@ghostlygawd/codeweb 0.9.0

package/scripts/find-similar.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// codeweb find-similar — reuse-at-write-time. Before an agent writes a function, it asks "does
+// something already do this?": shingle a candidate body/signature and rank existing non-test
+// function bodies by token-shingle Jaccard. Turns codeweb's post-hoc duplication detection into
+// write-time PREVENTION. Read-only, deterministic. Shares the K=3 shingler with overlap.mjs via
+// ./lib/shingles.mjs (one truth).
+//
+// Usage:
+//   node find-similar.mjs <graph.json> (--body <file> | --stdin | --signature "<text>") [--k N] [--json]
+// Exit: 0 ok (even with zero matches), 2 usage / source unavailable.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { normalizeGraph, isTestFile } from './lib/graph-ops.mjs';
+import { shingles, jaccard } from './lib/shingles.mjs';
+import { structuralShingles } from './lib/skeleton.mjs'; // F6: Type-2 (rename-invariant) similarity
+
+const USAGE = 'usage: find-similar.mjs <graph.json> (--body <file> | --stdin | --signature "<text>") [--k N] [--structural] [--json]';
+import { die, emitJson, finish, loadGraph, sourceReader } from './lib/cli.mjs';
+
+const argv = process.argv.slice(2);
+let json = false, body = null, stdin = false, signature = null, k = 10, structural = false; const pos = [];
+for (let i = 0; i < argv.length; i++) {
+  const t = argv[i];
+  if (t === '--json') json = true;
+  else if (t === '--stdin') stdin = true;
+  else if (t === '--structural') structural = true;
+  else if (t === '--body') body = argv[++i];
+  else if (t === '--signature') signature = argv[++i];
+  else if (t === '--k') k = Math.max(1, parseInt(argv[++i], 10) || 10);
+  else if (!t.startsWith('-')) pos.push(t);
+}
+// F6: --structural ranks by skeleton (identifier-normalized) shingles, so a clone with all variables
+// renamed scores ~1 even when its lexical (token) similarity is lower. Lexical is the default.
+const shg = structural ? (s) => structuralShingles(s, 3) : (s) => shingles(s, 3);
+// exactly one candidate source
+const sources = [body != null, stdin, signature != null].filter(Boolean).length;
+if (sources !== 1) die(USAGE, 2);
+
+const { graph, abs } = loadGraph(pos[0], { usage: USAGE });
+
+const root = graph.meta?.root || null;
+if (!root || !existsSync(root)) die(`source unavailable: graph.meta.root is missing or not on disk — find-similar needs real bodies to compare (got ${root || 'none'})`, 2);
+
+// read candidate text
+let candidateText;
+try {
+  if (body != null) candidateText = readFileSync(resolve(body), 'utf8');
+  else if (stdin) candidateText = readFileSync(0, 'utf8');
+  else candidateText = signature;
+} catch (e) { die(`cannot read candidate: ${e.message}`, 2); }
+
+const candidate = shg(candidateText);
+
+// score every non-test function/method body
+const reader = sourceReader(root);
+const bodyOf = reader.bodyOf;
+const tierOf = (s) => (s >= 0.6 ? 'high' : s >= 0.35 ? 'medium' : 'low'); // overlap.mjs bands
+
+const matches = [];
+for (const n of graph.nodes) {
+  if (n.kind !== 'function' && n.kind !== 'method') continue;
+  if (isTestFile(n.file)) continue;
+  const src = bodyOf(n);
+  if (src == null) continue;
+  const sim = jaccard(candidate, shg(src));
+  if (sim < 0.15) continue; // exclude below the low band
+  matches.push({ id: n.id, label: n.label, file: n.file, line: n.line, domain: n.domain, sim: +sim.toFixed(6), tier: tierOf(sim) });
+}
+matches.sort((a, b) => b.sim - a.sim || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+const top = matches.slice(0, k);
+
+const payload = {
+  candidate: { source: body != null ? 'body' : stdin ? 'stdin' : 'signature', shingles: candidate.size, mode: structural ? 'structural' : 'lexical' },
+  matches: top, count: top.length, scanned: graph.nodes.filter((n) => (n.kind === 'function' || n.kind === 'method') && !isTestFile(n.file)).length,
+};
+
+if (json) { emitJson(payload); } else {
+  console.log(`find-similar: candidate (${payload.candidate.shingles} shingles) vs ${payload.scanned} existing symbols`);
+  if (!top.length) console.log('  no similar existing symbol (>=15%) — looks novel; safe to write.');
+  else {
+    console.log(`  ${top.length} similar — consider reusing instead of re-implementing:`);
+    for (const m of top) console.log(`  [${(m.sim * 100).toFixed(0).padStart(3)}% ${m.tier.padEnd(6)}] ${m.id}  (${m.file}:${m.line})`);
+  }
+  finish(0);
+}

package/scripts/find.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+// codeweb find — concept search: turn an idea ("retry handling", "where is config parsed")
+// into ranked symbols, deterministically. The one query family that doesn't need a name.
+//
+//   node scripts/find.mjs <graph.json> <query words...> [--limit 10] [--offset N] [--json]
+//
+// Ranking: identifier/file/domain token match (camelCase & snake_case split, light stemming)
+// weighted by exports, role (product first — unless the query asks for tests), and fan-in.
+// Output is budgeted (top-N + true total + more.remaining), staleness-annotated like query.mjs.
+
+import { die, emitJson, emitText, loadGraph, capList, checkStaleness } from './lib/cli.mjs';
+import { buildIndex } from './lib/graph-ops.mjs';
+import { findSymbols } from './lib/find-core.mjs';
+
+const USAGE = 'usage: find.mjs <graph.json> <query words...> [--limit 10] [--offset N] [--json]';
+const argv = process.argv.slice(2);
+let json = false, limit = 10, offset = 0; const pos = [];
+for (let i = 0; i < argv.length; i++) {
+  const t = argv[i];
+  if (t === '--json') json = true;
+  else if (t === '--limit') limit = parseInt(argv[++i], 10);
+  else if (t === '--offset') offset = parseInt(argv[++i], 10) || 0;
+  else if (t === '--full') limit = NaN; // capList treats non-finite as "everything"
+  else if (!t.startsWith('-')) pos.push(t);
+}
+const { graph } = loadGraph(pos[0], { usage: USAGE });
+const query = pos.slice(1).join(' ').trim();
+if (!query) die(USAGE, 2);
+
+const index = buildIndex(graph);
+const { qtoks, results } = findSymbols(graph, index, query);
+if (!qtoks.length) die(`query "${query}" has no searchable terms after stopwords`, 2);
+
+const c = capList(results, Number.isFinite(limit) ? limit : null, offset);
+const domains = [...new Set(results.map((r) => r.domain))];
+const payload = {
+  query, terms: qtoks,
+  summary: `"${query}": ${results.length} match(es) across ${domains.length} domain(s)${results.length ? ` — top: ${results[0].id}` : ''}`,
+  results: c.items, count: results.length, domains: domains.slice(0, 8),
+};
+if (c.remaining > 0) payload.more = { remaining: c.remaining, nextOffset: c.offset + c.items.length };
+const stale = checkStaleness(graph);
+if (stale) { payload.stale = stale; payload.summary += ` — graph is stale for ${stale.count}+ file(s); run codeweb_refresh`; }
+
+if (json) { emitJson(payload); } else {
+  const L = [payload.summary];
+  for (const r of c.items) L.push(`  ${String(r.score).padStart(6)}  ${r.label}  (${r.kind}${r.role !== 'product' ? `, ${r.role}` : ''})  ${r.file}:${r.line}  [${r.domain}]  ${r.match}`);
+  if (payload.more) L.push(`  …+${payload.more.remaining} more (--offset ${payload.more.nextOffset})`);
+  emitText(L.join('\n'));
+}

package/scripts/fitness.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+// codeweb fitness (F6) — architecture-as-code. Check a graph against declared invariants and fail
+// review on violation. Rule types: forbidden-dependency {from,to} (domain match), no-cycles,
+// max-fan-in {limit}, max-symbol-loc {limit}, layer {order:[top..bottom]} (a domain may depend only
+// on domains at/below it). Read-only, deterministic. Built on ./lib/graph-ops.mjs.
+//
+// Usage: node fitness.mjs <graph.json> [--rules codeweb.rules.json] [--json]
+//   rules file: { "rules": [ { "id", "type", "severity"?, ...params } ] }   (severity default "error")
+// Exit: 0 ok, 1 when >=1 error-severity violation, 2 usage/IO/unknown-rule.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, join, dirname } from 'node:path';
+import { normalizeGraph, buildIndex, fileCycles } from './lib/graph-ops.mjs';
+
+const USAGE = 'usage: fitness.mjs <graph.json> [--rules codeweb.rules.json] [--json]';
+import { die, emitJson, finish } from './lib/cli.mjs';
+
+const argv = process.argv.slice(2);
+let json = false, rulesArg = null; const pos = [];
+for (let i = 0; i < argv.length; i++) { const t = argv[i]; if (t === '--json') json = true; else if (t === '--rules') rulesArg = argv[++i]; else if (!t.startsWith('-')) pos.push(t); }
+const graphPath = pos[0] || (process.env.CODEWEB_WS ? `${process.env.CODEWEB_WS}/graph.json` : null);
+if (!graphPath) die(USAGE, 2);
+
+const gAbs = resolve(graphPath);
+if (!existsSync(gAbs)) die(`graph not found: ${gAbs}`, 2);
+let graph;
+try { graph = normalizeGraph(JSON.parse(readFileSync(gAbs, 'utf8'))); }
+catch (e) { die(`invalid JSON in ${gAbs}: ${e.message}`, 2); }
+
+// locate rules: --rules, else codeweb.rules.json beside the graph, else in cwd
+const rulesPath = rulesArg ? resolve(rulesArg)
+  : [join(dirname(gAbs), 'codeweb.rules.json'), resolve('codeweb.rules.json')].find(existsSync);
+if (!rulesPath || !existsSync(rulesPath)) die('no rules file (pass --rules <codeweb.rules.json>)', 2);
+let rules;
+try { rules = JSON.parse(readFileSync(rulesPath, 'utf8')).rules; }
+catch (e) { die(`invalid rules JSON in ${rulesPath}: ${e.message}`, 2); }
+if (!Array.isArray(rules)) die('rules file must be { "rules": [ ... ] }', 2);
+
+const index = buildIndex(graph);
+const domOf = (id) => index.byId.get(id)?.domain || 'unassigned';
+const violations = [];
+const add = (rule, message, subjects) => { if (subjects.length) violations.push({ ruleId: rule.id, severity: rule.severity || 'error', type: rule.type, message, subjects }); };
+
+for (const rule of rules) {
+  switch (rule.type) {
+    case 'forbidden-dependency': {
+      const subj = graph.edges.filter((e) => domOf(e.from) === rule.from && domOf(e.to) === rule.to).map((e) => `${e.from} -> ${e.to}`).sort();
+      add(rule, `${subj.length} forbidden edge(s) from '${rule.from}' to '${rule.to}'`, subj);
+      break;
+    }
+    case 'layer': {
+      const rank = new Map((rule.order || []).map((d, i) => [d, i])); // index 0 = top layer
+      const subj = graph.edges.filter((e) => { const rf = rank.get(domOf(e.from)), rt = rank.get(domOf(e.to)); return rf != null && rt != null && rt < rf; }).map((e) => `${e.from} -> ${e.to}`).sort();
+      add(rule, `${subj.length} edge(s) depend on a higher layer (order: ${(rule.order || []).join(' > ')})`, subj);
+      break;
+    }
+    case 'no-cycles': {
+      const subj = fileCycles(graph).map((c) => c.join(' <-> '));
+      add(rule, `${subj.length} file dependency cycle(s)`, subj);
+      break;
+    }
+    case 'max-fan-in': {
+      const subj = graph.nodes.filter((n) => (index.callIn.get(n.id)?.size || 0) > rule.limit).map((n) => `${n.id} (${index.callIn.get(n.id).size} callers)`).sort();
+      add(rule, `${subj.length} symbol(s) exceed fan-in limit ${rule.limit}`, subj);
+      break;
+    }
+    case 'max-symbol-loc': {
+      const subj = graph.nodes.filter((n) => (n.loc || 0) > rule.limit).map((n) => `${n.id} (${n.loc} loc)`).sort();
+      add(rule, `${subj.length} symbol(s) exceed loc limit ${rule.limit}`, subj);
+      break;
+    }
+    default: die(`unknown rule type: ${rule.type} (rule id '${rule.id}')`, 2);
+  }
+}
+
+const errors = violations.filter((v) => v.severity === 'error');
+const payload = { target: graph.meta?.target || 'target', rulesChecked: rules.length, violations, ok: errors.length === 0, errorCount: errors.length, warningCount: violations.length - errors.length };
+const code = errors.length ? 1 : 0;
+
+if (json) { emitJson(payload, code); } else {
+
+console.log(`codeweb fitness: ${payload.target} — ${rules.length} rule(s), ${violations.length} violation(s) (${payload.errorCount} error, ${payload.warningCount} warning)`);
+for (const v of violations) {
+  console.log(`\n[${v.severity.toUpperCase()}] ${v.ruleId} — ${v.message}`);
+  for (const s of v.subjects.slice(0, 12)) console.log(`    ${s}`);
+  if (v.subjects.length > 12) console.log(`    …+${v.subjects.length - 12} more`);
+}
+if (payload.ok) console.log('\nok — no error-level violations');
+finish(code);
+}

package/scripts/grammars/PROVENANCE.md

@@ -0,0 +1,36 @@
+# Vendored tree-sitter grammars
+
+These `.wasm` grammar files are **vendored on purpose** (committed to the repo) so the optional
+tree-sitter engine is offline-reproducible and **determinism is pinned to an exact grammar version** —
+the same input always yields the same graph. Recorded in `meta.engine` when the tree-sitter engine runs.
+
+| File | Language | Source package | Version | ABI |
+|------|----------|----------------|---------|-----|
+| `tree-sitter-typescript.wasm` | TypeScript / TSX-free TS | `@vscode/tree-sitter-wasm` | 0.3.1 | 14 |
+| `tree-sitter-java.wasm` | Java (dispatch tier) | `@vscode/tree-sitter-wasm` | 0.3.1 | 14 |
+| `tree-sitter-c-sharp.wasm` | C# (dispatch tier) | `@vscode/tree-sitter-wasm` | 0.3.1 | 15 |
+| `tree-sitter-python.wasm` | Python (dispatch tier, Spec F) | `@vscode/tree-sitter-wasm` | 0.3.1 | 14 |
+| `tree-sitter-go.wasm` | Go (dispatch tier, Spec F) | `@vscode/tree-sitter-wasm` | 0.3.1 | 14 |
+| `tree-sitter-rust.wasm` | Rust (dispatch tier, Spec F) | `@vscode/tree-sitter-wasm` | 0.3.1 | 14 |
+
+## Runtime
+
+The WASM runtime is `web-tree-sitter@0.26.9`, declared in the root `package.json` as an
+**optionalDependency** — the regex engine (the default) needs zero dependencies; the tree-sitter tier
+is opt-in. If the runtime is not installed, the engine reports unavailable and the extractor falls back
+to the regex path per-file.
+
+## The ABI rule (do not skip)
+
+A grammar `.wasm` must sit inside the runtime's ABI window. `tree-sitter-wasms@0.1.13` ships ABI-13
+grammars (built with `tree-sitter-cli@0.20.x`) that **fail to load** against `web-tree-sitter@0.26.9`
+with a `dylink` metadata error. Always vendor a grammar whose ABI matches the pinned runtime, and bump
+both together. The spike that established this is at `spike/tree-sitter/` (PR #17).
+
+## Refreshing a grammar
+
+```sh
+npm i -D @vscode/tree-sitter-wasm@<version>
+cp node_modules/@vscode/tree-sitter-wasm/wasm/tree-sitter-typescript.wasm scripts/grammars/
+# update the version/ABI row above, bump web-tree-sitter if the ABI moved, re-run the determinism test
+```

package/scripts/hotspots.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// codeweb hotspots CLI (F4) — rank symbols by refactoring priority (complexity x fan-in x churn) so an
+// agent knows WHERE to optimize first in a large codebase. Read-only, deterministic. Built on
+// ./lib/hotspots.mjs (formula one truth, shared with the tests). Churn is optional: --churn <map.json>
+// or --git derives commit counts from the recorded meta.root.
+//
+// Usage: node hotspots.mjs <graph.json> [--churn <map.json> | --git] [--json]
+// Exit: 0 ok, 2 usage/IO.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import { normalizeGraph } from './lib/graph-ops.mjs';
+import { rankHotspots } from './lib/hotspots.mjs';
+
+const USAGE = 'usage: hotspots.mjs <graph.json> [--churn <map.json> | --git] [--json]';
+import { die, emitJson, finish, capList, loadGraph } from './lib/cli.mjs';
+
+const argv = process.argv.slice(2);
+let json = false, churnPath = null, useGit = false, limit = null; const pos = [];
+for (let i = 0; i < argv.length; i++) {
+  const t = argv[i];
+  if (t === '--json') json = true;
+  else if (t === '--limit') limit = Math.max(0, parseInt(argv[++i], 10) || 0);
+  else if (t === '--churn') churnPath = argv[++i];
+  else if (t === '--git') useGit = true;
+  else if (!t.startsWith('-')) pos.push(t);
+}
+const { graph, abs } = loadGraph(pos[0], { usage: USAGE });
+
+let churn = {};
+if (churnPath) { try { churn = JSON.parse(readFileSync(resolve(churnPath), 'utf8')); } catch (e) { die(`invalid churn JSON: ${e.message}`, 2); } }
+else if (useGit) {
+  const root = graph.meta?.root;
+  const r = spawnSync('git', ['-C', root || '.', 'log', '--format=', '--name-only'], { encoding: 'utf8', maxBuffer: 1 << 28 });
+  if (r.status === 0) for (const f of r.stdout.split(/\r?\n/)) if (f.trim()) churn[f.trim()] = (churn[f.trim()] || 0) + 1;
+}
+
+const full = rankHotspots(graph, { churn });
+const capped = capList(full.ranked, limit);
+const payload = { target: graph.meta?.target || 'target', summary: `${full.count} symbol(s) ranked by complexity x fan-in x churn`, ...full, ranked: capped.items };
+if (capped.truncated) payload.more = { remaining: capped.remaining };
+
+if (json) { emitJson(payload); } else {
+
+console.log(`codeweb hotspots: ${payload.target} — ${payload.count} symbol(s) ranked by complexity x fan-in x churn`);
+console.log(`  weights: ${Object.entries(payload.weights).map(([k, v]) => `${k} ${v}`).join(', ')}`);
+for (const r of payload.ranked.slice(0, 15)) {
+  const c = r.components;
+  console.log(`  ${r.score.toFixed(3)}  ${r.id}  [cx ${c.complexity} in ${c.fanIn} churn ${c.churn}]`);
+}
+finish();
+}

package/scripts/lib/annotations.mjs

@@ -0,0 +1,51 @@
+// codeweb finding-annotations (F7) — a deterministic, no-model memory of human/agent judgements.
+// Every finding gets a stable `fingerprint` of its ESSENTIAL identity (kind + the symbols it
+// implicates), so a "false-positive" suppression in `.codeweb/annotations.json` survives re-runs
+// (FPR-STABLE) but CANNOT mask a genuinely new issue: if the implicated symbols change, the
+// fingerprint changes and the finding resurfaces (ANN-IDENTITY-CHANGE-RESURFACES). Writes only to
+// `.codeweb` metadata, never to source. Pure except the two explicit IO helpers.
+
+import { createHash } from 'node:crypto';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+const ANN_FILE = 'annotations.json';
+
+// Essential identity = kind + the sorted set of implicated node ids. Title/severity/evidence/order
+// are cosmetic and excluded, so the same finding fingerprints identically across runs.
+export function fingerprint(finding) {
+  const kind = finding.kind || '';
+  const nodes = [...new Set((finding.nodes || []).map(String))].sort();
+  return createHash('sha1').update(JSON.stringify({ kind, nodes })).digest('hex').slice(0, 16);
+}
+
+// Read <dir>/annotations.json. `dir` IS the annotations directory (callers resolve `.codeweb`).
+// Absent or corrupt -> an empty, well-formed annotation set (never throws).
+export function loadAnnotations(dir) {
+  try {
+    const a = JSON.parse(readFileSync(join(dir, ANN_FILE), 'utf8'));
+    return { suppressions: Array.isArray(a.suppressions) ? a.suppressions : [] };
+  } catch { return { suppressions: [] }; }
+}
+
+// Partition findings into {visible, suppressed}, attaching each finding's fingerprint. A finding is
+// suppressed iff its fingerprint matches a 'false-positive' suppression. Pure (never mutates input).
+export function applySuppressions(findings, annotations) {
+  const killed = new Set((annotations?.suppressions || []).filter((s) => s.verdict === 'false-positive').map((s) => s.fingerprint));
+  const visible = [], suppressed = [];
+  for (const f of findings) {
+    const withFp = { ...f, fingerprint: fingerprint(f) };
+    (killed.has(withFp.fingerprint) ? suppressed : visible).push(withFp);
+  }
+  return { visible, suppressed };
+}
+
+// Append a suppression to <dir>/annotations.json, idempotent by fingerprint. Creates the dir if
+// needed. Returns the updated annotation set.
+export function addSuppression(dir, fp, { note = '', verdict = 'false-positive' } = {}) {
+  const ann = loadAnnotations(dir);
+  if (!ann.suppressions.some((s) => s.fingerprint === fp)) ann.suppressions.push({ fingerprint: fp, verdict, note });
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, ANN_FILE), JSON.stringify(ann, null, 2));
+  return ann;
+}

