@dreamtree-org/graphify 1.1.1 → 1.1.2

package/dist/cli/index.cjs

@@ -156,7 +156,7 @@ function validateDsn(dsn) {
     }
   };
 }
-function validateGraphPath(path17, base) {
+function validateGraphPath(path18, base) {
   const baseDir = base ?? nodePath.join(process.cwd(), "graphify-out");
   let resolvedBase;
   try {
@@ -164,7 +164,7 @@ function validateGraphPath(path17, base) {
   } catch {
     throw new Error(`Base directory does not exist: ${baseDir}`);
   }
-  const candidate = nodePath.isAbsolute(path17) ? path17 : nodePath.join(resolvedBase, path17);
+  const candidate = nodePath.isAbsolute(path18) ? path18 : nodePath.join(resolvedBase, path18);
   const resolvedCandidate = nodePath.resolve(candidate);
   let realCandidate = resolvedCandidate;
   try {
@@ -174,7 +174,7 @@ function validateGraphPath(path17, base) {
   const relative4 = nodePath.relative(resolvedBase, realCandidate);
   const escapes = relative4 === ".." || relative4.startsWith(`..${nodePath.sep}`) || nodePath.isAbsolute(relative4);
   if (escapes) {
-    throw new Error(`Path escapes graphify-out/: ${path17}`);
+    throw new Error(`Path escapes graphify-out/: ${path18}`);
   }
   return realCandidate;
 }
@@ -443,25 +443,25 @@ function shortestPath(graph, fromQuery, toQuery) {
   if (!visited.has(to.id)) {
     return { from, to, found: false, path: [], edges: [] };
   }
-  const path17 = [to.id];
+  const path18 = [to.id];
   let cursor = to.id;
   while (cursor !== from.id) {
     const prev = predecessor.get(cursor);
     if (!prev) break;
-    path17.unshift(prev);
+    path18.unshift(prev);
     cursor = prev;
   }
   const edges = [];
-  for (let i = 0; i < path17.length - 1; i++) {
-    const a = path17[i];
-    const b = path17[i + 1];
+  for (let i = 0; i < path18.length - 1; i++) {
+    const a = path18[i];
+    const b = path18[i + 1];
     const key = graph.edges(a, b)[0] ?? graph.edges(b, a)[0];
     if (key) {
       const attrs = graph.getEdgeAttributes(key);
       edges.push({ source: a, target: b, relation: String(attrs.relation), confidence: String(attrs.confidence) });
     }
   }
-  return { from, to, found: true, path: path17, edges };
+  return { from, to, found: true, path: path18, edges };
 }
 function explainNode(graph, query) {
   const match = resolveNode(graph, query);
@@ -607,6 +607,78 @@ var init_impact = __esm({
   }
 });
 
+// src/testmap.ts
+function isTestFile(path18) {
+  return TEST_FILE_PATTERNS.some((p) => p.test(path18));
+}
+function selectionFromImpact(graph, targetIds, targetLabel) {
+  const best = /* @__PURE__ */ new Map();
+  let affectedNodeCount = 0;
+  for (const id of targetIds) {
+    const impact = affectedBy(graph, id, { maxDepth: TEST_REACH_DEPTH, limit: TEST_REACH_LIMIT });
+    if (!impact) continue;
+    affectedNodeCount += impact.affected.length;
+    for (const node of impact.affected) {
+      if (!isTestFile(node.sourceFile)) continue;
+      const existing = best.get(node.sourceFile);
+      if (!existing || node.depth < existing.depth) {
+        best.set(node.sourceFile, { depth: node.depth, via: node.via.dependsOn });
+      }
+    }
+  }
+  const testFiles = [...best.entries()].map(([file, info]) => ({ file, depth: info.depth, via: info.via })).sort((a, b) => a.depth - b.depth || a.file.localeCompare(b.file));
+  return { target: targetLabel, testFiles, affectedNodeCount };
+}
+function testsForNode(graph, nodeQuery) {
+  const match = resolveNode(graph, nodeQuery);
+  if (!match) return null;
+  return selectionFromImpact(graph, [match.id], match.id);
+}
+function testsForChangedFiles(graph, changedFiles) {
+  const fileIds = [];
+  const selfSelected = /* @__PURE__ */ new Map();
+  for (const file of changedFiles) {
+    if (isTestFile(file)) {
+      selfSelected.set(file, { depth: 0, via: "(changed directly)" });
+      continue;
+    }
+    if (graph.hasNode(file)) fileIds.push(file);
+  }
+  const selection = selectionFromImpact(graph, fileIds, changedFiles.join(", "));
+  for (const [file, info] of selfSelected) {
+    if (!selection.testFiles.some((t) => t.file === file)) {
+      selection.testFiles.push({ file, depth: info.depth, via: info.via });
+    }
+  }
+  selection.testFiles.sort((a, b) => a.depth - b.depth || a.file.localeCompare(b.file));
+  return selection;
+}
+var TEST_FILE_PATTERNS, TEST_REACH_DEPTH, TEST_REACH_LIMIT;
+var init_testmap = __esm({
+  "src/testmap.ts"() {
+    "use strict";
+    init_cjs_shims();
+    init_impact();
+    init_query();
+    TEST_FILE_PATTERNS = [
+      /(^|\/)tests?\//,
+      // tests/ or test/ directory
+      /(^|\/)__tests__\//,
+      /(^|\/)spec\//,
+      /\.test\.[cm]?[jt]sx?$/,
+      /\.spec\.[cm]?[jt]sx?$/,
+      /(^|\/)test_[^/]+\.py$/,
+      /_test\.py$/,
+      /_test\.go$/,
+      /Tests?\.(java|cs)$/,
+      /_spec\.rb$/,
+      /_test\.rb$/
+    ];
+    TEST_REACH_DEPTH = 4;
+    TEST_REACH_LIMIT = 2e3;
+  }
+});
+
 // src/context.ts
 function lineNumberOf(sourceLocation) {
   const match = /^L(\d+)$/.exec(sourceLocation);
@@ -641,7 +713,7 @@ function snippetRange(startLine, fileLineCount, entityStartsInFile, maxLines) {
   const hardEnd = nextStart !== void 0 ? nextStart - 1 : fileLineCount;
   return { start: startLine, end: Math.min(hardEnd, startLine + maxLines - 1) };
 }
-async function buildContextPack(graph, task, readFile20, options = {}) {
+async function buildContextPack(graph, task, readFile21, options = {}) {
   const tokenBudget = options.tokenBudget ?? DEFAULT_CONTEXT_BUDGET;
   const maxSnippetLines = options.maxSnippetLines ?? DEFAULT_MAX_SNIPPET_LINES;
   const ranked = rankForTask(graph, task, options.maxSeeds);
@@ -662,7 +734,7 @@ async function buildContextPack(graph, task, readFile20, options = {}) {
     if (cached !== void 0) return cached;
     let lines;
     try {
-      lines = (await readFile20(file)).split("\n");
+      lines = (await readFile21(file)).split("\n");
     } catch {
       lines = null;
     }
@@ -748,78 +820,6 @@ var init_context = __esm({
   }
 });
 
-// src/testmap.ts
-function isTestFile(path17) {
-  return TEST_FILE_PATTERNS.some((p) => p.test(path17));
-}
-function selectionFromImpact(graph, targetIds, targetLabel) {
-  const best = /* @__PURE__ */ new Map();
-  let affectedNodeCount = 0;
-  for (const id of targetIds) {
-    const impact = affectedBy(graph, id, { maxDepth: TEST_REACH_DEPTH, limit: TEST_REACH_LIMIT });
-    if (!impact) continue;
-    affectedNodeCount += impact.affected.length;
-    for (const node of impact.affected) {
-      if (!isTestFile(node.sourceFile)) continue;
-      const existing = best.get(node.sourceFile);
-      if (!existing || node.depth < existing.depth) {
-        best.set(node.sourceFile, { depth: node.depth, via: node.via.dependsOn });
-      }
-    }
-  }
-  const testFiles = [...best.entries()].map(([file, info]) => ({ file, depth: info.depth, via: info.via })).sort((a, b) => a.depth - b.depth || a.file.localeCompare(b.file));
-  return { target: targetLabel, testFiles, affectedNodeCount };
-}
-function testsForNode(graph, nodeQuery) {
-  const match = resolveNode(graph, nodeQuery);
-  if (!match) return null;
-  return selectionFromImpact(graph, [match.id], match.id);
-}
-function testsForChangedFiles(graph, changedFiles) {
-  const fileIds = [];
-  const selfSelected = /* @__PURE__ */ new Map();
-  for (const file of changedFiles) {
-    if (isTestFile(file)) {
-      selfSelected.set(file, { depth: 0, via: "(changed directly)" });
-      continue;
-    }
-    if (graph.hasNode(file)) fileIds.push(file);
-  }
-  const selection = selectionFromImpact(graph, fileIds, changedFiles.join(", "));
-  for (const [file, info] of selfSelected) {
-    if (!selection.testFiles.some((t) => t.file === file)) {
-      selection.testFiles.push({ file, depth: info.depth, via: info.via });
-    }
-  }
-  selection.testFiles.sort((a, b) => a.depth - b.depth || a.file.localeCompare(b.file));
-  return selection;
-}
-var TEST_FILE_PATTERNS, TEST_REACH_DEPTH, TEST_REACH_LIMIT;
-var init_testmap = __esm({
-  "src/testmap.ts"() {
-    "use strict";
-    init_cjs_shims();
-    init_impact();
-    init_query();
-    TEST_FILE_PATTERNS = [
-      /(^|\/)tests?\//,
-      // tests/ or test/ directory
-      /(^|\/)__tests__\//,
-      /(^|\/)spec\//,
-      /\.test\.[cm]?[jt]sx?$/,
-      /\.spec\.[cm]?[jt]sx?$/,
-      /(^|\/)test_[^/]+\.py$/,
-      /_test\.py$/,
-      /_test\.go$/,
-      /Tests?\.(java|cs)$/,
-      /_spec\.rb$/,
-      /_test\.rb$/
-    ];
-    TEST_REACH_DEPTH = 4;
-    TEST_REACH_LIMIT = 2e3;
-  }
-});
-
 // src/mcp/server.ts
 var server_exports = {};
 __export(server_exports, {
@@ -914,7 +914,7 @@ function createGraphifyMcpServer(outDir) {
     },
     async ({ task, budget }) => {
       const graph = await loadGraph(outDir);
-      const pack = await buildContextPack(graph, task, (p) => fs22.readFile(p, "utf-8"), {
+      const pack = await buildContextPack(graph, task, (p) => fs23.readFile(p, "utf-8"), {
         tokenBudget: budget
       });
       return textResult(renderContextPack(pack));
@@ -940,23 +940,23 @@ function createGraphifyMcpServer(outDir) {
   return server;
 }
 async function startServer(graphPath, transport = new import_stdio.StdioServerTransport()) {
-  const outDir = path15.dirname(path15.resolve(graphPath));
-  const fileName = path15.basename(graphPath);
+  const outDir = path16.dirname(path16.resolve(graphPath));
+  const fileName = path16.basename(graphPath);
   validateGraphPath(fileName, outDir);
   const server = createGraphifyMcpServer(outDir);
   await server.connect(transport);
 }
 async function main(argv = process.argv) {
-  const graphPath = argv[2] ?? path15.join(process.cwd(), "graphify-out", "graph.json");
+  const graphPath = argv[2] ?? path16.join(process.cwd(), "graphify-out", "graph.json");
   await startServer(graphPath);
 }
-var fs22, path15, import_mcp, import_stdio, import_zod2;
+var fs23, path16, import_mcp, import_stdio, import_zod2;
 var init_server = __esm({
   "src/mcp/server.ts"() {
     "use strict";
     init_cjs_shims();
-    fs22 = __toESM(require("fs/promises"), 1);
-    path15 = __toESM(require("path"), 1);
+    fs23 = __toESM(require("fs/promises"), 1);
+    path16 = __toESM(require("path"), 1);
     import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
     import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
     import_zod2 = require("zod");
@@ -1131,9 +1131,9 @@ var init_mysql = __esm({
 // src/cli/index.ts
 init_cjs_shims();
 var import_node_child_process3 = require("child_process");
-var fs23 = __toESM(require("fs/promises"), 1);
+var fs24 = __toESM(require("fs/promises"), 1);
 var os3 = __toESM(require("os"), 1);
-var path16 = __toESM(require("path"), 1);
+var path17 = __toESM(require("path"), 1);
 var import_node_util3 = require("util");
 var import_chokidar = require("chokidar");
 var import_commander = require("commander");
@@ -1465,8 +1465,8 @@ init_graphStore();
 
 // src/pipeline.ts
 init_cjs_shims();
-var fs13 = __toESM(require("fs/promises"), 1);
-var path8 = __toESM(require("path"), 1);
+var fs14 = __toESM(require("fs/promises"), 1);
+var path9 = __toESM(require("path"), 1);
 
 // src/build.ts
 init_cjs_shims();
@@ -3138,10 +3138,10 @@ async function extractRust(filePath, displayPath) {
         }
       }
     } else if (fn.type === "scoped_identifier") {
-      const path17 = fn.childForFieldName("path")?.text;
+      const path18 = fn.childForFieldName("path")?.text;
       const name = fn.childForFieldName("name")?.text;
-      if (path17 && name) {
-        const viaImport = importIndex.get(path17);
+      if (path18 && name) {
+        const viaImport = importIndex.get(path18);
         if (viaImport) {
           targetId = viaImport.id;
           confidence = "INFERRED";
@@ -3601,6 +3601,8 @@ function renderReport(graph, analysis, now = /* @__PURE__ */ new Date()) {
 
 // src/resolve.ts
 init_cjs_shims();
+var fs13 = __toESM(require("fs/promises"), 1);
+var path8 = __toESM(require("path"), 1);
 var CODE_EXTENSIONS2 = [
   ".ts",
   ".tsx",
@@ -3620,6 +3622,29 @@ var CODE_EXTENSIONS2 = [
 function isOpaque(id) {
   return id.startsWith("module:") || id.startsWith("external:") || id.startsWith("db:");
 }
+var SELF_IMPORT_STEMS = (subpath) => subpath === "" ? ["index", "src/index", "lib/index", "source/index", "src/main"] : [
+  subpath,
+  `src/${subpath}`,
+  `lib/${subpath}`,
+  `source/${subpath}`,
+  `${subpath}/index`,
+  `src/${subpath}/index`,
+  `lib/${subpath}/index`
+];
+function selfImportCandidates(spec, selfNames) {
+  const selfName = selfNames.find((n) => spec === n || spec.startsWith(`${n}/`));
+  if (selfName === void 0) return null;
+  const subpath = spec === selfName ? "" : spec.slice(selfName.length + 1);
+  return SELF_IMPORT_STEMS(subpath).flatMap((stem) => CODE_EXTENSIONS2.map((ext) => `${stem}${ext}`));
+}
+async function readSelfNames(root) {
+  try {
+    const pkg = JSON.parse(await fs13.readFile(path8.join(root, "package.json"), "utf-8"));
+    return typeof pkg.name === "string" && pkg.name.length > 0 ? [pkg.name] : [];
+  } catch {
+    return [];
+  }
+}
 function stripKnownExtension(p) {
   for (const ext of CODE_EXTENSIONS2) {
     if (p.endsWith(ext)) return p.slice(0, -ext.length);
@@ -3644,11 +3669,16 @@ function uniqueMatch(guessed, candidates, realIds) {
   if (matches.size !== 1) return null;
   return [...matches][0];
 }
-function resolveCrossFileReferences(extractions) {
+function resolveCrossFileReferences(extractions, options = {}) {
+  const selfNames = options.selfNames ?? [];
   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);
+    const first = extraction.nodes[0];
+    if (first && first.id === first.sourceFile && !isOpaque(first.id)) {
+      realFiles.add(first.id);
+    }
     for (const node of extraction.nodes) {
       const sep3 = node.id.indexOf("::");
       if (sep3 > 0) realFiles.add(node.id.slice(0, sep3));
@@ -3659,6 +3689,19 @@ function resolveCrossFileReferences(extractions) {
   }
   const remap = /* @__PURE__ */ new Map();
   const resolveId = (id) => {
+    if (id.startsWith("module:") && selfNames.length > 0) {
+      const cachedSelf = remap.get(id);
+      if (cachedSelf !== void 0) return cachedSelf;
+      const candidates = selfImportCandidates(id.slice("module:".length), selfNames);
+      if (candidates !== null) {
+        const resolved2 = uniqueMatch(id, candidates, realFiles);
+        if (resolved2 !== null) {
+          remap.set(id, resolved2);
+          return resolved2;
+        }
+      }
+      return null;
+    }
     if (isOpaque(id)) return null;
     const cached = remap.get(id);
     if (cached !== void 0) return cached;
@@ -3705,21 +3748,21 @@ function resolveCrossFileReferences(extractions) {
 async function runPipeline(root, options = {}) {
   const progress = options.onProgress ?? (() => {
   });
-  const resolvedRoot = path8.resolve(root);
+  const resolvedRoot = path9.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 ?? path8.join(resolvedRoot, "graphify-out");
+  const outDir = options.outDir ?? path9.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 = path8.relative(process.cwd(), path8.join(resolvedRoot, relFile)) || relFile;
+    const filePath = path9.relative(process.cwd(), path9.join(resolvedRoot, relFile)) || relFile;
     try {
-      const key = cache.key(relFile, await fs13.readFile(path8.join(resolvedRoot, relFile)));
+      const key = cache.key(relFile, await fs14.readFile(path9.join(resolvedRoot, relFile)));
       let extraction = options.update ? await cache.get(key) : null;
       if (extraction) {
         cacheHits++;
@@ -3740,7 +3783,9 @@ async function runPipeline(root, options = {}) {
     extractions.push(...options.extraExtractions);
   }
   progress("Resolving cross-file references...");
-  const resolveStats = resolveCrossFileReferences(extractions);
+  const resolveStats = resolveCrossFileReferences(extractions, {
+    selfNames: await readSelfNames(resolvedRoot)
+  });
   if (resolveStats.resolvedEndpoints > 0) {
     progress(
       `  re-pointed ${resolveStats.resolvedEndpoints} guessed reference(s) at real nodes (${resolveStats.droppedPlaceholders} placeholder node(s) dropped).`
@@ -3797,9 +3842,10 @@ async function runAffected(nodeName, options = {}) {
       console.log("");
       console.log(currentDepth === 1 ? "Directly affected:" : `Affected at depth ${currentDepth}:`);
     }
-    const location = node.sourceLocation ? `:${node.sourceLocation}` : "";
+    const isPlaceholder = node.sourceFile === "<unknown>" || node.sourceFile === "<external>" || node.sourceFile === "";
+    const where = isPlaceholder ? "(reference only)" : `${node.sourceFile}${node.sourceLocation ? `:${node.sourceLocation}` : ""}`;
     console.log(
-      `  ${node.label} \u2014 ${node.sourceFile}${location} (--${node.via.relation}--> ${node.via.dependsOn}, ${node.via.confidence})`
+      `  ${node.label} \u2014 ${where} (--${node.via.relation}--> ${node.via.dependsOn}, ${node.via.confidence})`
     );
   }
   console.log("");
@@ -3814,11 +3860,12 @@ async function runAffected(nodeName, options = {}) {
 
 // src/cli/commands/benchmark.ts
 init_cjs_shims();
-var fs14 = __toESM(require("fs/promises"), 1);
+var fs15 = __toESM(require("fs/promises"), 1);
 init_graphStore();
 init_query();
+init_testmap();
 var tokensOf = (text) => Math.ceil(text.length / 4);
-async function benchmarkQuestion(graph, question, readFile20) {
+async function benchmarkQuestion(graph, question, readFile21) {
   const result = queryGraph(graph, question);
   const graphTokens = tokensOf(JSON.stringify(result));
   const sourceFiles = /* @__PURE__ */ new Set();
@@ -3832,7 +3879,7 @@ async function benchmarkQuestion(graph, question, readFile20) {
   let filesMissing = 0;
   for (const file of [...sourceFiles].sort((a, b) => a.localeCompare(b))) {
     try {
-      naiveTokens += tokensOf(await readFile20(file));
+      naiveTokens += tokensOf(await readFile21(file));
       filesRead++;
     } catch {
       filesMissing++;
@@ -3847,12 +3894,14 @@ async function benchmarkQuestion(graph, question, readFile20) {
     filesMissing
   };
 }
+var NON_QUESTION_FILE = /(^|\/)(examples?|scripts?|bench(?:mark)?s?|fixtures?|docs?|\.github)\/|\.(config|conf)\.[^/]+$|(^|\/)(rollup|webpack|vite|vitest|jest|babel|tsup|eslint|prettier)\.[^/]*$/i;
 function defaultQuestions(graph, count = 5) {
   const entries = [...graph.nodes()].map((id) => ({
     id,
     degree: graph.degree(id),
-    label: graph.getNodeAttribute(id, "label") ?? id
-  })).filter((e) => e.id.includes("::")).sort((a, b) => b.degree - a.degree || a.id.localeCompare(b.id));
+    label: graph.getNodeAttribute(id, "label") ?? id,
+    file: graph.getNodeAttribute(id, "sourceFile") ?? ""
+  })).filter((e) => e.id.includes("::")).filter((e) => !isTestFile(e.file) && !NON_QUESTION_FILE.test(e.file)).sort((a, b) => b.degree - a.degree || a.id.localeCompare(b.id));
   return entries.slice(0, count).map((e) => `how does ${e.label} work`);
 }
 async function runBenchmark(questions) {
@@ -3864,7 +3913,7 @@ async function runBenchmark(questions) {
   }
   const rows = [];
   for (const question of effective) {
-    rows.push(await benchmarkQuestion(graph, question, (p) => fs14.readFile(p, "utf-8")));
+    rows.push(await benchmarkQuestion(graph, question, (p) => fs15.readFile(p, "utf-8")));
   }
   console.log("Token cost per question \u2014 graph answer vs reading the files it touches:\n");
   for (const row of rows) {
@@ -3887,8 +3936,8 @@ Average reduction: ${avg.toFixed(1)}x across ${scored.length} question(s).`);
 
 // src/cli/commands/check.ts
 init_cjs_shims();
-var fs15 = __toESM(require("fs/promises"), 1);
-var path9 = __toESM(require("path"), 1);
+var fs16 = __toESM(require("fs/promises"), 1);
+var path10 = __toESM(require("path"), 1);
 
 // src/check.ts
 init_cjs_shims();
@@ -3959,10 +4008,10 @@ function checkRules(graph, config) {
 // src/cli/commands/check.ts
 init_graphStore();
 async function runCheck(options = {}) {
-  const rulesPath = path9.resolve(options.rules ?? "graphify.rules.json");
+  const rulesPath = path10.resolve(options.rules ?? "graphify.rules.json");
   let raw;
   try {
-    raw = await fs15.readFile(rulesPath, "utf-8");
+    raw = await fs16.readFile(rulesPath, "utf-8");
   } catch {
     throw new Error(
       `No rules file at ${rulesPath} \u2014 create graphify.rules.json with { "rules": [{ "name": "...", "from": "src/a/**", "disallow": ["src/b/**"] }] }.`
@@ -3985,12 +4034,12 @@ async function runCheck(options = {}) {
 
 // src/cli/commands/context.ts
 init_cjs_shims();
-var fs16 = __toESM(require("fs/promises"), 1);
+var fs17 = __toESM(require("fs/promises"), 1);
 init_context();
 init_graphStore();
 async function runContext(task, options = {}) {
   const graph = await loadGraph();
-  const pack = await buildContextPack(graph, task, (p) => fs16.readFile(p, "utf-8"), {
+  const pack = await buildContextPack(graph, task, (p) => fs17.readFile(p, "utf-8"), {
     tokenBudget: options.budget
   });
   console.log(renderContextPack(pack));
@@ -4007,9 +4056,13 @@ async function runExplain(nodeName) {
     console.log(`No node matched "${nodeName}".`);
     return;
   }
-  const location = result.sourceLocation ? `:${result.sourceLocation}` : "";
   console.log(result.label);
-  console.log(`  location: ${result.sourceFile}${location}`);
+  if (result.sourceFile === "<unknown>" || result.sourceFile === "<external>" || result.sourceFile === "") {
+    console.log("  location: (reference only \u2014 no declaration seen; check its outgoing edges for the real definition)");
+  } else {
+    const location = result.sourceLocation ? `:${result.sourceLocation}` : "";
+    console.log(`  location: ${result.sourceFile}${location}`);
+  }
   if (result.communityLabel) {
     console.log(`  community: ${result.communityLabel}`);
   }
@@ -4039,9 +4092,9 @@ init_cjs_shims();
 // src/diff.ts
 init_cjs_shims();
 var import_node_child_process = require("child_process");
-var fs17 = __toESM(require("fs/promises"), 1);
+var fs18 = __toESM(require("fs/promises"), 1);
 var os = __toESM(require("os"), 1);
-var path10 = __toESM(require("path"), 1);
+var path11 = __toESM(require("path"), 1);
 var import_node_util = require("util");
 init_impact();
 init_testmap();
@@ -4050,13 +4103,13 @@ 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(path10.join(root, relFile), relFile));
+    extractions.push(await extract(path11.join(root, relFile), relFile));
   }
-  resolveCrossFileReferences(extractions);
+  resolveCrossFileReferences(extractions, { selfNames: await readSelfNames(root) });
   return buildGraph(extractions);
 }
 async function checkoutRev(repoRoot, rev) {
-  const dest = await fs17.mkdtemp(path10.join(os.tmpdir(), `graphify-review-${rev.replace(/[^a-zA-Z0-9]/g, "_")}-`));
+  const dest = await fs18.mkdtemp(path11.join(os.tmpdir(), `graphify-review-${rev.replace(/[^a-zA-Z0-9]/g, "_")}-`));
   const { stdout } = await execFileAsync(
     "git",
     ["-C", repoRoot, "archive", "--format=tar", rev],
@@ -4124,8 +4177,8 @@ async function reviewRevisions(repoRoot, base, head = "HEAD") {
     return diffGraphs(baseGraph, headGraph, base, head);
   } finally {
     await Promise.all([
-      fs17.rm(baseDir, { recursive: true, force: true }),
-      fs17.rm(headDir, { recursive: true, force: true })
+      fs18.rm(baseDir, { recursive: true, force: true }),
+      fs18.rm(headDir, { recursive: true, force: true })
     ]);
   }
 }
@@ -4217,9 +4270,9 @@ async function runTests(nodeQuery, options = {}) {
 
 // src/cli/commands/global.ts
 init_cjs_shims();
-var fs18 = __toESM(require("fs/promises"), 1);
+var fs19 = __toESM(require("fs/promises"), 1);
 var os2 = __toESM(require("os"), 1);
-var path11 = __toESM(require("path"), 1);
+var path12 = __toESM(require("path"), 1);
 init_graphStore();
 
 // src/merge.ts
@@ -4281,14 +4334,14 @@ function mergeGraphs(entries) {
 
 // src/cli/commands/global.ts
 function registryDir() {
-  return path11.join(os2.homedir(), ".graphify");
+  return path12.join(os2.homedir(), ".graphify");
 }
 function registryPath() {
-  return path11.join(registryDir(), "global.json");
+  return path12.join(registryDir(), "global.json");
 }
 async function readRegistry() {
   try {
-    const raw = await fs18.readFile(registryPath(), "utf-8");
+    const raw = await fs19.readFile(registryPath(), "utf-8");
     const parsed = JSON.parse(raw);
     const projects = parsed.projects;
     if (!Array.isArray(projects)) return { projects: [] };
@@ -4298,23 +4351,23 @@ async function readRegistry() {
   }
 }
 async function writeRegistry(registry) {
-  await fs18.mkdir(registryDir(), { recursive: true });
-  await fs18.writeFile(registryPath(), JSON.stringify(registry, null, 2), "utf-8");
+  await fs19.mkdir(registryDir(), { recursive: true });
+  await fs19.writeFile(registryPath(), JSON.stringify(registry, null, 2), "utf-8");
 }
 async function projectNameFor(root) {
   try {
-    const raw = await fs18.readFile(path11.join(root, "package.json"), "utf-8");
+    const raw = await fs19.readFile(path12.join(root, "package.json"), "utf-8");
     const name = JSON.parse(raw).name;
     if (typeof name === "string" && name.length > 0) return name;
   } catch {
   }
-  return path11.basename(root);
+  return path12.basename(root);
 }
 async function runGlobalAdd(target = ".") {
-  const root = path11.resolve(target);
-  const graphJson = path11.join(root, "graphify-out", "graph.json");
+  const root = path12.resolve(target);
+  const graphJson = path12.join(root, "graphify-out", "graph.json");
   try {
-    await fs18.access(graphJson);
+    await fs19.access(graphJson);
   } catch {
     throw new Error(`${root} has no graphify-out/graph.json \u2014 run \`graphify ${target}\` first, then add it.`);
   }
@@ -4385,9 +4438,9 @@ async function runGlobalBuild(options = {}) {
     throw new Error("No projects registered. Add some with `graphify global add <path>` first.");
   }
   const entries = await loadEntries(
-    registry.projects.map((p) => ({ name: p.name, outDir: path11.join(p.root, "graphify-out") }))
+    registry.projects.map((p) => ({ name: p.name, outDir: path12.join(p.root, "graphify-out") }))
   );
-  await mergeAndExport(entries, path11.resolve(options.out ?? path11.join(registryDir(), "global-out")));
+  await mergeAndExport(entries, path12.resolve(options.out ?? path12.join(registryDir(), "global-out")));
 }
 async function runMerge(targets, options = {}) {
   if (targets.length < 2) {
@@ -4395,8 +4448,8 @@ async function runMerge(targets, options = {}) {
   }
   const sources = [];
   for (const target of targets) {
-    const root = path11.resolve(target);
-    sources.push({ name: await projectNameFor(root), outDir: path11.join(root, "graphify-out") });
+    const root = path12.resolve(target);
+    sources.push({ name: await projectNameFor(root), outDir: path12.join(root, "graphify-out") });
   }
   const names = sources.map((s) => s.name);
   const duplicate = names.find((name, i) => names.indexOf(name) !== i);
@@ -4404,13 +4457,13 @@ async function runMerge(targets, options = {}) {
     throw new Error(`Two of the given projects resolve to the same name ("${duplicate}") \u2014 rename one.`);
   }
   const entries = await loadEntries(sources);
-  await mergeAndExport(entries, path11.resolve(options.out ?? "graphify-merged"));
+  await mergeAndExport(entries, path12.resolve(options.out ?? "graphify-merged"));
 }
 
 // src/cli/commands/hook.ts
 init_cjs_shims();
-var fs19 = __toESM(require("fs/promises"), 1);
-var path12 = __toESM(require("path"), 1);
+var fs20 = __toESM(require("fs/promises"), 1);
+var path13 = __toESM(require("path"), 1);
 var MARKER_BEGIN = "# >>> graphify >>>";
 var MARKER_END = "# <<< graphify <<<";
 var HOOK_NAMES = ["post-commit", "post-merge"];
@@ -4421,34 +4474,34 @@ var HOOK_BLOCK = `${MARKER_BEGIN}
 (graphify . --update --no-viz >/dev/null 2>&1 &)
 ${MARKER_END}`;
 async function hooksDir(cwd) {
-  const gitDir = path12.join(cwd, ".git");
+  const gitDir = path13.join(cwd, ".git");
   let stats;
   try {
-    stats = await fs19.stat(gitDir);
+    stats = await fs20.stat(gitDir);
   } catch {
     throw new Error(`${cwd} is not a git repository (no .git directory) \u2014 run this from the repo root.`);
   }
   if (!stats.isDirectory()) {
-    const content = (await fs19.readFile(gitDir, "utf-8")).trim();
+    const content = (await fs20.readFile(gitDir, "utf-8")).trim();
     const match = /^gitdir:\s*(.+)$/.exec(content);
     if (!match) throw new Error(`${gitDir} exists but is neither a directory nor a gitdir pointer.`);
-    return path12.resolve(cwd, match[1], "hooks");
+    return path13.resolve(cwd, match[1], "hooks");
   }
-  return path12.join(gitDir, "hooks");
+  return path13.join(gitDir, "hooks");
 }
 async function runHookInstall(cwd = process.cwd()) {
   const dir = await hooksDir(cwd);
-  await fs19.mkdir(dir, { recursive: true });
+  await fs20.mkdir(dir, { recursive: true });
   const results = [];
   for (const hook of HOOK_NAMES) {
-    const hookPath = path12.join(dir, hook);
+    const hookPath = path13.join(dir, hook);
     let existing = null;
     try {
-      existing = await fs19.readFile(hookPath, "utf-8");
+      existing = await fs20.readFile(hookPath, "utf-8");
     } catch {
     }
     if (existing === null) {
-      await fs19.writeFile(hookPath, `#!/bin/sh
+      await fs20.writeFile(hookPath, `#!/bin/sh
 ${HOOK_BLOCK}
 `, { mode: 493 });
       results.push({ hook, path: hookPath, action: "created" });
@@ -4456,9 +4509,9 @@ ${HOOK_BLOCK}
       results.push({ hook, path: hookPath, action: "already-installed" });
     } else {
       const separator = existing.endsWith("\n") ? "" : "\n";
-      await fs19.writeFile(hookPath, `${existing}${separator}${HOOK_BLOCK}
+      await fs20.writeFile(hookPath, `${existing}${separator}${HOOK_BLOCK}
 `, "utf-8");
-      await fs19.chmod(hookPath, 493);
+      await fs20.chmod(hookPath, 493);
       results.push({ hook, path: hookPath, action: "appended" });
     }
   }
@@ -4474,10 +4527,10 @@ async function runHookUninstall(cwd = process.cwd()) {
   const dir = await hooksDir(cwd);
   const results = [];
   for (const hook of HOOK_NAMES) {
-    const hookPath = path12.join(dir, hook);
+    const hookPath = path13.join(dir, hook);
     let existing = null;
     try {
-      existing = await fs19.readFile(hookPath, "utf-8");
+      existing = await fs20.readFile(hookPath, "utf-8");
     } catch {
     }
     if (existing === null || !existing.includes(MARKER_BEGIN)) {
@@ -4487,9 +4540,9 @@ async function runHookUninstall(cwd = process.cwd()) {
     const blockPattern = new RegExp(`\\n?${MARKER_BEGIN}[\\s\\S]*?${MARKER_END}\\n?`);
     const remaining = existing.replace(blockPattern, "\n").trim();
     if (remaining === "" || remaining === "#!/bin/sh") {
-      await fs19.unlink(hookPath);
+      await fs20.unlink(hookPath);
     } else {
-      await fs19.writeFile(hookPath, `${remaining}
+      await fs20.writeFile(hookPath, `${remaining}
 `, "utf-8");
     }
     results.push({ hook, path: hookPath, action: "removed" });
@@ -4503,8 +4556,8 @@ async function runHookUninstall(cwd = process.cwd()) {
 // src/memory.ts
 init_cjs_shims();
 var import_node_crypto4 = require("crypto");
-var fs20 = __toESM(require("fs/promises"), 1);
-var path13 = __toESM(require("path"), 1);
+var fs21 = __toESM(require("fs/promises"), 1);
+var path14 = __toESM(require("path"), 1);
 var OUTCOMES = /* @__PURE__ */ new Set(["useful", "dead_end", "corrected"]);
 var TYPES = /* @__PURE__ */ new Set(["query", "path", "explain", "affected"]);
 function validateResult(value) {
@@ -4522,25 +4575,25 @@ function validateResult(value) {
 }
 async function saveResult(entry, memoryDir, now = /* @__PURE__ */ new Date()) {
   validateResult(entry);
-  await fs20.mkdir(memoryDir, { recursive: true });
+  await fs21.mkdir(memoryDir, { recursive: true });
   const saved = { ...entry, savedAt: now.toISOString() };
   const hash = (0, import_node_crypto4.createHash)("sha256").update(JSON.stringify(saved)).digest("hex").slice(0, 8);
   const stamp = saved.savedAt.replace(/[:.]/g, "-");
-  const filePath = path13.join(memoryDir, `result-${stamp}-${hash}.json`);
-  await fs20.writeFile(filePath, JSON.stringify(saved, null, 2), "utf-8");
+  const filePath = path14.join(memoryDir, `result-${stamp}-${hash}.json`);
+  await fs21.writeFile(filePath, JSON.stringify(saved, null, 2), "utf-8");
   return filePath;
 }
 async function loadResults(memoryDir) {
   let files;
   try {
-    files = (await fs20.readdir(memoryDir)).filter((f) => f.startsWith("result-") && f.endsWith(".json"));
+    files = (await fs21.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 fs20.readFile(path13.join(memoryDir, file), "utf-8"));
+      const parsed = JSON.parse(await fs21.readFile(path14.join(memoryDir, file), "utf-8"));
       if (parsed.question && parsed.savedAt) results.push(parsed);
     } catch {
     }
@@ -4617,18 +4670,18 @@ function renderLessons(results, options = {}) {
 // src/cli/commands/install.ts
 init_cjs_shims();
 var import_node_module3 = require("module");
-var fs21 = __toESM(require("fs/promises"), 1);
-var path14 = __toESM(require("path"), 1);
+var fs22 = __toESM(require("fs/promises"), 1);
+var path15 = __toESM(require("path"), 1);
 var require4 = (0, import_node_module3.createRequire)(importMetaUrl);
 function packageRoot() {
   const packageJsonPath = require4.resolve("@dreamtree-org/graphify/package.json");
-  return path14.dirname(packageJsonPath);
+  return path15.dirname(packageJsonPath);
 }
 var MD_MARKER_BEGIN = "<!-- >>> graphify >>> -->";
 var MD_MARKER_END = "<!-- <<< graphify <<< -->";
 async function writeOwnedFile(filePath, content) {
-  await fs21.mkdir(path14.dirname(filePath), { recursive: true });
-  await fs21.writeFile(filePath, content, "utf-8");
+  await fs22.mkdir(path15.dirname(filePath), { recursive: true });
+  await fs22.writeFile(filePath, content, "utf-8");
 }
 async function upsertMarkedBlock(filePath, content) {
   const block = `${MD_MARKER_BEGIN}
@@ -4636,32 +4689,32 @@ ${content.trim()}
 ${MD_MARKER_END}`;
   let existing = null;
   try {
-    existing = await fs21.readFile(filePath, "utf-8");
+    existing = await fs22.readFile(filePath, "utf-8");
   } catch {
   }
   if (existing === null) {
-    await fs21.mkdir(path14.dirname(filePath), { recursive: true });
-    await fs21.writeFile(filePath, `${block}
+    await fs22.mkdir(path15.dirname(filePath), { recursive: true });
+    await fs22.writeFile(filePath, `${block}
 `, "utf-8");
     return;
   }
   if (existing.includes(MD_MARKER_BEGIN)) {
     const pattern = new RegExp(`${MD_MARKER_BEGIN}[\\s\\S]*?${MD_MARKER_END}`);
-    await fs21.writeFile(filePath, existing.replace(pattern, block), "utf-8");
+    await fs22.writeFile(filePath, existing.replace(pattern, block), "utf-8");
     return;
   }
   const separator = existing.endsWith("\n") ? "\n" : "\n\n";
-  await fs21.writeFile(filePath, `${existing}${separator}${block}
+  await fs22.writeFile(filePath, `${existing}${separator}${block}
 `, "utf-8");
 }
 var PLATFORMS = {
   claude: async (cwd, content) => {
-    const target = path14.join(cwd, ".claude", "skills", "graphify", "SKILL.md");
+    const target = path15.join(cwd, ".claude", "skills", "graphify", "SKILL.md");
     await writeOwnedFile(target, content);
     return { host: "Claude Code", path: target };
   },
   cursor: async (cwd, content) => {
-    const target = path14.join(cwd, ".cursor", "rules", "graphify.mdc");
+    const target = path15.join(cwd, ".cursor", "rules", "graphify.mdc");
     const body = content.replace(/^---[\s\S]*?---\n/, "");
     await writeOwnedFile(
       target,
@@ -4674,30 +4727,30 @@ ${body}`
     return { host: "Cursor", path: target };
   },
   windsurf: async (cwd, content) => {
-    const target = path14.join(cwd, ".windsurf", "rules", "graphify.md");
+    const target = path15.join(cwd, ".windsurf", "rules", "graphify.md");
     await writeOwnedFile(target, content.replace(/^---[\s\S]*?---\n/, ""));
     return { host: "Windsurf", path: target };
   },
   cline: async (cwd, content) => {
-    const target = path14.join(cwd, ".clinerules", "graphify.md");
+    const target = path15.join(cwd, ".clinerules", "graphify.md");
     await writeOwnedFile(target, content.replace(/^---[\s\S]*?---\n/, ""));
     return { host: "Cline", path: target };
   },
   agents: async (cwd, content) => {
-    const target = path14.join(cwd, "AGENTS.md");
+    const target = path15.join(cwd, "AGENTS.md");
     await upsertMarkedBlock(target, content.replace(/^---[\s\S]*?---\n/, ""));
     return { host: "AGENTS.md agents (Codex, opencode, Amp, ...)", path: target };
   },
   gemini: async (cwd, content) => {
-    const target = path14.join(cwd, "GEMINI.md");
+    const target = path15.join(cwd, "GEMINI.md");
     await upsertMarkedBlock(target, content.replace(/^---[\s\S]*?---\n/, ""));
     return { host: "Gemini CLI", path: target };
   }
 };
 var SUPPORTED_PLATFORMS = Object.keys(PLATFORMS).sort((a, b) => a.localeCompare(b));
 async function runInstall(platforms = ["claude"], cwd = process.cwd()) {
-  const sourcePath = path14.join(packageRoot(), "src", "skill", "SKILL.md");
-  const content = await fs21.readFile(sourcePath, "utf-8");
+  const sourcePath = path15.join(packageRoot(), "src", "skill", "SKILL.md");
+  const content = await fs22.readFile(sourcePath, "utf-8");
   const requested = platforms.includes("all") ? SUPPORTED_PLATFORMS : platforms;
   const results = [];
   for (const platform of requested) {
@@ -4781,7 +4834,7 @@ function looksLikeGitUrl(value) {
 }
 async function cloneRepo(url) {
   const validated = validateUrl(url);
-  const dest = await fs23.mkdtemp(path16.join(os3.tmpdir(), "graphify-clone-"));
+  const dest = await fs24.mkdtemp(path17.join(os3.tmpdir(), "graphify-clone-"));
   await execFileAsync3("git", ["clone", "--depth", "1", validated, dest]);
   return dest;
 }
@@ -4795,7 +4848,7 @@ function clusterOptionsFrom(options) {
   };
 }
 async function runClusterOnly(root, options) {
-  const outDir = path16.join(root, "graphify-out");
+  const outDir = path17.join(root, "graphify-out");
   const graph = await loadGraph(outDir);
   cluster(graph, clusterOptionsFrom(options));
   const analysis = analyze(graph);
@@ -4829,9 +4882,9 @@ var program = new import_commander.Command();
 program.name("graphify").description("Turn a folder of code/docs/papers into a queryable knowledge graph.").argument("[path]", "path to scan, or a GitHub URL", ".").option("--mode <mode>", "extraction mode (deep for richer INFERRED edges \u2014 reserved, no-op in v1)").option("--update", "incremental rebuild \u2014 reuse cached extractions for unchanged files").option("--watch", "rebuild on file change").option("--cluster-only", "rerun clustering on an existing graph").option("--leiden", "use Leiden instead of Louvain for community detection (v2 \u2014 better community quality)").option("--max-iterations <n>", "Leiden only: cap on outer iterations for very large graphs", Number).option("--no-viz", "skip graph.html").option("--svg", "also export graph.svg (not implemented in v1)").option("--graphml", "also export graph.graphml (not implemented in v1)").option("--neo4j", "generate graphify-out/cypher.txt for Neo4j (not implemented in v1)").option("--mcp", "start MCP stdio server instead of running the pipeline").option("--mysql <dsn>", "also extract a MySQL schema (mysql://user:pass@host:port/db) into the graph").action(async (targetArg, options) => {
   try {
     if (options.mcp) {
-      const outDir = path16.resolve(targetArg === "." ? process.cwd() : targetArg, "graphify-out");
+      const outDir = path17.resolve(targetArg === "." ? process.cwd() : targetArg, "graphify-out");
       const { startServer: startServer2 } = await Promise.resolve().then(() => (init_server(), server_exports));
-      await startServer2(path16.join(outDir, "graph.json"));
+      await startServer2(path17.join(outDir, "graph.json"));
       return;
     }
     let root = targetArg;
@@ -4839,7 +4892,7 @@ program.name("graphify").description("Turn a folder of code/docs/papers into a q
       console.error(`Cloning ${targetArg} ...`);
       root = await cloneRepo(targetArg);
     }
-    root = path16.resolve(root);
+    root = path17.resolve(root);
     if (options.mode) {
       console.error(`--mode ${options.mode} is reserved for a future richer-INFERRED-edges pass \u2014 currently a no-op.`);
     }
@@ -4993,7 +5046,7 @@ program.command("merge <dirs...>").description("one-shot merge of two or more bu
 });
 program.command("save-result").description("save a Q&A result to graphify-out/memory/ for the graph feedback loop").requiredOption("--question <q>", "the question that was asked").requiredOption("--answer <a>", "the answer that was given").option("--nodes <ids...>", "node ids/labels cited in the answer", []).option("--type <t>", "query|path|explain|affected", "query").option("--outcome <o>", "useful|dead_end|corrected", "useful").option("--correction <text>", "what the right answer was (pairs with --outcome corrected)").action(async (options) => {
   try {
-    const memoryDir = path16.join(process.cwd(), "graphify-out", "memory");
+    const memoryDir = path17.join(process.cwd(), "graphify-out", "memory");
     const file = await saveResult(
       {
         question: options.question,
@@ -5013,12 +5066,12 @@ program.command("save-result").description("save a Q&A result to graphify-out/me
 });
 program.command("reflect").description("aggregate graphify-out/memory/ into a recency-weighted lessons doc").option("--half-life-days <n>", "a result loses half its weight every N days (default 30)", Number).option("--out <file>", "output path (default graphify-out/reflections/LESSONS.md)").action(async (options) => {
   try {
-    const memoryDir = path16.join(process.cwd(), "graphify-out", "memory");
+    const memoryDir = path17.join(process.cwd(), "graphify-out", "memory");
     const results = await loadResults(memoryDir);
     const lessons = renderLessons(results, { halfLifeDays: options.halfLifeDays });
-    const outPath = path16.resolve(options.out ?? path16.join(process.cwd(), "graphify-out", "reflections", "LESSONS.md"));
-    await fs23.mkdir(path16.dirname(outPath), { recursive: true });
-    await fs23.writeFile(outPath, lessons, "utf-8");
+    const outPath = path17.resolve(options.out ?? path17.join(process.cwd(), "graphify-out", "reflections", "LESSONS.md"));
+    await fs24.mkdir(path17.dirname(outPath), { recursive: true });
+    await fs24.writeFile(outPath, lessons, "utf-8");
     console.log(`Reflected ${results.length} result(s) -> ${outPath}`);
   } catch (error) {
     console.error(`graphify reflect: ${error.message}`);