Skip to content

Commit 4818e44

Browse files
authored
Merge pull request #140 from PhysShell/claude/multi-stack-architecture-yte8l6
docs: multi-stack frontend architecture (P-017/P-020), alpha-readiness gate, bilingual README
2 parents 876a5ab + 6d51b4a commit 4818e44

8 files changed

Lines changed: 2007 additions & 537 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ name: CI
22

33
# Least privilege: every job only reads the repo (no job pushes or needs write).
44
# Action SHA-pinning / persist-credentials hardening is deliberately deferred to
5-
# a Dependabot/hardening pass — see README "где оно жульничает" item #7.
5+
# a Dependabot/hardening pass — see README "Where it cheats" item #7.
66
permissions:
77
contents: read
88

‎README.md‎

Lines changed: 542 additions & 536 deletions
Large diffs are not rendered by default.

‎README.ru.md‎

Lines changed: 828 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/ROADMAP.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,46 @@ The long-term identity the backlog is aiming at:
3535
> typestate, effects, capabilities, and domain-specific types **without
3636
> rewriting the codebase.**
3737
38+
### Positioning against the competition (not another SAST)
39+
40+
The competition is already standing around this field with shovels and enterprise
41+
sales badges. CodeQL (semantic queries / code scanning), Sonar (quality / bugs /
42+
smells), Semgrep (rule-based AppSec), Snyk Code (SAST), and the AI PR reviewers all
43+
sell the **broad** promise: *"we'll find vulnerabilities / bugs / smells."* Entering
44+
that arena as *"another static analyzer / AI code reviewer / SAST"* is a fight lost
45+
to marketing budget, not to merit.
46+
47+
So Own.NET must **not** be pitched as any of those. The narrower, defensible niche:
48+
49+
> a **cross-language resource / lifetime / effect contract checker** — who holds
50+
> whom, who must release, which resource outlives which, which effect can
51+
> runaway, where a lifecycle contract is broken.
52+
53+
That is a different promise from *"an AI reviewer said this looks suspicious."* And
54+
it is deterministic where the AI reviewers are not — the grown-up framing is *an
55+
LLM may **propose** a suspicious lifecycle contract; Own **verifies** it
56+
deterministically* (reproducible rule, SARIF, suppression/spec, cross-language
57+
model). Not a head-on fight with AI review — a layer underneath it.
58+
59+
### From memory leaks to effect storms (one model, many skins)
60+
61+
The "big idea" that makes the niche coherent: four bugs that look unrelated are the
62+
**same lifecycle/resource-contract failure** in different ecosystems —
63+
64+
| Bug | The contract that broke |
65+
|-----|-------------------------|
66+
| WPF event leak | a long-lived publisher keeps a `ViewModel` alive |
67+
| DI captive dependency | a long-lived service retains a scoped service |
68+
| ArrayPool view-after-return | released backing storage still has a borrowed view |
69+
| **React effect storm** | an unstable dependency repeatedly re-triggers a network effect |
70+
71+
One model (source lifetime / resource / effect / cleanup / stability), one IR
72+
(OwnIR facts), one checker (the `ownlang/` core). The React row is the
73+
Cloudflare-shaped hook — used **honestly**: *"not all lifecycle bugs leak memory;
74+
some leak requests,"* never *"we'd have prevented the Cloudflare outage."* Its
75+
design is [P-020](proposals/P-020-ownts-react-effects.md) (the `Own.React` effect
76+
profile under the OwnTS frontend, [P-017](proposals/P-017-multi-stack-frontends.md)).
77+
3878
## Design philosophy (the load-bearing constraints)
3979

4080
- **One checker.** The Python core in `ownlang/` is the single source of truth.
@@ -91,6 +131,13 @@ ownership/lifetime/effects, (4) an MVP needs no PhD in Roslyn.
91131
| **P2** | async resource lifecycle; `ValueTask` affine usage; typestate/protocols | [P-008](proposals/P-008-effects-and-resources.md), [P-010](proposals/P-010-type-disciplines.md) |
92132
| **P3** | LOH fragmentation; static-collection memory bloat; cross-thread `ObjectDisposedException` | — (runtime-bound; see detectability matrix) |
93133

134+
> **Are we showable yet?** The concrete "delicious .NET alpha" gate — the A–G bar
135+
> (`dotnet tool` / Action / SARIF / 5 diagnostics / bad-ok examples / case studies /
136+
> suppression policy), the honest current status against it, and the 80/20 rule —
137+
> lives in [docs/notes/alpha-readiness.md](notes/alpha-readiness.md). Short version:
138+
> capability is past alpha; the gap to "people install it" is *packaging* (a single
139+
> `ownsharp check MyApp.sln` CLI, a wedge landing README, packaged case studies).
140+
94141
**The five concrete diagnostics to build first** (balanced across real pain,
95142
architectural strictness, and the borrow-checker showcase):
96143

