mindweave 0.0.1 → 2.1.2

package/dist/alternator/chassis/isolation.js

@@ -0,0 +1,336 @@
+/**
+ * isolation.ts — run oversized tree-sitter grammars where they cannot kill us.
+ *
+ * The OCaml grammar's parser tables are large enough that compiling its WASM can
+ * fail V8's internal zone allocation — `Fatal process out of memory: Zone` — and
+ * that failure is not an exception: it takes the whole process down. The suite
+ * previously CONTAINED this with heap headroom (--max-old-space-size) and test
+ * sequencing, which protects the test runner and does nothing for a user whose
+ * repository simply contains .ml files. objc's grammar is half again bigger, so
+ * the same fuse is lit under a language nobody has tripped yet.
+ *
+ * The cure is isolation, not headroom: grammars past a size threshold are loaded and
+ * parsed inside a separate CHILD PROCESS. When one dies, the extraction call resolves
+ * to null, which is already the contract every caller handles (tree-sitter is the
+ * fallback tier; null means "defer to grep/read"). A crash that used to be fatal
+ * becomes a degraded answer.
+ *
+ * ── WHY A PROCESS, NOT A WORKER THREAD ──────────────────────────────────────────
+ *
+ * This was a worker_thread with `resourceLimits`, on the reasoning that V8 terminates
+ * a worker which exceeds them and leaves the host untouched. That reasoning is right
+ * for the wrong failure. MEASURED, in the compiled build, with no teardown requested:
+ * parsing two lines of OCaml returned a CORRECT result and then killed the host with
+ * exit code 3.
+ *
+ * The distinction that matters is which allocator runs out:
+ *   - a JS HEAP overrun is thread-local; V8 kills the worker cleanly
+ *     (`ERR_WORKER_OUT_OF_MEMORY`) and the host carries on. This is what the old
+ *     "reproduction" test exercised by shrinking the heap to 8 MB, which is why the
+ *     containment looked like it worked.
+ *   - a ZONE overrun — the arena V8 uses while compiling — calls
+ *     `FatalProcessOutOfMemory`, which ABORTS THE PROCESS. It is not thread-local and
+ *     `resourceLimits` do not govern it, because a Zone is neither the heap nor the
+ *     code range.
+ *
+ * The OCaml grammar hits the second one. A thread shares the process with its host, so
+ * no thread-level mechanism can contain a process-level abort; a separate process is
+ * the only boundary V8's fatal handler cannot cross. Verified by construction: the
+ * child aborting is now an ordinary non-zero exit that this module observes.
+ *
+ * Mechanics worth knowing:
+ *   - The child imports treesitter.ts itself and calls the SAME entry points; an env
+ *     flag stops it recursing into isolation. No extraction logic is duplicated.
+ *   - One child serves all heavy grammars, spawned on first need, respawned after a
+ *     crash a bounded number of times. A grammar in flight when the child dies is
+ *     POISONED: further requests for it return null immediately rather than
+ *     re-crashing a fresh child on the same input forever.
+ *   - Requests carry a deadline. A wedged child (stuck, not crashed) is killed and
+ *     treated exactly like a crash. The host never waits on it unboundedly.
+ *   - The child's stdio is discarded. When it dies it prints a V8 crash dump, and that
+ *     is our normal degraded path — not something to spray across the user's terminal.
+ *
+ * Everything configurable reads the environment at spawn/call time, so tests can shrink
+ * the limits to reproduce the original crash condition and prove the host survives it.
+ */
+import { fork } from "node:child_process";
+import { fileURLToPath } from "node:url";
+/** Set in the child by the host at spawn. It is what stops the entry points the child
+ *  calls from routing straight back out into isolation. */
+export const IN_WORKER = process.env.MINDWEAVE_TS_IN_WORKER === "1";
+/** Child heap ceiling. Generous for one grammar + one file; small enough that a
+ *  pathological compile dies over there instead of paging the machine. Secondary to
+ *  the process boundary itself, which is what actually contains a Zone abort. */
+function workerHeapMb() {
+    return envInt("MINDWEAVE_TS_WORKER_HEAP_MB", 768);
+}
+/**
+ * Retire the worker once its RSS passes this, and start a fresh one on the next call.
+ *
+ * This is the containment that matters in practice, and it exists because of a
+ * measurement, not a theory: `parse()` followed by `tree.delete()` retains memory that
+ * never comes back. On a 54 KB JSX-heavy file that is ~57-70 MB PER PARSE, and it is
+ * WASM linear memory, which by specification can grow and never shrink. Indexing 120
+ * ordinary source files (960 KB in total) peaked at 1.9 GB.
+ *
+ * There is no version of this we can fix upstream today: the current runtime is pinned
+ * to `web-tree-sitter` 0.20.x to match `tree-sitter-wasms`' grammar ABI, and the newest
+ * runtime refuses those grammars outright (verified by loading one into it).
+ *
+ * So memory is bounded the one way that does not depend on understanding the leak: the
+ * child is watched and replaced. RSS is read in the CHILD and reported with every reply
+ * — the host cannot see a child's memory, and a proxy like "bytes parsed" does not
+ * track it (a clean 1.4 MB file costs 107 MB; a 54 KB JSX one costs more).
+ *
+ * The cost of a retirement is re-forking and recompiling the grammar wasm on the next
+ * call, so this wants to be high enough not to thrash and low enough to stay far from
+ * any commit limit.
+ */
+function workerRssMb() {
+    return envInt("MINDWEAVE_TS_WORKER_RSS_MB", 800);
+}
+/** Per-request deadline. Parsing one file is fast; anything past this is wedged. */
+function requestTimeoutMs() {
+    return envInt("MINDWEAVE_TS_WORKER_TIMEOUT_MS", 15_000);
+}
+/** How many times a dead worker is replaced before extraction goes dark for the
+ *  session. Two respawns tolerates a transient; a third death is a pattern. Reads the
+ *  environment like every other limit here, so a test can shrink it far enough to
+ *  actually reach exhaustion instead of asserting around it. */
+function maxRespawns() {
+    return envInt("MINDWEAVE_TS_MAX_RESPAWNS", 2);
+}
+/** With nothing in flight, the worker shuts itself down after this quiet period
+ *  and respawns on demand. Two reasons: it returns the grammar's sizeable WASM
+ *  heap when a burst of .ml work ends, and it guarantees the worker can never
+ *  hold the host process open at exit — `unref()` is not sufficient under every
+ *  loader (the tsx bootstrap holds a ref the parent cannot shed).
+ *
+ *  30 seconds, not 3: a respawn re-pays worker startup AND recompiling the
+ *  grammar wasm, so a short window turns interleaved heavy/light work (the test
+ *  suite is exactly this shape) into respawn thrash. Half a minute keeps bursts
+ *  warm; a session that touches .ml once still gets its memory back promptly. */
+function idleShutdownMs() {
+    return envInt("MINDWEAVE_TS_WORKER_IDLE_MS", 30_000);
+}
+let idleTimer = null;
+function armIdleShutdown() {
+    if (idleTimer)
+        clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => {
+        idleTimer = null;
+        if (worker && pending.size === 0)
+            retire(worker);
+    }, idleShutdownMs());
+    idleTimer.unref?.();
+}
+function envInt(name, fallback) {
+    const v = Number(process.env[name]);
+    return Number.isFinite(v) && v > 0 ? Math.floor(v) : fallback;
+}
+let worker = null;
+let nextId = 1;
+const pending = new Map();
+const poisoned = new Set();
+let respawns = 0;
+/** The worker that has crossed its memory budget, retired as soon as it goes idle.
+ *  Held as the CHILD, not a boolean, so a flag raised against one worker can never
+ *  retire its replacement. */
+let overBudget = null;
+/** Replies served by the CURRENT worker. A worker that has done real work and then
+ *  dies is a fresh incident, not a continuing crash loop — see `respawns`. */
+let served = 0;
+/** Replies after which the current worker counts as healthy and the crash history
+ *  clears. Low, because the failure this guards against (a fatal input crashing every
+ *  replacement) reproduces on the FIRST request every time. */
+const HEALTHY_REPLIES = 5;
+/** Visible for tests: how many workers this process has started, lost, and replaced
+ *  deliberately. `retirements` is the planned kind and must never count as a crash. */
+export const isolationStats = { spawns: 0, crashes: 0, retirements: 0 };
+/** Shut a worker down deliberately: strip its listeners FIRST so the exit it is about
+ *  to emit is not read as a crash (no respawn charged, no grammar poisoned). Shared by
+ *  the idle timer and the memory budget, which differ only in what prompts them. */
+function retire(w) {
+    if (worker === w)
+        worker = null;
+    if (overBudget === w)
+        overBudget = null;
+    served = 0;
+    w.removeAllListeners();
+    w.kill();
+}
+/**
+ * Which file the child runs, and how.
+ *
+ * `fork` inherits the parent's `execArgv` by default, and that one fact removes the
+ * whole bootstrap this needed as a thread. Under tsx (tests, dev from source) the
+ * parent already carries tsx's loader flags, so the child gets them too and resolves
+ * the `.ts` entry and every transitive `.js`→`.ts` import exactly as the parent does.
+ * Under the compiled build there are no extra flags and the child runs the `.js`
+ * directly. No `eval` shim, no loader registration, no divergence between the two.
+ */
+function workerEntry() {
+    const here = import.meta.url;
+    const file = here.endsWith(".ts") ? "./extractWorker.ts" : "./extractWorker.js";
+    return {
+        entry: fileURLToPath(new URL(file, here)),
+        // Bound the child's heap as a secondary guard. It is NOT what contains the Zone
+        // abort — the process boundary is — but it stops a pathological compile from
+        // eating the machine before it dies.
+        execArgv: [...process.execArgv, `--max-old-space-size=${workerHeapMb()}`],
+        env: { ...process.env, MINDWEAVE_TS_IN_WORKER: "1" },
+    };
+}
+function ensureWorker() {
+    if (worker)
+        return worker;
+    if (respawns > maxRespawns())
+        return null;
+    const { entry, execArgv, env } = workerEntry();
+    isolationStats.spawns++;
+    served = 0;
+    const w = fork(entry, [], {
+        execArgv,
+        env,
+        // Discard the child's output. A dying grammar prints a V8 crash dump, and that is
+        // this module's ordinary degraded path — the user should see a missing outline,
+        // not a stack trace they cannot act on. `ipc` is what `fork` talks over.
+        stdio: ["ignore", "ignore", "ignore", "ipc"],
+    });
+    w.unref(); // never keep the host process alive for us
+    w.channel?.unref(); // nor the IPC channel, which refs the loop independently
+    w.on("message", (msg) => {
+        const p = pending.get(msg.id);
+        if (!p)
+            return;
+        pending.delete(msg.id);
+        clearTimeout(p.timer);
+        p.resolve(msg.result ?? null);
+        // A worker that has answered a few times is working, whatever it does later. Without
+        // this, three unrelated crashes spread across a long session would exhaust the
+        // respawn budget and silently switch code intelligence off for good — which matters
+        // far more now that EVERY grammar depends on this worker, not just the exotic ones.
+        if (++served >= HEALTHY_REPLIES)
+            respawns = 0;
+        // The child measures itself; see workerRssMb for why this is read over there and
+        // why it is memory rather than a proxy for it.
+        if (typeof msg.rss === "number" && msg.rss > workerRssMb() * 1024 * 1024)
+            overBudget = w;
+        if (pending.size !== 0)
+            return;
+        // Retire only once nothing is in flight, so a request never dies for a reason that
+        // has nothing to do with it.
+        if (overBudget === w) {
+            isolationStats.retirements++;
+            if (idleTimer) {
+                clearTimeout(idleTimer);
+                idleTimer = null;
+            }
+            retire(w);
+            return;
+        }
+        armIdleShutdown();
+    });
+    const dead = () => {
+        if (worker === w)
+            worker = null;
+        if (overBudget === w)
+            overBudget = null;
+        served = 0;
+        isolationStats.crashes++;
+        respawns++;
+        // Whatever was in flight ON THIS CHILD is the likely culprit — poison it so the
+        // next spawn is not fed the same fatal input, and resolve those waiters with the
+        // null that "fallback tier unavailable" has always meant. Requests already running
+        // on a replacement child are untouched.
+        for (const [id, p] of pending) {
+            if (p.child !== w)
+                continue;
+            poisoned.add(p.grammarFile);
+            clearTimeout(p.timer);
+            p.resolve(null);
+            pending.delete(id);
+        }
+    };
+    w.on("error", dead);
+    w.on("exit", (code, signal) => {
+        // A Zone abort arrives here as an ordinary non-zero exit (or a signal), which is
+        // the entire point of the process boundary: the thing that used to kill us is now
+        // an event we handle.
+        if (code !== 0 || signal)
+            dead();
+        else if (worker === w)
+            worker = null;
+    });
+    worker = w;
+    return w;
+}
+/** Run one op in the isolation worker. Null on poison, crash, timeout, or when
+ *  respawns are exhausted — never a throw, never a host crash. */
+async function callWorker(grammarFile, op, payload) {
+    if (poisoned.has(grammarFile))
+        return null;
+    const w = ensureWorker();
+    if (!w)
+        return null;
+    const id = nextId++;
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            // Wedged, not crashed: kill it and let the exit handler do the rest — including
+            // resolving THIS promise via the pending sweep.
+            w.kill("SIGKILL");
+        }, requestTimeoutMs());
+        if (idleTimer) {
+            clearTimeout(idleTimer);
+            idleTimer = null;
+        }
+        pending.set(id, { resolve: resolve, grammarFile, timer, child: w });
+        w.send({ id, op, ...payload });
+    });
+}
+/** Extraction for a heavy grammar, isolated. Same contract as treeSitterExtract. */
+export function isolatedExtract(grammarFile, absPath, code) {
+    return callWorker(grammarFile, "extract", { absPath, code });
+}
+/**
+ * HTML/CSS extraction, isolated. Same contract as extractMarkup.
+ *
+ * The markup tier walks the parse tree directly rather than running a tag query, and a
+ * live tree cannot cross a process boundary — so the whole extraction runs in the
+ * child and only the finished defs/refs come back. Until now this tier had no guard of
+ * any kind, not even the grammar-size one, while parsing exactly the sort of large
+ * nested files that cost the most.
+ *
+ * Poison is keyed on the HTML grammar for both, since a stylesheet embedded in a page
+ * is parsed by the same worker and a crash cannot be attributed to one of the two.
+ */
+export function isolatedMarkup(absPath, code) {
+    return callWorker("tree-sitter-html.wasm", "markup", { absPath, code });
+}
+/** Span lookup for a heavy grammar, isolated. Same contract as treeSitterSpan. */
+export function isolatedSpan(grammarFile, absPath, code, name, nearLine) {
+    return callWorker(grammarFile, "span", { absPath, code, name, nearLine });
+}
+/** Test hook: forget crash history and poison so a fresh scenario starts clean. */
+export function resetIsolationForTests() {
+    if (idleTimer) {
+        clearTimeout(idleTimer);
+        idleTimer = null;
+    }
+    if (worker) {
+        worker.removeAllListeners();
+        worker.kill("SIGKILL");
+    }
+    worker = null;
+    overBudget = null;
+    served = 0;
+    respawns = 0;
+    poisoned.clear();
+    for (const [, p] of pending)
+        clearTimeout(p.timer);
+    pending.clear();
+    isolationStats.spawns = 0;
+    isolationStats.crashes = 0;
+    isolationStats.retirements = 0;
+}
+//# sourceMappingURL=isolation.js.map

