@ghostlygawd/codeweb 0.9.0

package/scripts/review.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+// codeweb review (F5) — turn a change into a deterministic STRUCTURAL review. Maps changed line
+// ranges to the symbols whose body span they touch, then reports the blast radius, domains touched,
+// and per-symbol caller counts (review-prioritization). With --before, adds the structural delta
+// (new file cycles + symbols that lost all callers — the structuralRegressions subset, NOT the
+// overlap delta a refreshed graph can't populate). Read-only, deterministic. Built on graph-ops.
+//
+// Usage:
+//   node review.mjs <graph.json> --changed <file[:s-e],...>   # explicit hunks (file = whole file)
+//   node review.mjs <graph.json> --range <gitref>             # derive hunks via git diff --unified=0
+//   ... [--before <graph.json>] [--gate] [--json]
+// Exit: 0 ok (advisory), 1 with --gate when a structural regression is present, 2 usage/IO.
+//
+// NOTE: changed-symbol selection uses the extractor's recorded [line, line+loc-1] span, which is
+// best-effort (loc is clamped/brace-matched); it can under-select on truncated bodies. --range path
+// assumes the graph's file paths match git's (graph mapped at the repo root).
+
+import { readFileSync, existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import { normalizeGraph, reviewImpact, structuralRegressions } from './lib/graph-ops.mjs';
+import { incrementalOverlap } from './lib/dup-check.mjs'; // F3: duplication-delta in the edit gate
+
+const USAGE = 'usage: review.mjs <graph.json> (--changed <file[:s-e],...> | --range <gitref>) [--before <graph.json>] [--gate] [--json]';
+import { die, emitJson, finish, loadGraph } from './lib/cli.mjs';
+
+const argv = process.argv.slice(2);
+let json = false, gate = false, changed = null, range = null, before = null; const pos = [];
+for (let i = 0; i < argv.length; i++) {
+  const t = argv[i];
+  if (t === '--json') json = true;
+  else if (t === '--gate') gate = true;
+  else if (t === '--changed') changed = argv[++i];
+  else if (t === '--range') range = argv[++i];
+  else if (t === '--before') before = argv[++i];
+  else if (!t.startsWith('-')) pos.push(t);
+}
+const graphPath = pos[0];
+if (!graphPath || (changed == null && range == null)) die(USAGE, 2);
+
+const load = (p) => loadGraph(p).graph; // Spec E: one truth with every other CLI (was a duplicated pre-loadGraph copy)
+const graph = load(graphPath);
+
+// build hunks from --changed (explicit) or --range (git)
+function parseChanged(csv) {
+  const fileRanges = new Map(); // file -> [[s,e]...] | 'whole'
+  for (const entry of csv.split(',').map((s) => s.trim()).filter(Boolean)) {
+    const ci = entry.indexOf(':');
+    if (ci === -1) { fileRanges.set(entry, 'whole'); continue; }
+    const file = entry.slice(0, ci), rng = entry.slice(ci + 1);
+    if (fileRanges.get(file) === 'whole') continue;
+    const m = /^(\d+)-(\d+)$/.exec(rng);
+    if (!m) die(`bad range in --changed (want file:start-end): ${entry}`, 2);
+    const arr = fileRanges.get(file) || []; arr.push([+m[1], +m[2]]); fileRanges.set(file, arr);
+  }
+  return [...fileRanges].map(([file, v]) => ({ file, ranges: v === 'whole' ? null : v }));
+}
+function hunksFromGit(ref) {
+  const r = spawnSync('git', ['diff', '--unified=0', ref], { encoding: 'utf8', maxBuffer: 1 << 28 });
+  if (r.status !== 0) die(`git diff failed: ${(r.stderr || '').trim()}`, 2);
+  const byFile = new Map(); let cur = null;
+  for (const line of r.stdout.split(/\r?\n/)) {
+    let m;
+    if ((m = /^\+\+\+ b\/(.+)$/.exec(line))) { cur = m[1] === '/dev/null' ? null : m[1]; if (cur && !byFile.has(cur)) byFile.set(cur, []); }
+    else if (cur && (m = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/.exec(line))) {
+      const start = +m[1], len = m[2] === undefined ? 1 : +m[2];
+      byFile.get(cur).push([start, start + Math.max(len, 1) - 1]);
+    }
+  }
+  return [...byFile].map(([file, ranges]) => ({ file, ranges }));
+}
+const hunks = range != null ? hunksFromGit(range) : parseChanged(changed);
+
+const impact = reviewImpact(graph, hunks);
+let structural = null, hasRegression = false;
+if (before != null) {
+  const sr = structuralRegressions(load(before), graph);
+  structural = sr;
+  hasRegression = sr.newCycles.length > 0 || sr.lostCallers.length > 0;
+}
+// F3: duplication delta — when the target source is readable, body-confirm whether any CHANGED symbol
+// now duplicates an existing one (the overlap delta a refreshed graph's overlaps:[] cannot show). A
+// new body-confirmed duplication is a regression (fails --gate), closing the prevent-duplication hole.
+const root = graph.meta?.root;
+const newDuplications = (root && existsSync(root)) ? incrementalOverlap(graph, impact.changedSymbols, { root }) : [];
+if (newDuplications.length) hasRegression = true;
+
+const payload = { ...impact, filesChanged: hunks.map((h) => h.file).sort(), structural, newDuplications };
+const code = (gate && hasRegression) ? 1 : 0;
+
+if (json) { emitJson(payload, code); } else {
+
+console.log(`codeweb review: ${impact.changedSymbols.length} changed symbol(s) across ${payload.filesChanged.length} file(s)`);
+console.log(`  domains touched: ${impact.domainsTouched.join(', ') || '(none)'}`);
+console.log(`  blast radius: ${impact.blastRadius.count} transitive dependent(s)`);
+if (impact.callerCounts.length) {
+  console.log('  highest-fan-in changed symbols (review first):');
+  for (const c of impact.callerCounts.slice(0, 8)) console.log(`    ${c.callers} caller(s)  ${c.id}`);
+}
+if (structural) {
+  if (structural.newCycles.length || structural.lostCallers.length) {
+    console.log('  STRUCTURAL REGRESSIONS:');
+    if (structural.newCycles.length) console.log(`    x ${structural.newCycles.length} new file cycle(s): ${structural.newCycles.map((c) => c.join('+')).join(', ')}`);
+    if (structural.lostCallers.length) console.log(`    x ${structural.lostCallers.length} symbol(s) lost all callers: ${structural.lostCallers.join(', ')}`);
+  } else console.log('  structural: ok — no new cycles or lost-caller regressions vs --before');
+}
+if (newDuplications.length) {
+  console.log(`  NEW DUPLICATION (body-confirmed) — ${newDuplications.length}:`);
+  for (const d of newDuplications) console.log(`    x ${d.id} duplicates ${d.dupOf} (${(d.sim * 100).toFixed(0)}%)`);
+}
+finish(code);
+}

package/scripts/risk.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// codeweb risk (F7) — rank symbols by change-risk so a reviewer triages the dangerous ones first.
+// risk = weighted, graph-max-normalized blend of fan-in, fan-out, loc, transitive blast radius, and
+// git churn (the formula + weights live in ./lib/risk.mjs — one truth, shared with the tests).
+// Read-only, deterministic. Built on ./lib/graph-ops.mjs.
+//
+// Usage: node risk.mjs <graph.json> [--changed <file,...>] [--churn <map.json> | --git] [--json]
+//   --churn map.json: { "<relpath>": <commitCount> }   --git: derive churn from `git log` (integration)
+// 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, buildIndex, impactOf } from './lib/graph-ops.mjs';
+import { RISK_WEIGHTS, riskScore } from './lib/risk.mjs';
+
+const USAGE = 'usage: risk.mjs <graph.json> [--changed <file,...>] [--churn <map.json> | --git] [--json]';
+import { die, emitJson, finish, capList, loadGraph } from './lib/cli.mjs';
+
+const argv = process.argv.slice(2);
+let json = false, changed = null, 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 === '--changed') changed = argv[++i];
+  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 });
+
+// churn map: file -> commit count
+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 index = buildIndex(graph);
+// components per node (raw structural metrics + churn-by-file)
+const comp = graph.nodes.map((n) => ({
+  id: n.id, file: n.file, domain: n.domain,
+  fanIn: index.callIn.get(n.id)?.size || 0,
+  fanOut: index.callOut.get(n.id)?.size || 0,
+  loc: n.loc || 0,
+  blast: impactOf(index, [n.id]).length,
+  churn: churn[n.file] || 0,
+}));
+// graph-max per component (normalization denominator)
+const maxes = { fanIn: 0, fanOut: 0, loc: 0, blast: 0, churn: 0 };
+for (const c of comp) for (const k of Object.keys(maxes)) maxes[k] = Math.max(maxes[k], c[k]);
+
+let ranked = comp.map((c) => ({ id: c.id, file: c.file, domain: c.domain, risk: riskScore(c, maxes), components: { fanIn: c.fanIn, fanOut: c.fanOut, loc: c.loc, blast: c.blast, churn: c.churn } }))
+  .sort((a, b) => b.risk - a.risk || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+
+if (changed != null) {
+  const files = new Set(changed.split(',').map((s) => s.trim()).filter(Boolean));
+  ranked = ranked.filter((r) => files.has(r.file));
+}
+
+const capped = capList(ranked, limit);
+const payload = { target: graph.meta?.target || 'target', summary: `${ranked.length} symbol(s) ranked by change-risk${changed != null ? ' (changed only)' : ''}`, weights: RISK_WEIGHTS, maxes, count: ranked.length, ranked: capped.items };
+if (capped.truncated) payload.more = { remaining: capped.remaining };
+
+if (json) { emitJson(payload); } else {
+
+console.log(`codeweb risk: ${payload.target} — ${ranked.length} symbol(s) ranked by change-risk${changed != null ? ' (changed only)' : ''}`);
+console.log(`  weights: ${Object.entries(RISK_WEIGHTS).map(([k, v]) => `${k} ${v}`).join(', ')}`);
+for (const r of ranked.slice(0, 15)) {
+  const c = r.components;
+  console.log(`  ${r.risk.toFixed(3)}  ${r.id}  [in ${c.fanIn} out ${c.fanOut} loc ${c.loc} blast ${c.blast} churn ${c.churn}]`);
+}
+finish();
+}

package/scripts/run.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// codeweb — pipeline orchestrator (the entry point the /codeweb command + codebase-anatomy skill call).
+// Runs the full deterministic pipeline for ONE target into its OWN workspace, so analyzing several
+// targets never clobbers each other's outputs. Resolves all paths from the plugin root, so it works
+// regardless of the caller's cwd (e.g. `node ${CLAUDE_PLUGIN_ROOT}/scripts/run.mjs <target>`).
+//
+//   node scripts/run.mjs <SRC> [--target <label>] [--out-dir <dir>]
+//
+// Default workspace: <plugin>/.codeweb/runs/<slug>  (override with --out-dir, e.g. <target>/.codeweb).
+// Stages read their workspace from CODEWEB_WS (default '.live' when run standalone).
+// Outputs in the workspace: fragment.json, graph.json, overlap.md, report.html, report.md.
+// Read-only over the target; never executes target code.
+
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..'); // plugin root (parent of scripts/)
+
+// Bump when ANY downstream stage (cluster/overlap/optimize/report) changes behavior — it keys the
+// stage memo, so an old workspace can never serve outputs computed by an older pipeline.
+const MEMO_VERSION = 1;
+
+const argv = process.argv.slice(2);
+const opts = { src: null, target: null, outDir: null, open: false, full: false };
+for (let i = 0; i < argv.length; i++) {
+  const t = argv[i];
+  if (t === '--target') opts.target = argv[++i];
+  else if (t === '--out-dir') opts.outDir = argv[++i];
+  else if (t === '--open') opts.open = true;
+  else if (t === '--full') opts.full = true;
+  else if (!opts.src) opts.src = t;
+}
+if (!opts.src) { console.error('usage: run.mjs <SRC> [--target <label>] [--out-dir <dir>]'); process.exit(1); }
+// Resolve the target against the CALLER's cwd (not the plugin root the stages run in) — a relative
+// <SRC> must mean the same thing as a relative --out-dir. Fail here with one clean line, not a
+// stage-level stack trace.
+opts.src = resolve(opts.src);
+if (!existsSync(opts.src)) { console.error(`[run] target not found: ${opts.src}`); process.exit(1); }
+
+// slug = whole target label (or last 2 path segments of src), so e.g. ecc/scripts -> "ecc-scripts"
+// rather than a collision-prone "scripts".
+const base = opts.target || opts.src.replace(/\\/g, '/').replace(/\/+$/, '').split('/').slice(-2).join('/');
+const slug = base.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'target';
+const ws = opts.outDir ? resolve(opts.outDir) : join(ROOT, '.codeweb', 'runs', slug);
+mkdirSync(ws, { recursive: true });
+
+const env = { ...process.env, CODEWEB_WS: ws };
+const node = process.execPath;
+const S = (p) => join(ROOT, p);
+const run = (label, file, args, useEnv) => {
+  console.error(`\n[run] ${label}`);
+  try {
+    execFileSync(node, [file, ...args], { stdio: 'inherit', env: useEnv ? env : process.env, cwd: ROOT });
+  } catch (e) {
+    // The stage already printed its own diagnostics (stdio inherited) — add one clean line, not a
+    // raw execFileSync stack dump.
+    console.error(`\n[run] stage '${label}' failed${typeof e?.status === 'number' ? ` (exit ${e.status})` : ''} — aborting`);
+    process.exit(1);
+  }
+};
+
+const targetArg = opts.target ? ['--target', opts.target] : [];
+// Extract always runs — it is the change detector — and rides the scan cache (Spec A), so a
+// no-change re-run costs ~the regex baseline instead of a full parse.
+run('extract', S('scripts/extract-symbols.mjs'), [opts.src, ...targetArg, '--cache', join(ws, '.scan-cache.json'), '--out', join(ws, 'fragment.json')], false);
+
+// Spec B (docs/specs/perf-stage-memo-scale.md): the four downstream stages are pure functions of
+// (fragment bytes, CODEWEB_* levers, pipeline version). When that key matches the previous run and
+// every output still exists, reuse the outputs — wall-time changes, never a byte. --full forces.
+const STAGE_OUTPUTS = ['graph.json', 'overlap.md', 'optimize.md', 'report.html', 'report.md'];
+const levers = Object.keys(process.env)
+  .filter((k) => k.startsWith('CODEWEB_') && k !== 'CODEWEB_WS').sort()
+  .map((k) => `${k}=${process.env[k]}`).join(';');
+const memoKey = createHash('sha1')
+  .update(`v${MEMO_VERSION}|${levers}|`).update(readFileSync(join(ws, 'fragment.json')))
+  .digest('hex');
+const memoPath = join(ws, '.stages.json');
+let prevKey = null;
+try { prevKey = JSON.parse(readFileSync(memoPath, 'utf8')).key; } catch { /* absent/corrupt -> compute */ }
+const reusable = !opts.full && prevKey === memoKey && STAGE_OUTPUTS.every((f) => existsSync(join(ws, f)));
+
+if (reusable) {
+  console.error('\n[run] stages reused (fragment unchanged) — skipping downstream recompute; --full forces');
+} else {
+  run('cluster', S('scripts/cluster3.mjs'), [], true);
+  run('overlap', S('scripts/overlap.mjs'), [], true);
+  run('optimize', S('scripts/optimize.mjs'), [join(ws, 'graph.json'), '--out', join(ws, 'optimize.md')], false);
+  run('report', S('scripts/build-report.mjs'), [join(ws, 'graph.json'), ...(opts.open ? ['--open'] : [])], false);
+  try { writeFileSync(memoPath, JSON.stringify({ key: memoKey, at: new Date().toISOString() }) + '\n'); } catch { /* memo is best-effort */ }
+}
+
+console.error(`\n[run] done -> ${ws}`);
+console.error(`[run]   ${ws}/report.html · report.md · overlap.md · optimize.md · graph.json · fragment.json`);

package/scripts/screenshot.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+// codeweb screenshot — the demo-shot pipeline, deterministic and staged. Every committed
+// screenshot regenerates from the REAL report with one command, at retina scale, in states
+// that actually show the product (a selected symbol with its blast lit, a populated
+// inspector) instead of default first paints. Layout is seeded, so reruns produce stable
+// frames.
+//
+//   node scripts/screenshot.mjs <report.html> --out <dir> [--prefix shot] [--scale 2]
+//
+// Emits: <prefix>-findings.png, -graph.png (areas overview), -blast.png (top hotspot
+// selected, neighbors lit), -treemap.png, -matrix.png
+// Requires playwright + a chromium (PLAYWRIGHT_BROWSERS_PATH or CODEWEB_CHROMIUM).
+
+import { resolve, join } from 'node:path';
+import { mkdirSync, existsSync, readdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+
+const argv = process.argv.slice(2);
+let report = null, outDir = 'shots', prefix = 'shot', scale = 2;
+for (let i = 0; i < argv.length; i++) {
+  const t = argv[i];
+  if (t === '--out') outDir = argv[++i];
+  else if (t === '--prefix') prefix = argv[++i];
+  else if (t === '--scale') scale = parseFloat(argv[++i]) || 2;
+  else if (!t.startsWith('-')) report = t;
+}
+if (!report) { console.error('usage: screenshot.mjs <report.html> --out <dir> [--prefix p] [--scale 2]'); process.exit(2); }
+
+// dev-only dependency, resolved from the CALLER'S cwd (the engine itself stays zero-dep)
+let chromium;
+try {
+  const req = createRequire(join(process.cwd(), 'noop.js'));
+  const mod = await import(pathToFileURL(req.resolve('playwright')).href);
+  chromium = mod.chromium || (mod.default && mod.default.chromium);
+  if (!chromium) throw new Error('no chromium export');
+} catch { console.error('playwright not resolvable from cwd — npm i playwright somewhere and run from there (dev-only; the report itself has zero deps)'); process.exit(2); }
+
+function findChromium() {
+  if (process.env.CODEWEB_CHROMIUM) return process.env.CODEWEB_CHROMIUM;
+  const root = process.env.PLAYWRIGHT_BROWSERS_PATH;
+  if (root && existsSync(root)) {
+    for (const d of readdirSync(root)) if (d.startsWith('chromium')) {
+      const p = join(root, d, 'chrome-linux', 'chrome');
+      if (existsSync(p)) return p;
+    }
+  }
+  return undefined; // let playwright resolve its own download
+}
+
+mkdirSync(resolve(outDir), { recursive: true });
+const VW = 1600, VH = 1000, PANEL = 340;
+const browser = await chromium.launch({ executablePath: findChromium() });
+const page = await browser.newPage({ viewport: { width: VW, height: VH }, deviceScaleFactor: scale });
+page.on('pageerror', (e) => { console.error('page error: ' + e.message); process.exitCode = 1; });
+await page.goto('file://' + resolve(report));
+await page.waitForTimeout(800);
+// clip = crop to CONTENT (CSS px) — a README thumbnail of a full frame is unreadable; empty
+// canvas never ships. Clips are clamped to the viewport.
+const shot = (name, clip) => {
+  if (clip) {
+    const x = Math.max(0, Math.floor(clip.x)), y = Math.max(0, Math.floor(clip.y));
+    clip = { x, y, width: Math.min(VW - x, Math.ceil(clip.width)), height: Math.min(VH - y, Math.ceil(clip.height)) };
+  }
+  return page.screenshot({ path: join(resolve(outDir), `${prefix}-${name}.png`), ...(clip ? { clip } : {}) });
+};
+const tab = async (v) => { await page.click(`.tab[data-view="${v}"]`); await page.waitForTimeout(700); };
+const graphClip = async (pad) => {
+  const b = await page.evaluate(() => window.__codewebStage && window.__codewebStage.graphBBox && window.__codewebStage.graphBBox());
+  if (!b) return null;
+  // graph bbox + header row; always include the inspector column on the right
+  return { x: Math.max(0, b.x - pad), y: 0, width: VW - Math.max(0, b.x - pad), height: Math.min(VH, 48 + b.y + b.h + pad) };
+};
+
+// 1. findings — first paint, overview card populated by construction
+await shot('findings');
+
+// 2. graph — the areas overview, settled, cropped to the drawn content
+await tab('graph');
+await page.waitForTimeout(3200);
+await page.click('#gFit');
+await page.waitForTimeout(400);
+await shot('graph', await graphClip(40));
+
+// 3. blast — top hotspot selected (zoomed), its area expanded, inspector populated
+const staged = await page.evaluate(() => window.__codewebStage ? window.__codewebStage.topHotspot() : null);
+if (staged) { await page.waitForTimeout(2600); await shot('blast', await graphClip(24)); }
+else console.error('stage hook missing — blast shot skipped (old report build?)');
+
+// 4. treemap — dense edge-to-edge, full frame
+await tab('treemap'); await shot('treemap');
+
+// 5. matrix — cropped to the table + legend (it occupies a corner of the full frame)
+await tab('matrix');
+const mClip = await page.evaluate(() => {
+  const t = document.querySelector('table.m'); const l = document.querySelector('#view-matrix .legend');
+  if (!t) return null;
+  const tr = t.getBoundingClientRect(), lr = l ? l.getBoundingClientRect() : tr;
+  return { x: 0, y: 0, width: Math.max(tr.right, lr.right) + 24, height: Math.max(tr.bottom, lr.bottom) + 16 };
+});
+await shot('matrix', mClip);
+
+await browser.close();
+console.log(`[screenshot] ${staged ? 5 : 4} frame(s) -> ${resolve(outDir)}/${prefix}-*.png${staged ? ` (blast: ${staged})` : ''}`);

package/scripts/simulate-edit.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+// codeweb simulate-edit — predict the regression gate's STRUCTURAL verdict for a hypothetical edit,
+// WITHOUT performing it. Lets an agent discard doomed edits for ~zero cost before generating a line.
+// Scoped to structuralRegressions (new file-cycles + symbols that lose all callers) — the same
+// subset the post-edit hook enforces. Duplication delta needs the full body-confirmed pipeline and
+// is intentionally OUT OF SCOPE (documented, not silently dropped). Read-only; never writes.
+// Built on ./lib/graph-ops.mjs (shares applyEdit with optimize.mjs — one truth).
+//
+// Usage:
+//   node simulate-edit.mjs <graph.json> --delete <symbol>
+//   node simulate-edit.mjs <graph.json> --merge <s1,s2,...> [--into <id>]   (default canonical = smallest id)
+//   node simulate-edit.mjs <graph.json> --move <symbol> --to <file>
+//   (or set CODEWEB_WS instead of <graph.json>)   add --json for machine output.
+// Exit: 0 ok (verdict lives in projected.ok), 1 symbol not found, 2 usage/IO.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { normalizeGraph, resolveSymbol, applyEdit, structuralRegressions } from './lib/graph-ops.mjs';
+
+const USAGE = 'usage: simulate-edit.mjs <graph.json> (--delete <sym> | --merge <s1,s2,..> [--into <id>] | --move <sym> --to <file>) [--json]';
+import { die, emitJson, finish, loadGraph } from './lib/cli.mjs';
+
+const argv = process.argv.slice(2);
+let json = false, del = null, merge = null, into = null, move = null, to = null; const pos = [];
+for (let i = 0; i < argv.length; i++) {
+  const t = argv[i];
+  if (t === '--json') json = true;
+  else if (t === '--delete') del = argv[++i];
+  else if (t === '--merge') merge = argv[++i];
+  else if (t === '--into') into = argv[++i];
+  else if (t === '--move') move = argv[++i];
+  else if (t === '--to') to = argv[++i];
+  else if (!t.startsWith('-')) pos.push(t);
+}
+if ([del, merge, move].filter((x) => x != null).length !== 1) die(USAGE, 2);
+if (move != null && to == null) die('move requires --to <file>', 2);
+
+const { graph, abs } = loadGraph(pos[0], { usage: USAGE });
+
+let opName, after, target, intoOut = null, toOut = null;
+if (del != null) {
+  const ids = resolveSymbol(graph, del);
+  if (!ids.length) die(`symbol not found: ${del}`, 1);
+  opName = 'delete'; target = ids; after = applyEdit(graph, { kind: 'delete', ids });
+} else if (merge != null) {
+  const syms = merge.split(',').map((s) => s.trim()).filter(Boolean);
+  const ids = [...new Set(syms.flatMap((s) => resolveSymbol(graph, s)))].sort();
+  if (ids.length < 2) die(`merge needs >=2 resolved symbols (got ${ids.length})`, ids.length ? 2 : 1);
+  const canonical = into != null ? (resolveSymbol(graph, into)[0] || into) : ids[0]; // default: smallest id
+  opName = 'merge'; target = ids; intoOut = canonical; after = applyEdit(graph, { kind: 'merge', ids, into: canonical });
+} else {
+  const ids = resolveSymbol(graph, move);
+  if (!ids.length) die(`symbol not found: ${move}`, 1);
+  opName = 'move'; target = ids; toOut = to;
+  after = ids.reduce((g, id) => applyEdit(g, { kind: 'move', id, to }), graph); // move every matched def
+}
+
+const { newCycles, lostCallers } = structuralRegressions(graph, after);
+const projected = { newCycles, lostCallers, ok: newCycles.length === 0 && lostCallers.length === 0 };
+const payload = { op: opName, target, into: intoOut, to: toOut, projected };
+
+if (json) { emitJson(payload); } else {
+
+console.log(`simulate-edit: ${opName} ${target.join(', ')}${intoOut ? ` -> ${intoOut}` : ''}${toOut ? ` -> ${toOut}` : ''}`);
+console.log(`projected gate: ${projected.ok ? 'PASS — the gate would accept this edit (exit 0)' : 'BLOCK — the gate would reject this edit (exit 1)'}`);
+if (newCycles.length) console.log(`  new file cycle(s): ${newCycles.map((c) => c.join(' -> ')).join(' | ')}`);
+if (lostCallers.length) console.log(`  symbol(s) left with no callers: ${lostCallers.join(', ')}`);
+console.log('  (structural pre-flight: duplication delta is out of scope — run the full pipeline for that.)');
+finish();
+}

package/scripts/stats.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+// codeweb stats — the value receipt: what codeweb actually did in this workspace, month by
+// month, counted at the moment it happened (hooks + MCP server). Local-only by construction;
+// see lib/stats.mjs. Empty ledger -> says so and explains how counters accrue.
+//
+//   node scripts/stats.mjs <graph.json> [--json]
+
+import { die, emitJson, emitText, loadGraph } from './lib/cli.mjs';
+import { readStats, monthLine } from './lib/stats.mjs';
+
+const USAGE = 'usage: stats.mjs <graph.json> [--json]';
+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); else die(USAGE, 2); }
+
+const { graph, abs } = loadGraph(pos[0], { usage: USAGE });
+const s = readStats(abs);
+
+if (json) { emitJson(s || { empty: true, note: 'no activity recorded yet — counters accrue as the hooks and MCP server run (CODEWEB_NO_STATS=1 disables)' }); }
+else {
+  const L = [`codeweb activity — ${graph.meta?.target || abs}`];
+  const months = s ? Object.keys(s.months || {}).sort() : [];
+  const lines = months.map((m) => ({ m, line: monthLine(s.months[m]) })).filter((x) => x.line);
+  if (!lines.length) {
+    L.push('  no activity recorded yet — counters accrue as the hooks and MCP server run.');
+    L.push('  (local-only: stats.json lives beside the graph and never leaves this machine; CODEWEB_NO_STATS=1 disables)');
+  } else {
+    for (const { m, line } of lines) L.push(`  ${m}: ${line}`);
+  }
+  emitText(L.join('\n'));
+}