@@ -172,6 +219,21 @@ architectural strictness, and the borrow-checker showcase):
172219
Nethermind, AiDotNet.Tensors).
173220
5. **Effects** — `pure` / `use !Db` / `use !Log` / `use Clock`, layer policies
174221
(P-008). The architectural X-ray — landed *after* the leak checkers prove value.
222+
6. **Platform-agnostic core (multi-stack)** — *horizon, on the record for
223+
consideration only.* The same OwnIR seam, reused for non-.NET stacks to prove the
224+
"one core, frontends only extract facts" spine was not .NET-shaped luck (P-017).
225+
Decision recorded: **JS/TS = one frontend family (`OwnTS`), two confidence tiers**
226+
(TS type-aware via the TypeScript Compiler API; JS best-effort via syntax/JSDoc) —
227+
*not* two products; **Java/Kotlin = split frontends** (`OwnJava` via Error Prone/
228+
JDT/Spoon, `OwnKotlin` via Detekt/KSP/K2) **unified by one `OwnJVM` profile** —
229+
because the JVM lifecycle/resource model is shared but the source tooling is not.
230+
The axis the naive layout conflates is **language frontend** (`OwnTS`/`OwnJava`/
231+
`OwnKotlin`) vs **platform profile** (`OwnReact`/`OwnJVM`/`OwnAndroid`/`OwnSpring`)
232+
vs **core** — a brand-per-framework layout "is not a product line, it is a census."
233+
Gated behind a tasty .NET alpha + a real cross-stack bug; the first slices are a
234+
`useEffect`-cleanup *marketing* spike and a listener-leak *research* spike, each
235+
`acquire` without `release` → the existing `OWN001`. See
236+
[P-017](proposals/P-017-multi-stack-frontends.md).
175237

176238
## What static analysis can and cannot catch (the reality matrix)
177239

@@ -248,3 +310,5 @@ own scan. Label them as estimates wherever they appear.
248310
| [P-014](proposals/P-014-semantic-resolution.md) | Project-local semantic resolution (`+=` event vs number) | P0 | in progress (Tier A default-on + Tier B light path `--ref-dir`; full MSBuild closure deferred) |
249311
| [P-015](proposals/P-015-configuration-surface.md) | Configuration surface (check selection & severity) | P2 | draft (stub) |
250312
| [P-016](proposals/P-016-deep-fact-extraction.md) | Deep C# fact extraction (CFG + flow lowering) | P1 | in progress (B0a/B0b/B2/A1 via `--flow-locals`) |
313+
| [P-017](proposals/P-017-multi-stack-frontends.md) | Multi-stack frontends (OwnTS / OwnJVM: OwnJava + OwnKotlin) | horizon | draft |
314+
| [P-020](proposals/P-020-ownts-react-effects.md) | OwnTS React effects profile (`Own.React`) — effect-storm angle | horizon | draft |

