Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

feat: fold callees/impact into callers (0.6.0); tokens-saved footer on all retrieval cmds

anirudhkumar-nanonets486c03622eac
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 00000000..aface2a4
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,43 @@
+# Changelog
+
+## 0.6.0
+
+Consolidates the structural-traversal surface and wires the MCP server into
+Claude Code. **Breaking** — see migration below.
+
+### Breaking
+
+- **Removed `graft callees` and `graft impact`.** Both fold into `graft callers`:
+ - `graft callees <symbol>` → `graft callers <symbol> --direction out`
+ - `graft impact <symbol> -d N` → `graft callers <symbol> --depth N`
+ - `graft callers` with no new flags is unchanged (defaults `--direction in --depth 1`).
+- **Removed MCP tools `graft_callees` and `graft_blast_radius`.** The `graft_callers`
+ tool now takes optional `direction` (`in`|`out`, default `in`) and `depth`
+ (default `1`) parameters covering both:
+ - callees → `graft_callers { direction: "out" }`
+ - blast radius → `graft_callers { depth: N }` (accepts a file path or symbol,
+ same file-seed aggregation the old `graft_blast_radius` did).
+
+ Rationale: a coding-agent tool-selection experiment showed agents never picked
+ `graft_blast_radius`/`impact` (they reconstructed it by calling `callers`
+ repeatedly) and never picked `callees` (they read the named file instead). One
+ well-named command with flags is selected more reliably than three.
+
+### Added
+
+- `graft callers --direction <in|out>` — walk incoming (callers, default) or
+ outgoing (callees) edges.
+- `graft callers --depth <n>` — walk transitively out to depth N for the full
+ blast radius (default 1 = direct edges only). For a file seed at depth >1 the
+ walk aggregates over the symbols the file defines.
+- `graft init` now registers the graft MCP server in the project's `.mcp.json`
+ for Claude Code (previously Claude Code got only hooks + statusline + skill).
+ Restart Claude Code to load it. Existing `.mcp.json` servers are preserved.
+
+### Changed
+
+- `graft mcp --help` and docs now list the full tool set
+ (`graft_ask`, `graft_callers`, `graft_grep`, `graft_skeleton`, `graft_map`,
+ `graft_check`) instead of only three.
+- The bundled Claude Code skill and other-agent instructions document the
+ consolidated `callers` flags.
diff --git a/README.md b/README.md
index 9f953e33..0a4c07e1 100644
--- a/README.md
+++ b/README.md
@@ -71,9 +71,11 @@ npx @nanonets/graft init
### MCP server
`graft init` also registers Graft's MCP server with agents that support it, so
-`graft_ask`, `graft_check`, and `graft_blast_radius` appear as native tools —
-no shell required. Skip with `--no-mcp`. Run it manually with `graft mcp [dir]`,
-or register it by hand:
+`graft_ask`, `graft_callers`, `graft_grep`, `graft_skeleton`, `graft_map`, and
+`graft_check` appear as native tools — no shell required. Claude Code now gets
+this too: `graft init` writes the server into the project's `.mcp.json` (restart
+Claude Code to load it). Skip with `--no-mcp`. Run it manually with
+`graft mcp [dir]`, or register it by hand:
```json
{ "mcpServers": { "graft": { "command": "npx", "args": ["-y", "@nanonets/graft", "mcp"] } } }
@@ -189,8 +191,8 @@ graft ask "<task>" [dir] # query the graph — ranked nodes + exact
graft ask "<task>" --json # machine-readable result
graft callers <symbol> [dir] # who calls/references/imports/implements/extends a symbol (no LLM, no key)
-graft callees <symbol> [dir] # what a symbol calls/references/imports/implements/extends (no LLM, no key)
-graft impact <symbol> [dir] -d N # BFS over incoming edges — who breaks if this symbol changes (no LLM, no key)
+graft callers <symbol> --direction out # the reverse: what the symbol itself calls/references (was `graft callees`)
+graft callers <symbol> -d N # walk transitively out to depth N — full blast radius (was `graft impact`)
graft grep "<regex>" [dir] # exhaustive regex search over indexed files, grouped by enclosing symbol (no LLM, no key)
graft grep "<regex>" --in <path> # narrow to files whose path contains this substring
@@ -205,7 +207,7 @@ graft check --json # print the drift report as JSON
graft viz [dir] # see the graph: serves an interactive viewer on localhost
graft viz --port 5000 --no-open # pick a port; don't auto-open the browser
-graft init [dir] # wire Graft into the coding agents detected in this repo (Claude Code always gets full hooks + statusline)
+graft init [dir] # wire Graft into the coding agents detected in this repo (Claude Code always gets full hooks + statusline + MCP)
graft init --no-build # wire the files only; don't build the graph
graft init --agents cursor kiro # wire only these agents (ids: agents, cursor, gemini, copilot, kiro, windsurf, claude)
graft init --all-agents # wire every known agent, detected or not
@@ -221,7 +223,7 @@ graft --version, -v # print the installed version and exit
Method calls resolve through the receiver's type — constructor assignments
(`self.router = APIRouter()`) and type annotations, not just the call-site
-name — so `callers`/`impact`/`grep --in` return calls bound to the right
+name — so `callers`/`grep --in` return calls bound to the right
type on method-heavy code, not every method anywhere with that name.
## Search & orient (`graft grep` / `graft map`)
diff --git a/graft/.graph/wiring.json b/graft/.graph/wiring.json
index ab706939..35084f6b 100644
--- a/graft/.graph/wiring.json
+++ b/graft/.graph/wiring.json
@@ -1,8 +1,8 @@
{
"meta": {
"version": 1,
- "nodeCount": 750,
- "edgeCount": 1924,
+ "nodeCount": 758,
+ "edgeCount": 1955,
"languages": [
"typescript"
]
@@ -2096,13 +2096,13 @@
"name": "ask.ts",
"kind": "file",
"path": "src/ask/ask.ts",
- "span": "L1-L749",
+ "span": "L1-L756",
"signature": null,
"exported": true,
"origin": "ast",
- "body_hash": "62d693c39f77019e50437b5285fafe5802b8b077e7aa6545589a3b084f93e552",
- "chars": 32834,
- "summary_state": "ready",
+ "body_hash": "7a50c1c1d10cf0339157147d88858dcd22a2f3fad56f426bbf75fbcff29f4538",
+ "chars": 33648,
+ "summary_state": "stale",
"summary": "This module provides a mechanism to process natural language queries and return structured results from a codebase, enhancing the ability to find relevant code snippets and their relationships.",
"crux": {
"code": "function structural(query: string, graph: GraphV1, limit: number): StructuralOutcome {\n const wantsIn = INCOMING.test(query);\n const wantsOut = OUTGOING.test(query);\n if (!wantsIn && !wantsOut) return null;\n\n const { nodes: subjects, tried } = findSubjectNodes(query, graph);\n if (subjects.length === 0) return { fallthroughNote: fallthroughNoteFor(tried) };\n\n const ids = new Set(subjects.map((n) => n.id));\n const byId = new Map(graph.nodes.map((n) => [n.id, n]));\n const outgoing = wantsOut && !wantsIn; // \"what does X call / import\" — else default to callers\n const rels = new Set(outgoing ? OUTGOING_RELS : INCOMING_RELS);",
@@ -2114,7 +2114,7 @@
"name": "ask",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L592-L622",
+ "span": "L581-L611",
"signature": "function ask(dir: string, query: string, opts: AskOptions = {}): AskResult",
"exported": true,
"origin": "ast",
@@ -2131,7 +2131,7 @@
"name": "AskHit",
"kind": "interface",
"path": "src/ask/ask.ts",
- "span": "L26-L39",
+ "span": "L27-L40",
"signature": "interface AskHit",
"exported": true,
"origin": "ast",
@@ -2145,7 +2145,7 @@
"name": "AskOptions",
"kind": "interface",
"path": "src/ask/ask.ts",
- "span": "L489-L505",
+ "span": "L490-L506",
"signature": "interface AskOptions",
"exported": true,
"origin": "ast",
@@ -2162,7 +2162,7 @@
"name": "AskResult",
"kind": "interface",
"path": "src/ask/ask.ts",
- "span": "L45-L62",
+ "span": "L46-L63",
"signature": "interface AskResult",
"exported": true,
"origin": "ast",
@@ -2174,17 +2174,31 @@
"span": "L45-L56"
}
},
+ {
+ "id": "src/ask/ask.ts#askSavingsFooter",
+ "name": "askSavingsFooter",
+ "kind": "function",
+ "path": "src/ask/ask.ts",
+ "span": "L743-L755",
+ "signature": "function askSavingsFooter(r: AskResult, body: string): string",
+ "exported": false,
+ "origin": "ast",
+ "body_hash": "6d41a7ba0226bbe165fcaaf3024079b957cfb23397111727ab8c642871a10718",
+ "summary_state": "pending",
+ "summary": null,
+ "crux": null
+ },
{
"id": "src/ask/ask.ts#baselineFor",
"name": "baselineFor",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L574-L589",
+ "span": "L575-L578",
"signature": "function baselineFor(hits: AskHit[], graph: GraphV1 | null): AskResult[\"saved\"] | undefined",
"exported": false,
"origin": "ast",
- "body_hash": "72fb36d83f07af995f68449fa92d57766850ea34ff5644a0a09dde44e0f19ae2",
- "summary_state": "ready",
+ "body_hash": "91cd3cce13a575ea02b8aa87e2fa9a411a7c34fe85f654640d382f4f305bf8b7",
+ "summary_state": "stale",
"summary": "Calculates the baseline file size and character count for the hits, providing a measure of the cost of reading the full files.",
"crux": {
"code": "function baselineFor(hits: AskHit[], graph: GraphV1 | null): AskResult[\"saved\"] | undefined {\n if (!graph) return undefined;\n const size = new Map<string, number>();\n for (const n of graph.nodes)\n if (n.kind === \"file\" && typeof n.chars === \"number\") size.set(n.path, n.chars);\n\n let baselineChars = 0;\n let files = 0;\n for (const path of hitFiles(hits)) {\n const c = size.get(path);\n if (c === undefined) continue;\n baselineChars += c;",
@@ -2196,7 +2210,7 @@
"name": "bm25",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L166-L182",
+ "span": "L167-L183",
"signature": "function bm25( query: Map<string, number>, doc: Map<string, number>, idf: Map<string, number>, dl: number, avgdl: number, ): number",
"exported": false,
"origin": "ast",
@@ -2213,7 +2227,7 @@
"name": "computeIdf",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L140-L145",
+ "span": "L141-L146",
"signature": "function computeIdf(docBags: Array<Set<string>>): Map<string, number>",
"exported": false,
"origin": "ast",
@@ -2230,7 +2244,7 @@
"name": "computeIdfFromIndex",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L154-L159",
+ "span": "L155-L160",
"signature": "function computeIdfFromIndex(index: AskIndex, conceptBags: Array<Set<string>>): Map<string, number>",
"exported": false,
"origin": "ast",
@@ -2247,7 +2261,7 @@
"name": "Corpus",
"kind": "interface",
"path": "src/ask/ask.ts",
- "span": "L74-L81",
+ "span": "L75-L82",
"signature": "interface Corpus",
"exported": false,
"origin": "ast",
@@ -2259,12 +2273,26 @@
"span": "L74-L81"
}
},
+ {
+ "id": "src/ask/ask.ts#escalationNudge",
+ "name": "escalationNudge",
+ "kind": "function",
+ "path": "src/ask/ask.ts",
+ "span": "L731-L738",
+ "signature": "function escalationNudge(r: AskResult): string",
+ "exported": false,
+ "origin": "ast",
+ "body_hash": "9c40bcc6776ac6747c2735c73c9461cc93d6ff1af1169d6696ef3fc24d721668",
+ "summary_state": "pending",
+ "summary": null,
+ "crux": null
+ },
{
"id": "src/ask/ask.ts#fallthroughNoteFor",
"name": "fallthroughNoteFor",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L223-L228",
+ "span": "L224-L229",
"signature": "function fallthroughNoteFor(subject: string): string",
"exported": false,
"origin": "ast",
@@ -2281,7 +2309,7 @@
"name": "findSubjectNodes",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L206-L213",
+ "span": "L207-L214",
"signature": "function findSubjectNodes(query: string, graph: GraphV1): { nodes: NodeV1[]; tried: string }",
"exported": false,
"origin": "ast",
@@ -2298,7 +2326,7 @@
"name": "firstProse",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L65-L72",
+ "span": "L66-L73",
"signature": "function firstProse(body: string): string",
"exported": false,
"origin": "ast",
@@ -2315,12 +2343,12 @@
"name": "formatAsk",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L693-L731",
+ "span": "L686-L724",
"signature": "function formatAsk(r: AskResult): string",
"exported": true,
"origin": "ast",
- "body_hash": "413023c3201e82617c165c0ddf39bf37f4e963b7d5c1af202ff4f7132191f8ae",
- "summary_state": "ready",
+ "body_hash": "804ecdadf6fb746fe70ea7fa3e2f3d5f4a37e01d04a648e740d6ef7d57af593c",
+ "summary_state": "stale",
"summary": "Formats the results of an ask query into a string for presentation, ensuring clarity and usability.",
"crux": {
"code": "export function formatAsk(r: AskResult): string {\n const head = `graft ask — \"${r.query}\" (${r.mode})`;\n // The note prints as its own prominent line(s) right under the header —\n // above every hit — so a loud structural-fallthrough note (or the\n // no-structural-edges / no-lexical-match note) can never be missed by only\n // being embedded inline in the header parenthetical. Only a genuine\n // fallthrough/warning line (from `fallthroughNoteFor`, always prefixed\n // \"structural index:\") gets the ⚠ marker; the benign structural header note\n // (\"callers / references of X\" / \"outgoing edges from X\") prints plain —\n // it's informational, not a warning.\n const noteBlock = r.note\n ? r.note",
@@ -2332,12 +2360,12 @@
"name": "formatSkeleton",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L676-L685",
+ "span": "L668-L678",
"signature": "function formatSkeleton(r: SkeletonResult): string",
"exported": true,
"origin": "ast",
- "body_hash": "959580717569409d09522b36316a884d13fc49702fdd4aa9b55b7d534afdc0fc",
- "summary_state": "ready",
+ "body_hash": "25c867d1efd19358c8ecd1cd4024c42f8050b8c07816a4a1df6edc57f7a0583d",
+ "summary_state": "stale",
"summary": "Formats the skeleton result into a string representation for display or output purposes.",
"crux": {
"code": "export function formatSkeleton(r: SkeletonResult): string {\n const head = `graft skeleton — ${r.file}`;\n if (!r.entries.length) return `${head}\\n\\n${r.note ?? \"no definitions.\"}\\n`;\n const lines = r.entries.map((e) => {\n const sig = e.signature ? ` ${e.signature}` : \"\";\n const sum = e.summary ? ` — ${e.summary}` : \"\";\n return `- ${e.span} ${e.kind} ${e.name}${sig}${sum}`;\n });\n return `${head}\\n${lines.join(\"\\n\")}\\n`;\n}",
@@ -2349,7 +2377,7 @@
"name": "hasTerm",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L298-L300",
+ "span": "L299-L301",
"signature": "function hasTerm(f: Map<string, number>, t: string): boolean",
"exported": false,
"origin": "ast",
@@ -2366,7 +2394,7 @@
"name": "hitFiles",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L560-L569",
+ "span": "L561-L570",
"signature": "function hitFiles(hits: AskHit[]): Set<string>",
"exported": false,
"origin": "ast",
@@ -2383,7 +2411,7 @@
"name": "idfFromDf",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L134-L138",
+ "span": "L135-L139",
"signature": "function idfFromDf(df: Map<string, number>, n: number): Map<string, number>",
"exported": false,
"origin": "ast",
@@ -2400,7 +2428,7 @@
"name": "inlineSource",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L539-L556",
+ "span": "L540-L557",
"signature": "function inlineSource(root: string, hits: AskHit[], graph: GraphV1 | null, full: boolean): void",
"exported": false,
"origin": "ast",
@@ -2417,7 +2445,7 @@
"name": "lexical",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L325-L487",
+ "span": "L326-L488",
"signature": "function lexical(query: string, corpus: Corpus, limit: number, graphRank: boolean): AskResult",
"exported": false,
"origin": "ast",
@@ -2434,7 +2462,7 @@
"name": "bodyLen",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L416-L420",
+ "span": "L417-L421",
"signature": "bodyLen = (m: Map<string, number>)",
"exported": false,
"origin": "ast",
@@ -2451,7 +2479,7 @@
"name": "loadCorpus",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L83-L108",
+ "span": "L84-L109",
"signature": "function loadCorpus(outDir: string): Corpus",
"exported": false,
"origin": "ast",
@@ -2468,7 +2496,7 @@
"name": "matchedIdfShare",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L309-L323",
+ "span": "L310-L324",
"signature": "function matchedIdfShare( q: Map<string, number>, fields: Array<Map<string, number>>, idf: Map<string, number>, dfltIdf: number, ): number",
"exported": false,
"origin": "ast",
@@ -2485,7 +2513,7 @@
"name": "parseSpan",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L509-L513",
+ "span": "L510-L514",
"signature": "function parseSpan(pointer: string): { path: string; from: number; to: number } | null",
"exported": false,
"origin": "ast",
@@ -2497,29 +2525,12 @@
"span": "L255-L257"
}
},
- {
- "id": "src/ask/ask.ts#savingsFooter",
- "name": "savingsFooter",
- "kind": "function",
- "path": "src/ask/ask.ts",
- "span": "L736-L748",
- "signature": "function savingsFooter(r: AskResult, body: string): string",
- "exported": false,
- "origin": "ast",
- "body_hash": "343954821ba1b41301acd0788cd9e648cd4aa44d498a57028a52d290d97de7c5",
- "summary_state": "ready",
- "summary": "Generates a footer for the ask results that summarizes the savings in terms of file reading costs.",
- "crux": {
- "code": "function savingsFooter(r: AskResult, body: string): string {\n if (!r.saved || r.saved.baselineChars <= 0) return \"\";\n const pack = toTokens(body.length);\n const base = toTokens(r.saved.baselineChars);\n if (base <= pack) return \"\"; // no saving to claim (tiny files); stay quiet\n const saved = base - pack;\n const pct = Math.round((saved / base) * 100);\n return (\n `\\n\\n[graft] tokens saved ≈ ${saved.toLocaleString()} (${pct}%) — this pack ≈ ` +\n `${pack.toLocaleString()} tok vs reading the ${r.saved.files} source file(s) whole ≈ ` +\n `${base.toLocaleString()} tok. Estimate (baseline = those files read in full).`\n );",
- "span": "L736-L747"
- }
- },
{
"id": "src/ask/ask.ts#score",
"name": "score",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L117-L128",
+ "span": "L118-L129",
"signature": "function score( query: Map<string, number>, doc: Map<string, number>, idf: Map<string, number>, ): number",
"exported": false,
"origin": "ast",
@@ -2536,12 +2547,12 @@
"name": "skeleton",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L644-L673",
+ "span": "L635-L665",
"signature": "function skeleton(dir: string, file: string, opts: { contextDir?: string } = {}): SkeletonResult",
"exported": true,
"origin": "ast",
- "body_hash": "dce0b973c651c9f800712f6a2ab2fb09cb21f9fb943d36f0b15bc6286c02b8f7",
- "summary_state": "ready",
+ "body_hash": "c2057571eb11b9a08e8cd9a1d73d9f006fdfa2cd41df94080656b8e17889f1b2",
+ "summary_state": "stale",
"summary": "Extracts a skeleton representation of a file, providing a summary and context for its contents.",
"crux": {
"code": "export function skeleton(dir: string, file: string, opts: { contextDir?: string } = {}): SkeletonResult {\n const outDir = contextDirFor(resolve(dir), opts.contextDir);\n const graph = loadGraphCached(outDir);\n if (!graph) return { file, entries: [], note: \"no wiring graph — run `graft build` first\" };\n\n let defs = graph.nodes.filter((n) => n.kind !== \"file\" && n.path === file);\n if (!defs.length) {\n const matches = new Set(\n graph.nodes.filter((n) => n.path === file || n.path.endsWith(`/${file}`)).map((n) => n.path),\n );\n if (matches.size > 1)\n return { file, entries: [], note: `ambiguous — matches: ${[...matches].sort().join(\", \")}` };",
@@ -2553,7 +2564,7 @@
"name": "startLine",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L661-L661",
+ "span": "L652-L652",
"signature": "startLine = (span: string)",
"exported": true,
"origin": "ast",
@@ -2570,7 +2581,7 @@
"name": "SkeletonEntry",
"kind": "interface",
"path": "src/ask/ask.ts",
- "span": "L626-L633",
+ "span": "L615-L622",
"signature": "interface SkeletonEntry",
"exported": true,
"origin": "ast",
@@ -2587,12 +2598,12 @@
"name": "SkeletonResult",
"kind": "interface",
"path": "src/ask/ask.ts",
- "span": "L635-L639",
+ "span": "L624-L630",
"signature": "interface SkeletonResult",
"exported": true,
"origin": "ast",
- "body_hash": "852555fd408bd54eca9e183234e6d6d89e02e58efa4f3c180e93d1641febe36c",
- "summary_state": "ready",
+ "body_hash": "9fc13a0df0d2a8e697e0526483319f3f1335418f90e29beaa6f6e6c0e25b12f5",
+ "summary_state": "stale",
"summary": "Defines the structure of the result returned from the skeleton function, encapsulating the extracted information.",
"crux": {
"code": "export interface SkeletonResult {\n file: string;\n entries: SkeletonEntry[];\n note?: string;\n}",
@@ -2604,7 +2615,7 @@
"name": "sliceSpan",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L517-L532",
+ "span": "L518-L533",
"signature": "function sliceSpan(root: string, path: string, from: number, to: number): string | null",
"exported": false,
"origin": "ast",
@@ -2621,7 +2632,7 @@
"name": "structural",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L230-L279",
+ "span": "L231-L280",
"signature": "function structural(query: string, graph: GraphV1, limit: number): StructuralOutcome",
"exported": false,
"origin": "ast",
@@ -2638,7 +2649,7 @@
"name": "StructuralOutcome",
"kind": "type",
"path": "src/ask/ask.ts",
- "span": "L221-L221",
+ "span": "L222-L222",
"signature": "type StructuralOutcome = { result: AskResult } | { fallthroughNote: string } | null;",
"exported": false,
"origin": "ast",
@@ -2655,7 +2666,7 @@
"name": "subjectWords",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L194-L196",
+ "span": "L195-L197",
"signature": "function subjectWords(query: string): string[]",
"exported": false,
"origin": "ast",
@@ -2672,7 +2683,7 @@
"name": "toTokens",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L688-L690",
+ "span": "L681-L683",
"signature": "function toTokens(chars: number): number",
"exported": false,
"origin": "ast",
@@ -2923,13 +2934,13 @@
"name": "format.ts",
"kind": "file",
"path": "src/claude/format.ts",
- "span": "L1-L174",
+ "span": "L1-L183",
"signature": null,
"exported": true,
"origin": "ast",
- "body_hash": "de278daec7071243ac381603d43817c6589406a1c8d03cef4d0bcf58b4b1d902",
- "chars": 7803,
- "summary_state": "ready",
+ "body_hash": "332bb3a33ff816cd4db1b8db53d5f735eacedd98caddfa26c09be81bc2e62144",
+ "chars": 8623,
+ "summary_state": "stale",
"summary": "This file contains functions and types for formatting and rendering status information related to a graph-based system.",
"crux": null
},
@@ -2986,12 +2997,12 @@
"name": "formatOrientation",
"kind": "function",
"path": "src/claude/format.ts",
- "span": "L165-L167",
+ "span": "L165-L176",
"signature": "function formatOrientation(indexMd: string, budgetBytes = 1500): string",
"exported": true,
"origin": "ast",
- "body_hash": "0da076da5c6f3cacf6a7e8d372517b658ae7cd073d52740909684ba5b5aff6f0",
- "summary_state": "ready",
+ "body_hash": "675c636789b2140b470d83e2665878a0813525aa34efd8935e352318c5b12649",
+ "summary_state": "stale",
"summary": "Creates a formatted string representing the orientation of the repository map, limited to a specified byte budget.",
"crux": {
"code": " return `[graft] repo map (graft/INDEX.md):\\n${indexMd.slice(0, budgetBytes)}`;",
@@ -3105,7 +3116,7 @@
"name": "renderSubagent",
"kind": "function",
"path": "src/claude/format.ts",
- "span": "L169-L173",
+ "span": "L178-L182",
"signature": "function renderSubagent(agentName: string, session: SessionState | null): string",
"exported": true,
"origin": "ast",
@@ -3126,8 +3137,8 @@
"signature": "function retrievalBody(hits: AskJson['hits']): string",
"exported": false,
"origin": "ast",
- "body_hash": "2e68851469a8165204e9fbaf2dab76cbb78d5671cd5437b3a40498acc95a92fd",
- "summary_state": "ready",
+ "body_hash": "c1f7256a9594b2717c050b70c35592a22334e58f69fe95236583a42cb6abf899",
+ "summary_state": "stale",
"summary": "Constructs a formatted string representation of retrieval hits, including pointers and snippets, for display purposes.",
"crux": {
"code": " const blocks = hits.map((h, i) => {\n const ptr = (h.pointer ?? '').split(',')[0].trim();\n const snip = (h.snippet ?? '').replace(/\\s+/g, ' ').trim().slice(0, 140);\n let b = ` ${i + 1}. ${h.title} — ${ptr}`;\n if (snip) b += `\\n ${snip}`;\n if (h.code) b += `\\n\\`\\`\\`\\n${h.code}\\n\\`\\`\\``;\n return b;\n });\n // Two pack shapes: with inlined code the pack is substitutive (read here, don't\n // re-open); without code it is pointers-only — locators the agent may follow,\n // pulling spans itself via `graft ask --source` (push→pull: per-prompt injected\n // tokens are always fresh full-price input, so the pack stays tiny).",
@@ -3355,13 +3366,13 @@
"name": "init.ts",
"kind": "file",
"path": "src/claude/init.ts",
- "span": "L1-L50",
+ "span": "L1-L58",
"signature": null,
"exported": true,
"origin": "ast",
- "body_hash": "7a686f132722453ee18c4715e4ab563f1577ac41811b01cced574de075a452ee",
- "chars": 2251,
- "summary_state": "ready",
+ "body_hash": "af0c4b0aa75bc1753bfa634e939200cb96539b0388e22549ac458267cbd0ab7e",
+ "chars": 2762,
+ "summary_state": "stale",
"summary": "Initializes the Claude environment by setting up necessary directories, configuration files, and shims for the application.",
"crux": {
"code": "export function runInit(dir: string, opts: { build?: boolean; cliPath?: string } = {}): InitResult {\n const helpersDir = join(dir, '.claude', 'helpers');\n mkdirSync(helpersDir, { recursive: true });\n\n const settingsPath = join(dir, '.claude', 'settings.json');\n let existing: Record<string, any> = {};\n try { existing = JSON.parse(readFileSync(settingsPath, 'utf8')); } catch { /* none/invalid → start fresh */ }\n const { merged, warnings } = mergeGraftSettings(existing);\n writeFileSync(settingsPath, `${JSON.stringify(merged, null, 2)}\\n`);\n\n const sl = join(helpersDir, 'graft-statusline.cjs');\n const hk = join(helpersDir, 'graft-hooks.cjs');",
@@ -3373,12 +3384,12 @@
"name": "InitResult",
"kind": "interface",
"path": "src/claude/init.ts",
- "span": "L9-L15",
+ "span": "L10-L18",
"signature": "interface InitResult",
"exported": true,
"origin": "ast",
- "body_hash": "452d62ae1f5e60a539835b2fe9892f24cb79cb4b002808473397cfd0f3e729cc",
- "summary_state": "ready",
+ "body_hash": "648322df342d1b35df7d6be1f7626e5deff07a53a4cd67d247b681bdc3db3386",
+ "summary_state": "stale",
"summary": "Defines the structure of the result returned by the runInit function, encapsulating settings, shims, skill, warnings, and build status.",
"crux": null
},
@@ -3387,12 +3398,12 @@
"name": "runInit",
"kind": "function",
"path": "src/claude/init.ts",
- "span": "L17-L49",
+ "span": "L20-L57",
"signature": "function runInit(dir: string, opts: { build?: boolean; cliPath?: string } = {}): InitResult",
"exported": true,
"origin": "ast",
- "body_hash": "8b5756f072c04e6fcef32d10f1a29a8b5c0d4f5e68d7642cfcb1ab43aef61fb0",
- "summary_state": "ready",
+ "body_hash": "ea3853a573550bbd8095b416a8894cbbcfef1f264a41bb18ea37b17fa3475577",
+ "summary_state": "stale",
"summary": "Initializes the Claude environment by setting up necessary directories, merging settings, creating shims, and optionally building the project.",
"crux": {
"code": "export function runInit(dir: string, opts: { build?: boolean; cliPath?: string } = {}): InitResult {\n const helpersDir = join(dir, '.claude', 'helpers');\n mkdirSync(helpersDir, { recursive: true });\n\n const settingsPath = join(dir, '.claude', 'settings.json');\n let existing: Record<string, any> = {};\n try { existing = JSON.parse(readFileSync(settingsPath, 'utf8')); } catch { /* none/invalid → start fresh */ }\n const { merged, warnings } = mergeGraftSettings(existing);\n writeFileSync(settingsPath, `${JSON.stringify(merged, null, 2)}\\n`);\n\n const sl = join(helpersDir, 'graft-statusline.cjs');\n const hk = join(helpersDir, 'graft-hooks.cjs');",
@@ -3636,13 +3647,13 @@
"name": "skill-template.ts",
"kind": "file",
"path": "src/claude/skill-template.ts",
- "span": "L1-L77",
+ "span": "L1-L89",
"signature": null,
"exported": true,
"origin": "ast",
- "body_hash": "4e951868562ef41f827b4828dc1931cf1e645d2e57999308b1919f62de5af7fb",
- "chars": 4071,
- "summary_state": "ready",
+ "body_hash": "7fab95031aad5a0e84d156d9d12915d4bb7a9206dada3b165961f690a8a64959",
+ "chars": 4886,
+ "summary_state": "stale",
"summary": "Provides a structured template for the graft Claude Code skill, enabling efficient onboarding and understanding of the codebase.",
"crux": {
"code": "export function skillTemplate(): string {\n return `---\nname: graft\ndescription: This repo is indexed by graft/. For ANY task here — understanding\n how something works, finding where code lives, or scoping a change — get your\n context from graft before grepping or reading source files.\n---\n\n# graft\n\nThis repo's code is summarised in \\`graft/\\` — small markdown nodes, each\nexplaining one part in plain prose and naming the exact files and line-spans it",
@@ -3654,12 +3665,12 @@
"name": "skillTemplate",
"kind": "function",
"path": "src/claude/skill-template.ts",
- "span": "L6-L76",
+ "span": "L6-L88",
"signature": "function skillTemplate(): string",
"exported": true,
"origin": "ast",
- "body_hash": "a556c949cf0d4da9758a04f07d3a0d2ba7b7630e947aca38bdaad8430ee73a2f",
- "summary_state": "ready",
+ "body_hash": "8fa3af192bbb3c84e067e76616f505171a08423428fab288be889b2c17999534",
+ "summary_state": "stale",
"summary": "Generates a markdown string that serves as a comprehensive guide for using the graft tool effectively within a code repository.",
"crux": {
"code": "export function skillTemplate(): string {\n return `---\nname: graft\ndescription: This repo is indexed by graft/. For ANY task here — understanding\n how something works, finding where code lives, or scoping a change — get your\n context from graft before grepping or reading source files.\n---\n\n# graft\n\nThis repo's code is summarised in \\`graft/\\` — small markdown nodes, each\nexplaining one part in plain prose and naming the exact files and line-spans it",
@@ -4448,9 +4459,9 @@
"signature": null,
"exported": true,
"origin": "ast",
- "body_hash": "2c7acb076bd022635defd0b67c5358edd3b662328050be6c2d976e6baa17fc9c",
- "chars": 19746,
- "summary_state": "ready",
+ "body_hash": "e65431a2048d2659ae9c3faaa4b5e101d85f48f80fd3a8607276259e87000b67",
+ "chars": 19707,
+ "summary_state": "stale",
"summary": "Defines the command-line interface for the graft tool, enabling various operations on the codebase's context graph.",
"crux": {
"code": "program\n .name(\"graft\")\n .description(\"Build a repo's context graph as linked markdown, and keep it in sync with the code.\")",
@@ -4462,7 +4473,7 @@
"name": "cliConfig",
"kind": "function",
"path": "src/cli.ts",
- "span": "L57-L66",
+ "span": "L58-L67",
"signature": "function cliConfig(): EngineConfig",
"exported": false,
"origin": "ast",
@@ -4479,7 +4490,7 @@
"name": "engineFrom",
"kind": "function",
"path": "src/cli.ts",
- "span": "L68-L70",
+ "span": "L69-L71",
"signature": "function engineFrom(): Graft",
"exported": false,
"origin": "ast",
@@ -4496,7 +4507,7 @@
"name": "fmt",
"kind": "function",
"path": "src/cli.ts",
- "span": "L106-L110",
+ "span": "L107-L111",
"signature": "fmt = (o: Record<string, number>)",
"exported": false,
"origin": "ast",
@@ -4513,7 +4524,7 @@
"name": "GlobalOpts",
"kind": "interface",
"path": "src/cli.ts",
- "span": "L48-L54",
+ "span": "L49-L55",
"signature": "interface GlobalOpts",
"exported": false,
"origin": "ast",
@@ -4522,23 +4533,6 @@
"summary": "Holds the global options for the CLI, allowing configuration of the context graph generation and LLM provider settings.",
"crux": null
},
- {
- "id": "src/cli.ts#traverseAction",
- "name": "traverseAction",
- "kind": "function",
- "path": "src/cli.ts",
- "span": "L287-L293",
- "signature": "function traverseAction(kind: import(\"./graph/traverse-cli.js\").TraverseKind)",
- "exported": false,
- "origin": "ast",
- "body_hash": "22a87797c4d09df4b6dcf4876910653663d7e7968bc0c19e90dc77a9a3d675b4",
- "summary_state": "ready",
- "summary": "Handles traversal commands for graph analysis, allowing users to query relationships between symbols in the codebase.",
- "crux": {
- "code": " return async (symbol: string, dir: string, opts: { in?: string; json?: boolean; depth?: string }) => {\n const { runTraverseCommand } = await import(\"./graph/traverse-cli.js\");\n const globalOpts = program.opts<{ dir?: string }>();\n runTraverseCommand(kind, symbol, dir, { in: opts.in, json: opts.json, depth: opts.depth, globalDir: globalOpts.dir });\n };",
- "span": "L288-L292"
- }
- },
{
"id": "src/context/build.ts",
"name": "build.ts",
@@ -5250,6 +5244,91 @@
"span": "L158-L169"
}
},
+ {
+ "id": "src/context/savings.ts",
+ "name": "savings.ts",
+ "kind": "file",
+ "path": "src/context/savings.ts",
+ "span": "L1-L73",
+ "signature": null,
+ "exported": true,
+ "origin": "ast",
+ "body_hash": "ff8cc5330d8d1ac27285e75ce1b87852fb3c91d3909ddd392cd0458dbd5bf7e6",
+ "chars": 3101,
+ "summary_state": "pending",
+ "summary": null,
+ "crux": null
+ },
+ {
+ "id": "src/context/savings.ts#fileSizes",
+ "name": "fileSizes",
+ "kind": "function",
+ "path": "src/context/savings.ts",
+ "span": "L32-L37",
+ "signature": "function fileSizes(graph: GraphV1): Map<string, number>",
+ "exported": false,
+ "origin": "ast",
+ "body_hash": "cf86e222b98ca1b1598d640d52714b647757eeaf60e5b42e1ef2fd203e138ca2",
+ "summary_state": "pending",
+ "summary": null,
+ "crux": null
+ },
+ {
+ "id": "src/context/savings.ts#Savings",
+ "name": "Savings",
+ "kind": "interface",
+ "path": "src/context/savings.ts",
+ "span": "L17-L22",
+ "signature": "interface Savings",
+ "exported": true,
+ "origin": "ast",
+ "body_hash": "0c0a753f5e797f72b421f7bd766396ef4e84b440d5080497187820d907b2690a",
+ "summary_state": "pending",
+ "summary": null,
+ "crux": null
+ },
+ {
+ "id": "src/context/savings.ts#savingsFooter",
+ "name": "savingsFooter",
+ "kind": "function",
+ "path": "src/context/savings.ts",
+ "span": "L60-L72",
+ "signature": "function savingsFooter(body: string, saved: Savings | undefined): string",
+ "exported": true,
+ "origin": "ast",
+ "body_hash": "a52162795bb01ef973dded780df072bf49a5c03e5823baed4d4bc1cefd0c82ae",
+ "summary_state": "pending",
+ "summary": null,
+ "crux": null
+ },
+ {
+ "id": "src/context/savings.ts#savingsFor",
+ "name": "savingsFor",
+ "kind": "function",
+ "path": "src/context/savings.ts",
+ "span": "L42-L53",
+ "signature": "function savingsFor(graph: GraphV1, paths: Iterable<string>): Savings | undefined",
+ "exported": true,
+ "origin": "ast",
+ "body_hash": "4fcc66724fcb55e23fff7e019707b7b7148fb41f635d3b3b5209c48e0a32a658",
+ "summary_state": "pending",
+ "summary": null,
+ "crux": null
+ },
+ {
+ "id": "src/context/savings.ts#toTokens",
+ "name": "toTokens",
+ "kind": "function",
+ "path": "src/context/savings.ts",
+ "span": "L25-L27",
+ "signature": "function toTokens(chars: number): number",
+ "exported": true,
+ "origin": "ast",
+ "body_hash": "c309fa8bd0227742b657331eb45be3225e5a5efc56b1967871624df6c83ab954",
+ "summary_state": "pending",
+ "summary": null,
+ "crux": null
+ },
{
"id": "src/engine.ts",
"name": "engine.ts",
@@ -6934,13 +7013,13 @@
"name": "map.ts",
"kind": "file",
"path": "src/graph/map.ts",
- "span": "L1-L224",
+ "span": "L1-L230",
"signature": null,
"exported": true,
"origin": "ast",
- "body_hash": "aa982e0a06ce4e8d3af76cec5847846d495f36ace8835fe6bf70805429346ffd",
- "chars": 8087,
- "summary_state": "ready",
+ "body_hash": "c93bf89e679f77c233199627c448e960659722a95ab91f0f1938ebb318201c9a",
+ "chars": 8433,
+ "summary_state": "stale",
"summary": "Builds a structured representation of a repository's file and symbol organization based on their relationships, facilitating easier navigation and understanding of the codebase.",
"crux": {
"code": "export function buildRepoMap(graph: GraphV1, opts: BuildRepoMapOptions = {}): RepoMap {\n const maxDirs = opts.maxDirs ?? DEFAULT_MAX_DIRS;\n const hubsPerDir = opts.hubsPerDir ?? DEFAULT_HUBS_PER_DIR;\n const hotspotsN = opts.hotspots ?? DEFAULT_HOTSPOTS;\n\n const fileNodes = graph.nodes.filter((n) => n.kind === \"file\");\n const totalFiles = fileNodes.length;\n\n // Pass 1: depth-1 file counts, to find (at most one) group over the\n // split threshold — two groups can't both exceed 60% of the same total.\n const depth1FileCounts = new Map<string, number>();\n for (const n of fileNodes) {",
@@ -6952,7 +7031,7 @@
"name": "basenameOf",
"kind": "function",
"path": "src/graph/map.ts",
- "span": "L184-L187",
+ "span": "L189-L192",
"signature": "function basenameOf(path: string): string",
"exported": false,
"origin": "ast",
@@ -6969,12 +7048,12 @@
"name": "buildRepoMap",
"kind": "function",
"path": "src/graph/map.ts",
- "span": "L112-L180",
+ "span": "L116-L185",
"signature": "function buildRepoMap(graph: GraphV1, opts: BuildRepoMapOptions = {}): RepoMap",
"exported": true,
"origin": "ast",
- "body_hash": "c66c141b16315640a81aa5795d073aea7f842de00309186def0f0008e8bfd6af",
- "summary_state": "ready",
+ "body_hash": "91692bf83bf7d1ae520baa1ba803c76f9d8d5c06ef684824445da7a25d2800b3",
+ "summary_state": "stale",
"summary": "Constructs the repository map from a given graph, organizing files and symbols into a structured format for easy access.",
"crux": {
"code": "export function buildRepoMap(graph: GraphV1, opts: BuildRepoMapOptions = {}): RepoMap {\n const maxDirs = opts.maxDirs ?? DEFAULT_MAX_DIRS;\n const hubsPerDir = opts.hubsPerDir ?? DEFAULT_HUBS_PER_DIR;\n const hotspotsN = opts.hotspots ?? DEFAULT_HOTSPOTS;\n\n const fileNodes = graph.nodes.filter((n) => n.kind === \"file\");\n const totalFiles = fileNodes.length;\n\n // Pass 1: depth-1 file counts, to find (at most one) group over the\n // split threshold — two groups can't both exceed 60% of the same total.\n const depth1FileCounts = new Map<string, number>();\n for (const n of fileNodes) {",
@@ -6986,7 +7065,7 @@
"name": "depthFor",
"kind": "function",
"path": "src/graph/map.ts",
- "span": "L137-L137",
+ "span": "L141-L141",
"signature": "depthFor = (path: string): number",
"exported": true,
"origin": "ast",
@@ -7003,7 +7082,7 @@
"name": "BuildRepoMapOptions",
"kind": "interface",
"path": "src/graph/map.ts",
- "span": "L51-L58",
+ "span": "L55-L62",
"signature": "interface BuildRepoMapOptions",
"exported": true,
"origin": "ast",
@@ -7020,7 +7099,7 @@
"name": "computeInDegree",
"kind": "function",
"path": "src/graph/map.ts",
- "span": "L78-L85",
+ "span": "L82-L89",
"signature": "function computeInDegree(graph: GraphV1): Map<string, number>",
"exported": false,
"origin": "ast",
@@ -7037,7 +7116,7 @@
"name": "DirEntry",
"kind": "interface",
"path": "src/graph/map.ts",
- "span": "L33-L39",
+ "span": "L34-L40",
"signature": "interface DirEntry",
"exported": true,
"origin": "ast",
@@ -7054,7 +7133,7 @@
"name": "dirKey",
"kind": "function",
"path": "src/graph/map.ts",
- "span": "L70-L73",
+ "span": "L74-L77",
"signature": "function dirKey(path: string, depth: number): string",
"exported": false,
"origin": "ast",
@@ -7071,7 +7150,7 @@
"name": "formatDirHub",
"kind": "function",
"path": "src/graph/map.ts",
- "span": "L189-L191",
+ "span": "L194-L196",
"signature": "function formatDirHub(h: Hub): string",
"exported": false,
"origin": "ast",
@@ -7088,7 +7167,7 @@
"name": "formatDirLine",
"kind": "function",
"path": "src/graph/map.ts",
- "span": "L193-L198",
+ "span": "L198-L203",
"signature": "function formatDirLine(d: DirEntry): string",
"exported": false,
"origin": "ast",
@@ -7105,7 +7184,7 @@
"name": "formatHotspot",
"kind": "function",
"path": "src/graph/map.ts",
- "span": "L200-L202",
+ "span": "L205-L207",
"signature": "function formatHotspot(h: Hub): string",
"exported": false,
"origin": "ast",
@@ -7122,12 +7201,12 @@
"name": "formatRepoMap",
"kind": "function",
"path": "src/graph/map.ts",
- "span": "L210-L223",
+ "span": "L215-L229",
"signature": "function formatRepoMap(map: RepoMap): string",
"exported": true,
"origin": "ast",
- "body_hash": "ff6f40dcbf4f3a67393e3322642d103b5f68f05b209276a8b74247e219560f1f",
- "summary_state": "ready",
+ "body_hash": "4185b84957995879f7e9af4efe0a295ca215b8e0c725f0a25ee4fb80bfcff8ea",
+ "summary_state": "stale",
"summary": "Renders the repository map as a human-readable string, summarizing its contents and structure for easy understanding.",
"crux": {
"code": "export function formatRepoMap(map: RepoMap): string {\n const { totals } = map;\n const header = `repo map — ${totals.files} files · ${totals.symbols} symbols · ${totals.edges} edges · ${totals.languages.join(\", \")}`;\n\n const lines: string[] = [header, \"\"];\n for (const d of map.dirs) lines.push(formatDirLine(d));\n if (map.dropped > 0) {\n lines.push(`… +${map.dropped} more director${map.dropped === 1 ? \"y\" : \"ies\"} not shown (raise max-dirs to see more)`);\n }\n lines.push(\"\");\n lines.push(`hotspots: ${map.hotspots.map(formatHotspot).join(\" \")}`);\n",
@@ -7139,7 +7218,7 @@
"name": "Hub",
"kind": "interface",
"path": "src/graph/map.ts",
- "span": "L25-L31",
+ "span": "L26-L32",
"signature": "interface Hub",
"exported": true,
"origin": "ast",
@@ -7156,12 +7235,12 @@
"name": "RepoMap",
"kind": "interface",
"path": "src/graph/map.ts",
- "span": "L41-L49",
+ "span": "L42-L53",
"signature": "interface RepoMap",
"exported": true,
"origin": "ast",
- "body_hash": "3086d36e77c71336febddbd8948e49aff8230f0f3ddd37c9e0d02c5063b73f5b",
- "summary_state": "ready",
+ "body_hash": "605e2c9030866aa7c7a6fe59bab94f571f024b59defb53b5aa238f6babddfea2",
+ "summary_state": "stale",
"summary": "Encapsulates the entire repository map structure, providing a comprehensive overview of files, symbols, and their relationships.",
"crux": {
"code": "export interface RepoMap {\n totals: { files: number; symbols: number; edges: number; languages: string[] };\n /** Sorted by symbol count desc (ties by path asc), capped at `maxDirs`. */\n dirs: DirEntry[];\n /** Global top hubs by inDegree, ties by name asc then path asc. */\n hotspots: Hub[];\n /** Directory groups beyond the `maxDirs` cap — never silently dropped. */\n dropped: number;\n}",
@@ -7173,7 +7252,7 @@
"name": "sortedLanguages",
"kind": "function",
"path": "src/graph/map.ts",
- "span": "L98-L105",
+ "span": "L102-L109",
"signature": "function sortedLanguages(paths: string[]): string[]",
"exported": false,
"origin": "ast",
@@ -7190,7 +7269,7 @@
"name": "topHubs",
"kind": "function",
"path": "src/graph/map.ts",
- "span": "L90-L96",
+ "span": "L94-L100",
"signature": "function topHubs(nodes: NodeV1[], inDegree: Map<string, number>, cap: number): Hub[]",
"exported": false,
"origin": "ast",
@@ -7393,13 +7472,13 @@
"name": "traverse-cli.ts",
"kind": "file",
"path": "src/graph/traverse-cli.ts",
- "span": "L1-L156",
+ "span": "L1-L183",
"signature": null,
"exported": true,
"origin": "ast",
- "body_hash": "080714fc91e5caefe4548e87c071b2010fdc593a670366db941d9fd2907b08e2",
- "chars": 5487,
- "summary_state": "ready",
+ "body_hash": "679656c15592b5abec15c01cfedb3f640b1366309724946b30a772b8753b32e5",
+ "chars": 6675,
+ "summary_state": "stale",
"summary": "This file implements CLI commands for traversing a graph to find callers, callees, and impact of symbols, ensuring a consistent user experience across different commands.",
"crux": {
"code": "function edgesFor(kind: TraverseKind, graph: GraphV1, node: NodeV1, depth: number): EdgeHit[] {\n if (kind === \"callers\") return callersOf(graph, node);\n if (kind === \"callees\") return calleesOf(graph, node);\n return impactOf(graph, node, depth);\n}",
@@ -7407,28 +7486,39 @@
}
},
{
- "id": "src/graph/traverse-cli.ts#edgesFor",
- "name": "edgesFor",
+ "id": "src/graph/traverse-cli.ts#CallersCliOptions",
+ "name": "CallersCliOptions",
+ "kind": "interface",
+ "path": "src/graph/traverse-cli.ts",
+ "span": "L21-L30",
+ "signature": "interface CallersCliOptions",
+ "exported": true,
+ "origin": "ast",
+ "body_hash": "b9bdee3683e8728ac1c920a050958fd8c63c7b7dc64ae1a59ceb3b31bcfd62c6",
+ "summary_state": "pending",
+ "summary": null,
+ "crux": null
+ },
+ {
+ "id": "src/graph/traverse-cli.ts#callersSavings",
+ "name": "callersSavings",
"kind": "function",
"path": "src/graph/traverse-cli.ts",
- "span": "L31-L35",
- "signature": "function edgesFor(kind: TraverseKind, graph: GraphV1, node: NodeV1, depth: number): EdgeHit[]",
- "exported": false,
+ "span": "L55-L65",
+ "signature": "function callersSavings( graph: GraphV1, results: { symbol: NodeV1; hits: EdgeHit[] }[], ): Savings | undefined",
+ "exported": true,
"origin": "ast",
- "body_hash": "0cba9677135c955d5db241232c49e8a076f471de306cbbe19cc540c3c02255a5",
- "summary_state": "ready",
- "summary": "Determines the edges to traverse in the graph based on the specified kind, facilitating the retrieval of relevant connections for a node.",
- "crux": {
- "code": "function edgesFor(kind: TraverseKind, graph: GraphV1, node: NodeV1, depth: number): EdgeHit[] {\n if (kind === \"callers\") return callersOf(graph, node);\n if (kind === \"callees\") return calleesOf(graph, node);\n return impactOf(graph, node, depth);",
- "span": "L31-L34"
- }
+ "body_hash": "ebeebed400044ce3b14a43e1e5160325046e715b0e460c97510c0ebab593f5df",
+ "summary_state": "pending",
+ "summary": null,
+ "crux": null
},
{
"id": "src/graph/traverse-cli.ts#headerOf",
"name": "headerOf",
"kind": "function",
"path": "src/graph/traverse-cli.ts",
- "span": "L41-L43",
+ "span": "L38-L40",
"signature": "function headerOf(n: NodeV1): string",
"exported": true,
"origin": "ast",
@@ -7445,7 +7535,7 @@
"name": "hitJson",
"kind": "function",
"path": "src/graph/traverse-cli.ts",
- "span": "L88-L97",
+ "span": "L102-L111",
"signature": "function hitJson(hit: EdgeHit): HitJson",
"exported": false,
"origin": "ast",
@@ -7462,7 +7552,7 @@
"name": "HitJson",
"kind": "interface",
"path": "src/graph/traverse-cli.ts",
- "span": "L74-L82",
+ "span": "L88-L96",
"signature": "interface HitJson",
"exported": false,
"origin": "ast",
@@ -7476,12 +7566,12 @@
"name": "hitLine",
"kind": "function",
"path": "src/graph/traverse-cli.ts",
- "span": "L45-L50",
- "signature": "function hitLine(kind: TraverseKind, hit: EdgeHit): string",
+ "span": "L44-L49",
+ "signature": "function hitLine(direction: Direction, hit: EdgeHit, showDepth: boolean): string",
"exported": true,
"origin": "ast",
- "body_hash": "76918dc9bd348cc7c19fdf778ccb604a9d1e9123167d71979c83c477df61d026",
- "summary_state": "ready",
+ "body_hash": "a87b7edebb9ea1bb174c1439e0de0d80e9f56d692bd54f9a313cb27521abbfec",
+ "summary_state": "stale",
"summary": "Formats a single hit line for display, showing the relationship and details of a node in the context of the traversal.",
"crux": {
"code": "export function hitLine(kind: TraverseKind, hit: EdgeHit): string {\n const arrow = ARROW[kind];\n const depthTag = kind === \"impact\" ? ` [depth ${hit.depth}]` : \"\";\n const label = hit.node ? `${hit.node.name} (${hit.node.path}:${hit.node.span})` : `${hit.id} (unresolved import)`;\n return ` ${hit.relation} ${arrow} ${label}${depthTag}`;\n}",
@@ -7493,12 +7583,12 @@
"name": "looseNoteFor",
"kind": "function",
"path": "src/graph/traverse-cli.ts",
- "span": "L54-L58",
- "signature": "function looseNoteFor(kind: TraverseKind, name: string): string",
+ "span": "L68-L72",
+ "signature": "function looseNoteFor(direction: Direction, name: string): string",
"exported": true,
"origin": "ast",
- "body_hash": "7b7f3eefe60c81c8c2e4026e5c3237c9a33ff5ce6076535787d52b45dd3adcd5",
- "summary_state": "ready",
+ "body_hash": "99056d32295a0aae85f994c7a4c161a7978cde0784d02f1b5fe71fed4b1d5534",
+ "summary_state": "stale",
"summary": "Creates a user-friendly message when no edges are found for a symbol, guiding users on next steps.",
"crux": {
"code": "export function looseNoteFor(kind: TraverseKind, name: string): string {\n const label = kind === \"callees\" ? \"callees\" : \"callers\";\n const direction = kind === \"callees\" ? \"outgoing\" : \"incoming\";\n return ` no indexed ${label} — the graph has no ${direction} call/reference edges for this symbol; try grep -rn \"${name}\"`;\n}",
@@ -7510,7 +7600,7 @@
"name": "MatchJson",
"kind": "interface",
"path": "src/graph/traverse-cli.ts",
- "span": "L68-L72",
+ "span": "L82-L86",
"signature": "interface MatchJson",
"exported": false,
"origin": "ast",
@@ -7520,28 +7610,39 @@
"crux": null
},
{
- "id": "src/graph/traverse-cli.ts#runTraverseCommand",
- "name": "runTraverseCommand",
+ "id": "src/graph/traverse-cli.ts#resolveDirection",
+ "name": "resolveDirection",
"kind": "function",
"path": "src/graph/traverse-cli.ts",
- "span": "L105-L155",
- "signature": "function runTraverseCommand(kind: TraverseKind, query: string, dir: string, opts: TraverseCliOptions): void",
+ "span": "L114-L119",
+ "signature": "function resolveDirection(raw: string | undefined): Direction",
+ "exported": false,
+ "origin": "ast",
+ "body_hash": "807b24d3052edc03c2f217c2a11927bc76a3e1f6000ae35d5fd85f53bb1ee1a0",
+ "summary_state": "pending",
+ "summary": null,
+ "crux": null
+ },
+ {
+ "id": "src/graph/traverse-cli.ts#runCallersCommand",
+ "name": "runCallersCommand",
+ "kind": "function",
+ "path": "src/graph/traverse-cli.ts",
+ "span": "L127-L182",
+ "signature": "function runCallersCommand(query: string, dir: string, opts: CallersCliOptions): void",
"exported": true,
"origin": "ast",
- "body_hash": "166ca03408bcfd5c0f8deac25be0afbf85b3ea1f99d143ab3e0c012f48599bb1",
- "summary_state": "ready",
- "summary": "Executes the traversal command based on user input, handling graph resolution and output formatting, while managing errors effectively.",
- "crux": {
- "code": "export function runTraverseCommand(kind: TraverseKind, query: string, dir: string, opts: TraverseCliOptions): void {\n const root = resolve(dir);\n const contextDir = contextDirFor(root, opts.globalDir);\n const graph = loadGraphCached(contextDir);\n if (!graph) {\n console.error(`✗ no graph found at ${contextDir} — run \\`graft build\\` first`);\n process.exit(1);\n }\n\n const matches = resolveSymbol(graph, query, opts.in ? { in: opts.in } : {});\n if (matches.length === 0) {\n console.error(`✗ no symbol \"${query}\" in the graph — check spelling or run graft build`);",
- "span": "L105-L116"
- }
+ "body_hash": "b2c975fdf09ac0c9efac3210c1d8b8e8a36f598ee0b94a5b278f56cd9e369daa",
+ "summary_state": "pending",
+ "summary": null,
+ "crux": null
},
{
"id": "src/graph/traverse-cli.ts#symbolJson",
"name": "symbolJson",
"kind": "function",
"path": "src/graph/traverse-cli.ts",
- "span": "L84-L86",
+ "span": "L98-L100",
"signature": "function symbolJson(n: NodeV1): SymbolJson",
"exported": false,
"origin": "ast",
@@ -7558,7 +7659,7 @@
"name": "SymbolJson",
"kind": "interface",
"path": "src/graph/traverse-cli.ts",
- "span": "L60-L66",
+ "span": "L74-L80",
"signature": "interface SymbolJson",
"exported": false,
"origin": "ast",
@@ -7567,46 +7668,18 @@
"summary": "Defines the structure for symbol metadata in JSON format, ensuring consistent representation of symbols in output.",
"crux": null
},
- {
- "id": "src/graph/traverse-cli.ts#TraverseCliOptions",
- "name": "TraverseCliOptions",
- "kind": "interface",
- "path": "src/graph/traverse-cli.ts",
- "span": "L19-L26",
- "signature": "interface TraverseCliOptions",
- "exported": true,
- "origin": "ast",
- "body_hash": "81222f4fc4c9c9d285bd325a0e77f451c77b0f8465314cab9438111230c4d997",
- "summary_state": "ready",
- "summary": "Specifies options for the CLI traversal commands, allowing customization of input, output format, and traversal depth.",
- "crux": null
- },
- {
- "id": "src/graph/traverse-cli.ts#TraverseKind",
- "name": "TraverseKind",
- "kind": "type",
- "path": "src/graph/traverse-cli.ts",
- "span": "L17-L17",
- "signature": "type TraverseKind = \"callers\" | \"callees\" | \"impact\";",
- "exported": true,
- "origin": "ast",
- "body_hash": "324cf2d7939c64ad6d957bf858d25acb5b665dbe40de99d3a22e5c4741d309c4",
- "summary_state": "ready",
- "summary": "Defines the types of traversal operations available for graph navigation, ensuring type safety in CLI commands.",
- "crux": null
- },
{
"id": "src/graph/traverse.ts",
"name": "traverse.ts",
"kind": "file",
"path": "src/graph/traverse.ts",
- "span": "L1-L192",
+ "span": "L1-L223",
"signature": null,
"exported": true,
"origin": "ast",
- "body_hash": "dd38bef08a175c1db6751823f7f6f1eaae3952227737b063373987f69c52d7fa",
- "chars": 8004,
- "summary_state": "ready",
+ "body_hash": "cf349716f93ae52c79c61935dea060babe111216563d7c308c8375a8aaed698e",
+ "chars": 9750,
+ "summary_state": "stale",
"summary": "Centralizes the logic for resolving symbol queries in a graph, enabling consistent identification of nodes based on various naming conventions and paths.",
"crux": {
"code": " */\nexport function resolveSymbol(graph: GraphV1, query: string, opts: ResolveSymbolOptions = {}): NodeV1[] {\n const lowerQuery = query.toLowerCase();\n const looksLikeFilename = query.includes(\".\") && !query.includes(\"#\");\n\n let matches = symbolMatches(graph.nodes, lowerQuery);\n\n if (matches.length === 0 && query.includes(\".\")) {\n const lastSegment = query.slice(query.lastIndexOf(\".\") + 1).toLowerCase();\n if (lastSegment) {\n matches = graph.nodes.filter((n) => n.kind !== \"file\" && n.name.toLowerCase() === lastSegment);\n }",
@@ -7618,7 +7691,7 @@
"name": "calleesOf",
"kind": "function",
"path": "src/graph/traverse.ts",
- "span": "L107-L115",
+ "span": "L113-L121",
"signature": "function calleesOf(graph: GraphV1, symbol: NodeV1): EdgeHit[]",
"exported": true,
"origin": "ast",
@@ -7635,7 +7708,7 @@
"name": "callersOf",
"kind": "function",
"path": "src/graph/traverse.ts",
- "span": "L96-L104",
+ "span": "L102-L110",
"signature": "function callersOf(graph: GraphV1, symbol: NodeV1): EdgeHit[]",
"exported": true,
"origin": "ast",
@@ -7647,12 +7720,26 @@
"span": "L96-L103"
}
},
+ {
+ "id": "src/graph/traverse.ts#Direction",
+ "name": "Direction",
+ "kind": "type",
+ "path": "src/graph/traverse.ts",
+ "span": "L21-L21",
+ "signature": "type Direction = \"in\" | \"out\";",
+ "exported": true,
+ "origin": "ast",
+ "body_hash": "48667bce4f305c7050d7914dd04e31e7db5fd8cbf7e79d19e426f7a8db04c886",
+ "summary_state": "pending",
+ "summary": null,
+ "crux": null
+ },
{
"id": "src/graph/traverse.ts#EdgeHit",
"name": "EdgeHit",
"kind": "interface",
"path": "src/graph/traverse.ts",
- "span": "L88-L93",
+ "span": "L94-L99",
"signature": "interface EdgeHit",
"exported": true,
"origin": "ast",
@@ -7664,12 +7751,26 @@
"span": "L88-L93"
}
},
+ {
+ "id": "src/graph/traverse.ts#edgeWalk",
+ "name": "edgeWalk",
+ "kind": "function",
+ "path": "src/graph/traverse.ts",
+ "span": "L218-L222",
+ "signature": "function edgeWalk(graph: GraphV1, node: NodeV1, direction: Direction, depth: number): EdgeHit[]",
+ "exported": true,
+ "origin": "ast",
+ "body_hash": "28792965a036b184ee16e13d0f5dcd144afd62f7e4cb35d7004e86cf58a475b4",
+ "summary_state": "pending",
+ "summary": null,
+ "crux": null
+ },
{
"id": "src/graph/traverse.ts#impactOf",
"name": "impactOf",
"kind": "function",
"path": "src/graph/traverse.ts",
- "span": "L123-L125",
+ "span": "L129-L131",
"signature": "function impactOf(graph: GraphV1, symbol: NodeV1, maxDepth = 2): EdgeHit[]",
"exported": true,
"origin": "ast",
@@ -7686,12 +7787,12 @@
"name": "impactOfFile",
"kind": "function",
"path": "src/graph/traverse.ts",
- "span": "L189-L191",
- "signature": "function impactOfFile(graph: GraphV1, fileNode: NodeV1, maxDepth = 2): EdgeHit[]",
+ "span": "L201-L203",
+ "signature": "function impactOfFile(graph: GraphV1, fileNode: NodeV1, maxDepth = 2, direction: Direction = \"in\"): EdgeHit[]",
"exported": true,
"origin": "ast",
- "body_hash": "37bb8999dd4c8486366d90c974d9d7161a40dc6a42508927b5befbc19a1b923d",
- "summary_state": "ready",
+ "body_hash": "eafa282969956ae0ecae5ba75238424a8b3e7c91e3d45ce6cf1b8f1c43380829",
+ "summary_state": "stale",
"summary": "Aggregates the impact analysis for a file node and its defined symbols, ensuring all dependents are considered.",
"crux": {
"code": "export function impactOfFile(graph: GraphV1, fileNode: NodeV1, maxDepth = 2): EdgeHit[] {\n return impactOfMany(graph, [fileNode, ...symbolsInFile(graph, fileNode)], maxDepth);\n}",
@@ -7703,12 +7804,12 @@
"name": "impactOfMany",
"kind": "function",
"path": "src/graph/traverse.ts",
- "span": "L141-L172",
- "signature": "function impactOfMany(graph: GraphV1, seeds: NodeV1[], maxDepth = 2): EdgeHit[]",
+ "span": "L149-L184",
+ "signature": "function impactOfMany(graph: GraphV1, seeds: NodeV1[], maxDepth = 2, direction: Direction = \"in\"): EdgeHit[]",
"exported": true,
"origin": "ast",
- "body_hash": "bd8d064833fa0679633b8c4d662761e243c0d78a5dd31c60d3f49c613000353a",
- "summary_state": "ready",
+ "body_hash": "ed0429a5e6283a3a65470de4599a5b11ee48fbc54e8a63c3e8bef942d5e75c40",
+ "summary_state": "stale",
"summary": "Generalizes the impact analysis to multiple seed nodes, aggregating the results of their incoming edges.",
"crux": {
"code": "export function impactOfMany(graph: GraphV1, seeds: NodeV1[], maxDepth = 2): EdgeHit[] {\n const byId = new Map(graph.nodes.map((n) => [n.id, n]));\n\n // target id → incoming {source, relation} pairs, restricted to walk relations.\n const incoming = new Map<string, { source: string; relation: Relation }[]>();\n for (const e of graph.edges as EdgeV1[]) {\n if (!WALK_RELATIONS.has(e.relation)) continue;\n const arr = incoming.get(e.target);\n const entry = { source: e.source, relation: e.relation };\n if (arr) arr.push(entry);\n else incoming.set(e.target, [entry]);\n }",
@@ -7720,7 +7821,7 @@
"name": "resolveSymbol",
"kind": "function",
"path": "src/graph/traverse.ts",
- "span": "L47-L72",
+ "span": "L53-L78",
"signature": "function resolveSymbol(graph: GraphV1, query: string, opts: ResolveSymbolOptions = {}): NodeV1[]",
"exported": true,
"origin": "ast",
@@ -7737,7 +7838,7 @@
"name": "ResolveSymbolOptions",
"kind": "interface",
"path": "src/graph/traverse.ts",
- "span": "L23-L26",
+ "span": "L29-L32",
"signature": "interface ResolveSymbolOptions",
"exported": true,
"origin": "ast",
@@ -7754,7 +7855,7 @@
"name": "SymbolMatch",
"kind": "interface",
"path": "src/graph/traverse.ts",
- "span": "L19-L21",
+ "span": "L25-L27",
"signature": "interface SymbolMatch",
"exported": true,
"origin": "ast",
@@ -7771,7 +7872,7 @@
"name": "symbolMatches",
"kind": "function",
"path": "src/graph/traverse.ts",
- "span": "L74-L83",
+ "span": "L80-L89",
"signature": "function symbolMatches(nodes: NodeV1[], lowerQuery: string): NodeV1[]",
"exported": false,
"origin": "ast",
@@ -7788,7 +7889,7 @@
"name": "symbolsInFile",
"kind": "function",
"path": "src/graph/traverse.ts",
- "span": "L176-L178",
+ "span": "L188-L190",
"signature": "function symbolsInFile(graph: GraphV1, fileNode: NodeV1): NodeV1[]",
"exported": false,
"origin": "ast",
@@ -8245,13 +8346,13 @@
"name": "instructions.ts",
"kind": "file",
"path": "src/hosts/instructions.ts",
- "span": "L1-L65",
+ "span": "L1-L66",
"signature": null,
"exported": true,
"origin": "ast",
- "body_hash": "1dddea660f4d5e65952faf2beee42f04153ccab893658e75bda1dce6c0245b18",
- "chars": 2627,
- "summary_state": "ready",
+ "body_hash": "17afda3d983ab46e0329ed7e4e781e361265578ee99fcf9ab8cd4228b8b5f3c5",
+ "chars": 2647,
+ "summary_state": "stale",
"summary": "This file provides Graft instructions for navigating and utilizing the context graph effectively.",
"crux": null
},
@@ -8260,7 +8361,7 @@
"name": "cursorRule",
"kind": "function",
"path": "src/hosts/instructions.ts",
- "span": "L44-L51",
+ "span": "L45-L52",
"signature": "function cursorRule(): string",
"exported": true,
"origin": "ast",
@@ -8277,12 +8378,12 @@
"name": "instructionBody",
"kind": "function",
"path": "src/hosts/instructions.ts",
- "span": "L6-L42",
+ "span": "L6-L43",
"signature": "function instructionBody(): string",
"exported": true,
"origin": "ast",
- "body_hash": "9003c83453867680b4936696a28bb8086e14e432bb3c3debc4d7e5ab5ab7a0be",
- "summary_state": "ready",
+ "body_hash": "dc7ccce561fcd4c23d60739f2538908fbf5ff0fcb4205bfbdae4ea61ee7c5f80",
+ "summary_state": "stale",
"summary": "Generates the main instructional content for using the Graft context graph.",
"crux": {
"code": "export function instructionBody(): string {\n return `## Graft — repo context graph\n\nThis repo is indexed in \\`graft/\\`: small linked markdown nodes that explain each\nsystem and carry exact file:line spans, kept in sync with the code through git.\n\nFor ANY task here — understanding how something works, finding where code lives,\nor scoping a change — get context from the graph before grepping or opening\nsource files. Re-ask freely (it's cheap) and reuse literal identifiers you\nalready have (symbol, error string, file name) as the query. New to this repo?\nRun \\`graft map\\` first — a token-budgeted orientation (dir clusters, hubs,\nhotspots), no LLM, no key.",
@@ -8294,7 +8395,7 @@
"name": "kiroSteering",
"kind": "function",
"path": "src/hosts/instructions.ts",
- "span": "L53-L59",
+ "span": "L54-L60",
"signature": "function kiroSteering(): string",
"exported": true,
"origin": "ast",
@@ -8311,7 +8412,7 @@
"name": "windsurfRule",
"kind": "function",
"path": "src/hosts/instructions.ts",
- "span": "L61-L64",
+ "span": "L62-L65",
"signature": "function windsurfRule(): string",
"exported": true,
"origin": "ast",
@@ -8332,9 +8433,9 @@
"signature": null,
"exported": true,
"origin": "ast",
- "body_hash": "c3a3dea18371806ed352e7cab582265db2341b7d4ea5797578e495b512a9b0b3",
- "chars": 3338,
- "summary_state": "ready",
+ "body_hash": "a449aa6fea8dc1b842e565d9c60fb61e46343effe69c1064a758c31d30cd5329",
+ "chars": 3352,
+ "summary_state": "stale",
"summary": "Facilitates the registration and configuration of multiple MCP servers in specified host configurations, ensuring proper JSON and TOML formatting.",
"crux": {
"code": "export function registerMcpConfigs(\n repo: string,\n ids: string[],\n opts: { home?: string } = {},\n): McpWrite[] {\n const home = opts.home ?? homedir();\n const out: McpWrite[] = [];\n for (const id of ids) {\n switch (id) {\n case 'cursor':\n out.push(mergeJsonKey(id, join(repo, '.cursor', 'mcp.json'), 'mcpServers', SERVER_ENTRY));\n break;",
@@ -8382,7 +8483,7 @@
"path": "src/hosts/mcp-config.ts",
"span": "L23-L43",
"signature": "function mergeJsonKey(id: string, path: string, topKey: string, entry: object): McpWrite",
- "exported": false,
+ "exported": true,
"origin": "ast",
"body_hash": "e399dc21ae5ece8ec15889555e73360fb028691ac71f96255de36ae942b6707d",
"summary_state": "ready",
@@ -8758,12 +8859,12 @@
"name": "tools.ts",
"kind": "file",
"path": "src/mcp/tools.ts",
- "span": "L1-L243",
+ "span": "L1-L216",
"signature": null,
"exported": true,
"origin": "ast",
- "body_hash": "26d386319a711ec0eb758a2561513dc05e164f2c4d5828b6089b41db2b0a715b",
- "chars": 10847,
+ "body_hash": "aaf51610f56c46c7cd820891375c55e84f2b8f107495801b825b28b29fd0636b",
+ "chars": 9754,
"summary_state": "pending",
"summary": null,
"crux": null
@@ -8773,12 +8874,12 @@
"name": "callTool",
"kind": "function",
"path": "src/mcp/tools.ts",
- "span": "L149-L242",
+ "span": "L134-L215",
"signature": "function callTool( root: string, name: string, args: Record<string, unknown>, dirOverride?: string, ): { text: string; isError: boolean }",
"exported": true,
"origin": "ast",
- "body_hash": "ff7c769fef542a2ef86fd774fd9ad72aee3dc1745d295a675c530f76c530dab2",
- "summary_state": "ready",
+ "body_hash": "c9755bbd18f707188f094406f20f4d54b7d762683ed9561bd0b7cfc729932791",
+ "summary_state": "stale",
"summary": "Handles the invocation of various tools based on user input, managing errors and returning formatted results for different graph operations.",
"crux": {
"code": "export function callTool(\n root: string,\n name: string,\n args: Record<string, unknown>,\n dirOverride?: string,\n): { text: string; isError: boolean } {\n try {\n switch (name) {\n case 'graft_ask': {\n const query = String(args.query ?? '');\n if (!query) return { text: 'graft_ask requires a query', isError: true };\n const limit = typeof args.limit === 'number' ? args.limit : 5;",
@@ -8790,12 +8891,12 @@
"name": "renderMatches",
"kind": "function",
"path": "src/mcp/tools.ts",
- "span": "L137-L147",
- "signature": "function renderMatches(kind: TraverseKind, matches: NodeV1[], hitsFor: (n: NodeV1) => EdgeHit[]): string",
+ "span": "L117-L132",
+ "signature": "function renderMatches( direction: Direction, showDepth: boolean, matches: NodeV1[], hitsFor: (n: NodeV1) => EdgeHit[], ): string",
"exported": false,
"origin": "ast",
- "body_hash": "b1fb04cdcb7c8aef1225f590bb7147d80d211ffa478c2f0eec54b33028045d66",
- "summary_state": "ready",
+ "body_hash": "7059bf338ce7e9e88b1ab4bfc452b62fb489c56239322352f8c07b2b2bb42ebc",
+ "summary_state": "stale",
"summary": "Formats and renders the results of graph traversal matches, providing a structured output for users to understand symbol relationships.",
"crux": {
"code": "function renderMatches(kind: TraverseKind, matches: NodeV1[], hitsFor: (n: NodeV1) => EdgeHit[]): string {\n return matches\n .map((m) => {\n const hits = hitsFor(m);\n const lines = [headerOf(m)];\n if (hits.length === 0) lines.push(looseNoteFor(kind, m.name));\n else for (const h of hits) lines.push(hitLine(kind, h));\n return lines.join('\\n');\n })\n .join('\\n\\n');\n}",
@@ -8807,7 +8908,7 @@
"name": "ToolDef",
"kind": "interface",
"path": "src/mcp/tools.ts",
- "span": "L18-L22",
+ "span": "L19-L23",
"signature": "interface ToolDef",
"exported": true,
"origin": "ast",
@@ -8824,7 +8925,7 @@
"name": "unknownSymbolText",
"kind": "function",
"path": "src/mcp/tools.ts",
- "span": "L29-L31",
+ "span": "L27-L29",
"signature": "function unknownSymbolText(query: string): string",
"exported": false,
"origin": "ast",
@@ -8841,13 +8942,13 @@
"name": "grep-cli.ts",
"kind": "file",
"path": "src/search/grep-cli.ts",
- "span": "L1-L113",
+ "span": "L1-L116",
"signature": null,
"exported": true,
"origin": "ast",
- "body_hash": "70bcb32d3ae5e4e9e39eb8b07151da7145a08756015e91f215edcadce5bddef8",
- "chars": 4779,
- "summary_state": "ready",
+ "body_hash": "64dc983c11be49dc755c21f1eb6420adb1ef016077d5e3cc3fe7d5ad82baee78",
+ "chars": 4921,
+ "summary_state": "stale",
"summary": "This file provides the command-line interface for the grep functionality, formatting results for user-friendly output.",
"crux": {
"code": "export function formatGrepResult(result: GrepResult): string {\n const blocks = [formatGrepHeader(result), \"\", ...result.groups.map((g) => formatGroup(g) + \"\\n\")];\n let out = blocks.join(\"\\n\").replace(/\\n+$/, \"\\n\");\n const note = truncationNote(result);\n if (note) out += note + \"\\n\";\n return out;\n}",
@@ -8859,7 +8960,7 @@
"name": "formatGrepHeader",
"kind": "function",
"path": "src/search/grep-cli.ts",
- "span": "L36-L39",
+ "span": "L37-L40",
"signature": "function formatGrepHeader(result: GrepResult): string",
"exported": true,
"origin": "ast",
@@ -8876,12 +8977,12 @@
"name": "formatGrepResult",
"kind": "function",
"path": "src/search/grep-cli.ts",
- "span": "L53-L59",
+ "span": "L54-L62",
"signature": "function formatGrepResult(result: GrepResult): string",
"exported": true,
"origin": "ast",
- "body_hash": "e59d3613490b4b2c02381befb02b8c63946845a5073e7ae13298a4b156f43123",
- "summary_state": "ready",
+ "body_hash": "f8a8198261b13ec5667805d4024024a19adf344fb6a4af500e19bf884e7c6b44",
+ "summary_state": "stale",
"summary": "Compiles the full human-readable report of grep results, including headers and formatted groups.",
"crux": {
"code": "export function formatGrepResult(result: GrepResult): string {\n const blocks = [formatGrepHeader(result), \"\", ...result.groups.map((g) => formatGroup(g) + \"\\n\")];\n let out = blocks.join(\"\\n\").replace(/\\n+$/, \"\\n\");\n const note = truncationNote(result);\n if (note) out += note + \"\\n\";\n return out;\n}",
@@ -8893,7 +8994,7 @@
"name": "formatGroup",
"kind": "function",
"path": "src/search/grep-cli.ts",
- "span": "L29-L33",
+ "span": "L30-L34",
"signature": "function formatGroup(g: GrepGroup): string",
"exported": false,
"origin": "ast",
@@ -8910,7 +9011,7 @@
"name": "GrepCliOptions",
"kind": "interface",
"path": "src/search/grep-cli.ts",
- "span": "L15-L22",
+ "span": "L16-L23",
"signature": "interface GrepCliOptions",
"exported": true,
"origin": "ast",
@@ -8924,7 +9025,7 @@
"name": "groupHeader",
"kind": "function",
"path": "src/search/grep-cli.ts",
- "span": "L24-L27",
+ "span": "L25-L28",
"signature": "function groupHeader(g: GrepGroup): string",
"exported": false,
"origin": "ast",
@@ -8941,7 +9042,7 @@
"name": "runGrepCommand",
"kind": "function",
"path": "src/search/grep-cli.ts",
- "span": "L83-L112",
+ "span": "L86-L115",
"signature": "function runGrepCommand(pattern: string, dir: string, opts: GrepCliOptions): void",
"exported": true,
"origin": "ast",
@@ -8958,7 +9059,7 @@
"name": "truncationNote",
"kind": "function",
"path": "src/search/grep-cli.ts",
- "span": "L42-L49",
+ "span": "L43-L50",
"signature": "function truncationNote(result: GrepResult): string | null",
"exported": false,
"origin": "ast",
@@ -8975,7 +9076,7 @@
"name": "zeroHitNote",
"kind": "function",
"path": "src/search/grep-cli.ts",
- "span": "L69-L74",
+ "span": "L72-L77",
"signature": "function zeroHitNote(result: GrepResult): string",
"exported": true,
"origin": "ast",
@@ -8992,13 +9093,13 @@
"name": "grep.ts",
"kind": "file",
"path": "src/search/grep.ts",
- "span": "L1-L196",
+ "span": "L1-L201",
"signature": null,
"exported": true,
"origin": "ast",
- "body_hash": "e0ba3aaa565892e2772e4de0492931a568fc3f3724f8fca44b2a188a24e5eeb4",
- "chars": 6525,
- "summary_state": "ready",
+ "body_hash": "f3405967f0d2e4aba158b720188369dbe913c6c12955aa1511cabed498fddaf9",
+ "chars": 6816,
+ "summary_state": "stale",
"summary": "This file implements a regex search over indexed files in a graph, grouping results by their enclosing symbols and ranking them by their importance based on incoming edges.",
"crux": {
"code": " * `graft grep` core: regex search over the graph's indexed files, with hits\n * grouped by their innermost enclosing symbol and ranked by incoming-edge\n * count (coupling) — a grep that answers \"which of these hits matters\",\n * because plain `grep -rn` gives no way to tell a hit inside a\n * heavily-depended-on function from one inside dead code.",
@@ -9010,7 +9111,7 @@
"name": "computeInDegree",
"kind": "function",
"path": "src/search/grep.ts",
- "span": "L119-L126",
+ "span": "L123-L130",
"signature": "function computeInDegree(graph: GraphV1): Map<string, number>",
"exported": false,
"origin": "ast",
@@ -9027,7 +9128,7 @@
"name": "enclosingSymbol",
"kind": "function",
"path": "src/search/grep.ts",
- "span": "L108-L115",
+ "span": "L112-L119",
"signature": "function enclosingSymbol(symbols: SymbolSpan[], line: number): NodeV1 | null",
"exported": false,
"origin": "ast",
@@ -9044,7 +9145,7 @@
"name": "escapeRegExp",
"kind": "function",
"path": "src/search/grep.ts",
- "span": "L75-L77",
+ "span": "L79-L81",
"signature": "function escapeRegExp(s: string): string",
"exported": false,
"origin": "ast",
@@ -9061,12 +9162,12 @@
"name": "grepGraph",
"kind": "function",
"path": "src/search/grep.ts",
- "span": "L133-L195",
+ "span": "L137-L200",
"signature": "function grepGraph(graph: GraphV1, repoRoot: string, pattern: string, opts: GrepOptions = {}): GrepResult",
"exported": true,
"origin": "ast",
- "body_hash": "a18090820283ca87714b7e993b34c5af73234a6aa03759f1829d1d825be58931",
- "summary_state": "ready",
+ "body_hash": "468a117edd348b57d625a7e44c9b15ad2e67c220296b40961aa6903eefacef76",
+ "summary_state": "stale",
"summary": "Performs the grep search on the graph, collecting and returning results based on the specified pattern and options.",
"crux": {
"code": "export function grepGraph(graph: GraphV1, repoRoot: string, pattern: string, opts: GrepOptions = {}): GrepResult {\n const maxHits = opts.maxHits ?? DEFAULT_MAX_HITS;\n const source = opts.fixed ? escapeRegExp(pattern) : pattern;\n const regex = new RegExp(source, opts.ignoreCase ? \"i\" : \"\");\n\n const inDegree = computeInDegree(graph);\n const fileNodes = graph.nodes.filter((n) => n.kind === \"file\" && (!opts.in || n.path.includes(opts.in)));\n\n const groups = new Map<string, GrepGroup>();\n let collected = 0;\n let truncatedHits = 0;\n let truncatedFiles = 0;",
@@ -9078,7 +9179,7 @@
"name": "GrepGroup",
"kind": "interface",
"path": "src/search/grep.ts",
- "span": "L33-L42",
+ "span": "L34-L43",
"signature": "interface GrepGroup",
"exported": true,
"origin": "ast",
@@ -9095,7 +9196,7 @@
"name": "GrepHit",
"kind": "interface",
"path": "src/search/grep.ts",
- "span": "L17-L21",
+ "span": "L18-L22",
"signature": "interface GrepHit",
"exported": true,
"origin": "ast",
@@ -9112,7 +9213,7 @@
"name": "GrepOptions",
"kind": "interface",
"path": "src/search/grep.ts",
- "span": "L60-L69",
+ "span": "L64-L73",
"signature": "interface GrepOptions",
"exported": true,
"origin": "ast",
@@ -9129,12 +9230,12 @@
"name": "GrepResult",
"kind": "interface",
"path": "src/search/grep.ts",
- "span": "L44-L58",
+ "span": "L45-L62",
"signature": "interface GrepResult",
"exported": true,
"origin": "ast",
- "body_hash": "0e16fb84e869bb3443c681dd6c4f18ca395c415858fb8800a8024b4118474ca2",
- "summary_state": "ready",
+ "body_hash": "3c2826b6ccea2928580aa2a73561f99a6a0aae6b12bf84274c90a1b2fb8a72ab",
+ "summary_state": "stale",
"summary": "Encapsulates the results of a grep operation, including the pattern searched, total hits, and grouped results.",
"crux": {
"code": "export interface GrepResult {\n pattern: string;\n /** Indexed file nodes considered (after the `in` filter), whether or not\n * each was actually readable — matches the CLI's \"searched N indexed\n * files\" wording. */\n filesSearched: number;\n /** Hits actually collected (<= maxHits). */\n totalHits: number;\n /** Sorted: inDegree desc, then path asc. */\n groups: GrepGroup[];\n /** Dropped counts — never silent. `files`: indexed file nodes that\n * couldn't be read from disk. `hits`: matches found beyond `maxHits`,",
@@ -9146,7 +9247,7 @@
"name": "GrepSymbolRef",
"kind": "interface",
"path": "src/search/grep.ts",
- "span": "L23-L31",
+ "span": "L24-L32",
"signature": "interface GrepSymbolRef",
"exported": true,
"origin": "ast",
@@ -9163,7 +9264,7 @@
"name": "spanBounds",
"kind": "function",
"path": "src/search/grep.ts",
- "span": "L79-L83",
+ "span": "L83-L87",
"signature": "function spanBounds(span: string): { start: number; end: number } | null",
"exported": false,
"origin": "ast",
@@ -9180,7 +9281,7 @@
"name": "symbolsOf",
"kind": "function",
"path": "src/search/grep.ts",
- "span": "L93-L102",
+ "span": "L97-L106",
"signature": "function symbolsOf(graph: GraphV1, path: string): SymbolSpan[]",
"exported": false,
"origin": "ast",
@@ -9197,7 +9298,7 @@
"name": "SymbolSpan",
"kind": "interface",
"path": "src/search/grep.ts",
- "span": "L85-L89",
+ "span": "L89-L93",
"signature": "interface SymbolSpan",
"exported": false,
"origin": "ast",
@@ -9214,7 +9315,7 @@
"name": "toSymbolRef",
"kind": "function",
"path": "src/search/grep.ts",
- "span": "L128-L131",
+ "span": "L132-L135",
"signature": "function toSymbolRef(n: NodeV1): GrepSymbolRef",
"exported": false,
"origin": "ast",
@@ -9671,13 +9772,13 @@
"name": "claude-format.test.ts",
"kind": "file",
"path": "test/claude-format.test.ts",
- "span": "L1-L155",
+ "span": "L1-L157",
"signature": null,
"exported": true,
"origin": "ast",
- "body_hash": "cfaa9f489dd95956e3c9917ebe29a46992dfdbab943b5971eecbd98f18b3268c",
- "chars": 7267,
- "summary_state": "ready",
+ "body_hash": "1696c17377f2a228112d0a3d568cb04b3583d4f6b1c892dc731bd090cde62fc4",
+ "chars": 7466,
+ "summary_state": "stale",
"summary": "This test suite verifies the functionality of various formatting and retrieval functions related to the status line and enriched segments in a codebase, ensuring correct rendering based on different states and inputs.",
"crux": {
"code": "test('not-built state', () => {\n const lines = renderStatusline(null, null, { ctxPct: null });\n assert.match(strip(lines[0]), /not built/);\n});\n\ntest('enriched segment hidden when zero ready', () => {\n assert.equal(enrichedSegment({ ...emptyStats(), totalCount: 10, readyCount: 0 }), null);\n});\n\ntest('enriched segment shown when >=1 ready', () => {\n const seg = enrichedSegment({ ...emptyStats(), totalCount: 4, readyCount: 2 });\n assert.equal(strip(seg!), '50% enriched');",
@@ -9919,9 +10020,9 @@
"signature": null,
"exported": true,
"origin": "ast",
- "body_hash": "49f60183a51f9c307a33b5d4da3a7ded2f55509407e6a85778f3512b27db7cde",
- "chars": 1188,
- "summary_state": "ready",
+ "body_hash": "50c33ebe05bb251de0fd754dc4b75fe915e7db642ffd53c99198d1624a6ed723",
+ "chars": 1199,
+ "summary_state": "stale",
"summary": "This test ensures that the generated skill template adheres to the expected format and contains the necessary components for functionality.",
"crux": {
"code": " assert.ok(src.startsWith('---\\n'), 'starts with YAML frontmatter');\n assert.match(src, /^name: graft$/m, 'declares name: graft');\n assert.match(src, /^description:/m, 'has a description');\n const body = src.split(/\\n---\\n/)[1] ?? '';\n assert.ok(body.trim().length > 0, 'has a non-empty body');\n assert.match(body, /graft ask/, 'body tells the agent to use `graft ask`');\n assert.match(body, /every occurrence/i, 'body teaches the exhaustive-task grep rule');\n assert.match(body, /graft callers/, 'body teaches the callers command');\n assert.match(body, /graft callees/, 'body teaches the callees command');\n assert.match(body, /graft impact/, 'body teaches the impact command');\n assert.match(body, /truncated/i, 'body tells the agent to follow up on truncated spans');\n assert.match(body, /graft grep/, 'body routes sweeps to graft grep');",
@@ -10245,9 +10346,9 @@
"signature": null,
"exported": true,
"origin": "ast",
- "body_hash": "8df11988d049b5243d8c7a0d55045163b714965897448797b40c8ef458b0896b",
- "chars": 5524,
- "summary_state": "ready",
+ "body_hash": "1d283a2ff0318b7a3cd9be2b76ad3ef8a2eb4599934d37135448315c703c2c83",
+ "chars": 5530,
+ "summary_state": "stale",
"summary": "This file contains tests for caching mechanisms in the graph loading functionality to improve performance by avoiding unnecessary re-parsing of files.",
"crux": {
"code": "test(\"loadGraphCached: two loads of an unchanged file return the same parsed object\", () => {\n const dir = fixtureDir();\n writeGraph({ version: 1, nodes: [node(\"a\")], edges: [] } as GraphV1, dir);\n __resetParseCounts();\n\n const g1 = loadGraphCached(dir);\n const g2 = loadGraphCached(dir);\n assert.ok(g1);\n assert.strictEqual(g1, g2, \"second load must reuse the cached object, not re-parse\");\n assert.equal(__parseCount.graph, 1);\n});\n",
@@ -10448,13 +10549,13 @@
"name": "graph-traverse-cli.test.ts",
"kind": "file",
"path": "test/graph-traverse-cli.test.ts",
- "span": "L1-L126",
+ "span": "L1-L143",
"signature": null,
"exported": true,
"origin": "ast",
- "body_hash": "d79347b0640178631235552105c0518029305ead4990726470d3adf5a1b52f09",
- "chars": 5030,
- "summary_state": "ready",
+ "body_hash": "53390c4f5cb5d2135b2d423c9b7e191abdb4897ebc29909be741cef4f0f7d81f",
+ "chars": 5928,
+ "summary_state": "stale",
"summary": "This file contains tests for the CLI commands related to graph traversal, ensuring correct functionality and output for various scenarios.",
"crux": {
"code": "test('graft callers: happy path shows header and the caller hit', () => {\n const d = builtRepo();\n const r = runCli(['callers', 'add', d]);\n assert.equal(r.status, 0);\n assert.match(r.stdout, /add · function · src\\/math\\.ts:/);\n assert.match(r.stdout, /calls ← sub \\(src\\/math\\.ts:/);\n});\n\ntest('graft callers --json: shape matches {query, matches:[{symbol,hits}]}', () => {\n const d = builtRepo();\n const r = runCli(['callers', 'add', d, '--json']);\n assert.equal(r.status, 0);",
@@ -10466,7 +10567,7 @@
"name": "builtRepo",
"kind": "function",
"path": "test/graph-traverse-cli.test.ts",
- "span": "L16-L27",
+ "span": "L17-L28",
"signature": "function builtRepo(): string",
"exported": false,
"origin": "ast",
@@ -10483,7 +10584,7 @@
"name": "runCli",
"kind": "function",
"path": "test/graph-traverse-cli.test.ts",
- "span": "L29-L40",
+ "span": "L30-L41",
"signature": "function runCli(args: string[]): { stdout: string; stderr: string; status: number }",
"exported": false,
"origin": "ast",
@@ -11219,13 +11320,13 @@
"name": "mcp-server.test.ts",
"kind": "file",
"path": "test/mcp-server.test.ts",
- "span": "L1-L68",
+ "span": "L1-L66",
"signature": null,
"exported": true,
"origin": "ast",
- "body_hash": "4d828181f0a8c645f00097ab43c2bdcf5bc65da276e83b7503bc2888ae09f254",
- "chars": 2604,
- "summary_state": "ready",
+ "body_hash": "5eacb67182a2925edec5bd036ae556018ed3b2c266d65aaefa0d4d1ff0a3fee6",
+ "chars": 2564,
+ "summary_state": "stale",
"summary": "This file contains tests for the RPC functionality of the MCP server, ensuring that various methods return expected results and handle errors correctly.",
"crux": {
"code": "test('initialize → tools/list → tools/call round-trip', async () => {\n const dir = mkdtempSync(join(tmpdir(), 'graft-mcpsrv-'));\n const rs = await rpc(\n [\n { jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-03-26', capabilities: {}, clientInfo: { name: 't', version: '0' } } },\n { jsonrpc: '2.0', method: 'notifications/initialized' },\n { jsonrpc: '2.0', id: 2, method: 'tools/list' },\n { jsonrpc: '2.0', id: 3, method: 'tools/call', params: { name: 'graft_blast_radius', arguments: { file: 'x.ts' } } },\n ],\n dir,\n 3,\n );",
@@ -11254,13 +11355,13 @@
"name": "mcp-tools.test.ts",
"kind": "file",
"path": "test/mcp-tools.test.ts",
- "span": "L1-L290",
+ "span": "L1-L289",
"signature": null,
"exported": true,
"origin": "ast",
- "body_hash": "22d3a32a85a0ba1542969786e8bda07d3df02ee068554d4070f705d30d7239dc",
- "chars": 12646,
- "summary_state": "ready",
+ "body_hash": "edf9190673e0d472438bdad78bcfd03682c847a6a8f11e90f8a1425f5bcd45ef",
+ "chars": 12727,
+ "summary_state": "stale",
"summary": "This test suite validates the functionality of various tools in the MCP codebase, ensuring they operate correctly on built repositories and handle errors appropriately.",
"crux": {
"code": "test('TOOLS lists all eight tools with schemas', () => {\n assert.deepEqual(TOOLS.map((t) => t.name), [\n 'graft_ask',\n 'graft_skeleton',\n 'graft_check',\n 'graft_blast_radius',\n 'graft_callers',\n 'graft_callees',\n 'graft_grep',\n 'graft_map',\n ]);\n for (const t of TOOLS) {",
@@ -13990,6 +14091,12 @@
"relation": "contains",
"confidence": "extracted"
},
+ {
+ "source": "src/ask/ask.ts",
+ "target": "src/ask/ask.ts#askSavingsFooter",
+ "relation": "contains",
+ "confidence": "extracted"
+ },
{
"source": "src/ask/ask.ts",
"target": "src/ask/ask.ts#baselineFor",
@@ -14020,6 +14127,12 @@
"relation": "contains",
"confidence": "extracted"
},
+ {
+ "source": "src/ask/ask.ts",
+ "target": "src/ask/ask.ts#escalationNudge",
+ "relation": "contains",
+ "confidence": "extracted"
+ },
{
"source": "src/ask/ask.ts",
"target": "src/ask/ask.ts#fallthroughNoteFor",
@@ -14098,12 +14211,6 @@
"relation": "contains",
"confidence": "extracted"
},
- {
- "source": "src/ask/ask.ts",
- "target": "src/ask/ask.ts#savingsFooter",
- "relation": "contains",
- "confidence": "extracted"
- },
{
"source": "src/ask/ask.ts",
"target": "src/ask/ask.ts#score",
@@ -14194,6 +14301,12 @@
"relation": "imports",
"confidence": "extracted"
},
+ {
+ "source": "src/ask/ask.ts",
+ "target": "src/context/savings.ts",
+ "relation": "imports",
+ "confidence": "extracted"
+ },
{
"source": "src/ask/ask.ts",
"target": "src/graph/load.ts",
@@ -14248,12 +14361,24 @@
"relation": "calls",
"confidence": "inferred"
},
+ {
+ "source": "src/ask/ask.ts#askSavingsFooter",
+ "target": "src/ask/ask.ts#toTokens",
+ "relation": "calls",
+ "confidence": "extracted"
+ },
{
"source": "src/ask/ask.ts#baselineFor",
"target": "src/ask/ask.ts#hitFiles",
"relation": "calls",
"confidence": "extracted"
},
+ {
+ "source": "src/ask/ask.ts#baselineFor",
+ "target": "src/context/savings.ts#savingsFor",
+ "relation": "calls",
+ "confidence": "inferred"
+ },
{
"source": "src/ask/ask.ts#computeIdf",
"target": "src/ask/ask.ts#idfFromDf",
@@ -14280,10 +14405,22 @@
},
{
"source": "src/ask/ask.ts#formatAsk",
- "target": "src/ask/ask.ts#savingsFooter",
+ "target": "src/ask/ask.ts#askSavingsFooter",
"relation": "calls",
"confidence": "extracted"
},
+ {
+ "source": "src/ask/ask.ts#formatAsk",
+ "target": "src/ask/ask.ts#escalationNudge",
+ "relation": "calls",
+ "confidence": "extracted"
+ },
+ {
+ "source": "src/ask/ask.ts#formatSkeleton",
+ "target": "src/context/savings.ts#savingsFooter",
+ "relation": "calls",
+ "confidence": "inferred"
+ },
{
"source": "src/ask/ask.ts#hitFiles",
"target": "src/ask/ask.ts#parseSpan",
@@ -14387,20 +14524,20 @@
"confidence": "extracted"
},
{
- "source": "src/ask/ask.ts#savingsFooter",
- "target": "src/ask/ask.ts#toTokens",
+ "source": "src/ask/ask.ts#skeleton",
+ "target": "src/ask/ask.ts#skeleton.startLine",
"relation": "calls",
"confidence": "extracted"
},
{
"source": "src/ask/ask.ts#skeleton",
- "target": "src/ask/ask.ts#skeleton.startLine",
+ "target": "src/context/node-file.ts#contextDirFor",
"relation": "calls",
- "confidence": "extracted"
+ "confidence": "inferred"
},
{
"source": "src/ask/ask.ts#skeleton",
- "target": "src/context/node-file.ts#contextDirFor",
+ "target": "src/context/savings.ts#savingsFor",
"relation": "calls",
"confidence": "inferred"
},
@@ -15034,6 +15171,12 @@
"relation": "imports",
"confidence": "extracted"
},
+ {
+ "source": "src/claude/init.ts",
+ "target": "src/hosts/mcp-config.ts",
+ "relation": "imports",
+ "confidence": "extracted"
+ },
{
"source": "src/claude/init.ts#runInit",
"target": "src/claude/paths.ts#claudeDistDir",
@@ -15064,6 +15207,12 @@
"relation": "calls",
"confidence": "inferred"
},
+ {
+ "source": "src/claude/init.ts#runInit",
+ "target": "src/hosts/mcp-config.ts#mergeJsonKey",
+ "relation": "calls",
+ "confidence": "inferred"
+ },
{
"source": "src/claude/paths.ts",
"target": "src/claude/paths.ts#claudeDistDir",
@@ -15862,12 +16011,6 @@
"relation": "calls",
"confidence": "extracted"
},
- {
- "source": "src/cli.ts",
- "target": "src/cli.ts#traverseAction",
- "relation": "calls",
- "confidence": "extracted"
- },
{
"source": "src/cli.ts",
"target": "src/context/check.ts#formatCheckReport",
@@ -15934,6 +16077,12 @@
"relation": "calls",
"confidence": "inferred"
},
+ {
+ "source": "src/cli.ts",
+ "target": "src/graph/traverse-cli.ts#runCallersCommand",
+ "relation": "calls",
+ "confidence": "inferred"
+ },
{
"source": "src/cli.ts",
"target": "src/hosts/init.ts#runHostsInit",
@@ -15988,12 +16137,6 @@
"relation": "contains",
"confidence": "extracted"
},
- {
- "source": "src/cli.ts",
- "target": "src/cli.ts#traverseAction",
- "relation": "contains",
- "confidence": "extracted"
- },
{
"source": "src/cli.ts",
"target": "commander",
@@ -16096,12 +16239,6 @@
"relation": "calls",
"confidence": "extracted"
},
- {
- "source": "src/cli.ts#traverseAction",
- "target": "src/graph/traverse-cli.ts#runTraverseCommand",
- "relation": "calls",
- "confidence": "inferred"
- },
{
"source": "src/context/build.ts",
"target": "src/context/build.ts#batchBySize",
@@ -16648,6 +16785,54 @@
"relation": "calls",
"confidence": "extracted"
},
+ {
+ "source": "src/context/savings.ts",
+ "target": "src/context/savings.ts#fileSizes",
+ "relation": "contains",
+ "confidence": "extracted"
+ },
+ {
+ "source": "src/context/savings.ts",
+ "target": "src/context/savings.ts#Savings",
+ "relation": "contains",
+ "confidence": "extracted"
+ },
+ {
+ "source": "src/context/savings.ts",
+ "target": "src/context/savings.ts#savingsFooter",
+ "relation": "contains",
+ "confidence": "extracted"
+ },
+ {
+ "source": "src/context/savings.ts",
+ "target": "src/context/savings.ts#savingsFor",
+ "relation": "contains",
+ "confidence": "extracted"
+ },
+ {
+ "source": "src/context/savings.ts",
+ "target": "src/context/savings.ts#toTokens",
+ "relation": "contains",
+ "confidence": "extracted"
+ },
+ {
+ "source": "src/context/savings.ts",
+ "target": "src/graph/types.ts",
+ "relation": "imports",
+ "confidence": "extracted"
+ },
+ {
+ "source": "src/context/savings.ts#savingsFooter",
+ "target": "src/context/savings.ts#toTokens",
+ "relation": "calls",
+ "confidence": "extracted"
+ },
+ {
+ "source": "src/context/savings.ts#savingsFor",
+ "target": "src/context/savings.ts#fileSizes",
+ "relation": "calls",
+ "confidence": "extracted"
+ },
{
"source": "src/engine.ts",
"target": "src/engine.ts#CheckRunOptions",
@@ -18268,6 +18453,12 @@
"relation": "contains",
"confidence": "extracted"
},
+ {
+ "source": "src/graph/map.ts",
+ "target": "src/context/savings.ts",
+ "relation": "imports",
+ "confidence": "extracted"
+ },
{
"source": "src/graph/map.ts",
"target": "src/graph/extract.ts",
@@ -18286,6 +18477,12 @@
"relation": "imports",
"confidence": "extracted"
},
+ {
+ "source": "src/graph/map.ts#buildRepoMap",
+ "target": "src/context/savings.ts#savingsFor",
+ "relation": "calls",
+ "confidence": "inferred"
+ },
{
"source": "src/graph/map.ts#buildRepoMap",
"target": "src/graph/map.ts#buildRepoMap.depthFor",
@@ -18334,6 +18531,12 @@
"relation": "calls",
"confidence": "extracted"
},
+ {
+ "source": "src/graph/map.ts#formatRepoMap",
+ "target": "src/context/savings.ts#savingsFooter",
+ "relation": "calls",
+ "confidence": "inferred"
+ },
{
"source": "src/graph/map.ts#formatRepoMap",
"target": "src/graph/map.ts#formatDirLine",
@@ -18468,7 +18671,13 @@
},
{
"source": "src/graph/traverse-cli.ts",
- "target": "src/graph/traverse-cli.ts#edgesFor",
+ "target": "src/graph/traverse-cli.ts#CallersCliOptions",
+ "relation": "contains",
+ "confidence": "extracted"
+ },
+ {
+ "source": "src/graph/traverse-cli.ts",
+ "target": "src/graph/traverse-cli.ts#callersSavings",
"relation": "contains",
"confidence": "extracted"
},
@@ -18510,43 +18719,43 @@
},
{
"source": "src/graph/traverse-cli.ts",
- "target": "src/graph/traverse-cli.ts#runTraverseCommand",
+ "target": "src/graph/traverse-cli.ts#resolveDirection",
"relation": "contains",
"confidence": "extracted"
},
{
"source": "src/graph/traverse-cli.ts",
- "target": "src/graph/traverse-cli.ts#symbolJson",
+ "target": "src/graph/traverse-cli.ts#runCallersCommand",
"relation": "contains",
"confidence": "extracted"
},
{
"source": "src/graph/traverse-cli.ts",
- "target": "src/graph/traverse-cli.ts#SymbolJson",
+ "target": "src/graph/traverse-cli.ts#symbolJson",
"relation": "contains",
"confidence": "extracted"
},
{
"source": "src/graph/traverse-cli.ts",
- "target": "src/graph/traverse-cli.ts#TraverseCliOptions",
+ "target": "src/graph/traverse-cli.ts#SymbolJson",
"relation": "contains",
"confidence": "extracted"
},
{
"source": "src/graph/traverse-cli.ts",
- "target": "src/graph/traverse-cli.ts#TraverseKind",
- "relation": "contains",
+ "target": "node:path",
+ "relation": "imports",
"confidence": "extracted"
},
{
"source": "src/graph/traverse-cli.ts",
- "target": "node:path",
+ "target": "src/context/node-file.ts",
"relation": "imports",
"confidence": "extracted"
},
{
"source": "src/graph/traverse-cli.ts",
- "target": "src/context/node-file.ts",
+ "target": "src/context/savings.ts",
"relation": "imports",
"confidence": "extracted"
},
@@ -18569,67 +18778,73 @@
"confidence": "extracted"
},
{
- "source": "src/graph/traverse-cli.ts#edgesFor",
- "target": "src/graph/traverse.ts#calleesOf",
+ "source": "src/graph/traverse-cli.ts#callersSavings",
+ "target": "src/context/savings.ts#savingsFor",
"relation": "calls",
"confidence": "inferred"
},
{
- "source": "src/graph/traverse-cli.ts#edgesFor",
- "target": "src/graph/traverse.ts#callersOf",
+ "source": "src/graph/traverse-cli.ts#runCallersCommand",
+ "target": "src/context/node-file.ts#contextDirFor",
"relation": "calls",
"confidence": "inferred"
},
{
- "source": "src/graph/traverse-cli.ts#edgesFor",
- "target": "src/graph/traverse.ts#impactOf",
+ "source": "src/graph/traverse-cli.ts#runCallersCommand",
+ "target": "src/context/savings.ts#savingsFooter",
"relation": "calls",
"confidence": "inferred"
},
{
- "source": "src/graph/traverse-cli.ts#runTraverseCommand",
- "target": "src/context/node-file.ts#contextDirFor",
- "relation": "calls",
- "confidence": "inferred"
- },
- {
- "source": "src/graph/traverse-cli.ts#runTraverseCommand",
+ "source": "src/graph/traverse-cli.ts#runCallersCommand",
"target": "src/graph/load.ts#loadGraphCached",
"relation": "calls",
"confidence": "inferred"
},
{
- "source": "src/graph/traverse-cli.ts#runTraverseCommand",
- "target": "src/graph/traverse-cli.ts#edgesFor",
+ "source": "src/graph/traverse-cli.ts#runCallersCommand",
+ "target": "src/graph/traverse-cli.ts#callersSavings",
"relation": "calls",
"confidence": "extracted"
},
{
- "source": "src/graph/traverse-cli.ts#runTraverseCommand",
+ "source": "src/graph/traverse-cli.ts#runCallersCommand",
"target": "src/graph/traverse-cli.ts#headerOf",
"relation": "calls",
"confidence": "extracted"
},
{
- "source": "src/graph/traverse-cli.ts#runTraverseCommand",
+ "source": "src/graph/traverse-cli.ts#runCallersCommand",
"target": "src/graph/traverse-cli.ts#hitLine",
"relation": "calls",
"confidence": "extracted"
},
{
- "source": "src/graph/traverse-cli.ts#runTraverseCommand",
+ "source": "src/graph/traverse-cli.ts#runCallersCommand",
"target": "src/graph/traverse-cli.ts#looseNoteFor",
"relation": "calls",
"confidence": "extracted"
},
{
- "source": "src/graph/traverse-cli.ts#runTraverseCommand",
+ "source": "src/graph/traverse-cli.ts#runCallersCommand",
+ "target": "src/graph/traverse-cli.ts#resolveDirection",
+ "relation": "calls",
+ "confidence": "extracted"
+ },
+ {
+ "source": "src/graph/traverse-cli.ts#runCallersCommand",
"target": "src/graph/traverse-cli.ts#symbolJson",
"relation": "calls",
"confidence": "extracted"
},
{
- "source": "src/graph/traverse-cli.ts#runTraverseCommand",
+ "source": "src/graph/traverse-cli.ts#runCallersCommand",
+ "target": "src/graph/traverse.ts#edgeWalk",
+ "relation": "calls",
+ "confidence": "inferred"
+ },
+ {
+ "source": "src/graph/traverse-cli.ts#runCallersCommand",
"target": "src/graph/traverse.ts#resolveSymbol",
"relation": "calls",
"confidence": "inferred"
@@ -18646,12 +18861,24 @@
"relation": "contains",
"confidence": "extracted"
},
+ {
+ "source": "src/graph/traverse.ts",
+ "target": "src/graph/traverse.ts#Direction",
+ "relation": "contains",
+ "confidence": "extracted"
+ },
{
"source": "src/graph/traverse.ts",
"target": "src/graph/traverse.ts#EdgeHit",
"relation": "contains",
"confidence": "extracted"
},
+ {
+ "source": "src/graph/traverse.ts",
+ "target": "src/graph/traverse.ts#edgeWalk",
+ "relation": "contains",
+ "confidence": "extracted"
+ },
{
"source": "src/graph/traverse.ts",
"target": "src/graph/traverse.ts#impactOf",
@@ -18712,6 +18939,30 @@
"relation": "imports",
"confidence": "extracted"
},
+ {
+ "source": "src/graph/traverse.ts#edgeWalk",
+ "target": "src/graph/traverse.ts#calleesOf",
+ "relation": "calls",
+ "confidence": "extracted"
+ },
+ {
+ "source": "src/graph/traverse.ts#edgeWalk",
+ "target": "src/graph/traverse.ts#callersOf",
+ "relation": "calls",
+ "confidence": "extracted"
+ },
+ {
+ "source": "src/graph/traverse.ts#edgeWalk",
+ "target": "src/graph/traverse.ts#impactOfFile",
+ "relation": "calls",
+ "confidence": "extracted"
+ },
+ {
+ "source": "src/graph/traverse.ts#edgeWalk",
+ "target": "src/graph/traverse.ts#impactOfMany",
+ "relation": "calls",
+ "confidence": "extracted"
+ },
{
"source": "src/graph/traverse.ts#impactOf",
"target": "src/graph/traverse.ts#impactOfMany",
@@ -19366,6 +19617,12 @@
"relation": "imports",
"confidence": "extracted"
},
+ {
+ "source": "src/mcp/tools.ts",
+ "target": "src/context/savings.ts",
+ "relation": "imports",
+ "confidence": "extracted"
+ },
{
"source": "src/mcp/tools.ts",
"target": "src/engine.ts",
@@ -19450,6 +19707,12 @@
"relation": "calls",
"confidence": "inferred"
},
+ {
+ "source": "src/mcp/tools.ts#callTool",
+ "target": "src/context/savings.ts#savingsFooter",
+ "relation": "calls",
+ "confidence": "inferred"
+ },
{
"source": "src/mcp/tools.ts#callTool",
"target": "src/engine.ts#Graft.ask",
@@ -19494,13 +19757,13 @@
},
{
"source": "src/mcp/tools.ts#callTool",
- "target": "src/graph/traverse.ts#impactOf",
+ "target": "src/graph/traverse-cli.ts#callersSavings",
"relation": "calls",
"confidence": "inferred"
},
{
"source": "src/mcp/tools.ts#callTool",
- "target": "src/graph/traverse.ts#impactOfFile",
+ "target": "src/graph/traverse.ts#edgeWalk",
"relation": "calls",
"confidence": "inferred"
},
@@ -19618,6 +19881,12 @@
"relation": "imports",
"confidence": "extracted"
},
+ {
+ "source": "src/search/grep-cli.ts",
+ "target": "src/context/savings.ts",
+ "relation": "imports",
+ "confidence": "extracted"
+ },
{
"source": "src/search/grep-cli.ts",
"target": "src/graph/load.ts",
@@ -19630,6 +19899,12 @@
"relation": "imports",
"confidence": "extracted"
},
+ {
+ "source": "src/search/grep-cli.ts#formatGrepResult",
+ "target": "src/context/savings.ts#savingsFooter",
+ "relation": "calls",
+ "confidence": "inferred"
+ },
{
"source": "src/search/grep-cli.ts#formatGrepResult",
"target": "src/search/grep-cli.ts#formatGrepHeader",
@@ -19774,6 +20049,12 @@
"relation": "imports",
"confidence": "extracted"
},
+ {
+ "source": "src/search/grep.ts",
+ "target": "src/context/savings.ts",
+ "relation": "imports",
+ "confidence": "extracted"
+ },
{
"source": "src/search/grep.ts",
"target": "src/graph/relations.ts",
@@ -19786,6 +20067,12 @@
"relation": "imports",
"confidence": "extracted"
},
+ {
+ "source": "src/search/grep.ts#grepGraph",
+ "target": "src/context/savings.ts#savingsFor",
+ "relation": "calls",
+ "confidence": "inferred"
+ },
{
"source": "src/search/grep.ts#grepGraph",
"target": "src/search/grep.ts#computeInDegree",
diff --git a/graft/INDEX.md b/graft/INDEX.md
index e7125849..5ae08943 100644
--- a/graft/INDEX.md
+++ b/graft/INDEX.md
@@ -38,5 +38,5 @@ filename here, or run `graft ask "<task>"`. Each node carries prose plus exact
## Files
-111 per-file wiring cards mirror the source tree under `graft/` (100 carry extracted symbols). They are deliberately not enumerated here —
+112 per-file wiring cards mirror the source tree under `graft/` (101 carry extracted symbols). They are deliberately not enumerated here —
`grep` a symbol or `find`/`ls` a filename under `graft/` to land on the card for that file.
diff --git a/graft/graph-traversal-and-analysis.md b/graft/graph-traversal-and-analysis.md
index 839eb869..274e9dd7 100644
--- a/graft/graph-traversal-and-analysis.md
+++ b/graft/graph-traversal-and-analysis.md
@@ -22,138 +22,144 @@ links:
generator:
version: 1
covers:
- - symbol: TraverseKind
- kind: type
- at: 'src/graph/traverse-cli.ts:L17-L17'
- - symbol: TraverseCliOptions
+ - symbol: CallersCliOptions
kind: interface
- at: 'src/graph/traverse-cli.ts:L19-L26'
- - symbol: edgesFor
- kind: function
- at: 'src/graph/traverse-cli.ts:L31-L35'
+ at: 'src/graph/traverse-cli.ts:L21-L30'
- symbol: headerOf
kind: function
- at: 'src/graph/traverse-cli.ts:L41-L43'
+ at: 'src/graph/traverse-cli.ts:L38-L40'
- symbol: hitLine
kind: function
- at: 'src/graph/traverse-cli.ts:L45-L50'
+ at: 'src/graph/traverse-cli.ts:L44-L49'
+ - symbol: callersSavings
+ kind: function
+ at: 'src/graph/traverse-cli.ts:L55-L65'
- symbol: looseNoteFor
kind: function
- at: 'src/graph/traverse-cli.ts:L54-L58'
+ at: 'src/graph/traverse-cli.ts:L68-L72'
- symbol: SymbolJson
kind: interface
- at: 'src/graph/traverse-cli.ts:L60-L66'
+ at: 'src/graph/traverse-cli.ts:L74-L80'
- symbol: MatchJson
kind: interface
- at: 'src/graph/traverse-cli.ts:L68-L72'
+ at: 'src/graph/traverse-cli.ts:L82-L86'
- symbol: HitJson
kind: interface
- at: 'src/graph/traverse-cli.ts:L74-L82'
+ at: 'src/graph/traverse-cli.ts:L88-L96'
- symbol: symbolJson
kind: function
- at: 'src/graph/traverse-cli.ts:L84-L86'
+ at: 'src/graph/traverse-cli.ts:L98-L100'
- symbol: hitJson
kind: function
- at: 'src/graph/traverse-cli.ts:L88-L97'
- - symbol: runTraverseCommand
+ at: 'src/graph/traverse-cli.ts:L102-L111'
+ - symbol: resolveDirection
+ kind: function
+ at: 'src/graph/traverse-cli.ts:L114-L119'
+ - symbol: runCallersCommand
kind: function
- at: 'src/graph/traverse-cli.ts:L105-L155'
+ at: 'src/graph/traverse-cli.ts:L127-L182'
+ - symbol: Direction
+ kind: type
+ at: 'src/graph/traverse.ts:L21-L21'
- symbol: SymbolMatch
kind: interface
- at: 'src/graph/traverse.ts:L19-L21'
+ at: 'src/graph/traverse.ts:L25-L27'
- symbol: ResolveSymbolOptions
kind: interface
- at: 'src/graph/traverse.ts:L23-L26'
+ at: 'src/graph/traverse.ts:L29-L32'
- symbol: resolveSymbol
kind: function
- at: 'src/graph/traverse.ts:L47-L72'
+ at: 'src/graph/traverse.ts:L53-L78'
- symbol: symbolMatches
kind: function
- at: 'src/graph/traverse.ts:L74-L83'
+ at: 'src/graph/traverse.ts:L80-L89'
- symbol: EdgeHit
kind: interface
- at: 'src/graph/traverse.ts:L88-L93'
+ at: 'src/graph/traverse.ts:L94-L99'
- symbol: callersOf
kind: function
- at: 'src/graph/traverse.ts:L96-L104'
+ at: 'src/graph/traverse.ts:L102-L110'
- symbol: calleesOf
kind: function
- at: 'src/graph/traverse.ts:L107-L115'
+ at: 'src/graph/traverse.ts:L113-L121'
- symbol: impactOf
kind: function
- at: 'src/graph/traverse.ts:L123-L125'
+ at: 'src/graph/traverse.ts:L129-L131'
- symbol: impactOfMany
kind: function
- at: 'src/graph/traverse.ts:L141-L172'
+ at: 'src/graph/traverse.ts:L149-L184'
- symbol: symbolsInFile
kind: function
- at: 'src/graph/traverse.ts:L176-L178'
+ at: 'src/graph/traverse.ts:L188-L190'
- symbol: impactOfFile
kind: function
- at: 'src/graph/traverse.ts:L189-L191'
+ at: 'src/graph/traverse.ts:L201-L203'
+ - symbol: edgeWalk
+ kind: function
+ at: 'src/graph/traverse.ts:L218-L222'
- symbol: GrepCliOptions
kind: interface
- at: 'src/search/grep-cli.ts:L15-L22'
+ at: 'src/search/grep-cli.ts:L16-L23'
- symbol: groupHeader
kind: function
- at: 'src/search/grep-cli.ts:L24-L27'
+ at: 'src/search/grep-cli.ts:L25-L28'
- symbol: formatGroup
kind: function
- at: 'src/search/grep-cli.ts:L29-L33'
+ at: 'src/search/grep-cli.ts:L30-L34'
- symbol: formatGrepHeader
kind: function
- at: 'src/search/grep-cli.ts:L36-L39'
+ at: 'src/search/grep-cli.ts:L37-L40'
- symbol: truncationNote
kind: function
- at: 'src/search/grep-cli.ts:L42-L49'
+ at: 'src/search/grep-cli.ts:L43-L50'
- symbol: formatGrepResult
kind: function
- at: 'src/search/grep-cli.ts:L53-L59'
+ at: 'src/search/grep-cli.ts:L54-L62'
- symbol: zeroHitNote
kind: function
- at: 'src/search/grep-cli.ts:L69-L74'
+ at: 'src/search/grep-cli.ts:L72-L77'
- symbol: runGrepCommand
kind: function
- at: 'src/search/grep-cli.ts:L83-L112'
+ at: 'src/search/grep-cli.ts:L86-L115'
- symbol: GrepHit
kind: interface
- at: 'src/search/grep.ts:L17-L21'
+ at: 'src/search/grep.ts:L18-L22'
- symbol: GrepSymbolRef
kind: interface
- at: 'src/search/grep.ts:L23-L31'
+ at: 'src/search/grep.ts:L24-L32'
- symbol: GrepGroup
kind: interface
- at: 'src/search/grep.ts:L33-L42'
+ at: 'src/search/grep.ts:L34-L43'
- symbol: GrepResult
kind: interface
- at: 'src/search/grep.ts:L44-L58'
+ at: 'src/search/grep.ts:L45-L62'
- symbol: GrepOptions
kind: interface
- at: 'src/search/grep.ts:L60-L69'
+ at: 'src/search/grep.ts:L64-L73'
- symbol: escapeRegExp
kind: function
- at: 'src/search/grep.ts:L75-L77'
+ at: 'src/search/grep.ts:L79-L81'
- symbol: spanBounds
kind: function
- at: 'src/search/grep.ts:L79-L83'
+ at: 'src/search/grep.ts:L83-L87'
- symbol: SymbolSpan
kind: interface
- at: 'src/search/grep.ts:L85-L89'
+ at: 'src/search/grep.ts:L89-L93'
- symbol: symbolsOf
kind: function
- at: 'src/search/grep.ts:L93-L102'
+ at: 'src/search/grep.ts:L97-L106'
- symbol: enclosingSymbol
kind: function
- at: 'src/search/grep.ts:L108-L115'
+ at: 'src/search/grep.ts:L112-L119'
- symbol: computeInDegree
kind: function
- at: 'src/search/grep.ts:L119-L126'
+ at: 'src/search/grep.ts:L123-L130'
- symbol: toSymbolRef
kind: function
- at: 'src/search/grep.ts:L128-L131'
+ at: 'src/search/grep.ts:L132-L135'
- symbol: grepGraph
kind: function
- at: 'src/search/grep.ts:L133-L195'
+ at: 'src/search/grep.ts:L137-L200'
---
<!-- context:generated:start -->
## Summary
diff --git a/graft/host-management-and-configuration.md b/graft/host-management-and-configuration.md
index 25b50283..1afaa27f 100644
--- a/graft/host-management-and-configuration.md
+++ b/graft/host-management-and-configuration.md
@@ -59,16 +59,16 @@ covers:
at: 'src/hosts/init.ts:L37-L72'
- symbol: instructionBody
kind: function
- at: 'src/hosts/instructions.ts:L6-L42'
+ at: 'src/hosts/instructions.ts:L6-L43'
- symbol: cursorRule
kind: function
- at: 'src/hosts/instructions.ts:L44-L51'
+ at: 'src/hosts/instructions.ts:L45-L52'
- symbol: kiroSteering
kind: function
- at: 'src/hosts/instructions.ts:L53-L59'
+ at: 'src/hosts/instructions.ts:L54-L60'
- symbol: windsurfRule
kind: function
- at: 'src/hosts/instructions.ts:L61-L64'
+ at: 'src/hosts/instructions.ts:L62-L65'
- symbol: McpWrite
kind: interface
at: 'src/hosts/mcp-config.ts:L10-L14'
diff --git a/graft/src/ask/ask.md b/graft/src/ask/ask.md
index eebcd84b..f15570ca 100644
--- a/graft/src/ask/ask.md
+++ b/graft/src/ask/ask.md
@@ -2,37 +2,38 @@
This module provides a mechanism to process natural language queries and return structured results from a codebase, enhancing the ability to find relevant code snippets and their relationships.
-- AskHit · interface · L26-L39 — Represents a hit in the query results, encapsulating details about a code symbol and its context.
-- AskResult · interface · L45-L62 — Represents the result of an 'ask' query, encapsulating the query details and the hits found.
-- firstProse · function · L65-L72 — Extracts the first meaningful prose line from a body of text, ignoring headings and blank lines.
-- Corpus · interface · L74-L81 — Defines the structure for holding concepts and graph data used in processing queries.
-- loadCorpus · function · L83-L108 — Loads a corpus of concepts and graph data from a specified directory, enabling query processing.
-- score · function · L117-L128 — Calculates a score for a document based on its token counts relative to a query, enhancing relevance ranking.
-- idfFromDf · function · L134-L138 — Computes the inverse document frequency (IDF) from document frequency (DF) data, aiding in scoring relevance.
-- computeIdf · function · L140-L145 — Generates IDF values from document bags, which are used to weight query matches based on term rarity.
-- computeIdfFromIndex · function · L154-L159 — Calculates IDF values using precomputed index data, optimizing the scoring process for queries.
-- bm25 · function · L166-L182 — Implements the BM25 scoring algorithm to rank documents based on term frequency and document length.
-- subjectWords · function · L194-L196 — Tokenizes a query into words while preserving qualified names, facilitating accurate subject resolution.
-- findSubjectNodes · function · L206-L213 — Finds nodes in the graph that match the structural subject of a query, enhancing query resolution.
-- StructuralOutcome · type · L221-L221 — Defines the possible outcomes of a structural query, indicating whether a result was found, a fallthrough note is needed, or if there was no structural intent.
-- fallthroughNoteFor · function · L223-L228 — Generates a note for cases where a structural query falls back to lexical processing, providing user guidance.
-- structural · function · L230-L279 — Processes a structural query to find relationships in the graph, returning relevant results or fallthrough notes.
-- hasTerm · function · L298-L300 — Checks for the presence of a term in a document's token map, aiding in relevance scoring.
-- matchedIdfShare · function · L309-L323 — Calculates the share of query terms matched by a document, weighted by term rarity for relevance assessment.
-- lexical · function · L325-L487 — Handles lexical queries by scoring documents based on term matches and relevance, returning structured results.
-- bodyLen · function · L416-L420 — Calculates the length of the body of a lexical document to ensure it meets certain criteria for processing.
-- AskOptions · interface · L489-L505 — Defines the options available for configuring the ask function, allowing customization of its behavior.
-- parseSpan · function · L509-L513 — Parses a string pointer into its file path and line range components, facilitating source code navigation.
-- sliceSpan · function · L517-L532 — Reads a specified range of lines from a source file, allowing for inlined code snippets in query results.
-- inlineSource · function · L539-L556 — Inlines the source code for the hits found, providing context directly in the results without needing to open files.
-- hitFiles · function · L560-L569 — Extracts a set of unique file paths from the hits, indicating which files are relevant to the query results.
-- baselineFor · function · L574-L589 — Calculates the baseline file size and character count for the hits, providing a measure of the cost of reading the full files.
-- ask · function · L592-L622 — Handles the main logic for processing a query against a directory, returning structured results based on the query type.
-- SkeletonEntry · interface · L626-L633 — Defines the structure of a skeleton entry, which represents a piece of information extracted from a file.
-- SkeletonResult · interface · L635-L639 — Defines the structure of the result returned from the skeleton function, encapsulating the extracted information.
-- skeleton · function · L644-L673 — Extracts a skeleton representation of a file, providing a summary and context for its contents.
-- startLine · function · L661-L661 — Calculates the starting line number from a given span, aiding in the extraction of relevant code sections.
-- formatSkeleton · function · L676-L685 — Formats the skeleton result into a string representation for display or output purposes.
-- toTokens · function · L688-L690 — Converts a character count into a token count, facilitating the processing of text for queries.
-- formatAsk · function · L693-L731 — Formats the results of an ask query into a string for presentation, ensuring clarity and usability.
-- savingsFooter · function · L736-L748 — Generates a footer for the ask results that summarizes the savings in terms of file reading costs.
+- AskHit · interface · L27-L40 — Represents a hit in the query results, encapsulating details about a code symbol and its context.
+- AskResult · interface · L46-L63 — Represents the result of an 'ask' query, encapsulating the query details and the hits found.
+- firstProse · function · L66-L73 — Extracts the first meaningful prose line from a body of text, ignoring headings and blank lines.
+- Corpus · interface · L75-L82 — Defines the structure for holding concepts and graph data used in processing queries.
+- loadCorpus · function · L84-L109 — Loads a corpus of concepts and graph data from a specified directory, enabling query processing.
+- score · function · L118-L129 — Calculates a score for a document based on its token counts relative to a query, enhancing relevance ranking.
+- idfFromDf · function · L135-L139 — Computes the inverse document frequency (IDF) from document frequency (DF) data, aiding in scoring relevance.
+- computeIdf · function · L141-L146 — Generates IDF values from document bags, which are used to weight query matches based on term rarity.
+- computeIdfFromIndex · function · L155-L160 — Calculates IDF values using precomputed index data, optimizing the scoring process for queries.
+- bm25 · function · L167-L183 — Implements the BM25 scoring algorithm to rank documents based on term frequency and document length.
+- subjectWords · function · L195-L197 — Tokenizes a query into words while preserving qualified names, facilitating accurate subject resolution.
+- findSubjectNodes · function · L207-L214 — Finds nodes in the graph that match the structural subject of a query, enhancing query resolution.
+- StructuralOutcome · type · L222-L222 — Defines the possible outcomes of a structural query, indicating whether a result was found, a fallthrough note is needed, or if there was no structural intent.
+- fallthroughNoteFor · function · L224-L229 — Generates a note for cases where a structural query falls back to lexical processing, providing user guidance.
+- structural · function · L231-L280 — Processes a structural query to find relationships in the graph, returning relevant results or fallthrough notes.
+- hasTerm · function · L299-L301 — Checks for the presence of a term in a document's token map, aiding in relevance scoring.
+- matchedIdfShare · function · L310-L324 — Calculates the share of query terms matched by a document, weighted by term rarity for relevance assessment.
+- lexical · function · L326-L488 — Handles lexical queries by scoring documents based on term matches and relevance, returning structured results.
+- bodyLen · function · L417-L421 — Calculates the length of the body of a lexical document to ensure it meets certain criteria for processing.
+- AskOptions · interface · L490-L506 — Defines the options available for configuring the ask function, allowing customization of its behavior.
+- parseSpan · function · L510-L514 — Parses a string pointer into its file path and line range components, facilitating source code navigation.
+- sliceSpan · function · L518-L533 — Reads a specified range of lines from a source file, allowing for inlined code snippets in query results.
+- inlineSource · function · L540-L557 — Inlines the source code for the hits found, providing context directly in the results without needing to open files.
+- hitFiles · function · L561-L570 — Extracts a set of unique file paths from the hits, indicating which files are relevant to the query results.
+- baselineFor · function · L575-L578 — Calculates the baseline file size and character count for the hits, providing a measure of the cost of reading the full files.
+- ask · function · L581-L611 — Handles the main logic for processing a query against a directory, returning structured results based on the query type.
+- SkeletonEntry · interface · L615-L622 — Defines the structure of a skeleton entry, which represents a piece of information extracted from a file.
+- SkeletonResult · interface · L624-L630 — Defines the structure of the result returned from the skeleton function, encapsulating the extracted information.
+- skeleton · function · L635-L665 — Extracts a skeleton representation of a file, providing a summary and context for its contents.
+- startLine · function · L652-L652 — Calculates the starting line number from a given span, aiding in the extraction of relevant code sections.
+- formatSkeleton · function · L668-L678 — Formats the skeleton result into a string representation for display or output purposes.
+- toTokens · function · L681-L683 — Converts a character count into a token count, facilitating the processing of text for queries.
+- formatAsk · function · L686-L724 — Formats the results of an ask query into a string for presentation, ensuring clarity and usability.
+- escalationNudge · function · L731-L738 — function escalationNudge(r: AskResult): string
+- askSavingsFooter · function · L743-L755 — function askSavingsFooter(r: AskResult, body: string): string
diff --git a/graft/src/claude/format.md b/graft/src/claude/format.md
index f65abe06..2636e62b 100644
--- a/graft/src/claude/format.md
+++ b/graft/src/claude/format.md
@@ -14,5 +14,5 @@ This file contains functions and types for formatting and rendering status infor
- retrievalTokensSaved · function · L111-L117 — Calculates the number of tokens saved by using a retrieval pack instead of reading files in full, based on the hits and baseline size.
- formatRetrieval · function · L119-L132 — Formats the retrieval results into a string, including details about tokens saved and the estimated size of the retrieval pack.
- relevantRetrieval · function · L152-L163 — Determines if a retrieval pack should be injected based on relevance and novelty, returning the formatted text or null if not applicable.
-- formatOrientation · function · L165-L167 — Creates a formatted string representing the orientation of the repository map, limited to a specified byte budget.
-- renderSubagent · function · L169-L173 — Generates a string representation of a subagent's status, including its query if available, for display purposes.
+- formatOrientation · function · L165-L176 — Creates a formatted string representing the orientation of the repository map, limited to a specified byte budget.
+- renderSubagent · function · L178-L182 — Generates a string representation of a subagent's status, including its query if available, for display purposes.
diff --git a/graft/src/claude/init.md b/graft/src/claude/init.md
index 02da9616..566dc190 100644
--- a/graft/src/claude/init.md
+++ b/graft/src/claude/init.md
@@ -2,5 +2,5 @@
Initializes the Claude environment by setting up necessary directories, configuration files, and shims for the application.
-- InitResult · interface · L9-L15 — Defines the structure of the result returned by the runInit function, encapsulating settings, shims, skill, warnings, and build status.
-- runInit · function · L17-L49 — Initializes the Claude environment by setting up necessary directories, merging settings, creating shims, and optionally building the project.
+- InitResult · interface · L10-L18 — Defines the structure of the result returned by the runInit function, encapsulating settings, shims, skill, warnings, and build status.
+- runInit · function · L20-L57 — Initializes the Claude environment by setting up necessary directories, merging settings, creating shims, and optionally building the project.
diff --git a/graft/src/claude/skill-template.md b/graft/src/claude/skill-template.md
index aad781a4..58d5f3c5 100644
--- a/graft/src/claude/skill-template.md
+++ b/graft/src/claude/skill-template.md
@@ -2,4 +2,4 @@
Provides a structured template for the graft Claude Code skill, enabling efficient onboarding and understanding of the codebase.
-- skillTemplate · function · L6-L76 — Generates a markdown string that serves as a comprehensive guide for using the graft tool effectively within a code repository.
+- skillTemplate · function · L6-L88 — Generates a markdown string that serves as a comprehensive guide for using the graft tool effectively within a code repository.
diff --git a/graft/src/cli.md b/graft/src/cli.md
index 47f8b479..639c76bb 100644
--- a/graft/src/cli.md
+++ b/graft/src/cli.md
@@ -2,8 +2,7 @@
Defines the command-line interface for the graft tool, enabling various operations on the codebase's context graph.
-- GlobalOpts · interface · L48-L54 — Holds the global options for the CLI, allowing configuration of the context graph generation and LLM provider settings.
-- cliConfig · function · L57-L66 — Constructs the configuration object for the engine based on CLI options, ensuring the correct parameters are used for graph generation.
-- engineFrom · function · L68-L70 — Creates an instance of the Graft engine using the current CLI configuration, enabling graph operations.
-- fmt · function · L106-L110 — Formats a record of counts into a human-readable string for console output.
-- traverseAction · function · L287-L293 — Handles traversal commands for graph analysis, allowing users to query relationships between symbols in the codebase.
+- GlobalOpts · interface · L49-L55 — Holds the global options for the CLI, allowing configuration of the context graph generation and LLM provider settings.
+- cliConfig · function · L58-L67 — Constructs the configuration object for the engine based on CLI options, ensuring the correct parameters are used for graph generation.
+- engineFrom · function · L69-L71 — Creates an instance of the Graft engine using the current CLI configuration, enabling graph operations.
+- fmt · function · L107-L111 — Formats a record of counts into a human-readable string for console output.
diff --git a/graft/src/context/savings.md b/graft/src/context/savings.md
new file mode 100644
index 00000000..53ea6afc
--- /dev/null
+++ b/graft/src/context/savings.md
@@ -0,0 +1,7 @@
+# src/context/savings.ts
+
+- Savings · interface · L17-L22 — interface Savings
+- toTokens · function · L25-L27 — function toTokens(chars: number): number
+- fileSizes · function · L32-L37 — function fileSizes(graph: GraphV1): Map<string, number>
+- savingsFor · function · L42-L53 — function savingsFor(graph: GraphV1, paths: Iterable<string>): Savings | undefined
+- savingsFooter · function · L60-L72 — function savingsFooter(body: string, saved: Savings | undefined): string
diff --git a/graft/src/graph/map.md b/graft/src/graph/map.md
index 82bf378c..cf4997a0 100644
--- a/graft/src/graph/map.md
+++ b/graft/src/graph/map.md
@@ -2,18 +2,18 @@
Builds a structured representation of a repository's file and symbol organization based on their relationships, facilitating easier navigation and understanding of the codebase.
-- Hub · interface · L25-L31 — Defines the structure of a hub in the repository map, capturing its essential attributes for identification and ranking.
-- DirEntry · interface · L33-L39 — Represents a directory entry in the repository map, summarizing its contents and associated hubs for better navigation.
-- RepoMap · interface · L41-L49 — Encapsulates the entire repository map structure, providing a comprehensive overview of files, symbols, and their relationships.
-- BuildRepoMapOptions · interface · L51-L58 — Specifies options for building the repository map, allowing customization of directory and hub limits.
-- dirKey · function · L70-L73 — Generates a directory key based on the specified depth, facilitating the grouping of files in the repository map.
-- computeInDegree · function · L78-L85 — Calculates the in-degree of nodes in the graph, determining the number of incoming edges for each target, which is crucial for identifying hubs.
-- topHubs · function · L90-L96 — Identifies the top hubs based on in-degree, ensuring that only significant nodes are included in the repository map.
-- sortedLanguages · function · L98-L105 — Sorts and deduplicates the programming languages used in the repository, enhancing the metadata of the repository map.
-- buildRepoMap · function · L112-L180 — Constructs the repository map from a given graph, organizing files and symbols into a structured format for easy access.
-- depthFor · function · L137-L137 — Determines the depth for a given path, influencing how files are grouped in the repository map based on the split segment.
-- basenameOf · function · L184-L187 — Extracts the base name from a file path, simplifying the representation of file names in the output.
-- formatDirHub · function · L189-L191 — Formats a hub's information for display, providing a user-friendly representation of its attributes.
-- formatDirLine · function · L193-L198 — Formats a directory entry for display, summarizing its contents and associated hubs in a readable format.
-- formatHotspot · function · L200-L202 — Formats a hotspot's information for display, detailing its attributes in a clear manner.
-- formatRepoMap · function · L210-L223 — Renders the repository map as a human-readable string, summarizing its contents and structure for easy understanding.
+- Hub · interface · L26-L32 — Defines the structure of a hub in the repository map, capturing its essential attributes for identification and ranking.
+- DirEntry · interface · L34-L40 — Represents a directory entry in the repository map, summarizing its contents and associated hubs for better navigation.
+- RepoMap · interface · L42-L53 — Encapsulates the entire repository map structure, providing a comprehensive overview of files, symbols, and their relationships.
+- BuildRepoMapOptions · interface · L55-L62 — Specifies options for building the repository map, allowing customization of directory and hub limits.
+- dirKey · function · L74-L77 — Generates a directory key based on the specified depth, facilitating the grouping of files in the repository map.
+- computeInDegree · function · L82-L89 — Calculates the in-degree of nodes in the graph, determining the number of incoming edges for each target, which is crucial for identifying hubs.
+- topHubs · function · L94-L100 — Identifies the top hubs based on in-degree, ensuring that only significant nodes are included in the repository map.
+- sortedLanguages · function · L102-L109 — Sorts and deduplicates the programming languages used in the repository, enhancing the metadata of the repository map.
+- buildRepoMap · function · L116-L185 — Constructs the repository map from a given graph, organizing files and symbols into a structured format for easy access.
+- depthFor · function · L141-L141 — Determines the depth for a given path, influencing how files are grouped in the repository map based on the split segment.
+- basenameOf · function · L189-L192 — Extracts the base name from a file path, simplifying the representation of file names in the output.
+- formatDirHub · function · L194-L196 — Formats a hub's information for display, providing a user-friendly representation of its attributes.
+- formatDirLine · function · L198-L203 — Formats a directory entry for display, summarizing its contents and associated hubs in a readable format.
+- formatHotspot · function · L205-L207 — Formats a hotspot's information for display, detailing its attributes in a clear manner.
+- formatRepoMap · function · L215-L229 — Renders the repository map as a human-readable string, summarizing its contents and structure for easy understanding.
diff --git a/graft/src/graph/traverse-cli.md b/graft/src/graph/traverse-cli.md
index 4cff1d70..605738ef 100644
--- a/graft/src/graph/traverse-cli.md
+++ b/graft/src/graph/traverse-cli.md
@@ -2,15 +2,15 @@
This file implements CLI commands for traversing a graph to find callers, callees, and impact of symbols, ensuring a consistent user experience across different commands.
-- TraverseKind · type · L17-L17 — Defines the types of traversal operations available for graph navigation, ensuring type safety in CLI commands.
-- TraverseCliOptions · interface · L19-L26 — Specifies options for the CLI traversal commands, allowing customization of input, output format, and traversal depth.
-- edgesFor · function · L31-L35 — Determines the edges to traverse in the graph based on the specified kind, facilitating the retrieval of relevant connections for a node.
-- headerOf · function · L41-L43 — Generates a formatted header string for a node, providing essential information for display in CLI output.
-- hitLine · function · L45-L50 — Formats a single hit line for display, showing the relationship and details of a node in the context of the traversal.
-- looseNoteFor · function · L54-L58 — Creates a user-friendly message when no edges are found for a symbol, guiding users on next steps.
-- SymbolJson · interface · L60-L66 — Defines the structure for symbol metadata in JSON format, ensuring consistent representation of symbols in output.
-- MatchJson · interface · L68-L72 — Defines the structure for matching results in JSON format, encapsulating symbol information and associated hits.
-- HitJson · interface · L74-L82 — Defines the structure for hit details in JSON format, providing information about the relationship and depth of hits.
-- symbolJson · function · L84-L86 — Converts a node into a standardized JSON format, facilitating consistent output for symbol information.
-- hitJson · function · L88-L97 — Transforms an EdgeHit into a JSON format, ensuring structured output for hits in the traversal results.
-- runTraverseCommand · function · L105-L155 — Executes the traversal command based on user input, handling graph resolution and output formatting, while managing errors effectively.
+- CallersCliOptions · interface · L21-L30 — interface CallersCliOptions
+- headerOf · function · L38-L40 — Generates a formatted header string for a node, providing essential information for display in CLI output.
+- hitLine · function · L44-L49 — Formats a single hit line for display, showing the relationship and details of a node in the context of the traversal.
+- callersSavings · function · L55-L65 — function callersSavings( graph: GraphV1, results: { symbol: NodeV1; hits: EdgeHit[] }[], ): Savings | undefined
+- looseNoteFor · function · L68-L72 — Creates a user-friendly message when no edges are found for a symbol, guiding users on next steps.
+- SymbolJson · interface · L74-L80 — Defines the structure for symbol metadata in JSON format, ensuring consistent representation of symbols in output.
+- MatchJson · interface · L82-L86 — Defines the structure for matching results in JSON format, encapsulating symbol information and associated hits.
+- HitJson · interface · L88-L96 — Defines the structure for hit details in JSON format, providing information about the relationship and depth of hits.
+- symbolJson · function · L98-L100 — Converts a node into a standardized JSON format, facilitating consistent output for symbol information.
+- hitJson · function · L102-L111 — Transforms an EdgeHit into a JSON format, ensuring structured output for hits in the traversal results.
+- resolveDirection · function · L114-L119 — function resolveDirection(raw: string | undefined): Direction
+- runCallersCommand · function · L127-L182 — function runCallersCommand(query: string, dir: string, opts: CallersCliOptions): void
diff --git a/graft/src/graph/traverse.md b/graft/src/graph/traverse.md
index e4bab1a5..0658fb00 100644
--- a/graft/src/graph/traverse.md
+++ b/graft/src/graph/traverse.md
@@ -2,14 +2,16 @@
Centralizes the logic for resolving symbol queries in a graph, enabling consistent identification of nodes based on various naming conventions and paths.
-- SymbolMatch · interface · L19-L21 — Represents a resolved match for a symbol search in the graph, allowing for future disambiguation of metadata.
-- ResolveSymbolOptions · interface · L23-L26 — Defines options for narrowing down symbol resolution candidates based on path substring filtering.
-- resolveSymbol · function · L47-L72 — Resolves a query string to all matching nodes in the graph, handling various naming conventions and fallbacks.
-- symbolMatches · function · L74-L83 — Filters nodes in the graph to find matches based on a case-insensitive query, considering both name and id suffixes.
-- EdgeHit · interface · L88-L93 — Represents a traversed edge in the graph, capturing the relationship and depth of the connection to a node.
-- callersOf · function · L96-L104 — Finds all edges leading to a specified symbol, indicating which nodes directly call it.
-- calleesOf · function · L107-L115 — Identifies all edges originating from a specified symbol, showing which nodes it directly calls.
-- impactOf · function · L123-L125 — Performs a breadth-first search to determine the impact of changes to a symbol, identifying affected nodes up to a specified depth.
-- impactOfMany · function · L141-L172 — Generalizes the impact analysis to multiple seed nodes, aggregating the results of their incoming edges.
-- symbolsInFile · function · L176-L178 — Retrieves all symbols defined in a specific file, filtering out file nodes.
-- impactOfFile · function · L189-L191 — Aggregates the impact analysis for a file node and its defined symbols, ensuring all dependents are considered.
+- Direction · type · L21-L21 — type Direction = "in" | "out";
+- SymbolMatch · interface · L25-L27 — Represents a resolved match for a symbol search in the graph, allowing for future disambiguation of metadata.
+- ResolveSymbolOptions · interface · L29-L32 — Defines options for narrowing down symbol resolution candidates based on path substring filtering.
+- resolveSymbol · function · L53-L78 — Resolves a query string to all matching nodes in the graph, handling various naming conventions and fallbacks.
+- symbolMatches · function · L80-L89 — Filters nodes in the graph to find matches based on a case-insensitive query, considering both name and id suffixes.
+- EdgeHit · interface · L94-L99 — Represents a traversed edge in the graph, capturing the relationship and depth of the connection to a node.
+- callersOf · function · L102-L110 — Finds all edges leading to a specified symbol, indicating which nodes directly call it.
+- calleesOf · function · L113-L121 — Identifies all edges originating from a specified symbol, showing which nodes it directly calls.
+- impactOf · function · L129-L131 — Performs a breadth-first search to determine the impact of changes to a symbol, identifying affected nodes up to a specified depth.
+- impactOfMany · function · L149-L184 — Generalizes the impact analysis to multiple seed nodes, aggregating the results of their incoming edges.
+- symbolsInFile · function · L188-L190 — Retrieves all symbols defined in a specific file, filtering out file nodes.
+- impactOfFile · function · L201-L203 — Aggregates the impact analysis for a file node and its defined symbols, ensuring all dependents are considered.
+- edgeWalk · function · L218-L222 — function edgeWalk(graph: GraphV1, node: NodeV1, direction: Direction, depth: number): EdgeHit[]
diff --git a/graft/src/hosts/instructions.md b/graft/src/hosts/instructions.md
index b0555561..70e378fb 100644
--- a/graft/src/hosts/instructions.md
+++ b/graft/src/hosts/instructions.md
@@ -2,7 +2,7 @@
This file provides Graft instructions for navigating and utilizing the context graph effectively.
-- instructionBody · function · L6-L42 — Generates the main instructional content for using the Graft context graph.
-- cursorRule · function · L44-L51 — Defines a rule to always apply the Graft context graph before exploring source code.
-- kiroSteering · function · L53-L59 — Specifies a rule for always including the Graft context graph in the workflow.
-- windsurfRule · function · L61-L64 — Provides a rule that incorporates the Graft context graph into its logic.
+- instructionBody · function · L6-L43 — Generates the main instructional content for using the Graft context graph.
+- cursorRule · function · L45-L52 — Defines a rule to always apply the Graft context graph before exploring source code.
+- kiroSteering · function · L54-L60 — Specifies a rule for always including the Graft context graph in the workflow.
+- windsurfRule · function · L62-L65 — Provides a rule that incorporates the Graft context graph into its logic.
diff --git a/graft/src/mcp/tools.md b/graft/src/mcp/tools.md
index 00236aaf..450f5874 100644
--- a/graft/src/mcp/tools.md
+++ b/graft/src/mcp/tools.md
@@ -1,6 +1,6 @@
# src/mcp/tools.ts
-- ToolDef · interface · L18-L22 — Defines the structure for tool definitions used in the MCP tools, ensuring consistent input schema and metadata for each tool.
-- unknownSymbolText · function · L29-L31 — Generates an error message for an unknown symbol query, guiding users to check their input or build the graph.
-- renderMatches · function · L137-L147 — Formats and renders the results of graph traversal matches, providing a structured output for users to understand symbol relationships.
-- callTool · function · L149-L242 — Handles the invocation of various tools based on user input, managing errors and returning formatted results for different graph operations.
+- ToolDef · interface · L19-L23 — Defines the structure for tool definitions used in the MCP tools, ensuring consistent input schema and metadata for each tool.
+- unknownSymbolText · function · L27-L29 — Generates an error message for an unknown symbol query, guiding users to check their input or build the graph.
+- renderMatches · function · L117-L132 — Formats and renders the results of graph traversal matches, providing a structured output for users to understand symbol relationships.
+- callTool · function · L134-L215 — Handles the invocation of various tools based on user input, managing errors and returning formatted results for different graph operations.
diff --git a/graft/src/search/grep-cli.md b/graft/src/search/grep-cli.md
index 3f649c39..3d1aa4a2 100644
--- a/graft/src/search/grep-cli.md
+++ b/graft/src/search/grep-cli.md
@@ -2,11 +2,11 @@
This file provides the command-line interface for the grep functionality, formatting results for user-friendly output.
-- GrepCliOptions · interface · L15-L22 — Defines options for the grep command-line interface, allowing customization of search behavior.
-- groupHeader · function · L24-L27 — Generates a header string for a group of grep results, summarizing the group's metadata.
-- formatGroup · function · L29-L33 — Formats a group of grep results into a human-readable string, including hit lines.
-- formatGrepHeader · function · L36-L39 — Creates a header for the grep results, summarizing the total hits and files searched.
-- truncationNote · function · L42-L49 — Generates a note about any truncation in the grep results, indicating unreadable files or additional hits beyond the cap.
-- formatGrepResult · function · L53-L59 — Compiles the full human-readable report of grep results, including headers and formatted groups.
-- zeroHitNote · function · L69-L74 — Provides a detailed message for zero-hit results, explaining the absence of matches and potential issues.
-- runGrepCommand · function · L83-L112 — Executes the grep command, handling graph resolution, pattern searching, and output formatting.
+- GrepCliOptions · interface · L16-L23 — Defines options for the grep command-line interface, allowing customization of search behavior.
+- groupHeader · function · L25-L28 — Generates a header string for a group of grep results, summarizing the group's metadata.
+- formatGroup · function · L30-L34 — Formats a group of grep results into a human-readable string, including hit lines.
+- formatGrepHeader · function · L37-L40 — Creates a header for the grep results, summarizing the total hits and files searched.
+- truncationNote · function · L43-L50 — Generates a note about any truncation in the grep results, indicating unreadable files or additional hits beyond the cap.
+- formatGrepResult · function · L54-L62 — Compiles the full human-readable report of grep results, including headers and formatted groups.
+- zeroHitNote · function · L72-L77 — Provides a detailed message for zero-hit results, explaining the absence of matches and potential issues.
+- runGrepCommand · function · L86-L115 — Executes the grep command, handling graph resolution, pattern searching, and output formatting.
diff --git a/graft/src/search/grep.md b/graft/src/search/grep.md
index b750f445..acb7cf89 100644
--- a/graft/src/search/grep.md
+++ b/graft/src/search/grep.md
@@ -2,16 +2,16 @@
This file implements a regex search over indexed files in a graph, grouping results by their enclosing symbols and ranking them by their importance based on incoming edges.
-- GrepHit · interface · L17-L21 — Represents a single hit found during the grep search, including the line number and trimmed text of the line.
-- GrepSymbolRef · interface · L23-L31 — Defines a reference to a symbol in the graph, including its qualified name and span, to facilitate grouping grep hits by their enclosing symbols.
-- GrepGroup · interface · L33-L42 — Groups grep hits by their enclosing symbol, providing context such as the symbol's in-degree and the path of the file.
-- GrepResult · interface · L44-L58 — Encapsulates the results of a grep operation, including the pattern searched, total hits, and grouped results.
-- GrepOptions · interface · L60-L69 — Holds options for configuring the grep search, such as case sensitivity and maximum hits to collect.
-- escapeRegExp · function · L75-L77 — Escapes special characters in a string to create a safe regex pattern for searching.
-- spanBounds · function · L79-L83 — Extracts the start and end line numbers from a span string, returning null if the format is invalid.
-- SymbolSpan · interface · L85-L89 — Represents a span of a symbol in the graph, including its start and end lines, to assist in finding enclosing symbols.
-- symbolsOf · function · L93-L102 — Retrieves and sorts the symbols of a given file in the graph, based on their span start lines.
-- enclosingSymbol · function · L108-L115 — Finds the innermost symbol that contains a specified line number, returning the corresponding node from the graph.
-- computeInDegree · function · L119-L126 — Calculates the incoming edge count for each symbol in the graph, which is used to rank grep hits by importance.
-- toSymbolRef · function · L128-L131 — Converts a node in the graph to a GrepSymbolRef, providing a structured representation of the symbol.
-- grepGraph · function · L133-L195 — Performs the grep search on the graph, collecting and returning results based on the specified pattern and options.
+- GrepHit · interface · L18-L22 — Represents a single hit found during the grep search, including the line number and trimmed text of the line.
+- GrepSymbolRef · interface · L24-L32 — Defines a reference to a symbol in the graph, including its qualified name and span, to facilitate grouping grep hits by their enclosing symbols.
+- GrepGroup · interface · L34-L43 — Groups grep hits by their enclosing symbol, providing context such as the symbol's in-degree and the path of the file.
+- GrepResult · interface · L45-L62 — Encapsulates the results of a grep operation, including the pattern searched, total hits, and grouped results.
+- GrepOptions · interface · L64-L73 — Holds options for configuring the grep search, such as case sensitivity and maximum hits to collect.
+- escapeRegExp · function · L79-L81 — Escapes special characters in a string to create a safe regex pattern for searching.
+- spanBounds · function · L83-L87 — Extracts the start and end line numbers from a span string, returning null if the format is invalid.
+- SymbolSpan · interface · L89-L93 — Represents a span of a symbol in the graph, including its start and end lines, to assist in finding enclosing symbols.
+- symbolsOf · function · L97-L106 — Retrieves and sorts the symbols of a given file in the graph, based on their span start lines.
+- enclosingSymbol · function · L112-L119 — Finds the innermost symbol that contains a specified line number, returning the corresponding node from the graph.
+- computeInDegree · function · L123-L130 — Calculates the incoming edge count for each symbol in the graph, which is used to rank grep hits by importance.
+- toSymbolRef · function · L132-L135 — Converts a node in the graph to a GrepSymbolRef, providing a structured representation of the symbol.
+- grepGraph · function · L137-L200 — Performs the grep search on the graph, collecting and returning results based on the specified pattern and options.
diff --git a/graft/test/graph-traverse-cli.test.md b/graft/test/graph-traverse-cli.test.md
index 3bce7e79..fb87e227 100644
--- a/graft/test/graph-traverse-cli.test.md
+++ b/graft/test/graph-traverse-cli.test.md
@@ -2,5 +2,5 @@
This file contains tests for the CLI commands related to graph traversal, ensuring correct functionality and output for various scenarios.
-- builtRepo · function · L16-L27 — Sets up a temporary repository with a sample math module for testing CLI commands.
-- runCli · function · L29-L40 — Executes the CLI command with given arguments and captures the output and status code.
+- builtRepo · function · L17-L28 — Sets up a temporary repository with a sample math module for testing CLI commands.
+- runCli · function · L30-L41 — Executes the CLI command with given arguments and captures the output and status code.
diff --git a/graft/testing-and-validation.md b/graft/testing-and-validation.md
index ef5754d0..e6487532 100644
--- a/graft/testing-and-validation.md
+++ b/graft/testing-and-validation.md
@@ -160,10 +160,10 @@ covers:
at: 'test/graph-resolve-typed.test.ts:L6-L10'
- symbol: builtRepo
kind: function
- at: 'test/graph-traverse-cli.test.ts:L16-L27'
+ at: 'test/graph-traverse-cli.test.ts:L17-L28'
- symbol: runCli
kind: function
- at: 'test/graph-traverse-cli.test.ts:L29-L40'
+ at: 'test/graph-traverse-cli.test.ts:L30-L41'
---
<!-- context:generated:start -->
## Summary
diff --git a/package.json b/package.json
index dee23492..cea0abbd 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "@nanonets/graft",
- "version": "0.5.1",
+ "version": "0.6.0",
"description": "Build a repo's context graph as a folder of linked markdown files that live in the repo and stay in sync with the code through git.",
"keywords": [
"ai",
diff --git a/src/ask/ask.ts b/src/ask/ask.ts
index f08af6c2..c6bfbfa7 100644
--- a/src/ask/ask.ts
+++ b/src/ask/ask.ts
@@ -17,6 +17,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
import { join, resolve } from "node:path";
import matter from "gray-matter";
import { contextDirFor } from "../context/node-file.js";
+import { savingsFooter, savingsFor, type Savings } from "../context/savings.js";
import { loadGraphCached, loadAskIndexCached } from "../graph/load.js";
import { resolveSymbol } from "../graph/traverse.js";
import type { EdgeV1, GraphV1, NodeV1, Relation } from "../graph/types.js";
@@ -573,19 +574,7 @@ function hitFiles(hits: AskHit[]): Set<string> {
* (a pre-upgrade index) — the caller then just omits the estimate. */
function baselineFor(hits: AskHit[], graph: GraphV1 | null): AskResult["saved"] | undefined {
if (!graph) return undefined;
- const size = new Map<string, number>();
- for (const n of graph.nodes)
- if (n.kind === "file" && typeof n.chars === "number") size.set(n.path, n.chars);
-
- let baselineChars = 0;
- let files = 0;
- for (const path of hitFiles(hits)) {
- const c = size.get(path);
- if (c === undefined) continue;
- baselineChars += c;
- files++;
- }
- return files > 0 ? { files, baselineChars } : undefined;
+ return savingsFor(graph, hitFiles(hits));
}
/** Answer a query from the graft/ graph at `dir`. Deterministic, $0. */
@@ -636,6 +625,8 @@ export interface SkeletonResult {
file: string;
entries: SkeletonEntry[];
note?: string;
+ /** Tokens-saved baseline: this file read whole vs the signatures-only view. */
+ saved?: Savings;
}
/** Signatures-only view of one file, straight from the wiring graph — the
@@ -669,6 +660,7 @@ export function skeleton(dir: string, file: string, opts: { contextDir?: string
signature: n.signature,
summary: n.summary?.split("\n")[0].trim() || undefined,
})),
+ saved: savingsFor(graph, [defs[0].path]),
};
}
@@ -681,7 +673,8 @@ export function formatSkeleton(r: SkeletonResult): string {
const sum = e.summary ? ` — ${e.summary}` : "";
return `- ${e.span} ${e.kind} ${e.name}${sig}${sum}`;
});
- return `${head}\n${lines.join("\n")}\n`;
+ const body = `${head}\n${lines.join("\n")}`;
+ return body + savingsFooter(body, r.saved) + "\n";
}
/** Rough tokens for a byte length (≈ 4 chars/token; good enough for an estimate). */
@@ -727,7 +720,7 @@ export function formatAsk(r: AskResult): string {
});
}
const body = lines.join("\n").trimEnd();
- return body + savingsFooter(r, body) + escalationNudge(r) + "\n";
+ return body + askSavingsFooter(r, body) + escalationNudge(r) + "\n";
}
/** When a lexical `ask` returns thin/no results, the productive next move is a
@@ -747,7 +740,7 @@ function escalationNudge(r: AskResult): string {
/** The one-line token-saving estimate `ask` appends in retriever mode, so the
* agent gets the number for free in the tool output — no extra work on its end.
* `packChars` is measured from the rendered body: exactly what the agent reads. */
-function savingsFooter(r: AskResult, body: string): string {
+function askSavingsFooter(r: AskResult, body: string): string {
if (!r.saved || r.saved.baselineChars <= 0) return "";
const pack = toTokens(body.length);
const base = toTokens(r.saved.baselineChars);
diff --git a/src/claude/init.ts b/src/claude/init.ts
index aa71e51b..df118375 100644
--- a/src/claude/init.ts
+++ b/src/claude/init.ts
@@ -5,11 +5,14 @@ import { mergeGraftSettings } from './settings-merge.js';
import { statuslineShim, hooksShim } from './shim-template.js';
import { skillTemplate } from './skill-template.js';
import { claudeDistDir } from './paths.js';
+import { mergeJsonKey, SERVER_ENTRY, type McpWrite } from '../hosts/mcp-config.js';
export interface InitResult {
settingsPath: string;
shims: string[];
skill: string;
+ /** the `.mcp.json` write registering the graft MCP server for Claude Code. */
+ mcp: McpWrite;
warnings: string[];
built: boolean;
}
@@ -37,6 +40,11 @@ export function runInit(dir: string, opts: { build?: boolean; cliPath?: string }
const skillPath = join(skillDir, 'SKILL.md');
writeFileSync(skillPath, skillTemplate());
+ // Register the graft MCP server in the project's .mcp.json so Claude Code
+ // exposes graft_ask/graft_callers/etc. as tools — the same keyed merge the
+ // other hosts use (existing servers preserved; unparseable files skipped).
+ const mcp = mergeJsonKey('claude', join(dir, '.mcp.json'), 'mcpServers', SERVER_ENTRY);
+
let built = false;
const wiring = join(dir, 'graft', '.graph', 'wiring.json');
if (opts.build !== false && opts.cliPath && !existsSync(wiring)) {
@@ -45,5 +53,5 @@ export function runInit(dir: string, opts: { build?: boolean; cliPath?: string }
built = true;
} catch { /* build best-effort; user can run `graft build` manually */ }
}
- return { settingsPath, shims: [sl, hk], skill: skillPath, warnings, built };
+ return { settingsPath, shims: [sl, hk], skill: skillPath, mcp, warnings, built };
}
diff --git a/src/claude/skill-template.ts b/src/claude/skill-template.ts
index 57d31e92..6e88ce36 100644
--- a/src/claude/skill-template.ts
+++ b/src/claude/skill-template.ts
@@ -31,9 +31,10 @@ same understanding costs thousands.
ask is top-N and WILL miss instances; grep is the tool for "find them all".
- **A file's whole API surface** → \`graft skeleton <file>\` — every signature in
~200 tokens. One call beats several asks when you just need "what's in here".
-- **Who uses / what breaks if I change X** → \`graft callers <symbol>\` or
- \`graft impact <symbol>\`; what X itself depends on → \`graft callees <symbol>\`.
- Run one of these before editing a symbol.
+- **Who uses / what breaks if I change X** → \`graft callers <symbol>\` (add
+ \`--depth N\` to walk transitively for the full blast radius); what X itself
+ depends on → \`graft callers <symbol> --direction out\`. Run one before
+ editing a symbol.
- **First contact with an unfamiliar repo** → \`graft map\` — token-budgeted
orientation (dir clusters, hubs, hotspots). Read the hub cards it names rather
than asking per subsystem.
@@ -62,13 +63,19 @@ exhaustive where it matters, so reach for them first.
that is expected, not a graft failure.
**Precise graph modes** — for structural questions, skip ranking and go
-straight to precomputed edges:
+straight to precomputed edges. It's all one command, \`graft callers\`:
-- \`graft callers <symbol>\` / \`graft callees <symbol>\` — who breaks if this
- changes / what does this call — precomputed edges, exact answers; structural
- phrasing inside ask ("who calls X") routes here too.
-- \`graft impact <symbol> [-d N]\` — BFS over incoming edges out to depth N: the
- full blast radius of a change.
+- \`graft callers <symbol>\` — who calls/references this (exact edges, not text);
+ structural phrasing inside ask ("who calls X") routes here too.
+- \`graft callers <symbol> --direction out\` — the reverse: what this symbol
+ itself calls/depends on (the old \`callees\`).
+- \`graft callers <symbol> --depth N\` — walk transitively out to depth N for the
+ full blast radius of a change (the old \`impact\`).
+
+When the graft MCP server is connected, the same operations are exposed as
+tools — \`graft_ask\`, \`graft_callers\` (with \`direction\`/\`depth\`),
+\`graft_grep\`, \`graft_skeleton\`, \`graft_map\` — prefer whichever surface is
+available.
If a returned span is truncated ("+N more lines"), open the file at that exact
range before finalizing.
diff --git a/src/cli.ts b/src/cli.ts
index 6f840004..14408132 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -7,10 +7,11 @@
* check fail if graft/ has drifted from the code — for CI.
* viz serve the interactive graph viewer.
* mcp serve the graph over MCP (stdio) for coding agents.
- * callers / callees / impact precise graph traversal for a symbol ($0, no LLM).
+ * callers precise graph traversal for a symbol ($0, no LLM); --direction out = callees, --depth N = blast radius.
+ * skeleton signatures-only view of one file ($0, no LLM).
* grep regex search over indexed files, grouped by enclosing symbol, ranked by coupling ($0, no LLM).
* map token-budgeted repo orientation — dir clusters, hubs, hotspots ($0, no LLM).
- * init set up the Claude Code integration (.claude/ statusline + hooks) in this repo.
+ * init set up the Claude Code integration (.claude/ statusline + hooks + MCP) in this repo.
*
* Git is the sync: commit graft/ and anyone who clones the repo has the
* graph, with no setup.
@@ -275,7 +276,7 @@ program
program
.command("mcp")
- .description("Serve the graph over MCP (stdio) — exposes graft_ask / graft_check / graft_blast_radius as tools")
+ .description("Serve the graph over MCP (stdio) — exposes graft_ask, graft_callers, graft_grep, graft_skeleton, graft_map and graft_check as tools")
.argument("[dir]", "repository root", ".")
.action(async (dir: string) => {
const { resolve } = await import("node:path");
@@ -284,41 +285,34 @@ program
startMcpServer(resolve(dir), globalOpts.dir);
});
-function traverseAction(kind: import("./graph/traverse-cli.js").TraverseKind) {
- return async (symbol: string, dir: string, opts: { in?: string; json?: boolean; depth?: string }) => {
- const { runTraverseCommand } = await import("./graph/traverse-cli.js");
- const globalOpts = program.opts<{ dir?: string }>();
- runTraverseCommand(kind, symbol, dir, { in: opts.in, json: opts.json, depth: opts.depth, globalDir: globalOpts.dir });
- };
-}
-
program
.command("callers")
- .description("Who calls/references/imports/implements/extends a symbol ($0, no LLM)")
- .argument("<symbol>", "bare name, qualified (Class.method), or package-qualified (pkg.Fn)")
- .argument("[dir]", "repository root", ".")
- .option("--in <path>", "narrow matches to nodes whose path contains this substring")
- .option("--json", "output as JSON")
- .action(traverseAction("callers"));
-
-program
- .command("callees")
- .description("What a symbol calls/references/imports/implements/extends ($0, no LLM)")
- .argument("<symbol>", "bare name, qualified (Class.method), or package-qualified (pkg.Fn)")
- .argument("[dir]", "repository root", ".")
- .option("--in <path>", "narrow matches to nodes whose path contains this substring")
- .option("--json", "output as JSON")
- .action(traverseAction("callees"));
-
-program
- .command("impact")
- .description("BFS over incoming edges — who breaks if this symbol changes ($0, no LLM)")
+ .description(
+ "Who calls/references a symbol ($0, no LLM). --direction out gives callees (what it calls); --depth N walks transitively for full blast radius",
+ )
.argument("<symbol>", "bare name, qualified (Class.method), or package-qualified (pkg.Fn)")
.argument("[dir]", "repository root", ".")
- .option("-d, --depth <n>", "max BFS depth (default 2)")
+ .option("--direction <in|out>", 'edge direction: "in" = callers (default), "out" = callees')
+ .option("-d, --depth <n>", "walk transitively up to N hops for blast radius (default 1)")
.option("--in <path>", "narrow matches to nodes whose path contains this substring")
.option("--json", "output as JSON")
- .action(traverseAction("impact"));
+ .action(
+ async (
+ symbol: string,
+ dir: string,
+ opts: { direction?: string; depth?: string; in?: string; json?: boolean },
+ ) => {
+ const { runCallersCommand } = await import("./graph/traverse-cli.js");
+ const globalOpts = program.opts<{ dir?: string }>();
+ runCallersCommand(symbol, dir, {
+ direction: opts.direction,
+ depth: opts.depth,
+ in: opts.in,
+ json: opts.json,
+ globalDir: globalOpts.dir,
+ });
+ },
+ );
program
.command("grep")
@@ -386,7 +380,7 @@ program
program
.command("init")
- .description("Wire Graft into the AI coding agents used with this repo (instruction files; full hooks + statusline for Claude Code)")
+ .description("Wire Graft into the AI coding agents used with this repo (instruction files + MCP server; full hooks + statusline + MCP for Claude Code)")
.argument("[dir]", "target repo directory", ".")
.option("--no-build", "skip building the graph (wire files only)")
.option("--agents <ids...>", `only these agents (${hostIds().join(", ")}, claude)`)
@@ -420,6 +414,12 @@ program
console.error(`✓ wrote ${res.settingsPath}`);
for (const s of res.shims) console.error(`✓ wrote ${s}`);
console.error(`✓ wrote ${res.skill}`);
+ if (res.mcp.action === "skipped-unparseable")
+ console.error(`⚠ .mcp.json: ${res.mcp.path} left unchanged (not valid JSON) — add the graft server manually`);
+ else if (res.mcp.action === "unchanged")
+ console.error(`· mcp claude: ${res.mcp.path} (already registered)`);
+ else
+ console.error(`✓ mcp claude: ${res.mcp.path} (${res.mcp.action}) — restart Claude Code to load the graft MCP server`);
console.error(res.built ? "✓ built the graph (graft build)" : "· skipped graph build");
for (const w of res.warnings) console.error(`⚠ ${w}`);
}
diff --git a/src/context/savings.ts b/src/context/savings.ts
new file mode 100644
index 00000000..ec9327f8
--- /dev/null
+++ b/src/context/savings.ts
@@ -0,0 +1,72 @@
+/**
+ * Shared "tokens saved" estimate for every retrieval-style graft command.
+ *
+ * The model is always the same: baseline (what you'd have read otherwise, in
+ * full) − this output (what graft handed you). The baseline is measured from
+ * the `chars` the build stored on each file node, so it costs nothing and is
+ * honest about the alternative — opening the files whole. When no file in the
+ * baseline has a known size (a pre-`chars` graph), the estimate is omitted
+ * rather than faked.
+ *
+ * `graft ask` keeps its own footer (it carries an escalation nudge and feeds
+ * the session saved-token counter); everything else — skeleton, grep, callers,
+ * map — routes through {@link savingsFor} + {@link savingsFooter} here.
+ */
+import type { GraphV1 } from '../graph/types.js';
+
+export interface Savings {
+ /** How many source files the baseline covers. */
+ files: number;
+ /** Total chars of those files — the "read them whole" cost. */
+ baselineChars: number;
+}
+
+/** Rough tokens for a byte length (≈ 4 chars/token; good enough for an estimate). */
+export function toTokens(chars: number): number {
+ return Math.round(chars / 4);
+}
+
+/** path → char size, from the file nodes the build sized. Skips nodes with no
+ * `chars` (pre-upgrade graphs), so an old index just yields a smaller baseline
+ * rather than a wrong one. */
+function fileSizes(graph: GraphV1): Map<string, number> {
+ const m = new Map<string, number>();
+ for (const n of graph.nodes)
+ if (n.kind === 'file' && typeof n.chars === 'number') m.set(n.path, n.chars);
+ return m;
+}
+
+/** Baseline = whole size of the distinct `paths`, summed from file-node sizes.
+ * Returns undefined when not a single path has a known size — the caller then
+ * omits the estimate instead of claiming a bogus one. */
+export function savingsFor(graph: GraphV1, paths: Iterable<string>): Savings | undefined {
+ const sizes = fileSizes(graph);
+ let baselineChars = 0;
+ let files = 0;
+ for (const p of new Set(paths)) {
+ const c = sizes.get(p);
+ if (c === undefined) continue;
+ baselineChars += c;
+ files++;
+ }
+ return files > 0 ? { files, baselineChars } : undefined;
+}
+
+/** The one-line footer a command appends to its text output, so the agent gets
+ * the number for free — no extra tool call. `body` is the exact rendered output
+ * the agent reads (the pack). Returns "" when there's nothing honest to claim:
+ * no baseline, or the output isn't actually smaller than reading the files
+ * (tiny files, where the pointers cost more than the source). */
+export function savingsFooter(body: string, saved: Savings | undefined): string {
+ if (!saved || saved.baselineChars <= 0) return '';
+ const pack = toTokens(body.length);
+ const base = toTokens(saved.baselineChars);
+ if (base <= pack) return '';
+ const delta = base - pack;
+ const pct = Math.round((delta / base) * 100);
+ return (
+ `\n\n[graft] tokens saved ≈ ${delta.toLocaleString()} (${pct}%) — this output ≈ ` +
+ `${pack.toLocaleString()} tok vs reading the ${saved.files} file(s) it covers whole ≈ ` +
+ `${base.toLocaleString()} tok (estimate).`
+ );
+}
diff --git a/src/graph/map.ts b/src/graph/map.ts
index eb579566..078bdd4a 100644
--- a/src/graph/map.ts
+++ b/src/graph/map.ts
@@ -21,6 +21,7 @@
import type { GraphV1, NodeV1 } from "./types.js";
import { languageOf } from "./extract.js";
import { WALK_RELATIONS } from "./relations.js";
+import { savingsFooter, savingsFor, type Savings } from "../context/savings.js";
export interface Hub {
name: string;
@@ -46,6 +47,9 @@ export interface RepoMap {
hotspots: Hub[];
/** Directory groups beyond the `maxDirs` cap — never silently dropped. */
dropped: number;
+ /** Tokens-saved baseline: every indexed file read whole — the cost of
+ * orienting by reading the repo instead of this map. */
+ saved?: Savings;
}
export interface BuildRepoMapOptions {
@@ -176,6 +180,7 @@ export function buildRepoMap(graph: GraphV1, opts: BuildRepoMapOptions = {}): Re
dirs,
hotspots,
dropped,
+ saved: savingsFor(graph, fileNodes.map((f) => f.path)),
};
}
@@ -219,5 +224,6 @@ export function formatRepoMap(map: RepoMap): string {
lines.push("");
lines.push(`hotspots: ${map.hotspots.map(formatHotspot).join(" ")}`);
- return lines.join("\n") + "\n";
+ const body = lines.join("\n");
+ return body + savingsFooter(body, map.saved) + "\n";
}
diff --git a/src/graph/traverse-cli.ts b/src/graph/traverse-cli.ts
index 23a1394a..5c8559f5 100644
--- a/src/graph/traverse-cli.ts
+++ b/src/graph/traverse-cli.ts
@@ -1,60 +1,74 @@
/**
- * CLI wiring for `graft callers` / `callees` / `impact`.
+ * CLI wiring for `graft callers` and its `--direction` / `--depth` flags.
*
- * 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.
+ * 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_callers`
+ * tool (`src/mcp/tools.ts`), so both surfaces render identical reports.
*/
import { resolve } from "node:path";
import { contextDirFor } from "../context/node-file.js";
+import { savingsFooter, savingsFor, type Savings } from "../context/savings.js";
import { loadGraphCached } from "./load.js";
-import { resolveSymbol, callersOf, calleesOf, impactOf, type EdgeHit } from "./traverse.js";
+import { resolveSymbol, edgeWalk, type Direction, type EdgeHit } from "./traverse.js";
import type { GraphV1, NodeV1 } from "./types.js";
-export type TraverseKind = "callers" | "callees" | "impact";
-
-export interface TraverseCliOptions {
+export interface CallersCliOptions {
in?: string;
json?: boolean;
- /** impact only: max BFS depth, as the raw --depth string (validated here). */
+ /** walk direction; defaults to "in" (callers). "out" gives callees. */
+ direction?: string;
+ /** max BFS depth, as the raw --depth string (validated here); defaults to 1. */
depth?: string;
/** the top-level `--dir` override, so this command respects it like every other. */
globalDir?: string;
}
-const ARROW: Record<TraverseKind, "←" | "→"> = { callers: "←", impact: "←", callees: "→" };
-const DEFAULT_IMPACT_DEPTH = 2;
+const ARROW: Record<Direction, "←" | "→"> = { in: "←", out: "→" };
+const DEFAULT_DEPTH = 1;
-function edgesFor(kind: TraverseKind, graph: GraphV1, node: NodeV1, depth: number): EdgeHit[] {
- 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. */
+/** Exported so the MCP `graft_callers` 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: NodeV1): string {
return `${n.name} · ${n.kind} · ${n.path}:${n.span}`;
}
-export function hitLine(kind: TraverseKind, hit: EdgeHit): string {
- const arrow = ARROW[kind];
- const depthTag = kind === "impact" ? ` [depth ${hit.depth}]` : "";
+/** `showDepth` is set for multi-hop walks (depth > 1), matching the old
+ * `graft impact` output which tagged every hit with its BFS depth. */
+export function hitLine(direction: Direction, hit: EdgeHit, showDepth: boolean): string {
+ 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)`;
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: TraverseKind, name: string): string {
- 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}"`;
+/** 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: GraphV1,
+ results: { symbol: NodeV1; hits: EdgeHit[] }[],
+): Savings | undefined {
+ const paths: string[] = [];
+ 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. */
+export function looseNoteFor(direction: Direction, name: string): string {
+ const label = direction === "out" ? "callees" : "callers";
+ const dir = direction === "out" ? "outgoing" : "incoming";
+ return ` no indexed ${label} — the graph has no ${dir} call/reference edges for this symbol; try grep -rn "${name}"`;
}
interface SymbolJson {
@@ -96,13 +110,21 @@ function hitJson(hit: EdgeHit): HitJson {
return out;
}
+/** Parse and validate the raw `--direction` string; exits (code 1) on garbage. */
+function resolveDirection(raw: string | undefined): Direction {
+ 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 `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.
+ * 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 runTraverseCommand(kind: TraverseKind, query: string, dir: string, opts: TraverseCliOptions): void {
+export function runCallersCommand(query: string, dir: string, opts: CallersCliOptions): void {
const root = resolve(dir);
const contextDir = contextDirFor(root, opts.globalDir);
const graph = loadGraphCached(contextDir);
@@ -117,17 +139,20 @@ export function runTraverseCommand(kind: TraverseKind, query: string, dir: strin
process.exit(1);
}
- let depth = DEFAULT_IMPACT_DEPTH;
- if (kind === "impact" && opts.depth !== undefined) {
+ const direction = resolveDirection(opts.direction);
+ let depth = DEFAULT_DEPTH;
+ if (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;
+ depth = Math.floor(d);
}
+ const showDepth = depth > 1;
- const results = matches.map((symbol) => ({ symbol, hits: edgesFor(kind, graph, symbol, depth) }));
+ const results = matches.map((symbol) => ({ symbol, hits: edgeWalk(graph, symbol, direction, depth) }));
+ const saved = callersSavings(graph, results);
if (opts.json) {
const payload = {
@@ -135,10 +160,11 @@ export function runTraverseCommand(kind: TraverseKind, query: string, dir: strin
matches: results.map((r): MatchJson => {
const m: MatchJson = { symbol: symbolJson(r.symbol), hits: r.hits.map(hitJson) };
if (r.hits.length === 0) {
- m.note = looseNoteFor(kind, r.symbol.name);
+ m.note = looseNoteFor(direction, r.symbol.name);
}
return m;
}),
+ saved,
};
console.log(JSON.stringify(payload, null, 2));
return;
@@ -147,9 +173,10 @@ export function runTraverseCommand(kind: TraverseKind, query: string, dir: strin
const lines: string[] = [];
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));
+ if (hits.length === 0) lines.push(looseNoteFor(direction, symbol.name));
+ else for (const h of hits) lines.push(hitLine(direction, h, showDepth));
lines.push("");
}
- process.stdout.write(lines.join("\n").replace(/\n+$/, "\n"));
+ const body = lines.join("\n").replace(/\n+$/, "\n");
+ process.stdout.write(body + savingsFooter(body, saved));
}
diff --git a/src/graph/traverse.ts b/src/graph/traverse.ts
index 2f4cb885..6edea82c 100644
--- a/src/graph/traverse.ts
+++ b/src/graph/traverse.ts
@@ -1,11 +1,12 @@
/**
- * Pure graph-traversal core shared by `graft callers` / `callees` / `impact`,
- * their MCP equivalents, and `ask`'s structural intent path.
+ * Pure graph-traversal core shared by `graft callers` (its `--direction`/
+ * `--depth` flags), the MCP `graft_callers` tool, 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.
+ * 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
@@ -14,6 +15,11 @@
import type { EdgeV1, GraphV1, NodeV1, Relation } from "./types.js";
import { WALK_RELATIONS } from "./relations.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 {
@@ -125,30 +131,36 @@ export function impactOf(graph: GraphV1, symbol: NodeV1, maxDepth = 2): 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.
+ * 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: GraphV1, seeds: NodeV1[], maxDepth = 2): EdgeHit[] {
+export function impactOfMany(graph: GraphV1, seeds: NodeV1[], maxDepth = 2, direction: Direction = "in"): EdgeHit[] {
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<string, { source: string; relation: Relation }[]>();
+ // 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<string, { other: string; relation: Relation }[]>();
for (const e of graph.edges as EdgeV1[]) {
if (!WALK_RELATIONS.has(e.relation)) continue;
- const arr = incoming.get(e.target);
- const entry = { source: e.source, relation: e.relation };
+ 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 incoming.set(e.target, [entry]);
+ else adj.set(key, [entry]);
}
const visited = new Set<string>(seeds.map((s) => s.id));
@@ -158,11 +170,11 @@ export function impactOfMany(graph: GraphV1, seeds: NodeV1[], maxDepth = 2): Edg
for (let depth = 1; depth <= maxDepth && frontier.length > 0; depth++) {
const next: string[] = [];
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);
+ 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;
@@ -186,6 +198,25 @@ function symbolsInFile(graph: GraphV1, fileNode: NodeV1): NodeV1[] {
* 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: GraphV1, fileNode: NodeV1, maxDepth = 2): EdgeHit[] {
- return impactOfMany(graph, [fileNode, ...symbolsInFile(graph, fileNode)], maxDepth);
+export function impactOfFile(graph: GraphV1, fileNode: NodeV1, maxDepth = 2, direction: Direction = "in"): EdgeHit[] {
+ return impactOfMany(graph, [fileNode, ...symbolsInFile(graph, fileNode)], maxDepth, direction);
+}
+
+/**
+ * The single entry point behind `graft callers` and the MCP `graft_callers`
+ * 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: GraphV1, node: NodeV1, direction: Direction, depth: number): EdgeHit[] {
+ 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);
}
diff --git a/src/hosts/instructions.ts b/src/hosts/instructions.ts
index a6e38f61..1dd85292 100644
--- a/src/hosts/instructions.ts
+++ b/src/hosts/instructions.ts
@@ -27,9 +27,10 @@ hotspots), no LLM, no key.
to raw \`grep -rn\` only for unindexed files.
- \`graft skeleton <file>\` → every definition's signature + span, ~10× cheaper
than reading the file; use it to skim an API surface.
-- \`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.
+- \`graft callers <symbol>\` gives precomputed, exact edges — who calls this.
+ Add \`--direction out\` for what it calls, or \`--depth N\` to walk
+ transitively for the full blast radius. For structural questions, skip
+ ranking and use this directly.
- Or browse: \`graft/INDEX.md\` lists every node; follow the links.
If a returned span is truncated ("+N more lines"), open the file at that exact
diff --git a/src/hosts/mcp-config.ts b/src/hosts/mcp-config.ts
index 7f67e795..578eec8d 100644
--- a/src/hosts/mcp-config.ts
+++ b/src/hosts/mcp-config.ts
@@ -13,14 +13,14 @@ export interface McpWrite {
action: 'created' | 'updated' | 'unchanged' | 'skipped-unparseable';
}
-const SERVER_ENTRY = { command: 'npx', args: ['-y', '@nanonets/graft', 'mcp'] };
+export const SERVER_ENTRY = { command: 'npx', args: ['-y', '@nanonets/graft', 'mcp'] };
const OPENCODE_ENTRY = { type: 'local', command: ['npx', '-y', '@nanonets/graft', 'mcp'], enabled: true };
function dirExists(p: string): boolean {
try { return statSync(p).isDirectory(); } catch { return false; }
}
-function mergeJsonKey(id: string, path: string, topKey: string, entry: object): McpWrite {
+export function mergeJsonKey(id: string, path: string, topKey: string, entry: object): McpWrite {
let root: Record<string, any> = {};
const existed = existsSync(path);
if (existed) {
diff --git a/src/mcp/tools.ts b/src/mcp/tools.ts
index 3e3952a3..6b343c1d 100644
--- a/src/mcp/tools.ts
+++ b/src/mcp/tools.ts
@@ -8,8 +8,9 @@ import { formatCheckReport } from '../context/check.js';
import { formatGraphCheckReport } from '../graph/check.js';
import { loadGraphCached } from '../graph/load.js';
import { contextDirFor } from '../context/node-file.js';
-import { resolveSymbol, callersOf, calleesOf, impactOf, impactOfFile, type EdgeHit } from '../graph/traverse.js';
-import { headerOf, hitLine, looseNoteFor, type TraverseKind } from '../graph/traverse-cli.js';
+import { resolveSymbol, edgeWalk, type Direction, type EdgeHit } from '../graph/traverse.js';
+import { callersSavings, headerOf, hitLine, looseNoteFor } from '../graph/traverse-cli.js';
+import { savingsFooter } from '../context/savings.js';
import { grepGraph } from '../search/grep.js';
import { formatGrepResult, zeroHitNote } from '../search/grep-cli.js';
import { buildRepoMap, formatRepoMap } from '../graph/map.js';
@@ -21,9 +22,6 @@ export interface ToolDef {
inputSchema: object;
}
-/** 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: string): string {
@@ -65,39 +63,20 @@ export const TOOLS: ToolDef[] = [
description: 'Report whether the committed graph is in sync with the code (drift check).',
inputSchema: { type: 'object', properties: {} },
},
- {
- name: 'graft_blast_radius',
- 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 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).',
+ description:
+ 'Structural edges for a symbol, over call/reference/import/implements/extends ($0, no LLM). Defaults to direct callers (who depends on it). Set direction:"out" for callees (what it calls); set depth>1 to walk transitively for the full blast radius — who breaks if it changes.',
inputSchema: {
type: 'object',
properties: {
- symbol: { type: 'string', description: 'bare name, qualified (Class.method), or package-qualified (pkg.Fn)' },
+ symbol: { type: 'string', description: 'bare name, qualified (Class.method), or package-qualified (pkg.Fn); a file path also works' },
+ direction: {
+ type: 'string',
+ enum: ['in', 'out'],
+ description: '"in" (default) = callers/dependents; "out" = callees/dependencies',
+ },
+ depth: { type: 'number', description: 'transitive walk depth for blast radius (default 1 = direct edges only)' },
in: { type: 'string', description: 'narrow matches to nodes whose path contains this substring' },
},
required: ['symbol'],
@@ -133,14 +112,20 @@ export const TOOLS: ToolDef[] = [
/** 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: TraverseKind, matches: NodeV1[], hitsFor: (n: NodeV1) => EdgeHit[]): string {
+ * `graft callers` uses for multi-match symbols. `showDepth` tags each hit with
+ * its BFS depth (for transitive `depth>1` walks). */
+function renderMatches(
+ direction: Direction,
+ showDepth: boolean,
+ matches: NodeV1[],
+ hitsFor: (n: NodeV1) => EdgeHit[],
+): string {
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));
+ if (hits.length === 0) lines.push(looseNoteFor(direction, m.name));
+ else for (const h of hits) lines.push(hitLine(direction, h, showDepth));
return lines.join('\n');
})
.join('\n\n');
@@ -176,41 +161,29 @@ export function callTool(
if (!g.missing) parts.push(formatGraphCheckReport(g));
return { text: parts.join('\n\n'), isError: false };
}
- case 'graft_blast_radius': {
- 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, dirOverride));
- 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 };
+ case 'graft_callers': {
+ // One tool covers callers (direction:in, the default), callees
+ // (direction:out), and blast radius (depth>1). edgeWalk handles the
+ // file-seed aggregation that the old graft_blast_radius did: for a
+ // file at depth>1 it walks the file node AND every symbol defined in
+ // it, so dependents that call into a symbol (targeting the SYMBOL id,
+ // never the FILE id) aren't silently dropped.
+ const symbol = String(args.symbol ?? args.file ?? '');
+ if (!symbol) return { text: 'graft_callers requires a symbol', isError: true };
const w = loadGraphCached(contextDirFor(root, dirOverride));
if (!w) 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: TraverseKind = name === 'graft_callers' ? 'callers' : 'callees';
- const walk = kind === 'callers' ? callersOf : calleesOf;
- const text = renderMatches(kind, matches, (m) => walk(w, m));
+ const direction: Direction = args.direction === 'out' ? 'out' : 'in';
+ const depth =
+ typeof args.depth === 'number' && Number.isFinite(args.depth) && args.depth >= 1
+ ? Math.floor(args.depth)
+ : 1;
+ const results = matches.map((m) => ({ symbol: m, hits: edgeWalk(w, m, direction, depth) }));
+ const byId = new Map(results.map((r) => [r.symbol.id, r.hits]));
+ const body = renderMatches(direction, depth > 1, matches, (m) => byId.get(m.id) ?? []);
+ const text = body + savingsFooter(body, callersSavings(w, results));
return { text, isError: false };
}
case 'graft_grep': {
diff --git a/src/search/grep-cli.ts b/src/search/grep-cli.ts
index 09fd92a9..b0a98a6c 100644
--- a/src/search/grep-cli.ts
+++ b/src/search/grep-cli.ts
@@ -9,6 +9,7 @@
*/
import { resolve } from "node:path";
import { contextDirFor } from "../context/node-file.js";
+import { savingsFooter } from "../context/savings.js";
import { loadGraphCached } from "../graph/load.js";
import { grepGraph, type GrepGroup, type GrepResult } from "./grep.js";
@@ -55,6 +56,8 @@ export function formatGrepResult(result: GrepResult): string {
let out = blocks.join("\n").replace(/\n+$/, "\n");
const note = truncationNote(result);
if (note) out += note + "\n";
+ const footer = savingsFooter(out, result.saved);
+ if (footer) out += footer + "\n";
return out;
}
diff --git a/src/search/grep.ts b/src/search/grep.ts
index 5bbc48b0..66c1ff01 100644
--- a/src/search/grep.ts
+++ b/src/search/grep.ts
@@ -13,6 +13,7 @@ import { readFileSync } from "node:fs";
import { join } from "node:path";
import type { GraphV1, NodeV1 } from "../graph/types.js";
import { WALK_RELATIONS } from "../graph/relations.js";
+import { savingsFor, type Savings } from "../context/savings.js";
export interface GrepHit {
line: number;
@@ -55,6 +56,9 @@ export interface GrepResult {
* couldn't be read from disk. `hits`: matches found beyond `maxHits`,
* counted but not collected. */
truncated: { files: number; hits: number };
+ /** Tokens-saved baseline: the files that had hits, read whole. Undefined
+ * when there were no hits or the graph predates file sizing. */
+ saved?: Savings;
}
export interface GrepOptions {
@@ -191,5 +195,6 @@ export function grepGraph(graph: GraphV1, repoRoot: string, pattern: string, opt
totalHits: collected,
groups: sortedGroups,
truncated: { files: truncatedFiles, hits: truncatedHits },
+ saved: savingsFor(graph, sortedGroups.map((g) => g.path)),
};
}
diff --git a/test/claude-skill-template.test.ts b/test/claude-skill-template.test.ts
index f6da133b..4de31331 100644
--- a/test/claude-skill-template.test.ts
+++ b/test/claude-skill-template.test.ts
@@ -12,8 +12,8 @@ test('skill template is a well-formed SKILL.md', () => {
assert.match(body, /graft ask/, 'body tells the agent to use `graft ask`');
assert.match(body, /every occurrence/i, 'body teaches the exhaustive-task grep rule');
assert.match(body, /graft callers/, 'body teaches the callers command');
- assert.match(body, /graft callees/, 'body teaches the callees command');
- assert.match(body, /graft impact/, 'body teaches the impact command');
+ assert.match(body, /--direction out/, 'body teaches callees via --direction out');
+ assert.match(body, /--depth/, 'body teaches blast radius via --depth');
assert.match(body, /truncated/i, 'body tells the agent to follow up on truncated spans');
assert.match(body, /graft grep/, 'body routes sweeps to graft grep');
assert.match(body, /graft map/, 'body tells the agent to orient with graft map before exploring');
diff --git a/test/graph-load.test.ts b/test/graph-load.test.ts
index 8aade04c..d7d0b45f 100644
--- a/test/graph-load.test.ts
+++ b/test/graph-load.test.ts
@@ -118,15 +118,15 @@ test("loadAskIndexCached: caches and invalidates the same way as the graph loade
assert.equal(__parseCount.askIndex, 2);
});
-test("callTool: graft_blast_radius on the same dir twice doesn't reparse the graph", () => {
+test("callTool: graft_callers on the same dir twice doesn't reparse the graph", () => {
const dir = fixtureDir();
mkdirSync(join(dir, "src"), { recursive: true });
writeFileSync(join(dir, "src", "math.ts"), "export function add() { return 1; }\n");
const graph: GraphV1 = {
version: 1,
// A real `buildGraph` always emits a `kind: "file"` node per source file;
- // include one here too so `graft_blast_radius` (now a `resolveSymbol` +
- // `impactOf` walk, same as `graft impact`) can resolve the filename-shaped
+ // include one here too so `graft_callers` with depth (a `resolveSymbol` +
+ // `edgeWalk` walk, the old `graft impact`) can resolve the filename-shaped
// query the way it would against a real build.
nodes: [
{ ...node("src/math.ts#add"), path: "src/math.ts" },
@@ -134,7 +134,7 @@ test("callTool: graft_blast_radius on the same dir twice doesn't reparse the gra
],
edges: [],
} as GraphV1;
- // graft_blast_radius reads through `contextDirFor(root)`, i.e. `<root>/graft`
+ // graft_callers reads through `contextDirFor(root)`, i.e. `<root>/graft`
// by default — write the graph there directly rather than round-tripping
// through a real `graft build`.
const outDir = join(dir, "graft");
@@ -142,11 +142,11 @@ test("callTool: graft_blast_radius on the same dir twice doesn't reparse the gra
writeGraph(graph, outDir);
__resetParseCounts();
- const r1 = callTool(dir, "graft_blast_radius", { file: "src/math.ts" });
+ const r1 = callTool(dir, "graft_callers", { symbol: "src/math.ts", depth: 2 });
assert.equal(r1.isError, false);
assert.equal(__parseCount.graph, 1);
- const r2 = callTool(dir, "graft_blast_radius", { file: "src/math.ts" });
+ const r2 = callTool(dir, "graft_callers", { symbol: "src/math.ts", depth: 2 });
assert.equal(r2.isError, false);
assert.equal(__parseCount.graph, 1, "second call on the same dir must not reparse");
});
diff --git a/test/graph-traverse-cli.test.ts b/test/graph-traverse-cli.test.ts
index aed48a1f..6787a039 100644
--- a/test/graph-traverse-cli.test.ts
+++ b/test/graph-traverse-cli.test.ts
@@ -1,7 +1,8 @@
/**
- * CLI tests for `graft callers` / `callees` / `impact` — the three commands
- * that wire src/graph/traverse.ts's pure resolver + edge-walkers into the
- * `graft` binary. Runs the real CLI via execFileSync (same pattern as
+ * CLI tests for `graft callers` and its `--direction`/`--depth` flags — the one
+ * command that wires src/graph/traverse.ts's pure resolver + edge-walkers into
+ * the `graft` binary (`--direction out` is the old `callees`; `--depth N` is the
+ * old `impact`). Runs the real CLI via execFileSync (same pattern as
* test/mcp-tools.test.ts's `builtRepo` helper) against a built fixture repo,
* so these tests exercise the actual process boundary: exit codes, stdout vs
* stderr, and --json shape.
@@ -75,20 +76,28 @@ test('graft callers: unknown symbol exits 1 with a stderr message', () => {
assert.equal(r.stdout, '');
});
-test('graft callees: zero-edge symbol prints a loud note and still exits 0', () => {
+test('graft callers --direction out: happy path shows the outgoing (callee) hit', () => {
+ const d = builtRepo();
+ // `sub` calls `add`, so its outgoing edge points at add with a `→` arrow.
+ const r = runCli(['callers', 'sub', d, '--direction', 'out']);
+ assert.equal(r.status, 0);
+ assert.match(r.stdout, /sub · function · src\/math\.ts:/);
+ assert.match(r.stdout, /calls → add \(src\/math\.ts:/);
+});
+
+test('graft callers --direction out: zero-edge symbol prints a loud callees note and still exits 0', () => {
const d = builtRepo();
// `add` calls nothing, so its callees are empty — must not be a silent list.
- const r = runCli(['callees', 'add', d]);
+ const r = runCli(['callers', 'add', d, '--direction', 'out']);
assert.equal(r.status, 0);
assert.match(r.stdout, /add · function · src\/math\.ts:/);
assert.match(r.stdout, /no indexed callees/);
assert.match(r.stdout, /grep -rn "add"/);
});
-test('graft callees --json: zero-edge symbol includes a note field', () => {
+test('graft callers --direction out --json: zero-edge symbol includes a note field', () => {
const d = builtRepo();
- // `add` calls nothing, so its callees are empty — JSON must include the note.
- const r = runCli(['callees', 'add', d, '--json']);
+ const r = runCli(['callers', 'add', d, '--direction', 'out', '--json']);
assert.equal(r.status, 0);
const parsed = JSON.parse(r.stdout);
assert.equal(parsed.query, 'add');
@@ -100,16 +109,17 @@ test('graft callees --json: zero-edge symbol includes a note field', () => {
assert.match(m.note, /try grep -rn/);
});
-test('graft impact -d: depth flag limits the BFS, default reaches further', () => {
+test('graft callers --depth: depth flag walks the BFS transitively (blast radius)', () => {
const d = builtRepo();
- // compute -> sub -> add: impact of `add` at depth 1 is just `sub`;
- // the default depth (2) also reaches `compute`.
- const shallow = runCli(['impact', 'add', d, '-d', '1']);
+ // compute -> sub -> add: callers of `add` at depth 1 is just `sub`;
+ // depth 2 also reaches `compute` and tags each hit with its depth.
+ const shallow = runCli(['callers', 'add', d, '--depth', '1']);
assert.equal(shallow.status, 0);
assert.match(shallow.stdout, /← sub \(/);
assert.doesNotMatch(shallow.stdout, /compute/);
+ assert.doesNotMatch(shallow.stdout, /\[depth/); // depth 1 → no depth tags
- const deeper = runCli(['impact', 'add', d]);
+ const deeper = runCli(['callers', 'add', d, '--depth', '2']);
assert.equal(deeper.status, 0);
assert.match(deeper.stdout, /← sub \(/);
assert.match(deeper.stdout, /\[depth 1\]/);
@@ -117,6 +127,13 @@ test('graft impact -d: depth flag limits the BFS, default reaches further', () =
assert.match(deeper.stdout, /\[depth 2\]/);
});
+test('graft callers --direction: rejects a bad value with exit 1', () => {
+ const d = builtRepo();
+ const r = runCli(['callers', 'add', d, '--direction', 'sideways']);
+ assert.equal(r.status, 1);
+ assert.match(r.stderr, /--direction must be "in" or "out"/);
+});
+
test('graft callers: no graph at all is a stderr error, exit 1', () => {
const bare = mkdtempSync(join(tmpdir(), 'graft-traversecli-bare-'));
const r = runCli(['callers', 'add', bare]);
diff --git a/test/mcp-server.test.ts b/test/mcp-server.test.ts
index 8e95c835..ef37a931 100644
--- a/test/mcp-server.test.ts
+++ b/test/mcp-server.test.ts
@@ -34,7 +34,7 @@ test('initialize → tools/list → tools/call round-trip', async () => {
{ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-03-26', capabilities: {}, clientInfo: { name: 't', version: '0' } } },
{ jsonrpc: '2.0', method: 'notifications/initialized' },
{ jsonrpc: '2.0', id: 2, method: 'tools/list' },
- { jsonrpc: '2.0', id: 3, method: 'tools/call', params: { name: 'graft_blast_radius', arguments: { file: 'x.ts' } } },
+ { jsonrpc: '2.0', id: 3, method: 'tools/call', params: { name: 'graft_callers', arguments: { symbol: 'x.ts', depth: 2 } } },
],
dir,
3,
@@ -49,9 +49,7 @@ test('initialize → tools/list → tools/call round-trip', async () => {
'graft_ask',
'graft_skeleton',
'graft_check',
- 'graft_blast_radius',
'graft_callers',
- 'graft_callees',
'graft_grep',
'graft_map',
]);
diff --git a/test/mcp-tools.test.ts b/test/mcp-tools.test.ts
index 6ab6e266..af5d03f9 100644
--- a/test/mcp-tools.test.ts
+++ b/test/mcp-tools.test.ts
@@ -72,14 +72,12 @@ function multiDirRepo(): string {
return d;
}
-test('TOOLS lists all eight tools with schemas', () => {
+test('TOOLS lists the six tools with schemas', () => {
assert.deepEqual(TOOLS.map((t) => t.name), [
'graft_ask',
'graft_skeleton',
'graft_check',
- 'graft_blast_radius',
'graft_callers',
- 'graft_callees',
'graft_grep',
'graft_map',
]);
@@ -87,11 +85,12 @@ test('TOOLS lists all eight tools with schemas', () => {
assert.ok(t.description.length > 0);
assert.equal((t.inputSchema as { type: string }).type, 'object');
}
- // graft_blast_radius accepts `symbol` as an alternative to `file` (callTool
- // does `args.symbol ?? args.file`) — the schema must document it too.
- const blastRadius = TOOLS.find((t) => t.name === 'graft_blast_radius')!;
- const props = (blastRadius.inputSchema as { properties: Record<string, unknown> }).properties;
- assert.ok('symbol' in props, 'graft_blast_radius schema should document `symbol`');
+ // graft_callers absorbed callees (direction) and blast radius (depth) — the
+ // schema must document both flags.
+ const callers = TOOLS.find((t) => t.name === 'graft_callers')!;
+ const props = (callers.inputSchema as { properties: Record<string, unknown> }).properties;
+ assert.ok('direction' in props, 'graft_callers schema should document `direction`');
+ assert.ok('depth' in props, 'graft_callers schema should document `depth`');
});
test('graft_ask returns ranked hits for a built repo', () => {
@@ -109,16 +108,16 @@ test('graft_check reports the wiring state', () => {
assert.match(r.text, /graph check: OK/);
});
-test('graft_blast_radius names dependents of a file', () => {
+test('graft_callers with depth names dependents of a file (blast radius)', () => {
const d = builtRepo();
- const r = callTool(d, 'graft_blast_radius', { file: 'src/math.ts' });
+ const r = callTool(d, 'graft_callers', { symbol: 'src/math.ts', depth: 2 });
assert.equal(r.isError, false);
assert.ok(r.text.length > 0);
});
test('unbuilt repo and unknown tool are soft errors', () => {
const bare = mkdtempSync(join(tmpdir(), 'graft-mcptools-bare-'));
- const r1 = callTool(bare, 'graft_blast_radius', { file: 'x.ts' });
+ const r1 = callTool(bare, 'graft_callers', { symbol: 'x.ts', depth: 2 });
assert.equal(r1.isError, true);
assert.match(r1.text, /graft build/);
const r2 = callTool(bare, 'nope', {});
@@ -144,39 +143,39 @@ test('graft_callers: qualified/--in narrowing still resolves through the shared
assert.match(miss.text, /no symbol "add" in the graph/);
});
-test('graft_callees round-trips a callee, and reports a loud note when there are none', () => {
+test('graft_callers direction:out round-trips a callee, and reports a loud note when there are none', () => {
const d = builtRepo();
- const callee = callTool(d, 'graft_callees', { symbol: 'sub' });
+ const callee = callTool(d, 'graft_callers', { symbol: 'sub', direction: 'out' });
assert.equal(callee.isError, false);
assert.match(callee.text, /calls → add \(src\/math\.ts:/);
// `add` calls nothing, so its callees are empty — must be a loud note, not silence.
- const empty = callTool(d, 'graft_callees', { symbol: 'add' });
+ const empty = callTool(d, 'graft_callers', { symbol: 'add', direction: 'out' });
assert.equal(empty.isError, false);
assert.match(empty.text, /no indexed callees/);
assert.match(empty.text, /grep -rn "add"/);
});
-test('graft_callers/graft_callees: unknown symbol is a soft isError', () => {
+test('graft_callers: unknown symbol / missing symbol are soft isErrors', () => {
const d = builtRepo();
const r1 = callTool(d, 'graft_callers', { symbol: 'noSuchSymbolAnywhere' });
assert.equal(r1.isError, true);
assert.match(r1.text, /no symbol "noSuchSymbolAnywhere" in the graph/);
assert.match(r1.text, /check spelling|graft build/);
- const r2 = callTool(d, 'graft_callees', {});
+ const r2 = callTool(d, 'graft_callers', {});
assert.equal(r2.isError, true);
assert.match(r2.text, /requires a symbol/);
});
-test('graft_blast_radius: depth param is honored (default 2 reaches further than depth 1)', () => {
+test('graft_callers: depth param is honored (depth 2 reaches further than depth 1)', () => {
const d = chainRepo();
- const shallow = callTool(d, 'graft_blast_radius', { file: 'add', depth: 1 });
+ const shallow = callTool(d, 'graft_callers', { symbol: 'add', depth: 1 });
assert.equal(shallow.isError, false);
assert.match(shallow.text, /← sub \(/);
assert.doesNotMatch(shallow.text, /compute/);
- const deeper = callTool(d, 'graft_blast_radius', { file: 'add' });
+ const deeper = callTool(d, 'graft_callers', { symbol: 'add', depth: 2 });
assert.equal(deeper.isError, false);
assert.match(deeper.text, /← sub \(/);
assert.match(deeper.text, /\[depth 1\]/);
@@ -184,20 +183,20 @@ test('graft_blast_radius: depth param is honored (default 2 reaches further than
assert.match(deeper.text, /\[depth 2\]/);
});
-test('graft_blast_radius: file-scope match aggregates dependents that call into a symbol the file defines, not just file-level imports', () => {
+test('graft_callers depth>1 on a file aggregates dependents that call into a symbol the file defines, not just file-level imports', () => {
const d = fileScopeRepo();
- const r = callTool(d, 'graft_blast_radius', { file: 'src/a.ts' });
+ const r = callTool(d, 'graft_callers', { symbol: 'src/a.ts', depth: 2 });
assert.equal(r.isError, false);
- // Old behavior (walking only the FILE node's incoming edges) found b.ts via
- // `imports` but silently dropped it via `calls`, since a `calls` edge
- // targets the SYMBOL id (`src/a.ts#helper`), never the FILE id.
+ // Walking only the FILE node's incoming edges would find b.ts via `imports`
+ // but drop it via `calls`, since a `calls` edge targets the SYMBOL id
+ // (`src/a.ts#helper`), never the FILE id. edgeWalk aggregates over both.
assert.match(r.text, /imports ← b\.ts \(src\/b\.ts/);
assert.match(r.text, /calls ← useB \(src\/b\.ts/);
});
-test('graft_blast_radius: unknown symbol is a soft isError with the check-spelling message', () => {
+test('graft_callers: unknown symbol is a soft isError with the check-spelling message', () => {
const d = builtRepo();
- const r = callTool(d, 'graft_blast_radius', { file: 'noSuchSymbolAnywhere' });
+ const r = callTool(d, 'graft_callers', { symbol: 'noSuchSymbolAnywhere', depth: 2 });
assert.equal(r.isError, true);
assert.match(r.text, /no symbol "noSuchSymbolAnywhere" in the graph/);
assert.match(r.text, /check spelling/);