trail-code 0.0.0-stage → 0.28.0-semantic.3

package/dist/graph/traverse-cli.js

@@ -0,0 +1,189 @@
+/**
+ * CLI wiring for `graft callers` and its `--direction` / `--depth` flags.
+ *
+ * One command, one implementation: resolve a symbol via `resolveSymbol`, walk
+ * edges via `edgeWalk` (incoming or outgoing, depth 1 or a BFS), 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.
+ *
+ * `--direction out` subsumes the old `graft callees`; `--depth N` subsumes the
+ * old `graft impact`. Exported formatters are reused by the MCP `graft_trace_calls`
+ * tool (`src/mcp/tools.ts`), so both surfaces render identical reports.
+ */
+import { resolve } from "node:path";
+import { fileReader, referenceLine, wordRe } from "../blast/evidence.js";
+import { contextDirFor } from "../context/node-file.js";
+import { withSavings, savingsFor } from "../context/savings.js";
+import { loadGraphCached } from "./load.js";
+import { resolveSymbol, edgeWalk } from "./traverse.js";
+import { cmd } from "../brand.js";
+const ARROW = { in: "←", out: "→" };
+const DEFAULT_DEPTH = 1;
+/** Exported so the MCP `graft_trace_calls` tool (`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` / `edgeWalk` core. */
+export function headerOf(n) {
+    return `${n.name} · ${n.kind} · ${n.path}:${n.span}`;
+}
+/** `showDepth` is set for multi-hop walks (depth > 1), matching the old
+ * `graft impact` output which tagged every hit with its BFS depth.
+ *
+ * `quote`, when given, is the call site itself — the line inside the hit where it
+ * references the symbol. An edge that says "total calls add" is a claim; the line
+ * under it is the evidence, and it saves opening the file to check.
+ */
+export function hitLine(direction, hit, showDepth, quote) {
+    const arrow = ARROW[direction];
+    const depthTag = showDepth ? ` [depth ${hit.depth}]` : "";
+    const label = hit.node ? `${hit.node.name} (${hit.node.path}:${hit.node.span})` : `${hit.id} (unresolved import)`;
+    const line = `  ${hit.relation} ${arrow} ${label}${depthTag}`;
+    return quote ? `${line}\n      ${quote.n}: ${quote.text.trim()}` : line;
+}
+/**
+ * The call site for one hit, or nothing.
+ *
+ * Only for a resolved hit whose span we can read: an unresolved import has no
+ * file, and a hit at depth 2+ references something in between rather than the
+ * symbol asked about, so quoting it would point at the wrong line.
+ */
+function quoteFor(hit, name, read) {
+    if (!hit.node || hit.depth > 1)
+        return undefined;
+    return referenceLine(hit.node.path, hit.node.span, [wordRe(name)], read) ?? undefined;
+}
+/** Tokens-saved baseline for a callers/callees walk: the files of the matched
+ * symbols plus every resolved edge endpoint, read whole — the files you'd open
+ * to trace these edges by hand. Shared by the CLI and the MCP tool so both
+ * surfaces report the same number. */
+export function callersSavings(graph, results) {
+    const paths = [];
+    for (const { symbol, hits } of results) {
+        paths.push(symbol.path);
+        for (const h of hits)
+            if (h.node)
+                paths.push(h.node.path);
+    }
+    return savingsFor(graph, paths);
+}
+/** Loud, actionable empty-result note — never a bare empty list. `candidateCount`
+ * is how many nodes {@link resolveSymbol} matched for this query (both call
+ * sites already hold it as `matches.length`) — when it's >1, the query name is
+ * itself ambiguous (several definitions share it), which is exactly the case
+ * `resolve.ts` drops a cross-file call/reference for rather than guessing which
+ * one it means. Without saying so, a zero-hit result here reads as "nothing
+ * calls this" when it may really be "something does, but the edge was dropped". */
+export function looseNoteFor(direction, name, candidateCount) {
+    const label = direction === "out" ? "callees" : "callers";
+    const dir = direction === "out" ? "outgoing" : "incoming";
+    const ambiguity = candidateCount > 1
+        ? ` ${candidateCount} definitions share the name "${name}"; a cross-file caller of an ambiguous name is dropped rather than guessed, so this may undercount.`
+        : "";
+    return `  no indexed ${label} — the graph has no ${dir} call/reference edges for this symbol as written.${ambiguity} Check the name (try the bare symbol, or "Type.method"), or find its uses with ${cmd("graft grep")} "${name}". Fall back to raw grep -rn only for unindexed files`;
+}
+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;
+}
+/** Parse and validate the raw `--direction` string; exits (code 1) on garbage. */
+function resolveDirection(raw) {
+    if (raw === undefined)
+        return "in";
+    if (raw === "in" || raw === "out")
+        return raw;
+    console.error(`✗ --direction must be "in" or "out", got "${raw}"`);
+    process.exit(1);
+}
+/**
+ * Resolve `query` in the graph at `dir` (respecting `--dir`/`--in`), walk edges
+ * per `--direction`/`--depth`, 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 runCallersCommand(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 \`${cmd("graft build")}\` first`);
+        process.exit(1);
+    }
+    // `resolveSymbol` throws on an `--in` prefix that matches nothing indexed —
+    // a caller mistake, reported in the same shape as the ones around it rather
+    // than as a bare stack-trace message from the top-level handler.
+    let matches;
+    try {
+        matches = resolveSymbol(graph, query, opts.in ? { in: opts.in } : {});
+    }
+    catch (err) {
+        console.error(`✗ ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+        return;
+    }
+    if (matches.length === 0) {
+        console.error(`✗ no symbol "${query}" in the graph — check spelling or run ${cmd("graft build")}`);
+        process.exit(1);
+    }
+    const direction = resolveDirection(opts.direction);
+    let depth = DEFAULT_DEPTH;
+    if (opts.depth !== undefined) {
+        // `all` (aka full/max) = the whole transitive closure: walk until no new
+        // node is reached. The BFS's visited-set makes this cycle-safe, and it
+        // terminates when the frontier empties. This is the "show me every
+        // connected source" mode — the right first move before a multi-file
+        // refactor, where stopping at direct edges misses sibling/downstream files.
+        if (/^(all|full|max)$/i.test(opts.depth)) {
+            depth = Number.POSITIVE_INFINITY;
+        }
+        else {
+            const d = Number(opts.depth);
+            if (!Number.isFinite(d) || d < 1) {
+                console.error(`✗ --depth must be a positive number or "all", got "${opts.depth}"`);
+                process.exit(1);
+            }
+            depth = Math.floor(d);
+        }
+    }
+    const showDepth = depth > 1;
+    const results = matches.map((symbol) => ({ symbol, hits: edgeWalk(graph, symbol, direction, depth) }));
+    const saved = callersSavings(graph, results);
+    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(direction, r.symbol.name, matches.length);
+                }
+                return m;
+            }),
+            saved,
+        };
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+    }
+    const lines = [];
+    // One reader for the whole walk: several hits usually live in the same file.
+    const read = fileReader(root);
+    for (const { symbol, hits } of results) {
+        lines.push(headerOf(symbol));
+        if (hits.length === 0)
+            lines.push(looseNoteFor(direction, symbol.name, matches.length));
+        else
+            for (const h of hits)
+                lines.push(hitLine(direction, h, showDepth, quoteFor(h, symbol.name, read)));
+        lines.push("");
+    }
+    const body = lines.join("\n").replace(/\n+$/, "\n");
+    process.stdout.write(withSavings(body, saved));
+}
+//# 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,112 @@
+/**
+ * Pure graph-traversal core shared by `graft callers` (its `--direction`/
+ * `--depth` flags), the MCP `graft_trace_calls` tool, and `ask`'s structural
+ * intent path.
+ *
+ * Centralizes the symbol-resolution contract (bare name, qualified id-suffix,
+ * last-segment fallback, `--in` narrowing) so all surfaces agree on what a
+ * query like `Cache.get` or `hashstructure.Hash` means, and the direction-aware
+ * (incoming/outgoing) depth-1 and BFS 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";
+/** Which way to walk the wiring graph: `in` = incoming edges (who points at
+ * the symbol — callers / blast radius), `out` = outgoing edges (what the symbol
+ * points at — callees). */
+export type Direction = "in" | "out";
+/** 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 at or under this repo-relative path prefix —
+     * the same segment-aware rule `ask --in` and `grep --in` use, so `--in` means
+     * one thing across every command. Normalized here, so either separator works. */
+    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 walk-relation edges from *multiple* seed nodes at once, in the given
+ * `direction` (`in` = incoming, the default — "who breaks if this changes";
+ * `out` = outgoing — "what this reaches"). 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, direction?: Direction): 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, direction?: Direction): EdgeHit[];
+/**
+ * The single entry point behind `graft callers` and the MCP `graft_trace_calls`
+ * tool, covering all of what were once three commands:
+ *   - `direction:in,  depth:1`  → callers      (who calls/references this)
+ *   - `direction:out, depth:1`  → callees      (what this calls/references)
+ *   - `direction:in,  depth>1`  → blast radius  (transitive dependents)
+ *   - `direction:out, depth>1`  → transitive dependencies
+ *
+ * Depth 1 uses the plain single-hop scan ({@link callersOf}/{@link calleesOf})
+ * so `graft callers <symbol>` output is unchanged. Depth >1 runs the BFS, and
+ * for a `kind: 'file'` seed aggregates over the symbols the file defines (see
+ * {@link impactOfMany}) so file-level dependents aren't silently dropped.
+ */
+export declare function edgeWalk(graph: GraphV1, node: NodeV1, direction: Direction, depth: 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;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAU,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAKpE;;2BAE2B;AAC3B,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,KAAK,CAAC;AAErC;8DAC8D;AAC9D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,oBAAoB;IACnC;;qFAEiF;IACjF,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,CA6BtG;AA4BD;;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;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,QAAQ,SAAI,EAAE,SAAS,GAAE,SAAgB,GAAG,OAAO,EAAE,CAmClH;AAQD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,SAAI,EAAE,SAAS,GAAE,SAAgB,GAAG,OAAO,EAAE,CAEnH;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,EAAE,CAIrG"}

package/dist/graph/traverse.js

@@ -0,0 +1,192 @@
+import { WALK_RELATIONS } from "./relations.js";
+import { assertPrefixIndexed, pathUnderPrefix } from "./scopes.js";
+import { normalizePathPrefix } from "../util/paths.js";
+/**
+ * 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) {
+        const prefix = normalizePathPrefix(opts.in);
+        assertPrefixIndexed(graph, prefix);
+        matches = matches.filter((n) => pathUnderPrefix(n.path, prefix));
+    }
+    return matches;
+}
+/** Strips extract.ts's mint-time disambiguation ordinals (`~2`, `~3`, ...)
+ * from segment ends in a dotted id-tail — the same shape extract.ts mints
+ * when a document-order duplicate definition would otherwise collide with an
+ * already-minted id (see extract.ts's mint-time uniqueness comment). Without
+ * this, a qualified query like `C.m` only ever matches the bare id (`#C.m`),
+ * silently hiding the `~2` duplicate from callers/ask/MCP lookups. The
+ * ordinal can land on any segment, not just the tail (a reopened class shows
+ * up as `C~2.m`), so this strips at every segment boundary (`.` or end of
+ * string), not just the very end of the string. */
+function stripOrdinals(idTail) {
+    return idTail.replace(/~\d+(?=\.|$)/g, "");
+}
+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();
+        const hashIdx = lowerId.indexOf("#");
+        const candidateId = hashIdx === -1 ? lowerId : lowerId.slice(0, hashIdx + 1) + stripOrdinals(lowerId.slice(hashIdx + 1));
+        return candidateId.endsWith(suffixHash) || candidateId.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 walk-relation edges from *multiple* seed nodes at once, in the given
+ * `direction` (`in` = incoming, the default — "who breaks if this changes";
+ * `out` = outgoing — "what this reaches"). 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, direction = "in") {
+    const byId = new Map(graph.nodes.map((n) => [n.id, n]));
+    // Adjacency keyed for the walk direction, restricted to walk relations:
+    //   'in'  → key = edge.target, neighbour = edge.source (who points AT key)
+    //   'out' → key = edge.source, neighbour = edge.target (what key points TO)
+    const adj = new Map();
+    for (const e of graph.edges) {
+        if (!WALK_RELATIONS.has(e.relation))
+            continue;
+        const key = direction === "in" ? e.target : e.source;
+        const other = direction === "in" ? e.source : e.target;
+        const entry = { other, relation: e.relation };
+        const arr = adj.get(key);
+        if (arr)
+            arr.push(entry);
+        else
+            adj.set(key, [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 { other, relation } of adj.get(current) ?? []) {
+                if (visited.has(other))
+                    continue;
+                visited.add(other);
+                hits.push({ node: byId.get(other) ?? null, id: other, relation, depth });
+                next.push(other);
+            }
+        }
+        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, direction = "in") {
+    return impactOfMany(graph, [fileNode, ...symbolsInFile(graph, fileNode)], maxDepth, direction);
+}
+/**
+ * The single entry point behind `graft callers` and the MCP `graft_trace_calls`
+ * tool, covering all of what were once three commands:
+ *   - `direction:in,  depth:1`  → callers      (who calls/references this)
+ *   - `direction:out, depth:1`  → callees      (what this calls/references)
+ *   - `direction:in,  depth>1`  → blast radius  (transitive dependents)
+ *   - `direction:out, depth>1`  → transitive dependencies
+ *
+ * Depth 1 uses the plain single-hop scan ({@link callersOf}/{@link calleesOf})
+ * so `graft callers <symbol>` output is unchanged. Depth >1 runs the BFS, and
+ * for a `kind: 'file'` seed aggregates over the symbols the file defines (see
+ * {@link impactOfMany}) so file-level dependents aren't silently dropped.
+ */
+export function edgeWalk(graph, node, direction, depth) {
+    if (depth <= 1)
+        return direction === "in" ? callersOf(graph, node) : calleesOf(graph, node);
+    if (node.kind === "file")
+        return impactOfFile(graph, node, depth, direction);
+    return impactOfMany(graph, [node], depth, direction);
+}
+//# 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/types.d.ts

@@ -0,0 +1,78 @@
+/**
+ * `graph.json` — the code graph schema (v1).
+ *
+ * One node per definition (file, class, function, method, interface, type, enum),
+ * wired by edges (contains, imports, calls, ...). Field names follow the LSP
+ * vocabulary (`name`, `kind`, ...) rather than any one tool's conventions.
+ *
+ * Two tiers of data live on a node:
+ *   - Tier-1 (deterministic, $0): everything from the AST. Rebuilt on every run.
+ *   - Tier-2 (one LLM call, cached on `body_hash`): `summary` + `crux`.
+ * M1 populates Tier-1 only; Tier-2 fields ship as `pending`/null.
+ */
+/** What a node represents. LSP SymbolKind, narrowed to what our extractors produce. */
+export type Kind = "file" | "class" | "function" | "method" | "interface" | "type" | "enum" | "struct" | "trait" | "module" | "constant" | "variable";
+/** How confident we are an edge is true, best-first. The hand-written AST
+ * resolver assigns `extracted`/`inferred`; the opt-in LSP enrichment pass
+ * (`graft build --lsp`) can promote an edge to compiler-grade `lsp_resolved`
+ * (an exact server-confirmed target) or `lsp_dispatch` (an interface/virtual
+ * candidate). Order matters: consumers that rank by provenance treat earlier
+ * values as stronger. */
+export type Confidence = "lsp_resolved" | "lsp_dispatch" | "extracted" | "inferred";
+/** Whether the LLM meaning-layer has been computed for a node. */
+export type SummaryState = "pending" | "ready" | "stale";
+/** The LLM-chosen business-logic excerpt. `code` is the source of truth; `span`
+ * is a best-effort pointer that may drift and is never used to re-slice. */
+export interface Crux {
+    code: string;
+    span: string;
+}
+export interface NodeV1 {
+    id: string;
+    name: string;
+    kind: Kind;
+    owner?: string;
+    path: string;
+    span: string;
+    signature: string | null;
+    exported: boolean;
+    origin: "ast" | "generic";
+    body_hash: string;
+    chars?: number;
+    body_text?: string;
+    arity?: number;
+    variadic?: boolean;
+    summary_state: SummaryState;
+    summary: string | null;
+    crux: Crux | null;
+}
+export type Relation = "contains" | "calls" | "imports" | "references" | "implements" | "extends";
+export interface EdgeV1 {
+    source: string;
+    target: string;
+    relation: Relation;
+    confidence: Confidence;
+}
+/** A ranking scope: a sub-project discovered by project-marker files (`package.json`,
+ * `go.mod`, ...). `prefix` is a posix path relative to the graph root ("" = root scope);
+ * `label` is the same value without a trailing slash (also "" for root); `markers` lists
+ * which marker file(s) were found in that directory. See `src/graph/scopes.ts`. */
+export interface ScopeV1 {
+    prefix: string;
+    label: string;
+    markers: string[];
+}
+export interface GraphV1 {
+    meta: {
+        version: 1;
+        nodeCount: number;
+        edgeCount: number;
+        languages: string[];
+        /** Ranking scopes: posix path prefixes relative to the graph root, "" = root scope.
+         * Absent (old graphs) ≡ [{ prefix: "", label: "" }]. Sorted by prefix length desc. */
+        scopes?: ScopeV1[];
+    };
+    nodes: NodeV1[];
+    edges: EdgeV1[];
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/graph/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,uFAAuF;AACvF,MAAM,MAAM,IAAI,GACZ,MAAM,GACN,OAAO,GACP,UAAU,GACV,QAAQ,GACR,WAAW,GACX,MAAM,GACN,MAAM,GACN,QAAQ,GACR,OAAO,GAMP,QAAQ,GACR,UAAU,GACV,UAAU,CAAC;AAEf;;;;;yBAKyB;AACzB,MAAM,MAAM,UAAU,GAAG,cAAc,GAAG,cAAc,GAAG,WAAW,GAAG,UAAU,CAAC;AAEpF,kEAAkE;AAClE,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;AAEzD;4EAC4E;AAC5E,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,MAAM;IAErB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,IAAI,CAAC;IAKX,KAAK,CAAC,EAAE,MAAM,CAAC;IAGf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;IAIlB,MAAM,EAAE,KAAK,GAAG,SAAS,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,SAAS,CAAC,EAAE,MAAM,CAAC;IAKnB,KAAK,CAAC,EAAE,MAAM,CAAC;IAMf,QAAQ,CAAC,EAAE,OAAO,CAAC;IAInB,aAAa,EAAE,YAAY,CAAC;IAC5B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;CACnB;AAED,MAAM,MAAM,QAAQ,GAChB,UAAU,GACV,OAAO,GACP,SAAS,GACT,YAAY,GACZ,YAAY,GACZ,SAAS,CAAC;AAEd,MAAM,WAAW,MAAM;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,QAAQ,CAAC;IACnB,UAAU,EAAE,UAAU,CAAC;CACxB;AAED;;;mFAGmF;AACnF,MAAM,WAAW,OAAO;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE;QACJ,OAAO,EAAE,CAAC,CAAC;QACX,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,EAAE,CAAC;QACpB;8FACsF;QACtF,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;KACpB,CAAC;IACF,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB"}

package/dist/graph/types.js

@@ -0,0 +1,14 @@
+/**
+ * `graph.json` — the code graph schema (v1).
+ *
+ * One node per definition (file, class, function, method, interface, type, enum),
+ * wired by edges (contains, imports, calls, ...). Field names follow the LSP
+ * vocabulary (`name`, `kind`, ...) rather than any one tool's conventions.
+ *
+ * Two tiers of data live on a node:
+ *   - Tier-1 (deterministic, $0): everything from the AST. Rebuilt on every run.
+ *   - Tier-2 (one LLM call, cached on `body_hash`): `summary` + `crux`.
+ * M1 populates Tier-1 only; Tier-2 fields ship as `pending`/null.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/graph/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/graph/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/graph/wasm-runtime.d.ts

@@ -0,0 +1,19 @@
+type WebTreeSitter = typeof import("web-tree-sitter");
+/** The initialised current runtime, loading and initialising it on the first call. */
+export declare function webTreeSitter(): Promise<WebTreeSitter>;
+/** What the depth tier uses of web-tree-sitter 0.22's API. */
+export interface DepthWasmParser {
+    setLanguage(language: unknown): void;
+    parse(input: (index: number) => string): {
+        rootNode: unknown;
+        delete(): void;
+    } | null;
+}
+export interface DepthRuntime {
+    load(wasm: Uint8Array): Promise<unknown>;
+    newParser(): DepthWasmParser;
+}
+/** The depth tier's runtime, initialised on the first call. */
+export declare function depthRuntime(): Promise<DepthRuntime>;
+export {};
+//# sourceMappingURL=wasm-runtime.d.ts.map

package/dist/graph/wasm-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasm-runtime.d.ts","sourceRoot":"","sources":["../../src/graph/wasm-runtime.ts"],"names":[],"mappings":"AAmBA,KAAK,aAAa,GAAG,cAAc,iBAAiB,CAAC,CAAC;AAItD,sFAAsF;AACtF,wBAAgB,aAAa,IAAI,OAAO,CAAC,aAAa,CAAC,CAMtD;AAED,8DAA8D;AAC9D,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAC;IACrC,KAAK,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,MAAM,IAAI,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;CACvF;AAMD,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzC,SAAS,IAAI,eAAe,CAAC;CAC9B;AAID,+DAA+D;AAC/D,wBAAgB,YAAY,IAAI,OAAO,CAAC,YAAY,CAAC,CAOpD"}