package/dist/alternator/chassis/isolation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isolation.js","sourceRoot":"","sources":["../../../src/alternator/chassis/isolation.ts"],"names":[],"mappings":"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"}

package/dist/alternator/chassis/langCases.js

@@ -0,0 +1,69 @@
+/**
+ * langCases.ts — shared checker and case list for the broad-language tests.
+ *
+ * Loading every grammar wasm in one process exhausts V8's heap, and Node's test
+ * runner isolates each test FILE in its own process — so the language cases are
+ * split across several test files, each exercising `checkLang` on one PART.
+ * Keeping the assertion here means every part verifies identically.
+ *
+ * The parts are balanced by GRAMMAR BYTES, not by case count, because grammars
+ * differ in size by more than a hundredfold (lua 43KB, ocaml 5MB) and an even count
+ * of cases says nothing about the real cost. `PART_BUDGET_BYTES` keeps that from
+ * drifting: `langBudget.test.ts` weighs the real wasm files and fails when a part
+ * exceeds it, so adding a heavy grammar forces a deliberate re-split.
+ *
+ * WHAT THIS SPLIT DOES NOT FIX, since the wrong story was believed for a while:
+ * the suite's intermittent `Fatal process out of memory: Zone` crash is NOT caused
+ * by the balance between parts. It is the `ocaml` grammar, which is the largest and
+ * tips V8 over when the machine is already under memory pressure. Measured: the
+ * crash still happened with file concurrency forced to 1, and it FOLLOWED ocaml
+ * from one part to another when the cases were moved. The actual fix is the heap
+ * headroom (`--max-old-space-size`) and the sequential `test:lang` phase in
+ * package.json. Balancing the parts is still worth keeping, but do not reach for it
+ * when that crash comes back.
+ */
+import assert from "node:assert/strict";
+import { treeSitterExtract, isSupported } from "./treesitter.js";
+/** Assert a language's headline symbol extracts, against its real grammar. */
+export async function checkLang(c) {
+    assert.ok(isSupported(c.file), `${c.file} should be a supported language`);
+    const ex = await treeSitterExtract(c.file, c.code);
+    assert.ok(ex, `extraction returned null for ${c.file}`);
+    const hit = ex.defs.find((d) => d.name === c.expect.name);
+    assert.ok(hit, `expected def '${c.expect.name}' in ${c.file}, got: ${ex.defs.map((d) => d.name).join(", ") || "(none)"}`);
+    assert.equal(hit.kind, c.expect.kind);
+}
+/**
+ * Ceiling on the grammar bytes any one part may load. Set above the current
+ * heaviest part (~6.1MB) with room for an ordinary grammar. A part that exceeds
+ * this should be re-split rather than the budget raised.
+ */
+export const PART_BUDGET_BYTES = 7_000_000;
+// The four parts, packed heaviest-grammar-first so no part carries two of the big
+// ones. Approximate wasm size is noted per case, since that is the property being
+// balanced and it is otherwise invisible when editing this list.
+export const PART1 = [
+    { file: "a.ml", code: "let hello x = do_thing x", expect: { name: "hello", kind: "function" } }, // ocaml ~5.0MB
+    { file: "a.c", code: "int hello() { return do_thing(); }", expect: { name: "hello", kind: "function" } }, // ~0.8MB
+    { file: "a.go", code: "package main\nfunc Hello() int { return doThing() }", expect: { name: "Hello", kind: "function" } }, // ~0.2MB
+];
+export const PART2 = [
+    { file: "a.cpp", code: "class Foo { public: void bar(); };", expect: { name: "Foo", kind: "class" } }, // ~4.7MB
+    { file: "a.php", code: "<?php\nfunction hello() { return doThing(); }", expect: { name: "hello", kind: "function" } }, // ~0.8MB
+    { file: "a.java", code: "class Foo { void bar() { baz(); } }", expect: { name: "Foo", kind: "class" } }, // ~0.4MB
+    { file: "a.lua", code: "function hello()\n  return doThing()\nend", expect: { name: "hello", kind: "function" } }, // ~0.04MB
+];
+export const PART3 = [
+    { file: "a.kt", code: "class Foo { fun bar() { baz() } }", expect: { name: "Foo", kind: "class" } }, // kotlin ~4.1MB
+    { file: "a.sh", code: "hello() {\n  do_thing\n}", expect: { name: "hello", kind: "function" } }, // bash ~1.4MB
+    { file: "a.scala", code: "class Foo { def bar() = baz() }", expect: { name: "Foo", kind: "class" } }, // ~0.2MB
+];
+export const PART4 = [
+    { file: "a.cs", code: "class Foo { void Bar() { Baz(); } }", expect: { name: "Foo", kind: "class" } }, // c_sharp ~4.0MB
+    { file: "a.rs", code: "struct Foo {}\nfn hello() -> i32 { do_thing() }", expect: { name: "Foo", kind: "struct" } }, // ~0.8MB
+    { file: "a.zig", code: "fn hello() i32 { return doThing(); }", expect: { name: "hello", kind: "function" } }, // ~0.7MB
+    { file: "a.sol", code: "contract Foo {\n  function bar() public {}\n}", expect: { name: "Foo", kind: "class" } }, // ~0.4MB
+];
+/** Every part, for the budget guard. Order matches the file numbering. */
+export const PARTS = [PART1, PART2, PART3, PART4];
+//# sourceMappingURL=langCases.js.map

package/dist/alternator/chassis/langCases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"langCases.js","sourceRoot":"","sources":["../../../src/alternator/chassis/langCases.ts"],"names":[],"mappings":"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"}