@nanonets/graft 0.4.3 → 0.4.5

package/dist/graph/traverse-cli.js

@@ -0,0 +1,112 @@
+/**
+ * CLI wiring for `graft callers` / `callees` / `impact`.
+ *
+ * The three commands are one implementation with a direction flag: they all
+ * resolve a symbol via `resolveSymbol`, walk edges via `callersOf` /
+ * `calleesOf` / `impactOf`, and share the same resolve-or-die flow, human
+ * formatter, and --json shape. Kept out of cli.ts so that file stays thin
+ * (argument wiring only) and this logic stays unit-testable without shelling
+ * out to the CLI on every case.
+ */
+import { resolve } from "node:path";
+import { contextDirFor } from "../context/node-file.js";
+import { loadGraphCached } from "./load.js";
+import { resolveSymbol, callersOf, calleesOf, impactOf } from "./traverse.js";
+const ARROW = { callers: "←", impact: "←", callees: "→" };
+const DEFAULT_IMPACT_DEPTH = 2;
+function edgesFor(kind, graph, node, depth) {
+    if (kind === "callers")
+        return callersOf(graph, node);
+    if (kind === "callees")
+        return calleesOf(graph, node);
+    return impactOf(graph, node, depth);
+}
+/** Exported so the MCP tools (`graft_callers`/`graft_callees`/`graft_blast_radius`
+ * in `src/mcp/tools.ts`) can render the same human report format as the CLI,
+ * rather than re-implementing it — both surfaces walk the same edges via the
+ * same `resolveSymbol`/`callersOf`/`calleesOf`/`impactOf` core. */
+export function headerOf(n) {
+    return `${n.name} · ${n.kind} · ${n.path}:${n.span}`;
+}
+export function hitLine(kind, hit) {
+    const arrow = ARROW[kind];
+    const depthTag = kind === "impact" ? ` [depth ${hit.depth}]` : "";
+    const label = hit.node ? `${hit.node.name} (${hit.node.path}:${hit.node.span})` : `${hit.id} (unresolved import)`;
+    return `  ${hit.relation} ${arrow} ${label}${depthTag}`;
+}
+/** Loud, actionable empty-result note — never a bare empty list. `callers` and
+ * `impact` both walk incoming edges, so they share the "callers" wording. */
+export function looseNoteFor(kind, name) {
+    const label = kind === "callees" ? "callees" : "callers";
+    const direction = kind === "callees" ? "outgoing" : "incoming";
+    return `  no indexed ${label} — the graph has no ${direction} call/reference edges for this symbol; try grep -rn "${name}"`;
+}
+function symbolJson(n) {
+    return { id: n.id, name: n.name, kind: n.kind, path: n.path, span: n.span };
+}
+function hitJson(hit) {
+    const out = { id: hit.id, relation: hit.relation, depth: hit.depth };
+    if (hit.node) {
+        out.name = hit.node.name;
+        out.kind = hit.node.kind;
+        out.path = hit.node.path;
+        out.span = hit.node.span;
+    }
+    return out;
+}
+/**
+ * Resolve `query` in the graph at `dir` (respecting `--dir`/`--in`), walk
+ * edges per `kind`, and print either the human report or `--json`. Exits the
+ * process (code 1) when there's no graph at all or the symbol is unknown —
+ * both are caller-facing mistakes, not recoverable states.
+ */
+export function runTraverseCommand(kind, query, dir, opts) {
+    const root = resolve(dir);
+    const contextDir = contextDirFor(root, opts.globalDir);
+    const graph = loadGraphCached(contextDir);
+    if (!graph) {
+        console.error(`✗ no graph found at ${contextDir} — run \`graft build\` first`);
+        process.exit(1);
+    }
+    const matches = resolveSymbol(graph, query, opts.in ? { in: opts.in } : {});
+    if (matches.length === 0) {
+        console.error(`✗ no symbol "${query}" in the graph — check spelling or run graft build`);
+        process.exit(1);
+    }
+    let depth = DEFAULT_IMPACT_DEPTH;
+    if (kind === "impact" && opts.depth !== undefined) {
+        const d = Number(opts.depth);
+        if (!Number.isFinite(d) || d < 1) {
+            console.error(`✗ --depth must be a positive number, got "${opts.depth}"`);
+            process.exit(1);
+        }
+        depth = d;
+    }
+    const results = matches.map((symbol) => ({ symbol, hits: edgesFor(kind, graph, symbol, depth) }));
+    if (opts.json) {
+        const payload = {
+            query,
+            matches: results.map((r) => {
+                const m = { symbol: symbolJson(r.symbol), hits: r.hits.map(hitJson) };
+                if (r.hits.length === 0) {
+                    m.note = looseNoteFor(kind, r.symbol.name);
+                }
+                return m;
+            }),
+        };
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+    }
+    const lines = [];
+    for (const { symbol, hits } of results) {
+        lines.push(headerOf(symbol));
+        if (hits.length === 0)
+            lines.push(looseNoteFor(kind, symbol.name));
+        else
+            for (const h of hits)
+                lines.push(hitLine(kind, h));
+        lines.push("");
+    }
+    process.stdout.write(lines.join("\n").replace(/\n+$/, "\n"));
+}
+//# sourceMappingURL=traverse-cli.js.map

