Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
fix(ask): --in keeps sidecar body bags, accepts trailing slash, narrows structural subjects
Shrish Dwivedif923bdaf660e
diff --git a/src/ask/ask.ts b/src/ask/ask.tsindex 9497180d..5fd2c510 100644--- a/src/ask/ask.ts+++ b/src/ask/ask.ts@@ -213,11 +213,21 @@ function subjectWords(query: string): string[] {* last regardless of outcome, so a caller can name *something* in a fallthrough* note even when nothing resolved (e.g. `subjects.length === 0`). This is what* makes a qualified/dotted subject like `Cache.get` resolve, where the old- * plain name-equality lookup (`findSubject`) never matched it. */-function findSubjectNodes(query: string, graph: GraphV1): { nodes: NodeV1[]; tried: string } {+ * plain name-equality lookup (`findSubject`) never matched it.+ *+ * `inPrefix`, when given, filters each word's `resolveSymbol` matches down to+ * nodes under that path prefix BEFORE checking whether any survived — same+ * "narrow the subject resolution" semantics `callers`/`callees`/`impact --in`+ * already have (segment-aware here, via `pathUnderPrefix`). A word that+ * resolves globally but has nothing under the prefix does NOT count as a+ * match; the next (shorter) word is tried instead, same as an unresolved word+ * today — and if nothing survives for ANY word, `subjects.length === 0`+ * naturally falls through to the existing loud fallthrough note. */+function findSubjectNodes(query: string, graph: GraphV1, inPrefix?: string): { nodes: NodeV1[]; tried: string } {const words = subjectWords(query).sort((a, b) => b.length - a.length);for (const w of words) {- const nodes = resolveSymbol(graph, w);+ let nodes = resolveSymbol(graph, w);+ if (inPrefix) nodes = nodes.filter((n) => pathUnderPrefix(n.path, inPrefix));if (nodes.length > 0) return { nodes, tried: w };}return { nodes: [], tried: words[0] ?? query };@@ -238,12 +248,12 @@ function fallthroughNoteFor(subject: string): string {);}-function structural(query: string, graph: GraphV1, limit: number): StructuralOutcome {+function structural(query: string, graph: GraphV1, limit: number, inPrefix?: string): StructuralOutcome {const wantsIn = INCOMING.test(query);const wantsOut = OUTGOING.test(query);if (!wantsIn && !wantsOut) return null;- const { nodes: subjects, tried } = findSubjectNodes(query, graph);+ const { nodes: subjects, tried } = findSubjectNodes(query, graph, inPrefix);if (subjects.length === 0) return { fallthroughNote: fallthroughNoteFor(tried) };const ids = new Set(subjects.map((n) => n.id));@@ -358,11 +368,21 @@ function lexical(query: string, corpus: Corpus, limit: number, graphRank: boolea// mismatched set, e.g. a hand-edited or corrupt sidecar). Anything short of// that — missing, unparseable, unknown version, wrong count, mismatched ids —// falls back to live tokenization so results never depend on the sidecar- // existing; see `readAskIndex`'s own null-on-anything-off contract. `--in` also- // forces the live path: the sidecar's `df`/`avgBodyLen` are corpus-global, and- // a narrowed query needs idf/avgdl computed from ONLY the filtered doc set.+ // existing; see `readAskIndex`'s own null-on-anything-off contract.+ //+ // `--in` does NOT disable the sidecar here: `writeGraph` strips `body_text`+ // from every node it serializes (see `write.ts`) — the sidecar's per-doc+ // `docs[].body` bags are the ONLY place a symbol's body tokens survive on a+ // graph loaded from disk. Bypassing the sidecar under `--in` would silently+ // empty out `body` for every node (falling back to `n.body_text ?? ""`,+ // always `""` post-slim-serialization), losing every body-only match under+ // the filtered prefix. What DOES need bypassing under `--in` is the+ // sidecar's GLOBAL `df`/`docCount`/`avgBodyLen` — those cover the whole+ // corpus, not the filtered subset — so each read of those three fields below+ // is separately gated on `!inPrefix`, while the per-doc bags (used to build+ // `symbolDocs` right after this) are used unconditionally.let docById: Map<string, AskIndexDoc> | null = null;- if (!inPrefix && corpus.askIndex && graph && corpus.askIndex.docs.length === graph.nodes.length) {+ if (corpus.askIndex && graph && corpus.askIndex.docs.length === graph.nodes.length) {const map = new Map(corpus.askIndex.docs.map((d) => [d.id, d]));if (graph.nodes.every((n) => map.has(n.id))) docById = map;}@@ -399,15 +419,19 @@ function lexical(query: string, corpus: Corpus, limit: number, graphRank: boolea// IDF must see the SAME inputs either way: with a sidecar, its `df` (stored// WITHOUT concepts) plus these live concept bags reproduces exactly what// `computeIdf` below would compute from concept+symbol bags tokenized live.- const idf = askIndex+ // `askIndex.df` is a corpus-GLOBAL count, so `--in` can't use it — the+ // filtered doc set needs its own idf, computed from (already-filtered)+ // `symbolDocs`' own bags, regardless of where those bags came from.+ const idf = askIndex && !inPrefix? computeIdfFromIndex(askIndex, conceptBags): computeIdf([...conceptBags, ...symbolDocs.map((d) => new Set([...d.name.keys(), ...d.path.keys(), ...d.body.keys()]))]);// Per-hit idf-weighted coverage, kept out of the public AskHit shape; only// the top hit's value survives, as `coverage` on the result. The df=0 weight// mirrors idfFromDf's formula at df=0 for whichever corpus size idf was- // computed from.- const nDocs = askIndex+ // computed from. Same `--in` reasoning as `idf` above: `askIndex.docCount`+ // is global.+ const nDocs = askIndex && !inPrefix? askIndex.docCount + conceptBags.length: conceptBags.length + symbolDocs.length;const dfltIdf = Math.log(1 + nDocs);@@ -521,9 +545,12 @@ function lexical(query: string, corpus: Corpus, limit: number, graphRank: booleaif (fusion.federated.length > 1 || fusion.alsoMatched.length > 0)scopeMeta = { federated: fusion.federated, alsoMatched: fusion.alsoMatched };} else {- // Single-scope: the pre-scopes ranking path, byte-identical output. Kept at- // its original indentation on purpose — the git diff proves it untouched.- const avgBodyLen = askIndex+ // Single-scope: the pre-scopes ranking path, byte-identical output when+ // `--in` is absent (Task 3's regression guarantee: `askIndex && !inPrefix`+ // reduces to plain `askIndex` when `inPrefix` is undefined, so this line is+ // a no-op change for every non-`--in` caller). Under `--in`, `askIndex`'s+ // `avgBodyLen` is corpus-global and must not be reused for the filtered set.+ const avgBodyLen = askIndex && !inPrefix? askIndex.avgBodyLen: symbolDocs.length? symbolDocs.reduce((a, d) => a + bodyLen(d.body), 0) / symbolDocs.length@@ -713,24 +740,29 @@ export function ask(dir: string, query: string, opts: AskOptions = {}): AskResulconst limit = opts.limit ?? 8;const corpus = loadCorpus(outDir);const graphRank = opts.graphRank ?? true;-- // `--in` validated up front, before either mode runs: a prefix matching no+ // Trailing slash(es) stripped ONCE, up front, and this normalized value used+ // everywhere below (validation, filtering, structural). `ask --in frontend/`+ // must work exactly like `--in frontend` — `scopeLabel`/the footer's own+ // `--in <scope>/` suggestion always includes the slash, so rejecting it+ // would make the tool's own suggested next command fail.+ const inPrefix = opts.in ? opts.in.replace(/\/+$/, "") : undefined;++ // `--in` validated up front, before any mode runs: a prefix matching no// indexed node is a caller mistake (typo, wrong sub-project), not a// legitimate zero-hit query, so it's a loud error rather than an empty pack.- if (opts.in && corpus.graph && !corpus.graph.nodes.some((n) => pathUnderPrefix(n.path, opts.in!))) {- const disp = opts.in.replace(/\/+$/, "");+ if (inPrefix && corpus.graph && !corpus.graph.nodes.some((n) => pathUnderPrefix(n.path, inPrefix))) {throw new Error(- `nothing indexed under "${disp}/"${scopesHereClause(scopesOfGraph(corpus.graph))} (or any path prefix)`,+ `nothing indexed under "${inPrefix}/"${scopesHereClause(scopesOfGraph(corpus.graph))} (or any path prefix)`,);}let result: AskResult;if (corpus.graph) {- const outcome = structural(query, corpus.graph, limit);+ const outcome = structural(query, corpus.graph, limit, inPrefix);if (outcome && "result" in outcome) {result = outcome.result;} else {- result = lexical(query, corpus, limit, graphRank, opts.in);+ result = lexical(query, corpus, limit, graphRank, inPrefix);// A structural-intent query that couldn't be answered structurally still// gets a prominent note on the lexical fallback result — never silent.if (outcome && "fallthroughNote" in outcome) {@@ -738,7 +770,7 @@ export function ask(dir: string, query: string, opts: AskOptions = {}): AskResul}}} else {- result = lexical(query, corpus, limit, graphRank, opts.in);+ result = lexical(query, corpus, limit, graphRank, inPrefix);}if (opts.source) {inlineSource(root, result.hits, corpus.graph, opts.full ?? false);diff --git a/test/ask.test.ts b/test/ask.test.tsindex e8f22bcf..b8bc3812 100644--- a/test/ask.test.ts+++ b/test/ask.test.ts@@ -489,6 +489,126 @@ test("ask --in on the multi-scope fixture: filtering to one scope carries no sco}});+// ── Review fix: `--in` must not blind the sidecar's per-doc body bags ──────++/** A term that appears ONLY in a function's body (never its name/signature),+ * same shape as the pre-existing body-indexing test — but the node lives+ * inside a directory that IS the `--in` prefix, so this catches the sidecar+ * bypass bug: a build writes `body_text` into `.cache/ask-index.json` and+ * then strips it from `wiring.json` (see `write.ts`), so a graph loaded from+ * disk has NO other source for body tokens. Disabling the sidecar under+ * `--in` (rather than just its global df/avgdl) silently empties every+ * node's body bag, making a body-only term unfindable everywhere, including+ * under its own directory. */+test("ask --in: a body-only term is still found when filtered to its own directory (sidecar body bags must survive --in)", async () => {+ const dir = mkdtempSync(join(tmpdir(), "graft-ask-in-body-"));+ try {+ mkdirSync(join(dir, "widgets"), { recursive: true });+ writeFileSync(+ join(dir, "widgets", "pay.ts"),+ `export function checkout(amount: number): string {\n` ++ ` const token = createStripeCharge(amount);\n` ++ ` return token;\n` ++ `}\n`,+ );+ await buildGraph(dir);+ // Unfiltered: sanity-check the term is findable at all (pins the existing+ // body-indexing contract this test's fixture depends on).+ const unfiltered = ask(dir, "stripe");+ assert.ok(unfiltered.hits.some((h) => h.title.startsWith("checkout")), "sanity: findable unfiltered");++ const r = ask(dir, "stripe", { in: "widgets" });+ const hit = r.hits.find((h) => h.title.startsWith("checkout"));+ assert.ok(hit, "checkout must still be findable via its body-only term when --in filters to its OWN directory");+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+});++// ── Review fix: `--in` accepts a trailing slash ─────────────────────────────++test("ask --in: a trailing slash is accepted — `--in frontend/` behaves exactly like `--in frontend`", async () => {+ const dir = multiScopeFixture();+ try {+ await buildGraph(dir);+ const withSlash = ask(dir, "how are errors handled", { limit: 10, in: "frontend/" });+ const withoutSlash = ask(dir, "how are errors handled", { limit: 10, in: "frontend" });+ assert.ok(withSlash.hits.length > 0, "the tool's own suggested `--in scope/` (with slash) must not come up empty");+ assert.deepEqual(+ withSlash.hits.map((h) => h.pointer),+ withoutSlash.hits.map((h) => h.pointer),+ "trailing slash must not change which hits are returned",+ );+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+});++// ── Review fix: `--in` must also narrow structural queries, not silently no-op ──++/** Same symbol NAME (`handle`) defined independently in two directories, each+ * with its own distinct caller — `resolveSymbol` matches both by name alone,+ * so without `--in` a structural query's subject is ambiguous (both nodes),+ * and both callers show up. `--in` must narrow the SUBJECT resolution to the+ * one under the prefix (same "narrow resolveSymbol" semantics+ * `callers`/`callees`/`impact --in` already have), not just filter docs. */+function duplicateNameFixture(): string {+ const dir = mkdtempSync(join(tmpdir(), "graft-ask-in-structural-"));+ mkdirSync(join(dir, "frontend"), { recursive: true });+ mkdirSync(join(dir, "backend"), { recursive: true });+ writeFileSync(+ join(dir, "frontend", "a.ts"),+ `export function handle(): number {\n return 1;\n}\n\n` ++ `export function frontendCaller(): number {\n return handle();\n}\n`,+ );+ writeFileSync(+ join(dir, "backend", "b.ts"),+ `export function handle(): number {\n return 2;\n}\n\n` ++ `export function backendCaller(): number {\n return handle();\n}\n`,+ );+ return dir;+}++test("ask --in: structural queries narrow the resolved subject by prefix, not just the lexical docs", async () => {+ const dir = duplicateNameFixture();+ try {+ await buildGraph(dir);++ const unfiltered = ask(dir, "who calls handle");+ assert.equal(unfiltered.mode, "structural");+ assert.ok(unfiltered.hits.some((h) => h.title === "frontendCaller"), "sanity: both callers show up unfiltered");+ assert.ok(unfiltered.hits.some((h) => h.title === "backendCaller"), "sanity: both callers show up unfiltered");++ const r = ask(dir, "who calls handle", { in: "frontend" });+ assert.equal(r.mode, "structural", "still resolves structurally once narrowed to frontend's handle");+ assert.ok(r.hits.some((h) => h.title === "frontendCaller"), "frontend's caller must be found");+ assert.ok(+ !r.hits.some((h) => h.title === "backendCaller"),+ "backend's handle/caller must not leak in when --in=frontend",+ );+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+});++test("ask --in: a structural subject that exists ONLY outside the prefix falls through loudly, never a silent no-op", async () => {+ const dir = duplicateNameFixture();+ try {+ await buildGraph(dir);+ // "handle" only resolves under backend/ once frontend/ is filtered out via+ // an --in that excludes it entirely (a prefix with no "handle" at all).+ mkdirSync(join(dir, "docs"), { recursive: true });+ writeFileSync(join(dir, "docs", "readme.ts"), `export function docsOnly(): number {\n return 0;\n}\n`);+ await buildGraph(dir);+ const r = ask(dir, "who calls handle", { in: "docs" });+ assert.notEqual(r.mode, "structural", "no `handle` under docs/ — must fall through, not silently return nothing");+ assert.ok(r.note, "a fallthrough note must be set");+ assert.match(r.note!, /structural index: no entries for 'handle'/);+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+});+/** The regression pin Task 7's cross-version gate relies on: on a single-scope* graph the fusion code paths must be completely inert. `meta.scopes` hand-set* to the canonical single form vs deleted (an old graph) must produce