@dreamtree-org/graphify 1.1.2 → 1.2.0

package/dist/cli/index.cjs

@@ -332,7 +332,10 @@ function scoreNodes(graph, query) {
     }
     if (score > 0) matches.push({ id, label, score });
   });
-  matches.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+  const placeholderRank = (id) => id.startsWith("module:") || id.startsWith("external:") ? 1 : 0;
+  matches.sort(
+    (a, b) => b.score - a.score || placeholderRank(a.id) - placeholderRank(b.id) || a.id.localeCompare(b.id)
+  );
   return matches;
 }
 function resolveNode(graph, query) {
@@ -542,6 +545,7 @@ function affectedBy(graph, nodeQuery, options = {}) {
   if (!target) return null;
   const maxDepth = options.maxDepth ?? DEFAULT_IMPACT_DEPTH;
   const limit = options.limit ?? DEFAULT_IMPACT_LIMIT;
+  const followed = options.relations ? new Set(options.relations) : DEPENDENCY_RELATIONS;
   const affected = [];
   const visited = /* @__PURE__ */ new Set([target.id]);
   let frontier = [target.id];
@@ -552,7 +556,7 @@ function affectedBy(graph, nodeQuery, options = {}) {
       graph.forEachInEdge(current, (_edge, edgeAttrs, source) => {
         if (visited.has(source)) return;
         const relation = edgeAttrs.relation;
-        if (!DEPENDENCY_RELATIONS.has(relation)) return;
+        if (!followed.has(relation)) return;
         const confidence = edgeAttrs.confidence;
         const existing = nextFrontier.get(source);
         if (existing && CONFIDENCE_RANK2[existing.via.confidence] >= CONFIDENCE_RANK2[confidence]) return;
@@ -611,11 +615,11 @@ var init_impact = __esm({
 function isTestFile(path18) {
   return TEST_FILE_PATTERNS.some((p) => p.test(path18));
 }
-function selectionFromImpact(graph, targetIds, targetLabel) {
+function selectionFromImpact(graph, targetIds, targetLabel, relations) {
   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 });
+    const impact = affectedBy(graph, id, { maxDepth: TEST_REACH_DEPTH, limit: TEST_REACH_LIMIT, relations });
     if (!impact) continue;
     affectedNodeCount += impact.affected.length;
     for (const node of impact.affected) {
@@ -627,11 +631,27 @@ function selectionFromImpact(graph, targetIds, targetLabel) {
     }
   }
   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 };
+  return {
+    target: targetLabel,
+    testFiles,
+    affectedNodeCount,
+    precision: relations ? "usage" : "import-reachability"
+  };
+}
+function entityRootsOf(graph, id) {
+  if (id.includes("::")) return [id];
+  const roots = [];
+  graph.forEachOutEdge(id, (_edge, attrs, _source, target) => {
+    if (String(attrs.relation) === "contains") roots.push(target);
+  });
+  roots.sort((a, b) => a.localeCompare(b));
+  return roots.length > 0 ? roots : [id];
 }
 function testsForNode(graph, nodeQuery) {
   const match = resolveNode(graph, nodeQuery);
   if (!match) return null;
+  const precise = selectionFromImpact(graph, entityRootsOf(graph, match.id), match.id, USAGE_RELATIONS);
+  if (precise.testFiles.length > 0) return precise;
   return selectionFromImpact(graph, [match.id], match.id);
 }
 function testsForChangedFiles(graph, changedFiles) {
@@ -644,7 +664,12 @@ function testsForChangedFiles(graph, changedFiles) {
     }
     if (graph.hasNode(file)) fileIds.push(file);
   }
-  const selection = selectionFromImpact(graph, fileIds, changedFiles.join(", "));
+  const label = changedFiles.join(", ");
+  const preciseRoots = fileIds.flatMap((f) => entityRootsOf(graph, f));
+  let selection = selectionFromImpact(graph, preciseRoots, label, USAGE_RELATIONS);
+  if (selection.testFiles.length === 0) {
+    selection = selectionFromImpact(graph, fileIds, label);
+  }
   for (const [file, info] of selfSelected) {
     if (!selection.testFiles.some((t) => t.file === file)) {
       selection.testFiles.push({ file, depth: info.depth, via: info.via });
@@ -653,7 +678,7 @@ function testsForChangedFiles(graph, changedFiles) {
   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 TEST_FILE_PATTERNS, TEST_REACH_DEPTH, TEST_REACH_LIMIT, USAGE_RELATIONS;
 var init_testmap = __esm({
   "src/testmap.ts"() {
     "use strict";
@@ -676,6 +701,7 @@ var init_testmap = __esm({
     ];
     TEST_REACH_DEPTH = 4;
     TEST_REACH_LIMIT = 2e3;
+    USAGE_RELATIONS = ["calls", "inherits", "implements", "mixes_in", "embeds", "references"];
   }
 });
 
@@ -3213,13 +3239,11 @@ async function extractTypeScript(filePath, displayPath) {
     });
   }
   function importTargetId(binding, property) {
-    if (!binding.ref.external) {
-      if (binding.kind === "named" && binding.importedName) {
-        return entityId(binding.ref.id, binding.importedName);
-      }
-      if (binding.kind === "namespace" && property) {
-        return entityId(binding.ref.id, property);
-      }
+    if (binding.kind === "named" && binding.importedName) {
+      return entityId(binding.ref.id, binding.importedName);
+    }
+    if (binding.kind === "namespace" && property) {
+      return entityId(binding.ref.id, property);
     }
     return binding.ref.id;
   }
@@ -3257,24 +3281,35 @@ async function extractTypeScript(filePath, displayPath) {
       }
     }
   }
+  function unwrapExpression(node) {
+    let current = node;
+    while (current.type === "as_expression" || current.type === "satisfies_expression" || current.type === "non_null_expression" || current.type === "parenthesized_expression") {
+      const inner = namedChildren(current)[0];
+      if (!inner) break;
+      current = inner;
+    }
+    return current;
+  }
   function handleTopLevelVariableFunctions(node) {
+    const isExported = node.parent?.type === "export_statement";
     for (const declarator of namedChildren(node)) {
       if (declarator.type !== "variable_declarator") continue;
       const value = declarator.childForFieldName("value");
       if (!value) continue;
-      if (value.type === "arrow_function" || value.type === "function_expression") {
+      const core = unwrapExpression(value);
+      if (core.type === "arrow_function" || core.type === "function_expression") {
         const name = declarator.childForFieldName("name")?.text;
         if (!name) continue;
         const id = entityId(sourceFile, name);
         builder.addNode({ id, label: `function ${name}`, sourceFile, sourceLocation: lineOf(declarator) });
         builder.addEdge({ source: fileId, target: id, relation: "contains", confidence: "EXTRACTED" });
         nameIndex.set(name, id);
-        functionNodeMap.set(value.id, id);
+        functionNodeMap.set(core.id, id);
         continue;
       }
-      if (value.type === "call_expression") {
-        const callee = value.childForFieldName("function");
-        const specifier = callee?.type === "identifier" && callee.text === "require" ? firstStringArgument(value) : null;
+      if (core.type === "call_expression") {
+        const callee = core.childForFieldName("function");
+        const specifier = callee?.type === "identifier" && callee.text === "require" ? firstStringArgument(core) : null;
         if (specifier) {
           const nameNode = declarator.childForFieldName("name");
           if (nameNode) {
@@ -3282,6 +3317,21 @@ async function extractTypeScript(filePath, displayPath) {
             addModuleNode(ref);
             registerRequireBinding(nameNode, ref);
           }
+          continue;
+        }
+      }
+      if (isExported) {
+        const name = declarator.childForFieldName("name")?.text;
+        if (!name) continue;
+        const id = entityId(sourceFile, name);
+        builder.addNode({ id, label: `const ${name}`, sourceFile, sourceLocation: lineOf(declarator) });
+        builder.addEdge({ source: fileId, target: id, relation: "contains", confidence: "EXTRACTED" });
+        nameIndex.set(name, id);
+        if (core.type === "identifier") {
+          const aliased = nameIndex.get(core.text);
+          if (aliased !== void 0 && aliased !== id) {
+            builder.addEdge({ source: id, target: aliased, relation: "references", confidence: "EXTRACTED" });
+          }
         }
       }
     }
@@ -3661,13 +3711,12 @@ function candidatePaths(guessed) {
   }
   return candidates.filter((c) => c !== guessed);
 }
-function uniqueMatch(guessed, candidates, realIds) {
+function uniqueMatch(candidates, real) {
   const matches = /* @__PURE__ */ new Set();
   for (const candidate of candidates) {
-    if (realIds.has(candidate)) matches.add(candidate);
+    if (real.has(candidate)) matches.add(candidate);
   }
-  if (matches.size !== 1) return null;
-  return [...matches][0];
+  return matches.size === 1 ? [...matches][0] : null;
 }
 function resolveCrossFileReferences(extractions, options = {}) {
   const selfNames = options.selfNames ?? [];
@@ -3688,20 +3737,24 @@ function resolveCrossFileReferences(extractions, options = {}) {
     }
   }
   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;
+  let resolvedEndpoints = 0;
+  const applyRemap = (resolveId) => {
+    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++;
         }
       }
-      return null;
     }
+  };
+  const resolvePathId = (id) => {
     if (isOpaque(id)) return null;
     const cached = remap.get(id);
     if (cached !== void 0) return cached;
@@ -3711,30 +3764,77 @@ function resolveCrossFileReferences(extractions, options = {}) {
       if (realIds.has(id)) return null;
       const guessedPath = id.slice(0, sep3);
       const name = id.slice(sep3);
-      const candidates = candidatePaths(guessedPath).map((p) => `${p}${name}`);
-      resolved = uniqueMatch(id, candidates, realIds);
+      resolved = uniqueMatch(candidatePaths(guessedPath).map((p) => `${p}${name}`), realIds);
     } else {
       if (realFiles.has(id)) return null;
-      resolved = uniqueMatch(id, candidatePaths(id), realFiles);
+      resolved = uniqueMatch(candidatePaths(id), realFiles);
     }
     if (resolved !== null) remap.set(id, resolved);
     return resolved;
   };
-  let resolvedEndpoints = 0;
+  applyRemap(resolvePathId);
+  const namedAlias = /* @__PURE__ */ new Map();
+  const starTargets = /* @__PURE__ */ new Map();
   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++;
+      if (edge.relation !== "re_exports" || !realFiles.has(edge.source)) continue;
+      const sep3 = edge.target.lastIndexOf("::");
+      if (sep3 > 0 && realIds.has(edge.target)) {
+        namedAlias.set(`${edge.source}|${edge.target.slice(sep3 + 2)}`, edge.target);
+      } else if (sep3 < 0 && realFiles.has(edge.target)) {
+        const targets = starTargets.get(edge.source) ?? [];
+        targets.push(edge.target);
+        starTargets.set(edge.source, targets);
       }
     }
   }
+  const throughBarrel = (file, name) => {
+    const direct = `${file}::${name}`;
+    if (realIds.has(direct)) return direct;
+    const aliased = namedAlias.get(`${file}|${name}`);
+    if (aliased !== void 0) return aliased;
+    const viaStar = (starTargets.get(file) ?? []).map((sf) => `${sf}::${name}`).filter((id) => realIds.has(id));
+    return viaStar.length === 1 ? viaStar[0] : null;
+  };
+  const resolveBarrelId = (id) => {
+    const cached = remap.get(id);
+    if (cached !== void 0) return cached;
+    if (id.startsWith("module:")) {
+      const spec = id.slice("module:".length);
+      const sep4 = spec.indexOf("::");
+      const moduleSpec = sep4 > 0 ? spec.slice(0, sep4) : spec;
+      const name = sep4 > 0 ? spec.slice(sep4 + 2) : null;
+      const candidates = selfImportCandidates(moduleSpec, selfNames);
+      if (candidates === null) {
+        if (name === null) return null;
+        remap.set(id, `module:${moduleSpec}`);
+        return `module:${moduleSpec}`;
+      }
+      const file = uniqueMatch(candidates, realFiles);
+      let resolved = null;
+      if (file !== null) {
+        resolved = name !== null ? throughBarrel(file, name) ?? file : file;
+      } else if (name !== null) {
+        resolved = `module:${moduleSpec}`;
+      }
+      if (resolved !== null) remap.set(id, resolved);
+      return resolved;
+    }
+    const sep3 = id.indexOf("::");
+    if (sep3 > 0 && !realIds.has(id)) {
+      const guessedPath = id.slice(0, sep3);
+      const name = id.slice(sep3 + 2);
+      const files = [guessedPath, ...candidatePaths(guessedPath)].filter((f) => realFiles.has(f));
+      const resolvedSet = new Set(files.map((f) => throughBarrel(f, name)).filter((r) => r !== null));
+      if (resolvedSet.size === 1) {
+        const resolved = [...resolvedSet][0];
+        remap.set(id, resolved);
+        return resolved;
+      }
+    }
+    return null;
+  };
+  applyRemap(resolveBarrelId);
   let droppedPlaceholders = 0;
   for (const extraction of extractions) {
     const before = extraction.nodes.length;
@@ -4261,7 +4361,8 @@ async function runTests(nodeQuery, options = {}) {
     );
     return;
   }
-  console.log(`Test files for ${selection.target} (most direct first):`);
+  const how = selection.precision === "usage" ? "selected by actual usage (calls/inheritance)" : "selected by import reachability \u2014 may over-include files sharing an entry point";
+  console.log(`Test files for ${selection.target} (${how}; most direct first):`);
   for (const test of selection.testFiles) {
     const via = test.depth === 0 ? test.via : `depth ${test.depth}, via ${test.via}`;
     console.log(`  ${test.file}  (${via})`);
@@ -4677,6 +4778,29 @@ function packageRoot() {
   const packageJsonPath = require4.resolve("@dreamtree-org/graphify/package.json");
   return path15.dirname(packageJsonPath);
 }
+var MCP_SERVER_ENTRY = {
+  command: "npx",
+  args: ["-y", "@dreamtree-org/graphify", "--mcp"]
+};
+async function upsertMcpServer(filePath, serversKey = "mcpServers") {
+  let config = {};
+  try {
+    config = JSON.parse(await fs22.readFile(filePath, "utf-8"));
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw new Error(`cannot update ${filePath} \u2014 it exists but is not valid JSON; fix or remove it and re-run.`, {
+        cause: error
+      });
+    }
+  }
+  const servers = config[serversKey] ?? {};
+  servers["graphify"] = MCP_SERVER_ENTRY;
+  config[serversKey] = servers;
+  await fs22.mkdir(path15.dirname(filePath), { recursive: true });
+  await fs22.writeFile(filePath, `${JSON.stringify(config, null, 2)}
+`, "utf-8");
+  return filePath;
+}
 var MD_MARKER_BEGIN = "<!-- >>> graphify >>> -->";
 var MD_MARKER_END = "<!-- <<< graphify <<< -->";
 async function writeOwnedFile(filePath, content) {
@@ -4711,7 +4835,8 @@ var PLATFORMS = {
   claude: async (cwd, content) => {
     const target = path15.join(cwd, ".claude", "skills", "graphify", "SKILL.md");
     await writeOwnedFile(target, content);
-    return { host: "Claude Code", path: target };
+    const mcpPath = await upsertMcpServer(path15.join(cwd, ".mcp.json"));
+    return { host: "Claude Code", path: target, mcpPath };
   },
   cursor: async (cwd, content) => {
     const target = path15.join(cwd, ".cursor", "rules", "graphify.mdc");
@@ -4724,7 +4849,8 @@ alwaysApply: false
 ---
 ${body}`
     );
-    return { host: "Cursor", path: target };
+    const mcpPath = await upsertMcpServer(path15.join(cwd, ".cursor", "mcp.json"));
+    return { host: "Cursor", path: target, mcpPath };
   },
   windsurf: async (cwd, content) => {
     const target = path15.join(cwd, ".windsurf", "rules", "graphify.md");
@@ -4744,10 +4870,32 @@ ${body}`
   gemini: async (cwd, content) => {
     const target = path15.join(cwd, "GEMINI.md");
     await upsertMarkedBlock(target, content.replace(/^---[\s\S]*?---\n/, ""));
-    return { host: "Gemini CLI", path: target };
+    const mcpPath = await upsertMcpServer(path15.join(cwd, ".gemini", "settings.json"));
+    return { host: "Gemini CLI", path: target, mcpPath };
   }
 };
 var SUPPORTED_PLATFORMS = Object.keys(PLATFORMS).sort((a, b) => a.localeCompare(b));
+var PLATFORM_MARKERS = {
+  cursor: [".cursor"],
+  windsurf: [".windsurf"],
+  cline: [".clinerules"],
+  agents: ["AGENTS.md"],
+  gemini: ["GEMINI.md", ".gemini"]
+};
+async function detectPlatforms(cwd = process.cwd()) {
+  const platforms = ["claude"];
+  for (const [platform, markers] of Object.entries(PLATFORM_MARKERS)) {
+    for (const marker of markers) {
+      try {
+        await fs22.access(path15.join(cwd, marker));
+        platforms.push(platform);
+        break;
+      } catch {
+      }
+    }
+  }
+  return platforms;
+}
 async function runInstall(platforms = ["claude"], cwd = process.cwd()) {
   const sourcePath = path15.join(packageRoot(), "src", "skill", "SKILL.md");
   const content = await fs22.readFile(sourcePath, "utf-8");
@@ -4763,7 +4911,8 @@ async function runInstall(platforms = ["claude"], cwd = process.cwd()) {
     results.push(await installer(cwd, content));
   }
   for (const result of results) {
-    console.log(`Installed graphify for ${result.host} -> ${result.path}`);
+    const mcpNote = result.mcpPath ? ` (MCP server registered in ${result.mcpPath})` : "";
+    console.log(`Installed graphify for ${result.host} -> ${result.path}${mcpNote}`);
   }
   return results;
 }
@@ -4879,7 +5028,7 @@ async function watchAndRebuild(root, runOnce) {
   });
 }
 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) => {
+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("--no-install", "skip auto-installing the agent skill + MCP config after the build").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 = path17.resolve(targetArg === "." ? process.cwd() : targetArg, "graphify-out");
@@ -4888,7 +5037,8 @@ program.name("graphify").description("Turn a folder of code/docs/papers into a q
       return;
     }
     let root = targetArg;
-    if (looksLikeGitUrl(targetArg)) {
+    const cloned = looksLikeGitUrl(targetArg);
+    if (cloned) {
       console.error(`Cloning ${targetArg} ...`);
       root = await cloneRepo(targetArg);
     }
@@ -4914,6 +5064,13 @@ program.name("graphify").description("Turn a folder of code/docs/papers into a q
       onProgress: (m) => console.error(m)
     });
     await runOnce();
+    if (options.install && !cloned) {
+      try {
+        await runInstall(await detectPlatforms(root), root);
+      } catch (error) {
+        console.error(`graphify: agent skill/MCP install skipped: ${error.message}`);
+      }
+    }
     if (options.watch) {
       console.error(`Watching ${root} for changes (Ctrl+C to stop) ...`);
       await watchAndRebuild(root, runOnce);
@@ -4995,7 +5152,7 @@ program.command("benchmark [questions...]").description("measure token savings o
     process.exitCode = 1;
   }
 });
-program.command("install").description("install the skill/rules files into local agents (claude, cursor, windsurf, cline, agents, gemini, all)").option("--platform <names...>", "platform(s) to install for", ["claude"]).action(async (options) => {
+program.command("install").description("install the skill/rules files + project MCP config into local agents (claude, cursor, windsurf, cline, agents, gemini, all)").option("--platform <names...>", "platform(s) to install for", ["claude"]).action(async (options) => {
   try {
     await runInstall(options.platform);
   } catch (error) {