@esankhan3/code-search-mcp 1.0.6 → 1.1.1

package/dist/tools/graph.js

@@ -1,158 +1,318 @@
 import { existsSync } from "node:fs";
+import { execFileSync } from "node:child_process";
 import { join } from "node:path";
 import {
   getBlobStore,
   getGraphStore,
+  getRetriever,
+  findChunksInProject,
   loadAllProfiles,
   loadProfile,
   getAllChanges,
-  getChangedFilesList
+  getChangedFilesList,
+  SYMMETRIC_EDGE_TYPES
 } from "@esankhan3/anvil-knowledge-core";
 import { resolvedKnowledgeConfig } from "../core/env-config.js";
-const GRAPH_TOOL_NAMES = [
-  "get_repo_graph",
-  "get_cross_repo_edges",
-  "find_callers",
-  "find_dependencies",
-  "impact_analysis",
-  "trace_path",
-  "find_dead_code",
-  "get_architecture",
-  "search_graph",
-  "detect_changes"
-];
+import { missingProfileText } from "./profile.js";
+import { toolError, toolText, validateArgs } from "./validate.js";
 const repoOf = (key) => key.split("::")[0] ?? "";
-function makeNeighborGetter(store, direction) {
-  const cache = /* @__PURE__ */ new Map();
-  return (key) => {
-    let v = cache.get(key);
-    if (v === void 0) {
-      v = store.neighborsOf(key, direction);
-      cache.set(key, v);
+const fileOf = (key) => key.split("::")[1] ?? "";
+const TRAVERSAL_MAX_NODES = 5e4;
+const TRAVERSAL_BUDGET_MS = 1e3;
+const NEIGHBOR_BATCH = 400;
+class TraversalBudget {
+  deadline = Date.now() + TRAVERSAL_BUDGET_MS;
+  /** Distinct nodes discovered so far. */
+  explored = 0;
+  /** Set once a limit stopped the traversal. */
+  exhausted = false;
+  /** Room for another query? Marks the budget exhausted when there isn't. */
+  hasRoom() {
+    if (this.explored >= TRAVERSAL_MAX_NODES || Date.now() > this.deadline) this.exhausted = true;
+    return !this.exhausted;
+  }
+}
+function expandLevel(store, frontier, direction, types, budget, visit) {
+  for (let i = 0; i < frontier.length; i += NEIGHBOR_BATCH) {
+    if (!budget.hasRoom()) return false;
+    const limit = TRAVERSAL_MAX_NODES - budget.explored;
+    const rows = store.neighborEdges(frontier.slice(i, i + NEIGHBOR_BATCH), direction, types, limit);
+    for (const [key, nb] of rows) if (visit(key, nb)) return true;
+    if (rows.length >= limit) {
+      budget.exhausted = true;
+      return false;
     }
-    return v;
-  };
+  }
+  return false;
 }
-function shortestPath(getNeighbors, fromKeys, toKeys, maxDepth) {
-  const seed = fromKeys.find((k) => toKeys.has(k));
-  if (seed) return [seed];
-  const visited = new Set(fromKeys);
-  let frontier = fromKeys.map((k) => [k]);
-  for (let depth = 0; depth < maxDepth && frontier.length > 0; depth++) {
+const REVERSE = { callees: "callers", callers: "callees", both: "both" };
+function shortestPath(store, fromKeys, toKeys, maxDepth, direction, types, budget) {
+  const fwd = new Map(fromKeys.map((k) => [k, null]));
+  const bwd = new Map(toKeys.map((k) => [k, null]));
+  const chain = (m, k) => {
+    const out = [k];
+    for (let p = m.get(k); p != null; p = m.get(p)) out.push(p);
+    return out;
+  };
+  budget.explored = fwd.size + bwd.size;
+  let fFront = [...fwd.keys()];
+  let bFront = [...bwd.keys()];
+  let depth = 0;
+  let path = null;
+  while (depth < maxDepth && fFront.length > 0 && bFront.length > 0) {
+    const forward = fFront.length <= bFront.length;
+    const [mine, other] = forward ? [fwd, bwd] : [bwd, fwd];
     const next = [];
-    for (const path of frontier) {
-      for (const nb of getNeighbors(path[path.length - 1])) {
-        if (visited.has(nb)) continue;
-        if (toKeys.has(nb)) return [...path, nb];
-        visited.add(nb);
-        next.push([...path, nb]);
+    expandLevel(store, forward ? fFront : bFront, forward ? direction : REVERSE[direction], types, budget, (k, nb) => {
+      if (other.has(nb)) {
+        const p = forward ? [...chain(fwd, k).reverse(), ...chain(bwd, nb)] : [...chain(fwd, nb).reverse(), ...chain(bwd, k)];
+        if (p[0] !== p[p.length - 1]) {
+          path = p;
+          return true;
+        }
       }
-    }
-    frontier = next;
+      if (!mine.has(nb)) {
+        mine.set(nb, k);
+        next.push(nb);
+        budget.explored++;
+      }
+      return false;
+    });
+    if (path || budget.exhausted) break;
+    if (forward) fFront = next;
+    else bFront = next;
+    depth++;
   }
-  return null;
+  return { path, depth };
 }
-function reachable(getNeighbors, fromKeys, maxDepth, cap = 50) {
+function reachable(store, fromKeys, maxDepth, direction, types, budget, cap = 50) {
   const visited = new Set(fromKeys);
   const out = [];
+  budget.explored = visited.size;
   let frontier = [...fromKeys];
   for (let depth = 1; depth <= maxDepth && frontier.length > 0; depth++) {
     const next = [];
-    for (const k of frontier) {
-      for (const nb of getNeighbors(k)) {
-        if (visited.has(nb)) continue;
-        visited.add(nb);
-        out.push({ key: nb, depth });
-        next.push(nb);
-        if (out.length >= cap) return out;
+    const full = expandLevel(store, frontier, direction, types, budget, (_k, nb) => {
+      if (visited.has(nb)) return false;
+      visited.add(nb);
+      budget.explored++;
+      out.push({ key: nb, depth });
+      next.push(nb);
+      return out.length >= cap;
+    });
+    if (full || budget.exhausted) break;
+    frontier = next;
+  }
+  return out;
+}
+function endpointsIn(store, keys) {
+  const types = store.nodeTypes(keys);
+  return keys.filter((k) => types.get(k) === "external");
+}
+const HOP_EDGE_CAP = 1e3;
+function dependentHops(store, scope, depth, fileLevel, budget) {
+  const visited = new Set(scope);
+  const repos = /* @__PURE__ */ new Set();
+  const hops = [];
+  let frontier = [...scope];
+  for (let hop = 1; hop <= depth && frontier.length > 0; hop++) {
+    budget.explored = visited.size;
+    if (!budget.hasRoom()) break;
+    const d = store.dependents(frontier, HOP_EDGE_CAP, TRAVERSAL_MAX_NODES);
+    const edges = d.edges.filter((e) => !visited.has(e.source));
+    const direct = /* @__PURE__ */ new Set();
+    const next = [];
+    for (const e of edges) {
+      repos.add(repoOf(e.source));
+      if (!fileLevel.has(e.target)) direct.add(e.source);
+      if (!visited.has(e.source)) {
+        visited.add(e.source);
+        next.push(e.source);
       }
     }
+    for (const k of next) if (!direct.has(k)) fileLevel.add(k);
+    hops.push({ hop, edges, total: d.total - (d.edges.length - edges.length), truncated: d.truncated });
     frontier = next;
   }
+  return { hops, repos };
+}
+const atLeast = (truncated) => truncated ? "+" : "";
+const AT_LEAST_NOTE = `_N+ = at least N: a hop counts at most ${TRAVERSAL_MAX_NODES} dependent edges._`;
+function edgeLine(e, fileLevel) {
+  const arrow = SYMMETRIC_EDGE_TYPES.has(e.type ?? "") ? "\u2194" : "\u2192";
+  return `- \`${e.source}\` ${arrow} \`${e.target}\` (${e.type ?? "edge"})${e.evidence ? ` \u2014 ${e.evidence}` : ""}${fileLevel.has(e.target) ? " [file-level]" : ""}`;
+}
+async function indexedSources(project, repo, files) {
+  const cfg = resolvedKnowledgeConfig();
+  const parts = /* @__PURE__ */ new Map();
+  try {
+    const vs = (await getRetriever(project, cfg)).vectorStore;
+    await Promise.all(files.map(async (f) => {
+      const chunks = await vs.getChunksByFile(repo, f);
+      if (chunks.length > 0) parts.set(f, chunks.map((c) => c.content));
+    }));
+  } catch {
+  }
+  const missing = new Set(files.filter((f) => !parts.has(f)));
+  if (missing.size > 0 && await getBlobStore(project, cfg).exists("chunks.json")) {
+    const found = await findChunksInProject(project, (c) => c.repoName === repo && missing.has(c.filePath), Number.POSITIVE_INFINITY, cfg);
+    for (const c of found) {
+      if (!parts.has(c.filePath)) parts.set(c.filePath, []);
+      parts.get(c.filePath).push(c.content);
+    }
+  }
+  return new Map([...parts].map(([f, cs]) => [f, cs.join("\n")]));
+}
+const escapeRegex = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function identifierCount(src, name) {
+  return src.match(new RegExp(`(?<![\\w$])${escapeRegex(name)}(?![\\w$])`, "g"))?.length ?? 0;
+}
+const runGit = (repoPath, args) => execFileSync("git", args, {
+  cwd: repoPath,
+  encoding: "utf-8",
+  maxBuffer: 64 * 1024 * 1024,
+  stdio: ["pipe", "pipe", "pipe"]
+});
+function diffHunks(repoPath, baseSha, files) {
+  const out = /* @__PURE__ */ new Map();
+  if (files.length === 0) return out;
+  let file = "";
+  for (const line of runGit(repoPath, ["diff", "-U0", "--no-color", "--no-ext-diff", baseSha, "--", ...files]).split("\n")) {
+    if (line.startsWith("+++ ")) {
+      file = line.slice(4).replace(/^b\//, "");
+      continue;
+    }
+    const m = /^@@ -(\d+)(?:,(\d+))? /.exec(line);
+    if (m && file) {
+      if (!out.has(file)) out.set(file, []);
+      out.get(file).push([Number(m[1]), m[2] === void 0 ? 1 : Number(m[2])]);
+    }
+  }
   return out;
 }
+function declarationRanges(src, names) {
+  const lines = src.split("\n");
+  const starts = [];
+  for (const name of names) {
+    const n = escapeRegex(name);
+    const keyword = new RegExp(`\\b(?:function\\*?|class|interface|type|enum|struct|trait|impl|def|func|fn|const|let|var)\\s+(?:\\([^)]*\\)\\s*)?${n}(?![\\w$])`);
+    const method = new RegExp(`^\\s*(?:(?:public|private|protected|internal|static|async|override|readonly|abstract|final|virtual|export|default)\\s+)*(?:[\\w$<>\\[\\],.?]+\\s+)?${n}\\s*(?:<[^>]*>)?\\(`);
+    let found = lines.flatMap((l, i) => keyword.test(l) ? [i + 1] : []);
+    if (found.length === 0) found = lines.flatMap((l, i) => method.test(l) && !l.trimEnd().endsWith(";") ? [i + 1] : []);
+    for (const line of found) starts.push({ name, line });
+  }
+  starts.sort((a, b) => a.line - b.line);
+  return starts.map((s, i) => ({ name: s.name, start: s.line, end: (starts[i + 1]?.line ?? lines.length + 1) - 1 }));
+}
+function touchedEntities(ranges, hunks) {
+  const names = /* @__PURE__ */ new Set();
+  let fileLevel = false;
+  for (const [start, count] of hunks) {
+    const hit = ranges.filter((r) => count > 0 ? r.start <= start + count - 1 && r.end >= start : r.start <= start && r.end >= start + 1);
+    if (hit.length === 0) fileLevel = true;
+    for (const r of hit) names.add(r.name);
+  }
+  return { names, fileLevel };
+}
+const RELATIONS = ["calls", "imports", "uses", "type-ref", "inherits", "all"];
+const relationsProp = (what) => ({
+  type: "array",
+  items: { type: "string", enum: RELATIONS },
+  description: `Edge types to follow for ${what} (default ["calls"]): calls; imports (a file imports a file); uses (a file imports this symbol by name); type-ref; inherits; or "all" (every edge type except contains, cross-repo edges included)`
+});
+function edgeTypes(args) {
+  const r = args.relations ?? ["calls"];
+  return r.includes("all") ? void 0 : r;
+}
 function registerGraphTools() {
   return [
     {
       name: "get_repo_graph",
-      description: "Get the AST knowledge graph for a repo \u2014 entities (functions, classes, types) and their relationships (calls, imports, inheritance).",
+      description: "List a repo's AST graph: node and edge counts, entities (id + type) and edges (source \u2192 target + relation; `contains` omitted), each list capped by `limit`.",
       inputSchema: {
         type: "object",
-        properties: { repo: { type: "string", description: "Repository name" } },
+        properties: {
+          repo: { type: "string", minLength: 1, description: "Repository name" },
+          limit: { type: "integer", minimum: 1, description: "Max entities and max edges listed (default 50)" }
+        },
         required: ["repo"]
       }
     },
     {
       name: "get_cross_repo_edges",
-      description: "Get connections between repos \u2014 shared deps, Kafka topics, HTTP routes, database tables, gRPC services, etc.",
+      description: "Connections between repos \u2014 HTTP routes, gRPC services, event/Kafka topics, database tables, Redis keys, S3 buckets, OpenAPI contracts, shared types / constants / env vars / npm deps \u2014 each with the evidence that produced it (route, topic, table, package). Same-repo workspace-package dependencies are listed in their own section. Up to 50 edges.",
       inputSchema: {
         type: "object",
-        properties: { repo: { type: "string", description: "Filter to edges involving this repo (optional)" } }
+        properties: { repo: { type: "string", minLength: 1, description: "Only edges involving this repo (optional)" } }
       }
     },
     {
       name: "find_callers",
-      description: "Find all functions/methods that call a given function (exact name match by default). Uses the AST graph.",
+      description: 'Find the callers of a symbol \u2014 entities with a `calls` edge into it. The name is matched exactly (case-sensitive; a full "repo::file::entity" id works too) unless fuzzy:true. Imports, type references and inheritance are not calls: they are listed, by relation, only when requested via `relations`.',
       inputSchema: {
         type: "object",
         properties: {
-          function: { type: "string", description: "Function name to find callers of" },
-          repo: { type: "string", description: "Limit search to this repo (optional)" },
-          fuzzy: { type: "boolean", description: "Substring-match the name instead of exact (default false)" }
+          function: { type: "string", minLength: 1, description: "Symbol name or qualified id (repo::file::entity)" },
+          repo: { type: "string", minLength: 1, description: "Limit resolution to this repo (optional)" },
+          fuzzy: { type: "boolean", description: "Case-insensitive substring match on symbol names instead of exact (default false)" },
+          relations: relationsProp("callers")
         },
         required: ["function"]
       }
     },
     {
       name: "find_dependencies",
-      description: "Find what a function depends on \u2014 calls, imports, type references (exact name match by default).",
+      description: 'Find what a symbol calls \u2014 targets of its `calls` edges. The name is matched exactly (case-sensitive; a full "repo::file::entity" id works too) unless fuzzy:true. Type references, inheritance and imports are listed, by relation, only when requested via `relations`.',
       inputSchema: {
         type: "object",
         properties: {
-          function: { type: "string", description: "Function name" },
-          repo: { type: "string", description: "Limit to this repo (optional)" },
-          fuzzy: { type: "boolean", description: "Substring-match the name instead of exact (default false)" }
+          function: { type: "string", minLength: 1, description: "Symbol name or qualified id (repo::file::entity)" },
+          repo: { type: "string", minLength: 1, description: "Limit resolution to this repo (optional)" },
+          fuzzy: { type: "boolean", description: "Case-insensitive substring match on symbol names instead of exact (default false)" },
+          relations: relationsProp("dependencies")
         },
         required: ["function"]
       }
     },
     {
       name: "impact_analysis",
-      description: "Analyze what would be affected if a file or entity is changed. Traces callers, dependents, and cross-repo connections.",
+      description: "What is affected if a file or entity changes: everything that depends on it, transitively up to `depth` hops \u2014 over every relation (calls, imports, uses, type-refs, inheritance, cross-repo edges); shared-resource edges (topics, tables, Redis keys, buckets, shared types / constants / env vars / npm deps) count both ways. With `entity`, the cross-repo endpoints declared in the same file (routes, topics, tables \u2026) are included and their dependents marked [file-level], since the graph can't tie them to one entity. A hop counts at most 50,000 edges (shown as 50000+); hops stop after 1 s, with a note.",
       inputSchema: {
         type: "object",
         properties: {
-          file: { type: "string", description: "File path (relative to repo root)" },
-          entity: { type: "string", description: "Specific entity name (optional \u2014 if omitted, analyzes all entities in the file)" },
-          repo: { type: "string", description: "Repository name" }
+          file: { type: "string", minLength: 1, description: "File path (relative to repo root)" },
+          entity: { type: "string", minLength: 1, description: 'Entity name or full "repo::file::entity" id (optional \u2014 if omitted, analyzes everything in the file)' },
+          repo: { type: "string", minLength: 1, description: "Repository name" },
+          depth: { type: "integer", minimum: 1, maximum: 5, description: "Dependency hops to follow (default 2, max 5)" }
         },
         required: ["file", "repo"]
       }
     },
     {
       name: "trace_path",
-      description: 'Trace the call chain from a function across multiple hops. With "to", returns the shortest path between two functions; otherwise returns the reachable call tree. Follows confidence-weighted call/import/use edges.',
+      description: 'Trace a call chain across multiple hops. With "to", returns the shortest path (fewest hops, bidirectional BFS) between two symbols; otherwise lists what is reachable, by depth (up to 50 nodes). Follows `calls` edges by default (`relations` for imports, type-refs, inheritance) and skips edges with confidence below 0.7. Names are matched exactly (a full "repo::file::entity" id works too) unless fuzzy:true. A search stops after 50,000 nodes or 1 s and says so \u2014 then narrow it or lower maxDepth.',
       inputSchema: {
         type: "object",
         properties: {
-          from: { type: "string", description: "Starting function name or qualified id (repo::file::entity)" },
-          to: { type: "string", description: "Target function name or qualified id (optional \u2014 shortest path)" },
-          repo: { type: "string", description: "Limit resolution to this repo (optional)" },
+          from: { type: "string", minLength: 1, description: "Starting symbol name or qualified id (repo::file::entity)" },
+          to: { type: "string", minLength: 1, description: "Target symbol name or qualified id (optional \u2014 shortest path)" },
+          repo: { type: "string", minLength: 1, description: "Limit resolution to this repo (optional)" },
           direction: { type: "string", enum: ["callees", "callers", "both"], description: "Traverse callees (what it calls), callers (who calls it), or both. Default callees." },
-          maxDepth: { type: "number", description: "Max hops to traverse (default 4)" },
-          fuzzy: { type: "boolean", description: "Substring-match names instead of exact (default false)" }
+          maxDepth: { type: "integer", minimum: 1, maximum: 10, description: "Max hops to traverse (default 4, max 10)" },
+          fuzzy: { type: "boolean", description: "Case-insensitive substring match on symbol names instead of exact (default false)" },
+          relations: relationsProp("the traversal")
         },
         required: ["from"]
       }
     },
     {
       name: "find_dead_code",
-      description: "List entities (functions, methods, classes) with no callers/importers in a repo \u2014 likely dead code. Heuristic: exported APIs, reflection, and dynamic dispatch produce false positives.",
+      description: "List entities (functions, methods, classes, structs, enums, traits) with no incoming edge in the repo graph and no other mention of their name in their own file \u2014 likely dead code. Heuristic: exported APIs, reflection, and dynamic dispatch produce false positives.",
       inputSchema: {
         type: "object",
         properties: {
-          repo: { type: "string", description: "Repository name" },
-          limit: { type: "number", description: "Max results (default 50)" }
+          repo: { type: "string", minLength: 1, description: "Repository name" },
+          limit: { type: "integer", minimum: 1, description: "Max results (default 50)" }
         },
         required: ["repo"]
       }
@@ -162,59 +322,74 @@ function registerGraphTools() {
       description: "High-level architecture overview of the project \u2014 repo roles, key flows, and how services connect. Built from the LLM-generated project graph and repo profiles.",
       inputSchema: {
         type: "object",
-        properties: { repo: { type: "string", description: "Drill into one repo profile (optional)" } }
+        properties: { repo: { type: "string", minLength: 1, description: "Drill into one repo profile (optional)" } }
       }
     },
     {
       name: "search_graph",
-      description: `Structural search over the knowledge graph: filter entities by name (regex/substring), type, file, and repo; rank by connectivity (degree). Answers "which functions matter most in this module" \u2014 a structural question search/grep can't.`,
+      description: `Structural search over the knowledge graph: filter nodes by name (case-insensitive regex over symbol names), type, file, and repo; rank by connectivity (degree). Answers "which functions matter most in this module" \u2014 a structural question search/grep can't.`,
       inputSchema: {
         type: "object",
         properties: {
-          name: { type: "string", description: "Name regex or substring to match (optional)" },
-          type: { type: "string", description: "Entity type filter: function | class | interface | method | type | \u2026 (optional)" },
-          file: { type: "string", description: "File-path substring filter (optional)" },
-          repo: { type: "string", description: "Limit to this repo (optional)" },
-          minDegree: { type: "number", description: "Only entities with at least this many connections (default 0)" },
-          limit: { type: "number", description: "Max results (default 50)" }
+          name: { type: "string", minLength: 1, description: "Case-insensitive regex over symbol names (a plain substring works too). Files and cross-repo endpoints are skipped unless `type` is module / external. Optional." },
+          type: { type: "string", minLength: 1, description: "Node type: function | method | class | interface | type | const | struct | enum | trait | impl | package | module (a file) | external (a cross-repo endpoint). Optional." },
+          file: { type: "string", minLength: 1, description: "Case-insensitive file-path substring filter (optional)" },
+          repo: { type: "string", minLength: 1, description: "Limit to this repo (optional)" },
+          minDegree: { type: "integer", minimum: 0, description: "Only nodes with at least this many connections, `contains` excluded (default 0)" },
+          limit: { type: "integer", minimum: 1, description: "Max results (default 50)" }
         }
       }
     },
     {
       name: "detect_changes",
-      description: "Map a git diff to affected symbols and their dependents. Compares the working tree against a base commit (or the last-indexed SHA) and reports which entities changed and what depends on them \u2014 a blast-radius / code-review tool. Requires a local repo (local/serve mode).",
+      description: "Map a git diff to affected symbols and their dependents. Diffs the working tree against a base commit (default: the last-indexed SHA) and reports the entities whose line range at the base (from their declaration line to the next declaration) overlaps a changed hunk (every entity of an added or deleted file), the cross-repo endpoints of modified files (file-level), and what directly depends on them \u2014 a blast-radius / code-review tool. Requires a local repo (local/serve mode).",
       inputSchema: {
         type: "object",
         properties: {
-          repo: { type: "string", description: "Repository name" },
-          baseSha: { type: "string", description: "Git base commit to diff against (default: last-indexed SHA)" },
-          limit: { type: "number", description: "Max dependent edges to list (default 50)" }
+          repo: { type: "string", minLength: 1, description: "Repository name" },
+          baseSha: { type: "string", minLength: 1, description: "Git base commit to diff against (default: last-indexed SHA)" },
+          limit: { type: "integer", minimum: 1, description: "Max dependent edges to list (default 50)" }
         },
         required: ["repo"]
       }
     }
   ];
 }
+const SCHEMAS = new Map(registerGraphTools().map((t) => [t.name, t.inputSchema]));
 async function handleGraphTool(name, args, ctx) {
-  if (!GRAPH_TOOL_NAMES.includes(name)) return null;
-  const text = (t) => ({ content: [{ type: "text", text: t }] });
+  const schema = SCHEMAS.get(name);
+  if (!schema) return null;
+  const invalid = validateArgs(schema, args);
+  if (invalid) return toolError(`${name}: ${invalid}`);
+  const text = toolText;
   const NO_GRAPH = "No system graph found. Build KB first.";
   try {
     const blobs = getBlobStore(ctx.projectName, resolvedKnowledgeConfig());
     if (name === "get_repo_graph") {
       const repo = args.repo;
+      const limit = args.limit ?? 50;
       const graph = await blobs.getJson(`${repo}/graph.json`);
-      if (!graph) return text(`No graph found for repo "${repo}"`);
-      const summary = `# ${repo} AST Graph
-
-- **Nodes:** ${graph.nodes?.length ?? 0}
-- **Edges:** ${graph.links?.length ?? 0}
-
-## Entities
-${(graph.nodes ?? []).slice(0, 50).map((n) => `- \`${n.id}\` (${n.type})`).join("\n")}
-
-${graph.nodes?.length > 50 ? `... and ${graph.nodes.length - 50} more` : ""}`;
-      return text(summary);
+      if (!graph) return toolError(`No graph found for repo "${repo}" \u2014 check the name with list_repos.`);
+      const nodes = graph.nodes ?? [];
+      const links = graph.links ?? [];
+      const byType = /* @__PURE__ */ new Map();
+      for (const l of links) byType.set(l.type ?? "edge", (byType.get(l.type ?? "edge") ?? 0) + 1);
+      const listed = links.filter((l) => l.type !== "contains");
+      const more = (n) => n > limit ? [`... and ${n - limit} more`] : [];
+      return text([
+        `# ${repo} AST Graph`,
+        "",
+        `- **Nodes:** ${nodes.length}`,
+        `- **Edges:** ${links.length}${byType.size ? ` (${[...byType].map(([t, n]) => `${t} ${n}`).join(", ")})` : ""}`,
+        "",
+        "## Entities",
+        ...nodes.slice(0, limit).map((n) => `- \`${n.id}\` (${n.type})`),
+        ...more(nodes.length),
+        "",
+        `## Edges (${listed.length}, \`contains\` omitted)`,
+        ...listed.slice(0, limit).map((l) => `- \`${l.source}\` \u2192 \`${l.target}\` (${l.type ?? "edge"})`),
+        ...more(listed.length)
+      ].join("\n"));
     }
     if (name === "get_cross_repo_edges") {
       const store = await getGraphStore(ctx.projectName, resolvedKnowledgeConfig());
@@ -222,14 +397,28 @@ ${graph.nodes?.length > 50 ? `... and ${graph.nodes.length - 50} more` : ""}`;
       const repo = args.repo;
       const { edges, total } = store.crossRepoEdges(repo, 50);
       if (total === 0) return text(repo ? `No cross-repo edges found for "${repo}"` : "No cross-repo edges found");
-      const body = edges.map((e) => `- ${repoOf(e.source)} \u2192 ${repoOf(e.target)} (${e.type ?? "edge"})`).join("\n");
-      return text(`# Cross-Repo Edges${repo ? ` for ${repo}` : ""}
-
-${total} edges found:
-
-${body}${total > edges.length ? `
-
-... and ${total - edges.length} more` : ""}`);
+      const between = edges.filter((e) => repoOf(e.source) !== repoOf(e.target));
+      const within = edges.filter((e) => repoOf(e.source) === repoOf(e.target));
+      const ev = (e) => e.evidence ? ` \u2014 ${e.evidence}` : "";
+      const labels = store.labelsOf(within.flatMap((e) => [e.source, e.target]));
+      const body = [
+        `# Cross-Repo Edges${repo ? ` for ${repo}` : ""}`,
+        "",
+        `${total} edges found:`
+      ];
+      if (between.length) {
+        body.push("", `## Between repos (${between.length} listed)`);
+        for (const e of between) {
+          const arrow = SYMMETRIC_EDGE_TYPES.has(e.type ?? "") ? "\u2194" : "\u2192";
+          body.push(`- ${repoOf(e.source)} ${arrow} ${repoOf(e.target)} (${e.type ?? "edge"})${ev(e)}  \`${fileOf(e.source)}\` ${arrow} \`${fileOf(e.target)}\``);
+        }
+      }
+      if (within.length) {
+        body.push("", `## Within a repo \u2014 workspace packages (${within.length} listed)`);
+        for (const e of within) body.push(`- ${repoOf(e.source)}: ${labels.get(e.source)} \u2192 ${labels.get(e.target)} (${e.type ?? "edge"})${ev(e)}`);
+      }
+      if (total > edges.length) body.push("", `... and ${total - edges.length} more`);
+      return text(body.join("\n"));
     }
     if (name === "find_callers" || name === "find_dependencies") {
       const store = await getGraphStore(ctx.projectName, resolvedKnowledgeConfig());
@@ -237,45 +426,83 @@ ${body}${total > edges.length ? `
       const funcName = args.function;
       const repoFilter = args.repo;
       const fuzzy = args.fuzzy === true;
+      const types = edgeTypes(args);
       const matched = store.resolveNodes(funcName, repoFilter, fuzzy);
       if (matched.length === 0) {
-        return text(`No entity found matching "${funcName}"${repoFilter ? ` in ${repoFilter}` : ""}. Try fuzzy:true for substring matching.`);
+        return text(`No entity found matching "${funcName}"${repoFilter ? ` in ${repoFilter}` : ""}.${fuzzy ? "" : " Try fuzzy:true for substring matching."}`);
       }
       const keys = matched.map((m) => m.key);
-      const unique = name === "find_callers" ? store.callers(keys, 30) : store.dependencies(keys, 30);
-      const direction = name === "find_callers" ? "Callers of" : "Dependencies of";
-      if (unique.length === 0) {
-        return text(`# ${direction} "${funcName}"
+      const fetch = (t) => name === "find_callers" ? store.callers(keys, 30, t) : store.dependencies(keys, 30, t);
+      const found = fetch(types);
+      const noun = name === "find_callers" ? "callers" : "dependencies";
+      const title = `# ${name === "find_callers" ? "Callers of" : "Dependencies of"} "${funcName}"`;
+      const relLabel = types ? types.join(", ") : "any relation";
+      if (found.length === 0) {
+        const other = /* @__PURE__ */ new Map();
+        if (types) for (const o of fetch(void 0)) other.set(o.type, (other.get(o.type) ?? 0) + 1);
+        const hint = other.size ? `
+
+Other relations: ${[...other].map(([t, n]) => `${t} ${n}`).join(", ")} \u2014 pass relations: ${JSON.stringify([...other.keys()])} to list them.` : "";
+        return text(`${title}
 
-Matched ${matched.length} entit${matched.length === 1 ? "y" : "ies"}, but no ${name === "find_callers" ? "callers" : "dependencies"} found.`);
+Matched ${matched.length} entit${matched.length === 1 ? "y" : "ies"}, but no ${noun} via ${relLabel}.${hint}`);
       }
-      return text(`# ${direction} "${funcName}"
+      const byType = /* @__PURE__ */ new Map();
+      for (const f of found) {
+        if (!byType.has(f.type)) byType.set(f.type, []);
+        byType.get(f.type).push(f.key);
+      }
+      const sections = [...byType].map(([t, ks]) => `## ${t} (${ks.length})
+${ks.map((k) => `- \`${k}\``).join("\n")}`).join("\n\n");
+      return text(`${title}
+
+${found.length} found (${relLabel}):
 
-${unique.length} found:
-${unique.map((r) => `- \`${r}\``).join("\n")}`);
+${sections}`);
     }
     if (name === "impact_analysis") {
       const store = await getGraphStore(ctx.projectName, resolvedKnowledgeConfig());
       if (!store) return text("No system graph found.");
       const file = args.file;
       const repo = args.repo;
-      const entity = args.entity;
-      const fileKeys = store.nodesInFiles(repo, [file], entity);
-      const { edges: dependents, total, repos } = store.dependents(fileKeys, 30);
+      const depth = args.depth ?? 2;
+      let entity = args.entity;
+      if (entity?.includes("::")) {
+        const prefix = `${repo}::${file}::`;
+        if (!entity.startsWith(prefix)) return toolError(`impact_analysis: entity id "${entity}" is not in ${repo}/${file} \u2014 pass a bare name or an id starting with "${prefix}".`);
+        entity = entity.slice(prefix.length);
+      }
+      const fileKeys = store.nodesInFiles(repo, [file]);
+      if (fileKeys.length === 0) return toolError(`No graph nodes for ${repo}/${file} \u2014 check the repo name and that the path is repo-relative and indexed.`);
+      const scope = entity ? store.nodesInFiles(repo, [file], entity) : fileKeys;
+      if (scope.length === 0) return toolError(`No entity "${entity}" in ${repo}/${file}.`);
+      const endpoints = entity ? endpointsIn(store, fileKeys).filter((k) => !scope.includes(k)) : [];
+      const fileLevel = new Set(endpoints);
+      const budget = new TraversalBudget();
+      const { hops, repos } = dependentHops(store, [...scope, ...endpoints], depth, fileLevel, budget);
+      const total = hops.reduce((n, h) => n + h.total, 0);
+      const truncated = hops.some((h) => h.truncated);
       const body = [
-        `# Impact Analysis: ${repo}/${file}${entity ? `::${entity}` : ""}`,
-        "",
-        `## Entities in scope: ${fileKeys.length}`,
-        ...fileKeys.slice(0, 20).map((k) => `- \`${k}\``),
+        `# Impact Analysis: ${repo}/${file}${entity ? `::${entity}` : ""} (depth ${depth})`,
         "",
-        `## Dependents: ${total} edges from ${repos.length} repos`,
-        ...dependents.map((e) => `- \`${e.source}\` \u2192 \`${e.target}\` (${e.type ?? "edge"})`),
-        total > dependents.length ? `
-... and ${total - dependents.length} more` : "",
-        "",
-        `## Affected repos: ${repos.join(", ") || "none"}`
-      ].join("\n");
-      return text(body);
+        `## Entities in scope: ${scope.length}`,
+        ...scope.slice(0, 20).map((k) => `- \`${k}\``)
+      ];
+      if (endpoints.length) {
+        body.push("", `## File-level endpoints: ${endpoints.length} (cross-repo endpoints in ${file}, not tied to ${entity})`, ...endpoints.slice(0, 20).map((k) => `- \`${k}\``));
+      }
+      body.push("", `## Dependents: ${total}${atLeast(truncated)} edges from ${repos.size} repos`);
+      for (const h of hops) {
+        if (h.edges.length === 0) continue;
+        body.push(`### Hop ${h.hop} (${h.total}${atLeast(h.truncated)})`, ...h.edges.slice(0, 30).map((e) => edgeLine(e, fileLevel)));
+        if (h.total > Math.min(h.edges.length, 30)) body.push(`... and ${h.total - Math.min(h.edges.length, 30)}${atLeast(h.truncated)} more`);
+      }
+      if (truncated) body.push("", AT_LEAST_NOTE);
+      if (budget.exhausted) {
+        body.push("", `_Stopped before hop ${hops.length + 1} at the traversal budget (explored ${budget.explored} nodes) \u2014 lower depth or pass an entity._`);
+      }
+      body.push("", `## Affected repos: ${[...repos].join(", ") || "none"}`);
+      return text(body.join("\n"));
     }
     if (name === "trace_path") {
       const store = await getGraphStore(ctx.projectName, resolvedKnowledgeConfig());
@@ -285,14 +512,18 @@ ${unique.map((r) => `- \`${r}\``).join("\n")}`);
       const repo = args.repo;
       const fuzzy = args.fuzzy === true;
       const direction = args.direction ?? "callees";
-      const maxDepth = Math.max(1, Math.min(10, args.maxDepth || 4));
+      const maxDepth = args.maxDepth ?? 4;
       const fromKeys = store.resolveNodes(from, repo, fuzzy).map((m) => m.key);
-      if (fromKeys.length === 0) return text(`No entity found matching "${from}". Try fuzzy:true.`);
-      const getNeighbors = makeNeighborGetter(store, direction);
+      if (fromKeys.length === 0) return text(`No entity found matching "${from}".${fuzzy ? "" : " Try fuzzy:true."}`);
+      const types = edgeTypes(args);
+      const budget = new TraversalBudget();
       if (to) {
-        const toKeys = new Set(store.resolveNodes(to, repo, fuzzy).map((m) => m.key));
-        if (toKeys.size === 0) return text(`No entity found matching target "${to}". Try fuzzy:true.`);
-        const path = shortestPath(getNeighbors, fromKeys, toKeys, maxDepth);
+        const toKeys = store.resolveNodes(to, repo, fuzzy).map((m) => m.key);
+        if (toKeys.length === 0) return text(`No entity found matching target "${to}".${fuzzy ? "" : " Try fuzzy:true."}`);
+        const { path, depth } = shortestPath(store, fromKeys, toKeys, maxDepth, direction, types, budget);
+        if (!path && budget.exhausted) {
+          return text(`No path from "${from}" to "${to}" found within the traversal budget (explored ${budget.explored} nodes, depth ${depth} of ${maxDepth}, direction: ${direction}) \u2014 narrow the search (repo, exact names, relations) or lower maxDepth.`);
+        }
         if (!path) return text(`No path from "${from}" to "${to}" within ${maxDepth} hops (direction: ${direction}).`);
         const labelOf2 = store.labelsOf(path);
         const arrow = direction === "callers" ? " \u2190 " : " \u2192 ";
@@ -303,8 +534,11 @@ ${rendered}
 
 ${path.map((k) => `- \`${k}\``).join("\n")}`);
       }
-      const nodes = reachable(getNeighbors, fromKeys, maxDepth);
-      if (nodes.length === 0) return text(`No ${direction} reachable from "${from}" within ${maxDepth} hops.`);
+      const nodes = reachable(store, fromKeys, maxDepth, direction, types, budget);
+      const stopped = budget.exhausted ? `
+
+_Stopped early at the traversal budget (explored ${budget.explored} nodes) \u2014 narrow the search or lower maxDepth._` : "";
+      if (nodes.length === 0) return text(`No ${direction} reachable from "${from}" within ${maxDepth} hops.${stopped}`);
       const labelOf = store.labelsOf(nodes.map((n) => n.key));
       const byDepth = /* @__PURE__ */ new Map();
       for (const { key, depth } of nodes) {
@@ -317,20 +551,25 @@ ${ks.map((k) => `- ${k}`).join("\n")}`).join("\n\n");
 
 ${nodes.length} nodes:
 
-${sections}`);
+${sections}${stopped}`);
     }
     if (name === "find_dead_code") {
       const repo = args.repo;
-      const limit = args.limit || 50;
+      const limit = args.limit ?? 50;
       const graph = await blobs.getJson(`${repo}/graph.json`);
-      if (!graph) return text(`No graph found for repo "${repo}"`);
+      if (!graph) return toolError(`No graph found for repo "${repo}" \u2014 check the name with list_repos.`);
       const ENTITY_TYPES = /* @__PURE__ */ new Set(["function", "method", "class", "struct", "enum", "trait"]);
       const inDegree = /* @__PURE__ */ new Map();
       for (const l of graph.links ?? []) {
         if (l.type === "contains") continue;
         inDegree.set(l.target, (inDegree.get(l.target) ?? 0) + 1);
       }
-      const dead = (graph.nodes ?? []).filter((n) => ENTITY_TYPES.has(n.type) && (inDegree.get(n.id) ?? 0) === 0);
+      const candidates = (graph.nodes ?? []).filter((n) => ENTITY_TYPES.has(n.type) && (inDegree.get(n.id) ?? 0) === 0);
+      const source = await indexedSources(ctx.projectName, repo, [...new Set(candidates.map((n) => n.file).filter(Boolean))]);
+      const dead = candidates.filter((n) => {
+        const src = source.get(n.file);
+        return src === void 0 || identifierCount(src, n.label ?? n.id) <= 1;
+      });
       if (dead.length === 0) return text(`# Dead code in ${repo}
 
 No zero-caller entities found.`);
@@ -349,7 +588,7 @@ _Note: exported APIs, reflection, and dynamic dispatch can cause false positives
       const repo = args.repo;
       if (repo) {
         const profile = await loadProfile(ctx.projectName, repo, resolvedKnowledgeConfig());
-        if (!profile) return text(`No profile for "${repo}". Run profiling (requires LLM) to generate one.`);
+        if (!profile) return text(missingProfileText(repo));
         const ep = (xs) => xs?.length ? xs.map((e) => `  - ${e.type}: ${e.identifier} \u2014 ${e.description}`).join("\n") : "  - (none)";
         const body = [
           `# ${profile.name} \u2014 ${profile.role} (${profile.domain})`,
@@ -397,9 +636,9 @@ _Note: exported APIs, reflection, and dynamic dispatch can cause false positives
 
 ${profiles.map((p) => `- **${p.name}** \u2014 ${p.role} (${p.domain}): ${p.description}`).join("\n")}
 
-_Run project-graph generation (requires LLM) for a full architecture view._`);
+_A full architecture view needs the LLM project graph (\`anvil graph build\`)._`);
       }
-      return text("No architecture data yet. Index the project, then run profiling / project-graph generation (requires an LLM) for an architecture overview.");
+      return text("No architecture data yet: it needs repo profiles (generated during indexing when an LLM is configured) or the LLM project graph (`anvil graph build`).");
     }
     if (name === "search_graph") {
       const store = await getGraphStore(ctx.projectName, resolvedKnowledgeConfig());
@@ -410,7 +649,7 @@ _Run project-graph generation (requires LLM) for a full architecture view._`);
         file: args.file,
         repo: args.repo,
         minDegree: args.minDegree ?? 0
-      }, args.limit || 50);
+      }, args.limit ?? 50);
       if (total === 0) return text("No entities match the given filters.");
       const body = rows.map((m) => `- \`${m.label}\` (${m.type}, ${m.file}) \u2014 degree ${m.degree}  \`${m.key}\``).join("\n");
       return text(`# search_graph \u2014 ${total} match${total === 1 ? "" : "es"}
@@ -421,13 +660,13 @@ ${body}${total > rows.length ? `
     }
     if (name === "detect_changes") {
       const repo = args.repo;
-      const limit = args.limit || 50;
+      const limit = args.limit ?? 50;
       if (!ctx.directoryPath) {
-        return text("detect_changes needs a local repo path \u2014 available in local/serve mode only (not remote-proxy mode).");
+        return toolError("detect_changes needs a local repo path \u2014 available in local/serve mode only (not remote-proxy mode).");
       }
       const candidate = join(ctx.directoryPath, repo);
       const repoPath = existsSync(join(candidate, ".git")) ? candidate : ctx.directoryPath;
-      if (!existsSync(repoPath)) return text(`Repo path not found: ${repoPath}`);
+      if (!existsSync(repoPath)) return toolError(`Repo path not found: ${repoPath}`);
       let baseSha = args.baseSha;
       if (!baseSha) {
         try {
@@ -436,43 +675,87 @@ ${body}${total > rows.length ? `
         } catch {
         }
       }
-      if (!baseSha) return text("No base commit available. Pass baseSha, or index the repo first so a last-indexed SHA exists.");
+      if (!baseSha) return toolError("No base commit available. Pass baseSha, or index the repo first so a last-indexed SHA exists.");
       const diff = getAllChanges(repoPath, baseSha);
-      if (diff.fallbackToFull) return text(`git diff against ${baseSha.slice(0, 7)} failed or is too large to map incrementally. Check the base SHA.`);
+      if (diff.fallbackToFull) return toolError(`git diff against ${baseSha.slice(0, 7)} failed or is too large to map incrementally. Check the base SHA.`);
       const changedFiles = getChangedFilesList(diff);
       if (changedFiles.length === 0 && diff.deleted.length === 0) return text(`No source changes since ${baseSha.slice(0, 7)}.`);
       const store = await getGraphStore(ctx.projectName, resolvedKnowledgeConfig());
-      let changedKeys = [];
-      let dependents = [];
-      let depTotal = 0;
-      let depRepos = [];
+      const changedKeys = [];
+      const endpoints = [];
+      const wholeFile = [];
+      const unlocated = /* @__PURE__ */ new Set();
+      let hops = [];
+      let depRepos = /* @__PURE__ */ new Set();
+      const fileLevel = /* @__PURE__ */ new Set();
+      let budget = null;
       if (store) {
-        changedKeys = store.nodesInFiles(repo, changedFiles);
-        const d = store.dependents(changedKeys, limit);
-        dependents = d.edges;
-        depTotal = d.total;
-        depRepos = d.repos;
+        changedKeys.push(...store.nodesInFiles(repo, [...diff.added, ...diff.deleted]));
+        const hunks = diffHunks(repoPath, baseSha, diff.modified);
+        for (const file of diff.modified) {
+          const fileKeys = store.nodesInFiles(repo, [file]);
+          const types = store.nodeTypes(fileKeys);
+          const modKey = `${repo}::${file}`;
+          const entities = new Map(fileKeys.filter((k) => k.startsWith(`${modKey}::`) && !["module", "external", "package"].includes(types.get(k) ?? "")).map((k) => [k.slice(modKey.length + 2), k]));
+          endpoints.push(...fileKeys.filter((k) => types.get(k) === "external"));
+          let base;
+          try {
+            base = runGit(repoPath, ["show", `${baseSha}:${file}`]);
+          } catch {
+            wholeFile.push(file);
+            changedKeys.push(...fileKeys.filter((k) => types.get(k) !== "external"));
+            continue;
+          }
+          const ranges = declarationRanges(base, [...entities.keys()]);
+          const { names, fileLevel: touchesFile } = touchedEntities(ranges, hunks.get(file) ?? []);
+          if (touchesFile && fileKeys.includes(modKey)) changedKeys.push(modKey);
+          const located = new Set(ranges.map((r) => r.name));
+          for (const [name2, key] of entities) {
+            if (names.has(name2)) changedKeys.push(key);
+            else if (!located.has(name2)) {
+              changedKeys.push(key);
+              unlocated.add(key);
+            }
+          }
+        }
+        for (const k of endpoints) fileLevel.add(k);
+        budget = new TraversalBudget();
+        ({ hops, repos: depRepos } = dependentHops(store, [...changedKeys, ...endpoints], 1, fileLevel, budget));
       }
+      const dependents = hops[0]?.edges ?? [];
+      const depTotal = hops[0]?.total ?? 0;
+      const plus = atLeast(hops[0]?.truncated ?? false);
       const lines = [
         `# Changes since ${baseSha.slice(0, 7)} \u2014 ${repo}`,
         "",
-        `## Changed files: ${changedFiles.length} (+${diff.added.length} / ~${diff.modified.length}), deleted ${diff.deleted.length}`,
-        ...changedFiles.slice(0, 30).map((f) => `- ${f}`),
+        `## Changed files: ${changedFiles.length} (+${diff.added.length} / ~${diff.modified.length})`,
+        ...changedFiles.slice(0, 30).map((f) => `- ${f}${wholeFile.includes(f) ? " (not readable at the base \u2014 every entity in the file)" : ""}`),
+        "",
+        `## Deleted files: ${diff.deleted.length}`,
+        ...diff.deleted.slice(0, 30).map((f) => `- ${f}`),
         "",
         `## Affected entities: ${changedKeys.length}`,
-        ...changedKeys.slice(0, 30).map((k) => `- \`${k}\``),
+        ...changedKeys.slice(0, 30).map((k) => `- \`${k}\`${unlocated.has(k) ? " (declaration not found in the file \u2014 included to be safe)" : ""}`)
+      ];
+      if (endpoints.length) {
+        lines.push("", `## File-level endpoints: ${endpoints.length} (cross-repo endpoints in modified files)`, ...endpoints.slice(0, 30).map((k) => `- \`${k}\``));
+      }
+      lines.push(
         "",
-        `## Dependents: ${depTotal} edges from ${depRepos.length} repo(s)`,
-        ...dependents.map((e) => `- \`${e.source}\` \u2192 \`${e.target}\` (${e.type ?? "edge"})`),
+        `## Dependents: ${depTotal}${plus} edges from ${depRepos.size} repo(s)`,
+        ...dependents.slice(0, limit).map((e) => edgeLine(e, fileLevel)),
+        ...depTotal > Math.min(dependents.length, limit) ? [`... and ${depTotal - Math.min(dependents.length, limit)}${plus} more`] : [],
+        ...plus ? ["", AT_LEAST_NOTE] : [],
+        ...budget?.exhausted ? ["", `_Dependents not looked up: ${budget.explored} affected nodes exceed the traversal budget \u2014 diff against a closer baseSha._`] : [],
         "",
-        `## Affected repos: ${depRepos.join(", ") || "none"}`
-      ];
+        `## Affected repos: ${[...depRepos].join(", ") || "none"}`
+      );
       return text(lines.join("\n"));
     }
     return null;
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    return { content: [{ type: "text", text: `Graph tool error: ${msg}` }] };
+    return toolError(`Graph tool error: ${msg}`);
   }
 }
 export {