package/dist/graph/traverse-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"traverse-cli.js","sourceRoot":"","sources":["../../src/graph/traverse-cli.ts"],"names":[],"mappings":"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"}

package/dist/graph/traverse.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Pure graph-traversal core shared by `graft callers` / `callees` / `impact`,
+ * their MCP equivalents, and `ask`'s structural intent path.
+ *
+ * Centralizes the symbol-resolution contract (bare name, qualified id-suffix,
+ * last-segment fallback, `--in` narrowing) so all three surfaces agree on what
+ * a query like `Cache.get` or `hashstructure.Hash` means, and the depth-1
+ * (callers/callees) and BFS (impact) edge walks over the wiring graph.
+ *
+ * No I/O here: callers pass in an already-loaded `GraphV1` (via
+ * `loadGraphCached`), which keeps this module trivially unit-testable against
+ * hand-built fixture graphs.
+ */
+import type { GraphV1, NodeV1, Relation } from "./types.js";
+/** A resolved symbol-search hit. Reserved for future disambiguation metadata
+ * (e.g. why a query matched); today it wraps the node 1:1. */
+export interface SymbolMatch {
+    node: NodeV1;
+}
+export interface ResolveSymbolOptions {
+    /** Narrow candidates to nodes whose `path` contains this substring. */
+    in?: string;
+}
+/**
+ * Resolve a query string to every matching node in the graph.
+ *
+ * Matching, in order:
+ *  1. Non-file nodes whose `name` equals the query case-insensitively, OR
+ *     whose `id` ends with `#<query>` or `.<query>` case-insensitively — this
+ *     is what makes a qualified name like `Cache.get` resolve against an id
+ *     like `src/cache.ts#Cache.get`.
+ *  2. If that yields nothing and the query contains a `.`, retry with just
+ *     the last dot-segment as a bare name (`hashstructure.Hash` → `Hash`) —
+ *     covers package-qualified names (e.g. Go) whose id never contains the
+ *     package prefix.
+ *  3. If *that* still yields nothing and the query looks like a filename
+ *     (contains `.`, no `#`), fall back to `kind: 'file'` nodes matched by
+ *     name or path.
+ *
+ * `opts.in` then filters whichever candidate set was produced, by path
+ * substring. Multiple matches are not an error — every match is returned.
+ */
+export declare function resolveSymbol(graph: GraphV1, query: string, opts?: ResolveSymbolOptions): NodeV1[];
+/** One traversed edge. `node` is null when the edge's other endpoint isn't a
+ * real node in the graph (e.g. an unresolved import module string) — such
+ * hits are kept, labeled by the raw id, rather than dropped. */
+export interface EdgeHit {
+    node: NodeV1 | null;
+    id: string;
+    relation: Relation;
+    depth: number;
+}
+/** Depth-1: nodes with a walk-relation edge whose target is `symbol`. */
+export declare function callersOf(graph: GraphV1, symbol: NodeV1): EdgeHit[];
+/** Depth-1: walk-relation edges whose source is `symbol`. */
+export declare function calleesOf(graph: GraphV1, symbol: NodeV1): EdgeHit[];
+/**
+ * BFS over INCOMING walk-relation edges from `symbol`, up to `maxDepth` hops
+ * — "who breaks if this changes". Each reached node is deduped by id and
+ * reported once, at the depth it was first reached (a diamond-shaped
+ * dependency graph counts its convergence node exactly once).
+ */
+export declare function impactOf(graph: GraphV1, symbol: NodeV1, maxDepth?: number): EdgeHit[];
+/**
+ * BFS over INCOMING walk-relation edges from *multiple* seed nodes at once —
+ * the multi-seed generalization of {@link impactOf} (`impactOf(g, n, d)` is
+ * exactly `impactOfMany(g, [n], d)`). Used when one logical unit spans several
+ * graph node ids — e.g. a file plus every symbol defined in it, since a
+ * `calls`/`references`/etc. edge from another file always targets the SYMBOL
+ * id, never the FILE id, so walking the file node alone misses dependents that
+ * call into it rather than merely importing it.
+ *
+ * Every seed is pre-marked visited (so a seed can never appear as its own
+ * hit, and an edge between two seeds is never reported), then the walk
+ * proceeds exactly like `impactOf`'s: each reached node deduped by id and
+ * reported once, at the depth it was first reached from *any* seed.
+ */
+export declare function impactOfMany(graph: GraphV1, seeds: NodeV1[], maxDepth?: number): EdgeHit[];
+/**
+ * `impactOf`, generalized for a `kind: 'file'` seed: aggregates the BFS over
+ * the file node AND every symbol node defined in that file (via
+ * {@link impactOfMany} — dedup by id, min depth, seeds excluded). Fixes a file
+ * query silently dropping dependents that `calls`/`references`/etc. into a
+ * symbol the file defines, rather than merely `imports`-ing the file itself —
+ * see this module's header and `impactOfMany`'s doc for why. Symbol-kind
+ * queries keep using plain `impactOf`; this is only for file-kind matches.
+ */
+export declare function impactOfFile(graph: GraphV1, fileNode: NodeV1, maxDepth?: number): EdgeHit[];
+//# sourceMappingURL=traverse.d.ts.map

