@dreamtree-org/graphify 1.0.0 → 1.1.1

package/dist/{chunk-DG5FECXV.js → chunk-EW23BLJC.js}

@@ -1,8 +1,12 @@
+import {
+  affectedBy,
+  testsForNode
+} from "./chunk-YT7B6DOD.js";
 import {
   escapeHtml,
   sanitizeLabel,
   validateGraphPath
-} from "./chunk-5ANIDX3G.js";
+} from "./chunk-6JLEILYF.js";
 
 // src/detect.ts
 import * as fs from "fs";
@@ -242,7 +246,7 @@ async function createParser(grammarName) {
 }
 
 // src/extractors/csharp.ts
-async function extractCSharp(filePath) {
+async function extractCSharp(filePath, displayPath) {
   const parser = await createParser("c_sharp");
   const raw = await fs2.readFile(filePath);
   const content = raw.toString("utf-8");
@@ -251,7 +255,7 @@ async function extractCSharp(filePath) {
     throw new Error(`extractCSharp: parser produced no tree for ${filePath}`);
   }
   const root = tree.rootNode;
-  const sourceFile = toPosix(filePath);
+  const sourceFile = toPosix(displayPath ?? filePath);
   const builder = new ExtractionBuilder();
   const fileId = sourceFile;
   builder.addNode({ id: fileId, label: sourceFile, sourceFile, sourceLocation: "L1" });
@@ -455,7 +459,7 @@ function defaultPackageQualifier(importPath) {
   const segments = importPath.split("/");
   return segments[segments.length - 1] ?? importPath;
 }
-async function extractGo(filePath) {
+async function extractGo(filePath, displayPath) {
   const parser = await createParser("go");
   const raw = await fs3.readFile(filePath);
   const content = raw.toString("utf-8");
@@ -464,7 +468,7 @@ async function extractGo(filePath) {
     throw new Error(`extractGo: parser produced no tree for ${filePath}`);
   }
   const root = tree.rootNode;
-  const sourceFile = toPosix(filePath);
+  const sourceFile = toPosix(displayPath ?? filePath);
   const builder = new ExtractionBuilder();
   const fileId = sourceFile;
   builder.addNode({ id: fileId, label: sourceFile, sourceFile, sourceLocation: "L1" });
@@ -662,7 +666,7 @@ async function extractGo(filePath) {
 
 // src/extractors/java.ts
 import * as fs4 from "fs/promises";
-async function extractJava(filePath) {
+async function extractJava(filePath, displayPath) {
   const parser = await createParser("java");
   const raw = await fs4.readFile(filePath);
   const content = raw.toString("utf-8");
@@ -671,7 +675,7 @@ async function extractJava(filePath) {
     throw new Error(`extractJava: parser produced no tree for ${filePath}`);
   }
   const root = tree.rootNode;
-  const sourceFile = toPosix(filePath);
+  const sourceFile = toPosix(displayPath ?? filePath);
   const builder = new ExtractionBuilder();
   const fileId = sourceFile;
   builder.addNode({ id: fileId, label: sourceFile, sourceFile, sourceLocation: "L1" });
@@ -863,7 +867,7 @@ async function extractJava(filePath) {
 
 // src/extractors/python.ts
 import * as fs5 from "fs/promises";
-async function extractPython(filePath) {
+async function extractPython(filePath, displayPath) {
   const parser = await createParser("python");
   const raw = await fs5.readFile(filePath);
   const content = raw.toString("utf-8");
@@ -872,7 +876,7 @@ async function extractPython(filePath) {
     throw new Error(`extractPython: parser produced no tree for ${filePath}`);
   }
   const root = tree.rootNode;
-  const sourceFile = toPosix(filePath);
+  const sourceFile = toPosix(displayPath ?? filePath);
   const builder = new ExtractionBuilder();
   const fileId = sourceFile;
   builder.addNode({ id: fileId, label: sourceFile, sourceFile, sourceLocation: "L1" });
@@ -1107,7 +1111,7 @@ function stringLiteralContent(node) {
   const content = namedChildren(node).find((c) => c.type === "string_content");
   return content ? content.text : "";
 }
-async function extractRuby(filePath) {
+async function extractRuby(filePath, displayPath) {
   const parser = await createParser("ruby");
   const raw = await fs6.readFile(filePath);
   const content = raw.toString("utf-8");
@@ -1116,7 +1120,7 @@ async function extractRuby(filePath) {
     throw new Error(`extractRuby: parser produced no tree for ${filePath}`);
   }
   const root = tree.rootNode;
-  const sourceFile = toPosix(filePath);
+  const sourceFile = toPosix(displayPath ?? filePath);
   const builder = new ExtractionBuilder();
   const fileId = sourceFile;
   builder.addNode({ id: fileId, label: sourceFile, sourceFile, sourceLocation: "L1" });
@@ -1309,7 +1313,7 @@ function convertUsePath(segments) {
   }
   return segments.join("::");
 }
-async function extractRust(filePath) {
+async function extractRust(filePath, displayPath) {
   const parser = await createParser("rust");
   const raw = await fs7.readFile(filePath);
   const content = raw.toString("utf-8");
@@ -1318,7 +1322,7 @@ async function extractRust(filePath) {
     throw new Error(`extractRust: parser produced no tree for ${filePath}`);
   }
   const root = tree.rootNode;
-  const sourceFile = toPosix(filePath);
+  const sourceFile = toPosix(displayPath ?? filePath);
   const builder = new ExtractionBuilder();
   const fileId = sourceFile;
   builder.addNode({ id: fileId, label: sourceFile, sourceFile, sourceLocation: "L1" });
@@ -1531,10 +1535,10 @@ async function extractRust(filePath) {
         }
       }
     } else if (fn.type === "scoped_identifier") {
-      const path7 = fn.childForFieldName("path")?.text;
+      const path10 = fn.childForFieldName("path")?.text;
       const name = fn.childForFieldName("name")?.text;
-      if (path7 && name) {
-        const viaImport = importIndex.get(path7);
+      if (path10 && name) {
+        const viaImport = importIndex.get(path10);
         if (viaImport) {
           targetId = viaImport.id;
           confidence = "INFERRED";
@@ -1575,7 +1579,7 @@ function firstStringArgument(call) {
   if (!first || first.type !== "string") return null;
   return stripQuotes2(first.text);
 }
-async function extractTypeScript(filePath) {
+async function extractTypeScript(filePath, displayPath) {
   const ext = path3.extname(filePath);
   const grammar = grammarForExtension(ext);
   const parser = await createParser(grammar);
@@ -1586,7 +1590,7 @@ async function extractTypeScript(filePath) {
     throw new Error(`extractTypeScript: parser produced no tree for ${filePath}`);
   }
   const root = tree.rootNode;
-  const sourceFile = toPosix(filePath);
+  const sourceFile = toPosix(displayPath ?? filePath);
   const builder = new ExtractionBuilder();
   const fileId = sourceFile;
   builder.addNode({ id: fileId, label: sourceFile, sourceFile, sourceLocation: "L1" });
@@ -1903,13 +1907,13 @@ var EXTRACTOR_REGISTRY = {
   ".cs": extractCSharp,
   ".rb": extractRuby
 };
-async function extract(filePath) {
+async function extract(filePath, displayPath) {
   const ext = path4.extname(filePath);
   const extractor = EXTRACTOR_REGISTRY[ext];
   if (!extractor) {
     return { nodes: [], edges: [] };
   }
-  return extractor(filePath);
+  return extractor(filePath, displayPath);
 }
 
 // src/schema.ts
@@ -2012,6 +2016,107 @@ function buildGraph(extractions) {
   return graph;
 }
 
+// src/resolve.ts
+var CODE_EXTENSIONS2 = [
+  ".ts",
+  ".tsx",
+  ".mts",
+  ".cts",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".py",
+  ".go",
+  ".rs",
+  ".java",
+  ".cs",
+  ".rb"
+];
+function isOpaque(id) {
+  return id.startsWith("module:") || id.startsWith("external:") || id.startsWith("db:");
+}
+function stripKnownExtension(p) {
+  for (const ext of CODE_EXTENSIONS2) {
+    if (p.endsWith(ext)) return p.slice(0, -ext.length);
+  }
+  return null;
+}
+function candidatePaths(guessed) {
+  const stem = stripKnownExtension(guessed) ?? guessed;
+  const candidates = [];
+  for (const ext of CODE_EXTENSIONS2) candidates.push(`${stem}${ext}`);
+  for (const ext of CODE_EXTENSIONS2) candidates.push(`${guessed}/index${ext}`);
+  if (stem !== guessed) {
+    for (const ext of CODE_EXTENSIONS2) candidates.push(`${stem}/index${ext}`);
+  }
+  return candidates.filter((c) => c !== guessed);
+}
+function uniqueMatch(guessed, candidates, realIds) {
+  const matches = /* @__PURE__ */ new Set();
+  for (const candidate of candidates) {
+    if (realIds.has(candidate)) matches.add(candidate);
+  }
+  if (matches.size !== 1) return null;
+  return [...matches][0];
+}
+function resolveCrossFileReferences(extractions) {
+  const realIds = /* @__PURE__ */ new Set();
+  const realFiles = /* @__PURE__ */ new Set();
+  for (const extraction of extractions) {
+    for (const node of extraction.nodes) realIds.add(node.id);
+    for (const node of extraction.nodes) {
+      const sep2 = node.id.indexOf("::");
+      if (sep2 > 0) realFiles.add(node.id.slice(0, sep2));
+    }
+    for (const edge of extraction.edges) {
+      if (edge.relation === "contains") realFiles.add(edge.source);
+    }
+  }
+  const remap = /* @__PURE__ */ new Map();
+  const resolveId = (id) => {
+    if (isOpaque(id)) return null;
+    const cached = remap.get(id);
+    if (cached !== void 0) return cached;
+    const sep2 = id.indexOf("::");
+    let resolved;
+    if (sep2 > 0) {
+      if (realIds.has(id)) return null;
+      const guessedPath = id.slice(0, sep2);
+      const name = id.slice(sep2);
+      const candidates = candidatePaths(guessedPath).map((p) => `${p}${name}`);
+      resolved = uniqueMatch(id, candidates, realIds);
+    } else {
+      if (realFiles.has(id)) return null;
+      resolved = uniqueMatch(id, candidatePaths(id), realFiles);
+    }
+    if (resolved !== null) remap.set(id, resolved);
+    return resolved;
+  };
+  let resolvedEndpoints = 0;
+  for (const extraction of extractions) {
+    for (const edge of extraction.edges) {
+      const source = resolveId(edge.source);
+      if (source !== null) {
+        edge.source = source;
+        resolvedEndpoints++;
+      }
+      const target = resolveId(edge.target);
+      if (target !== null) {
+        edge.target = target;
+        resolvedEndpoints++;
+      }
+    }
+  }
+  let droppedPlaceholders = 0;
+  for (const extraction of extractions) {
+    const before = extraction.nodes.length;
+    extraction.nodes = extraction.nodes.filter((node) => !remap.has(node.id));
+    droppedPlaceholders += before - extraction.nodes.length;
+  }
+  return { resolvedEndpoints, droppedPlaceholders };
+}
+
 // src/cluster.ts
 import { createHash } from "crypto";
 import Graph2 from "graphology";
@@ -2408,29 +2513,81 @@ async function exportGraph(graph, options, report) {
   }
 }
 
-// src/pipeline.ts
+// src/extractionCache.ts
+import { createHash as createHash2 } from "crypto";
+import * as fs10 from "fs/promises";
 import * as path6 from "path";
+var ExtractionCache = class {
+  dir;
+  constructor(outDir) {
+    this.dir = path6.join(outDir, "cache");
+  }
+  key(relFile, content) {
+    return createHash2("sha256").update(relFile).update("\0").update(content).digest("hex");
+  }
+  async get(key) {
+    try {
+      const raw = await fs10.readFile(path6.join(this.dir, `${key}.json`), "utf-8");
+      const parsed = JSON.parse(raw);
+      if (!Array.isArray(parsed.nodes) || !Array.isArray(parsed.edges)) return null;
+      return parsed;
+    } catch {
+      return null;
+    }
+  }
+  async put(key, extraction) {
+    await fs10.mkdir(this.dir, { recursive: true });
+    await fs10.writeFile(path6.join(this.dir, `${key}.json`), JSON.stringify(extraction), "utf-8");
+  }
+};
+
+// src/pipeline.ts
+import * as fs11 from "fs/promises";
+import * as path7 from "path";
 async function runPipeline(root, options = {}) {
   const progress = options.onProgress ?? (() => {
   });
-  const resolvedRoot = path6.resolve(root);
+  const resolvedRoot = path7.resolve(root);
   progress(`Scanning ${resolvedRoot} ...`);
   const manifest = collectFiles(resolvedRoot);
   progress(
     `Found ${manifest.totalFiles} file(s) (${manifest.files.code.length} code, ${manifest.skippedSensitive.length} skipped as sensitive).`
   );
+  const outDir = options.outDir ?? path7.join(resolvedRoot, "graphify-out");
+  const cache = new ExtractionCache(outDir);
   progress("Extracting...");
   const extractions = [];
+  let cacheHits = 0;
   for (const relFile of manifest.files.code.sort((a, b) => a.localeCompare(b))) {
-    const filePath = path6.relative(process.cwd(), path6.join(resolvedRoot, relFile)) || relFile;
+    const filePath = path7.relative(process.cwd(), path7.join(resolvedRoot, relFile)) || relFile;
     try {
-      const extraction = await extract(filePath);
+      const key = cache.key(relFile, await fs11.readFile(path7.join(resolvedRoot, relFile)));
+      let extraction = options.update ? await cache.get(key) : null;
+      if (extraction) {
+        cacheHits++;
+      } else {
+        extraction = await extract(filePath, relFile);
+        await cache.put(key, extraction);
+      }
       extractions.push(extraction);
     } catch (error) {
       progress(`  extraction failed for ${relFile}: ${error.message}`);
       throw error;
     }
   }
+  if (options.update) {
+    progress(`  cache: ${cacheHits} hit(s), ${extractions.length - cacheHits} re-extracted.`);
+  }
+  if (options.extraExtractions && options.extraExtractions.length > 0) {
+    extractions.push(...options.extraExtractions);
+  }
+  progress("Resolving cross-file references...");
+  const resolveStats = resolveCrossFileReferences(extractions);
+  if (resolveStats.resolvedEndpoints > 0) {
+    progress(
+      `  re-pointed ${resolveStats.resolvedEndpoints} guessed reference(s) at real nodes (${resolveStats.droppedPlaceholders} placeholder node(s) dropped).`
+    );
+  }
   progress("Building graph...");
   const graph = buildGraph(extractions);
   progress(`Clustering (${options.algorithm ?? "louvain"})...`);
@@ -2439,7 +2596,6 @@ async function runPipeline(root, options = {}) {
   const analysis = analyze(graph);
   progress("Rendering report...");
   const report = renderReport(graph, analysis);
-  const outDir = options.outDir ?? path6.join(resolvedRoot, "graphify-out");
   progress(`Exporting to ${outDir} ...`);
   await exportGraph(
     graph,
@@ -2457,6 +2613,367 @@ async function runPipeline(root, options = {}) {
   return { manifest, graph, analysis, report };
 }
 
+// src/merge.ts
+import Graph3 from "graphology";
+var CONFIDENCE_RANK2 = { EXTRACTED: 3, INFERRED: 2, AMBIGUOUS: 1 };
+function strongerConfidence2(a, b) {
+  return CONFIDENCE_RANK2[a] >= CONFIDENCE_RANK2[b] ? a : b;
+}
+function isShared(id) {
+  return id.startsWith("external:") || id.startsWith("module:");
+}
+function namespaced(project, id) {
+  return isShared(id) ? id : `${project}/${id}`;
+}
+function mergeGraphs(entries) {
+  const names = entries.map((e) => e.name);
+  const duplicate = names.find((name, i) => names.indexOf(name) !== i);
+  if (duplicate !== void 0) {
+    throw new Error(`Duplicate project name in merge: "${duplicate}" \u2014 every entry needs a unique name.`);
+  }
+  const merged = new Graph3({ type: "directed", multi: true, allowSelfLoops: true });
+  const sorted = [...entries].sort((a, b) => a.name.localeCompare(b.name));
+  for (const { name, graph } of sorted) {
+    const nodeIds = [...graph.nodes()].sort((a, b) => a.localeCompare(b));
+    for (const id of nodeIds) {
+      const attrs = graph.getNodeAttributes(id);
+      const newId = namespaced(name, id);
+      if (merged.hasNode(newId)) {
+        merged.setNodeAttribute(newId, "project", "(shared)");
+        continue;
+      }
+      const sourceFile = attrs.sourceFile ?? "";
+      merged.addNode(newId, {
+        label: attrs.label ?? id,
+        sourceFile: isShared(id) || sourceFile === "" ? sourceFile : `${name}/${sourceFile}`,
+        sourceLocation: attrs.sourceLocation ?? "",
+        project: name
+      });
+    }
+    const edgeKeys = [...graph.edges()].sort((a, b) => a.localeCompare(b));
+    for (const edgeKey of edgeKeys) {
+      const attrs = graph.getEdgeAttributes(edgeKey);
+      const source = namespaced(name, graph.source(edgeKey));
+      const target = namespaced(name, graph.target(edgeKey));
+      const relation = String(attrs.relation);
+      const confidence = attrs.confidence;
+      const key = `${source}|${relation}|${target}`;
+      if (merged.hasEdge(key)) {
+        const existing = merged.getEdgeAttribute(key, "confidence");
+        merged.setEdgeAttribute(key, "confidence", strongerConfidence2(existing, confidence));
+        continue;
+      }
+      merged.addEdgeWithKey(key, source, target, { relation, confidence });
+    }
+  }
+  return merged;
+}
+
+// src/memory.ts
+import { createHash as createHash3 } from "crypto";
+import * as fs12 from "fs/promises";
+import * as path8 from "path";
+var OUTCOMES = /* @__PURE__ */ new Set(["useful", "dead_end", "corrected"]);
+var TYPES = /* @__PURE__ */ new Set(["query", "path", "explain", "affected"]);
+function validateResult(value) {
+  if (!value.question) throw new Error("save-result requires --question");
+  if (!value.answer) throw new Error("save-result requires --answer");
+  if (!OUTCOMES.has(value.outcome)) {
+    throw new Error(`--outcome must be one of: useful, dead_end, corrected (got "${value.outcome}")`);
+  }
+  if (!TYPES.has(value.type)) {
+    throw new Error(`--type must be one of: query, path, explain, affected (got "${value.type}")`);
+  }
+  if (value.outcome === "corrected" && !value.correction) {
+    throw new Error("--outcome corrected requires --correction with what the right answer was");
+  }
+}
+async function saveResult(entry, memoryDir, now = /* @__PURE__ */ new Date()) {
+  validateResult(entry);
+  await fs12.mkdir(memoryDir, { recursive: true });
+  const saved = { ...entry, savedAt: now.toISOString() };
+  const hash = createHash3("sha256").update(JSON.stringify(saved)).digest("hex").slice(0, 8);
+  const stamp = saved.savedAt.replace(/[:.]/g, "-");
+  const filePath = path8.join(memoryDir, `result-${stamp}-${hash}.json`);
+  await fs12.writeFile(filePath, JSON.stringify(saved, null, 2), "utf-8");
+  return filePath;
+}
+async function loadResults(memoryDir) {
+  let files;
+  try {
+    files = (await fs12.readdir(memoryDir)).filter((f) => f.startsWith("result-") && f.endsWith(".json"));
+  } catch {
+    return [];
+  }
+  const results = [];
+  for (const file of files.sort((a, b) => a.localeCompare(b))) {
+    try {
+      const parsed = JSON.parse(await fs12.readFile(path8.join(memoryDir, file), "utf-8"));
+      if (parsed.question && parsed.savedAt) results.push(parsed);
+    } catch {
+    }
+  }
+  return results;
+}
+function renderLessons(results, options = {}) {
+  const halfLife = options.halfLifeDays ?? 30;
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  const minCorroboration = options.minCorroboration ?? 2;
+  const weightOf = (savedAt) => {
+    const ageDays = Math.max(0, (now.getTime() - new Date(savedAt).getTime()) / 864e5);
+    return Math.pow(0.5, ageDays / halfLife);
+  };
+  const signals = /* @__PURE__ */ new Map();
+  const corrections = [];
+  for (const result of results) {
+    const weight = weightOf(result.savedAt);
+    for (const node of result.nodes ?? []) {
+      const signal = signals.get(node) ?? { useful: 0, deadEnd: 0, usefulCount: 0, deadEndCount: 0 };
+      if (result.outcome === "useful") {
+        signal.useful += weight;
+        signal.usefulCount++;
+      } else if (result.outcome === "dead_end") {
+        signal.deadEnd += weight;
+        signal.deadEndCount++;
+      }
+      signals.set(node, signal);
+    }
+    if (result.outcome === "corrected" && result.correction) {
+      corrections.push({ question: result.question, correction: result.correction, savedAt: result.savedAt });
+    }
+  }
+  const byScore = (kind) => [...signals.entries()].filter(([, s]) => kind === "useful" ? s.usefulCount >= minCorroboration : s.deadEndCount > 0).sort((a, b) => b[1][kind] - a[1][kind] || a[0].localeCompare(b[0])).slice(0, 10);
+  const lines = [
+    "# Graph lessons",
+    "",
+    `_Aggregated from ${results.length} saved result(s); signal half-life ${halfLife} day(s)._`,
+    "",
+    "## Nodes that keep answering",
+    ""
+  ];
+  const useful = byScore("useful");
+  if (useful.length === 0) {
+    lines.push(`(none yet with >= ${minCorroboration} corroborating results \u2014 keep saving results)`);
+  } else {
+    for (const [node, s] of useful) {
+      lines.push(`- **${node}** \u2014 score ${s.useful.toFixed(2)} across ${s.usefulCount} useful result(s)`);
+    }
+  }
+  lines.push("", "## Dead ends", "");
+  const deadEnds = byScore("deadEnd");
+  if (deadEnds.length === 0) {
+    lines.push("(none recorded)");
+  } else {
+    for (const [node, s] of deadEnds) {
+      lines.push(`- **${node}** \u2014 score ${s.deadEnd.toFixed(2)} across ${s.deadEndCount} dead-end result(s)`);
+    }
+  }
+  lines.push("", "## Corrections", "");
+  if (corrections.length === 0) {
+    lines.push("(none recorded)");
+  } else {
+    corrections.sort((a, b) => b.savedAt.localeCompare(a.savedAt));
+    for (const c of corrections.slice(0, 20)) {
+      lines.push(`- (${c.savedAt.slice(0, 10)}) Q: ${c.question}`);
+      lines.push(`  Right answer: ${c.correction}`);
+    }
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+// src/diff.ts
+import { execFile } from "child_process";
+import * as fs13 from "fs/promises";
+import * as os from "os";
+import * as path9 from "path";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+async function graphForDirectory(root) {
+  const manifest = collectFiles(root);
+  const extractions = [];
+  for (const relFile of manifest.files.code.sort((a, b) => a.localeCompare(b))) {
+    extractions.push(await extract(path9.join(root, relFile), relFile));
+  }
+  resolveCrossFileReferences(extractions);
+  return buildGraph(extractions);
+}
+async function checkoutRev(repoRoot, rev) {
+  const dest = await fs13.mkdtemp(path9.join(os.tmpdir(), `graphify-review-${rev.replace(/[^a-zA-Z0-9]/g, "_")}-`));
+  const { stdout } = await execFileAsync(
+    "git",
+    ["-C", repoRoot, "archive", "--format=tar", rev],
+    { encoding: "buffer", maxBuffer: 512 * 1024 * 1024 }
+  );
+  await new Promise((resolve4, reject) => {
+    const tar = execFile("tar", ["-x", "-C", dest], (error) => error ? reject(error) : resolve4());
+    tar.stdin?.end(stdout);
+  });
+  return dest;
+}
+function edgeSignature(graph, id) {
+  const signature = /* @__PURE__ */ new Set();
+  graph.forEachOutEdge(id, (_e, attrs, _s, target) => signature.add(`-> ${String(attrs.relation)} ${target}`));
+  graph.forEachInEdge(id, (_e, attrs, source) => signature.add(`<- ${String(attrs.relation)} ${source}`));
+  return signature;
+}
+function describeSymbol(graph, id) {
+  const attrs = graph.getNodeAttributes(id);
+  const impact = affectedBy(graph, id, { maxDepth: 3 });
+  const tests = testsForNode(graph, id);
+  return {
+    id,
+    label: attrs.label ?? id,
+    sourceFile: attrs.sourceFile ?? "",
+    blastRadius: impact?.affected.length ?? 0,
+    tests: tests?.testFiles.map((t) => t.file) ?? []
+  };
+}
+function entityIds(graph) {
+  const ids = /* @__PURE__ */ new Set();
+  graph.forEachNode((id) => {
+    if (id.includes("::")) ids.add(id);
+  });
+  return ids;
+}
+function diffGraphs(baseGraph, headGraph, base, head) {
+  const baseIds = entityIds(baseGraph);
+  const headIds = entityIds(headGraph);
+  const added = [];
+  const removed = [];
+  const rewired = [];
+  for (const id of [...headIds].sort((a, b) => a.localeCompare(b))) {
+    if (!baseIds.has(id)) {
+      added.push(describeSymbol(headGraph, id));
+      continue;
+    }
+    const before = edgeSignature(baseGraph, id);
+    const after = edgeSignature(headGraph, id);
+    const gained = [...after].filter((e) => !before.has(e)).sort((a, b) => a.localeCompare(b));
+    const lost = [...before].filter((e) => !after.has(e)).sort((a, b) => a.localeCompare(b));
+    if (gained.length > 0 || lost.length > 0) {
+      rewired.push({ ...describeSymbol(headGraph, id), gainedEdges: gained, lostEdges: lost });
+    }
+  }
+  for (const id of [...baseIds].sort((a, b) => a.localeCompare(b))) {
+    if (!headIds.has(id)) removed.push(describeSymbol(baseGraph, id));
+  }
+  return { base, head, added, removed, rewired };
+}
+async function reviewRevisions(repoRoot, base, head = "HEAD") {
+  const [baseDir, headDir] = await Promise.all([checkoutRev(repoRoot, base), checkoutRev(repoRoot, head)]);
+  try {
+    const [baseGraph, headGraph] = [await graphForDirectory(baseDir), await graphForDirectory(headDir)];
+    return diffGraphs(baseGraph, headGraph, base, head);
+  } finally {
+    await Promise.all([
+      fs13.rm(baseDir, { recursive: true, force: true }),
+      fs13.rm(headDir, { recursive: true, force: true })
+    ]);
+  }
+}
+function renderReview(diff) {
+  const lines = [
+    `# Structural review: ${diff.base}..${diff.head}`,
+    "",
+    `${diff.added.length} symbol(s) added, ${diff.removed.length} removed, ${diff.rewired.length} rewired.`,
+    ""
+  ];
+  const section = (title, symbols) => {
+    lines.push(`## ${title} (${symbols.length})`, "");
+    if (symbols.length === 0) {
+      lines.push("(none)", "");
+      return;
+    }
+    for (const s of symbols) {
+      const tests = s.tests.length > 0 ? ` | tests: ${s.tests.join(", ")}` : " | tests: none found";
+      lines.push(`- **${s.label}** (${s.sourceFile}) \u2014 blast radius ${s.blastRadius}${tests}`);
+      const r = s;
+      if (r.gainedEdges) {
+        for (const e of r.gainedEdges.slice(0, 5)) lines.push(`  - gained: ${e}`);
+        for (const e of r.lostEdges.slice(0, 5)) lines.push(`  - lost: ${e}`);
+      }
+    }
+    lines.push("");
+  };
+  section("Removed \u2014 check every caller", diff.removed);
+  section("Rewired \u2014 dependencies changed", diff.rewired);
+  section("Added", diff.added);
+  const allTests = /* @__PURE__ */ new Set();
+  for (const s of [...diff.removed, ...diff.rewired, ...diff.added]) {
+    for (const t of s.tests) allTests.add(t);
+  }
+  lines.push(`## Suggested test run (${allTests.size} file(s))`, "");
+  for (const t of [...allTests].sort((a, b) => a.localeCompare(b))) lines.push(`- ${t}`);
+  lines.push("");
+  return lines.join("\n");
+}
+
+// src/check.ts
+var DEPENDENCY_RELATIONS = /* @__PURE__ */ new Set([
+  "calls",
+  "imports",
+  "imports_from",
+  "inherits",
+  "implements",
+  "mixes_in",
+  "embeds",
+  "re_exports"
+]);
+function globToRegExp(glob) {
+  const escaped = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  const pattern = escaped.replace(
+    /\*\*|\*|\?/g,
+    (token) => token === "**" ? ".*" : token === "*" ? "[^/]*" : "[^/]"
+  );
+  return new RegExp(`^${pattern}$`);
+}
+function validateRules(value) {
+  const config = value;
+  if (!config || !Array.isArray(config.rules)) {
+    throw new Error('Rules file must be JSON of shape { "rules": [{ "name", "from", "disallow": [...] }] }');
+  }
+  for (const rule of config.rules) {
+    if (!rule.name || typeof rule.from !== "string" || !Array.isArray(rule.disallow)) {
+      throw new Error(`Malformed rule "${rule.name ?? "(unnamed)"}" \u2014 need name, from, and disallow[].`);
+    }
+  }
+  return config;
+}
+function checkRules(graph, config) {
+  const compiled = config.rules.map((rule) => ({
+    rule,
+    from: globToRegExp(rule.from),
+    disallow: rule.disallow.map(globToRegExp)
+  }));
+  const violations = [];
+  graph.forEachEdge((_edge, attrs, source, target) => {
+    const relation = String(attrs.relation);
+    if (!DEPENDENCY_RELATIONS.has(relation)) return;
+    const fromFile = graph.getNodeAttribute(source, "sourceFile") ?? "";
+    const toFile = graph.getNodeAttribute(target, "sourceFile") ?? "";
+    if (!fromFile || !toFile || fromFile === toFile) return;
+    for (const { rule, from, disallow } of compiled) {
+      if (!from.test(fromFile)) continue;
+      if (disallow.some((d) => d.test(toFile))) {
+        violations.push({
+          rule: rule.name,
+          reason: rule.reason,
+          fromFile,
+          fromNode: source,
+          toFile,
+          toNode: target,
+          relation
+        });
+      }
+    }
+  });
+  violations.sort(
+    (a, b) => a.rule.localeCompare(b.rule) || a.fromFile.localeCompare(b.fromFile) || a.toFile.localeCompare(b.toFile) || a.fromNode.localeCompare(b.fromNode)
+  );
+  return violations;
+}
+
 export {
   collectFiles,
   EXTRACTOR_REGISTRY,
@@ -2465,10 +2982,23 @@ export {
   ExtractionValidationError,
   validateExtraction,
   buildGraph,
+  resolveCrossFileReferences,
   cluster,
   analyze,
   renderReport,
   exportGraph,
-  runPipeline
+  ExtractionCache,
+  runPipeline,
+  mergeGraphs,
+  saveResult,
+  loadResults,
+  renderLessons,
+  graphForDirectory,
+  diffGraphs,
+  reviewRevisions,
+  renderReview,
+  globToRegExp,
+  validateRules,
+  checkRules
 };
-//# sourceMappingURL=chunk-DG5FECXV.js.map
+//# sourceMappingURL=chunk-EW23BLJC.js.map