@esankhan3/code-search-mcp 1.1.0 → 1.1.2

package/dist/__tests__/graph-traversal.test.js

@@ -0,0 +1,262 @@
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { createSystemGraphSqliteWriter, getGraphStore, invalidateRetriever } from "@esankhan3/anvil-knowledge-core";
+import { handleGraphTool } from "../tools/graph.js";
+const MAX_NODES = 5e4;
+let tmp = "";
+let stashDataDir;
+function ctx(projectName) {
+  return {
+    projectName,
+    directoryPath: null,
+    indexReady: true,
+    startedAt: 0,
+    indexing: {
+      status: "idle",
+      phase: null,
+      message: null,
+      percent: 0,
+      startedAt: null,
+      error: null,
+      lastSuccess: null,
+      lastDurationMs: 0,
+      history: []
+    }
+  };
+}
+const text = (r) => r?.content?.[0]?.text ?? "";
+const call = async (project, name, args) => text(await handleGraphTool(name, args, ctx(project)));
+const key = (name, file = "f.ts") => `r::${file}::${name}`;
+async function writeGraph(project, nodes, edges, fileOf = (_n) => "f.ts") {
+  const kb = join(tmp, project);
+  mkdirSync(kb, { recursive: true });
+  const w = await createSystemGraphSqliteWriter(kb);
+  assert.ok(w, "no sqlite driver");
+  w.addRepoGraph("r", {
+    nodes: nodes.map((n) => ({ id: `${n.file ?? "f.ts"}::${n.name}`, label: n.name, type: "function", file: n.file ?? "f.ts" })),
+    links: edges.map((e) => ({ source: `${fileOf(e.s)}::${e.s}`, target: `${fileOf(e.t)}::${e.t}`, type: e.type, confidence: e.confidence }))
+  });
+  w.finalize();
+}
+async function instrument(project, methods, onRead = () => {
+}) {
+  const store = await getGraphStore(project);
+  const nodes = /* @__PURE__ */ new Set();
+  for (const m of methods) {
+    const orig = store[m];
+    if (typeof orig !== "function") continue;
+    store[m] = (...a) => {
+      const r = orig.apply(store, a);
+      if (Array.isArray(r)) for (const x of r) for (const k of Array.isArray(x) ? x : [x]) nodes.add(k);
+      onRead();
+      return r;
+    };
+  }
+  return { nodes, restore: () => {
+    for (const m of methods) delete store[m];
+  } };
+}
+function expireClock() {
+  const real = Date.now;
+  Date.now = () => real() + 6e4;
+  return () => {
+    Date.now = real;
+  };
+}
+before(() => {
+  stashDataDir = process.env.CODE_SEARCH_DATA_DIR;
+  tmp = mkdtempSync(join(tmpdir(), "cs-trav-"));
+  process.env.CODE_SEARCH_DATA_DIR = tmp;
+});
+after(async () => {
+  await invalidateRetriever();
+  rmSync(tmp, { recursive: true, force: true });
+  if (stashDataDir === void 0) delete process.env.CODE_SEARCH_DATA_DIR;
+  else process.env.CODE_SEARCH_DATA_DIR = stashDataDir;
+});
+function rng(seed) {
+  return () => {
+    seed = seed + 1831565813 | 0;
+    let t = Math.imul(seed ^ seed >>> 15, 1 | seed);
+    t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+function steps(edges, direction, types) {
+  const adj = /* @__PURE__ */ new Map();
+  const add = (a, b) => {
+    if (!adj.has(a)) adj.set(a, /* @__PURE__ */ new Set());
+    adj.get(a).add(b);
+  };
+  for (const e of edges) {
+    if (e.confidence < 0.7 || types && !types.includes(e.type)) continue;
+    if (direction !== "callers") add(e.s, e.t);
+    if (direction !== "callees") add(e.t, e.s);
+  }
+  return adj;
+}
+function bfsHops(adj, from, to) {
+  if (from === to) return null;
+  const dist = /* @__PURE__ */ new Map([[from, 0]]);
+  let frontier = [from];
+  while (frontier.length > 0) {
+    const next = [];
+    for (const k of frontier) {
+      for (const n of adj.get(k) ?? []) {
+        if (dist.has(n)) continue;
+        dist.set(n, dist.get(k) + 1);
+        if (n === to) return dist.get(n);
+        next.push(n);
+      }
+    }
+    frontier = next;
+  }
+  return null;
+}
+const pathKeys = (t) => [...t.matchAll(/^- `([^`]+)`$/gm)].map((m) => m[1]);
+describe("trace_path \u2014 shortest path", () => {
+  it("matches a plain BFS on random graphs: hop count, a real path, maxDepth", async () => {
+    const rand = rng(7);
+    const pick = (xs) => xs[Math.floor(rand() * xs.length)];
+    let paths = 0;
+    let none = 0;
+    for (let g = 0; g < 25; g++) {
+      const n = 8 + Math.floor(rand() * 20);
+      const names = Array.from({ length: n }, (_, i) => `n${i}`);
+      const edges = Array.from({ length: Math.floor(n * (1 + rand() * 1.5)) }, () => ({
+        s: pick(names),
+        t: pick(names),
+        type: rand() < 0.75 ? "calls" : "imports",
+        confidence: rand() < 0.85 ? 0.9 : 0.5
+      }));
+      const project = `rnd${g}`;
+      await writeGraph(project, names.map((name) => ({ name })), edges);
+      for (let q = 0; q < 16; q++) {
+        const from = pick(names);
+        const to = pick(names);
+        const direction = pick(["callees", "callers", "both"]);
+        const relations = pick([void 0, ["imports"], ["all"]]);
+        const maxDepth = 1 + Math.floor(rand() * 6);
+        const adj = steps(edges, direction, relations === void 0 ? ["calls"] : relations[0] === "all" ? null : relations);
+        const want = bfsHops(adj, from, to);
+        const t = await call(project, "trace_path", { from: key(from), to: key(to), direction, maxDepth, ...relations ? { relations } : {} });
+        const label = `${project}: ${from} \u2192 ${to} (${direction}, ${relations ?? "calls"}, maxDepth ${maxDepth})
+${t}`;
+        if (want === null || want > maxDepth) {
+          assert.match(t, new RegExp(`^No path from .* within ${maxDepth} hops`), label);
+          none++;
+          continue;
+        }
+        assert.equal(Number(/^# Path \((\d+) hops\)/.exec(t)?.[1]), want, label);
+        const keys = pathKeys(t);
+        assert.equal(keys.length, want + 1, label);
+        assert.equal(keys[0], key(from), label);
+        assert.equal(keys[keys.length - 1], key(to), label);
+        for (let i = 1; i < keys.length; i++) {
+          assert.ok(adj.get(keys[i - 1].split("::")[2])?.has(keys[i].split("::")[2]), `no step ${keys[i - 1]} \u2192 ${keys[i]} in ${label}`);
+        }
+        paths++;
+      }
+    }
+    assert.ok(paths >= 60 && none >= 60, `sample covers both outcomes (${paths} paths, ${none} none)`);
+  });
+  it("picks the shorter of two routes and honours maxDepth exactly", async () => {
+    const e = (s, t2) => ({ s, t: t2, type: "calls", confidence: 0.9 });
+    await writeGraph("routes", ["a", "b", "c", "d", "e", "x", "y"].map((name) => ({ name })), [
+      e("a", "b"),
+      e("b", "c"),
+      e("c", "d"),
+      e("d", "e"),
+      // 4 hops
+      e("a", "x"),
+      e("x", "y"),
+      e("y", "e")
+      // 3 hops
+    ]);
+    const t = await call("routes", "trace_path", { from: "a", to: "e" });
+    assert.match(t, /# Path \(3 hops\)\n\na → x → y → e/);
+    assert.match(await call("routes", "trace_path", { from: "a", to: "e", maxDepth: 3 }), /3 hops/);
+    assert.match(await call("routes", "trace_path", { from: "a", to: "e", maxDepth: 2 }), /^No path from "a" to "e" within 2 hops/);
+    assert.match(await call("routes", "trace_path", { from: "e", to: "a", direction: "callers" }), /# Path \(3 hops\)\n\ne ← y ← x ← a/);
+    assert.match(await call("routes", "trace_path", { from: "e", to: "a" }), /^No path from "e" to "a"/);
+  });
+});
+describe("traversal budget on a high-fan-out graph", () => {
+  const FAN = 250;
+  before(async () => {
+    const nodes = [{ name: "src" }, { name: "dst" }, { name: "sink", file: "sink.ts" }];
+    const edges = [];
+    const calls = (s, t) => edges.push({ s, t, type: "calls", confidence: 0.9 });
+    for (let i = 0; i < FAN; i++) {
+      nodes.push({ name: `c${i}` }, { name: `k${i}` });
+      calls("src", `c${i}`);
+      calls(`k${i}`, "dst");
+      for (let j = 0; j < FAN; j++) {
+        nodes.push({ name: `g${i}_${j}` });
+        calls(`c${i}`, `g${i}_${j}`);
+        calls(`g${i}_${j}`, "sink");
+      }
+    }
+    await writeGraph("fan", nodes, edges, (n) => n === "sink" ? "sink.ts" : "f.ts");
+  });
+  it('trace_path stops at the node cap and says so instead of "No path"', async () => {
+    const reads = await instrument("fan", ["neighborsOf", "neighborEdges"]);
+    try {
+      const t = await call("fan", "trace_path", { from: "src", to: "dst", maxDepth: 10 });
+      assert.match(t, /^No path from "src" to "dst" found within the traversal budget \(explored \d+ nodes, depth \d+ of 10/);
+      assert.match(t, /narrow the search .* or lower maxDepth/);
+      assert.ok(Number(/explored (\d+) nodes/.exec(t)?.[1]) <= MAX_NODES, t);
+      assert.ok(reads.nodes.size <= MAX_NODES, `read ${reads.nodes.size} distinct nodes`);
+    } finally {
+      reads.restore();
+    }
+  });
+  it("trace_path stops when the wall-clock budget runs out", async () => {
+    let restoreClock = () => {
+    };
+    let queries = 0;
+    const reads = await instrument("fan", ["neighborsOf", "neighborEdges"], () => {
+      if (++queries === 1) restoreClock = expireClock();
+    });
+    try {
+      const t = await call("fan", "trace_path", { from: "src", to: "dst", maxDepth: 10 });
+      assert.match(t, /found within the traversal budget \(explored \d+ nodes, depth 1 of 10/);
+      assert.equal(queries, 1);
+    } finally {
+      restoreClock();
+      reads.restore();
+    }
+  });
+  it("trace_path still finds a path into a hub within the budget", async () => {
+    const t = await call("fan", "trace_path", { from: "c0", to: "sink", maxDepth: 10 });
+    assert.match(t, /# Path \(2 hops\)\n\nc0 → g0_\d+ → sink/);
+  });
+  it("impact_analysis caps the dependents scanned per hop and marks the count as a lower bound", async () => {
+    const t = await call("fan", "impact_analysis", { repo: "r", file: "sink.ts", depth: 1 });
+    assert.match(t, new RegExp(`## Dependents: ${MAX_NODES}\\+ edges`));
+    assert.match(t, new RegExp(`### Hop 1 \\(${MAX_NODES}\\+\\)`));
+  });
+  it("impact_analysis stops between hops when the wall-clock budget runs out", async () => {
+    let restoreClock = () => {
+    };
+    let expired = false;
+    const reads = await instrument("fan", ["dependents"], () => {
+      if (!expired) {
+        expired = true;
+        restoreClock = expireClock();
+      }
+    });
+    try {
+      const t = await call("fan", "impact_analysis", { repo: "r", file: "sink.ts", depth: 3 });
+      assert.match(t, /### Hop 1/);
+      assert.doesNotMatch(t, /### Hop 2/);
+      assert.match(t, /traversal budget/);
+    } finally {
+      restoreClock();
+      reads.restore();
+    }
+  });
+});