package/dist/graph/traverse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traverse.d.ts","sourceRoot":"","sources":["../../src/graph/traverse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAU,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEpE;8DAC8D;AAC9D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,oBAAoB;IACnC,uEAAuE;IACvE,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAeD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,oBAAyB,GAAG,MAAM,EAAE,CAyBtG;AAaD;;gEAEgE;AAChE,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,yEAAyE;AACzE,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,EAAE,CAQnE;AAED,6DAA6D;AAC7D,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,EAAE,CAQnE;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,OAAO,EAAE,CAEhF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,QAAQ,SAAI,GAAG,OAAO,EAAE,CA+BrF;AAQD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,OAAO,EAAE,CAEtF"}

package/dist/graph/traverse.js

@@ -0,0 +1,158 @@
+/**
+ * Edges that carry meaning-flow for a walk. `contains` is deliberately
+ * excluded — see graphrank.ts's identical WALK_RELATIONS for why (a file
+ * "contains" every symbol in it, which would make the file a false hub).
+ */
+const WALK_RELATIONS = new Set([
+    "calls",
+    "references",
+    "imports",
+    "implements",
+    "extends",
+]);
+/**
+ * Resolve a query string to every matching node in the graph.
+ *
+ * Matching, in order:
+ *  1. Non-file nodes whose `name` equals the query case-insensitively, OR
+ *     whose `id` ends with `#<query>` or `.<query>` case-insensitively — this
+ *     is what makes a qualified name like `Cache.get` resolve against an id
+ *     like `src/cache.ts#Cache.get`.
+ *  2. If that yields nothing and the query contains a `.`, retry with just
+ *     the last dot-segment as a bare name (`hashstructure.Hash` → `Hash`) —
+ *     covers package-qualified names (e.g. Go) whose id never contains the
+ *     package prefix.
+ *  3. If *that* still yields nothing and the query looks like a filename
+ *     (contains `.`, no `#`), fall back to `kind: 'file'` nodes matched by
+ *     name or path.
+ *
+ * `opts.in` then filters whichever candidate set was produced, by path
+ * substring. Multiple matches are not an error — every match is returned.
+ */
+export function resolveSymbol(graph, query, opts = {}) {
+    const lowerQuery = query.toLowerCase();
+    const looksLikeFilename = query.includes(".") && !query.includes("#");
+    let matches = symbolMatches(graph.nodes, lowerQuery);
+    if (matches.length === 0 && query.includes(".")) {
+        const lastSegment = query.slice(query.lastIndexOf(".") + 1).toLowerCase();
+        if (lastSegment) {
+            matches = graph.nodes.filter((n) => n.kind !== "file" && n.name.toLowerCase() === lastSegment);
+        }
+    }
+    if (matches.length === 0 && looksLikeFilename) {
+        matches = graph.nodes.filter((n) => n.kind === "file" &&
+            (n.name.toLowerCase() === lowerQuery ||
+                n.path.toLowerCase() === lowerQuery ||
+                n.path.toLowerCase().endsWith("/" + lowerQuery)));
+    }
+    if (opts.in)
+        matches = matches.filter((n) => n.path.includes(opts.in));
+    return matches;
+}
+function symbolMatches(nodes, lowerQuery) {
+    const suffixHash = "#" + lowerQuery;
+    const suffixDot = "." + lowerQuery;
+    return nodes.filter((n) => {
+        if (n.kind === "file")
+            return false;
+        if (n.name.toLowerCase() === lowerQuery)
+            return true;
+        const lowerId = n.id.toLowerCase();
+        return lowerId.endsWith(suffixHash) || lowerId.endsWith(suffixDot);
+    });
+}
+/** Depth-1: nodes with a walk-relation edge whose target is `symbol`. */
+export function callersOf(graph, symbol) {
+    const byId = new Map(graph.nodes.map((n) => [n.id, n]));
+    const hits = [];
+    for (const e of graph.edges) {
+        if (!WALK_RELATIONS.has(e.relation) || e.target !== symbol.id)
+            continue;
+        hits.push({ node: byId.get(e.source) ?? null, id: e.source, relation: e.relation, depth: 1 });
+    }
+    return hits;
+}
+/** Depth-1: walk-relation edges whose source is `symbol`. */
+export function calleesOf(graph, symbol) {
+    const byId = new Map(graph.nodes.map((n) => [n.id, n]));
+    const hits = [];
+    for (const e of graph.edges) {
+        if (!WALK_RELATIONS.has(e.relation) || e.source !== symbol.id)
+            continue;
+        hits.push({ node: byId.get(e.target) ?? null, id: e.target, relation: e.relation, depth: 1 });
+    }
+    return hits;
+}
+/**
+ * BFS over INCOMING walk-relation edges from `symbol`, up to `maxDepth` hops
+ * — "who breaks if this changes". Each reached node is deduped by id and
+ * reported once, at the depth it was first reached (a diamond-shaped
+ * dependency graph counts its convergence node exactly once).
+ */
+export function impactOf(graph, symbol, maxDepth = 2) {
+    return impactOfMany(graph, [symbol], maxDepth);
+}
+/**
+ * BFS over INCOMING walk-relation edges from *multiple* seed nodes at once —
+ * the multi-seed generalization of {@link impactOf} (`impactOf(g, n, d)` is
+ * exactly `impactOfMany(g, [n], d)`). Used when one logical unit spans several
+ * graph node ids — e.g. a file plus every symbol defined in it, since a
+ * `calls`/`references`/etc. edge from another file always targets the SYMBOL
+ * id, never the FILE id, so walking the file node alone misses dependents that
+ * call into it rather than merely importing it.
+ *
+ * Every seed is pre-marked visited (so a seed can never appear as its own
+ * hit, and an edge between two seeds is never reported), then the walk
+ * proceeds exactly like `impactOf`'s: each reached node deduped by id and
+ * reported once, at the depth it was first reached from *any* seed.
+ */
+export function impactOfMany(graph, seeds, maxDepth = 2) {
+    const byId = new Map(graph.nodes.map((n) => [n.id, n]));
+    // target id → incoming {source, relation} pairs, restricted to walk relations.
+    const incoming = new Map();
+    for (const e of graph.edges) {
+        if (!WALK_RELATIONS.has(e.relation))
+            continue;
+        const arr = incoming.get(e.target);
+        const entry = { source: e.source, relation: e.relation };
+        if (arr)
+            arr.push(entry);
+        else
+            incoming.set(e.target, [entry]);
+    }
+    const visited = new Set(seeds.map((s) => s.id));
+    const hits = [];
+    let frontier = [...visited];
+    for (let depth = 1; depth <= maxDepth && frontier.length > 0; depth++) {
+        const next = [];
+        for (const current of frontier) {
+            for (const { source, relation } of incoming.get(current) ?? []) {
+                if (visited.has(source))
+                    continue;
+                visited.add(source);
+                hits.push({ node: byId.get(source) ?? null, id: source, relation, depth });
+                next.push(source);
+            }
+        }
+        frontier = next;
+    }
+    return hits;
+}
+/** Every non-file node whose `path` equals `fileNode.path` — the symbols
+ * defined in that file. */
+function symbolsInFile(graph, fileNode) {
+    return graph.nodes.filter((n) => n.kind !== "file" && n.path === fileNode.path);
+}
+/**
+ * `impactOf`, generalized for a `kind: 'file'` seed: aggregates the BFS over
+ * the file node AND every symbol node defined in that file (via
+ * {@link impactOfMany} — dedup by id, min depth, seeds excluded). Fixes a file
+ * query silently dropping dependents that `calls`/`references`/etc. into a
+ * symbol the file defines, rather than merely `imports`-ing the file itself —
+ * see this module's header and `impactOfMany`'s doc for why. Symbol-kind
+ * queries keep using plain `impactOf`; this is only for file-kind matches.
+ */
+export function impactOfFile(graph, fileNode, maxDepth = 2) {
+    return impactOfMany(graph, [fileNode, ...symbolsInFile(graph, fileNode)], maxDepth);
+}
+//# sourceMappingURL=traverse.js.map

