@vizalice/codegraph 1.5.0

package/scripts/agent-eval/probe-decl-only.mjs

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+/**
+ * CG-28 measurement probe — what a DECLARATION-ONLY file takes from an explore
+ * envelope, with and without a generated banner.
+ *
+ * The issue was filed because a Wrangler `worker-configuration.d.ts` scored 49
+ * at `pen 1.00` and took 60.7% of an envelope on generic identifier overlap
+ * (`ReadableStream`, `Body`, `ImageMetadata`, `Message`, …) with a prose query.
+ * CG-25 has since taught `GENERATED_CONTENT_PATTERNS` the Wrangler banner, so
+ * the first thing to measure is whether that alone settles it — it does, and
+ * this probe quantifies it. What CG-25 does NOT cover is a declaration-only file
+ * that carries no banner at all: a hand-maintained ambient `.d.ts`, vendored
+ * typings, module augmentation. This probe puts both shapes in ONE fixture
+ * against ONE envelope so the banner is the only difference between them.
+ * (`.pyi` is not an indexed extension, so Python stubs never enter the graph.)
+ *
+ * Findings and the full regression evidence:
+ * `docs/benchmarks/explore-declaration-only-cg28.md`.
+ *
+ * Fixture: `__tests__/fixtures/ambient-decls-ts/` — an upload path (route →
+ * stream → metadata → queue) competing with:
+ *   types/worker-configuration.d.ts  declaration-only, Wrangler banner (CG-25)
+ *   types/platform-shims.d.ts        declaration-only, hand-written, NO banner
+ *   src/storage/types.ts             declaration-only but IMPORTED — the control
+ *                                    that must never be damped
+ *
+ * Variants (`--variant`):
+ *   both          as committed — the controlled comparison
+ *   strip-banner  the banner is deleted from worker-configuration.d.ts, so the
+ *                 two declaration files differ in NOTHING the ranker can see;
+ *                 the delta against `both` is exactly what CG-25 buys
+ *
+ * Usage (needs a current `npm run build`):
+ *   node scripts/agent-eval/probe-decl-only.mjs
+ *   node scripts/agent-eval/probe-decl-only.mjs --variant strip-banner
+ *   node scripts/agent-eval/probe-decl-only.mjs --json
+ *   node scripts/agent-eval/probe-decl-only.mjs --query "..."
+ */
+import { cpSync, mkdtempSync, readFileSync, writeFileSync, rmSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(HERE, '../..');
+const FIXTURE = join(REPO_ROOT, '__tests__/fixtures/ambient-decls-ts');
+
+const GENERATED_DECL = 'types/worker-configuration.d.ts';
+const HANDWRITTEN_DECL = 'types/platform-shims.d.ts';
+
+/**
+ * The query shapes. The flow ones are prose and name no symbol — the shape that
+ * let the original file in. The last one is the counter-case the issue requires:
+ * a question genuinely ABOUT a declared type must still reach the declaration.
+ */
+const QUERIES = [
+  { id: 'flow-upload', kind: 'flow', text: 'how does an upload request stream the file body to storage and record image metadata' },
+  { id: 'flow-pipe', kind: 'flow', text: 'where does the upload body get piped into the bucket and the metadata written' },
+  { id: 'flow-generic', kind: 'flow', text: 'how are streams and messages and image metadata handled for uploads' },
+  { id: 'flow-queue', kind: 'flow', text: 'what happens after an object is stored and the follow-up message is queued' },
+  { id: 'type-shim', kind: 'type', text: 'UploadStorage StoredUploadObject ImageMetadataShim' },
+  { id: 'type-prose', kind: 'type', text: 'what does the UploadStorage interface declare for putting an object' },
+];
+
+const argv = process.argv.slice(2);
+const asJson = argv.includes('--json');
+const at = (flag) => { const i = argv.indexOf(flag); return i >= 0 ? argv[i + 1] : undefined; };
+const VARIANT = at('--variant') ?? 'both';
+const ONE_QUERY = at('--query');
+const ONE_ID = at('--only');
+
+const say = (s = '') => { if (!asJson) console.log(s); };
+const num = (n) => Math.round(n).toLocaleString('en-US');
+const pct = (f) => `${(f * 100).toFixed(1)}%`;
+
+if (!existsSync(join(REPO_ROOT, 'dist/index.js'))) {
+  console.error('dist/ not built — run `npm run build` first.');
+  process.exit(2);
+}
+const load = (rel) => import(pathToFileURL(resolve(REPO_ROOT, rel)).href);
+const idxMod = await load('dist/index.js');
+const toolsMod = await load('dist/mcp/tools.js');
+const CodeGraph = idxMod.default?.default ?? idxMod.default ?? idxMod.CodeGraph;
+const ToolHandler = toolsMod.ToolHandler ?? toolsMod.default?.ToolHandler;
+
+/** Copy the fixture, apply the variant, index it. Hermetic per run. */
+function materialize(variant) {
+  const dir = mkdtempSync(join(tmpdir(), 'cg-decl-'));
+  cpSync(FIXTURE, dir, { recursive: true });
+  rmSync(join(dir, '.codegraph'), { recursive: true, force: true });
+  if (variant === 'strip-banner') {
+    const p = join(dir, GENERATED_DECL);
+    // Drop only the banner comment lines; every declaration stays.
+    const kept = readFileSync(p, 'utf8').split('\n').filter((l) => !/^\/\/ .*(Generated by Wrangler|Runtime types generated)/.test(l));
+    writeFileSync(p, kept.join('\n'));
+  } else if (variant !== 'both') {
+    rmSync(dir, { recursive: true, force: true });
+    throw new Error(`unknown --variant ${variant} (both | strip-banner)`);
+  }
+  return dir;
+}
+
+const queries = ONE_QUERY
+  ? [{ id: 'custom', kind: 'flow', text: ONE_QUERY }]
+  : QUERIES.filter((q) => !ONE_ID || q.id === ONE_ID);
+
+const dir = materialize(VARIANT);
+let rows;
+try {
+  let cg = CodeGraph.initSync(dir);
+  await cg.indexAll();
+  cg.close?.();
+
+  const sidecar = join(dir, 'diag.jsonl');
+  rows = [];
+  for (const q of queries) {
+    rmSync(sidecar, { force: true });
+    process.env.CODEGRAPH_EXPLORE_DEBUG = sidecar;
+    cg = CodeGraph.openSync(dir);
+    const res = await new ToolHandler(cg).execute('codegraph_explore', { query: q.text });
+    const text = res.content?.[0]?.text ?? '';
+    cg.close?.();
+    delete process.env.CODEGRAPH_EXPLORE_DEBUG;
+    const report = JSON.parse(readFileSync(sidecar, 'utf8').trim().split('\n').pop());
+
+    const pick = (path) => {
+      const f = report.files.find((x) => x.path === path);
+      if (!f) return null;
+      return {
+        path, rank: f.rank, score: f.score, graph: f.graphScore, hits: f.termHits,
+        penalty: f.penalty, generated: f.generated, render: f.render,
+        named: f.named, entry: f.entry, central: f.central,
+        allocatedShare: f.allocatedShare, share: f.share,
+        emitted: f.emittedChars, final: f.finalChars, skipped: f.skipped,
+      };
+    };
+    const declPaths = new Set([GENERATED_DECL, HANDWRITTEN_DECL]);
+    const totalSource = report.files.reduce((a, f) => a + f.finalChars, 0);
+    const declSource = report.files
+      .filter((f) => declPaths.has(f.path))
+      .reduce((a, f) => a + f.finalChars, 0);
+    // "Named in the response but carrying no source" is the correct outcome for
+    // a cliffed declaration file — the agent can still fetch it in one call.
+    const namedInResponse = (p) => text.includes(p);
+
+    rows.push({
+      query: q.id, kind: q.kind, text: q.text,
+      envelope: report.envelope,
+      generatedDecl: pick(GENERATED_DECL),
+      handwrittenDecl: pick(HANDWRITTEN_DECL),
+      declSourceShare: totalSource > 0 ? declSource / totalSource : 0,
+      implSourceShare: totalSource > 0 ? (totalSource - declSource) / totalSource : 0,
+      topFile: report.files.filter((f) => f.finalChars > 0).sort((a, b) => b.finalChars - a.finalChars)[0]?.path ?? null,
+      generatedNamed: namedInResponse(GENERATED_DECL),
+      handwrittenNamed: namedInResponse(HANDWRITTEN_DECL),
+      files: report.files
+        .filter((f) => f.emittedChars > 0 || f.finalChars > 0)
+        .map((f) => ({ rank: f.rank, path: f.path, score: f.score, graph: f.graphScore, hits: f.termHits, penalty: f.penalty, generated: f.generated, declOnly: f.ambientDeclaration, named: f.named, entry: f.entry, central: f.central, render: f.render, final: f.finalChars, share: f.share })),
+    });
+  }
+} finally {
+  rmSync(dir, { recursive: true, force: true });
+}
+
+if (asJson) {
+  console.log(JSON.stringify({ variant: VARIANT, rows }, null, 2));
+} else {
+  say(`variant  ${VARIANT}`);
+  say('');
+  for (const r of rows) {
+    say(`── ${r.query} [${r.kind}]  "${r.text}"`);
+    say(`   envelope ${num(r.envelope.chars)} chars · decl-only files hold ${pct(r.declSourceShare)} of delivered source`);
+    say('    #  deliv%    bytes  score    graph  hits  pen   gen  flags               render     file');
+    for (const f of r.files) {
+      const flags = [f.named && "named", f.entry && "entry", f.central && "central", f.declOnly && "decl-only"].filter(Boolean).join(" ") || "-";
+      say(
+        '   ' + String(f.rank).padStart(2) + '  ' +
+        pct(f.share).padStart(6) + '  ' +
+        num(f.final).padStart(7) + '  ' +
+        Number(f.score).toFixed(1).padStart(5) + '  ' +
+        f.graph.toFixed(5).padStart(7) + '  ' +
+        String(f.hits).padStart(4) + '  ' +
+        f.penalty.toFixed(2).padStart(4) + '  ' +
+        (f.generated ? ' ✓ ' : '   ') + '  ' +
+        flags.padEnd(18) + '  ' +
+        (f.render ?? '-').padEnd(9) + '  ' +
+        f.path,
+      );
+    }
+    for (const [label, d, named] of [
+      ['generated  ', r.generatedDecl, r.generatedNamed],
+      ['handwritten', r.handwrittenDecl, r.handwrittenNamed],
+    ]) {
+      say(`   ${label} ${d ? `rank #${d.rank}, score ${Number(d.score).toFixed(1)}, pen ${d.penalty.toFixed(2)}, ${num(d.final)} chars (${pct(d.share)})${d.final === 0 ? ` — ${d.skipped ?? d.render ?? 'not rendered'}` : ''}` : 'not a candidate'}${named ? ' · named in response' : ''}`);
+    }
+    say('');
+  }
+}

package/scripts/agent-eval/probe-explore.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// One-shot probe: run handleExplore against an existing index using the built
+// dist, print the output + a few stats. Lets us verify explore's coverage fix
+// without a full agent run. Usage: node probe-explore.mjs <repo-with-.codegraph> "<query>"
+import { pathToFileURL } from 'node:url';
+import { resolve } from 'node:path';
+
+const [, , repo, query] = process.argv;
+if (!repo || !query) {
+  console.error('usage: probe-explore.mjs <repo> "<query>"');
+  process.exit(1);
+}
+
+const load = async (rel) => import(pathToFileURL(resolve(rel)).href);
+const idx = await load('dist/index.js');
+const tools = await load('dist/mcp/tools.js');
+
+// esModuleInterop: dynamic import of CJS yields { default: module.exports, ...named }
+const CodeGraph = idx.default?.default ?? idx.default ?? idx.CodeGraph;
+const ToolHandler = tools.ToolHandler ?? tools.default?.ToolHandler;
+
+if (typeof CodeGraph?.openSync !== 'function') {
+  console.error('could not resolve CodeGraph.openSync; index keys:', Object.keys(idx), 'default keys:', idx.default && Object.keys(idx.default));
+  process.exit(2);
+}
+if (typeof ToolHandler !== 'function') {
+  console.error('could not resolve ToolHandler; tools keys:', Object.keys(tools));
+  process.exit(2);
+}
+
+const cg = CodeGraph.openSync(repo);
+const h = new ToolHandler(cg);
+const res = await h.execute('codegraph_explore', { query });
+const text = res.content?.[0]?.text ?? '(no text)';
+console.log(text);
+console.error('\n--- PROBE STATS ---');
+console.error('output chars:', text.length);
+console.error('triggerRender body present (-> setState({})):', /triggerRender[\s\S]{0,400}setState\(\{\}\)/.test(text));
+console.error('App.tsx in source section:', /\*\*`.*App\.tsx`\*\* —/.test(text));
+try { cg.close?.(); } catch {}

package/scripts/agent-eval/probe-factory-closure.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+/**
+ * CG-27 measurement probe — what a factory-closure file actually delivers.
+ *
+ * `probe-allocation.mjs` measures how the envelope is split BETWEEN files. This
+ * one measures what comes back from WITHIN one file whose top-level symbol spans
+ * almost all of it: a `createFoo()` factory returning an object of closures
+ * (Svelte 5 rune stores, React hook modules, Zustand `create((set,get)=>({…}))`,
+ * IIFE module-pattern JS). The claim under test is a ranking one, not a byte one
+ * — CG-30 already bounds the bytes — so the number that matters is WHICH inner
+ * symbols reach the agent, not how many chars did.
+ *
+ * Prints, for the factory file: every line range the response delivered, and for
+ * each inner function whether its DEFINITION LINE is inside one of them.
+ *
+ * Usage (needs a current `npm run build`):
+ *   node scripts/agent-eval/probe-factory-closure.mjs
+ *   node scripts/agent-eval/probe-factory-closure.mjs --json
+ *   node scripts/agent-eval/probe-factory-closure.mjs --query "..."
+ */
+import { cpSync, mkdtempSync, readFileSync, rmSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(HERE, '../..');
+const FIXTURE = join(REPO_ROOT, '__tests__/fixtures/factory-closure-ts');
+const targetAt = process.argv.indexOf('--target');
+const TARGET = targetAt >= 0 ? process.argv[targetAt + 1] : 'src/stores/dashboard-store.ts';
+const factoryAt = process.argv.indexOf('--factory');
+const FACTORY = factoryAt >= 0 ? process.argv[factoryAt + 1] : 'createDashboardStore';
+
+const argv = process.argv.slice(2);
+const asJson = argv.includes('--json');
+const queryAt = argv.indexOf('--query');
+const QUERY = queryAt >= 0
+  ? argv[queryAt + 1]
+  : 'how does the dashboard store refresh its metrics and apply a filter';
+
+const say = (s = '') => { if (!asJson) console.log(s); };
+const num = (n) => Math.round(n).toLocaleString('en-US');
+
+const load = (rel) => import(pathToFileURL(resolve(REPO_ROOT, rel)).href);
+if (!existsSync(join(REPO_ROOT, 'dist/index.js'))) {
+  console.error('dist/ not built — run `npm run build` first.');
+  process.exit(2);
+}
+const idxMod = await load('dist/index.js');
+const toolsMod = await load('dist/mcp/tools.js');
+const CodeGraph = idxMod.default?.default ?? idxMod.default ?? idxMod.CodeGraph;
+const ToolHandler = toolsMod.ToolHandler ?? toolsMod.default?.ToolHandler;
+
+const dir = mkdtempSync(join(tmpdir(), 'cg-factory-'));
+cpSync(FIXTURE, dir, { recursive: true });
+rmSync(join(dir, '.codegraph'), { recursive: true, force: true });
+
+let out;
+try {
+  let cg = CodeGraph.initSync(dir);
+  await cg.indexAll();
+
+  // Inner function definitions, straight from the index — the symbols the file's
+  // enclosing factory range would otherwise swallow.
+  const nodes = cg.getNodesInFile(TARGET);
+  const factory = nodes.find((n) => n.name === FACTORY);
+  const inner = nodes
+    .filter((n) => (n.kind === 'function' || n.kind === 'method')
+      && n.name !== FACTORY
+      && factory && n.startLine > factory.startLine && n.endLine <= factory.endLine)
+    .sort((a, b) => a.startLine - b.startLine);
+  cg.close?.();
+
+  const sidecar = join(dir, 'diag.jsonl');
+  process.env.CODEGRAPH_EXPLORE_DEBUG = sidecar;
+  cg = CodeGraph.openSync(dir);
+  const res = await new ToolHandler(cg).execute('codegraph_explore', { query: QUERY });
+  const text = res.content?.[0]?.text ?? '';
+  cg.close?.();
+  delete process.env.CODEGRAPH_EXPLORE_DEBUG;
+  const report = JSON.parse(readFileSync(sidecar, 'utf8').trim().split('\n').pop());
+
+  // Which source lines of the target file the response actually carries. The
+  // response numbers every delivered line `<n>\t<text>`; match them back against
+  // the file so a line number that merely appears in prose can't count.
+  const source = readFileSync(join(dir, TARGET), 'utf8').split('\n');
+  const delivered = new Set();
+  for (const line of text.split('\n')) {
+    const m = /^(\d+)\t(.*)$/.exec(line);
+    if (!m) continue;
+    const n = Number(m[1]);
+    if (n >= 1 && n <= source.length && source[n - 1] === m[2]) delivered.add(n);
+  }
+  // Collapse to ranges for display.
+  const ranges = [];
+  for (const n of [...delivered].sort((a, b) => a - b)) {
+    const last = ranges[ranges.length - 1];
+    if (last && n === last.end + 1) last.end = n;
+    else ranges.push({ start: n, end: n });
+  }
+
+  const covered = (n) => delivered.has(n.startLine);
+  const rec = report.files.find((f) => f.path === TARGET) ?? null;
+
+  out = {
+    query: QUERY,
+    target: TARGET,
+    fileLines: source.length,
+    factory: factory ? { name: factory.name, start: factory.startLine, end: factory.endLine } : null,
+    file: rec && {
+      rank: rec.rank, render: rec.render, clipped: rec.clipped,
+      emittedChars: rec.emittedChars, finalChars: rec.finalChars,
+      allowance: rec.allowance, spendable: rec.spendable, skipped: rec.skipped,
+    },
+    deliveredRanges: ranges,
+    deliveredLines: delivered.size,
+    inner: inner.map((n) => ({ name: n.name, start: n.startLine, end: n.endLine, delivered: covered(n) })),
+    innerDelivered: inner.filter(covered).length,
+    innerTotal: inner.length,
+    envelope: report.envelope,
+    allFiles: report.files
+      .filter((f) => f.emittedChars > 0 || f.finalChars > 0)
+      .map((f) => ({ rank: f.rank, path: f.path, render: f.render, emitted: f.emittedChars, final: f.finalChars })),
+  };
+} finally {
+  rmSync(dir, { recursive: true, force: true });
+}
+
+if (asJson) {
+  console.log(JSON.stringify(out, null, 2));
+} else {
+  say(`query   "${out.query}"`);
+  say(`target  ${out.target} — ${out.fileLines} lines, factory ${out.factory?.name} spans ${out.factory?.start}–${out.factory?.end}`);
+  say('');
+  say('  #  render      emitted    final  file');
+  for (const f of out.allFiles) {
+    say(`  ${String(f.rank).padStart(2)}  ${(f.render ?? '-').padEnd(10)}  ${num(f.emitted).padStart(7)}  ${num(f.final).padStart(7)}  ${f.path}`);
+  }
+  say('');
+  say(`delivered lines of ${out.target}: ${out.deliveredLines}`);
+  say(`  ranges: ${out.deliveredRanges.map((r) => `${r.start}-${r.end}`).join(', ') || '(none)'}`);
+  say('');
+  say(`inner symbols whose definition reached the agent: ${out.innerDelivered}/${out.innerTotal}`);
+  for (const n of out.inner) {
+    say(`  ${n.delivered ? '✓' : '·'}  ${n.name} (${n.start}–${n.end})`);
+  }
+}

package/scripts/agent-eval/probe-file-spend.mjs

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+/**
+ * Per-file reservation-vs-delivered sweep for `codegraph_explore` (CG-36).
+ *
+ * `probe-suite-envelope.mjs` answers "how much source did the response deliver";
+ * this answers the question one level down — "did the bytes go to the files that
+ * earned them". The CG-36 defect was invisible to the envelope probe because the
+ * envelope stayed full: a rank-#3 file spent 24% of its reservation, the slack
+ * carried forward exactly as designed, and a far weaker file spent 3.5x its own.
+ * The response looked healthy; the ANSWER-bearing file had been starved.
+ *
+ * So the flag here is a PAIR, not a per-file threshold: a file that leaves a
+ * large share of its reservation unspent WHILE a materially lower-scoring file
+ * spends well over its own. Either alone is legitimate — a small file simply has
+ * less to say, and carry-forward is the mechanism that hands its slack down.
+ *
+ * Numbers come from the CG-4 diagnostic (`CODEGRAPH_EXPLORE_DEBUG`), so this
+ * measures the shipping allocator rather than re-deriving shares from markdown.
+ *
+ * Usage (needs a current `npm run build`, and full-REBUILT indexes — CG-33):
+ *   node scripts/agent-eval/probe-file-spend.mjs
+ *   node scripts/agent-eval/probe-file-spend.mjs --json > /tmp/new.json
+ *   node scripts/agent-eval/probe-file-spend.mjs --baseline /tmp/base.json
+ *   node scripts/agent-eval/probe-file-spend.mjs django --all   # every file, not just flags
+ *   CORPUS=/tmp/codegraph-corpus node scripts/agent-eval/probe-file-spend.mjs
+ *
+ * Exit code is 1 when any repo carries a starvation flag, so this can gate.
+ */
+import { mkdtempSync, readFileSync, rmSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const CORPUS = process.env.CORPUS ?? '/tmp/codegraph-corpus';
+
+/** Same six repos and queries the CG-30/CG-31/CG-26 envelope tables use. */
+const SUITE = [
+  { id: 'django', q: 'How does a QuerySet turn into SQL and fetch rows from the database?' },
+  { id: 'excalidraw', q: 'How does updating an element re-render the canvas on screen?' },
+  { id: 'okhttp', q: 'How does a call go through the interceptor chain to the network?' },
+  { id: 'tokio', q: 'How does a spawned task get scheduled and run by a worker?' },
+  { id: 'gin', q: 'How does a registered route handler get invoked for an incoming HTTP request?' },
+  { id: 'alamofire', q: 'How does a request get built and sent through the session?' },
+];
+
+/**
+ * Starvation thresholds. A flag needs BOTH sides — the starved file and the
+ * overspending one it lost the bytes to.
+ *
+ * `MIN_RESERVED` keeps the noise out: under it, "80% unspent" is a few hundred
+ * chars and means nothing. `SCORE_RATIO` is what makes the pair meaningful —
+ * a higher-scoring file underspending while a *comparable* one overspends is
+ * ordinary; the defect is a materially weaker file taking the bytes.
+ */
+const STARVED_SHARE = 0.5;   // spent < half its reservation
+const OVERSPEND_RATIO = 1.5; // spent > 1.5x its own reservation
+const SCORE_RATIO = 2;       // ...while scoring less than half the starved file
+const MIN_RESERVED = 2000;   // ignore files whose reservation is too small to matter
+
+const argv = process.argv.slice(2);
+const asJson = argv.includes('--json');
+const showAll = argv.includes('--all');
+const baselineAt = argv.includes('--baseline') ? argv[argv.indexOf('--baseline') + 1] : null;
+const only = argv.filter((a) => !a.startsWith('--') && a !== baselineAt);
+
+const say = (s = '') => { if (!asJson) console.log(s); };
+const num = (n) => Math.round(n).toLocaleString('en-US');
+const pct = (f) => `${(f * 100).toFixed(1)}%`;
+
+const load = (rel) => import(pathToFileURL(resolve(rel)).href);
+const idx = await load('dist/index.js');
+const toolsMod = await load('dist/mcp/tools.js');
+const CodeGraph = idx.default?.default ?? idx.default ?? idx.CodeGraph;
+const ToolHandler = toolsMod.ToolHandler ?? toolsMod.default?.ToolHandler;
+if (typeof CodeGraph?.openSync !== 'function' || typeof ToolHandler !== 'function') {
+  console.error('could not resolve CodeGraph/ToolHandler from dist/ — run `npm run build`');
+  process.exit(2);
+}
+
+/**
+ * Pair up the starved with the overspenders they lost bytes to. Only files the
+ * render loop actually reached (a reservation and a render mode) take part —
+ * a cliffed or max-files file never had bytes to spend.
+ */
+function findStarvation(files) {
+  const spenders = files.filter(
+    (f) => f.allowance !== null && f.allowance > 0 && f.render && f.render !== 'backref',
+  );
+  const flags = [];
+  for (const s of spenders) {
+    if (s.allowance < MIN_RESERVED) continue;
+    if (s.finalChars >= s.allowance * STARVED_SHARE) continue;
+    for (const o of spenders) {
+      if (o.path === s.path) continue;
+      if (o.finalChars <= o.allowance * OVERSPEND_RATIO) continue;
+      if (o.score * SCORE_RATIO > s.score) continue;
+      flags.push({
+        starved: s.path,
+        starvedScore: s.score,
+        starvedReserved: s.allowance,
+        starvedSpent: s.finalChars,
+        overspent: o.path,
+        overspentScore: o.score,
+        overspentReserved: o.allowance,
+        overspentSpent: o.finalChars,
+      });
+    }
+  }
+  return flags;
+}
+
+const tmp = mkdtempSync(join(tmpdir(), 'cg-spend-'));
+const results = [];
+try {
+  for (const { id, q } of SUITE) {
+    if (only.length > 0 && !only.includes(id)) continue;
+    const repo = join(CORPUS, id);
+    if (!existsSync(join(repo, '.codegraph', 'codegraph.db'))) {
+      say(`${id}: no index at ${repo} — skipped`);
+      continue;
+    }
+    const sidecar = join(tmp, `${id}.jsonl`);
+    process.env.CODEGRAPH_EXPLORE_DEBUG = sidecar;
+    const cg = CodeGraph.openSync(repo);
+    const h = new ToolHandler(cg);
+    await h.execute('codegraph_explore', { query: q });
+    try { cg.close?.(); } catch { /* best effort */ }
+    const report = JSON.parse(readFileSync(sidecar, 'utf8').trim().split('\n').pop());
+    const files = report.files.map((f) => ({
+      path: f.path,
+      rank: f.rank,
+      score: f.score,
+      allowance: f.allowance,
+      spendable: f.spendable,
+      finalChars: f.finalChars,
+      render: f.render,
+      skipped: f.skipped,
+      spent: f.allowance ? f.finalChars / f.allowance : null,
+    }));
+    results.push({
+      repo: id,
+      sourceChars: report.envelope.sourceChars,
+      files,
+      flags: findStarvation(files),
+    });
+  }
+} finally {
+  rmSync(tmp, { recursive: true, force: true });
+}
+
+if (asJson) {
+  console.log(JSON.stringify(results, null, 2));
+} else {
+  const base = baselineAt ? JSON.parse(readFileSync(baselineAt, 'utf8')) : null;
+  const byRepo = new Map((base ?? []).map((r) => [r.repo, r]));
+  for (const r of results) {
+    const b = byRepo.get(r.repo);
+    say(`\n${r.repo}  —  ${num(r.sourceChars)} source chars`
+      + (b ? `  (baseline ${num(b.sourceChars)})` : ''));
+    say(' #   score  reserved   spent   spent%   render        file');
+    say('-'.repeat(96));
+    const flagged = new Set(r.flags.flatMap((f) => [f.starved, f.overspent]));
+    for (const f of r.files) {
+      if (f.allowance === null || f.allowance === 0) continue;
+      if (!showAll && !flagged.has(f.path) && f.spent > STARVED_SHARE && f.spent < OVERSPEND_RATIO) continue;
+      const mark = flagged.has(f.path) ? '*' : ' ';
+      say(
+        `${String(f.rank).padStart(2)}${mark} ${String(Math.round(f.score)).padStart(6)} `
+        + `${num(f.allowance).padStart(9)} ${num(f.finalChars).padStart(7)} `
+        + `${pct(f.spent).padStart(7)}   ${(f.render ?? f.skipped ?? '—').padEnd(13)} ${f.path}`,
+      );
+    }
+    for (const f of r.flags) {
+      say(`  FLAG: ${f.starved} (score ${Math.round(f.starvedScore)}) spent `
+        + `${num(f.starvedSpent)}/${num(f.starvedReserved)} while ${f.overspent} `
+        + `(score ${Math.round(f.overspentScore)}) spent ${num(f.overspentSpent)}/${num(f.overspentReserved)}`);
+    }
+  }
+  const total = results.reduce((n, r) => n + r.flags.length, 0);
+  say('');
+  say(total === 0
+    ? 'No file leaves a large share of its reservation unspent while a weaker file overspends.'
+    : `STARVATION: ${total} flag(s) across `
+      + `${results.filter((r) => r.flags.length > 0).map((r) => r.repo).join(', ')}.`);
+  if (base) {
+    const worse = results.filter((r) => {
+      const b = byRepo.get(r.repo);
+      return b && (r.flags.length > b.flags.length || r.sourceChars < b.sourceChars);
+    });
+    say(worse.length === 0
+      ? 'No repo flags more or delivers less than the baseline.'
+      : `REGRESSION vs baseline: ${worse.map((r) => r.repo).join(', ')}.`);
+  }
+  if (total > 0) process.exitCode = 1;
+}