package/scripts/lib/bench-core.mjs

@@ -0,0 +1,178 @@
+// bench-core — the oracle-A/B engine, factored out of bench/experiments/oracle-ab.mjs so the
+// SAME arms/oracle/scoring serve two callers: the frozen paper experiment (canonical results in
+// bench/results/oracle-ab.json) and the product CLI `scripts/bench.mjs` ("run grep-vs-codeweb on
+// YOUR repo, graded by YOUR compiler"). One truth — a divergence here would make the product
+// bench and the published numbers measure different things.
+//
+// Design (unchanged from the experiment):
+//   control   = grep  (`rg -n '\bX\b'` — the dump a grep-first agent ingests)
+//   treatment = codeweb (`--dependents`, budgeted pages of 20, as served over MCP)
+//   oracle    = TypeScript LanguageService getReferencesAtPosition (optional — absent => ungraded)
+//   grading unit = FILES; cost = bytes injected into the agent context (tokens ~ bytes/4).
+
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { join, resolve } from 'node:path';
+import { createRequire } from 'node:module';
+import { runQuery } from './query-core.mjs';
+
+/** Deterministic PRNG (mulberry32) — the seed IS the sample. */
+export const mulberry = (a) => () => { a |= 0; a = (a + 0x6D2B79F5) | 0; let t = Math.imul(a ^ (a >>> 15), 1 | a); t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t; return ((t ^ (t >>> 14)) >>> 0) / 4294967296; };
+
+/** Repo-relative prefix of the benchmark scope (e.g. packages/vite/src), '' = whole repo. */
+export const scopeOf = (srcRoot, graphRoot) =>
+  resolve(srcRoot).replace(/\\/g, '/').slice(resolve(graphRoot).replace(/\\/g, '/').length).replace(/^\//, '');
+
+export const relOf = (abs, graphRoot) =>
+  abs.replace(/\\/g, '/').slice(resolve(graphRoot).replace(/\\/g, '/').length).replace(/^\//, '');
+
+/** The optional oracle dependency, resolved from the caller's cwd (TS_MODULE overrides). */
+export function loadTypescript(tsModule = process.env.TS_MODULE || 'typescript') {
+  try { return createRequire(join(process.cwd(), 'noop.js'))(tsModule); }
+  catch { return null; }
+}
+
+let _rg = null;
+/** Is ripgrep on PATH? (The grep arm needs it; absent => that arm reports unavailable.) */
+export function rgAvailable() {
+  if (_rg === null) _rg = spawnSync('rg', ['--version'], { stdio: 'ignore' }).error == null;
+  return _rg;
+}
+
+/**
+ * Deterministic symbol sample: exported product functions/classes in scope, label >= 4 chars,
+ * fan-in (calls + imports) >= 3 — symbols an agent would actually ask about. A fixed id list
+ * (A/B across engine versions needs identical tasks) bypasses sampling; absent ids are returned
+ * in `missing`, never silently dropped.
+ */
+export function sampleSymbols(graph, index, { scope = '', n = 30, seed = 42, fixedIds = null } = {}) {
+  if (fixedIds) {
+    const byId = new Map(graph.nodes.map((nd) => [nd.id, nd]));
+    return { sample: fixedIds.map((id) => byId.get(id)).filter(Boolean), missing: fixedIds.filter((id) => !byId.has(id)) };
+  }
+  const rng = mulberry(seed);
+  const pool = graph.nodes.filter((nd) =>
+    (nd.kind === 'function' || nd.kind === 'class') && nd.role === 'product' && nd.exports &&
+    nd.file.startsWith(scope) && nd.label.length >= 4 &&
+    (index.callIn.get(nd.id)?.size || 0) + (index.importIn.get(nd.id)?.size || 0) >= 3
+  ).sort((a, b) => (a.id < b.id ? -1 : 1));
+  const sample = [];
+  while (sample.length < Math.min(n, pool.length) && pool.length) sample.push(pool.splice(Math.floor(rng() * pool.length), 1)[0]);
+  return { sample, missing: [] };
+}
+
+/**
+ * TS LanguageService over the scope. oracleFiles(node) = files with >=1 compiler reference to the
+ * symbol OUTSIDE its declaration entry, or null when the oracle can't resolve it (excluded, not
+ * counted against either arm).
+ */
+export function makeTsOracle(ts, { srcRoot, graphRoot }) {
+  const tsFiles = [];
+  (function walk(d) { for (const e of readdirSync(d, { withFileTypes: true })) { const p = join(d, e.name); if (e.isDirectory()) { if (!/node_modules|__tests__/.test(e.name)) walk(p); } else if (/\.tsx?$/.test(e.name) && !/\.d\.ts$/.test(e.name) && !/\.(test|spec)\./.test(e.name)) tsFiles.push(p); } })(srcRoot);
+  const snapshots = new Map();
+  const host = {
+    getScriptFileNames: () => tsFiles,
+    getScriptVersion: () => '1',
+    getScriptSnapshot: (f) => { if (!snapshots.has(f)) { try { snapshots.set(f, ts.ScriptSnapshot.fromString(readFileSync(f, 'utf8'))); } catch { snapshots.set(f, null); } } return snapshots.get(f); },
+    getCurrentDirectory: () => srcRoot,
+    getCompilationSettings: () => ({ allowJs: true, module: ts.ModuleKind.ESNext, target: ts.ScriptTarget.ES2022, moduleResolution: ts.ModuleResolutionKind.Bundler, noEmit: true, skipLibCheck: true }),
+    getDefaultLibFileName: (o) => ts.getDefaultLibFilePath(o),
+    fileExists: (f) => existsSync(f),
+    readFile: (f) => { try { return readFileSync(f, 'utf8'); } catch { return undefined; } },
+    directoryExists: (d) => { try { return statSync(d).isDirectory(); } catch { return false; } },
+    getDirectories: (d) => { try { return readdirSync(d, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name); } catch { return []; } },
+  };
+  const ls = ts.createLanguageService(host, ts.createDocumentRegistry());
+  const oracleFiles = (node) => {
+    const abs = join(graphRoot, node.file);
+    const text = host.readFile(abs);
+    if (!text) return null;
+    const lines = text.split(/\r?\n/);
+    const col = (lines[node.line - 1] || '').indexOf(node.label);
+    if (col === -1) return null;
+    const position = lines.slice(0, node.line - 1).reduce((s, l) => s + l.length + 1, 0) + col;
+    let refs;
+    try { refs = ls.getReferencesAtPosition(abs, position); } catch { return null; }
+    if (!refs || !refs.length) return null;
+    const files = new Set();
+    for (const r of refs) { if (!r.isDefinition) files.add(relOf(r.fileName, graphRoot)); }
+    return files.size ? files : null;
+  };
+  return { tsFileCount: tsFiles.length, oracleFiles };
+}
+
+/** codeweb arm: --dependents, budgeted pages of 20 (the MCP default), paged to exhaustion. */
+export function codewebArm(graph, index, node, limit = 20) {
+  let offset = 0, files = new Set(), bytes = 0, pages = 0;
+  for (;;) {
+    const { payload } = runQuery(graph, index, { query: 'dependents', symbol: node.id, limit, offset });
+    bytes += JSON.stringify(payload).length; pages++;
+    for (const id of payload.results || []) { const n = index.byId.get(id); if (n) files.add(n.file); }
+    if (!payload.more) break;
+    offset = payload.more.nextOffset;
+  }
+  return { files, bytes, pages };
+}
+
+/** grep arm: one rg dump over the scope. null when rg is not installed. */
+export function grepArm(node, { srcRoot, graphRoot }) {
+  if (!rgAvailable()) return null;
+  let out = '';
+  try { out = execFileSync('rg', ['-n', `\\b${node.label}\\b`, srcRoot], { encoding: 'utf8', maxBuffer: 1 << 28 }); }
+  catch (e) { out = e.stdout || ''; }
+  const files = new Set();
+  for (const line of out.split('\n')) { const m = /^(.*?):\d+:/.exec(line); if (m) files.add(relOf(resolve(m[1]), graphRoot)); }
+  files.delete(node.file); // the agent knows the definition site already
+  return { files, bytes: out.length };
+}
+
+export const score = (reported, truth) => {
+  const inter = [...reported].filter((f) => truth.has(f)).length;
+  return { recall: truth.size ? inter / truth.size : 1, precision: reported.size ? inter / reported.size : 1 };
+};
+
+/**
+ * Blast-radius COST ("what transitively breaks?"): one budgeted codeweb_impact call vs the
+ * recursive grep loop an agent must run to a fixpoint — simulated GENEROUSLY for grep (the graph
+ * hands it each next frontier's symbol names; a real agent must read files to learn them).
+ * grep fields are null when rg is not installed.
+ */
+export function impactCost(graph, index, node, { srcRoot }) {
+  const { payload } = runQuery(graph, index, { query: 'impact', symbol: node.id, limit: 20 });
+  const cw = { bytes: JSON.stringify(payload).length, size: payload.count };
+  if (!rgAvailable()) return { codewebBytes: cw.bytes, impactSize: cw.size, grepBytes: null, grepRounds: null };
+  let bytes = 0, rounds = 0;
+  const seen = new Set([node.id]);
+  let frontier = [node];
+  while (frontier.length && rounds < 12) {
+    rounds++;
+    for (const label of [...new Set(frontier.map((n) => n.label))]) {
+      try { bytes += execFileSync('rg', ['-n', `\\b${label}\\b`, srcRoot], { encoding: 'utf8', maxBuffer: 1 << 28 }).length; }
+      catch (e) { bytes += (e.stdout || '').length; }
+    }
+    const next = [];
+    for (const n of frontier) for (const c of index.callIn.get(n.id) || []) {
+      if (!seen.has(c)) { seen.add(c); const cn = index.byId.get(c); if (cn) next.push(cn); }
+    }
+    frontier = next;
+  }
+  return { codewebBytes: cw.bytes, impactSize: cw.size, grepBytes: bytes, grepRounds: rounds };
+}
+
+export const mean = (xs) => (xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : 0);
+
+/** Recall/precision/cost aggregate for one arm over graded rows (shape frozen by the paper run). */
+export const aggArm = (rows, arm) => ({
+  meanRecall: +mean(rows.map((r) => r[arm].recall)).toFixed(3),
+  meanPrecision: +mean(rows.map((r) => r[arm].precision)).toFixed(3),
+  totalBytes: rows.reduce((s, r) => s + r[arm].bytes, 0),
+  meanBytes: Math.round(mean(rows.map((r) => r[arm].bytes))),
+});
+
+export const aggImpact = (rows) => ({
+  meanImpactSize: Math.round(mean(rows.map((r) => r.impact.impactSize))),
+  codewebMeanBytes: Math.round(mean(rows.map((r) => r.impact.codewebBytes))),
+  grepMeanBytes: Math.round(mean(rows.map((r) => r.impact.grepBytes))),
+  grepMeanRounds: +mean(rows.map((r) => r.impact.grepRounds)).toFixed(1),
+  costRatio: +(mean(rows.map((r) => r.impact.grepBytes)) / Math.max(1, mean(rows.map((r) => r.impact.codewebBytes)))).toFixed(1),
+});