@ghostlygawd/codeweb 0.9.0

package/scripts/codemod.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+// codeweb codemod (F8) — turn a consolidation OPPORTUNITY (or an explicit merge) into a concrete,
+// gate-checked edit PLAN, and optionally APPLY it. Default is plan-only (pure). --write is
+// conservative + REVERSIBLE: it refuses when the plan predicts a regression or a loser label can't
+// be rewritten unambiguously, backs up every touched file, applies the edits, RE-EXTRACTS, and
+// reverts byte-for-byte if the structural gate regresses. Source-rewriting is structural best-effort
+// (it never re-introduces the byName guessing the extractor refuses). Built on ./lib/graph-ops.mjs
+// (shares applyEdit / structuralRegressions / chooseCanonical — one truth with simulate-edit/optimize).
+//
+// Usage: node codemod.mjs <graph.json> (--opportunity <ovId> | --merge <ids> --into <id>) [--json] [--write]
+// Exit: 0 ok, 1 predicted/actual regression (no net change), 2 usage/IO/ambiguous.
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { normalizeGraph, buildIndex, callersOf, impactOf, applyEdit, structuralRegressions, chooseCanonical, resolveSymbol } from './lib/graph-ops.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const USAGE = 'usage: codemod.mjs <graph.json> (--opportunity <ovId> | --merge <ids> --into <id>) [--json] [--write]';
+import { die, emitJson, finish, loadGraph } from './lib/cli.mjs';
+
+const argv = process.argv.slice(2);
+let json = false, doWrite = false, opp = null, merge = null, into = null; const pos = [];
+for (let i = 0; i < argv.length; i++) {
+  const t = argv[i];
+  if (t === '--json') json = true;
+  else if (t === '--write') doWrite = true;
+  else if (t === '--opportunity') opp = argv[++i];
+  else if (t === '--merge') merge = argv[++i];
+  else if (t === '--into') into = 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 || (opp == null && merge == null)) die(USAGE, 2);
+
+const { graph, abs } = loadGraph(graphPath, { usage: USAGE });
+
+const index = buildIndex(graph);
+
+// resolve the cluster to merge + the canonical survivor
+let ids, canonical;
+if (opp != null) {
+  const o = graph.overlaps.find((x) => x.id === opp);
+  if (!o) die(`opportunity not found: ${opp}`, 2);
+  ids = [...new Set(o.nodes)];
+  if (ids.length < 2) die(`opportunity ${opp} has <2 nodes`, 2);
+  canonical = chooseCanonical(index, ids);
+} else {
+  ids = [...new Set(merge.split(',').flatMap((s) => resolveSymbol(graph, s.trim())))];
+  if (ids.length < 2) die(`--merge needs >=2 resolved symbols (got ${ids.length})`, ids.length ? 2 : 1);
+  canonical = into != null ? (resolveSymbol(graph, into)[0] || into) : chooseCanonical(index, ids);
+}
+const losers = ids.filter((id) => id !== canonical);
+const byId = index.byId;
+
+// projected gate (the SAME oracle simulate-edit is pinned to — one truth)
+const after = applyEdit(graph, { kind: 'merge', ids, into: canonical });
+const sr = structuralRegressions(graph, after);
+const projectedGate = { newCycles: sr.newCycles, lostCallers: sr.lostCallers, ok: sr.newCycles.length === 0 && sr.lostCallers.length === 0 };
+
+const deletions = losers.map((id) => { const n = byId.get(id); return { id, file: n.file, range: [n.line, n.line + (n.loc || 1) - 1] }; });
+const rewrites = callersOf(index, losers).map((cid) => { const n = byId.get(cid); return { callerId: cid, file: n?.file ?? null, line: n?.line ?? null }; });
+const locReclaimed = losers.reduce((s, id) => s + (byId.get(id)?.loc || 0), 0);
+const canonLabel = byId.get(canonical)?.label;
+const plan = { canonical, canonicalLabel: canonLabel, losers, deletions, rewrites, blastRadius: impactOf(index, ids).length, locReclaimed, projectedGate };
+
+// ---- --write: conservative, gated, reversible ------------------------------------------------
+let writeResult = null, code = 0;
+if (doWrite) {
+  const root = graph.meta?.root;
+  if (!root || !existsSync(root)) die(`--write needs graph.meta.root on disk (got ${root || 'none'})`, 2);
+  if (!projectedGate.ok) { writeResult = { applied: false, reason: 'the gate predicts a regression — refusing to write', projectedGate }; code = 1; }
+  else {
+    // a loser whose label differs from the canonical's must have a GLOBALLY-UNIQUE label to rewrite
+    // safely (the token unambiguously refers to it); else refuse (never guess — the extractor's rule).
+    const labelCount = (lab) => graph.nodes.filter((n) => n.label === lab).length;
+    const renameLosers = losers.filter((id) => byId.get(id).label !== canonLabel);
+    const ambiguous = renameLosers.filter((id) => labelCount(byId.get(id).label) !== 1);
+    if (ambiguous.length) { writeResult = { applied: false, reason: `cannot safely rewrite ambiguous label(s): ${ambiguous.map((id) => byId.get(id).label).join(', ')} — apply by hand`, ambiguous }; code = 2; }
+    else {
+      const touched = [...new Set([...deletions.map((d) => d.file), ...rewrites.map((r) => r.file).filter(Boolean)])];
+      const backup = new Map();
+      for (const f of touched) { const p = join(root, f); backup.set(f, existsSync(p) ? readFileSync(p, 'utf8') : null); }
+      const restore = () => { for (const [f, txt] of backup) if (txt != null) writeFileSync(join(root, f), txt); };
+      try {
+        // 1) delete loser definition line-ranges (descending per file so indices stay valid)
+        const delByFile = new Map();
+        for (const d of deletions) { if (!delByFile.has(d.file)) delByFile.set(d.file, []); delByFile.get(d.file).push(d.range); }
+        for (const [f, ranges] of delByFile) {
+          const p = join(root, f); const raw = readFileSync(p, 'utf8');
+          const eol = raw.includes('\r\n') ? '\r\n' : '\n'; // preserve the file's line ending (no silent CRLF->LF)
+          const lines = raw.split(/\r?\n/);
+          for (const [s, e] of ranges.slice().sort((a, b) => b[0] - a[0])) lines.splice(s - 1, e - s + 1);
+          writeFileSync(p, lines.join(eol));
+        }
+        // 2) rewrite each rename-loser's label token -> canonical label, across every touched file
+        const renameLabels = [...new Set(renameLosers.map((id) => byId.get(id).label))];
+        for (const f of touched) {
+          const p = join(root, f); if (!existsSync(p)) continue;
+          let txt = readFileSync(p, 'utf8');
+          for (const lab of renameLabels) txt = txt.replace(new RegExp(`\\b${lab.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'g'), canonLabel);
+          writeFileSync(p, txt);
+        }
+        // 3) re-extract + gate; revert on regression
+        const r = spawnSync(process.execPath, [join(HERE, 'extract-symbols.mjs'), root], { encoding: 'utf8', maxBuffer: 1 << 28 });
+        if (r.status !== 0) { restore(); writeResult = { applied: false, reason: `re-extraction failed; reverted` }; code = 1; }
+        else {
+          const fresh = normalizeGraph(JSON.parse(r.stdout));
+          const post = structuralRegressions(graph, fresh);
+          if (post.newCycles.length || post.lostCallers.length) { restore(); writeResult = { applied: false, reason: 'post-edit gate regressed; reverted', post }; code = 1; }
+          else writeResult = { applied: true, filesTouched: touched, reExtractGate: { newCycles: post.newCycles, lostCallers: post.lostCallers, ok: true } };
+        }
+      } catch (e) { restore(); writeResult = { applied: false, reason: `error during write; reverted: ${e.message}` }; code = 1; }
+    }
+  }
+}
+
+const payload = { ...plan, write: writeResult };
+if (json) { emitJson(payload, code); } else {
+
+console.log(`codeweb codemod: merge ${ids.length} -> keep ${canonical}`);
+console.log(`  removes ${losers.length} copy(ies), rewires ${rewrites.length} caller(s), ~${locReclaimed} LOC, blast ${plan.blastRadius}`);
+console.log(`  projected gate: ${projectedGate.ok ? 'PASS' : 'BLOCK'}${projectedGate.ok ? '' : ` (${projectedGate.newCycles.length} new cycle, ${projectedGate.lostCallers.length} lost-caller)`}`);
+console.log('  deletions:'); for (const d of deletions) console.log(`    ${d.file}:${d.range[0]}-${d.range[1]}  (${d.id})`);
+console.log('  rewrites:'); for (const r of rewrites) console.log(`    ${r.file}:${r.line}  (${r.callerId})`);
+if (writeResult) console.log(`  write: ${writeResult.applied ? `APPLIED to ${writeResult.filesTouched.length} file(s)` : `NOT applied — ${writeResult.reason}`}`);
+else console.log('  (plan-only — pass --write to apply, gated + reversible)');
+finish(code);
+}

package/scripts/context-pack.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+// codeweb context-pack — blast-radius-scoped context for a symbol. Returns the target body, the
+// direct callers (the call sites that break if the contract changes — as CALL-SITE WINDOWS, a few
+// lines around each use, not whole function bodies), the direct callees (dependencies —
+// location-only to stay bounded), and the transitive impact set (ids only). Lets an agent edit with
+// a minimal window instead of grepping and reading whole files. Read-only, deterministic.
+//
+// The window default is the token budget made real: whole caller bodies blew a single "bounded"
+// pack past 300KB on a busy symbol (88 callers x full functions); the agent needs the call sites.
+// --full-bodies restores the old shape when a consumer genuinely wants every caller in full.
+//
+// Usage: node context-pack.mjs <graph.json> <symbol> [--window N] [--full-bodies] [--limit N] [--json]
+// Exit: 0 ok, 1 symbol not found, 2 usage/IO.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { normalizeGraph, buildIndex, resolveSymbol, callersOf, calleesOf, impactOf } from './lib/graph-ops.mjs';
+
+const USAGE = 'usage: context-pack.mjs <graph.json> <symbol> [--window N] [--full-bodies] [--limit N] [--json]   (or set CODEWEB_WS)';
+import { die, emitJson, finish, capList, checkStaleness, loadGraph, sourceReader } from './lib/cli.mjs';
+
+const argv = process.argv.slice(2);
+let json = false, windowN = 3, fullBodies = 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 === '--window') windowN = Math.max(0, parseInt(argv[++i], 10) || 3);
+  else if (t === '--full-bodies') fullBodies = true;
+  else if (t === '--limit') limit = Math.max(0, parseInt(argv[++i], 10) || 0);
+  else if (!t.startsWith('-')) pos.push(t);
+}
+let graphPath, symbol;
+if (pos.length >= 2) { graphPath = pos[0]; symbol = pos[1]; }
+else if (pos.length === 1 && process.env.CODEWEB_WS) { graphPath = `${process.env.CODEWEB_WS}/graph.json`; symbol = pos[0]; }
+else die(USAGE, 2);
+
+const { graph, abs } = loadGraph(graphPath, { usage: USAGE });
+
+const ids = resolveSymbol(graph, symbol);
+if (!ids.length) die(`symbol not found: ${symbol}`, 1);
+
+const index = buildIndex(graph);
+const callerIds = callersOf(index, ids);
+const calleeIds = calleesOf(index, ids);
+const blast = impactOf(index, ids);
+
+// CP-BODY-FIDELITY: sourceReader serves the exact source lines [line, line+loc-1] (one truth,
+// shared with find-similar + diff rename-matching).
+const reader = sourceReader(graph.meta?.root || null);
+const sourceAvailable = reader.available;
+const readLines = reader.linesOf;
+const bodyOf = reader.bodyOf;
+const view = (n, withBody) => {
+  const o = { id: n.id, label: n.label, kind: n.kind, file: n.file, line: n.line, loc: n.loc, domain: n.domain, exports: n.exports, signature: n.signature ?? null };
+  if (withBody) o.body = bodyOf(n);
+  return o;
+};
+// CALL-SITE WINDOWS: inside the caller's recorded span, every line that references the target label,
+// each with ±windowN lines of context. Windows overlapping-adjacent are merged. This is the part of
+// the caller an agent actually needs to update; the full body stays one --full-bodies away.
+const targetLabels = [...new Set(ids.map((id) => index.byId.get(id)?.label).filter(Boolean))];
+const labelRe = targetLabels.length ? new RegExp(`\\b(${targetLabels.map((l) => l.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')})\\b`) : null;
+const windowsOf = (n) => {
+  if (!sourceAvailable || !labelRe) return [];
+  const lines = readLines(n.file);
+  if (!lines) return [];
+  const start = n.line, end = Math.min(n.line + (n.loc || 1) - 1, lines.length);
+  const hits = [];
+  for (let ln = start; ln <= end; ln++) if (labelRe.test(lines[ln - 1] || '')) hits.push(ln);
+  const windows = [];
+  for (const h of hits.slice(0, 8)) { // a caller with >8 call sites: the first 8 windows tell the story
+    const s = Math.max(start, h - windowN), e = Math.min(end, h + windowN);
+    const last = windows[windows.length - 1];
+    if (last && s <= last.endLine + 1) { last.endLine = e; last.callLines.push(h); }
+    else windows.push({ startLine: s, endLine: e, callLines: [h] });
+  }
+  for (const w of windows) w.text = lines.slice(w.startLine - 1, w.endLine).join('\n');
+  return windows;
+};
+const callerView = (id) => {
+  const n = byId.get(id);
+  const o = view(n, fullBodies);
+  if (!fullBodies) o.windows = windowsOf(n);
+  return o;
+};
+const byId = index.byId;
+const cappedCallers = capList(callerIds, limit);
+const cappedCallees = capList(calleeIds, limit);
+const cappedBlast = capList(blast, limit != null ? Math.max(limit, 25) : null);
+const payload = {
+  symbol, matched: ids, sourceAvailable,
+  summary: `${symbol}: ${callerIds.length} caller(s), ${calleeIds.length} callee(s), blast radius ${blast.length}`,
+  mode: fullBodies ? 'full-bodies' : `call-site windows (±${windowN} lines)`,
+  target: ids.map((id) => view(byId.get(id), true)),
+  callers: cappedCallers.items.map(callerView),               // call sites that may need updating
+  callees: cappedCallees.items.map((id) => view(byId.get(id), false)),  // dependencies: location-only (bounded)
+  blastRadius: { count: blast.length, ids: cappedBlast.items }, // transitive impact: ids only
+};
+if (cappedCallers.truncated) payload.moreCallers = { remaining: cappedCallers.remaining };
+const staleInfo = checkStaleness(graph);
+if (staleInfo) { payload.stale = staleInfo; payload.summary += ` — graph is stale for ${staleInfo.count}+ file(s); run codeweb_refresh`; }
+if (cappedCallees.truncated) payload.moreCallees = { remaining: cappedCallees.remaining };
+
+if (json) { emitJson(payload); } else {
+
+console.log(`context-pack: ${symbol} -> ${ids.join(', ')}`);
+console.log(`source: ${sourceAvailable ? `available — ${payload.mode}` : 'absent — bodies null'}`);
+for (const t of payload.target) {
+  console.log(`\n# target ${t.id}  (${t.file}:${t.line}, ${t.loc} loc, ${t.domain})`);
+  if (t.body) console.log(t.body);
+}
+console.log(`\ncallers (${payload.callers.length}) — call sites that may need updating:`);
+for (const c of payload.callers) console.log(`  ${c.id}  (${c.file}:${c.line})`);
+console.log(`callees (${payload.callees.length}) — dependencies:`);
+for (const c of payload.callees) console.log(`  ${c.id}`);
+console.log(`blast radius: ${payload.blastRadius.count} transitive caller(s)`);
+finish();
+}

package/scripts/deadcode.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// codeweb deadcode (F10) — turn the orphans candidate list into a confidence-tiered action plan.
+// Partitions orphans (no production caller, not exported) into `safe` (no test edge, not defined in
+// a test file, not an entrypoint-like name — high-confidence dead) and `review` (referenced by a
+// test, defined in a test file (helper/mock/case registration), or an entrypoint-like name a
+// framework/CLI may invoke without a code edge). Honestly surfaces the
+// orphans caveat (extraction drops ambiguous call edges, so cross-check). Read-only, advisory,
+// deterministic. Built on ./lib/graph-ops.mjs (uses the SAME orphans + testIn as query.mjs — one truth).
+//
+// Usage: node deadcode.mjs <graph.json> [--json]   (or set CODEWEB_WS)
+// Exit: 0 (advisory), 2 usage/IO.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { normalizeGraph, buildIndex, orphans, isTestFile } from './lib/graph-ops.mjs';
+import { fingerprint, loadAnnotations } from './lib/annotations.mjs'; // F7: false-positive suppression memory
+
+// Entrypoint-like names that may be invoked by a framework / CLI / test runner rather than via a
+// code edge — so an uncalled one is "review", not "safe to delete". (Mirrored by the test oracle.)
+const ENTRYPOINTS = new Set(['main', 'default', 'index', 'setup', 'teardown', 'init']);
+// A/B lever (mirrors CODEWEB_LEGACY_FALLBACK / CODEWEB_HUB_INDEG): restore the pre-fix behavior where
+// a function DEFINED IN a test file falls through to `safe`. Defaults OFF (shipped: test-file -> review).
+// The effectiveness study flips this on to prove the H13 fix is load-bearing (safe-tier precision drops).
+const DEADCODE_LEGACY = process.env.CODEWEB_DEADCODE_LEGACY === '1';
+const USAGE = 'usage: deadcode.mjs <graph.json> [--json]   (or set CODEWEB_WS)';
+import { die, emitJson, finish, capList, loadGraph } from './lib/cli.mjs';
+
+const argv = process.argv.slice(2);
+let json = false, showSuppressed = false, annDir = null, limit = null; const pos = [];
+for (let i = 0; i < argv.length; i++) {
+  const t = argv[i];
+  if (t === '--json') json = true;
+  else if (t === '--show-suppressed') showSuppressed = true;
+  else if (t === '--annotations') annDir = argv[++i];
+  else if (t === '--limit') limit = Math.max(0, parseInt(argv[++i], 10) || 0);
+  else if (!t.startsWith('-')) pos.push(t);
+}
+const { graph, abs } = loadGraph(pos[0], { usage: USAGE });
+
+const index = buildIndex(graph);
+const CAVEAT = 'extraction drops ambiguous call edges (precision over recall), so a genuinely-called symbol can surface here — cross-check before deleting';
+
+const safe = [], review = [];
+for (const o of orphans(graph, index)) {           // orphans = no call|import|inherit incoming, not exported
+  const node = index.byId.get(o.id);
+  const label = node?.label || o.id;
+  const testers = index.testIn.get(o.id)?.size || 0;
+  const file = node?.file || o.file;
+  const loc = node?.loc || 0; // deleting this orphan reclaims its span — campaign's delete-ROI signal
+  if (testers > 0) review.push({ ...o, loc, reason: `referenced only by ${testers} test(s) — the test may be its only user; remove the test too, or it is genuinely used` });
+  else if (!DEADCODE_LEGACY && isTestFile(file)) review.push({ ...o, loc, reason: `defined in a test file '${file}' — a test runner may invoke it (helper, mock, or case registration) without a code edge, so deleting it can break tests` });
+  else if (ENTRYPOINTS.has(label)) review.push({ ...o, loc, reason: `entrypoint-like name '${label}' — may be invoked by a framework/CLI/test runner, not via a code edge` });
+  else safe.push({ ...o, loc, reason: 'no production caller, not exported, no test edge, not in a test file — high-confidence dead' }); // the shared caveat lives once in payload.note
+}
+
+// F7: every finding carries a stable fingerprint (kind 'orphan' + its id). A '.codeweb/annotations.json'
+// false-positive suppression hides a safe finding by default (so a confirmed not-dead symbol stops
+// resurfacing) and is COUNTED; --show-suppressed reveals them. Suppression keys on identity, so if the
+// symbol id changes the fingerprint changes and it is NOT silently hidden.
+for (const o of safe) o.fingerprint = fingerprint({ kind: 'orphan', nodes: [o.id] });
+for (const o of review) o.fingerprint = fingerprint({ kind: 'orphan', nodes: [o.id] });
+const dir = annDir || join(dirname(abs), '.codeweb');
+const killed = new Set(loadAnnotations(dir).suppressions.filter((s) => s.verdict === 'false-positive').map((s) => s.fingerprint));
+const suppressed = safe.filter((o) => killed.has(o.fingerprint));
+const visibleSafe = showSuppressed ? safe : safe.filter((o) => !killed.has(o.fingerprint));
+
+// Budget: totals stay TRUE; the lists cap at --limit each, biggest spans first (the deletes worth
+// doing first), with an explicit remainder — never a silent cut.
+const byLocDesc = (a, b) => (b.loc || 0) - (a.loc || 0) || (a.id < b.id ? -1 : 1);
+const capSafe = capList(limit != null ? visibleSafe.slice().sort(byLocDesc) : visibleSafe, limit);
+const capReview = capList(limit != null ? review.slice().sort(byLocDesc) : review, limit);
+const payload = {
+  target: graph.meta?.target || 'target',
+  summary: `${visibleSafe.length + review.length} orphan(s): ${visibleSafe.length} safe to delete, ${review.length} need review${suppressed.length ? `, ${suppressed.length} suppressed` : ''}`,
+  totals: { orphans: visibleSafe.length + review.length, safe: visibleSafe.length, review: review.length, suppressed: suppressed.length },
+  note: CAVEAT,
+  safe: capSafe.items, review: capReview.items, suppressed,
+};
+if (capSafe.truncated) payload.moreSafe = { remaining: capSafe.remaining };
+if (capReview.truncated) payload.moreReview = { remaining: capReview.remaining };
+
+if (json) { emitJson(payload); } else {
+
+const t = payload.totals;
+console.log(`codeweb deadcode: ${payload.target} — ${t.orphans} orphan(s): ${t.safe} safe, ${t.review} review${t.suppressed ? `, ${t.suppressed} suppressed` : ''}`);
+console.log(`\nsafe to delete (no caller, not exported, no test):`);
+for (const o of payload.safe) console.log(`  ${o.id}  [${o.domain}]  (${o.loc} loc)`);
+if (payload.moreSafe) console.log(`  … +${payload.moreSafe.remaining} more`);
+if (!safe.length) console.log('  (none)');
+console.log(`\nreview first (tests reference it, or entrypoint-like):`);
+for (const o of payload.review) console.log(`  ${o.id}  — ${o.reason}`);
+if (payload.moreReview) console.log(`  … +${payload.moreReview.remaining} more`);
+if (!review.length) console.log('  (none)');
+console.log(`\nnote: ${CAVEAT}.`);
+finish();
+}

package/scripts/explain.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// codeweb explain — ONE bounded card answering "tell me about X before I touch it": identity,
+// role, contract (signature/complexity), who depends on it (fan-in/out, tests, blast radius),
+// the top callers/callees by fan-in, and any duplication/pattern findings it belongs to.
+// The question agents ask most, previously 3-4 separate calls. Read-only, deterministic, small
+// by construction (~1KB) — counts + top-5s, never exhaustive lists (those stay one tool away).
+//
+// Usage: node explain.mjs <graph.json> <symbol> [--json]   (or set CODEWEB_WS and pass <symbol>)
+// Exit: 0 ok, 1 symbol not found, 2 usage/IO.
+
+import { buildIndex, resolveSymbol, callersOf, calleesOf, testersOf, impactOf, fanInOf } from './lib/graph-ops.mjs';
+import { callerReliance, relianceLine } from './lib/reliance.mjs';
+
+const USAGE = 'usage: explain.mjs <graph.json> <symbol> [--json]   (or set CODEWEB_WS)';
+import { die, emitJson, finish, loadGraph, checkStaleness, sourceReader } from './lib/cli.mjs';
+
+const argv = process.argv.slice(2);
+let json = false; const pos = [];
+for (const t of argv) { if (t === '--json') json = true; else if (!t.startsWith('-')) pos.push(t); }
+let graphArg = null, symbol = null;
+if (pos.length >= 2) { graphArg = pos[0]; symbol = pos[1]; }
+else if (pos.length === 1) { symbol = pos[0]; }
+if (!symbol) die(USAGE, 2);
+const { graph } = loadGraph(graphArg, { usage: USAGE });
+
+const ids = resolveSymbol(graph, symbol);
+if (!ids.length) { if (json) emitJson({ symbol, found: false }, 1); else die(`symbol not found: ${symbol}`, 1); }
+else {
+  const index = buildIndex(graph);
+  const reader = sourceReader(graph.meta && graph.meta.root);
+  const topBy = (list, n) => list.slice().sort((a, b) => fanInOf(index, b) - fanInOf(index, a) || (a < b ? -1 : 1)).slice(0, n);
+
+  const cards = ids.map((id) => {
+    const n = index.byId.get(id);
+    const callers = callersOf(index, [id]);
+    const callees = calleesOf(index, [id]);
+    const tests = testersOf(index, [id]);
+    const blast = impactOf(index, [id]);
+    const blastDomains = [...new Set(blast.map((x) => index.byId.get(x)?.domain || 'unassigned'))];
+    const findings = (graph.overlaps || []).filter((o) => (o.nodes || []).includes(id))
+      .map((o) => ({ id: o.id, kind: o.kind, title: o.title, confidence: o.confidence }));
+    const reliance = callerReliance(graph, index, n, reader);
+    // confidence calibration: say when "N callers" is NOT the whole story
+    const caveat = n.pub
+      ? 'public API (reachable from a package entrypoint) — external callers likely; renames are breaking'
+      : (callers.length === 0 && n.exports)
+        ? '0 in-repo callers but exported — external use possible'
+        : (callers.length === 0 && graph.meta?.dynamic)
+          ? `repo routes calls dynamically in ${graph.meta.dynamic.files} file(s) — absence of callers is weaker evidence`
+          : null;
+    return {
+      ...(n.pub ? { publicApi: true } : {}),
+      ...(caveat ? { caveat } : {}),
+      ...(reliance ? { callersRelyOn: reliance } : {}),
+      id, label: n.label, kind: n.kind, role: n.role || 'product', domain: n.domain,
+      at: `${n.file}:${n.line}`, loc: n.loc, exports: n.exports,
+      signature: n.signature ?? null,
+      ...(n.complexity != null ? { complexity: n.complexity, maxDepth: n.maxDepth } : {}),
+      dependents: { callers: callers.length, tests: tests.length, blastRadius: blast.length, blastDomains: blastDomains.length },
+      topCallers: topBy(callers, 5),
+      topCallees: topBy(callees, 5),
+      tests: tests.slice(0, 3),
+      findings,
+      summary: `${n.kind} ${n.label} (${n.role || 'product'}, ${n.domain}) — ${callers.length} caller(s), ${tests.length} test(s), blast ${blast.length} across ${blastDomains.length} domain(s)${findings.length ? `; in ${findings.length} finding(s)` : ''}${relianceLine(reliance) ? `; ${relianceLine(reliance)}` : ''}${caveat ? `; ⚠ ${caveat}` : ''}`,
+    };
+  });
+  const payload = { symbol, matched: ids, cards, summary: cards.map((c) => c.summary).join(' | ') };
+  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 {
+    for (const c of cards) {
+      console.log(`# ${c.id}`);
+      console.log(`  ${c.summary}`);
+      console.log(`  at ${c.at} · ${c.loc} loc${c.exports ? ' · exported' : ''}${c.signature ? ` · (${(c.signature.params || []).join(', ')})${c.signature.returns ? ' -> ' + c.signature.returns : ''}` : ''}${c.complexity != null ? ` · cx ${c.complexity}` : ''}`);
+      if (c.caveat) console.log(`  ⚠ ${c.caveat}`);
+      if (c.callersRelyOn) console.log(`  callers rely on: ${relianceLine(c.callersRelyOn)}`);
+      if (c.topCallers.length) console.log(`  top callers: ${c.topCallers.join(', ')}`);
+      if (c.topCallees.length) console.log(`  calls: ${c.topCallees.join(', ')}`);
+      if (c.tests.length) console.log(`  tests: ${c.tests.join(', ')}`);
+      for (const f of c.findings) console.log(`  finding: [${f.kind}/${f.confidence}] ${f.title}`);
+    }
+    if (payload.stale) console.log(`  ⚠ graph stale for ${payload.stale.count}+ file(s) — run codeweb_refresh`);
+    finish();
+  }
+}