@ashkand/code-graph-mcp 0.2.2

package/src/server.js

@@ -0,0 +1,149 @@
+// MCP server exposing the code graph tools (spec R3), over stdio or
+// Streamable HTTP (spec R8, for Claude custom connectors).
+import http from "node:http";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { z } from "zod";
+import { Graph } from "./graph.js";
+import { fullIndex } from "./indexer.js";
+import * as T from "./tools.js";
+
+const detailParam = z.enum(["compact", "full"]).optional().describe("compact (default) = terse line output; full = expanded lists");
+const maxTokensParam = z.number().int().min(100).max(20000).optional().describe("response token budget (default 2000)");
+
+function loadOrIndex(repoRoot) {
+  let graph = Graph.load(repoRoot);
+  if (!graph) {
+    const res = fullIndex(repoRoot);
+    graph = res.graph;
+    console.error(`[code-graph-mcp] full index: ${graph.stats().nodes} nodes in ${res.ms}ms (${res.warnings.length} warnings)`);
+  } else {
+    console.error(`[code-graph-mcp] loaded graph: ${graph.stats().nodes} nodes / ${graph.stats().edges} edges`);
+  }
+  return { graph };
+}
+
+export function buildServer(ref) {
+  const server = new McpServer({ name: "code-graph-mcp", version: "0.2.2" });
+  const text = (s) => ({ content: [{ type: "text", text: s }] });
+
+  server.registerTool("repo_summary", {
+    title: "Repo summary",
+    description: "High-level overview of the indexed repo: packages, dependency highlights, frontend routes, backend routes, node/edge counts, and session token-savings stats. Call this FIRST for any structural question instead of listing directories.",
+    inputSchema: { detail: detailParam, max_tokens: maxTokensParam },
+  }, async (a) => text(T.repoSummary(ref.graph, a)));
+
+  server.registerTool("find_component_relations", {
+    title: "Find component relations",
+    description: "Given a component or route name, return everything related: child components it renders, parents that render it, hooks/stores used, endpoints it calls, and file import relationships. Use instead of grepping for usages.",
+    inputSchema: { name: z.string().describe("component or route name, e.g. LoginPage or /login"), detail: detailParam, max_tokens: maxTokensParam },
+  }, async (a) => text(T.findComponentRelations(ref.graph, a)));
+
+  server.registerTool("map_frontend_to_backend", {
+    title: "Map frontend to backend",
+    description: "Trace the full chain Component/Route -> HTTP call -> backend route -> handler function. Accepts a frontend name (LoginPage), a route (/login), or an endpoint path (/api/login) and works from either end. Use for 'where does X land in the backend?' questions.",
+    inputSchema: { name: z.string().describe("component name, frontend route, or endpoint path"), max_tokens: maxTokensParam },
+  }, async (a) => text(T.mapFrontendToBackend(ref.graph, a)));
+
+  server.registerTool("visualize_graph", {
+    title: "Visualize graph slice",
+    description: "Return a Mermaid (default) or Graphviz DOT diagram for a slice of the graph: kind 'component-tree' (render hierarchy under a component) or 'fe-to-be' (frontend-to-backend flow). Paste the Mermaid block directly into chat to render it.",
+    inputSchema: {
+      name: z.string().describe("root component/route/endpoint for the slice"),
+      kind: z.enum(["component-tree", "fe-to-be"]).optional(),
+      format: z.enum(["mermaid", "dot"]).optional(),
+      max_nodes: z.number().int().min(3).max(200).optional(),
+      max_tokens: maxTokensParam,
+    },
+  }, async (a) => text(T.visualizeGraph(ref.graph, a)));
+
+  server.registerTool("search_symbols", {
+    title: "Search symbols",
+    description: "Fuzzy search any indexed node (components, routes, endpoints, handlers, files, packages) by name or path. Use instead of grep/find for 'where is X defined?'.",
+    inputSchema: {
+      query: z.string(),
+      types: z.array(z.enum(["package", "file", "component", "route", "endpoint-call", "api-route", "handler"])).optional(),
+      limit: z.number().int().min(1).max(50).optional(),
+      max_tokens: maxTokensParam,
+    },
+  }, async (a) => text(T.searchSymbols(ref.graph, a)));
+
+  server.registerTool("impact_of_change", {
+    title: "Impact of change (blast radius)",
+    description: "Given a component, handler, endpoint, or file path, list everything that depends on it (directly and transitively, up to depth N). Use before refactors and when debugging 'what breaks if I change this?'.",
+    inputSchema: { name: z.string().describe("node name or repo-relative file path"), depth: z.number().int().min(1).max(6).optional(), max_tokens: maxTokensParam },
+  }, async (a) => text(T.impactOfChange(ref.graph, a)));
+
+  server.registerTool("reindex", {
+    title: "Reindex repo",
+    description: "Refresh the graph. Incremental by default (only changed files reparsed); pass full:true to rebuild from scratch. Call after significant code edits.",
+    inputSchema: { full: z.boolean().optional() },
+  }, async (a) => text(T.reindex(ref, a)));
+
+  return server;
+}
+
+// ---------- stdio (Claude Code, Cursor, Codex CLI, local clients) ----------
+export async function startServer(repoRoot) {
+  const ref = loadOrIndex(repoRoot); // mutable ref so reindex can swap the instance
+  const server = buildServer(ref);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("[code-graph-mcp] ready (stdio)");
+  return server;
+}
+
+// ---------- Streamable HTTP (Claude custom connectors, MCP connector API) ----------
+// Stateless: a fresh McpServer+transport per request; the graph ref is shared
+// so the index is loaded once and reused across requests (spec R8.2).
+export async function startHttpServer(repoRoot, { port = 3333, host = "127.0.0.1", token = null } = {}) {
+  const ref = loadOrIndex(repoRoot);
+
+  const httpServer = http.createServer(async (req, res) => {
+    const url = new URL(req.url, `http://${req.headers.host ?? "localhost"}`);
+    const segs = url.pathname.split("/").filter(Boolean);
+    const isMcp = segs[0] === "mcp";
+    if (!isMcp) {
+      res.writeHead(404, { "content-type": "application/json" });
+      res.end(JSON.stringify({ error: "not found; MCP endpoint is /mcp" }));
+      return;
+    }
+    // auth (spec R8.3): Authorization: Bearer <token> OR /mcp/<token>
+    if (token) {
+      const header = (req.headers.authorization ?? "").replace(/^Bearer\s+/i, "");
+      const pathToken = segs[1] ?? "";
+      if (header !== token && pathToken !== token) {
+        res.writeHead(401, { "content-type": "application/json" });
+        res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32001, message: "unauthorized" }, id: null }));
+        return;
+      }
+    }
+    if (req.method === "GET" || req.method === "DELETE") {
+      // stateless mode: no SSE stream / session teardown to serve
+      res.writeHead(405, { "content-type": "application/json" });
+      res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32000, message: "stateless server: POST only" }, id: null }));
+      return;
+    }
+    try {
+      const chunks = [];
+      for await (const c of req) chunks.push(c);
+      const body = chunks.length ? JSON.parse(Buffer.concat(chunks).toString("utf8")) : undefined;
+      const server = buildServer(ref);
+      const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+      res.on("close", () => { transport.close(); server.close(); });
+      await server.connect(transport);
+      await transport.handleRequest(req, res, body);
+    } catch (e) {
+      if (!res.headersSent) {
+        res.writeHead(500, { "content-type": "application/json" });
+        res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32603, message: `internal error: ${e.message}` }, id: null }));
+      }
+    }
+  });
+
+  await new Promise((resolve) => httpServer.listen(port, host, resolve));
+  const shownPath = token ? `/mcp/<token>` : "/mcp";
+  console.error(`[code-graph-mcp] ready (streamable http) on http://${host}:${port}${shownPath}${token ? " (token required)" : " (no auth — keep this off the public internet)"}`);
+  return httpServer;
+}

