@ghostlygawd/codeweb 0.9.0

package/scripts/lib/graph-ops.mjs

@@ -0,0 +1,319 @@
+// codeweb shared graph primitives — pure functions over a graph.json object (see graph-schema.md).
+// Imported by scripts/query.mjs and scripts/diff.mjs so the call/cycle/orphan logic lives ONCE
+// (codeweb dogfooding its own anti-duplication mission). No I/O, no process.exit — callers own
+// those. Deterministic: every returned list is sorted.
+
+const asArray = (x) => (Array.isArray(x) ? x : []);
+const byIdLt = (a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+
+// Test-file predicate (shared by find-similar, the extractor's test-edge classification, and the
+// dead-code workflow — one truth). Matches `*.test.*`, `*.spec.*`, `*_test.*`, or a path segment
+// `tests/` | `test/` | `__tests__/`. Forward-slashed relative paths.
+// Canonical edge identity (from+to+kind) — was re-implemented in break-cycles/diff/shards (Spec E dogfood).
+export const edgeKey = (e) => [e.from, e.to, e.kind].join(String.fromCharCode(0)); // NUL-separated: ids can contain spaces
+
+export const isTestFile = (file) =>
+  /(?:^|\/)(?:tests?|__tests__|spec)\//.test(file || '') || /(?:\.test\.|\.spec\.|_test\.|_spec\.)/.test(file || '') ||
+  /(?:^|\/)src\/test\//.test(file || '') ||                       // Maven/Gradle convention
+  /(?:Tests?|Spec)\.(?:java|cs|php|swift|kt)$/.test(file || '');  // FooTest.java / FooTests.swift / FooTest.php …
+
+// Code ROLE by path — product code vs the supporting cast (one truth: the extractor stamps it on
+// every node; normalizeGraph back-fills older graphs). Rankings and default report views scope to
+// `product` so monorepo fixture noise can't dominate recommendations.
+export function roleOf(file) {
+  const f = file || '';
+  if (isTestFile(f)) return 'test';
+  if (/(^|\/)(fixtures?|__fixtures__|__mocks__|mocks?)\//.test(f)) return 'fixture';
+  if (/(^|\/)(examples?|samples?|demos?|playgrounds?|playground|sandbox|e2e)\//.test(f)) return 'example';
+  if (/(^|\/)(benchmarks?|bench|perf)\//.test(f)) return 'bench';
+  if (/\.(min|bundle)\.[cm]?js$/.test(f) || /(^|\/)(generated|__generated__)\//.test(f)) return 'generated';
+  return 'product';
+}
+
+// Spec E: per-repo role OVERRIDES (codeweb.rules.json `roles: [{glob, role}]`) — heuristics can't
+// know a repo's private layout ("docs/ here is generated site output"). Compile the config into a
+// matcher; first matching glob wins; an unknown role THROWS (extraction fails loudly, exit 2).
+export const VALID_ROLES = new Set(['product', 'test', 'fixture', 'example', 'bench', 'generated', 'vendored']);
+
+function globToRegex(glob) {
+  let re = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') { re += glob[i + 2] === '/' ? '(?:.*/)?' : '.*'; i += glob[i + 2] === '/' ? 2 : 1; }
+      else re += '[^/]*';
+    } else if (c === '?') re += '[^/]';
+    else re += /[.+^${}()|[\]\\]/.test(c) ? '\\' + c : c;
+  }
+  return new RegExp('^' + re + '$');
+}
+
+/** Compile `roles` config into (relPath) => role|null. Throws on an invalid entry. */
+export function compileRoleOverrides(roles) {
+  if (!roles) return () => null;
+  if (!Array.isArray(roles)) throw new Error('codeweb.rules.json: `roles` must be an array of {glob, role}');
+  const compiled = roles.map((r, i) => {
+    if (!r || typeof r.glob !== 'string' || typeof r.role !== 'string') throw new Error(`codeweb.rules.json roles[${i}]: need {glob, role}`);
+    if (!VALID_ROLES.has(r.role)) throw new Error(`codeweb.rules.json roles[${i}] ("${r.glob}"): unknown role "${r.role}" (valid: ${[...VALID_ROLES].join('|')})`);
+    return { re: globToRegex(r.glob), role: r.role };
+  });
+  return (relPath) => { for (const c of compiled) if (c.re.test(relPath)) return c.role; return null; };
+}
+
+// Fill the same defaults build-report.mjs applies, so every consumer sees a well-formed graph.
+export function normalizeGraph(graph) {
+  const g = graph || {};
+  g.meta = g.meta || {};
+  g.nodes = asArray(g.nodes);
+  g.edges = asArray(g.edges);
+  g.domains = asArray(g.domains);
+  g.overlaps = asArray(g.overlaps);
+  for (const n of g.nodes) {
+    if (n.domain == null || n.domain === '') n.domain = 'unassigned';
+    if (typeof n.exports !== 'boolean') n.exports = false;
+    if (n.file == null) n.file = '';
+    if (!n.role) n.role = roleOf(n.file); // pre-v7 graphs: derive
+  }
+  return g;
+}
+
+// Adjacency indexes. callIn/callOut are CALL edges only; hasIncoming tracks any call|import in-edge.
+export function buildIndex(graph) {
+  const byId = new Map(graph.nodes.map((n) => [n.id, n]));
+  const callIn = new Map();
+  const callOut = new Map();
+  const inheritIn = new Map(); // reverse inherit: base -> {subclasses}, for impact reachability
+  const testIn = new Map();    // F4: reverse `test` edges: prod symbol -> {test nodes exercising it}
+  const importIn = new Map();  // reverse `import` edges: symbol -> {symbols that import it}
+  const refIn = new Map();     // reverse `ref` edges: class -> {symbols using it via instanceof / static method}
+  const hasIncoming = new Set();
+  for (const e of graph.edges) {
+    if (e.kind === 'call') {
+      if (!callIn.has(e.to)) callIn.set(e.to, new Set());
+      callIn.get(e.to).add(e.from);
+      if (!callOut.has(e.from)) callOut.set(e.from, new Set());
+      callOut.get(e.from).add(e.to);
+    }
+    if (e.kind === 'inherit') {
+      if (!inheritIn.has(e.to)) inheritIn.set(e.to, new Set());
+      inheritIn.get(e.to).add(e.from);
+    }
+    if (e.kind === 'test') {
+      if (!testIn.has(e.to)) testIn.set(e.to, new Set());
+      testIn.get(e.to).add(e.from);
+    }
+    if (e.kind === 'import') {
+      if (!importIn.has(e.to)) importIn.set(e.to, new Set());
+      importIn.get(e.to).add(e.from);
+    }
+    if (e.kind === 'ref') {
+      if (!refIn.has(e.to)) refIn.set(e.to, new Set());
+      refIn.get(e.to).add(e.from);
+    }
+    // NOTE: `test` is intentionally EXCLUDED from hasIncoming — a symbol referenced only by tests is
+    // still a production orphan (the signal F10 consumes). Production callers also exclude tests.
+    if (e.kind === 'call' || e.kind === 'import' || e.kind === 'inherit' || e.kind === 'ref') hasIncoming.add(e.to);
+  }
+  return { byId, callIn, callOut, inheritIn, testIn, importIn, refIn, hasIncoming };
+}
+
+// Resolve a symbol to node ids: exact id wins; else every node whose label matches (sorted).
+export function resolveSymbol(graph, sym) {
+  if (graph.nodes.some((n) => n.id === sym)) return [sym];
+  return graph.nodes.filter((n) => n.label === sym).map((n) => n.id).sort();
+}
+
+const unionSorted = (ids, adj) => {
+  const out = new Set();
+  for (const id of ids) for (const x of (adj.get(id) || [])) out.add(x);
+  return [...out].sort();
+};
+// Pick the canonical survivor of a merge cluster: most callers (least disruptive to keep), tie ->
+// smallest loc, tie -> lexicographically smallest id. Deterministic. Shared by optimize + codemod.
+export function chooseCanonical(index, ids) {
+  return ids.slice().sort((a, b) => {
+    const ca = index.callIn.get(a)?.size || 0, cb = index.callIn.get(b)?.size || 0;
+    if (cb !== ca) return cb - ca;
+    const la = index.byId.get(a)?.loc || 0, lb = index.byId.get(b)?.loc || 0;
+    if (la !== lb) return la - lb;
+    return a < b ? -1 : a > b ? 1 : 0;
+  })[0];
+}
+
+export const callersOf = (index, ids) => unionSorted(ids, index.callIn);
+export const calleesOf = (index, ids) => unionSorted(ids, index.callOut);
+export const testersOf = (index, ids) => unionSorted(ids, index.testIn); // F4: tests exercising a symbol
+export const importersOf = (index, ids) => unionSorted(ids, index.importIn); // symbols that import a symbol
+export const refsOf = (index, ids) => unionSorted(ids, index.refIn); // symbols using a class via instanceof / static method
+
+// Every distinct symbol that DEPENDS on a target, across all in-edge kinds (call ∪ import ∪ inherit ∪
+// test ∪ ref) — the "who would I have to touch if I changed this?" set. Unlike callersOf (call-only),
+// this surfaces cross-file importers, subclasses, and instanceof/static-method users an agent must
+// update on a refactor. Deterministic.
+export const dependentsOf = (index, ids) => {
+  const out = new Set();
+  for (const adj of [index.callIn, index.importIn, index.inheritIn, index.testIn, index.refIn])
+    for (const id of ids) for (const x of (adj.get(id) || [])) out.add(x);
+  return [...out].sort();
+};
+
+// Fan-in of one node: reverse call edges, optionally + reverse imports (the "how depended-on is
+// this?" number every ranking uses — one definition, so consumers can't drift).
+export const fanInOf = (index, id, withImports = false) =>
+  (index.callIn.get(id)?.size || 0) + (withImports ? (index.importIn.get(id)?.size || 0) : 0);
+
+// Transitive reverse-call closure (blast radius) from all seeds, excluding the seeds themselves.
+export function impactOf(index, seedIds) {
+  const seeds = new Set(seedIds);
+  const visited = new Set(seedIds);
+  const queue = [...seedIds];
+  while (queue.length) {
+    const cur = queue.shift();
+    // reverse-reachability over callers AND subclasses: changing a node affects what calls it and
+    // what inherits from it.
+    const upstream = [...(index.callIn.get(cur) || []), ...(index.inheritIn?.get(cur) || [])];
+    for (const dep of upstream) {
+      if (!visited.has(dep)) { visited.add(dep); queue.push(dep); }
+    }
+  }
+  return [...visited].filter((id) => !seeds.has(id)).sort();
+}
+
+// F5: map changed line-ranges to the symbols they touch, plus blast radius. hunks =
+// [{ file, ranges:[[start,end],...] }]; ranges null/empty = the whole file. A node is "changed"
+// iff its recorded span [line, line+loc-1] intersects a changed range — best-effort, inheriting
+// bodyEnd's clamp limits (can under-select on truncated bodies; documented in review.mjs).
+export function reviewImpact(graph, hunks) {
+  const index = buildIndex(graph);
+  const byFile = new Map();
+  for (const h of hunks) {
+    if (!byFile.has(h.file)) byFile.set(h.file, []);
+    if (h.ranges == null || h.ranges.length === 0) byFile.get(h.file).push(null);
+    else for (const r of h.ranges) byFile.get(h.file).push(r);
+  }
+  const changed = [];
+  for (const n of graph.nodes) {
+    const rs = byFile.get(n.file);
+    if (!rs) continue;
+    const start = n.line, end = n.line + (n.loc || 1) - 1;
+    if (rs.some((r) => r == null || !(end < r[0] || start > r[1]))) changed.push(n.id);
+  }
+  changed.sort();
+  const blast = impactOf(index, changed);
+  const domainsTouched = [...new Set(changed.map((id) => index.byId.get(id)?.domain || 'unassigned'))].sort();
+  const callerCounts = changed.map((id) => ({ id, callers: index.callIn.get(id)?.size || 0 })).sort((a, b) => b.callers - a.callers || (a.id < b.id ? -1 : 1));
+  return { changedSymbols: changed, blastRadius: { count: blast.length, ids: blast }, domainsTouched, callerCounts };
+}
+
+// File-level dependency cycles: strongly-connected components of size >= 2 in the file graph built
+// from call+import edges. ITERATIVE Tarjan (explicit work stack) so deep graphs can't overflow the
+// JS call stack. Deterministic: neighbors and the final list are sorted.
+export function fileCycles(graph) {
+  const fileOf = new Map(graph.nodes.map((n) => [n.id, n.file]));
+  const adj = new Map();
+  const files = new Set();
+  for (const e of graph.edges) {
+    if (e.kind !== 'call' && e.kind !== 'import' && e.kind !== 'inherit' && e.kind !== 'ref') continue;
+    const f = fileOf.get(e.from), t = fileOf.get(e.to);
+    if (!f || !t || f === t) continue;
+    files.add(f); files.add(t);
+    if (!adj.has(f)) adj.set(f, new Set());
+    adj.get(f).add(t);
+  }
+  const neigh = (v) => [...(adj.get(v) || [])].sort();
+  const idx = new Map(), low = new Map(), onStack = new Set(), sccStack = [];
+  const out = [];
+  let counter = 0;
+  for (const root of [...files].sort()) {
+    if (idx.has(root)) continue;
+    idx.set(root, counter); low.set(root, counter); counter++; sccStack.push(root); onStack.add(root);
+    const work = [{ v: root, ns: neigh(root), i: 0 }];
+    while (work.length) {
+      const frame = work[work.length - 1];
+      if (frame.i < frame.ns.length) {
+        const w = frame.ns[frame.i++];
+        if (!idx.has(w)) {
+          idx.set(w, counter); low.set(w, counter); counter++; sccStack.push(w); onStack.add(w);
+          work.push({ v: w, ns: neigh(w), i: 0 });
+        } else if (onStack.has(w)) {
+          low.set(frame.v, Math.min(low.get(frame.v), idx.get(w)));
+        }
+      } else {
+        if (low.get(frame.v) === idx.get(frame.v)) {
+          const comp = []; let w;
+          do { w = sccStack.pop(); onStack.delete(w); comp.push(w); } while (w !== frame.v);
+          if (comp.length >= 2) out.push(comp.sort());
+        }
+        work.pop();
+        if (work.length) {
+          const parent = work[work.length - 1].v;
+          low.set(parent, Math.min(low.get(parent), low.get(frame.v)));
+        }
+      }
+    }
+  }
+  return out.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+}
+
+// Dead-code candidates: no incoming call|import edge AND not exported. Sorted by id.
+export function orphans(graph, index) {
+  return graph.nodes
+    .filter((n) => n.kind !== 'module' && !index.hasIncoming.has(n.id) && !n.exports)
+    .map((n) => ({ id: n.id, file: n.file, domain: n.domain }))
+    .sort(byIdLt);
+}
+
+// Edges-only structural regressions between two snapshots — the fast subset the post-edit hook
+// checks (re-extraction gives nodes+edges, not domains/overlaps): a file-level cycle present in
+// `after` but not `before`, and a symbol that EXISTS in both but lost ALL its callers (deleting a
+// symbol entirely is not a regression — only a surviving-but-orphaned one is). Duplication and
+// coupling deltas need the full pipeline; that stays diff.mjs.
+export function structuralRegressions(before, after) {
+  const b = normalizeGraph(before), a = normalizeGraph(after);
+  const cycleKey = (c) => c.join('|');
+  const beforeCycles = new Set(fileCycles(b).map(cycleKey));
+  const newCycles = fileCycles(a).filter((c) => !beforeCycles.has(cycleKey(c)));
+  const bi = buildIndex(b), ai = buildIndex(a);
+  const afterIds = new Set(a.nodes.map((n) => n.id));
+  const lostCallers = [];
+  for (const [id, callers] of bi.callIn) {
+    if (callers.size && afterIds.has(id) && !(ai.callIn.get(id)?.size)) lostCallers.push(id);
+  }
+  return { newCycles, lostCallers: lostCallers.sort() };
+}
+
+// Pure structural edit simulation — models delete / merge / move on a DEEP COPY of the graph and
+// never mutates its argument, so simulate-edit and optimize build the hypothetical graph through
+// ONE path (codeweb dogfooding "logic lives once"). Returns a normalized graph; overlaps are
+// dropped (they'd be stale — recompute via the pipeline if needed).
+//   op = { kind:'delete', ids:[...] } | { kind:'merge', ids:[...], into } | { kind:'move', id, to }
+export function applyEdit(graph, op) {
+  const g = normalizeGraph(structuredClone(graph)); // clone first: normalizeGraph mutates, the input must not change
+  const base = { meta: g.meta, domains: g.domains, overlaps: [] };
+  if (op.kind === 'delete') {
+    const drop = new Set(op.ids);
+    return normalizeGraph({ ...base,
+      nodes: g.nodes.filter((n) => !drop.has(n.id)),
+      edges: g.edges.filter((e) => !drop.has(e.from) && !drop.has(e.to)) });
+  }
+  if (op.kind === 'move') {
+    return normalizeGraph({ ...base,
+      nodes: g.nodes.map((n) => (n.id === op.id ? { ...n, file: op.to } : n)),
+      edges: g.edges });
+  }
+  if (op.kind === 'merge') {
+    const copies = new Set(op.ids);
+    const map = (id) => (copies.has(id) ? op.into : id);
+    const nodes = g.nodes.filter((n) => !(copies.has(n.id) && n.id !== op.into));
+    const seen = new Set(); const edges = [];
+    for (const e of g.edges) {
+      const from = map(e.from), to = map(e.to);
+      if (from === to) continue;               // self-loop (incl. merged-into-itself) -> dropped
+      const k = `${from} ${to} ${e.kind}`;
+      if (seen.has(k)) continue; seen.add(k);   // de-dup redirected edges
+      edges.push({ from, to, kind: e.kind });
+    }
+    return normalizeGraph({ ...base, nodes, edges });
+  }
+  throw new Error(`applyEdit: unknown op kind '${op && op.kind}'`);
+}

package/scripts/lib/hotspots.mjs

@@ -0,0 +1,34 @@
+// codeweb hotspot scoring (F4) — rank symbols by refactoring priority: complexity x fan-in x churn
+// (the Tornhill model). "Where do I start" in a huge repo. The formula lives here so hotspots.mjs and
+// its tests share one truth (mirrors lib/risk.mjs). Pure.
+//
+// score = Σ wᵢ · normᵢ, normᵢ = componentᵢ / graph-max(componentᵢ) (0 when the max is 0). Weights are
+// non-negative and sum to 1, so score ∈ [0,1] and is monotonic non-decreasing in each component for
+// fixed maxes (HOT-DOMINANCE).
+
+import { buildIndex } from './graph-ops.mjs';
+
+export const HOTSPOT_WEIGHTS = { complexity: 0.5, fanIn: 0.3, churn: 0.2 };
+
+export function hotspotScore(components, maxes) {
+  let s = 0;
+  for (const k of Object.keys(HOTSPOT_WEIGHTS)) {
+    const m = maxes[k] || 0;
+    s += HOTSPOT_WEIGHTS[k] * (m > 0 ? (components[k] || 0) / m : 0);
+  }
+  return s;
+}
+
+// Rank function/method nodes (the ones carrying complexity) by hotspot score. churn: { <relpath>: count }.
+export function rankHotspots(graph, { churn = {} } = {}) {
+  const index = buildIndex(graph);
+  const comps = graph.nodes
+    .filter((n) => n.kind === 'function' || n.kind === 'method')
+    .map((n) => ({ id: n.id, file: n.file, domain: n.domain, complexity: n.complexity || 0, fanIn: index.callIn.get(n.id)?.size || 0, churn: churn[n.file] || 0 }));
+  const maxes = { complexity: 0, fanIn: 0, churn: 0 };
+  for (const c of comps) for (const k of Object.keys(maxes)) maxes[k] = Math.max(maxes[k], c[k]);
+  const ranked = comps
+    .map((c) => ({ id: c.id, file: c.file, domain: c.domain, score: hotspotScore(c, maxes), components: { complexity: c.complexity, fanIn: c.fanIn, churn: c.churn } }))
+    .sort((a, b) => b.score - a.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  return { weights: HOTSPOT_WEIGHTS, maxes, count: ranked.length, ranked };
+}

package/scripts/lib/query-core.mjs

@@ -0,0 +1,85 @@
+// codeweb query core — the payload assembly behind query.mjs, extracted so the MCP server can
+// answer structural queries IN-PROCESS against a cached parsed graph (sub-ms after the first call)
+// while the CLI keeps shipping the exact same payloads (one truth, two transports).
+// Pure over (graph, index): no I/O, no process, no exit codes — callers own those.
+
+import { buildIndex, resolveSymbol, callersOf, calleesOf, testersOf, importersOf, refsOf, dependentsOf, impactOf, fileCycles, orphans } from './graph-ops.mjs';
+import { capList } from './cli.mjs';
+
+// Budgeted list cap: `count` stays the TRUE total, `more` describes the remainder (absent when
+// nothing was cut).
+function budget(payload, field, limit, offset) {
+  if (limit == null && !offset) return payload;
+  const c = capList(payload[field], limit, offset);
+  payload[field] = c.items;
+  if (c.remaining > 0) payload.more = { remaining: c.remaining, nextOffset: c.offset + c.items.length };
+  return payload;
+}
+
+// Confidence calibration for empty dependents/callers answers: "0 results" must not sound equally
+// sure for a public-API symbol (external callers invisible by construction), an exported one, or a
+// symbol in a repo that routes calls dynamically. Returns the caveat string or null.
+function zeroCallerCaveat(graph, index, matched) {
+  const nodes = matched.map((id) => index.byId.get(id)).filter(Boolean);
+  if (nodes.some((n) => n.pub)) return 'public API (reachable from a package entrypoint) — external callers likely';
+  if (nodes.some((n) => n.exports)) return 'exported — external use possible';
+  if (graph.meta?.dynamic) return `repo routes calls dynamically in ${graph.meta.dynamic.files} file(s) — absence of callers is weaker evidence`;
+  return null;
+}
+
+/**
+ * Run one structural query. opts: { query, symbol, limit, offset }.
+ * Returns { payload, code } — code 1 = symbol not found (payload carries found:false).
+ */
+export function runQuery(graph, index, opts) {
+  const { query, symbol, limit = null, offset = 0 } = opts;
+  index = index || buildIndex(graph);
+  let payload, code = 0;
+  if (query === 'callers' || query === 'callees' || query === 'tests') {
+    const matched = resolveSymbol(graph, symbol);
+    if (!matched.length) { payload = { query, symbol, found: false }; code = 1; }
+    else {
+      const results = query === 'callers' ? callersOf(index, matched) : query === 'callees' ? calleesOf(index, matched) : testersOf(index, matched);
+      payload = budget({ query, symbol, summary: `${results.length} ${query === 'tests' ? 'test(s) exercise' : query + ' of'} ${symbol}`, matched, results, count: results.length }, 'results', limit, offset);
+      if (query === 'callers' && !results.length) {
+        const caveat = zeroCallerCaveat(graph, index, matched);
+        if (caveat) { payload.caveat = caveat; payload.summary += ` — ⚠ ${caveat}`; }
+      }
+    }
+  } else if (query === 'dependents') {
+    const matched = resolveSymbol(graph, symbol);
+    if (!matched.length) { payload = { query: 'dependents', symbol, found: false }; code = 1; }
+    else {
+      const results = dependentsOf(index, matched);
+      const inheritIn = [...new Set(matched.flatMap((id) => [...(index.inheritIn.get(id) || [])]))].sort();
+      const byKind = { call: callersOf(index, matched), import: importersOf(index, matched), inherit: inheritIn, test: testersOf(index, matched), ref: refsOf(index, matched) };
+      const kindCounts = Object.fromEntries(Object.entries(byKind).map(([k, v]) => [k, v.length]));
+      // under a budget, byKind collapses to counts (the full per-kind lists are the bulk of the payload)
+      payload = { query: 'dependents', symbol, summary: `${results.length} dependent(s) of ${symbol} (${Object.entries(kindCounts).map(([k, v]) => `${k} ${v}`).join(', ')})`, matched, results, byKind: limit != null ? kindCounts : byKind, count: results.length };
+      budget(payload, 'results', limit, offset);
+      if (!results.length) {
+        const caveat = zeroCallerCaveat(graph, index, matched);
+        if (caveat) { payload.caveat = caveat; payload.summary += ` — ⚠ ${caveat}`; }
+      }
+    }
+  } else if (query === 'impact') {
+    const matched = resolveSymbol(graph, symbol);
+    if (!matched.length) { payload = { query: 'impact', symbol, found: false }; code = 1; }
+    else {
+      const results = impactOf(index, matched);
+      const domains = [...new Set(results.map((id) => index.byId.get(id)?.domain || 'unassigned'))].sort();
+      // under a budget, rank the surviving ids by fan-in — top-N must be the most RELEVANT N.
+      const ranked = limit != null
+        ? results.slice().sort((a, b) => (index.callIn.get(b)?.size || 0) - (index.callIn.get(a)?.size || 0) || (a < b ? -1 : 1))
+        : results;
+      payload = budget({ query: 'impact', symbol, summary: `editing ${symbol} touches ${results.length} function(s) across ${domains.length} domain(s)`, matched, results: ranked, domains, count: results.length }, 'results', limit, offset);
+    }
+  } else if (query === 'cycles') {
+    const cycles = fileCycles(graph);
+    payload = budget({ query: 'cycles', summary: `${cycles.length} file-level dependency cycle(s)`, cycles, count: cycles.length }, 'cycles', limit, offset);
+  } else if (query === 'orphans') {
+    const results = orphans(graph, index);
+    payload = budget({ query: 'orphans', summary: `${results.length} orphan(s) — no callers and not exported`, results, count: results.length }, 'results', limit, offset);
+  }
+  return { payload, code };
+}

package/scripts/lib/reading-order.mjs

@@ -0,0 +1,53 @@
+// codeweb reading-order (F8) — a minimal, dependency-ordered reading path for understanding a scope at
+// any scale: foundations (the depended-upon leaves) first, orchestrators last, bounded to a budget. A
+// curated tour instead of blind grep. Pure, deterministic. Built on lib/graph-ops.mjs.
+//
+// RO-FOUNDATIONS-FIRST: a valid "callee before caller" linearization of the in-scope call DAG — when A
+// calls B and both are emitted, B precedes A. Greedy "fewest unemitted in-scope callees first" gives a
+// reverse-topo order on DAGs (a sink has 0 unemitted callees) and degrades gracefully on cycles
+// (fewest-deps, then highest in-scope fan-in, then id). RO-BUDGET: keeps the first `budget` foundations.
+
+import { buildIndex, resolveSymbol } from './graph-ops.mjs';
+
+function scopeIdsOf(graph, index, scope) {
+  const kind = (scope && scope.kind) || 'all';
+  if (kind === 'domain') return graph.nodes.filter((n) => (n.domain || 'unassigned') === scope.value).map((n) => n.id);
+  if (kind === 'file') return graph.nodes.filter((n) => n.file === scope.value).map((n) => n.id);
+  if (kind === 'symbol') {
+    const seeds = resolveSymbol(graph, scope.value);
+    const set = new Set(seeds); const q = [...seeds];
+    while (q.length) { const cur = q.shift(); for (const c of (index.callOut.get(cur) || [])) if (!set.has(c)) { set.add(c); q.push(c); } }
+    return [...set];
+  }
+  return graph.nodes.filter((n) => n.kind !== 'module').map((n) => n.id); // 'all'
+}
+
+export function readingOrder(graph, { scope = { kind: 'all' }, budget = Infinity } = {}) {
+  const index = buildIndex(graph);
+  const inScope = new Set(scopeIdsOf(graph, index, scope));
+  const calleesIn = new Map(), fanInIn = new Map();
+  for (const id of inScope) { calleesIn.set(id, new Set([...(index.callOut.get(id) || [])].filter((x) => inScope.has(x)))); fanInIn.set(id, 0); }
+  for (const id of inScope) for (const c of calleesIn.get(id)) fanInIn.set(c, (fanInIn.get(c) || 0) + 1);
+
+  const emitted = new Set(), order = [];
+  const remaining = [...inScope].sort();
+  while (remaining.length) {
+    let best = null;
+    for (const id of remaining) {
+      let un = 0; for (const c of calleesIn.get(id)) if (!emitted.has(c)) un++;
+      const cand = { id, un, fi: fanInIn.get(id) || 0 };
+      if (!best || cand.un < best.un || (cand.un === best.un && (cand.fi > best.fi || (cand.fi === best.fi && cand.id < best.id)))) best = cand;
+    }
+    emitted.add(best.id); order.push(best.id);
+    remaining.splice(remaining.indexOf(best.id), 1);
+  }
+
+  const out = order.map((id) => {
+    const fi = fanInIn.get(id) || 0, co = calleesIn.get(id).size;
+    const why = fi === 0
+      ? (co ? `entry point — orchestrates ${co} in-scope symbol(s)` : 'isolated symbol')
+      : `foundation — ${fi} in-scope caller(s)${co ? `, depends on ${co}` : ''}`;
+    return { id, why };
+  });
+  return Number.isFinite(budget) ? out.slice(0, Math.max(0, budget)) : out;
+}

package/scripts/lib/reliance.mjs

@@ -0,0 +1,143 @@
+// reliance — what callers ACTUALLY depend on. The most common breaking edit is changing a
+// return shape while some caller still destructures `.timeout` off it; the call sites are all
+// in the graph, so read the dependency off them and say it in one line: "callers rely on
+// {timeout, retries} · awaited 3/4 · args 1-2". Conservative by construction: only patterns
+// visible on the call-site line count; absence of a report means "nothing detected", never
+// "nothing relied on".
+
+import { callersOf } from './graph-ops.mjs';
+
+const MAX_SITES = 40;
+const PROMISE_PLUMBING = new Set(['then', 'catch', 'finally']);
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** Count top-level commas of the first LABEL(...) call on the line; null when unparsable. */
+function argCount(line, label) {
+  const start = line.search(new RegExp(`\\b${escapeRe(label)}\\s*\\(`));
+  if (start === -1) return null;
+  let i = line.indexOf('(', start);
+  let depth = 0, args = 0, sawAny = false, quote = null;
+  for (; i < line.length; i++) {
+    const ch = line[i];
+    if (quote) { if (ch === quote && line[i - 1] !== '\\') quote = null; continue; }
+    if (ch === "'" || ch === '"' || ch === '`') { quote = ch; continue; }
+    if (ch === '(' || ch === '[' || ch === '{') depth++;
+    else if (ch === ')' || ch === ']' || ch === '}') {
+      depth--;
+      if (depth === 0) return sawAny ? args + 1 : 0;
+    } else if (depth === 1) {
+      if (ch === ',') args++;
+      else if (!/\s/.test(ch)) sawAny = true;
+    }
+  }
+  return null; // call spans lines — skip this site for arg counting
+}
+
+/**
+ * Inspect the call sites of `node` (via its graph callers + on-disk source) and report the
+ * observable reliance. Returns null when source is unreadable or no call sites were found.
+ */
+export function callerReliance(graph, index, node, reader) {
+  if (!reader?.available || !node?.label) return null;
+  const label = node.label;
+  const callRe = new RegExp(`\\b${escapeRe(label)}\\s*\\(`);
+  const destructureRe = new RegExp(`(?:const|let|var)\\s*\\{([^}]*)\\}\\s*=\\s*(?:await\\s+)?[\\w.$]*\\b${escapeRe(label)}\\s*\\(`);
+  const memberRe = new RegExp(`\\b${escapeRe(label)}\\s*\\([^()]*\\)\\s*\\.(\\w+)`);
+  const awaitRe = new RegExp(`\\bawait\\s+[\\w.$]*\\b${escapeRe(label)}\\s*\\(`);
+  // v2 (Spec G): exception + nullability reliance, same line-visible conservatism.
+  const catchChainRe = new RegExp(`\\b${escapeRe(label)}\\s*\\([^()]*\\)\\s*\\.catch\\s*\\(`);
+  const negatedRe = new RegExp(`!\\s*[\\w.$]*\\b${escapeRe(label)}\\s*\\(`);
+  const optChainRe = new RegExp(`\\b${escapeRe(label)}\\s*\\([^()]*\\)\\s*\\?\\.`);
+  const coalesceRe = new RegExp(`\\b${escapeRe(label)}\\s*\\([^()]*\\)\\s*\\?\\?`);
+  const nullCmpRe = new RegExp(`\\b${escapeRe(label)}\\s*\\([^()]*\\)\\s*[!=]==?\\s*(?:null|undefined)`);
+
+  const fields = new Set();
+  let sites = 0, awaited = 0, minArgs = null, maxArgs = null, handlesErrors = 0, nullChecked = 0;
+  for (const callerId of callersOf(index, [node.id])) {
+    if (sites >= MAX_SITES) break;
+    const caller = index.byId.get(callerId);
+    const lines = caller && reader.linesOf(caller.file);
+    if (!lines) continue;
+    const from = caller.line - 1, to = Math.min(lines.length, from + (caller.loc || 1));
+    let tryDepth = 0; // line-granular try-enclosure inside THIS caller's body
+    for (let i = from; i < to && sites < MAX_SITES; i++) {
+      const line = lines[i].replace(/(^|[^:])\/\/.*$/, '$1'); // strip line comments, keep ://
+      const opens = (line.match(/\btry\s*\{/g) || []).length;
+      const closes = (line.match(/\}\s*(?:catch|finally)\b/g) || []).length;
+      if (!callRe.test(line)) { tryDepth = Math.max(0, tryDepth + opens - closes); continue; }
+      sites++;
+      let thenable = false;
+      const d = destructureRe.exec(line);
+      if (d) {
+        for (const part of d[1].split(',')) {
+          const name = part.trim().split(/[:=]/)[0].trim();
+          if (name && !name.startsWith('...')) fields.add(name);
+        }
+      } else {
+        const m = memberRe.exec(line);
+        if (m) {
+          if (PROMISE_PLUMBING.has(m[1])) thenable = true;
+          else fields.add(m[1]);
+        }
+      }
+      if (awaitRe.test(line) || thenable) awaited++;
+      if (tryDepth > 0 || catchChainRe.test(line)) handlesErrors++;
+      if (optChainRe.test(line) || coalesceRe.test(line) || nullCmpRe.test(line) || negatedRe.test(line)) nullChecked++;
+      const a = argCount(line, label);
+      if (a != null) {
+        minArgs = minArgs == null ? a : Math.min(minArgs, a);
+        maxArgs = maxArgs == null ? a : Math.max(maxArgs, a);
+      }
+      tryDepth = Math.max(0, tryDepth + opens - closes);
+    }
+  }
+  if (!sites) return null;
+  const out = { sites, awaited };
+  if (fields.size) out.fields = [...fields].sort();
+  if (minArgs != null) out.argRange = [minArgs, maxArgs];
+  if (handlesErrors) out.handlesErrors = handlesErrors;
+  if (nullChecked) out.nullChecked = nullChecked;
+  const mutated = paramMutations(node, reader);
+  if (mutated.length) out.mutatesParams = mutated;
+  return out;
+}
+
+// v2 (Spec G): parameter-mutation hazard — the CALLEE writing through a named parameter means
+// callers share that object. Body-line patterns only: `p.x =`, `p[..] =`, `Object.assign(p`,
+// and the mutating array methods. No parameters or no source -> no claim.
+const MUTATING_METHODS = 'push|pop|shift|unshift|splice|sort|reverse|fill|copyWithin';
+function paramMutations(node, reader) {
+  const params = node?.signature?.params || [];
+  if (!params.length) return [];
+  const lines = reader.linesOf(node.file);
+  if (!lines) return [];
+  const from = node.line - 1, to = Math.min(lines.length, from + (node.loc || 1));
+  const mutated = new Set();
+  for (const p of params) {
+    const pe = escapeRe(p);
+    const res = [
+      new RegExp(`\\b${pe}\\s*(?:\\.[\\w$]+|\\[[^\\]]+\\])\\s*[+\\-*/]?=(?!=)`),
+      new RegExp(`Object\\.assign\\(\\s*${pe}\\b`),
+      new RegExp(`\\b${pe}\\s*(?:\\.[\\w$]+)*\\.(?:${MUTATING_METHODS})\\s*\\(`),
+    ];
+    for (let i = from; i < to; i++) {
+      const line = lines[i].replace(/(^|[^:])\/\/.*$/, '$1');
+      if (res.some((re) => re.test(line))) { mutated.add(p); break; }
+    }
+  }
+  return [...mutated].sort();
+}
+
+/** One compact line for cards/hooks, or null when there is nothing worth saying. */
+export function relianceLine(r) {
+  if (!r) return null;
+  const parts = [];
+  if (r.fields?.length) parts.push(`callers use {${r.fields.join(', ')}} of the result — keep those`);
+  if (r.awaited > 0) parts.push(`awaited ${r.awaited}/${r.sites}`);
+  if (r.argRange) parts.push(`args ${r.argRange[0] === r.argRange[1] ? r.argRange[0] : `${r.argRange[0]}-${r.argRange[1]}`}`);
+  if (r.handlesErrors) parts.push(`${r.handlesErrors} caller(s) handle errors from this — thrown types are contract`);
+  if (r.nullChecked) parts.push(`${r.nullChecked} caller(s) null-check the result — keep null/undefined returns possible`);
+  if (r.mutatesParams?.length) parts.push(r.mutatesParams.map((p) => `mutates its argument "${p}" — callers share that object`).join(' · '));
+  return parts.length ? parts.join(' · ') : null;
+}

package/scripts/lib/risk.mjs

@@ -0,0 +1,18 @@
+// codeweb risk scoring primitive (F7) — the change-risk formula in ONE place so risk.mjs and its
+// tests share the same constants (the test imports these; it does not re-hardcode them). Pure.
+//
+// risk = Σ wᵢ · normᵢ(componentᵢ), where normᵢ = componentᵢ / graph-max(componentᵢ) (0 when the max
+// is 0). Weights are non-negative and sum to 1, so risk ∈ [0,1] and is monotonic non-decreasing in
+// each component for fixed maxes (pinned by RK-MONOTONE).
+
+export const RISK_WEIGHTS = { fanIn: 0.30, fanOut: 0.15, loc: 0.15, blast: 0.30, churn: 0.10 };
+
+export function riskScore(components, maxes) {
+  let s = 0;
+  for (const k of Object.keys(RISK_WEIGHTS)) {
+    const m = maxes[k] || 0;
+    const norm = m > 0 ? (components[k] || 0) / m : 0;
+    s += RISK_WEIGHTS[k] * norm;
+  }
+  return s;
+}