|
| 1 | +# OwnTS — React `useEffect` frontend spike (`Own.React`) |
| 2 | + |
| 3 | +The TypeScript sibling of the [Roslyn C# extractor](../roslyn/). It scans a |
| 4 | +React `.tsx`, emits **OwnIR** facts, and lets the **existing** Python core |
| 5 | +(`python -m ownlang ownir`) flag the leak. Same seam, same checker, different |
| 6 | +skin — a `useEffect` acquire without a cleanup `return` is the core's `OWN001`, |
| 7 | +exactly as a C# `event +=` without `-=` is. |
| 8 | + |
| 9 | +> The same OwnIR idea behind WPF subscription leaks can model React effect storms. |
| 10 | +
|
| 11 | +This is a **spike**, per [P-020](../../docs/proposals/P-020-ownts-react-effects.md) |
| 12 | +— deliberately *not* a TypeScript analyzer. Extraction is heuristic (brace |
| 13 | +matching + cleanup-verb detection), not a real TS parse. Its only job is to prove |
| 14 | +the seam is cross-language. |
| 15 | + |
| 16 | +## Run it |
| 17 | + |
| 18 | +```bash |
| 19 | +# print the OwnIR facts extracted from a .tsx |
| 20 | +python frontend/ownts/ownts.py frontend/ownts/examples/Dashboard.tsx |
| 21 | + |
| 22 | +# extract + run straight through the core (the "catch") |
| 23 | +python frontend/ownts/ownts.py frontend/ownts/examples/Dashboard.tsx --check |
| 24 | + |
| 25 | +# the EFF001 stability showcase (propagation + the conservative silent cases) |
| 26 | +python frontend/ownts/ownts.py frontend/ownts/examples/EffectStorm.tsx --check |
| 27 | + |
| 28 | +# or the real two-step CLI, same as the C# side: |
| 29 | +python frontend/ownts/ownts.py frontend/ownts/examples/Dashboard.tsx -o facts.json |
| 30 | +python -m ownlang ownir facts.json --format sarif |
| 31 | + |
| 32 | +# pin the spike |
| 33 | +python frontend/ownts/test_ownts.py |
| 34 | +``` |
| 35 | + |
| 36 | +`Dashboard.tsx` drops three `OWN001` leaks **and** one `EFF001` effect storm; |
| 37 | +`DashboardClean.tsx` (every acquire has a cleanup `return`, and the unstable dep is |
| 38 | +`useMemo`'d) is silent. |
| 39 | + |
| 40 | +```text |
| 41 | +Dashboard.tsx:13: error: [OWN001] timer 'setInterval(() =>' ... never stopped ... (leak) [resource: timer] |
| 42 | +Dashboard.tsx:21: error: [OWN001] the result of '.subscribe(...)' is ignored ... (leak) [resource: subscription token] |
| 43 | +Dashboard.tsx:27: error: [OWN001] event '.addEventListener(...)' ... never unsubscribed ... (leak) [resource: subscription token] |
| 44 | +Dashboard.tsx:34: error: [EFF001] effect re-runs on every render: dependency 'filters' is an object literal ... can become a request storm ... [resource: react effect] |
| 45 | +``` |
| 46 | + |
| 47 | +## What it catches — the honest `Own.React` slice |
| 48 | + |
| 49 | +| EFF | Pattern | OwnIR fact | Core verdict | |
| 50 | +|-----|---------|-----------|--------------| |
| 51 | +| `EFF004` | `setInterval`/`setTimeout` in an effect, no `clearInterval`/`clearTimeout` cleanup | `resource: timer` | `OWN001` | |
| 52 | +| `EFF003` | `X.subscribe(...)` with no `unsubscribe` cleanup | `resource: subscribe` | `OWN001` | |
| 53 | +| `EFF003` | `addEventListener` with no `removeEventListener` cleanup | `resource: subscription` | `OWN001` | |
| 54 | +| `EFF001` | IO effect with a render-unstable dependency identity | `effects` block | `EFF001` (new core analysis — see below) | |
| 55 | + |
| 56 | +These three **are** the existing acquire→release model, just emitted by an OwnTS |
| 57 | +frontend. The core is untouched. |
| 58 | + |
| 59 | +## EFF001 — a real core analysis (not a heuristic, not OWN001) |
| 60 | + |
| 61 | +`EFF001` — the unstable-dependency "effect storm" (the Cloudflare 12-Sep-2025 |
| 62 | +shape: a `useEffect` whose dep object is re-created each render, re-firing the |
| 63 | +effect and storming the API) — **is not an acquire/release leak.** It is a new core |
| 64 | +analysis: **dependency-identity stability** (`ownlang/effects.py`), its own core |
| 65 | +code like `DI001`, *never* an `OWN001`. |
| 66 | + |
| 67 | +The honest split is preserved end-to-end. The frontend emits only **facts** — for |
| 68 | +each `useEffect`, its dep list, whether the body does IO, and a render-scope |
| 69 | +**binding table** (what each binding syntactically is: `object`/`array`/`new`, |
| 70 | +`memo`/`callback`/`ref`, `ident` derivation + the names it references, `call`, …). |
| 71 | +It does **not** pre-judge stability. The **core** runs an identity-stability lattice |
| 72 | +(`STABLE < UNKNOWN < UNSTABLE`) to a fixpoint over the references and decides: |
| 73 | + |
| 74 | +```text |
| 75 | +EFF001 fires ⟺ the effect does IO ∧ some dep is *provably* UNSTABLE |
| 76 | +``` |
| 77 | + |
| 78 | +- object/array literal in render scope → UNSTABLE (fresh identity every render) |
| 79 | +- `useMemo`/`useCallback`/`useRef`, prop, primitive → STABLE |
| 80 | +- an alias/derivation → the worst of what it references (instability *propagates*) |
| 81 | +- an opaque `call(...)` → UNKNOWN → **no finding** (conservative; low false positives) |
| 82 | + |
| 83 | +See `examples/EffectStorm.tsx`: two storms fire (a direct object dep and the alias |
| 84 | +that derives from it — `derives from 'filters' ... (via alias -> filters)`), while |
| 85 | +the memoised, ref, opaque-call, primitive, and no-IO effects all stay silent. |
| 86 | + |
| 87 | +The one-liner the spike pays for: **"Not all lifecycle bugs leak memory. Some |
| 88 | +leak requests."** We make **no** "Own would have prevented the Cloudflare outage" |
| 89 | +claim — see P-020's Non-goals. |
0 commit comments