‎docs/notes/alpha-readiness.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# "Delicious .NET alpha" — the showable-to-people gate
2+
3+
Working note. The strategy is **not** "spread across stacks" — it is *"make one
4+
stack delicious, and architecturally prove the core isn't bolted to it."* Concretely:
5+
**80% of effort → .NET to "damn, it actually found a leak in my project,"** **20% →
6+
one tiny spike in another stack** to back the platform-agnostic story (P-017/P-020).
7+
A zoo of half-built frontends is cute until you have to deploy it.
8+
9+
This note answers one recurring question — **"are we ready to show people yet?"** —
10+
by pinning a concrete gate and the *honest* current status against it. It is an
11+
assessment, not a promise; status reflects a read of the repo on 2026-06-27.
12+
13+
## The wedge (what we sell, what we refuse to)
14+
15+
Do **not** pitch as: a static analyzer / AI code reviewer / SAST / borrow checker
16+
for C# / multi-language bug finder. That arena belongs to Sonar/CodeQL/Semgrep/Snyk
17+
and their sales teams; see
18+
[ROADMAP — Positioning against the competition](../ROADMAP.md#positioning-against-the-competition-not-another-sast).
19+
20+
Sell the narrow clin:
21+
22+
> **Own.NET finds .NET lifetime/resource bugs: event leaks, timer leaks, missing
23+
> `Dispose`, DI lifetime capture, and pooled-buffer misuse** — the class of bug that
24+
> sends people to dotMemory to argue with their monitor.
25+
26+
Slogans on record (for posts, README, talks):
27+
- *Find leaks before the profiler.*
28+
- *GC collects unreachable objects; Own finds objects that should have become unreachable.*
29+
- *`event +=` is acquire, `-=` is release.*
30+
- *Not all lifecycle bugs leak memory — some leak requests.* (the Cloudflare-style post — P-020)
31+
32+
## The gate (A–G) and where we actually stand
33+
34+
The bar for "showable": a person can reproduce the wow in ~3 minutes
35+
(`install → run → it found my real dirt`).
36+
37+
| | Item | Status (2026-06-27) | Gap to close |
38+
|---|------|--------------------|--------------|
39+
| **A** | `dotnet tool` one-command CLI | ◑ **partial** — the *extractor* is `PackAsTool` (`ownsharp-extract`, P-013); the core is Python. The delightful `ownsharp check MyApp.sln` single tool isn't packaged. | Wrap extractor+core into one `dotnet tool` (or a self-contained CLI) that takes a `.sln`/dir and prints findings. |
40+
| **B** | GitHub Action | ✅ **built** — `action.yml`: `path`/`severity`/`format` (`github` / `msbuild` / `human` / `sarif`), purple shield branding. Matches the "stupidly simple YAML" bar. | Publish to Marketplace; pin the 6-line usage in the README. |
41+
| **C** | SARIF / PR annotations | ✅ **built** — SARIF 2.1.0 + GitHub annotations + reachability/evidence (P-015). | — |
42+
| **D** | 5 core diagnostics | ✅ **built, well past** — OWN001/002/003, OWN014, DI001–005, POOL001–005, WPF001–005 (catalog). The comment's `SUB001/SUB002/TMR001/DISP001/DI001` all exist *semantically*; the `SUB/TMR/DISP` catalog rename is the deferred consolidation item, not new work. | (naming only) land the catalog rename with the OwnIR-v1/profile-label work. |
43+
| **E** | 10 bad/ok examples | ✅ **built** — 12 test-pinned gallery cases (`examples/gallery/`, incl. `00_ok_clean`) + extractor samples. | Add `.cs`-native (not `.own`) bad/ok pairs for the C# audience. |
44+
| **F** | 3 real-world case studies | ◑ **partial** — one honest mining write-up (`real-world-mining.md`: Dapper, CsvHelper, **ScreenToGif** flagship `VideoSource` + two `SystemEvents` leaks, all TPs, clean on disciplined libs) + a 20-case `corpus/real-world/`. Raw material for 3 studies exists; the *packaged* studies don't. | Write 3 `bad → fixed → what others miss → how Own reports it` studies from existing finds. |
45+
| **G** | suppression + false-positive policy | ◑ **partial** — `[OwnIgnore("reason")]` designed (P-004), project-wide config is P-015 (draft); precision behaviour is strong & documented ("no FP from `using`"). | One consolidated user-facing page: suppression mechanism + explicit FP policy. |
46+
47+
**Plus the front door (not in A–G but the real blocker):** `README.md` is now
48+
bilingual (English default + a `README.ru.md` variant), but still `# OwnLang — PoC` —
49+
deep, research-framed, no wedge landing. There is **no 20-second landing /
50+
copy-paste install / Action quickstart** at the top. Per the comment's own
51+
open-source-path list (README-in-20s → copy-paste → bad/ok → Action → SARIF →
52+
suppression → "why not Sonar/CodeQL"), this is the highest-leverage missing piece.
53+
54+
## Honest verdict
55+
56+
**The engine is past alpha on *capability* (D/E strong, B/C built). The gap to
57+
"showable" is *packaging and presentation*, not analysis power:**
58+
59+
1. a single `ownsharp check MyApp.sln` tool (**A**);
60+
2. a wedge landing README + copy-paste quickstart (front door);
61+
3. three packaged case studies from finds we already have (**F**);
62+
4. one consolidated suppression / false-positive page (**G**).
63+
64+
None of those is research; all are the difference between "interesting PoC" and
65+
"people install it." That ordering *is* the day 1–30 milestone.
66+
67+
## The 20% rule (other stacks)
68+
69+
Other stacks are **proof of portability, not a second product.** Sanctioned now:
70+
**at most one rule each**, as experiments — not an OwnTS 1.0.
71+
72+
```
73+
experiments/
74+
owents-react-effect-cleanup/ # P-020: useEffect listener/effect, the PR/marketing spike
75+
ownjava-listener-leak/ # P-017: addListener w/o removeListener → same OwnIR, the model proof
76+
```
77+
78+
README framing, and no more: *"Experimental: the same OwnIR model can represent
79+
React effect cleanup and Java listener lifetimes."* Design lives in
80+
[P-017](../proposals/P-017-multi-stack-frontends.md) /
81+
[P-020](../proposals/P-020-ownts-react-effects.md); both stay `horizon`/`draft`
82+
until the .NET alpha above is delicious. Do not let the spike exceed 20%.
83+
84+
## 90-day shape (sequencing, not a schedule)
85+
86+
- **Days 1–30 — make the .NET alpha tasty:** close A, the README front door, F, G
87+
(B/C/D/E already done). Suppression UX + bad/ok corpus polish.
88+
- **Days 31–60 — real-world proof:** run over 20–50 OSS .NET/WPF/Avalonia/WinForms
89+
repos; table of findings / confirmed / FP / unsupported; 2 case studies; compare
90+
with CodeQL / NetAnalyzers / Infer# where possible (the oracle, `docs/notes/oracle.md`).
91+
- **Days 61–90 — public launch:** landing README, "WPF zombie ViewModels" post,
92+
HN/Reddit/dev.to/.NET community, Action on Marketplace, `good first spec` issues,
93+
feedback from WPF/Avalonia/WinForms maintainers. The React/Java spike runs in
94+
parallel — capped at 20%.
95+
96+
The standing priority is unchanged: **prove value, don't reshape form**
97+
([consolidation-and-positioning.md](consolidation-and-positioning.md)). This note is
98+
the concrete "what value, packaged how" gate for that.

0 commit comments

Comments
 (0)