|
| 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. |
0 commit comments