package/dist/tools/graph.js

@@ -17,49 +17,90 @@ import { missingProfileText } from "./profile.js";
 import { toolError, toolText, validateArgs } from "./validate.js";
 const repoOf = (key) => key.split("::")[0] ?? "";
 const fileOf = (key) => key.split("::")[1] ?? "";
-function makeNeighborGetter(store, direction, types) {
-  const cache = /* @__PURE__ */ new Map();
-  return (key) => {
-    let v = cache.get(key);
-    if (v === void 0) {
-      v = store.neighborsOf(key, direction, types);
-      cache.set(key, v);
+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 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 (toKeys.has(nb) && nb !== path[0]) return [...path, nb];
-        if (visited.has(nb)) continue;
-        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;
@@ -69,13 +110,15 @@ function endpointsIn(store, keys) {
   return keys.filter((k) => types.get(k) === "external");
 }
 const HOP_EDGE_CAP = 1e3;
-function dependentHops(store, scope, depth, fileLevel) {
+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++) {
-    const d = store.dependents(frontier, HOP_EDGE_CAP);
+    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 = [];
@@ -88,11 +131,13 @@ function dependentHops(store, scope, depth, fileLevel) {
       }
     }
     for (const k of next) if (!direct.has(k)) fileLevel.add(k);
-    hops.push({ hop, edges, total: d.total - (d.edges.length - edges.length) });
+    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]" : ""}`;
@@ -231,7 +276,7 @@ function registerGraphTools() {
     },
     {
       name: "impact_analysis",
-      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.",
+      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: {
@@ -245,7 +290,7 @@ function registerGraphTools() {
     },
     {
       name: "trace_path",
-      description: 'Trace a call chain across multiple hops. With "to", returns the shortest path (fewest hops, unweighted 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.',
+      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: {
@@ -433,8 +478,10 @@ ${sections}`);
       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 { hops, repos } = dependentHops(store, [...scope, ...endpoints], depth, fileLevel);
+      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}` : ""} (depth ${depth})`,
         "",
@@ -444,11 +491,15 @@ ${sections}`);
       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} edges from ${repos.size} repos`);
+      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})`, ...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)} more`);
+        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"));
@@ -464,11 +515,15 @@ ${sections}`);
       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}".${fuzzy ? "" : " Try fuzzy:true."}`);
