Skip to content

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

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.ts
index 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: boolea
if (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 = {}): AskResul
const 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.ts
index 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