Skip to content

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

Merge main (0.6.0) into feat/scope-aware-ranking

Shrish Dwivedi656271cc244c
diff --cc .claude/skills/graft/SKILL.md
index c780f795,c780f795..ef762e4b
--- a/.claude/skills/graft/SKILL.md
+++ b/.claude/skills/graft/SKILL.md
@@@ -12,24 -12,24 +12,30 @@@ explaining one part in plain prose and
covers. Reading a node costs a few hundred tokens; reading source to rebuild the
same understanding costs thousands.
--**Get context from graft first — two ways, both land here:**
++**Choose the graft tool by task shape — pick the one that answers in a single call:**
--- Ask: `graft ask "<your task, in plain words>"` — returns the relevant nodes,
-- ranked, with file:line pointers. Add `--source` to inline the actual code at
-- each span, so the result IS the code you need — no separate file read. By
-- default `--source` inlines each hit's crux (the ≤8-line core of the
-- definition, marked as such); add `--full` only when the crux isn't enough.
-- Ask is cheap (<1s) — re-ask with different phrasings for each sub-question,
-- and use structural forms too: `graft ask "who calls <symbol>"`.
--- Skim a file's API without reading it: `graft skeleton <file>` — every
-- definition's signature + span in ~200 tokens, ~10× cheaper than the file.
--- Or explore as usual: grep / ls / cat inside `graft/`. A grep for any concept,
-- symbol, or filename hits the node that covers it; `graft/INDEX.md` lists them
-- all.
++- **Locate / understand / "how does X work"** → `graft ask "<task>" --source` —
++ ranked nodes with the code inlined (`--source` gives each hit's ≤8-line crux;
++ add `--full` only if the crux isn't enough). For a genuinely multi-part
++ question, ask once per distinct sub-aspect. **But if an ask returns few or
++ weak hits, do NOT re-ask with reworded phrasings — switch tool** (below). The
++ ask output tells you when to switch.
++- **Every occurrence / "all the X" / a symbol or literal everywhere** →
++ `graft grep "<literal>"` — exhaustive, grouped by enclosing symbol. Ranked
++ 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>` (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.
--**First contact with an unfamiliar repo:** run `graft map` before exploring —
--a token-budgeted orientation (dir clusters, hubs, hotspots) built straight from
--the wiring graph, no LLM, no key.
++You can also grep / ls / cat inside `graft/` directly (the nodes are plain
++markdown; `graft/INDEX.md` lists them) — but the commands above are faster and
++exhaustive where it matters, so reach for them first.
**Match the tool to the task shape:**
@@@ -51,13 -51,13 +57,19 @@@
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 --cc graft/.graph/wiring.json
index ab706939,35084f6b..c9029fbe
--- a/graft/.graph/wiring.json
+++ b/graft/.graph/wiring.json
@@@ -1,10 -1,10 +1,19 @@@
{
"meta": {
"version": 1,
- "nodeCount": 750,
- "edgeCount": 1924,
- "nodeCount": 758,
- "edgeCount": 1955,
++ "nodeCount": 798,
++ "edgeCount": 2063,
"languages": [
"typescript"
++ ],
++ "scopes": [
++ {
++ "prefix": "",
++ "label": "",
++ "markers": [
++ "package.json"
++ ]
++ }
]
},
"nodes": [
@@@ -2096,13 -2096,13 +2105,13 @@@
"name": "ask.ts",
"kind": "file",
"path": "src/ask/ask.ts",
- "span": "L1-L749",
- "span": "L1-L756",
++ "span": "L1-L939",
"signature": null,
"exported": true,
"origin": "ast",
- "body_hash": "62d693c39f77019e50437b5285fafe5802b8b077e7aa6545589a3b084f93e552",
- "chars": 32834,
- "summary_state": "ready",
- "body_hash": "7a50c1c1d10cf0339157147d88858dcd22a2f3fad56f426bbf75fbcff29f4538",
- "chars": 33648,
++ "body_hash": "9b4a22ecd84021a10900b5cc6e266f8b52c261385337ec0cf8006ecae8b3d6c0",
++ "chars": 44203,
+ "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,12 -2114,12 +2123,12 @@@
"name": "ask",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L592-L622",
- "span": "L581-L611",
++ "span": "L726-L771",
"signature": "function ask(dir: string, query: string, opts: AskOptions = {}): AskResult",
"exported": true,
"origin": "ast",
-- "body_hash": "a9f712f1764f9391acc161a721d4c4f944f728cb4d0df2e602126460d3321cd7",
-- "summary_state": "ready",
++ "body_hash": "fe391f9d96cb8452f28b452ec4a4bd31a6ccb13a5b3f9f1aa928ffe9c6faf0ac",
++ "summary_state": "stale",
"summary": "Handles the main logic for processing a query against a directory, returning structured results based on the query type.",
"crux": {
"code": "export function ask(dir: string, query: string, opts: AskOptions = {}): AskResult {\n const root = resolve(dir);\n const outDir = contextDirFor(root, opts.contextDir);\n const limit = opts.limit ?? 8;\n const corpus = loadCorpus(outDir);\n const graphRank = opts.graphRank ?? true;\n\n let result: AskResult;\n if (corpus.graph) {\n const outcome = structural(query, corpus.graph, limit);\n if (outcome && \"result\" in outcome) {\n result = outcome.result;",
@@@ -2131,12 -2131,12 +2140,12 @@@
"name": "AskHit",
"kind": "interface",
"path": "src/ask/ask.ts",
- "span": "L26-L39",
- "span": "L27-L40",
++ "span": "L29-L46",
"signature": "interface AskHit",
"exported": true,
"origin": "ast",
-- "body_hash": "51baa90dc28b443f824809190b7bb95bd028db20b68aea518ca865769dae424c",
-- "summary_state": "ready",
++ "body_hash": "1829b4fe0563b6d00e315d91b386adc901876283c19e54738ecad4be76e9239a",
++ "summary_state": "stale",
"summary": "Represents a hit in the query results, encapsulating details about a code symbol and its context.",
"crux": null
},
@@@ -2145,12 -2145,12 +2154,12 @@@
"name": "AskOptions",
"kind": "interface",
"path": "src/ask/ask.ts",
- "span": "L489-L505",
- "span": "L490-L506",
++ "span": "L629-L651",
"signature": "interface AskOptions",
"exported": true,
"origin": "ast",
-- "body_hash": "e43e59155824acff2cc2bc06107314506a521eba1579a9a04af4875e4736ed57",
-- "summary_state": "ready",
++ "body_hash": "352459201a57364217b351980b179879cb37170119f6953bfcc3b3cc19f01c92",
++ "summary_state": "stale",
"summary": "Defines the options available for configuring the ask function, allowing customization of its behavior.",
"crux": {
"code": "export interface AskOptions {\n contextDir?: string;\n limit?: number;\n /** Inline the source at each `path:Lx-Ly` hit, sliced from `dir`. Turns the\n * pack from a locator into a retriever so the agent needn't re-open the file. */\n source?: boolean;\n /** Re-rank lexical hits by graph connectivity (personalized PageRank over the\n * wiring edges), demoting same-word collisions and rescuing strongly-connected\n * neighbours the query didn't name. On by default; set false for pure lexical. */\n graphRank?: boolean;\n /** With `source`: inline each hit's WHOLE definition span (capped at\n * {@link MAX_SPAN_LINES}) instead of the default crux-first slice. The",
@@@ -2162,24 -2162,38 +2171,38 @@@
"name": "AskResult",
"kind": "interface",
"path": "src/ask/ask.ts",
- "span": "L45-L62",
- "span": "L46-L63",
++ "span": "L52-L74",
"signature": "interface AskResult",
"exported": true,
"origin": "ast",
-- "body_hash": "4c4d6302e47ed2207bf8ea2e976f97386aaac0470d987fe0203790fe796593d5",
-- "summary_state": "ready",
++ "body_hash": "fd79deb57128e1f4a35d9b927145648ed13bb28e2d0111b52f3375b6a29ede13",
++ "summary_state": "stale",
"summary": "Represents the result of an 'ask' query, encapsulating the query details and the hits found.",
"crux": {
"code": "export interface AskResult {\n query: string;\n mode: \"structural\" | \"lexical\" | \"empty\";\n /** For structural mode: the symbol whose neighbours we walked. */\n subject?: string;\n hits: AskHit[];\n note?: string;\n /** Token-saving estimate, set only in `--source` (retriever) mode: the whole\n * size of the distinct files these hits point into, i.e. the baseline cost of\n * reading them instead of this pack. Computed from file sizes stored at build. */\n saved?: { files: number; baselineChars: number };\n /** Lexical mode only: share (0..1) of the query's distinct terms the TOP hit",
"span": "L45-L56"
}
},
+ {
+ "id": "src/ask/ask.ts#askSavingsFooter",
+ "name": "askSavingsFooter",
+ "kind": "function",
+ "path": "src/ask/ask.ts",
- "span": "L743-L755",
++ "span": "L907-L919",
+ "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",
++ "span": "L720-L723",
"signature": "function baselineFor(hits: AskHit[], graph: GraphV1 | null): AskResult[\"saved\"] | undefined",
"exported": false,
"origin": "ast",
@@@ -2196,7 -2210,7 +2219,7 @@@
"name": "bm25",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L166-L182",
- "span": "L167-L183",
++ "span": "L178-L194",
"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 +2236,7 @@@
"name": "computeIdf",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L140-L145",
- "span": "L141-L146",
++ "span": "L152-L157",
"signature": "function computeIdf(docBags: Array<Set<string>>): Map<string, number>",
"exported": false,
"origin": "ast",
@@@ -2230,7 -2244,7 +2253,7 @@@
"name": "computeIdfFromIndex",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L154-L159",
- "span": "L155-L160",
++ "span": "L166-L171",
"signature": "function computeIdfFromIndex(index: AskIndex, conceptBags: Array<Set<string>>): Map<string, number>",
"exported": false,
"origin": "ast",
@@@ -2247,7 -2261,7 +2270,7 @@@
"name": "Corpus",
"kind": "interface",
"path": "src/ask/ask.ts",
- "span": "L74-L81",
- "span": "L75-L82",
++ "span": "L86-L93",
"signature": "interface Corpus",
"exported": false,
"origin": "ast",
@@@ -2259,12 -2273,26 +2282,26 @@@
"span": "L74-L81"
}
},
+ {
+ "id": "src/ask/ask.ts#escalationNudge",
+ "name": "escalationNudge",
+ "kind": "function",
+ "path": "src/ask/ask.ts",
- "span": "L731-L738",
++ "span": "L895-L902",
+ "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",
++ "span": "L245-L250",
"signature": "function fallthroughNoteFor(subject: string): string",
"exported": false,
"origin": "ast",
@@@ -2281,12 -2309,12 +2318,12 @@@
"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 }",
++ "span": "L227-L235",
++ "signature": "function findSubjectNodes(query: string, graph: GraphV1, inPrefix?: string): { nodes: NodeV1[]; tried: string }",
"exported": false,
"origin": "ast",
-- "body_hash": "0a3f88de2d856cea23e66fd4d8ad75220907ec8ddc44e69a3bf853b37ea113f3",
-- "summary_state": "ready",
++ "body_hash": "761fdde19148564b12710387be9dc92d2fe2f61797a537dfe1d796889e313f66",
++ "summary_state": "stale",
"summary": "Finds nodes in the graph that match the structural subject of a query, enhancing query resolution.",
"crux": {
"code": "function findSubjectNodes(query: string, graph: GraphV1): { nodes: NodeV1[]; tried: string } {\n const words = subjectWords(query).sort((a, b) => b.length - a.length);\n for (const w of words) {\n const nodes = resolveSymbol(graph, w);\n if (nodes.length > 0) return { nodes, tried: w };\n }\n return { nodes: [], tried: words[0] ?? query };\n}",
@@@ -2298,7 -2326,7 +2335,7 @@@
"name": "firstProse",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L65-L72",
- "span": "L66-L73",
++ "span": "L77-L84",
"signature": "function firstProse(body: string): string",
"exported": false,
"origin": "ast",
@@@ -2315,12 -2343,12 +2352,12 @@@
"name": "formatAsk",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L693-L731",
- "span": "L686-L724",
++ "span": "L846-L888",
"signature": "function formatAsk(r: AskResult): string",
"exported": true,
"origin": "ast",
- "body_hash": "413023c3201e82617c165c0ddf39bf37f4e963b7d5c1af202ff4f7132191f8ae",
- "summary_state": "ready",
- "body_hash": "804ecdadf6fb746fe70ea7fa3e2f3d5f4a37e01d04a648e740d6ef7d57af593c",
++ "body_hash": "deabf4d01278ff8b1072c0f08014fbb10def94d18b3dbbec7a42d8511a66d78b",
+ "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,7 -2360,7 +2369,7 @@@
"name": "formatSkeleton",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L676-L685",
- "span": "L668-L678",
++ "span": "L828-L838",
"signature": "function formatSkeleton(r: SkeletonResult): string",
"exported": true,
"origin": "ast",
@@@ -2349,7 -2377,7 +2386,7 @@@
"name": "hasTerm",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L298-L300",
- "span": "L299-L301",
++ "span": "L320-L322",
"signature": "function hasTerm(f: Map<string, number>, t: string): boolean",
"exported": false,
"origin": "ast",
@@@ -2366,7 -2394,7 +2403,7 @@@
"name": "hitFiles",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L560-L569",
- "span": "L561-L570",
++ "span": "L706-L715",
"signature": "function hitFiles(hits: AskHit[]): Set<string>",
"exported": false,
"origin": "ast",
@@@ -2383,7 -2411,7 +2420,7 @@@
"name": "idfFromDf",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L134-L138",
- "span": "L135-L139",
++ "span": "L146-L150",
"signature": "function idfFromDf(df: Map<string, number>, n: number): Map<string, number>",
"exported": false,
"origin": "ast",
@@@ -2400,7 -2428,7 +2437,7 @@@
"name": "inlineSource",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L539-L556",
- "span": "L540-L557",
++ "span": "L685-L702",
"signature": "function inlineSource(root: string, hits: AskHit[], graph: GraphV1 | null, full: boolean): void",
"exported": false,
"origin": "ast",
@@@ -2417,12 -2445,12 +2454,12 @@@
"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",
++ "span": "L347-L627",
++ "signature": "function lexical(query: string, corpus: Corpus, limit: number, graphRank: boolean, inPrefix?: string): AskResult",
"exported": false,
"origin": "ast",
-- "body_hash": "407d174feaf3c69d35c15459e96cb9c0e184097237970ecf6ec87b0e2a4e6fdd",
-- "summary_state": "ready",
++ "body_hash": "bc0d80bd39fefdc2afbe20a539235b3167cde7a91f191c830d5582322e68c769",
++ "summary_state": "stale",
"summary": "Handles lexical queries by scoring documents based on term matches and relevance, returning structured results.",
"crux": {
"code": "function lexical(query: string, corpus: Corpus, limit: number, graphRank: boolean): AskResult {\n // Binary query terms: a word repeated in a pasted issue body counts once, so a\n // ranty description can't linearly amplify an incidental word.\n const q = new Map([...counts(tokenize(query)).keys()].map((t) => [t, 1]));\n const graph = corpus.graph;\n\n // ── Pass 1: tokenize every scored field once, and collect per-document token\n // bags so IDF can down-weight words that occur across the whole corpus. ──\n const conceptDocs = corpus.concepts.map((c) => ({\n c,\n name: counts(tokenize(c.name)),\n body: counts(tokenize(c.text)),",
@@@ -2434,7 -2462,7 +2471,7 @@@
"name": "bodyLen",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L416-L420",
- "span": "L417-L421",
++ "span": "L463-L467",
"signature": "bodyLen = (m: Map<string, number>)",
"exported": false,
"origin": "ast",
@@@ -2451,7 -2479,7 +2488,7 @@@
"name": "loadCorpus",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L83-L108",
- "span": "L84-L109",
++ "span": "L95-L120",
"signature": "function loadCorpus(outDir: string): Corpus",
"exported": false,
"origin": "ast",
@@@ -2468,7 -2496,7 +2505,7 @@@
"name": "matchedIdfShare",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L309-L323",
- "span": "L310-L324",
++ "span": "L331-L345",
"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 +2522,7 @@@
"name": "parseSpan",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L509-L513",
- "span": "L510-L514",
++ "span": "L655-L659",
"signature": "function parseSpan(pointer: string): { path: string; from: number; to: number } | null",
"exported": false,
"origin": "ast",
@@@ -2497,29 -2525,12 +2534,26 @@@
"span": "L255-L257"
}
},
+ {
- "id": "src/ask/ask.ts#savingsFooter",
- "name": "savingsFooter",
++ "id": "src/ask/ask.ts#scopeFooterLines",
++ "name": "scopeFooterLines",
+ "kind": "function",
+ "path": "src/ask/ask.ts",
- "span": "L736-L748",
- "signature": "function savingsFooter(r: AskResult, body: string): string",
++ "span": "L926-L938",
++ "signature": "function scopeFooterLines(r: AskResult): 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"
- }
++ "body_hash": "ce03d65f9e1db5c09735d5949ee47ec715f1c7d1d231741926df77480effc349",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
+ },
{
"id": "src/ask/ask.ts#score",
"name": "score",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L117-L128",
- "span": "L118-L129",
++ "span": "L129-L140",
"signature": "function score( query: Map<string, number>, doc: Map<string, number>, idf: Map<string, number>, ): number",
"exported": false,
"origin": "ast",
@@@ -2536,7 -2547,7 +2570,7 @@@
"name": "skeleton",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L644-L673",
- "span": "L635-L665",
++ "span": "L795-L825",
"signature": "function skeleton(dir: string, file: string, opts: { contextDir?: string } = {}): SkeletonResult",
"exported": true,
"origin": "ast",
@@@ -2553,7 -2564,7 +2587,7 @@@
"name": "startLine",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L661-L661",
- "span": "L652-L652",
++ "span": "L812-L812",
"signature": "startLine = (span: string)",
"exported": true,
"origin": "ast",
@@@ -2570,7 -2581,7 +2604,7 @@@
"name": "SkeletonEntry",
"kind": "interface",
"path": "src/ask/ask.ts",
- "span": "L626-L633",
- "span": "L615-L622",
++ "span": "L775-L782",
"signature": "interface SkeletonEntry",
"exported": true,
"origin": "ast",
@@@ -2587,7 -2598,7 +2621,7 @@@
"name": "SkeletonResult",
"kind": "interface",
"path": "src/ask/ask.ts",
- "span": "L635-L639",
- "span": "L624-L630",
++ "span": "L784-L790",
"signature": "interface SkeletonResult",
"exported": true,
"origin": "ast",
@@@ -2604,7 -2615,7 +2638,7 @@@
"name": "sliceSpan",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L517-L532",
- "span": "L518-L533",
++ "span": "L663-L678",
"signature": "function sliceSpan(root: string, path: string, from: number, to: number): string | null",
"exported": false,
"origin": "ast",
@@@ -2621,12 -2632,12 +2655,12 @@@
"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",
++ "span": "L252-L301",
++ "signature": "function structural(query: string, graph: GraphV1, limit: number, inPrefix?: string): StructuralOutcome",
"exported": false,
"origin": "ast",
-- "body_hash": "882a1b72a392c807907ef0e0f699a41d2f69dacacb713a0597b310d964f5fd30",
-- "summary_state": "ready",
++ "body_hash": "28d22f391db0d7decd6c4e2e0575cb620d13a909f63583789dc5c93c9f021532",
++ "summary_state": "stale",
"summary": "Processes a structural query to find relationships in the graph, returning relevant results or fallthrough notes.",
"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);",
@@@ -2638,7 -2649,7 +2672,7 @@@
"name": "StructuralOutcome",
"kind": "type",
"path": "src/ask/ask.ts",
- "span": "L221-L221",
- "span": "L222-L222",
++ "span": "L243-L243",
"signature": "type StructuralOutcome = { result: AskResult } | { fallthroughNote: string } | null;",
"exported": false,
"origin": "ast",
@@@ -2655,7 -2666,7 +2689,7 @@@
"name": "subjectWords",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L194-L196",
- "span": "L195-L197",
++ "span": "L206-L208",
"signature": "function subjectWords(query: string): string[]",
"exported": false,
"origin": "ast",
@@@ -2672,7 -2683,7 +2706,7 @@@
"name": "toTokens",
"kind": "function",
"path": "src/ask/ask.ts",
- "span": "L688-L690",
- "span": "L681-L683",
++ "span": "L841-L843",
"signature": "function toTokens(chars: number): number",
"exported": false,
"origin": "ast",
@@@ -2684,18 -2695,18 +2718,117 @@@
"span": "L688-L690"
}
},
++ {
++ "id": "src/ask/fuse.ts",
++ "name": "fuse.ts",
++ "kind": "file",
++ "path": "src/ask/fuse.ts",
++ "span": "L1-L224",
++ "signature": null,
++ "exported": true,
++ "origin": "ast",
++ "body_hash": "0b65313aa01758bbef3d80657e806c2427bbecf3d41b1d794f40372e1197a18c",
++ "chars": 9481,
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
++ {
++ "id": "src/ask/fuse.ts#byScore",
++ "name": "byScore",
++ "kind": "function",
++ "path": "src/ask/fuse.ts",
++ "span": "L52-L54",
++ "signature": "function byScore(a: ScopedDoc, b: ScopedDoc): number",
++ "exported": false,
++ "origin": "ast",
++ "body_hash": "2e71862b501450e9cb3bb07de26f16c01dd99618906c59c130a414e7da43a7aa",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
++ {
++ "id": "src/ask/fuse.ts#fuseScopes",
++ "name": "fuseScopes",
++ "kind": "function",
++ "path": "src/ask/fuse.ts",
++ "span": "L67-L130",
++ "signature": "function fuseScopes(docs: ScopedDoc[]): FusionResult",
++ "exported": true,
++ "origin": "ast",
++ "body_hash": "1fc7af0954ef0925b2932d5f741f73f4e3f24ca4d84f2f51a1f0361dd377eac4",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
++ {
++ "id": "src/ask/fuse.ts#FusionResult",
++ "name": "FusionResult",
++ "kind": "interface",
++ "path": "src/ask/fuse.ts",
++ "span": "L30-L40",
++ "signature": "interface FusionResult",
++ "exported": true,
++ "origin": "ast",
++ "body_hash": "4c74f3d554ecf76d50432d9c530683fbef3a6270373dc76c4cfd892c9642e16c",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
++ {
++ "id": "src/ask/fuse.ts#rankScopesAndFuse",
++ "name": "rankScopesAndFuse",
++ "kind": "function",
++ "path": "src/ask/fuse.ts",
++ "span": "L164-L223",
++ "signature": "function rankScopesAndFuse( scopes: string[], ops: ScopeRankOps, graphWeight: number, rescueFloor: number, ): FusionResult",
++ "exported": true,
++ "origin": "ast",
++ "body_hash": "84a89a0ba27ec0a5e74d63aa5840586fc941020843bec3f7ad7631baa04a06bd",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
++ {
++ "id": "src/ask/fuse.ts#ScopedDoc",
++ "name": "ScopedDoc",
++ "kind": "interface",
++ "path": "src/ask/fuse.ts",
++ "span": "L24-L28",
++ "signature": "interface ScopedDoc",
++ "exported": true,
++ "origin": "ast",
++ "body_hash": "7701e249da1aa85502adfa3140abb1817498a34d3e3d5d3982f50d0293d95051",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
++ {
++ "id": "src/ask/fuse.ts#ScopeRankOps",
++ "name": "ScopeRankOps",
++ "kind": "interface",
++ "path": "src/ask/fuse.ts",
++ "span": "L136-L143",
++ "signature": "interface ScopeRankOps",
++ "exported": true,
++ "origin": "ast",
++ "body_hash": "9238611c91e80fbdf72f0c01ee4b28169ee3ba45d8c3a7ee19afac94c1325126",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
{
"id": "src/ask/graphrank.ts",
"name": "graphrank.ts",
"kind": "file",
"path": "src/ask/graphrank.ts",
-- "span": "L1-L102",
++ "span": "L1-L114",
"signature": null,
"exported": true,
"origin": "ast",
-- "body_hash": "a8dfba7907ce7fea84669ddf9ca20f14392b7d1edb5b76db0acf522465078cd5",
-- "chars": 4125,
-- "summary_state": "ready",
++ "body_hash": "6f013649bbb0603d2731d19612da2905d346f86affc95e5b918f2330045ce09b",
++ "chars": 4857,
++ "summary_state": "stale",
"summary": "This module implements a personalized PageRank algorithm to improve the ranking of code nodes based on their structural relevance rather than just lexical similarity.",
"crux": {
"code": " * This module runs personalized PageRank (random-walk-with-restart) over the\n * wiring graph, seeded by the lexical scores. Mass concentrates on nodes that\n * are edge-connected to the matched set; a lexically-matched but structurally\n * isolated node keeps only its own restart mass and sinks. \"Lexical proposes,\n * graph disposes.\" Deterministic, $0, no embeddings — a lexical-seed →\n * graph-rank pipeline, the established alternative to vector search for code.",
@@@ -2707,12 -2718,12 +2840,12 @@@
"name": "PageRankOptions",
"kind": "interface",
"path": "src/ask/graphrank.ts",
-- "span": "L20-L26",
++ "span": "L20-L32",
"signature": "interface PageRankOptions",
"exported": true,
"origin": "ast",
-- "body_hash": "214701bc4bff2de310654c772007fffb60595fa79289cec6d08de2bd084e6ebc",
-- "summary_state": "ready",
++ "body_hash": "0645c00d3cf93eb3d2194eaa5f87937bb16eff0ae937a433068aa3781b91c162",
++ "summary_state": "stale",
"summary": "Defines options for configuring the personalized PageRank algorithm, including restart probability and iteration count.",
"crux": null
},
@@@ -2721,12 -2732,12 +2854,12 @@@
"name": "personalizedPageRank",
"kind": "function",
"path": "src/ask/graphrank.ts",
-- "span": "L39-L101",
++ "span": "L45-L113",
"signature": "function personalizedPageRank( graph: GraphV1, seeds: Map<string, number>, opts: PageRankOptions = {}, ): Map<string, number>",
"exported": true,
"origin": "ast",
-- "body_hash": "9047817eb293e393448f4c82571e0ac123573245583ec00ede7f9c621cda982d",
-- "summary_state": "ready",
++ "body_hash": "5cfcdfdadd4ab08f42acb99d706ef062ccfa94990e40d419cf7d80b9d1580603",
++ "summary_state": "stale",
"summary": "Calculates personalized PageRank scores for nodes in a wiring graph based on provided seeds, enhancing the relevance of code suggestions.",
"crux": {
"code": " let rank = new Map(restart);\n for (let i = 0; i < iters; i++) {\n const next = new Map<string, number>();\n // Teleport: every step, alpha of the mass returns to the seed set.\n for (const [id, r] of restart) next.set(id, alpha * r);\n // Dangling mass (nodes with no walk edges) is pooled and returned to the\n // seed set ONCE per iteration — same math as redistributing per node, but\n // O(nodes + seeds) instead of O(dangling × seeds).\n let dangling = 0;\n for (const [id, mass] of rank) {\n const nbrs = adj.get(id);\n if (!nbrs || nbrs.length === 0) {",
@@@ -2738,7 -2749,7 +2871,7 @@@
"name": "link",
"kind": "function",
"path": "src/ask/graphrank.ts",
-- "span": "L51-L53",
++ "span": "L63-L65",
"signature": "link = (a: string, b: string)",
"exported": true,
"origin": "ast",
@@@ -4444,13 -4455,13 +4577,13 @@@
"name": "cli.ts",
"kind": "file",
"path": "src/cli.ts",
-- "span": "L1-L460",
++ "span": "L1-L468",
"signature": null,
"exported": true,
"origin": "ast",
- "body_hash": "2c7acb076bd022635defd0b67c5358edd3b662328050be6c2d976e6baa17fc9c",
- "chars": 19746,
- "summary_state": "ready",
- "body_hash": "e65431a2048d2659ae9c3faaa4b5e101d85f48f80fd3a8607276259e87000b67",
- "chars": 19707,
++ "body_hash": "85850a973f72f1744c74d4d147bf86f676dd5d17972a877ef12eb16951ccff00",
++ "chars": 20013,
+ "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.\")",
@@@ -5255,13 -5334,13 +5456,13 @@@
"name": "engine.ts",
"kind": "file",
"path": "src/engine.ts",
-- "span": "L1-L141",
++ "span": "L1-L147",
"signature": null,
"exported": true,
"origin": "ast",
-- "body_hash": "55e2191dd67d1e4369c2a872f1b908937bd6034ce6f8f4b03e6c86a059e271c7",
-- "chars": 5445,
-- "summary_state": "ready",
++ "body_hash": "26150fbd17e28dc95952380426b55e2a9ac25089f2fa640fd805b134e499a1fe",
++ "chars": 5506,
++ "summary_state": "stale",
"summary": "The Graft class manages the construction and validation of a context graph from a code repository, ensuring it remains in sync with the codebase.",
"crux": {
"code": " /** Build the `.context/` graph from the repo at `dir`. */\n async init(dir: string, opts: InitOptions = {}): Promise<BuildResult> {\n return buildContext(dir, {\n contextDir: this.cfg.contextDir,\n extensions: opts.extensions,\n model: this.modelLabel(),\n summarizer: this.summarizer(),\n synthesizer: this.synthesizer(),\n onProgress: opts.onProgress,\n });\n }\n",
@@@ -5287,12 -5366,12 +5488,12 @@@
"name": "Graft",
"kind": "class",
"path": "src/engine.ts",
-- "span": "L47-L140",
++ "span": "L47-L146",
"signature": "class Graft",
"exported": true,
"origin": "ast",
-- "body_hash": "adb6ec4334ba397064dea215aa67225cda0e2ae630d092cb55289a43ec5ab406",
-- "summary_state": "ready",
++ "body_hash": "d22bbb74764ee80994c72fca91ae094b550c1c77438aea072d9a87fec2ce2bb9",
++ "summary_state": "stale",
"summary": "Manages the context graph operations, including building and checking synchronization with the codebase.",
"crux": {
"code": " /** Build the `.context/` graph from the repo at `dir`. */\n async init(dir: string, opts: InitOptions = {}): Promise<BuildResult> {\n return buildContext(dir, {\n contextDir: this.cfg.contextDir,\n extensions: opts.extensions,\n model: this.modelLabel(),\n summarizer: this.summarizer(),\n synthesizer: this.synthesizer(),\n onProgress: opts.onProgress,\n });\n }",
@@@ -5304,12 -5383,12 +5505,12 @@@
"name": "ask",
"kind": "method",
"path": "src/engine.ts",
-- "span": "L95-L97",
-- "signature": "ask(dir: string, query: string, opts: { limit?: number; source?: boolean; full?: boolean } = {}): AskResult",
++ "span": "L95-L103",
++ "signature": "ask(dir: string, query: string, opts: { limit?: number; source?: boolean; full?: boolean; in?: string } = {}): AskResult",
"exported": true,
"origin": "ast",
-- "body_hash": "f06a9cfee7165c009dc1154af3d19c72286f5e59f5df7fd0fd096836bbc1cf90",
-- "summary_state": "ready",
++ "body_hash": "855b7e12e241b242096a3b457ea181e47e11d1613583edb30931d473d2b06bfb",
++ "summary_state": "stale",
"summary": "Processes a query against the context graph, returning results based on structural and lexical analysis.",
"crux": {
"code": " ask(dir: string, query: string, opts: { limit?: number; source?: boolean; full?: boolean } = {}): AskResult {\n return ask(dir, query, { contextDir: this.cfg.contextDir, limit: opts.limit, source: opts.source, full: opts.full });",
@@@ -5321,7 -5400,7 +5522,7 @@@
"name": "chatModel",
"kind": "method",
"path": "src/engine.ts",
-- "span": "L102-L119",
++ "span": "L108-L125",
"signature": "private chatModel(): ChatModel",
"exported": true,
"origin": "ast",
@@@ -5389,7 -5468,7 +5590,7 @@@
"name": "cruxSummarizer",
"kind": "method",
"path": "src/engine.ts",
-- "span": "L126-L128",
++ "span": "L132-L134",
"signature": "private cruxSummarizer(): CruxSummarizer",
"exported": true,
"origin": "ast",
@@@ -5440,7 -5519,7 +5641,7 @@@
"name": "modelLabel",
"kind": "method",
"path": "src/engine.ts",
-- "span": "L135-L139",
++ "span": "L141-L145",
"signature": "private modelLabel(): string",
"exported": true,
"origin": "ast",
@@@ -5457,7 -5536,7 +5658,7 @@@
"name": "summarizer",
"kind": "method",
"path": "src/engine.ts",
-- "span": "L130-L132",
++ "span": "L136-L138",
"signature": "private summarizer(): Summarizer",
"exported": true,
"origin": "ast",
@@@ -5474,7 -5553,7 +5675,7 @@@
"name": "synthesizer",
"kind": "method",
"path": "src/engine.ts",
-- "span": "L121-L123",
++ "span": "L127-L129",
"signature": "private synthesizer(): Synthesizer",
"exported": true,
"origin": "ast",
@@@ -5860,27 -5939,27 +6061,41 @@@
"name": "build.ts",
"kind": "file",
"path": "src/graph/build.ts",
-- "span": "L1-L184",
++ "span": "L1-L216",
"signature": null,
"exported": true,
"origin": "ast",
-- "body_hash": "10ae2a085b299a56cb90d41289a956065dd8eef358ae2abbc39db59b82a12dc9",
-- "chars": 6887,
-- "summary_state": "ready",
++ "body_hash": "fe97252d1fd39edda75b40124928d3b820b85f148d380790db92533e5f3ad13d",
++ "chars": 8436,
++ "summary_state": "stale",
"summary": "This file defines the logic for building a graph representation of a code repository, including parsing source files and resolving dependencies.",
"crux": null
},
++ {
++ "id": "src/graph/build.ts#applyMinSubstanceGuard",
++ "name": "applyMinSubstanceGuard",
++ "kind": "function",
++ "path": "src/graph/build.ts",
++ "span": "L32-L47",
++ "signature": "function applyMinSubstanceGuard(scopes: ScopeV1[], nodes: NodeV1[]): ScopeV1[]",
++ "exported": false,
++ "origin": "ast",
++ "body_hash": "ef7ca21fa81ef0b4227430f8b8310ffd8b4b056b13c21789f21461de81bfd36b",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
{
"id": "src/graph/build.ts#buildGraph",
"name": "buildGraph",
"kind": "function",
"path": "src/graph/build.ts",
-- "span": "L78-L183",
++ "span": "L104-L215",
"signature": "async function buildGraph( dir: string, opts: GraphBuildOptions = {}, ): Promise<GraphBuildResult>",
"exported": true,
"origin": "ast",
-- "body_hash": "d1af486578fcbf56fba090f509e508dd3643f0b735167a7277b055e3cf16e450",
-- "summary_state": "ready",
++ "body_hash": "b8723ad9efae1fbdba009f24539b489eac1f9fa7f13848a46a828b9508cf7f20",
++ "summary_state": "stale",
"summary": "This function orchestrates the entire graph building process, from parsing source files to writing the final graph output.",
"crux": {
"code": "export async function buildGraph(\n dir: string,\n opts: GraphBuildOptions = {},\n): Promise<GraphBuildResult> {\n const root = resolve(dir);\n const outDir = contextDirFor(root, opts.contextDir);\n const files = listSourceFiles(root, outDir);\n\n const nodes: NodeV1[] = [];\n const rawEdges: RawEdge[] = [];\n const sources = new Map<string, string>();\n const langs = new Set<Language>();",
@@@ -5892,7 -5971,7 +6107,7 @@@
"name": "GraphBuildOptions",
"kind": "interface",
"path": "src/graph/build.ts",
-- "span": "L23-L36",
++ "span": "L49-L62",
"signature": "interface GraphBuildOptions",
"exported": true,
"origin": "ast",
@@@ -5906,7 -5985,7 +6121,7 @@@
"name": "GraphBuildResult",
"kind": "interface",
"path": "src/graph/build.ts",
-- "span": "L38-L51",
++ "span": "L64-L77",
"signature": "interface GraphBuildResult",
"exported": true,
"origin": "ast",
@@@ -5920,7 -5999,7 +6135,7 @@@
"name": "listSourceFiles",
"kind": "function",
"path": "src/graph/build.ts",
-- "span": "L54-L56",
++ "span": "L80-L82",
"signature": "function listSourceFiles(root: string, outDir: string): string[]",
"exported": true,
"origin": "ast",
@@@ -5937,7 -6016,7 +6152,7 @@@
"name": "readGoModules",
"kind": "function",
"path": "src/graph/build.ts",
-- "span": "L62-L76",
++ "span": "L88-L102",
"signature": "function readGoModules(root: string): GoModule[]",
"exported": false,
"origin": "ast",
@@@ -7388,64 -7467,75 +7603,300 @@@
"span": "L180-L191"
}
},
+ {
- "id": "src/graph/traverse-cli.ts",
- "name": "traverse-cli.ts",
++ "id": "src/graph/scopes.ts",
++ "name": "scopes.ts",
+ "kind": "file",
- "path": "src/graph/traverse-cli.ts",
- "span": "L1-L156",
++ "path": "src/graph/scopes.ts",
++ "span": "L1-L372",
+ "signature": null,
+ "exported": true,
+ "origin": "ast",
- "body_hash": "080714fc91e5caefe4548e87c071b2010fdc593a670366db941d9fd2907b08e2",
- "chars": 5487,
- "summary_state": "ready",
- "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}",
- "span": "L31-L35"
- }
++ "body_hash": "a47e2a9da9c40f42134609f13edfefd91e9d0968787b2a3972fa6d6018f840e3",
++ "chars": 15844,
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
+ },
+ {
- "id": "src/graph/traverse-cli.ts#edgesFor",
- "name": "edgesFor",
- "kind": "function",
- "path": "src/graph/traverse-cli.ts",
- "span": "L31-L35",
- "signature": "function edgesFor(kind: TraverseKind, graph: GraphV1, node: NodeV1, depth: number): EdgeHit[]",
++ "id": "src/graph/scopes.ts#Candidate",
++ "name": "Candidate",
++ "kind": "interface",
++ "path": "src/graph/scopes.ts",
++ "span": "L168-L171",
++ "signature": "interface Candidate",
+ "exported": false,
+ "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": "920700cef1ecb9fbded680bf0681df3b552cdb08a50afc945cdd6acfb06e9e3f",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
+ },
+ {
- "id": "src/graph/traverse-cli.ts#headerOf",
- "name": "headerOf",
++ "id": "src/graph/scopes.ts#collectDirs",
++ "name": "collectDirs",
+ "kind": "function",
- "path": "src/graph/traverse-cli.ts",
- "span": "L41-L43",
- "signature": "function headerOf(n: NodeV1): string",
- "exported": true,
++ "path": "src/graph/scopes.ts",
++ "span": "L37-L56",
++ "signature": "function collectDirs(root: string): string[]",
++ "exported": false,
+ "origin": "ast",
- "body_hash": "cf66c3da70d4f8f16119a88148580dc66acba7d47a6c37e24480581733e44f48",
- "summary_state": "ready",
- "summary": "Generates a formatted header string for a node, providing essential information for display in CLI output.",
- "crux": {
- "code": "export function headerOf(n: NodeV1): string {\n return `${n.name} · ${n.kind} · ${n.path}:${n.span}`;\n}",
- "span": "L41-L43"
- }
++ "body_hash": "478b43f13596223e67fc3f2c5b066cc5600316cdc4de6e221357326b4fdd5268",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
+ },
+ {
- "id": "src/graph/traverse-cli.ts#hitJson",
- "name": "hitJson",
++ "id": "src/graph/scopes.ts#collectDirs.walk",
++ "name": "walk",
++ "kind": "function",
++ "path": "src/graph/scopes.ts",
++ "span": "L39-L53",
++ "signature": "walk = (absDir: string, relDir: string): void",
++ "exported": false,
++ "origin": "ast",
++ "body_hash": "d26aac00009e7f76f7a7e1958f56bb969b377ef8c652b66dc68fc71d7cff8558",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
++ {
++ "id": "src/graph/scopes.ts#discoverScopes",
++ "name": "discoverScopes",
++ "kind": "function",
++ "path": "src/graph/scopes.ts",
++ "span": "L174-L307",
++ "signature": "function discoverScopes(root: string): ScopeV1[]",
++ "exported": true,
++ "origin": "ast",
++ "body_hash": "fc453ac1d5073a3b586e525cbc660a729877e5c647b68b686c1cea8cc27d54d4",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
++ {
++ "id": "src/graph/scopes.ts#discoverScopes.findNearestAncestorCandidate",
++ "name": "findNearestAncestorCandidate",
++ "kind": "function",
++ "path": "src/graph/scopes.ts",
++ "span": "L254-L264",
++ "signature": "findNearestAncestorCandidate = ( prefix: string, set: ReadonlyMap<string, Candidate>, ): string | null",
++ "exported": true,
++ "origin": "ast",
++ "body_hash": "4464e314cca7c830c5dc94dc606b8cc97716610b8bd749a852f644bc639155bc",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
++ {
++ "id": "src/graph/scopes.ts#discoverWorkspaceChildren",
++ "name": "discoverWorkspaceChildren",
++ "kind": "function",
++ "path": "src/graph/scopes.ts",
++ "span": "L347-L364",
++ "signature": "function discoverWorkspaceChildren(root: string): string[]",
++ "exported": true,
++ "origin": "ast",
++ "body_hash": "ad5224035ad5f438b40bc9fc34568618b42c75024d1340fbd41641b5e15488ea",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
++ {
++ "id": "src/graph/scopes.ts#parsePnpmPackagesList",
++ "name": "parsePnpmPackagesList",
++ "kind": "function",
++ "path": "src/graph/scopes.ts",
++ "span": "L60-L73",
++ "signature": "function parsePnpmPackagesList(text: string): string[] | null",
++ "exported": false,
++ "origin": "ast",
++ "body_hash": "497850dd39cb4720ad3f6b0382182385c977c2178be815689d0b09eba7b3124b",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
++ {
++ "id": "src/graph/scopes.ts#pathUnderPrefix",
++ "name": "pathUnderPrefix",
++ "kind": "function",
++ "path": "src/graph/scopes.ts",
++ "span": "L341-L343",
++ "signature": "function pathUnderPrefix(path: string, prefix: string): boolean",
++ "exported": true,
++ "origin": "ast",
++ "body_hash": "8ebed46dc3e14a70b8b67191511101e049c50147e543447e6c767de9d0d17665",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
++ {
++ "id": "src/graph/scopes.ts#readWorkspaceGlobs",
++ "name": "readWorkspaceGlobs",
++ "kind": "function",
++ "path": "src/graph/scopes.ts",
++ "span": "L78-L100",
++ "signature": "function readWorkspaceGlobs(root: string): string[] | null",
++ "exported": false,
++ "origin": "ast",
++ "body_hash": "a9e6972a267d58908ccacb9ef1ce561ec1954bf860ac26b1f57a733920402267",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
++ {
++ "id": "src/graph/scopes.ts#resolveGlob",
++ "name": "resolveGlob",
++ "kind": "function",
++ "path": "src/graph/scopes.ts",
++ "span": "L105-L166",
++ "signature": "function resolveGlob(root: string, pattern: string): string[]",
++ "exported": false,
++ "origin": "ast",
++ "body_hash": "910ede99c36cde0402153047838f72bdc950ecffd69af1c8dcc52dfc814f5c4d",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
++ {
++ "id": "src/graph/scopes.ts#resolveGlob.listDirs",
++ "name": "listDirs",
++ "kind": "function",
++ "path": "src/graph/scopes.ts",
++ "span": "L140-L150",
++ "signature": "listDirs = (absDir: string, relDir: string): string[]",
++ "exported": false,
++ "origin": "ast",
++ "body_hash": "c3df203af729650356a4e79472e0151bad1f5d5dc4dbb43016411c8e3c3c4ecf",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
++ {
++ "id": "src/graph/scopes.ts#scopeLabel",
++ "name": "scopeLabel",
++ "kind": "function",
++ "path": "src/graph/scopes.ts",
++ "span": "L323-L325",
++ "signature": "function scopeLabel(prefix: string): string",
++ "exported": true,
++ "origin": "ast",
++ "body_hash": "9db6c83369a7345b2ce41c3541ed789ed91b628118ad0a2bd273a5fa6577e953",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
++ {
++ "id": "src/graph/scopes.ts#scopeOf",
++ "name": "scopeOf",
++ "kind": "function",
++ "path": "src/graph/scopes.ts",
++ "span": "L312-L318",
++ "signature": "function scopeOf(path: string, scopes: ScopeV1[]): ScopeV1",
++ "exported": true,
++ "origin": "ast",
++ "body_hash": "f022d55c61cb3099f89f4a71a90e41b7227e0ad6b697dd099c5bb25d30f0d349",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
++ {
++ "id": "src/graph/scopes.ts#scopesHereClause",
++ "name": "scopesHereClause",
++ "kind": "function",
++ "path": "src/graph/scopes.ts",
++ "span": "L331-L334",
++ "signature": "function scopesHereClause(scopes: ScopeV1[]): string",
++ "exported": true,
++ "origin": "ast",
++ "body_hash": "8613ad77e3818712539ed410cac6a50fa428b86c7c4463bdee0709dcba65cac8",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
++ {
++ "id": "src/graph/scopes.ts#scopesOfGraph",
++ "name": "scopesOfGraph",
++ "kind": "function",
++ "path": "src/graph/scopes.ts",
++ "span": "L369-L371",
++ "signature": "function scopesOfGraph(graph: GraphV1): ScopeV1[]",
++ "exported": true,
++ "origin": "ast",
++ "body_hash": "f304cd86aef7ba19e8af9543afcc01dc714d92a64570c6207f005aa1a1ddb2d9",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
+ {
+ "id": "src/graph/traverse-cli.ts",
+ "name": "traverse-cli.ts",
+ "kind": "file",
+ "path": "src/graph/traverse-cli.ts",
+ "span": "L1-L183",
+ "signature": null,
+ "exported": true,
+ "origin": "ast",
+ "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}",
+ "span": "L31-L35"
+ }
+ },
+ {
+ "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": "L55-L65",
+ "signature": "function callersSavings( graph: GraphV1, results: { symbol: NodeV1; hits: EdgeHit[] }[], ): Savings | undefined",
+ "exported": true,
+ "origin": "ast",
+ "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": "L38-L40",
+ "signature": "function headerOf(n: NodeV1): string",
+ "exported": true,
+ "origin": "ast",
+ "body_hash": "cf66c3da70d4f8f16119a88148580dc66acba7d47a6c37e24480581733e44f48",
+ "summary_state": "ready",
+ "summary": "Generates a formatted header string for a node, providing essential information for display in CLI output.",
+ "crux": {
+ "code": "export function headerOf(n: NodeV1): string {\n return `${n.name} · ${n.kind} · ${n.path}:${n.span}`;\n}",
+ "span": "L41-L43"
+ }
+ },
+ {
+ "id": "src/graph/traverse-cli.ts#hitJson",
+ "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",
@@@ -7805,13 -7906,13 +8267,13 @@@
"name": "types.ts",
"kind": "file",
"path": "src/graph/types.ts",
-- "span": "L1-L90",
++ "span": "L1-L103",
"signature": null,
"exported": true,
"origin": "ast",
-- "body_hash": "27a9bdbef7783e5da94c860bc83525ef788e38a2176bc1184c8adbee539b1b51",
-- "chars": 3148,
-- "summary_state": "ready",
++ "body_hash": "745855a49536d9dac6a755a03cde0edff96f2acb089d14c8e4c9f2b415fc1d2e",
++ "chars": 3789,
++ "summary_state": "stale",
"summary": "Defines the structure and relationships of a code graph schema, facilitating the representation of code elements and their interactions.",
"crux": {
"code": "/**\n * `graph.json` — the code graph schema (v1).\n *\n * One node per definition (file, class, function, method, interface, type, enum),\n * wired by edges (contains, imports, calls, ...). Field names follow the LSP /\n * SCIP vocabulary (`name`, `kind`, ...) rather than any one tool's conventions.\n *\n * Two tiers of data live on a node:\n * - Tier-1 (deterministic, $0): everything from the AST. Rebuilt on every run.\n * - Tier-2 (one LLM call, cached on `body_hash`): `summary` + `crux`.\n * M1 populates Tier-1 only; Tier-2 fields ship as `pending`/null.\n */",
@@@ -7874,12 -7975,12 +8336,12 @@@
"name": "GraphV1",
"kind": "interface",
"path": "src/graph/types.ts",
-- "span": "L80-L89",
++ "span": "L90-L102",
"signature": "interface GraphV1",
"exported": true,
"origin": "ast",
-- "body_hash": "fa588451b38bfa2c1ea17eeabb5cd4d18769ecbf75ba79fb160d59d2d2666e8e",
-- "summary_state": "ready",
++ "body_hash": "369c9f71b71b2f6f38cfd27efd98311d1231bec2990215a97e776d9f84281f27",
++ "summary_state": "stale",
"summary": "Encapsulates the entire graph structure, including metadata and collections of nodes and edges.",
"crux": {
"code": "export interface GraphV1 {\n meta: {\n version: 1;\n nodeCount: number;\n edgeCount: number;\n languages: string[];\n };\n nodes: NodeV1[];\n edges: EdgeV1[];\n}",
@@@ -7937,13 -8038,13 +8399,27 @@@
"span": "L57-L63"
}
},
+ {
- "id": "src/graph/types.ts#SummaryState",
- "name": "SummaryState",
- "kind": "type",
++ "id": "src/graph/types.ts#ScopeV1",
++ "name": "ScopeV1",
++ "kind": "interface",
+ "path": "src/graph/types.ts",
- "span": "L29-L29",
- "signature": "type SummaryState = \"pending\" | \"ready\" | \"stale\";",
++ "span": "L84-L88",
++ "signature": "interface ScopeV1",
++ "exported": true,
++ "origin": "ast",
++ "body_hash": "e9815468264f0035da829ebd87cd5b705e7bbdcccaba90ba7d9be8e0c14dc7e4",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
+ {
+ "id": "src/graph/types.ts#SummaryState",
+ "name": "SummaryState",
+ "kind": "type",
+ "path": "src/graph/types.ts",
+ "span": "L29-L29",
+ "signature": "type SummaryState = \"pending\" | \"ready\" | \"stale\";",
"exported": true,
"origin": "ast",
"body_hash": "0689b3a76aa3ee3553bec1bccff2817cac613e747d317688f296748e8c929e0e",
@@@ -8758,12 -8859,12 +9234,12 @@@
"name": "tools.ts",
"kind": "file",
"path": "src/mcp/tools.ts",
- "span": "L1-L243",
- "span": "L1-L216",
++ "span": "L1-L221",
"signature": null,
"exported": true,
"origin": "ast",
- "body_hash": "26d386319a711ec0eb758a2561513dc05e164f2c4d5828b6089b41db2b0a715b",
- "chars": 10847,
- "body_hash": "aaf51610f56c46c7cd820891375c55e84f2b8f107495801b825b28b29fd0636b",
- "chars": 9754,
++ "body_hash": "c481205e1888764a7f6bba2bd2f8180aad34a26b76b770fa9eb98922095f8f37",
++ "chars": 10020,
"summary_state": "pending",
"summary": null,
"crux": null
@@@ -8773,12 -8874,12 +9249,12 @@@
"name": "callTool",
"kind": "function",
"path": "src/mcp/tools.ts",
- "span": "L149-L242",
- "span": "L134-L215",
++ "span": "L138-L220",
"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",
++ "body_hash": "2b07af42cf0890c11f542f61ab35d633d359cd356837ac762eacef33eaebd660",
+ "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 +9266,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",
++ "span": "L121-L136",
+ "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}",
@@@ -9531,6 -9632,6 +10007,49 @@@
"summary": "Defines the configuration options required to start the visualization server.",
"crux": null
},
++ {
++ "id": "test/ask-fusion.test.ts",
++ "name": "ask-fusion.test.ts",
++ "kind": "file",
++ "path": "test/ask-fusion.test.ts",
++ "span": "L1-L187",
++ "signature": null,
++ "exported": true,
++ "origin": "ast",
++ "body_hash": "8a50eb2ee2a7080cec7c15cecaae2d88d544de3aa574d2964e4c7b1cd007e262",
++ "chars": 7741,
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
++ {
++ "id": "test/ask-fusion.test.ts#makeOps",
++ "name": "makeOps",
++ "kind": "function",
++ "path": "test/ask-fusion.test.ts",
++ "span": "L120-L133",
++ "signature": "function makeOps(bRaw: number): ScopeRankOps",
++ "exported": false,
++ "origin": "ast",
++ "body_hash": "f3084c8993ffa26e4eae0137380efb9b1905f1a8b20eca904db995a40a51cc02",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
++ {
++ "id": "test/ask-fusion.test.ts#scopeDocs",
++ "name": "scopeDocs",
++ "kind": "function",
++ "path": "test/ask-fusion.test.ts",
++ "span": "L19-L21",
++ "signature": "function scopeDocs(scope: string, scores: number[]): ScopedDoc[]",
++ "exported": false,
++ "origin": "ast",
++ "body_hash": "8d5a6b8359ac99c0090d6fe289ac6046438586342fae817aafd18bee03eb130d",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
{
"id": "test/ask-index.test.ts",
"name": "ask-index.test.ts",
@@@ -9602,25 -9703,25 +10121,53 @@@
"name": "ask.test.ts",
"kind": "file",
"path": "test/ask.test.ts",
-- "span": "L1-L284",
++ "span": "L1-L651",
"signature": null,
"exported": true,
"origin": "ast",
-- "body_hash": "3445f8b156ba6b2f0e9123e9fc45781da352ec6d5baeb985ee144fe5aecaafb3",
-- "chars": 11713,
-- "summary_state": "ready",
++ "body_hash": "8fb44f43e36a31cd9d0e517666c39bcd3db352be9b26743d67bb3a2ea3f31df9",
++ "chars": 29002,
++ "summary_state": "stale",
"summary": "Contains tests for the `ask` functionality, validating its behavior with various options and scenarios.",
"crux": {
"code": "test(\"ask without source returns pointers but no inlined code\", async () => {\n const dir = makeFixture();\n try {\n await buildGraph(dir); // $0, structure-only — cards + wiring.json\n const r = ask(dir, \"addNumbers\");\n const hit = r.hits.find((h) => h.title.startsWith(\"addNumbers\"));\n assert.ok(hit, \"should locate the addNumbers symbol\");\n assert.match(hit.pointer, /^math\\.ts:L\\d+-L\\d+$/);\n assert.equal(hit.code, undefined, \"no source inlined without the option\");\n } finally {\n rmSync(dir, { recursive: true, force: true });\n }",
"span": "L27-L38"
}
},
++ {
++ "id": "test/ask.test.ts#duplicateNameFixture",
++ "name": "duplicateNameFixture",
++ "kind": "function",
++ "path": "test/ask.test.ts",
++ "span": "L555-L570",
++ "signature": "function duplicateNameFixture(): string",
++ "exported": false,
++ "origin": "ast",
++ "body_hash": "65d26c7671c925c41a2a09cad0036295c2ad65006b7f1a58c0c460bed2b31ddd",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
++ {
++ "id": "test/ask.test.ts#idfShiftFixture",
++ "name": "idfShiftFixture",
++ "kind": "function",
++ "path": "test/ask.test.ts",
++ "span": "L370-L381",
++ "signature": "function idfShiftFixture(): string",
++ "exported": false,
++ "origin": "ast",
++ "body_hash": "8a01704e38cec0ac645d0230c648b406a620aabb1cb504882c8badcb533027e3",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
{
"id": "test/ask.test.ts#makeFixture",
"name": "makeFixture",
"kind": "function",
"path": "test/ask.test.ts",
-- "span": "L16-L25",
++ "span": "L17-L26",
"signature": "function makeFixture(): string",
"exported": false,
"origin": "ast",
@@@ -9632,12 -9733,12 +10179,26 @@@
"span": "L16-L23"
}
},
++ {
++ "id": "test/ask.test.ts#multiScopeFixture",
++ "name": "multiScopeFixture",
++ "kind": "function",
++ "path": "test/ask.test.ts",
++ "span": "L277-L310",
++ "signature": "function multiScopeFixture(): string",
++ "exported": false,
++ "origin": "ast",
++ "body_hash": "861ae2479922824311b7da16753f6517024cd4f5989bc02070ca3ec7d0270cf2",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
{
"id": "test/ask.test.ts#qualifiedFixture",
"name": "qualifiedFixture",
"kind": "function",
"path": "test/ask.test.ts",
-- "span": "L189-L207",
++ "span": "L190-L208",
"signature": "function qualifiedFixture(): string",
"exported": false,
"origin": "ast",
@@@ -9649,12 -9750,12 +10210,40 @@@
"span": "L198-L200"
}
},
++ {
++ "id": "test/ask.test.ts#rankOf",
++ "name": "rankOf",
++ "kind": "function",
++ "path": "test/ask.test.ts",
++ "span": "L388-L388",
++ "signature": "rankOf = (r: ReturnType<typeof ask>[\"hits\"], title: string)",
++ "exported": false,
++ "origin": "ast",
++ "body_hash": "c03a498c384ff31544d9daa078d91655c746bfcf8f10830ad1e4f0f720e14717",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
++ {
++ "id": "test/ask.test.ts#siblingPrefixFixture",
++ "name": "siblingPrefixFixture",
++ "kind": "function",
++ "path": "test/ask.test.ts",
++ "span": "L336-L343",
++ "signature": "function siblingPrefixFixture(): string",
++ "exported": false,
++ "origin": "ast",
++ "body_hash": "c852d824057f313b5bb59d469c1e04b442dc6b8a3f15e5643e8edbb98c0504f1",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
{
"id": "test/ask.test.ts#stampCrux",
"name": "stampCrux",
"kind": "function",
"path": "test/ask.test.ts",
-- "span": "L43-L49",
++ "span": "L44-L50",
"signature": "function stampCrux(dir: string, code: string): void",
"exported": false,
"origin": "ast",
@@@ -10392,57 -10493,57 +10981,142 @@@
}
},
{
- "id": "test/graph-map.test.ts#symNode",
- "name": "symNode",
+ "id": "test/graph-map.test.ts#symNode",
+ "name": "symNode",
+ "kind": "function",
+ "path": "test/graph-map.test.ts",
+ "span": "L33-L49",
+ "signature": "function symNode(path: string, name: string, opts: { kind?: Kind; span?: string } = {}): NodeV1",
+ "exported": false,
+ "origin": "ast",
+ "body_hash": "819353898b73f80877d6102fc06f582cec736379220bb864d8be47c3a5107314",
+ "summary_state": "ready",
+ "summary": "Generates a symbol node representation for the graph, allowing for the inclusion of function or variable symbols with associated metadata.",
+ "crux": {
+ "code": "function symNode(path: string, name: string, opts: { kind?: Kind; span?: string } = {}): NodeV1 {\n const id = `${path}#${name}`;\n return {\n id,\n name,\n kind: opts.kind ?? \"function\",\n path,\n span: opts.span ?? \"L1-L10\",\n signature: `${name}()`,\n exported: true,\n origin: \"ast\",\n body_hash: `h${counter++}`,",
+ "span": "L33-L44"
+ }
+ },
+ {
+ "id": "test/graph-resolve-typed.test.ts",
+ "name": "graph-resolve-typed.test.ts",
+ "kind": "file",
+ "path": "test/graph-resolve-typed.test.ts",
+ "span": "L1-L93",
+ "signature": null,
+ "exported": true,
+ "origin": "ast",
+ "body_hash": "0c3760525cc61ee97de448fa26b4a5b9a3bb07c03b4acfbdf3608541b189cf81",
+ "chars": 4908,
+ "summary_state": "ready",
+ "summary": "This test file verifies the resolution of method calls and inheritance in a graph of nodes representing code elements, ensuring correct behavior in various scenarios.",
+ "crux": {
+ "code": "test(\"typed member call resolves despite global name ambiguity\", () => {\n const edges = resolveEdges(NODES, [\n { source: \"t.py#test_x\", relation: \"calls\", name: \"include_router\", viaMember: true, recvType: \"FastAPI\", file: \"t.py\" },\n ]);\n const call = edges.find((e) => e.relation === \"calls\");\n assert.equal(call?.target, \"app.py#FastAPI.include_router\");\n assert.equal(call?.confidence, \"inferred\");\n});\n\ntest(\"untyped ambiguous member call still drops (regression guard)\", () => {\n const edges = resolveEdges(NODES, [\n { source: \"t.py#test_x\", relation: \"calls\", name: \"include_router\", viaMember: true, file: \"t.py\" },",
+ "span": "L18-L29"
+ }
+ },
+ {
+ "id": "test/graph-resolve-typed.test.ts#n",
+ "name": "n",
+ "kind": "function",
+ "path": "test/graph-resolve-typed.test.ts",
+ "span": "L6-L10",
+ "signature": "function n(id: string, kind: NodeV1[\"kind\"]): NodeV1",
+ "exported": false,
+ "origin": "ast",
+ "body_hash": "25448bda72366b6bf9233cc1f03e63aa5ef4e1c2253c876b7c2223db09c163fc",
+ "summary_state": "ready",
+ "summary": "Creates a NodeV1 object representing a code element with its associated metadata, facilitating the construction of a node graph for resolution tests.",
+ "crux": {
+ "code": " const name = id.includes(\"#\") ? id.split(\"#\")[1].split(\".\").pop()! : id;\n return { id, name, kind, path: id.split(\"#\")[0], span: \"L1-L1\", signature: null,\n exported: true, origin: \"ast\", body_hash: \"h\", summary_state: \"pending\", summary: null, crux: null } as NodeV1;",
+ "span": "L7-L9"
+ }
+ },
++ {
++ "id": "test/graph-scopes.test.ts",
++ "name": "graph-scopes.test.ts",
++ "kind": "file",
++ "path": "test/graph-scopes.test.ts",
++ "span": "L1-L203",
++ "signature": null,
++ "exported": true,
++ "origin": "ast",
++ "body_hash": "030dea9cb5a26fac262acf50101289a62655681d7dd487a3518e59a64db209d8",
++ "chars": 8316,
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
++ {
++ "id": "test/graph-scopes.test.ts#fx",
++ "name": "fx",
++ "kind": "function",
++ "path": "test/graph-scopes.test.ts",
++ "span": "L17-L24",
++ "signature": "function fx(layout: Record<string, string>): string",
++ "exported": false,
++ "origin": "ast",
++ "body_hash": "8ab0bd0d4ecd0a2c1738c41a1260ab74a8f9407edaa90b444b43b8e8180058b1",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
++ {
++ "id": "test/graph-scopes.test.ts#normalize",
++ "name": "normalize",
++ "kind": "function",
++ "path": "test/graph-scopes.test.ts",
++ "span": "L93-L94",
++ "signature": "normalize = (prefixes: string[], siblingName: string): string[]",
++ "exported": false,
++ "origin": "ast",
++ "body_hash": "0da47baf7c1a7c14a23a56b743085bac4a9620dffbb4751e23ea705c176b3d5b",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
++ },
++ {
++ "id": "test/graph-scopes.test.ts#pyFns",
++ "name": "pyFns",
+ "kind": "function",
- "path": "test/graph-map.test.ts",
- "span": "L33-L49",
- "signature": "function symNode(path: string, name: string, opts: { kind?: Kind; span?: string } = {}): NodeV1",
++ "path": "test/graph-scopes.test.ts",
++ "span": "L159-L161",
++ "signature": "function pyFns(n: number): string",
+ "exported": false,
+ "origin": "ast",
- "body_hash": "819353898b73f80877d6102fc06f582cec736379220bb864d8be47c3a5107314",
- "summary_state": "ready",
- "summary": "Generates a symbol node representation for the graph, allowing for the inclusion of function or variable symbols with associated metadata.",
- "crux": {
- "code": "function symNode(path: string, name: string, opts: { kind?: Kind; span?: string } = {}): NodeV1 {\n const id = `${path}#${name}`;\n return {\n id,\n name,\n kind: opts.kind ?? \"function\",\n path,\n span: opts.span ?? \"L1-L10\",\n signature: `${name}()`,\n exported: true,\n origin: \"ast\",\n body_hash: `h${counter++}`,",
- "span": "L33-L44"
- }
++ "body_hash": "66058beee96d43f3e99600dd019dfff7771d96c51cbefa76db334ba5a08dec6f",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
+ },
+ {
- "id": "test/graph-resolve-typed.test.ts",
- "name": "graph-resolve-typed.test.ts",
- "kind": "file",
- "path": "test/graph-resolve-typed.test.ts",
- "span": "L1-L93",
- "signature": null,
- "exported": true,
++ "id": "test/graph-scopes.test.ts#run",
++ "name": "run",
++ "kind": "function",
++ "path": "test/graph-scopes.test.ts",
++ "span": "L75-L89",
++ "signature": "run = (siblingName: string): string[]",
++ "exported": false,
+ "origin": "ast",
- "body_hash": "0c3760525cc61ee97de448fa26b4a5b9a3bb07c03b4acfbdf3608541b189cf81",
- "chars": 4908,
- "summary_state": "ready",
- "summary": "This test file verifies the resolution of method calls and inheritance in a graph of nodes representing code elements, ensuring correct behavior in various scenarios.",
- "crux": {
- "code": "test(\"typed member call resolves despite global name ambiguity\", () => {\n const edges = resolveEdges(NODES, [\n { source: \"t.py#test_x\", relation: \"calls\", name: \"include_router\", viaMember: true, recvType: \"FastAPI\", file: \"t.py\" },\n ]);\n const call = edges.find((e) => e.relation === \"calls\");\n assert.equal(call?.target, \"app.py#FastAPI.include_router\");\n assert.equal(call?.confidence, \"inferred\");\n});\n\ntest(\"untyped ambiguous member call still drops (regression guard)\", () => {\n const edges = resolveEdges(NODES, [\n { source: \"t.py#test_x\", relation: \"calls\", name: \"include_router\", viaMember: true, file: \"t.py\" },",
- "span": "L18-L29"
- }
++ "body_hash": "1ad4b6cd5889ea9fd5db15c6aa691788477f3e18a1a38d2faaa36347ef1fab0b",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
+ },
+ {
- "id": "test/graph-resolve-typed.test.ts#n",
- "name": "n",
++ "id": "test/graph-scopes.test.ts#tsFns",
++ "name": "tsFns",
+ "kind": "function",
- "path": "test/graph-resolve-typed.test.ts",
- "span": "L6-L10",
- "signature": "function n(id: string, kind: NodeV1[\"kind\"]): NodeV1",
++ "path": "test/graph-scopes.test.ts",
++ "span": "L155-L157",
++ "signature": "function tsFns(n: number): string",
+ "exported": false,
+ "origin": "ast",
- "body_hash": "25448bda72366b6bf9233cc1f03e63aa5ef4e1c2253c876b7c2223db09c163fc",
- "summary_state": "ready",
- "summary": "Creates a NodeV1 object representing a code element with its associated metadata, facilitating the construction of a node graph for resolution tests.",
- "crux": {
- "code": " const name = id.includes(\"#\") ? id.split(\"#\")[1].split(\".\").pop()! : id;\n return { id, name, kind, path: id.split(\"#\")[0], span: \"L1-L1\", signature: null,\n exported: true, origin: \"ast\", body_hash: \"h\", summary_state: \"pending\", summary: null, crux: null } as NodeV1;",
- "span": "L7-L9"
- }
++ "body_hash": "3b0fd3e3016031d46b2c8e0c42d7571ad9c0abfe7656557ae90064211618503d",
++ "summary_state": "pending",
++ "summary": null,
++ "crux": null
+ },
{
"id": "test/graph-traverse-cli.test.ts",
"name": "graph-traverse-cli.test.ts",
@@@ -10655,13 -10756,13 +11329,13 @@@
"name": "graphrank.test.ts",
"kind": "file",
"path": "test/graphrank.test.ts",
-- "span": "L1-L203",
++ "span": "L1-L257",
"signature": null,
"exported": true,
"origin": "ast",
-- "body_hash": "9b6450a705fd5bbe7ddead7ae29f87fcb839599d34b6bd0c8ebcb0091ee70c47",
-- "chars": 8780,
-- "summary_state": "ready",
++ "body_hash": "e4e6155adc501b4d336cba4ad49192310678cf67f3547e2b362bfcb68f30a53e",
++ "chars": 11404,
++ "summary_state": "stale",
"summary": "This file contains unit and integration tests for the personalizedPageRank function, ensuring it correctly ranks nodes based on their connectivity in a graph.",
"crux": {
"code": "test(\"PageRank: a seed wired to the cluster outranks an isolated seed\", () => {\n // hub calls a, b, c; lone is a disconnected seed with equal restart weight.\n const g = graphOf(\n [\"hub\", \"a\", \"b\", \"c\", \"lone\"],\n [edge(\"hub\", \"a\"), edge(\"hub\", \"b\"), edge(\"hub\", \"c\")],\n );\n const pr = personalizedPageRank(g, new Map([[\"hub\", 1], [\"lone\", 1]]));\n assert.ok((pr.get(\"hub\") ?? 0) > (pr.get(\"lone\") ?? 0), \"connected seed beats isolated seed\");\n assert.equal([...pr.values()].some((v) => v === 1), true, \"top node normalized to 1\");\n});\n\ntest(\"PageRank: neighbours of a seed accrue mass even with zero restart weight\", () => {",
@@@ -10707,7 -10808,7 +11381,7 @@@
"name": "makeCollisionFixture",
"kind": "function",
"path": "test/graphrank.test.ts",
-- "span": "L128-L138",
++ "span": "L182-L192",
"signature": "function makeCollisionFixture(): string",
"exported": false,
"origin": "ast",
@@@ -10741,7 -10842,7 +11415,7 @@@
"name": "rank",
"kind": "function",
"path": "test/graphrank.test.ts",
-- "span": "L140-L141",
++ "span": "L194-L195",
"signature": "rank = (dir: string, gr: boolean)",
"exported": false,
"origin": "ast",
@@@ -11254,13 -11355,13 +11928,13 @@@
"name": "mcp-tools.test.ts",
"kind": "file",
"path": "test/mcp-tools.test.ts",
- "span": "L1-L290",
- "span": "L1-L289",
++ "span": "L1-L301",
"signature": null,
"exported": true,
"origin": "ast",
- "body_hash": "22d3a32a85a0ba1542969786e8bda07d3df02ee068554d4070f705d30d7239dc",
- "chars": 12646,
- "summary_state": "ready",
- "body_hash": "edf9190673e0d472438bdad78bcfd03682c847a6a8f11e90f8a1425f5bcd45ef",
- "chars": 12727,
++ "body_hash": "2241812ee605797530ebbbd0e646833ba632460cd2ce3a0b80d44cd53f6ef844",
++ "chars": 13284,
+ "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) {",
@@@ -14098,12 -14211,6 +14784,12 @@@
"relation": "contains",
"confidence": "extracted"
},
+ {
+ "source": "src/ask/ask.ts",
- "target": "src/ask/ask.ts#savingsFooter",
++ "target": "src/ask/ask.ts#scopeFooterLines",
+ "relation": "contains",
+ "confidence": "extracted"
+ },
{
"source": "src/ask/ask.ts",
"target": "src/ask/ask.ts#score",
@@@ -14176,6 -14283,6 +14862,12 @@@
"relation": "imports",
"confidence": "extracted"
},
++ {
++ "source": "src/ask/ask.ts",
++ "target": "src/ask/fuse.ts",
++ "relation": "imports",
++ "confidence": "extracted"
++ },
{
"source": "src/ask/ask.ts",
"target": "src/ask/graphrank.ts",
@@@ -14200,6 -14313,6 +14898,12 @@@
"relation": "imports",
"confidence": "extracted"
},
++ {
++ "source": "src/ask/ask.ts",
++ "target": "src/graph/scopes.ts",
++ "relation": "imports",
++ "confidence": "extracted"
++ },
{
"source": "src/ask/ask.ts",
"target": "src/graph/traverse.ts",
@@@ -14248,6 -14361,12 +14952,30 @@@
"relation": "calls",
"confidence": "inferred"
},
++ {
++ "source": "src/ask/ask.ts#ask",
++ "target": "src/graph/scopes.ts#pathUnderPrefix",
++ "relation": "calls",
++ "confidence": "inferred"
++ },
++ {
++ "source": "src/ask/ask.ts#ask",
++ "target": "src/graph/scopes.ts#scopesHereClause",
++ "relation": "calls",
++ "confidence": "inferred"
++ },
++ {
++ "source": "src/ask/ask.ts#ask",
++ "target": "src/graph/scopes.ts#scopesOfGraph",
++ "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",
@@@ -14272,6 -14397,6 +15006,12 @@@
"relation": "calls",
"confidence": "extracted"
},
++ {
++ "source": "src/ask/ask.ts#findSubjectNodes",
++ "target": "src/graph/scopes.ts#pathUnderPrefix",
++ "relation": "calls",
++ "confidence": "inferred"
++ },
{
"source": "src/ask/ask.ts#findSubjectNodes",
"target": "src/graph/traverse.ts#resolveSymbol",
@@@ -14280,10 -14405,22 +15020,28 @@@
},
{
"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#formatAsk",
++ "target": "src/ask/ask.ts#scopeFooterLines",
+ "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",
@@@ -14338,6 -14475,6 +15096,12 @@@
"relation": "calls",
"confidence": "extracted"
},
++ {
++ "source": "src/ask/ask.ts#lexical",
++ "target": "src/ask/fuse.ts#rankScopesAndFuse",
++ "relation": "calls",
++ "confidence": "inferred"
++ },
{
"source": "src/ask/ask.ts#lexical",
"target": "src/ask/graphrank.ts#personalizedPageRank",
@@@ -14356,6 -14493,6 +15120,30 @@@
"relation": "calls",
"confidence": "inferred"
},
++ {
++ "source": "src/ask/ask.ts#lexical",
++ "target": "src/graph/scopes.ts#pathUnderPrefix",
++ "relation": "calls",
++ "confidence": "inferred"
++ },
++ {
++ "source": "src/ask/ask.ts#lexical",
++ "target": "src/graph/scopes.ts#scopeOf",
++ "relation": "calls",
++ "confidence": "inferred"
++ },
++ {
++ "source": "src/ask/ask.ts#lexical",
++ "target": "src/graph/scopes.ts#scopesHereClause",
++ "relation": "calls",
++ "confidence": "inferred"
++ },
++ {
++ "source": "src/ask/ask.ts#lexical",
++ "target": "src/graph/scopes.ts#scopesOfGraph",
++ "relation": "calls",
++ "confidence": "inferred"
++ },
{
"source": "src/ask/ask.ts#lexical",
"target": "src/ask/ask.ts#lexical.bodyLen",
@@@ -14386,12 -14523,6 +15174,12 @@@
"relation": "calls",
"confidence": "extracted"
},
+ {
- "source": "src/ask/ask.ts#savingsFooter",
- "target": "src/ask/ask.ts#toTokens",
++ "source": "src/ask/ask.ts#scopeFooterLines",
++ "target": "src/graph/scopes.ts#scopeLabel",
+ "relation": "calls",
- "confidence": "extracted"
++ "confidence": "inferred"
+ },
{
"source": "src/ask/ask.ts#skeleton",
"target": "src/ask/ask.ts#skeleton.startLine",
@@@ -14428,6 -14565,6 +15222,48 @@@
"relation": "calls",
"confidence": "extracted"
},
++ {
++ "source": "src/ask/fuse.ts",
++ "target": "src/ask/fuse.ts#byScore",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/ask/fuse.ts",
++ "target": "src/ask/fuse.ts#fuseScopes",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/ask/fuse.ts",
++ "target": "src/ask/fuse.ts#FusionResult",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/ask/fuse.ts",
++ "target": "src/ask/fuse.ts#rankScopesAndFuse",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/ask/fuse.ts",
++ "target": "src/ask/fuse.ts#ScopedDoc",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/ask/fuse.ts",
++ "target": "src/ask/fuse.ts#ScopeRankOps",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/ask/fuse.ts#rankScopesAndFuse",
++ "target": "src/ask/fuse.ts#fuseScopes",
++ "relation": "calls",
++ "confidence": "extracted"
++ },
{
"source": "src/ask/graphrank.ts",
"target": "src/ask/graphrank.ts#PageRankOptions",
@@@ -17140,6 -17325,6 +18024,12 @@@
"relation": "calls",
"confidence": "extracted"
},
++ {
++ "source": "src/graph/build.ts",
++ "target": "src/graph/build.ts#applyMinSubstanceGuard",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
{
"source": "src/graph/build.ts",
"target": "src/graph/build.ts#buildGraph",
@@@ -17224,6 -17409,6 +18114,12 @@@
"relation": "imports",
"confidence": "extracted"
},
++ {
++ "source": "src/graph/build.ts",
++ "target": "src/graph/scopes.ts",
++ "relation": "imports",
++ "confidence": "extracted"
++ },
{
"source": "src/graph/build.ts",
"target": "src/graph/types.ts",
@@@ -17242,6 -17427,6 +18138,12 @@@
"relation": "imports",
"confidence": "extracted"
},
++ {
++ "source": "src/graph/build.ts#applyMinSubstanceGuard",
++ "target": "src/graph/scopes.ts#scopeOf",
++ "relation": "calls",
++ "confidence": "inferred"
++ },
{
"source": "src/graph/build.ts#buildGraph",
"target": "src/ask/index-file.ts#writeAskIndex",
@@@ -17254,9 -17439,15 +18156,15 @@@
"relation": "calls",
"confidence": "inferred"
},
+ {
+ "source": "src/graph/build.ts#buildGraph",
- "target": "src/graph/build.ts#listSourceFiles",
++ "target": "src/graph/build.ts#applyMinSubstanceGuard",
+ "relation": "calls",
+ "confidence": "extracted"
+ },
{
"source": "src/graph/build.ts#buildGraph",
- "target": "src/graph/build.ts#readGoModules",
+ "target": "src/graph/build.ts#listSourceFiles",
"relation": "calls",
"confidence": "extracted"
},
@@@ -17308,6 -17493,6 +18216,12 @@@
"relation": "calls",
"confidence": "inferred"
},
++ {
++ "source": "src/graph/build.ts#buildGraph",
++ "target": "src/graph/scopes.ts#discoverScopes",
++ "relation": "calls",
++ "confidence": "inferred"
++ },
{
"source": "src/graph/build.ts#buildGraph",
"target": "src/graph/write.ts#readGraph",
@@@ -18466,9 -18669,15 +19398,183 @@@
"relation": "contains",
"confidence": "extracted"
},
++ {
++ "source": "src/graph/scopes.ts",
++ "target": "src/graph/scopes.ts#Candidate",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/graph/scopes.ts",
++ "target": "src/graph/scopes.ts#collectDirs",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/graph/scopes.ts",
++ "target": "src/graph/scopes.ts#discoverScopes",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/graph/scopes.ts",
++ "target": "src/graph/scopes.ts#discoverWorkspaceChildren",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/graph/scopes.ts",
++ "target": "src/graph/scopes.ts#parsePnpmPackagesList",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/graph/scopes.ts",
++ "target": "src/graph/scopes.ts#pathUnderPrefix",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/graph/scopes.ts",
++ "target": "src/graph/scopes.ts#readWorkspaceGlobs",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/graph/scopes.ts",
++ "target": "src/graph/scopes.ts#resolveGlob",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/graph/scopes.ts",
++ "target": "src/graph/scopes.ts#scopeLabel",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/graph/scopes.ts",
++ "target": "src/graph/scopes.ts#scopeOf",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/graph/scopes.ts",
++ "target": "src/graph/scopes.ts#scopesHereClause",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/graph/scopes.ts",
++ "target": "src/graph/scopes.ts#scopesOfGraph",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/graph/scopes.ts",
++ "target": "node:fs",
++ "relation": "imports",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/graph/scopes.ts",
++ "target": "node:path",
++ "relation": "imports",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/graph/scopes.ts",
++ "target": "src/graph/types.ts",
++ "relation": "imports",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/graph/scopes.ts",
++ "target": "src/ingest/fs.ts",
++ "relation": "imports",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/graph/scopes.ts#collectDirs",
++ "target": "src/graph/scopes.ts#collectDirs.walk",
++ "relation": "calls",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/graph/scopes.ts#collectDirs",
++ "target": "src/graph/scopes.ts#collectDirs.walk",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/graph/scopes.ts#collectDirs.walk",
++ "target": "src/graph/scopes.ts#collectDirs.walk",
++ "relation": "calls",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/graph/scopes.ts#discoverScopes",
++ "target": "src/graph/scopes.ts#collectDirs",
++ "relation": "calls",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/graph/scopes.ts#discoverScopes",
++ "target": "src/graph/scopes.ts#discoverScopes.findNearestAncestorCandidate",
++ "relation": "calls",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/graph/scopes.ts#discoverScopes",
++ "target": "src/graph/scopes.ts#readWorkspaceGlobs",
++ "relation": "calls",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/graph/scopes.ts#discoverScopes",
++ "target": "src/graph/scopes.ts#resolveGlob",
++ "relation": "calls",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/graph/scopes.ts#discoverScopes",
++ "target": "src/graph/scopes.ts#discoverScopes.findNearestAncestorCandidate",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/graph/scopes.ts#readWorkspaceGlobs",
++ "target": "src/graph/scopes.ts#parsePnpmPackagesList",
++ "relation": "calls",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/graph/scopes.ts#resolveGlob",
++ "target": "src/graph/scopes.ts#resolveGlob.listDirs",
++ "relation": "calls",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/graph/scopes.ts#resolveGlob",
++ "target": "src/graph/scopes.ts#resolveGlob.listDirs",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
++ {
++ "source": "src/graph/scopes.ts#scopesHereClause",
++ "target": "src/graph/scopes.ts#scopeLabel",
++ "relation": "calls",
++ "confidence": "extracted"
++ },
+ {
+ "source": "src/graph/traverse-cli.ts",
+ "target": "src/graph/traverse-cli.ts#CallersCliOptions",
+ "relation": "contains",
+ "confidence": "extracted"
+ },
{
"source": "src/graph/traverse-cli.ts",
- "target": "src/graph/traverse-cli.ts#edgesFor",
+ "target": "src/graph/traverse-cli.ts#callersSavings",
"relation": "contains",
"confidence": "extracted"
},
@@@ -18778,6 -19029,6 +19926,12 @@@
"relation": "contains",
"confidence": "extracted"
},
++ {
++ "source": "src/graph/types.ts",
++ "target": "src/graph/types.ts#ScopeV1",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
{
"source": "src/graph/types.ts",
"target": "src/graph/types.ts#SummaryState",
@@@ -20008,6 -20295,6 +21198,72 @@@
"relation": "calls",
"confidence": "extracted"
},
++ {
++ "source": "test/ask-fusion.test.ts",
++ "target": "src/ask/ask.ts#formatAsk",
++ "relation": "calls",
++ "confidence": "inferred"
++ },
++ {
++ "source": "test/ask-fusion.test.ts",
++ "target": "src/ask/fuse.ts#fuseScopes",
++ "relation": "calls",
++ "confidence": "inferred"
++ },
++ {
++ "source": "test/ask-fusion.test.ts",
++ "target": "src/ask/fuse.ts#rankScopesAndFuse",
++ "relation": "calls",
++ "confidence": "inferred"
++ },
++ {
++ "source": "test/ask-fusion.test.ts",
++ "target": "test/ask-fusion.test.ts#makeOps",
++ "relation": "calls",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/ask-fusion.test.ts",
++ "target": "test/ask-fusion.test.ts#scopeDocs",
++ "relation": "calls",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/ask-fusion.test.ts",
++ "target": "test/ask-fusion.test.ts#makeOps",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/ask-fusion.test.ts",
++ "target": "test/ask-fusion.test.ts#scopeDocs",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/ask-fusion.test.ts",
++ "target": "node:assert/strict",
++ "relation": "imports",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/ask-fusion.test.ts",
++ "target": "node:test",
++ "relation": "imports",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/ask-fusion.test.ts",
++ "target": "src/ask/ask.ts",
++ "relation": "imports",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/ask-fusion.test.ts",
++ "target": "src/ask/fuse.ts",
++ "relation": "imports",
++ "confidence": "extracted"
++ },
{
"source": "test/ask-index.test.ts",
"target": "src/ask/ask.ts#ask",
@@@ -20230,36 -20517,36 +21486,96 @@@
"relation": "calls",
"confidence": "inferred"
},
++ {
++ "source": "test/ask.test.ts",
++ "target": "test/ask.test.ts#duplicateNameFixture",
++ "relation": "calls",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/ask.test.ts",
++ "target": "test/ask.test.ts#idfShiftFixture",
++ "relation": "calls",
++ "confidence": "extracted"
++ },
{
"source": "test/ask.test.ts",
"target": "test/ask.test.ts#makeFixture",
"relation": "calls",
"confidence": "extracted"
},
++ {
++ "source": "test/ask.test.ts",
++ "target": "test/ask.test.ts#multiScopeFixture",
++ "relation": "calls",
++ "confidence": "extracted"
++ },
{
"source": "test/ask.test.ts",
"target": "test/ask.test.ts#qualifiedFixture",
"relation": "calls",
"confidence": "extracted"
},
++ {
++ "source": "test/ask.test.ts",
++ "target": "test/ask.test.ts#rankOf",
++ "relation": "calls",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/ask.test.ts",
++ "target": "test/ask.test.ts#siblingPrefixFixture",
++ "relation": "calls",
++ "confidence": "extracted"
++ },
{
"source": "test/ask.test.ts",
"target": "test/ask.test.ts#stampCrux",
"relation": "calls",
"confidence": "extracted"
},
++ {
++ "source": "test/ask.test.ts",
++ "target": "test/ask.test.ts#duplicateNameFixture",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/ask.test.ts",
++ "target": "test/ask.test.ts#idfShiftFixture",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
{
"source": "test/ask.test.ts",
"target": "test/ask.test.ts#makeFixture",
"relation": "contains",
"confidence": "extracted"
},
++ {
++ "source": "test/ask.test.ts",
++ "target": "test/ask.test.ts#multiScopeFixture",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
{
"source": "test/ask.test.ts",
"target": "test/ask.test.ts#qualifiedFixture",
"relation": "contains",
"confidence": "extracted"
},
++ {
++ "source": "test/ask.test.ts",
++ "target": "test/ask.test.ts#rankOf",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/ask.test.ts",
++ "target": "test/ask.test.ts#siblingPrefixFixture",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
{
"source": "test/ask.test.ts",
"target": "test/ask.test.ts#stampCrux",
@@@ -20272,6 -20559,6 +21588,12 @@@
"relation": "imports",
"confidence": "extracted"
},
++ {
++ "source": "test/ask.test.ts",
++ "target": "node:child_process",
++ "relation": "imports",
++ "confidence": "extracted"
++ },
{
"source": "test/ask.test.ts",
"target": "node:fs",
@@@ -21640,6 -21927,6 +22962,192 @@@
"relation": "imports",
"confidence": "extracted"
},
++ {
++ "source": "test/graph-scopes.test.ts",
++ "target": "src/graph/build.ts#buildGraph",
++ "relation": "calls",
++ "confidence": "inferred"
++ },
++ {
++ "source": "test/graph-scopes.test.ts",
++ "target": "src/graph/load.ts#loadGraphCached",
++ "relation": "calls",
++ "confidence": "inferred"
++ },
++ {
++ "source": "test/graph-scopes.test.ts",
++ "target": "src/graph/scopes.ts#discoverScopes",
++ "relation": "calls",
++ "confidence": "inferred"
++ },
++ {
++ "source": "test/graph-scopes.test.ts",
++ "target": "src/graph/scopes.ts#discoverWorkspaceChildren",
++ "relation": "calls",
++ "confidence": "inferred"
++ },
++ {
++ "source": "test/graph-scopes.test.ts",
++ "target": "src/graph/scopes.ts#scopeOf",
++ "relation": "calls",
++ "confidence": "inferred"
++ },
++ {
++ "source": "test/graph-scopes.test.ts",
++ "target": "src/graph/scopes.ts#scopesOfGraph",
++ "relation": "calls",
++ "confidence": "inferred"
++ },
++ {
++ "source": "test/graph-scopes.test.ts",
++ "target": "src/graph/write.ts#readGraph",
++ "relation": "calls",
++ "confidence": "inferred"
++ },
++ {
++ "source": "test/graph-scopes.test.ts",
++ "target": "src/graph/write.ts#wiringPath",
++ "relation": "calls",
++ "confidence": "inferred"
++ },
++ {
++ "source": "test/graph-scopes.test.ts",
++ "target": "src/graph/write.ts#writeGraph",
++ "relation": "calls",
++ "confidence": "inferred"
++ },
++ {
++ "source": "test/graph-scopes.test.ts",
++ "target": "test/graph-scopes.test.ts#fx",
++ "relation": "calls",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/graph-scopes.test.ts",
++ "target": "test/graph-scopes.test.ts#normalize",
++ "relation": "calls",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/graph-scopes.test.ts",
++ "target": "test/graph-scopes.test.ts#pyFns",
++ "relation": "calls",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/graph-scopes.test.ts",
++ "target": "test/graph-scopes.test.ts#run",
++ "relation": "calls",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/graph-scopes.test.ts",
++ "target": "test/graph-scopes.test.ts#tsFns",
++ "relation": "calls",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/graph-scopes.test.ts",
++ "target": "test/graph-scopes.test.ts#fx",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/graph-scopes.test.ts",
++ "target": "test/graph-scopes.test.ts#normalize",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/graph-scopes.test.ts",
++ "target": "test/graph-scopes.test.ts#pyFns",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/graph-scopes.test.ts",
++ "target": "test/graph-scopes.test.ts#run",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/graph-scopes.test.ts",
++ "target": "test/graph-scopes.test.ts#tsFns",
++ "relation": "contains",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/graph-scopes.test.ts",
++ "target": "node:assert/strict",
++ "relation": "imports",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/graph-scopes.test.ts",
++ "target": "node:fs",
++ "relation": "imports",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/graph-scopes.test.ts",
++ "target": "node:os",
++ "relation": "imports",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/graph-scopes.test.ts",
++ "target": "node:path",
++ "relation": "imports",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/graph-scopes.test.ts",
++ "target": "node:test",
++ "relation": "imports",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/graph-scopes.test.ts",
++ "target": "src/graph/build.ts",
++ "relation": "imports",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/graph-scopes.test.ts",
++ "target": "src/graph/load.ts",
++ "relation": "imports",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/graph-scopes.test.ts",
++ "target": "src/graph/scopes.ts",
++ "relation": "imports",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/graph-scopes.test.ts",
++ "target": "src/graph/types.ts",
++ "relation": "imports",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/graph-scopes.test.ts",
++ "target": "src/graph/write.ts",
++ "relation": "imports",
++ "confidence": "extracted"
++ },
++ {
++ "source": "test/graph-scopes.test.ts#run",
++ "target": "src/graph/scopes.ts#discoverScopes",
++ "relation": "calls",
++ "confidence": "inferred"
++ },
++ {
++ "source": "test/graph-scopes.test.ts#run",
++ "target": "test/graph-scopes.test.ts#fx",
++ "relation": "calls",
++ "confidence": "extracted"
++ },
{
"source": "test/graph-traverse-cli.test.ts",
"target": "test/graph-traverse-cli.test.ts#builtRepo",
diff --cc graft/INDEX.md
index e7125849,5ae08943..661b8064
--- a/graft/INDEX.md
+++ b/graft/INDEX.md
@@@ -38,5 -38,5 +38,5 @@@ filename here, or run `graft ask "<task
## 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 —
++116 per-file wiring cards mirror the source tree under `graft/` (105 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 --cc graft/error-handling-and-reporting.md
index 829e404e,829e404e..ac39f20f
--- a/graft/error-handling-and-reporting.md
+++ b/graft/error-handling-and-reporting.md
@@@ -45,7 -45,7 +45,7 @@@ covers
at: 'src/engine.ts:L39-L45'
- symbol: Graft
kind: class
-- at: 'src/engine.ts:L47-L140'
++ at: 'src/engine.ts:L47-L146'
- symbol: constructor
kind: method
at: 'src/engine.ts:L50-L52'
@@@ -63,37 -63,37 +63,40 @@@
at: 'src/engine.ts:L81-L88'
- symbol: ask
kind: method
-- at: 'src/engine.ts:L95-L97'
++ at: 'src/engine.ts:L95-L103'
- symbol: chatModel
kind: method
-- at: 'src/engine.ts:L102-L119'
++ at: 'src/engine.ts:L108-L125'
- symbol: synthesizer
kind: method
-- at: 'src/engine.ts:L121-L123'
++ at: 'src/engine.ts:L127-L129'
- symbol: cruxSummarizer
kind: method
-- at: 'src/engine.ts:L126-L128'
++ at: 'src/engine.ts:L132-L134'
- symbol: summarizer
kind: method
-- at: 'src/engine.ts:L130-L132'
++ at: 'src/engine.ts:L136-L138'
- symbol: modelLabel
kind: method
-- at: 'src/engine.ts:L135-L139'
++ at: 'src/engine.ts:L141-L145'
++ - symbol: applyMinSubstanceGuard
++ kind: function
++ at: 'src/graph/build.ts:L32-L47'
- symbol: GraphBuildOptions
kind: interface
-- at: 'src/graph/build.ts:L23-L36'
++ at: 'src/graph/build.ts:L49-L62'
- symbol: GraphBuildResult
kind: interface
-- at: 'src/graph/build.ts:L38-L51'
++ at: 'src/graph/build.ts:L64-L77'
- symbol: listSourceFiles
kind: function
-- at: 'src/graph/build.ts:L54-L56'
++ at: 'src/graph/build.ts:L80-L82'
- symbol: readGoModules
kind: function
-- at: 'src/graph/build.ts:L62-L76'
++ at: 'src/graph/build.ts:L88-L102'
- symbol: buildGraph
kind: function
-- at: 'src/graph/build.ts:L78-L183'
++ at: 'src/graph/build.ts:L104-L215'
---
<!-- context:generated:start -->
## Summary
diff --cc graft/graph-extraction-and-loading.md
index 08dce6d9,08dce6d9..ca356136
--- a/graft/graph-extraction-and-loading.md
+++ b/graft/graph-extraction-and-loading.md
@@@ -159,9 -159,9 +159,12 @@@ covers
- symbol: EdgeV1
kind: interface
at: 'src/graph/types.ts:L73-L78'
++ - symbol: ScopeV1
++ kind: interface
++ at: 'src/graph/types.ts:L84-L88'
- symbol: GraphV1
kind: interface
-- at: 'src/graph/types.ts:L80-L89'
++ at: 'src/graph/types.ts:L90-L102'
---
<!-- context:generated:start -->
## Summary
diff --cc graft/graph-ranking.md
index 94172aaa,94172aaa..5e3e3cc3
--- a/graft/graph-ranking.md
+++ b/graft/graph-ranking.md
@@@ -26,10 -26,10 +26,10 @@@ covers
at: 'test/graphrank.test.ts:L42-L48'
- symbol: makeCollisionFixture
kind: function
-- at: 'test/graphrank.test.ts:L128-L138'
++ at: 'test/graphrank.test.ts:L182-L192'
- symbol: rank
kind: function
-- at: 'test/graphrank.test.ts:L140-L141'
++ at: 'test/graphrank.test.ts:L194-L195'
---
<!-- context:generated:start -->
## Summary
diff --cc graft/graph-representation.md
index 43afe138,43afe138..60d0b330
--- a/graft/graph-representation.md
+++ b/graft/graph-representation.md
@@@ -41,9 -41,9 +41,12 @@@ covers
- symbol: EdgeV1
kind: interface
at: 'src/graph/types.ts:L73-L78'
++ - symbol: ScopeV1
++ kind: interface
++ at: 'src/graph/types.ts:L84-L88'
- symbol: GraphV1
kind: interface
-- at: 'src/graph/types.ts:L80-L89'
++ at: 'src/graph/types.ts:L90-L102'
---
<!-- context:generated:start -->
## Summary
diff --cc graft/src/ask/ask.md
index eebcd84b,f15570ca..939bca54
--- a/graft/src/ask/ask.md
+++ b/graft/src/ask/ask.md
@@@ -2,37 -2,38 +2,39 @@@
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
++- AskHit · interface · L29-L46 — Represents a hit in the query results, encapsulating details about a code symbol and its context.
++- AskResult · interface · L52-L74 — Represents the result of an 'ask' query, encapsulating the query details and the hits found.
++- firstProse · function · L77-L84 — Extracts the first meaningful prose line from a body of text, ignoring headings and blank lines.
++- Corpus · interface · L86-L93 — Defines the structure for holding concepts and graph data used in processing queries.
++- loadCorpus · function · L95-L120 — Loads a corpus of concepts and graph data from a specified directory, enabling query processing.
++- score · function · L129-L140 — Calculates a score for a document based on its token counts relative to a query, enhancing relevance ranking.
++- idfFromDf · function · L146-L150 — Computes the inverse document frequency (IDF) from document frequency (DF) data, aiding in scoring relevance.
++- computeIdf · function · L152-L157 — Generates IDF values from document bags, which are used to weight query matches based on term rarity.
++- computeIdfFromIndex · function · L166-L171 — Calculates IDF values using precomputed index data, optimizing the scoring process for queries.
++- bm25 · function · L178-L194 — Implements the BM25 scoring algorithm to rank documents based on term frequency and document length.
++- subjectWords · function · L206-L208 — Tokenizes a query into words while preserving qualified names, facilitating accurate subject resolution.
++- findSubjectNodes · function · L227-L235 — Finds nodes in the graph that match the structural subject of a query, enhancing query resolution.
++- StructuralOutcome · type · L243-L243 — 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 · L245-L250 — Generates a note for cases where a structural query falls back to lexical processing, providing user guidance.
++- structural · function · L252-L301 — Processes a structural query to find relationships in the graph, returning relevant results or fallthrough notes.
++- hasTerm · function · L320-L322 — Checks for the presence of a term in a document's token map, aiding in relevance scoring.
++- matchedIdfShare · function · L331-L345 — Calculates the share of query terms matched by a document, weighted by term rarity for relevance assessment.
++- lexical · function · L347-L627 — Handles lexical queries by scoring documents based on term matches and relevance, returning structured results.
++- bodyLen · function · L463-L467 — Calculates the length of the body of a lexical document to ensure it meets certain criteria for processing.
++- AskOptions · interface · L629-L651 — Defines the options available for configuring the ask function, allowing customization of its behavior.
++- parseSpan · function · L655-L659 — Parses a string pointer into its file path and line range components, facilitating source code navigation.
++- sliceSpan · function · L663-L678 — Reads a specified range of lines from a source file, allowing for inlined code snippets in query results.
++- inlineSource · function · L685-L702 — Inlines the source code for the hits found, providing context directly in the results without needing to open files.
++- hitFiles · function · L706-L715 — Extracts a set of unique file paths from the hits, indicating which files are relevant to the query results.
++- baselineFor · function · L720-L723 — Calculates the baseline file size and character count for the hits, providing a measure of the cost of reading the full files.
++- ask · function · L726-L771 — Handles the main logic for processing a query against a directory, returning structured results based on the query type.
++- SkeletonEntry · interface · L775-L782 — Defines the structure of a skeleton entry, which represents a piece of information extracted from a file.
++- SkeletonResult · interface · L784-L790 — Defines the structure of the result returned from the skeleton function, encapsulating the extracted information.
++- skeleton · function · L795-L825 — Extracts a skeleton representation of a file, providing a summary and context for its contents.
++- startLine · function · L812-L812 — Calculates the starting line number from a given span, aiding in the extraction of relevant code sections.
++- formatSkeleton · function · L828-L838 — Formats the skeleton result into a string representation for display or output purposes.
++- toTokens · function · L841-L843 — Converts a character count into a token count, facilitating the processing of text for queries.
++- formatAsk · function · L846-L888 — Formats the results of an ask query into a string for presentation, ensuring clarity and usability.
++- escalationNudge · function · L895-L902 — function escalationNudge(r: AskResult): string
++- askSavingsFooter · function · L907-L919 — function askSavingsFooter(r: AskResult, body: string): string
++- scopeFooterLines · function · L926-L938 — function scopeFooterLines(r: AskResult): string[]
diff --cc graft/src/ask/fuse.md
index 00000000,00000000..2d0dd174
new file mode 100644
--- /dev/null
+++ b/graft/src/ask/fuse.md
@@@ -1,0 -1,0 +1,8 @@@
++# src/ask/fuse.ts
++
++- ScopedDoc · interface · L24-L28 — interface ScopedDoc
++- FusionResult · interface · L30-L40 — interface FusionResult
++- byScore · function · L52-L54 — function byScore(a: ScopedDoc, b: ScopedDoc): number
++- fuseScopes · function · L67-L130 — function fuseScopes(docs: ScopedDoc[]): FusionResult
++- ScopeRankOps · interface · L136-L143 — interface ScopeRankOps
++- rankScopesAndFuse · function · L164-L223 — function rankScopesAndFuse( scopes: string[], ops: ScopeRankOps, graphWeight: number, rescueFloor: number, ): FusionResult
diff --cc graft/src/ask/graphrank.md
index a24d4dbe,a24d4dbe..1b94029f
--- a/graft/src/ask/graphrank.md
+++ b/graft/src/ask/graphrank.md
@@@ -2,6 -2,6 +2,6 @@@
This module implements a personalized PageRank algorithm to improve the ranking of code nodes based on their structural relevance rather than just lexical similarity.
--- PageRankOptions · interface · L20-L26 — Defines options for configuring the personalized PageRank algorithm, including restart probability and iteration count.
--- personalizedPageRank · function · L39-L101 — Calculates personalized PageRank scores for nodes in a wiring graph based on provided seeds, enhancing the relevance of code suggestions.
--- link · function · L51-L53 — Creates undirected links between nodes in the graph for the PageRank calculation, ensuring that both directions are considered.
++- PageRankOptions · interface · L20-L32 — Defines options for configuring the personalized PageRank algorithm, including restart probability and iteration count.
++- personalizedPageRank · function · L45-L113 — Calculates personalized PageRank scores for nodes in a wiring graph based on provided seeds, enhancing the relevance of code suggestions.
++- link · function · L63-L65 — Creates undirected links between nodes in the graph for the PageRank calculation, ensuring that both directions are considered.
diff --cc graft/src/engine.md
index ce78085c,ce78085c..14119627
--- a/graft/src/engine.md
+++ b/graft/src/engine.md
@@@ -5,15 -5,15 +5,15 @@@ The Graft class manages the constructio
- InitOptions · interface · L28-L33 — Defines options for initializing the context graph build, including code extensions and a progress callback.
- CheckRunOptions · interface · L35-L37 — Specifies options for checking the context graph, allowing for code extensions to be included.
- GraphRunOptions · interface · L39-L45 — Defines options for running the graph building process, including LLM usage and concurrency settings.
--- Graft · class · L47-L140 — Manages the context graph operations, including building and checking synchronization with the codebase.
++- Graft · class · L47-L146 — Manages the context graph operations, including building and checking synchronization with the codebase.
- constructor · method · L50-L52 — Initializes the Graft class with a configuration, resolving the necessary settings for the context graph.
- init · method · L55-L64 — Builds the context graph from the specified directory, utilizing various options and configurations.
- check · method · L67-L69 — Checks if the committed context graph is in sync with the code in the specified directory.
- checkGraph · method · L72-L74 — Verifies if the committed graph.json file is in sync with the code, focusing on the Tier-1 differences.
- graph · method · L81-L88 — Builds a per-symbol code graph from the repository, optionally using a meaning layer with LLM.
--- ask · method · L95-L97 — Processes a query against the context graph, returning results based on structural and lexical analysis.
--- chatModel · method · L102-L119 — Retrieves the configured chat model or throws an error if the API key is missing, ensuring proper setup for LLM operations.
--- synthesizer · method · L121-L123 — Provides the synthesizer for generating responses, defaulting to a chat synthesizer if none is configured.
--- cruxSummarizer · method · L126-L128 — Returns a crux summarizer for the Tier-2 pass of the code graph, ensuring detailed summarization of nodes.
--- summarizer · method · L130-L132 — Fetches the summarizer for generating summaries, defaulting to a chat summarizer if not explicitly set.
--- modelLabel · method · L135-L139 — Determines the human-readable label for the active model, which is recorded in the manifest for reference.
++- ask · method · L95-L103 — Processes a query against the context graph, returning results based on structural and lexical analysis.
++- chatModel · method · L108-L125 — Retrieves the configured chat model or throws an error if the API key is missing, ensuring proper setup for LLM operations.
++- synthesizer · method · L127-L129 — Provides the synthesizer for generating responses, defaulting to a chat synthesizer if none is configured.
++- cruxSummarizer · method · L132-L134 — Returns a crux summarizer for the Tier-2 pass of the code graph, ensuring detailed summarization of nodes.
++- summarizer · method · L136-L138 — Fetches the summarizer for generating summaries, defaulting to a chat summarizer if not explicitly set.
++- modelLabel · method · L141-L145 — Determines the human-readable label for the active model, which is recorded in the manifest for reference.
diff --cc graft/src/graph/build.md
index c6c27cfd,c6c27cfd..75d0b758
--- a/graft/src/graph/build.md
+++ b/graft/src/graph/build.md
@@@ -2,8 -2,8 +2,9 @@@
This file defines the logic for building a graph representation of a code repository, including parsing source files and resolving dependencies.
--- GraphBuildOptions · interface · L23-L36 — This interface specifies options for customizing the graph build process, including output directory and summarization settings.
--- GraphBuildResult · interface · L38-L51 — This interface outlines the structure of the result returned from the graph build process, detailing the generated graph's metadata and statistics.
--- listSourceFiles · function · L54-L56 — This function retrieves a list of source files from a given directory, excluding the output directory and unsupported languages.
--- readGoModules · function · L62-L76 — This function identifies and reads Go modules from the repository to facilitate edge resolution for Go import paths.
--- buildGraph · function · L78-L183 — This function orchestrates the entire graph building process, from parsing source files to writing the final graph output.
++- applyMinSubstanceGuard · function · L32-L47 — function applyMinSubstanceGuard(scopes: ScopeV1[], nodes: NodeV1[]): ScopeV1[]
++- GraphBuildOptions · interface · L49-L62 — This interface specifies options for customizing the graph build process, including output directory and summarization settings.
++- GraphBuildResult · interface · L64-L77 — This interface outlines the structure of the result returned from the graph build process, detailing the generated graph's metadata and statistics.
++- listSourceFiles · function · L80-L82 — This function retrieves a list of source files from a given directory, excluding the output directory and unsupported languages.
++- readGoModules · function · L88-L102 — This function identifies and reads Go modules from the repository to facilitate edge resolution for Go import paths.
++- buildGraph · function · L104-L215 — This function orchestrates the entire graph building process, from parsing source files to writing the final graph output.
diff --cc graft/src/graph/scopes.md
index 00000000,00000000..776aa84b
new file mode 100644
--- /dev/null
+++ b/graft/src/graph/scopes.md
@@@ -1,0 -1,0 +1,17 @@@
++# src/graph/scopes.ts
++
++- collectDirs · function · L37-L56 — function collectDirs(root: string): string[]
++- walk · function · L39-L53 — walk = (absDir: string, relDir: string): void
++- parsePnpmPackagesList · function · L60-L73 — function parsePnpmPackagesList(text: string): string[] | null
++- readWorkspaceGlobs · function · L78-L100 — function readWorkspaceGlobs(root: string): string[] | null
++- resolveGlob · function · L105-L166 — function resolveGlob(root: string, pattern: string): string[]
++- listDirs · function · L140-L150 — listDirs = (absDir: string, relDir: string): string[]
++- Candidate · interface · L168-L171 — interface Candidate
++- discoverScopes · function · L174-L307 — function discoverScopes(root: string): ScopeV1[]
++- findNearestAncestorCandidate · function · L254-L264 — findNearestAncestorCandidate = ( prefix: string, set: ReadonlyMap<string, Candidate>, ): string | null
++- scopeOf · function · L312-L318 — function scopeOf(path: string, scopes: ScopeV1[]): ScopeV1
++- scopeLabel · function · L323-L325 — function scopeLabel(prefix: string): string
++- scopesHereClause · function · L331-L334 — function scopesHereClause(scopes: ScopeV1[]): string
++- pathUnderPrefix · function · L341-L343 — function pathUnderPrefix(path: string, prefix: string): boolean
++- discoverWorkspaceChildren · function · L347-L364 — function discoverWorkspaceChildren(root: string): string[]
++- scopesOfGraph · function · L369-L371 — function scopesOfGraph(graph: GraphV1): ScopeV1[]
diff --cc graft/src/graph/types.md
index 0a6c900a,0a6c900a..a5d96189
--- a/graft/src/graph/types.md
+++ b/graft/src/graph/types.md
@@@ -9,4 -9,4 +9,5 @@@ Defines the structure and relationship
- NodeV1 · interface · L38-L63 — Describes the properties of a node in the code graph, encapsulating its identity, location, and meaning for effective graph representation.
- Relation · type · L65-L71 — Defines the types of relationships between nodes in the graph, clarifying how symbols interact.
- EdgeV1 · interface · L73-L78 — Describes the edges connecting nodes in the graph, detailing the source, target, and relationship type.
--- GraphV1 · interface · L80-L89 — Encapsulates the entire graph structure, including metadata and collections of nodes and edges.
++- ScopeV1 · interface · L84-L88 — interface ScopeV1
++- GraphV1 · interface · L90-L102 — Encapsulates the entire graph structure, including metadata and collections of nodes and edges.
diff --cc graft/src/mcp/tools.md
index 00236aaf,450f5874..12d34fb0
--- a/graft/src/mcp/tools.md
+++ b/graft/src/mcp/tools.md
@@@ -1,6 -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.
++- renderMatches · function · L121-L136 — Formats and renders the results of graph traversal matches, providing a structured output for users to understand symbol relationships.
++- callTool · function · L138-L220 — Handles the invocation of various tools based on user input, managing errors and returning formatted results for different graph operations.
diff --cc graft/test/ask-fusion.test.md
index 00000000,00000000..2f26a68a
new file mode 100644
--- /dev/null
+++ b/graft/test/ask-fusion.test.md
@@@ -1,0 -1,0 +1,4 @@@
++# test/ask-fusion.test.ts
++
++- scopeDocs · function · L19-L21 — function scopeDocs(scope: string, scores: number[]): ScopedDoc[]
++- makeOps · function · L120-L133 — function makeOps(bRaw: number): ScopeRankOps
diff --cc graft/test/ask.test.md
index 411ba858,411ba858..af534a15
--- a/graft/test/ask.test.md
+++ b/graft/test/ask.test.md
@@@ -2,6 -2,6 +2,11 @@@
Contains tests for the `ask` functionality, validating its behavior with various options and scenarios.
--- makeFixture · function · L16-L25 — Creates a temporary directory with a sample TypeScript file for testing purposes.
--- stampCrux · function · L43-L49 — Updates the wiring.json file to include a crux for the specified node, allowing for inlined source retrieval.
--- qualifiedFixture · function · L189-L207 — Sets up a temporary directory with a cache implementation to test structural resolution of function calls.
++- makeFixture · function · L17-L26 — Creates a temporary directory with a sample TypeScript file for testing purposes.
++- stampCrux · function · L44-L50 — Updates the wiring.json file to include a crux for the specified node, allowing for inlined source retrieval.
++- qualifiedFixture · function · L190-L208 — Sets up a temporary directory with a cache implementation to test structural resolution of function calls.
++- multiScopeFixture · function · L277-L310 — function multiScopeFixture(): string
++- siblingPrefixFixture · function · L336-L343 — function siblingPrefixFixture(): string
++- idfShiftFixture · function · L370-L381 — function idfShiftFixture(): string
++- rankOf · function · L388-L388 — rankOf = (r: ReturnType<typeof ask>["hits"], title: string)
++- duplicateNameFixture · function · L555-L570 — function duplicateNameFixture(): string
diff --cc graft/test/graph-scopes.test.md
index 00000000,00000000..f68eb62c
new file mode 100644
--- /dev/null
+++ b/graft/test/graph-scopes.test.md
@@@ -1,0 -1,0 +1,7 @@@
++# test/graph-scopes.test.ts
++
++- fx · function · L17-L24 — function fx(layout: Record<string, string>): string
++- run · function · L75-L89 — run = (siblingName: string): string[]
++- normalize · function · L93-L94 — normalize = (prefixes: string[], siblingName: string): string[]
++- tsFns · function · L155-L157 — function tsFns(n: number): string
++- pyFns · function · L159-L161 — function pyFns(n: number): string
diff --cc graft/test/graphrank.test.md
index ed2ba0a6,ed2ba0a6..4ff32449
--- a/graft/test/graphrank.test.md
+++ b/graft/test/graphrank.test.md
@@@ -5,5 -5,5 +5,5 @@@ This file contains unit and integratio
- node · function · L23-L38 — Creates a node representation for the graph with specified properties.
- edge · function · L39-L41 — Defines an edge between two nodes in the graph, establishing a relationship.
- graphOf · function · L42-L48 — Constructs a graph object from given nodes and edges, encapsulating their relationships.
--- makeCollisionFixture · function · L128-L138 — Sets up a temporary file structure to simulate a collision scenario for testing graph ranking.
--- rank · function · L140-L141 — Executes the ask function with specified parameters to retrieve ranked results based on graph connectivity.
++- makeCollisionFixture · function · L182-L192 — Sets up a temporary file structure to simulate a collision scenario for testing graph ranking.
++- rank · function · L194-L195 — Executes the ask function with specified parameters to retrieve ranked results based on graph connectivity.
diff --cc graft/testing-and-validation.md
index ef5754d0,e6487532..cdea8b75
--- a/graft/testing-and-validation.md
+++ b/graft/testing-and-validation.md
@@@ -70,13 -70,13 +70,28 @@@ covers
at: 'test/ask-index.test.ts:L106-L106'
- symbol: makeFixture
kind: function
-- at: 'test/ask.test.ts:L16-L25'
++ at: 'test/ask.test.ts:L17-L26'
- symbol: stampCrux
kind: function
-- at: 'test/ask.test.ts:L43-L49'
++ at: 'test/ask.test.ts:L44-L50'
- symbol: qualifiedFixture
kind: function
-- at: 'test/ask.test.ts:L189-L207'
++ at: 'test/ask.test.ts:L190-L208'
++ - symbol: multiScopeFixture
++ kind: function
++ at: 'test/ask.test.ts:L277-L310'
++ - symbol: siblingPrefixFixture
++ kind: function
++ at: 'test/ask.test.ts:L336-L343'
++ - symbol: idfShiftFixture
++ kind: function
++ at: 'test/ask.test.ts:L370-L381'
++ - symbol: rankOf
++ kind: function
++ at: 'test/ask.test.ts:L388-L388'
++ - symbol: duplicateNameFixture
++ kind: function
++ at: 'test/ask.test.ts:L555-L570'
- symbol: strip
kind: function
at: 'test/claude-format.test.ts:L6-L6'
diff --cc src/ask/ask.ts
index 5fd2c510,c6bfbfa7..ed69dece
--- a/src/ask/ask.ts
+++ b/src/ask/ask.ts
@@@ -17,11 -17,10 +17,12 @@@ import { existsSync, readdirSync, readF
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 { pathUnderPrefix, scopeLabel, scopeOf, scopesHereClause, scopesOfGraph } from "../graph/scopes.js";
import { resolveSymbol } from "../graph/traverse.js";
import type { EdgeV1, GraphV1, NodeV1, Relation } from "../graph/types.js";
+import { rankScopesAndFuse } from "./fuse.js";
import { personalizedPageRank } from "./graphrank.js";
import { counts, tokenize, type AskIndex, type AskIndexDoc } from "./index-file.js";
@@@ -888,10 -718,23 +881,24 @@@ export function formatAsk(r: AskResult)
if (h.code) lines.push("", "```", h.code, "```");
lines.push("");
});
+ lines.push(...scopeFooterLines(r));
}
const body = lines.join("\n").trimEnd();
- return body + savingsFooter(r, body) + "\n";
+ return body + askSavingsFooter(r, body) + escalationNudge(r) + "\n";
+ }
+
+ /** When a lexical `ask` returns thin/no results, the productive next move is a
+ * different TOOL, not a re-phrased ask — re-asking is the "over-ask" trap that
+ * inflates cost. Surface the escalation in the output so the agent switches to
+ * grep/skeleton/callers instead. Silent when the result is already rich (>3
+ * hits) or in structural mode (a resolved who-calls IS the answer). */
+ function escalationNudge(r: AskResult): string {
+ if ((r.mode !== "lexical" && r.mode !== "empty") || r.hits.length > 3) return "";
+ const n = r.hits.length;
+ return (
+ `\n\n[graft] ${n === 0 ? "no hits" : `only ${n} hit${n === 1 ? "" : "s"}`} — don't re-ask with new wording; switch tool: ` +
+ "`graft grep \"<literal>\"` for every occurrence · `graft skeleton <file>` for a file's full API · `graft callers <symbol>` for who-uses."
+ );
}
/** The one-line token-saving estimate `ask` appends in retriever mode, so the