-      const getNeighbors = makeNeighborGetter(store, direction, edgeTypes(args));
+      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}".${fuzzy ? "" : " 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 ";
@@ -479,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) {
@@ -493,7 +551,7 @@ ${ks.map((k) => `- ${k}`).join("\n")}`).join("\n\n");
 
 ${nodes.length} nodes:
 
-${sections}`);
+${sections}${stopped}`);
     }
     if (name === "find_dead_code") {
       const repo = args.repo;
@@ -630,6 +688,7 @@ ${body}${total > rows.length ? `
       let hops = [];
       let depRepos = /* @__PURE__ */ new Set();
       const fileLevel = /* @__PURE__ */ new Set();
+      let budget = null;
       if (store) {
         changedKeys.push(...store.nodesInFiles(repo, [...diff.added, ...diff.deleted]));
         const hunks = diffHunks(repoPath, baseSha, diff.modified);
@@ -660,10 +719,12 @@ ${body}${total > rows.length ? `
           }
         }
         for (const k of endpoints) fileLevel.add(k);
-        ({ hops, repos: depRepos } = dependentHops(store, [...changedKeys, ...endpoints], 1, fileLevel));
+        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}`,
         "",
@@ -681,9 +742,11 @@ ${body}${total > rows.length ? `
       }
       lines.push(
         "",
-        `## Dependents: ${depTotal} edges from ${depRepos.size} repo(s)`,
+        `## 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)} more`] : [],
+        ...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"}`
       );

package/dist/tools/index-tools.js

@@ -9,6 +9,9 @@ function describeVectorIndex(v) {
     v.trainedRows ? `trained on ${v.trainedRows.toLocaleString()} rows at ${v.trainedAt}, +${v.rowsAddedSinceTrain.toLocaleString()} since (${Math.round(v.rowsAddedSinceTrain / v.trainedRows * 100)}%)` : "training untracked (retrains on the next writer run)"
   );
   parts.push(`${(v.numUnindexedRows ?? 0).toLocaleString()} unindexed rows`);
+  if (v.nprobes) {
+    parts.push(`${v.nprobes} probes per query (recall@10 ${v.calibratedRecall?.toFixed(3)} on ${v.calibrationQueries} query-like probes)`);
+  }
   if (v.retrainStartedAt) parts.push(`retrain started ${v.retrainStartedAt} has not completed`);
   if (v.lastError) parts.push(`last error: ${v.lastError}`);
   return parts.join("; ");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esankhan3/code-search-mcp",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "MCP server for multi-repo code search \u2014 GitHub org or local path, zero config",
   "type": "module",
   "license": "MIT",
@@ -24,7 +24,7 @@
   },
   "dependencies": {
     "@esankhan3/anvil-agent-core": "^0.5.0",
-    "@esankhan3/anvil-knowledge-core": "^0.4.0",
+    "@esankhan3/anvil-knowledge-core": "^0.4.8",
     "@modelcontextprotocol/node": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0"
   },