package/scripts/trend.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+// codeweb trend — body-confirmed duplication + cross-domain coupling over a series of snapshots,
+// so a one-shot map becomes a dashboard you re-open: is the codebase consolidating or sprawling?
+//
+// Two modes:
+//   node trend.mjs <graph.json> [<graph.json>...] [--labels a,b,..] [--json]
+//       Render a trend from pre-built graph snapshots, oldest -> newest.
+//   node trend.mjs --git <repo> [--last N] [--focus <subdir>] [--json]
+//       Snapshot each of the last N commits via an ephemeral git worktree + the deterministic
+//       pipeline, then render. Read-only over the repo; worktrees live under the OS temp dir and
+//       are removed after each commit (the caller's working tree is never touched).
+//
+// Metrics per snapshot:
+//   confirmed  = duplicate-logic overlaps with confidence 'high' (body-confirmed real duplications)
+//   candidates = duplicate-logic overlaps not 'refuted' (confirmed + unverified)
+//   coupling   = total weight of non-test edges whose endpoints sit in different domains
+
+import { readFileSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SPARK = '▁▂▃▄▅▆▇█';
+
+function parseArgs(argv) {
+  const a = { graphs: [], git: null, last: 10, focus: '.', json: false, labels: null };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === '--git') a.git = argv[++i];
+    else if (t === '--last') a.last = Math.max(1, parseInt(argv[++i], 10) || 10);
+    else if (t === '--focus') a.focus = argv[++i];
+    else if (t === '--labels') a.labels = (argv[++i] || '').split(',');
+    else if (t === '--json') a.json = true;
+    else a.graphs.push(t);
+  }
+  return a;
+}
+
+// ---- pure metrics ----
+function metrics(g) {
+  const overlaps = Array.isArray(g.overlaps) ? g.overlaps : [];
+  const dl = overlaps.filter((o) => o.kind === 'duplicate-logic');
+  const confirmed = dl.filter((o) => o.confidence === 'high').length;
+  const candidates = dl.filter((o) => o.confidence !== 'refuted').length;
+  const nodes = Array.isArray(g.nodes) ? g.nodes : [];
+  const edges = Array.isArray(g.edges) ? g.edges : [];
+  const dom = new Map(nodes.map((n) => [n.id, n.domain || 'unassigned']));
+  let coupling = 0;
+  for (const e of edges) {
+    if (e.kind === 'test') continue;
+    const a = dom.get(e.from), b = dom.get(e.to);
+    if (a != null && b != null && a !== b) coupling += e.weight || 1;
+  }
+  return { confirmed, candidates, coupling, nodes: nodes.length, files: new Set(nodes.map((n) => n.file).filter(Boolean)).size };
+}
+
+// ---- pure rendering ----
+function sparkline(values) {
+  if (!values.length) return '';
+  const min = Math.min(...values), max = Math.max(...values);
+  if (max === min) return SPARK[0].repeat(values.length); // flat series
+  return values.map((v) => SPARK[Math.round(((v - min) / (max - min)) * (SPARK.length - 1))]).join('');
+}
+function arrow(values) {
+  if (values.length < 2) return '→0';
+  const d = values[values.length - 1] - values[0];
+  return d > 0 ? `↑${d}` : d < 0 ? `↓${-d}` : '→0';
+}
+function line(label, seq) {
+  return `${label.padEnd(22)} ${sparkline(seq)}  ${seq.join(' → ')}  (${arrow(seq)})`;
+}
+function renderTrend(rows, { json } = {}) {
+  if (json) return JSON.stringify({ snapshots: rows }, null, 2);
+  const confirmed = rows.map((r) => r.confirmed);
+  const coupling = rows.map((r) => r.coupling);
+  const symbols = rows.map((r) => r.nodes);
+  const out = [];
+  out.push(`# codeweb — trend (${rows.length} snapshot${rows.length === 1 ? '' : 's'})`);
+  out.push('');
+  out.push('> Oldest → newest. **confirmed** = body-confirmed duplicate-logic findings; **coupling** = cross-domain edge weight.');
+  out.push('');
+  out.push('```');
+  out.push(line('confirmed duplications', confirmed));
+  out.push(line('cross-domain coupling', coupling));
+  out.push(line('symbols', symbols));
+  out.push('```');
+  out.push('');
+  out.push('| # | snapshot | symbols | confirmed dups | candidates | coupling |');
+  out.push('|---|----------|--------:|---------------:|-----------:|---------:|');
+  rows.forEach((r, i) => out.push(`| ${i + 1} | ${r.label} | ${r.nodes} | ${r.confirmed} | ${r.candidates} | ${r.coupling} |`));
+  out.push('');
+  const d = confirmed[confirmed.length - 1] - confirmed[0];
+  out.push(
+    rows.length < 2 ? '➡️ Single snapshot — run with more to see a trend.'
+      : d > 0 ? `⚠️ Duplication is **rising** (+${d} confirmed since the first snapshot).`
+        : d < 0 ? `✅ Duplication is **falling** (${d} confirmed since the first snapshot).`
+          : '➡️ Duplication is **flat** across the window.'
+  );
+  return out.join('\n');
+}
+
+// ---- snapshot sources ----
+const loadSnapshot = (p) => JSON.parse(readFileSync(resolve(p), 'utf8'));
+
+function gitSnapshots(repo, last, focus) {
+  const git = (args) => execFileSync('git', ['-C', repo, ...args], { encoding: 'utf8' });
+  const log = git(['log', '-n', String(last), '--format=%H\t%cs', '--', focus]).trim();
+  if (!log) return [];
+  const commits = log.split(/\r?\n/).map((l) => { const [sha, date] = l.split('\t'); return { sha, date }; }).reverse();
+  const rows = [];
+  for (const { sha, date } of commits) {
+    const base = mkdtempSync(join(tmpdir(), 'codeweb-trend-'));
+    const wt = join(base, 'wt'), ws = join(base, 'ws');
+    const label = `${sha.slice(0, 7)} (${date})`;
+    try {
+      git(['worktree', 'add', '--detach', '--force', wt, sha]);
+      execFileSync(process.execPath, [join(HERE, 'run.mjs'), join(wt, focus), '--target', sha.slice(0, 7), '--out-dir', ws], { stdio: 'ignore' });
+      rows.push({ label, ...metrics(loadSnapshot(join(ws, 'graph.json'))) });
+    } catch (e) {
+      rows.push({ label, error: String((e && e.message) || e), confirmed: 0, candidates: 0, coupling: 0, nodes: 0, files: 0 });
+    } finally {
+      try { git(['worktree', 'remove', '--force', wt]); } catch { /* best-effort */ }
+      try { rmSync(base, { recursive: true, force: true }); } catch { /* best-effort */ }
+    }
+  }
+  return rows;
+}
+
+// ---- main ----
+const opts = parseArgs(process.argv.slice(2));
+let rows = [];
+if (opts.git) {
+  rows = gitSnapshots(resolve(opts.git), opts.last, opts.focus);
+} else if (opts.graphs.length) {
+  rows = opts.graphs.map((p, i) => {
+    const g = loadSnapshot(p);
+    const label = (opts.labels && opts.labels[i]) || (g.meta && g.meta.target) || `snapshot ${i + 1}`;
+    return { label, ...metrics(g) };
+  });
+} else {
+  console.error('usage: trend.mjs <graph.json...> [--labels a,b] [--json]  |  trend.mjs --git <repo> [--last N] [--focus <sub>] [--json]');
+  process.exit(2);
+}
+if (!rows.length) { console.error('[codeweb] no snapshots to chart'); process.exit(1); }
+console.log(renderTrend(rows, { json: opts.json }));