Skip to content

Commit f5efe0a

Browse files
committed
docs(P-017): record multi-stack frontend architecture (OwnTS / OwnJVM)
Capture the decided shape for taking the one-core/OwnIR-seam architecture beyond .NET, so the decision is on the record rather than evaporating. - JS/TS: one frontend family (OwnTS), two confidence tiers — TS type-aware via the TypeScript Compiler API, JS best-effort via syntax/JSDoc — not two products. Same OWN001 bug model; only type info (→ severity) differs. - Java/Kotlin: split frontends (OwnJava via Error Prone/JDT/Spoon, OwnKotlin via Detekt/KSP/K2) unified by one shared OwnJVM profile. Shared JVM lifecycle model, different source tooling. - Separates the conflated axes: language frontend vs platform profile (OwnReact/OwnJVM/OwnAndroid/OwnSpring) vs core, refusing brand-per-framework. - Reuses the P-001 seam verbatim: *.ts/*.java/*.kt -> extractor -> facts.ownir.json -> existing core -> OWN0xx. No second checker, bug-driven, gated behind a tasty .NET alpha + a real cross-stack bug. Wires P-017 into the proposals index and the ROADMAP backlog (milestone 6, horizon). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QnGqHwVb2H1jZ71f498MFa
1 parent 3867c4b commit f5efe0a

3 files changed

Lines changed: 318 additions & 0 deletions

File tree

‎docs/ROADMAP.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -172,6 +172,21 @@ architectural strictness, and the borrow-checker showcase):
172172
Nethermind, AiDotNet.Tensors).
173173
5. **Effects** — `pure` / `use !Db` / `use !Log` / `use Clock`, layer policies
174174
(P-008). The architectural X-ray — landed *after* the leak checkers prove value.
175+
6. **Platform-agnostic core (multi-stack)** — *horizon, on the record for
176+
consideration only.* The same OwnIR seam, reused for non-.NET stacks to prove the
177+
"one core, frontends only extract facts" spine was not .NET-shaped luck (P-017).
178+
Decision recorded: **JS/TS = one frontend family (`OwnTS`), two confidence tiers**
179+
(TS type-aware via the TypeScript Compiler API; JS best-effort via syntax/JSDoc) —
180+
*not* two products; **Java/Kotlin = split frontends** (`OwnJava` via Error Prone/
181+
JDT/Spoon, `OwnKotlin` via Detekt/KSP/K2) **unified by one `OwnJVM` profile** —
182+
because the JVM lifecycle/resource model is shared but the source tooling is not.
183+
The axis the naive layout conflates is **language frontend** (`OwnTS`/`OwnJava`/
184+
`OwnKotlin`) vs **platform profile** (`OwnReact`/`OwnJVM`/`OwnAndroid`/`OwnSpring`)
185+
vs **core** — a brand-per-framework layout "is not a product line, it is a census."
186+
Gated behind a tasty .NET alpha + a real cross-stack bug; the first slices are a
187+
`useEffect`-cleanup *marketing* spike and a listener-leak *research* spike, each
188+
`acquire` without `release` → the existing `OWN001`. See
189+
[P-017](proposals/P-017-multi-stack-frontends.md).
175190

176191
## What static analysis can and cannot catch (the reality matrix)
177192

@@ -248,3 +263,4 @@ own scan. Label them as estimates wherever they appear.
248263
| [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) |
249264
| [P-015](proposals/P-015-configuration-surface.md) | Configuration surface (check selection & severity) | P2 | draft (stub) |
250265
| [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`) |
266+
| [P-017](proposals/P-017-multi-stack-frontends.md) | Multi-stack frontends (OwnTS / OwnJVM: OwnJava + OwnKotlin) | horizon | draft |
Lines changed: 301 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,301 @@
1+
# P-017 — Multi-stack frontends (OwnTS / OwnJVM: OwnJava + OwnKotlin)
2+
3+
- **Status:** draft — forward-looking; **no code commitment.** Records the
4+
decided *shape* for taking the one-core/OwnIR-seam architecture beyond .NET, so
5+
the decision does not evaporate. Nothing here ships before the .NET surface is a
6+
"tasty alpha" and a real cross-stack bug pulls it off the shelf.
7+
- **Depends on:** `spec/OwnCore.md`, `spec/Lifetimes.md` (the fact vocabulary the
8+
core checks), [P-001](P-001-csharp-extractor.md) (the proven Roslyn → OwnIR →
9+
core seam this generalises), [P-014](P-014-semantic-resolution.md) (type-aware
10+
binding — the lever that separates the two TS confidence tiers).
11+
12+
## Motivation
13+
14+
The core (`ownlang/`) is already language-neutral by construction: it checks
15+
**OwnIR facts** (`acquire` / `borrow` / `release` / `use` / `escapes` / `owner`),
16+
not C#. [P-001](P-001-csharp-extractor.md) proved the seam end-to-end —
17+
`*.cs → Roslyn extractor → facts.ownir.json → Python core → OWN001/OWN014`. The C#
18+
frontend never re-implements the checker; it only extracts facts.
19+
20+
If that is real, then the *same* core should find the *same* bug shapes in other
21+
ecosystems, because the load-bearing bugs are not C#-specific:
22+
23+
```
24+
useEffect(() => { window.addEventListener("resize", onResize); }, []);
25+
// no return () => window.removeEventListener("resize", onResize) → OWN001
26+
27+
const sub = observable.subscribe(handle); // no sub.unsubscribe() → OWN001
28+
const id = setInterval(tick, 1000); // no clearInterval(id) → OWN001
29+
30+
publisher.addListener(this::onChanged); // Java: no removeListener → OWN001
31+
InputStream s = new FileInputStream(path); // Java: no close() → OWN001
32+
val job = scope.launch { ... } // Kotlin: no job.cancel() → OWN001
33+
```
34+
35+
Each of these is the same `acquire` with no `release` on some path — exactly
36+
`OWN001`, plus a `[resource: …]` kind tag. The bet of this proposal is that the
37+
**second and third frontends cost a fact extractor, not a second checker** — and
38+
proving that is the strongest possible evidence that "one core, OwnIR is the seam"
39+
was the right spine, not just .NET-shaped luck.
40+
41+
This is the platform-agnostic-core claim made falsifiable. We resist the
42+
soul-eating version of it just as hard as everywhere else (see Non-goals).
43+
44+
## The decision in two sentences
45+
46+
> **JS/TS:** one frontend *family*, not two products. The bug model is identical
47+
> across `.js/.jsx/.ts/.tsx`; only the available **type information** differs, so
48+
> the same extractor runs in two confidence tiers.
49+
>
50+
> **Java/Kotlin:** *split the frontends* (the source-level tooling and language
51+
> are genuinely different), but *unify the rules* under one shared **OwnJVM**
52+
> profile (the JVM lifecycle/resource model is shared).
53+
54+
The failure mode this refuses is breeding a brand per language × framework
55+
(`OwnJS`, `OwnTS`, `OwnJava`, `OwnKotlin`, `OwnAndroid`, `OwnSpring`, `OwnReact`,
56+
`OwnVue`, …) — "that is not a product line, it is a census." The fix is to
57+
separate two axes that the naive layout conflates:
58+
59+
- **Language frontend** (what parses source & emits OwnIR): `OwnTS`, `OwnJava`, `OwnKotlin`.
60+
- **Platform profile** (what supplies the lifetime/resource facts a domain needs):
61+
`OwnJVM`, `OwnAndroid`, `OwnReact`, `OwnSpring`.
62+
- **Core** (what checks OwnIR): the existing `ownlang/` engine + OwnIR.
63+
64+
A profile is data fed *to* the core (lifetime regions, acquire/release pairs for a
65+
domain), exactly as WPF already is for .NET — "WPF is the first configured
66+
profile, not the identity." Profiles cross language frontends freely: `OwnReact`
67+
is consumed by `OwnTS`; `OwnJVM` by both `OwnJava` and `OwnKotlin`.
68+
69+
## The matrix
70+
71+
| Stack | Product surface | Extractor / tooling | Shared profile |
72+
|-------|-----------------|---------------------|----------------|
73+
| C# | **Own.NET** | Roslyn analyzer/extractor (built, P-001) | .NET resources / lifetimes (WPF, DI, pool) |
74+
| JS/TS | **OwnTS** | ESLint plugin + TypeScript Compiler API | Web / React effects |
75+
| Java | **OwnJava** | Error Prone / JDT / Spoon | **OwnJVM** |
76+
| Kotlin| **OwnKotlin** | Detekt / KSP / K2 (later) | **OwnJVM** + Android |
77+
78+
Three planes, named once each:
79+
80+
```
81+
Language frontend: OwnTS OwnJava OwnKotlin (+ OwnSharp/Roslyn, built)
82+
Platform profile: OwnReact OwnJVM OwnAndroid OwnSpring
83+
Core: ownlang/ + OwnIR (one checker, one fact vocabulary)
84+
```
85+
86+
> Naming note. The originating design comment also floated `Owen`/`OwenTS` and an
87+
> `OWENTS00x` rule prefix. This proposal standardises on the existing **Own** brand
88+
> (`OwnLang`/`OwnIR`/`OwnSharp` → `OwnTS`, rule prefix `OWNTS00x`) for consistency;
89+
> the `Owen*` spelling is the same thing under a different skin.
90+
91+
---
92+
93+
## JS/TS — one frontend, two confidence tiers (OwnTS)
94+
95+
JS and TS share too much at the ecosystem level to be two products: React, Vue,
96+
Angular, RxJS, DOM listeners, timers, `AbortController`, `Promise`/`fetch`,
97+
`EventEmitter` — and the resource/lifetime bugs are *identical* across
98+
`.js/.jsx/.ts/.tsx`. Splitting them would be the artificial multiplication of
99+
entities the project exists to refuse.
100+
101+
What genuinely differs is **type information**, and that maps cleanly onto the
102+
project's existing precision discipline (`OWN050` when a type can't be resolved;
103+
"honestly skip beats confidently lie"):
104+
105+
- **TypeScript mode** (`.ts/.tsx`, or `.js` with `checkJs`/JSDoc): type-aware via
106+
the **TypeScript Compiler API** / `typescript-eslint` `parserServices`. We can
107+
tell an `Observable` from a look-alike `.subscribe`, resolve imports, type the
108+
source/handler/subscription, and build precise OwnIR. → **high-confidence
109+
diagnostics (hard error).**
110+
- **JavaScript mode** (plain `.js/.jsx`): syntax + JSDoc + best-effort types.
111+
More heuristic, more *warnings* than hard errors unless JSDoc/`checkJs`/types lift
112+
the confidence. → **heuristic diagnostics.**
113+
114+
Same product, same OwnIR, same core — different `severity`/confidence tier on the
115+
emitted diagnostic, decided by how much the source told us. This is the same
116+
"definite vs maybe" split the core already makes (`spec/Diagnostics.md`), now keyed
117+
on frontend type-resolution depth.
118+
119+
### Distribution & rule set
120+
121+
Ship as an **ESLint plugin** (`eslint-plugin-own`) — the cheapest distribution
122+
surface in this ecosystem (`npm install`, drop into an existing config):
123+
124+
| Rule | Pattern | Core verdict |
125+
|------|---------|--------------|
126+
| `OWNTS001` | `useEffect` adds a listener with no cleanup `return` | `OWN001` |
127+
| `OWNTS002` | `setInterval` / `setTimeout` with no `clear*` | `OWN001` |
128+
| `OWNTS003` | `subscribe()` result never `unsubscribe`d | `OWN001` |
129+
| `OWNTS004` | `AbortController` created but never `abort()`ed | `OWN001` |
130+
| `OWNTS005` | unstable dependency re-triggers an external effect | (effect/region) |
131+
132+
```
133+
eslint-plugin-own ← authoring rules for JS/TS (the user-facing surface)
134+
owents-extract ← TypeScript Compiler API → OwnIR (the fact extractor)
135+
ownlang/ (core) ← OwnIR → diagnostics (unchanged)
136+
```
137+
138+
The `OWNTS001` React `useEffect`-cleanup case is the recommended **marketing
139+
spike**: a 10-line bug everyone recognises, a "request storm / Cloudflare-style"
140+
story that sells itself, and the easiest plugin to distribute. It is a spike, not
141+
a frontend — one rule, one tier, end-to-end, before any breadth.
142+
143+
---
144+
145+
## Java & Kotlin — split frontends, one OwnJVM profile
146+
147+
Java and Kotlin live on the JVM and share a lifecycle/resource model, but their
148+
**source-level tooling and language surface are different enough that one
149+
extractor would lie about one of them.** So: two extractors, one profile.
150+
151+
### Shared model → the OwnJVM profile
152+
153+
`OwnJVM` supplies the acquire/release pairs and lifetime regions common to the
154+
platform — fed to the core exactly like WPF's profile is for .NET:
155+
156+
```
157+
AutoCloseable / close() (≈ IDisposable / Dispose — the direct analog)
158+
listener add / remove
159+
RxJava Disposable
160+
ExecutorService.shutdown()
161+
ThreadLocal.remove()
162+
Spring DI lifetimes → OwnSpring
163+
Android Activity/Fragment/View → OwnAndroid
164+
coroutines / jobs / scopes (Kotlin)
165+
```
166+
167+
`AutoCloseable ≈ IDisposable` and "listener leak ≈ event leak" are why the
168+
Java/Kotlin spike is the *strongest* platform-agnostic-core proof: it is closest to
169+
the subscription/lifetime/resource model the core already speaks.
170+
171+
### OwnJava frontend
172+
173+
Java facts come from the type-aware JVM toolchain. Candidate hooks (pick one for
174+
the spike, don't build all): **javac plugin / annotation processor**, **Error
175+
Prone plugin**, or a **JDT / Spoon** extractor.
176+
177+
```java
178+
publisher.addListener(this::onChanged); // no removeListener → OWN001
179+
InputStream s = new FileInputStream(path); // no close() → OWN001
180+
```
181+
182+
Annotations are the natural escape-hatch / contract surface (mirrors the `.NET`
183+
`[OwnIgnore]` and the core's `consume`/`borrow` contracts):
184+
`@OwnResource`, `@Consumes`, `@Borrowed`, `@NoEscape`, `@Lifetime("Application")`.
185+
186+
### OwnKotlin frontend
187+
188+
Kotlin only *looks* like Java until you open real code: extension functions,
189+
properties over get/set, lambda syntax, scope functions (`use`/`also`/`apply`/
190+
`let`/`run`), `suspend`/coroutines, `Flow.collect`, `lifecycleScope`/
191+
`viewModelScope`, delegates, nullable/`inline`/`value` classes. It needs **its own
192+
hooks**, not a Java extractor in a wig:
193+
194+
```kotlin
195+
publisher.addListener { onChanged() } // no removeListener → OWN001
196+
val job = scope.launch { ... } // no job.cancel() → OWN001
197+
viewLifecycleOwner.lifecycleScope.launch { // Android lifetime case
198+
flow.collect { render(it) }
199+
}
200+
```
201+
202+
Tooling, easiest → deepest (and the order to attempt them):
203+
204+
- **Detekt rule** — simplest, lint-style; the right first slice.
205+
- **KSP** — good for reading annotations and generating metadata/specs; weaker at
206+
method-body control-flow ("forgot the cleanup *here*").
207+
- **Kotlin compiler plugin / K2** — deepest analysis; most power, most pain — *do
208+
not lead with this if you would like to keep your sanity.*
209+
- **IntelliJ PSI** — for IDE/plugin-style analysis later.
210+
211+
Use Detekt for lint rules first; reach for KSP when specs/annotations matter; defer
212+
the compiler plugin.
213+
214+
---
215+
216+
## Scope (what a first increment actually is)
217+
218+
Bug-driven, smallest-first, mirroring how P-001 landed (one pattern end-to-end
219+
before breadth):
220+
221+
1. **OwnTS spike** — `OWNTS001` (`useEffect` listener without cleanup) only, TS
222+
mode, `*.tsx → owents-extract → facts.ownir.json → core → OWN001` at the JSX
223+
line. Framed as a marketing/PR spike.
224+
2. **OwnJVM research spike** — one listener leak (`addListener` without
225+
`removeListener`) through **either** OwnJava **or** OwnKotlin → **the same
226+
`facts.ownir.json` shape** → the **unmodified** core → `OWN001`. The deliverable
227+
is the proof that the core is reused verbatim, not a frontend.
228+
229+
Everything is **OwnIR facts in the spec's vocabulary** — no new core code is in
230+
scope for either spike; if a spike needs a core change, that is a finding, not a
231+
silent edit.
232+
233+
## Non-goals (the most important section)
234+
235+
- **No second checker, in any language.** Every frontend produces/consumes OwnIR;
236+
the Python core stays the single source of truth. A JS/Java/Kotlin re-impl of the
237+
analysis is the exact drift this project exists to refuse.
238+
- **No whole-language frontends.** Not a TypeScript type-checker, not a Java/Kotlin
239+
semantic engine. Extract *facts* (acquire/borrow/use/release/escape/control-flow),
240+
the same narrow-frontend discipline as the C# side (async/generics/LINQ-equivalents
241+
stay out until a real bug needs them).
242+
- **No brand-per-framework.** `OwnVue`/`OwnAngular`/`OwnRxJava`/… are *profiles*
243+
under an existing frontend if they ever exist, never products.
244+
- **No new stack before .NET is a tasty alpha** and a real cross-stack bug is in
245+
hand. "We supported 40% of three more languages and found zero bugs" is the
246+
precise failure we are avoiding.
247+
- **Honest-skip over confident-lie** carries over: JS mode emits warnings, not hard
248+
errors, when types aren't there; an unsupported Kotlin coroutine shape is skipped
249+
and flagged, not guessed.
250+
251+
## Sketch / architecture (the seam, reused)
252+
253+
Every stack is the P-001 seam with a different front half:
254+
255+
```
256+
*.ts/.tsx --[owents-extract: TS Compiler API]--> facts.ownir.json --\
257+
*.java --[OwnJava: ErrorProne/JDT/Spoon ]--> facts.ownir.json ---+--> [ownlang core] --> OWN0xx
258+
*.kt --[OwnKotlin: Detekt/KSP/K2 ]--> facts.ownir.json --/ (+ [resource:] / [profile:])
259+
```
260+
261+
The OwnIR JSON is the contract (`OWNIR_VERSION`, currently `0`; a mismatched
262+
extractor/core pair fails loudly at load — same guarantee P-001 relies on). A new
263+
frontend that wants a resource kind the schema doesn't model yet rides the next
264+
OwnIR-schema bump (see the deferred `subscriptions → resources` rename in
265+
[consolidation-and-positioning.md](../notes/consolidation-and-positioning.md)),
266+
rather than minting a private format.
267+
268+
**Environment note** (same constraint as P-001's dotnet): this sandbox has no
269+
Node/JVM/Kotlin toolchain locally either. So the testable-now half of any spike is
270+
the **Python fact-ingest against hand-written `facts.ownir.json` fixtures**; the
271+
actual extractor (ESLint/javac/Detekt artifact) is CI-validated, exactly like the
272+
Roslyn extractor and the `dotnet-golden` job. Land one pattern's fixtures first.
273+
274+
## Strategy (sequencing, not a schedule)
275+
276+
1. **.NET → tasty alpha.** Prove value on real OSS C# repos first (the standing
277+
"prove value, don't reshape form" priority from the positioning note). No second
278+
stack competes with this.
279+
2. **OwnTS = marketing spike.** Small PR: React `useEffect` cleanup (`OWNTS001`).
280+
Big recognisable audience, cheap distribution.
281+
3. **OwnJava/OwnKotlin = research spike.** Listener leak → the *same* OwnIR → the
282+
*same* core. The point is the platform-agnostic-core proof, not Java coverage.
283+
284+
## Open questions
285+
286+
1. **Which JS/TS confidence tiers are hard error vs warning by default**, and how
287+
`checkJs`/JSDoc promotes a `.js` file from heuristic to high-confidence — the
288+
exact mapping onto the existing definite/maybe split (`spec/Diagnostics.md`).
289+
2. **OwnJava first hook:** Error Prone (easiest CI story) vs JDT/Spoon (richer
290+
standalone extraction) for the listener-leak spike.
291+
3. **OwnKotlin first hook:** Detekt (simplest) almost certainly for the spike —
292+
confirm KSP isn't needed even for v0, and keep K2/compiler-plugin explicitly off
293+
the first slice.
294+
4. **`[profile: …]` label.** This proposal assumes the deferred profile-label work
295+
(consolidation backlog item) lands so `OwnReact`/`OwnJVM`/`OwnAndroid` findings
296+
are attributable — is that a prerequisite for OwnTS, or can the spike ship with
297+
just `[resource: …]` as the .NET side does today?
298+
5. **OwnIR coverage gaps.** Does any TS/JVM resource shape (e.g. `AbortController`,
299+
coroutine `Job`, `Flow.collect` cancellation) need a fact the current schema
300+
can't express? Each such gap is a concrete OwnIR-v1 input, not a blocker to note
301+
and route through the schema bump.

‎docs/proposals/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ proposal is marked `done` with a pointer.
3838
| [P-014](P-014-semantic-resolution.md) | Project-local semantic resolution (kills `+=` false positives) | in progress (Tier A default-on + Tier B light path `--ref-dir`; full MSBuild closure deferred) |
3939
| [P-015](P-015-configuration-surface.md) | Configuration surface (check selection & per-category severity) | draft (stub) |
4040
| [P-016](P-016-deep-fact-extraction.md) | Deep C# fact extraction (CFG + flow lowering; loops) | in progress (B0a/B0b/B2/A1 via `--flow-locals`) |
41+
| [P-017](P-017-multi-stack-frontends.md) | Multi-stack frontends (OwnTS / OwnJVM: OwnJava + OwnKotlin) | draft |
4142

4243
> For priorities, milestones, the framing, and the design philosophy across all
4344
> of these, see the strategy hub: [`docs/ROADMAP.md`](../ROADMAP.md). P-004 … P-016

0 commit comments

Comments
 (0)