package/src/tools.js

@@ -0,0 +1,357 @@
+// Tool implementations. Everything answers from the in-memory graph (spec
+// constraint), formats compact line-oriented text (R4.1), and enforces a
+// token budget with "…+N more" truncation (R4.2).
+
+
+import path from "node:path";
+import { shortenPaths } from "./graph.js";
+import { incrementalIndex, fullIndex, pathsMatch } from "./indexer.js";
+
+const CHARS_PER_TOKEN = 4;
+const DEFAULT_MAX_TOKENS = 2000;
+
+// Session stats (R4.4)
+export const stats = { calls: 0, charsReturned: 0, rawCharsAvoided: 0 };
+
+export function budget(lines, maxTokens = DEFAULT_MAX_TOKENS) {
+  const cap = maxTokens * CHARS_PER_TOKEN;
+  let used = 0;
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i];
+    if (used + l.length + 1 > cap) {
+      out.push(`…+${lines.length - i} more (refine query or raise max_tokens)`);
+      return out.join("\n");
+    }
+    out.push(l);
+    used += l.length + 1;
+  }
+  return out.join("\n");
+}
+
+function record(text, filesTouched, graph) {
+  stats.calls++;
+  stats.charsReturned += text.length;
+  // Estimate what an agent would have read instead: sizes captured at index
+  // time on file nodes — no filesystem I/O at query time (spec constraint).
+  let raw = 0;
+  for (const rel of new Set(filesTouched)) {
+    raw += graph.nodes.get(`file:${rel}`)?.extra?.bytes ?? 0;
+  }
+  stats.rawCharsAvoided += Math.max(0, raw - text.length);
+  return text;
+}
+
+function notFound(graph, name, types) {
+  const close = graph.fuzzy(name, 5, types);
+  if (!close.length) return `not found: "${name}" (no close matches in graph — try search_symbols or reindex)`;
+  const lines = [`not found: "${name}". closest matches:`];
+  for (const n of close) lines.push(`  ${n.type} ${n.name}  ${n.file ?? ""}`);
+  return lines.join("\n");
+}
+
+// resolve a user-supplied name to node(s); prefers exact, disambiguates duplicates (E4)
+function resolve(graph, name, types) {
+  let hits = graph.findByName(name).filter((n) => !types || types.includes(n.type));
+  if (!hits.length) hits = graph.fuzzy(name, 3, types).filter((n) => n.name?.toLowerCase() === name.toLowerCase());
+  return hits;
+}
+
+// ---------- repo_summary ----------
+export function repoSummary(graph, { detail = "compact", max_tokens = DEFAULT_MAX_TOKENS } = {}) {
+  const s = graph.stats();
+  const lines = [`repo: ${path.basename(graph.repoRoot)}  nodes:${s.nodes} edges:${s.edges}`];
+  lines.push(`counts: ${Object.entries(s.byType).map(([t, c]) => `${t}=${c}`).join(" ")}`);
+  const pkgs = [...graph.nodes.values()].filter((n) => n.type === "package");
+  lines.push(`packages (${pkgs.length}):`);
+  for (const p of pkgs) {
+    const deps = (p.extra?.deps ?? []).slice(0, detail === "full" ? 20 : 6).join(",");
+    lines.push(`  ${p.file === "." ? "(root)" : p.file}  ${p.name} [${p.extra?.kind}]  deps: ${deps || "-"}`);
+  }
+  const routes = [...graph.nodes.values()].filter((n) => n.type === "route");
+  if (routes.length) {
+    lines.push(`frontend routes (${routes.length}):`);
+    for (const r of routes) lines.push(`  ${r.name} -> ${r.extra?.component ?? "?"}`);
+  }
+  const api = [...graph.nodes.values()].filter((n) => n.type === "api-route");
+  if (api.length) {
+    lines.push(`backend routes (${api.length}):`);
+    for (const a of api) lines.push(`  ${a.name}  (${a.file})`);
+  }
+  if (stats.calls > 0) {
+    const saved = stats.rawCharsAvoided / CHARS_PER_TOKEN;
+    lines.push(`session savings: ${stats.calls} calls served, ~${Math.round(saved).toLocaleString()} tokens of raw file reads avoided`);
+  }
+  const text = budget(lines, max_tokens);
+  return record(text, [], graph);
+}
+
+// ---------- find_component_relations ----------
+export function findComponentRelations(graph, { name, detail = "compact", max_tokens = DEFAULT_MAX_TOKENS }) {
+  const hits = resolve(graph, name, ["component", "route"]);
+  if (!hits.length) return record(notFound(graph, name, ["component", "route"]), [], graph);
+  const lines = [];
+  const files = [];
+  for (const node of hits) {
+    files.push(node.file);
+    lines.push(`${node.type}: ${node.name}  (${node.file ?? "-"})`);
+    const fileId = node.file ? `file:${node.file}` : null;
+    const sections = [
+      ["renders", graph.neighbors(node.id, "out", ["renders"])],
+      ["rendered by", graph.neighbors(node.id, "in", ["renders"])],
+      ["hooks/stores used", graph.neighbors(node.id, "out", ["uses"])],
+      ["endpoints called", graph.neighbors(node.id, "out", ["calls"])],
+    ];
+    if (fileId) {
+      sections.push(["file imports", graph.neighbors(fileId, "out", ["imports"])]);
+      sections.push(["file imported by", graph.neighbors(fileId, "in", ["imports"])]);
+    }
+    for (const [label, items] of sections) {
+      if (!items.length) continue;
+      const uniq = dedupe(items.map(({ node: n }) => n));
+      lines.push(`  ${label}:`);
+      const shown = detail === "full" ? uniq : uniq.slice(0, 12);
+      for (const n of shown) {
+        lines.push(`    ${n.name}${n.file && n.type !== "file" ? `  (${n.file})` : n.type === "file" ? `  (${n.file})` : ""}`);
+        if (n.file) files.push(n.file);
+      }
+      if (shown.length < uniq.length) lines.push(`    …+${uniq.length - shown.length} more (detail:"full")`);
+    }
+    if (hits.length > 1) lines.push("");
+  }
+  if (hits.length > 1) lines.unshift(`note: ${hits.length} matches for "${name}" — listed all:`);
+  return record(budget(lines, max_tokens), files, graph);
+}
+
+// ---------- map_frontend_to_backend ----------
+export function mapFrontendToBackend(graph, { name, max_tokens = DEFAULT_MAX_TOKENS }) {
+  const lines = [];
+  const files = [];
+
+  // Case A: name is an endpoint path -> walk backwards to FE and forwards to handler
+  if (name.startsWith("/")) {
+    const target = name.toLowerCase();
+    const apiRoutes = [...graph.nodes.values()].filter((n) => n.type === "api-route" && pathsMatch(normalizeForQuery(target), n.extra.normPath));
+    const calls = [...graph.nodes.values()].filter((n) => n.type === "endpoint-call" && pathsMatch(normalizeForQuery(target), n.extra.normPath));
+    if (!apiRoutes.length && !calls.length) return record(notFound(graph, name, ["api-route", "endpoint-call"]), [], graph);
+    for (const ar of apiRoutes) lines.push(...chainFromApiRoute(graph, ar, files));
+    for (const c of calls) if (!graph.neighbors(c.id, "out", ["hits-endpoint"]).length) {
+      lines.push(`${callerLabel(graph, c)} -> ${c.name} -> (no backend match found)`);
+    }
+    return record(budget(dedupeLines(lines), max_tokens), files, graph);
+  }
+
+  // Case B: component or route name -> its calls -> backend
+  const hits = resolve(graph, name, ["component", "route"]);
+  if (!hits.length) return record(notFound(graph, name, ["component", "route"]), [], graph);
+  for (const node of hits) {
+    files.push(node.file);
+    const calls = collectCalls(graph, node);
+    if (!calls.length) { lines.push(`${node.name}: no HTTP calls found (checked component + rendered children)`); continue; }
+    for (const c of calls) {
+      const hitEdges = graph.neighbors(c.node.id, "out", ["hits-endpoint"]);
+      if (!hitEdges.length) {
+        lines.push(`${node.name}${c.via ? ` -> ${c.via}` : ""} -> ${c.node.name} -> (no backend match)`);
+        continue;
+      }
+      for (const { node: ar } of hitEdges) {
+        const handlers = graph.neighbors(ar.id, "out", ["handled-by"]);
+        const h = handlers[0]?.node;
+        files.push(ar.file); if (h) files.push(h.file);
+        lines.push(`${node.name}${c.via ? ` -> ${c.via}` : ""} -> ${c.node.name} -> ${ar.name} (${ar.file})${h ? ` -> ${handlerName(h)}` : ""}`);
+      }
+    }
+  }
+  return record(budget(dedupeLines(lines), max_tokens), files, graph);
+}
+
+function normalizeForQuery(p) {
+  return p.replace(/\{[^}]*\}/g, ":param").replace(/:[A-Za-z_]\w*/g, ":param");
+}
+function handlerName(h) {
+  const mod = h.file ? h.file.replace(/\.\w+$/, "").split("/").pop() : "";
+  return mod ? `${mod}.${h.name}` : h.name;
+}
+function callerLabel(graph, call) {
+  const owners = graph.neighbors(call.id, "in", ["calls"]).map((e) => e.node.name);
+  return owners[0] ?? call.file ?? "?";
+}
+function chainFromApiRoute(graph, ar, files) {
+  const lines = [];
+  files.push(ar.file);
+  const handlers = graph.neighbors(ar.id, "out", ["handled-by"]);
+  const h = handlers[0]?.node;
+  if (h) files.push(h.file);
+  const callers = graph.neighbors(ar.id, "in", ["hits-endpoint"]);
+  if (!callers.length) {
+    lines.push(`(no frontend caller found) -> ${ar.name} (${ar.file})${h ? ` -> ${handlerName(h)}` : ""}`);
+  }
+  for (const { node: call } of callers) {
+    files.push(call.file);
+    lines.push(`${callerLabel(graph, call)} -> ${call.name} -> ${ar.name} (${ar.file})${h ? ` -> ${handlerName(h)}` : ""}`);
+  }
+  return lines;
+}
+// calls made by the node itself, or by components it renders (1 level), so
+// route -> page component -> call chains resolve.
+function collectCalls(graph, node) {
+  const direct = graph.neighbors(node.id, "out", ["calls"]).map(({ node: n }) => ({ node: n, via: null }));
+  const rendered = graph.neighbors(node.id, "out", ["renders"]);
+  const viaChildren = [];
+  for (const { node: child } of rendered) {
+    for (const { node: c } of graph.neighbors(child.id, "out", ["calls"])) {
+      viaChildren.push({ node: c, via: child.name });
+    }
+  }
+  return dedupe([...direct, ...viaChildren].map((x) => x), (x) => x.node.id + (x.via ?? ""));
+}
+
+// ---------- visualize_graph ----------
+export function visualizeGraph(graph, { name, kind = "component-tree", format = "mermaid", max_nodes = 30, max_tokens = DEFAULT_MAX_TOKENS }) {
+  const hits = resolve(graph, name, ["component", "route", "api-route"]);
+  if (!hits.length) return record(notFound(graph, name, ["component", "route", "api-route"]), [], graph);
+  const root = hits[0];
+  const nodes = new Map([[root.id, root]]);
+  const edges = [];
+  if (kind === "fe-to-be") {
+    // route/component -> calls -> api-route -> handler
+    const frontier = [root];
+    for (const start of frontier) {
+      for (const c of collectCalls(graph, start)) {
+        addViz(nodes, edges, start, c.node, "calls", max_nodes);
+        for (const { node: ar } of graph.neighbors(c.node.id, "out", ["hits-endpoint"])) {
+          addViz(nodes, edges, c.node, ar, "hits", max_nodes);
+          for (const { node: h } of graph.neighbors(ar.id, "out", ["handled-by"])) {
+            addViz(nodes, edges, ar, h, "handled by", max_nodes);
+          }
+        }
+      }
+      for (const { node: child } of graph.neighbors(start.id, "out", ["renders"])) {
+        addViz(nodes, edges, start, child, "renders", max_nodes);
+      }
+    }
+  } else {
+    // component tree: BFS over renders
+    let frontier = [root];
+    while (frontier.length && nodes.size < max_nodes) {
+      const next = [];
+      for (const cur of frontier) {
+        for (const { node: child } of graph.neighbors(cur.id, "out", ["renders"])) {
+          if (nodes.size >= max_nodes) break;
+          const isNew = !nodes.has(child.id);
+          addViz(nodes, edges, cur, child, "", max_nodes);
+          if (isNew) next.push(child);
+        }
+      }
+      frontier = next;
+    }
+  }
+  const text = format === "dot" ? renderDot(nodes, edges) : renderMermaid(nodes, edges);
+  const capped = nodes.size >= max_nodes ? `${text}\n%% capped at ${max_nodes} nodes (raise max_nodes for more)` : text;
+  return record(budget(capped.split("\n"), max_tokens), [...nodes.values()].map((n) => n.file).filter(Boolean), graph);
+}
+
+function addViz(nodes, edges, from, to, label, cap) {
+  if (nodes.size >= cap && !nodes.has(to.id)) return;
+  nodes.set(from.id, from);
+  nodes.set(to.id, to);
+  edges.push({ from: from.id, to: to.id, label });
+}
+function vizId(id) { return "n" + Math.abs(hashCode(id)).toString(36); }
+function hashCode(s) { let h = 0; for (let i = 0; i < s.length; i++) { h = (h << 5) - h + s.charCodeAt(i); h |= 0; } return h; }
+function vizLabel(n) {
+  const t = { component: "", route: "route ", "api-route": "", "endpoint-call": "", handler: "fn " }[n.type] ?? "";
+  return `${t}${n.name}`.replace(/["\[\]{}|]/g, "");
+}
+function renderMermaid(nodes, edges) {
+  const lines = ["graph LR"];
+  const shape = (n) => {
+    const l = vizLabel(n);
+    if (n.type === "api-route") return `${vizId(n.id)}[/"${l}"/]`;
+    if (n.type === "handler") return `${vizId(n.id)}[["${l}"]]`;
+    if (n.type === "route") return `${vizId(n.id)}(("${l}"))`;
+    return `${vizId(n.id)}["${l}"]`;
+  };
+  for (const n of nodes.values()) lines.push(`  ${shape(n)}`);
+  const seen = new Set();
+  for (const e of edges) {
+    const key = `${e.from}>${e.to}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    lines.push(`  ${vizId(e.from)} ${e.label ? `-- ${e.label} -->` : "-->"} ${vizId(e.to)}`);
+  }
+  return lines.join("\n");
+}
+function renderDot(nodes, edges) {
+  const lines = ["digraph G {", "  rankdir=LR;"];
+  for (const n of nodes.values()) lines.push(`  ${vizId(n.id)} [label="${vizLabel(n)}"];`);
+  const seen = new Set();
+  for (const e of edges) {
+    const key = `${e.from}>${e.to}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    lines.push(`  ${vizId(e.from)} -> ${vizId(e.to)}${e.label ? ` [label="${e.label}"]` : ""};`);
+  }
+  lines.push("}");
+  return lines.join("\n");
+}
+
+// ---------- search_symbols ----------
+export function searchSymbols(graph, { query, types = null, limit = 10, max_tokens = DEFAULT_MAX_TOKENS }) {
+  const hits = graph.fuzzy(query, limit, types);
+  if (!hits.length) return record(`no matches for "${query}"`, [], graph);
+  const paths = hits.map((n) => n.file ?? "");
+  const { prefix, paths: short } = shortenPaths(paths);
+  const lines = prefix ? [`(paths relative to ${prefix})`] : [];
+  hits.forEach((n, i) => lines.push(`${n.type}  ${n.name}  ${short[i] || "-"}`));
+  return record(budget(lines, max_tokens), paths.filter(Boolean), graph);
+}
+
+// ---------- impact_of_change ----------
+export function impactOfChange(graph, { name, depth = 3, max_tokens = DEFAULT_MAX_TOKENS }) {
+  let hits = resolve(graph, name, null);
+  if (!hits.length && (name.includes("/") || name.includes("."))) {
+    const f = graph.nodes.get(`file:${name}`);
+    if (f) hits = [f];
+  }
+  if (!hits.length) return record(notFound(graph, name, null), [], graph);
+  const lines = [];
+  const files = [];
+  for (const node of hits) {
+    const deps = graph.dependents(node.id, depth);
+    // for files, also include dependents of nodes defined in the file
+    if (node.type === "file") {
+      for (const id of graph.byFile.get(node.file) ?? []) {
+        if (id === node.id) continue;
+        for (const d of graph.dependents(id, depth)) {
+          if (!deps.some((x) => x.node.id === d.node.id)) deps.push(d);
+        }
+      }
+    }
+    lines.push(`${node.type}: ${node.name} (${node.file ?? "-"}) — ${deps.length} dependent(s) within depth ${depth}:`);
+    deps.sort((a, b) => a.depth - b.depth);
+    for (const { node: n, depth: d } of deps) {
+      lines.push(`  [d${d}] ${n.type}  ${n.name}  ${n.file ?? ""}`);
+      if (n.file) files.push(n.file);
+    }
+    if (!deps.length) lines.push("  (nothing depends on this — safe to change in isolation)");
+  }
+  return record(budget(lines, max_tokens), files, graph);
+}
+
+// ---------- reindex ----------
+export function reindex(graphRef, { full = false } = {}) {
+  const root = graphRef.graph.repoRoot;
+  const res = full ? fullIndex(root) : incrementalIndex(root, graphRef.graph);
+  graphRef.graph = res.graph;
+  const s = res.graph.stats();
+  const warn = res.warnings.length ? ` warnings:${res.warnings.length}` : "";
+  const text = `reindex ${res.mode}: +${res.added ?? "?"} changed:${res.changed} removed:${res.removed} in ${res.ms}ms — graph now ${s.nodes} nodes / ${s.edges} edges${warn}`;
+  return record(text, [], res.graph);
+}
+
+function dedupe(arr, keyFn = (x) => x.id ?? x) {
+  const seen = new Set();
+  return arr.filter((x) => { const k = keyFn(x); if (seen.has(k)) return false; seen.add(k); return true; });
+}
+function dedupeLines(lines) { return [...new Set(lines)]; }