package/dist/graph/traverse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"traverse.js","sourceRoot":"","sources":["../../src/graph/traverse.ts"],"names":[],"mappings":"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"}

package/dist/graph/write.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/graph/write.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAU,OAAO,EAAE,MAAM,YAAY,CAAC;AAElD,mFAAmF;AACnF,eAAO,MAAM,SAAS,WAAW,CAAC;AAClC,eAAO,MAAM,UAAU,gBAAgB,CAAC;AAExC,uFAAuF;AACvF,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAMtD;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAUjE"}
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/graph/write.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAU,OAAO,EAAU,MAAM,YAAY,CAAC;AAE1D,mFAAmF;AACnF,eAAO,MAAM,SAAS,WAAW,CAAC;AAClC,eAAO,MAAM,UAAU,gBAAgB,CAAC;AAExC,uFAAuF;AACvF,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAMtD;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAUjE"}

package/dist/graph/write.js

@@ -32,7 +32,7 @@ export function readGraph(path) {
 export function writeGraph(graph, outDir) {
     const sorted = {
         ...graph,
-        nodes: [...graph.nodes].sort((a, b) => a.id.localeCompare(b.id)),
+        nodes: [...graph.nodes].sort((a, b) => a.id.localeCompare(b.id)).map(stripBodyText),
         edges: [...graph.edges].sort(edgeOrder),
     };
     const path = wiringPath(outDir);
@@ -40,6 +40,21 @@ export function writeGraph(graph, outDir) {
     writeFileSync(path, JSON.stringify(sorted, null, 2) + "\n");
     return path;
 }
+/**
+ * Drop `body_text` from the SERIALIZED copy of a node — it is ~65% of
+ * wiring.json's bytes on a large graph, and every byte of it is already
+ * duplicated in the `ask` sidecar (`.cache/ask-index.json`), tokenized, which
+ * is the only place anything reads it from. Callers must pass this the
+ * in-memory graph BEFORE this stripped copy is produced (see `build.ts`:
+ * `writeAskIndex` runs on the original `graph` object, never on a re-read of
+ * this slimmed file) — this function never mutates the input node.
+ */
+function stripBodyText(node) {
+    if (node.body_text === undefined)
+        return node;
+    const { body_text: _body_text, ...rest } = node;
+    return rest;
+}
 function edgeOrder(a, b) {
     return (a.source.localeCompare(b.source) ||
         a.relation.localeCompare(b.relation) ||

package/dist/graph/write.js.map

@@ -1 +1 @@
-{"version":3,"file":"write.js","sourceRoot":"","sources":["../../src/graph/write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAG1C,mFAAmF;AACnF,MAAM,CAAC,MAAM,SAAS,GAAG,QAAQ,CAAC;AAClC,MAAM,CAAC,MAAM,UAAU,GAAG,aAAa,CAAC;AAExC,uFAAuF;AACvF,MAAM,UAAU,UAAU,CAAC,MAAc;IACvC,OAAO,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;AAC7C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAY,CAAC;IAC3D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAc,EAAE,MAAc;IACvD,MAAM,MAAM,GAAY;QACtB,GAAG,KAAK;QACR,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAChE,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC;KACxC,CAAC;IACF,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IAChC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAC5D,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,SAAS,CAAC,CAAS,EAAE,CAAS;IACrC,OAAO,CACL,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC;QAChC,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC;QACpC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CACjC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"write.js","sourceRoot":"","sources":["../../src/graph/write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAG1C,mFAAmF;AACnF,MAAM,CAAC,MAAM,SAAS,GAAG,QAAQ,CAAC;AAClC,MAAM,CAAC,MAAM,UAAU,GAAG,aAAa,CAAC;AAExC,uFAAuF;AACvF,MAAM,UAAU,UAAU,CAAC,MAAc;IACvC,OAAO,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;AAC7C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAY,CAAC;IAC3D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAc,EAAE,MAAc;IACvD,MAAM,MAAM,GAAY;QACtB,GAAG,KAAK;QACR,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC;QACnF,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC;KACxC,CAAC;IACF,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IAChC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAC5D,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,aAAa,CAAC,IAAY;IACjC,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC9C,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IAChD,OAAO,IAAc,CAAC;AACxB,CAAC;AAED,SAAS,SAAS,CAAC,CAAS,EAAE,CAAS;IACrC,OAAO,CACL,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC;QAChC,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC;QACpC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CACjC,CAAC;AACJ,CAAC"}

package/dist/hosts/instructions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../../src/hosts/instructions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,wBAAgB,eAAe,IAAI,MAAM,CAmBxC;AAED,wBAAgB,UAAU,IAAI,MAAM,CAOnC;AAED,wBAAgB,YAAY,IAAI,MAAM,CAMrC;AAED,wBAAgB,YAAY,IAAI,MAAM,CAGrC"}
+{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../../src/hosts/instructions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,wBAAgB,eAAe,IAAI,MAAM,CA6BxC;AAED,wBAAgB,UAAU,IAAI,MAAM,CAOnC;AAED,wBAAgB,YAAY,IAAI,MAAM,CAMrC;AAED,wBAAgB,YAAY,IAAI,MAAM,CAGrC"}

package/dist/hosts/instructions.js

@@ -10,14 +10,24 @@ system and carry exact file:line spans, kept in sync with the code through git.
 
 For ANY task here — understanding how something works, finding where code lives,
 or scoping a change — get context from the graph before grepping or opening
-source files:
+source files. Re-ask freely (it's cheap) and reuse literal identifiers you
+already have (symbol, error string, file name) as the query.
 
 - Run \`graft ask "<your question>" --source\` → ranked nodes with the relevant
-  code spans inlined. The node usually IS the answer; stop there.
+  code spans inlined. Match the tool to the task shape: for understanding or
+  editing, the top node IS the answer — cite its \`covers:\` file:line spans and
+  edit straight from \`--source\`. For exhaustive tasks ("every occurrence /
+  every caller of this pattern"), ranked results are top-N, not complete — use
+  graft to orient, then enumerate with grep over the source and verify each hit.
+- \`graft callers/callees <symbol>\` and \`graft impact <symbol> [-d N]\` give
+  precomputed, exact edges — who calls/is called by a symbol, and the full
+  blast radius — for structural questions, skip ranking and use these directly.
 - Or browse: \`graft/INDEX.md\` lists every node; follow the links.
 
-Only open source files when a node genuinely lacks a needed detail, and then at
-the exact file:line the node points to — never re-read whole files.
+If a returned span is truncated ("+N more lines"), open the file at that exact
+range before finalizing. Only open source files when a node genuinely lacks a
+needed detail, and then at the exact file:line the node points to — never
+re-read whole files.
 
 After big code changes, refresh the graph with \`graft build\` (deterministic,
 no API key, $0).`;

package/dist/hosts/instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../src/hosts/instructions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,UAAU,eAAe;IAC7B,OAAO;;;;;;;;;;;;;;;;;iBAiBQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,OAAO;;;;EAIP,eAAe,EAAE;CAClB,CAAC;AACF,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,OAAO;;;EAGP,eAAe,EAAE;CAClB,CAAC;AACF,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,OAAO,GAAG,eAAe,EAAE;CAC5B,CAAC;AACF,CAAC"}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../src/hosts/instructions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,UAAU,eAAe;IAC7B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2BQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,OAAO;;;;EAIP,eAAe,EAAE;CAClB,CAAC;AACF,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,OAAO;;;EAGP,eAAe,EAAE;CAClB,CAAC;AACF,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,OAAO,GAAG,eAAe,EAAE;CAC5B,CAAC;AACF,CAAC"}

package/dist/mcp/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,KAAK,EAAE,OAAO,EA4B1B,CAAC;AAEF,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAiCpC"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAWD,eAAO,MAAM,KAAK,EAAE,OAAO,EAyD1B,CAAC;AAiBF,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CA8DpC"}

package/dist/mcp/tools.js

@@ -1,14 +1,21 @@
 /**
- * The three MCP tools, as pure functions over the existing engine.
+ * The MCP tools, as pure functions over the existing engine.
  * `callTool` never throws — hosts get soft errors as isError content.
  */
 import { Graft } from '../engine.js';
 import { formatAsk } from '../ask/ask.js';
 import { formatCheckReport } from '../context/check.js';
 import { formatGraphCheckReport } from '../graph/check.js';
-import { formatBlastRadius } from '../claude/format.js';
-import { readGraph, wiringPath } from '../graph/write.js';
+import { loadGraphCached } from '../graph/load.js';
 import { contextDirFor } from '../context/node-file.js';
+import { resolveSymbol, callersOf, calleesOf, impactOf, impactOfFile } from '../graph/traverse.js';
+import { headerOf, hitLine, looseNoteFor } from '../graph/traverse-cli.js';
+/** Default BFS depth for `graft_blast_radius`, same default as `graft impact`. */
+const DEFAULT_BLAST_DEPTH = 2;
+const NO_GRAPH = 'no graph found — run `graft build` first';
+function unknownSymbolText(query) {
+    return `no symbol "${query}" in the graph — check spelling or run \`graft build\``;
+}
 export const TOOLS = [
     {
         name: 'graft_ask',
@@ -29,14 +36,59 @@ export const TOOLS = [
     },
     {
         name: 'graft_blast_radius',
-        description: 'List what depends on a file — who breaks if it changes.',
+        description: 'BFS over incoming call/reference/import/implements/extends edges from a file or symbol — who breaks if it changes ($0, no LLM).',
         inputSchema: {
             type: 'object',
-            properties: { file: { type: 'string', description: 'repo-relative path, e.g. src/cache.ts' } },
+            properties: {
+                file: { type: 'string', description: 'repo-relative file path, or a symbol name (bare, qualified, or package-qualified)' },
+                symbol: { type: 'string', description: 'alternative to `file` — a symbol name (bare, qualified, or package-qualified)' },
+                depth: { type: 'number', description: 'max BFS depth (default 2)' },
+            },
             required: ['file'],
         },
     },
+    {
+        name: 'graft_callers',
+        description: 'Who calls/references/imports/implements/extends a symbol (depth 1, $0, no LLM).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                symbol: { type: 'string', description: 'bare name, qualified (Class.method), or package-qualified (pkg.Fn)' },
+                in: { type: 'string', description: 'narrow matches to nodes whose path contains this substring' },
+            },
+            required: ['symbol'],
+        },
+    },
+    {
+        name: 'graft_callees',
+        description: 'What a symbol calls/references/imports/implements/extends (depth 1, $0, no LLM).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                symbol: { type: 'string', description: 'bare name, qualified (Class.method), or package-qualified (pkg.Fn)' },
+                in: { type: 'string', description: 'narrow matches to nodes whose path contains this substring' },
+            },
+            required: ['symbol'],
+        },
+    },
 ];
+/** Render every resolved match's header + edge report (or the loud zero-edge
+ * note), one block per match, joined with a blank line — the same grouping
+ * `graft callers`/`callees`/`impact` use for multi-match symbols. */
+function renderMatches(kind, matches, hitsFor) {
+    return matches
+        .map((m) => {
+        const hits = hitsFor(m);
+        const lines = [headerOf(m)];
+        if (hits.length === 0)
+            lines.push(looseNoteFor(kind, m.name));
+        else
+            for (const h of hits)
+                lines.push(hitLine(kind, h));
+        return lines.join('\n');
+    })
+        .join('\n\n');
+}
 export function callTool(root, name, args) {
     try {
         switch (name) {
@@ -59,14 +111,44 @@ export function callTool(root, name, args) {
                 return { text: parts.join('\n\n'), isError: false };
             }
             case 'graft_blast_radius': {
-                const file = String(args.file ?? '');
-                if (!file)
-                    return { text: 'graft_blast_radius requires a file', isError: true };
-                const w = readGraph(wiringPath(contextDirFor(root)));
+                const query = String(args.symbol ?? args.file ?? '');
+                if (!query)
+                    return { text: 'graft_blast_radius requires a file or symbol', isError: true };
+                const w = loadGraphCached(contextDirFor(root));
+                if (!w)
+                    return { text: NO_GRAPH, isError: true };
+                const matches = resolveSymbol(w, query);
+                if (matches.length === 0)
+                    return { text: unknownSymbolText(query), isError: true };
+                const depth = typeof args.depth === 'number' && Number.isFinite(args.depth) && args.depth >= 1
+                    ? args.depth
+                    : DEFAULT_BLAST_DEPTH;
+                // impactOf's BFS is over incoming edges — same wording family as "callers".
+                // A file-kind match must aggregate impact over the file node AND every
+                // symbol it defines: a `calls`/`references`/etc. edge into a function
+                // defined in the file targets the SYMBOL id, never the FILE id, so
+                // walking the file node alone silently drops dependents that call
+                // into it rather than merely importing it. Symbol-kind matches keep
+                // the plain single-seed walk.
+                const text = renderMatches('impact', matches, (m) => m.kind === 'file' ? impactOfFile(w, m, depth) : impactOf(w, m, depth));
+                return { text, isError: false };
+            }
+            case 'graft_callers':
+            case 'graft_callees': {
+                const symbol = String(args.symbol ?? '');
+                if (!symbol)
+                    return { text: `${name} requires a symbol`, isError: true };
+                const w = loadGraphCached(contextDirFor(root));
                 if (!w)
-                    return { text: 'no graph found — run `graft build` first', isError: true };
-                const br = formatBlastRadius(w, file);
-                return { text: br ?? `no known dependents of ${file}`, isError: false };
+                    return { text: NO_GRAPH, isError: true };
+                const inOpt = typeof args.in === 'string' && args.in ? { in: args.in } : {};
+                const matches = resolveSymbol(w, symbol, inOpt);
+                if (matches.length === 0)
+                    return { text: unknownSymbolText(symbol), isError: true };
+                const kind = name === 'graft_callers' ? 'callers' : 'callees';
+                const walk = kind === 'callers' ? callersOf : calleesOf;
+                const text = renderMatches(kind, matches, (m) => walk(w, m));
+                return { text, isError: false };
             }
             default:
                 return { text: `unknown tool: ${name}`, isError: true };