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
feat(ask): --in scope filter + scope-enumerating errors
Shrish Dwivedic7a7edf16b18
diff --git a/src/ask/ask.ts b/src/ask/ask.tsindex e06303b7..9497180d 100644--- a/src/ask/ask.ts+++ b/src/ask/ask.ts@@ -18,7 +18,7 @@ import { join, resolve } from "node:path";import matter from "gray-matter";import { contextDirFor } from "../context/node-file.js";import { loadGraphCached, loadAskIndexCached } from "../graph/load.js";-import { scopeOf, scopesOfGraph } from "../graph/scopes.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";@@ -333,19 +333,24 @@ function matchedIdfShare(return total > 0 ? matched / total : 0;}-function lexical(query: string, corpus: Corpus, limit: number, graphRank: boolean): AskResult {+function lexical(query: string, corpus: Corpus, limit: number, graphRank: boolean, inPrefix?: string): AskResult {// Binary query terms: a word repeated in a pasted issue body counts once, so a// ranty description can't linearly amplify an incidental word.const q = new Map([...counts(tokenize(query)).keys()].map((t) => [t, 1]));const graph = corpus.graph;// ── Pass 1: tokenize every scored field once, and collect per-document token- // bags so IDF can down-weight words that occur across the whole corpus. ──- const conceptDocs = corpus.concepts.map((c) => ({- c,- name: counts(tokenize(c.name)),- body: counts(tokenize(c.text)),- }));+ // bags so IDF can down-weight words that occur across the whole corpus. `--in`+ // drops a concept unless at least one of its sources falls under the prefix —+ // filtering happens here, before any scoring, so a narrowed query never sees+ // an unrelated concept from outside the prefix. ──+ const conceptDocs = corpus.concepts+ .filter((c) => !inPrefix || c.sources.some((p) => pathUnderPrefix(p, inPrefix)))+ .map((c) => ({+ c,+ name: counts(tokenize(c.name)),+ body: counts(tokenize(c.text)),+ }));// A build-time sidecar (`.cache/ask-index.json`) is usable only when it covers// every node in the current graph: `docs.length === graph.nodes.length` is a@@ -353,9 +358,11 @@ 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.+ // 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.let docById: Map<string, AskIndexDoc> | null = null;- if (corpus.askIndex && graph && corpus.askIndex.docs.length === graph.nodes.length) {+ if (!inPrefix && 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;}@@ -364,8 +371,12 @@ function lexical(query: string, corpus: Corpus, limit: number, graphRank: boolea// Symbols AND file nodes are scored: a symbol's body_text is its definition;// a file's body_text is the module-level residual (imports/constants not in// any symbol). Including files closes the recall gap where a gold file's only- // query-relevant text lives outside every function/class.- const symbolDocs = (graph?.nodes ?? []).map((n) => {+ // query-relevant text lives outside every function/class. `--in` filters the+ // node set here, at the very top, before any scoring — every downstream stat+ // (idf, avgdl, candidates, the per-scope partition below) then naturally+ // reflects only the filtered set with no other code needing to know about it.+ const graphNodes = inPrefix ? (graph?.nodes ?? []).filter((n) => pathUnderPrefix(n.path, inPrefix)) : (graph?.nodes ?? []);+ const symbolDocs = graphNodes.map((n) => {const d = docById?.get(n.id);if (d) return { n, name: new Map(d.name), path: new Map(d.path), body: new Map(d.body) };return {@@ -478,7 +489,10 @@ function lexical(query: string, corpus: Corpus, limit: number, graphRank: booleawalk: (s, seeds) =>graphRank? personalizedPageRank(graph!, seeds, {- nodeFilter: (id) => scopeOf(byId.get(id)?.path ?? "", scopes).prefix === s,+ nodeFilter: (id) => {+ const path = byId.get(id)?.path ?? "";+ return scopeOf(path, scopes).prefix === s && (!inPrefix || pathUnderPrefix(path, inPrefix));+ },}): new Map<string, number>(),},@@ -530,8 +544,11 @@ function lexical(query: string, corpus: Corpus, limit: number, graphRank: boolea}// ── Graph-rank: let connectivity to the matched set reorder and rescue ──+ // `--in` restricts the walk itself, not just the seeds: without a nodeFilter+ // here, a RESCUE_FLOOR-qualifying neighbour OUTSIDE the prefix could still+ // surface, defeating the "filters before scoring" contract.const pr = graphRank && graph && lex.size > 0- ? personalizedPageRank(graph, lex)+ ? personalizedPageRank(graph, lex, inPrefix ? { nodeFilter: (id) => pathUnderPrefix(byId.get(id)?.path ?? "", inPrefix) } : {}): new Map<string, number>();// Candidate symbols = everything the query word-matched, plus nodes the walk@@ -573,7 +590,11 @@ function lexical(query: string, corpus: Corpus, limit: number, graphRank: booleahits: scored.slice(0, limit),scopes: scopeMeta,coverage: scored.length && q.size > 0 ? matchedOf.get(scored[0]) ?? 0 : undefined,- note: scored.length ? undefined : "no matching nodes — try different words, or `graft build` if graft/ is empty",+ // Zero hits on a genuinely multi-scope graph names the scopes that exist,+ // so a query that missed everywhere still tells the caller where to look.+ note: scored.length+ ? undefined+ : `no matching nodes — try different words, or \`graft build\` if graft/ is empty${scopesHereClause(scopes ?? [])}`,};}@@ -593,6 +614,12 @@ export interface AskOptions {* decision point, ~10× cheaper than the full span — and the pack marks each* crux so the agent knows `--full` (or the file itself) has the rest. */full?: boolean;+ /** Narrow the doc/node set to this path prefix BEFORE scoring (segment-aware,+ * like `scopeOf` — "frontend" never matches "frontend-utils"). Per-scope+ * IDF/BM25/walk come free: the filtered set is usually one scope, so the+ * existing multi-scope machinery degrades to its single-scope passthrough+ * with no scope labels. A prefix matching nothing indexed throws. */+ in?: string;}/** Parse a `path:Lx-Ly` pointer into its parts, or null if it isn't one@@ -687,13 +714,23 @@ export function ask(dir: string, query: string, opts: AskOptions = {}): AskResulconst corpus = loadCorpus(outDir);const graphRank = opts.graphRank ?? true;+ // `--in` validated up front, before either 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(/\/+$/, "");+ throw new Error(+ `nothing indexed under "${disp}/"${scopesHereClause(scopesOfGraph(corpus.graph))} (or any path prefix)`,+ );+ }+let result: AskResult;if (corpus.graph) {const outcome = structural(query, corpus.graph, limit);if (outcome && "result" in outcome) {result = outcome.result;} else {- result = lexical(query, corpus, limit, graphRank);+ result = lexical(query, corpus, limit, graphRank, opts.in);// 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) {@@ -701,7 +738,7 @@ export function ask(dir: string, query: string, opts: AskOptions = {}): AskResul}}} else {- result = lexical(query, corpus, limit, graphRank);+ result = lexical(query, corpus, limit, graphRank, opts.in);}if (opts.source) {inlineSource(root, result.hits, corpus.graph, opts.full ?? false);@@ -849,15 +886,14 @@ function savingsFooter(r: AskResult, body: string): string {* Empty (zero output) whenever the result isn't a federated multi-scope one. */function scopeFooterLines(r: AskResult): string[] {if (!r.scopes) return [];- const label = (s: string) => (s === "" ? "(root)" : `${s}/`);const perScope = new Map<string, number>();for (const h of r.hits)if (h.scope !== undefined) perScope.set(h.scope, (perScope.get(h.scope) ?? 0) + 1);const parts = [...perScope].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))- .map(([s, c]) => `${label(s)} (${c})`);+ .map(([s, c]) => `${scopeLabel(s)} (${c})`);const out = parts.length ? [`matched in: ${parts.join(" · ")}`] : [];for (const m of r.scopes.alsoMatched)- out.push(`also matched: ${label(m.scope)} — narrow with --in ${label(m.scope)}`);+ out.push(`also matched: ${scopeLabel(m.scope)} — narrow with --in ${scopeLabel(m.scope)}`);return out;}diff --git a/src/cli.ts b/src/cli.tsindex 6f840004..b316c453 100644--- a/src/cli.ts+++ b/src/cli.ts@@ -174,10 +174,18 @@ program.option("-n, --limit <n>", "max results", "8").option("--source", "inline the source at each file:line hit (retriever mode — the pack IS the answer, no need to re-open files)").option("--full", "with --source: inline whole definition spans instead of the default ≤8-line crux excerpts")+ .option("--in <path>", "narrow to nodes under this path prefix, filtered before scoring (segment-aware, like scopeOf)").option("--json", "output the result as JSON")- .action(async (query: string, dir: string, opts: { limit: string; source?: boolean; full?: boolean; json?: boolean }) => {+ .action(async (query: string, dir: string, opts: { limit: string; source?: boolean; full?: boolean; in?: string; json?: boolean }) => {const engine = engineFrom();- const r = engine.ask(dir, query, { limit: Number(opts.limit), source: opts.source, full: opts.full });+ let r;+ try {+ r = engine.ask(dir, query, { limit: Number(opts.limit), source: opts.source, full: opts.full, in: opts.in });+ } catch (err) {+ console.error(`✗ ${err instanceof Error ? err.message : String(err)}`);+ process.exit(1);+ return;+ }if (opts.json) {console.log(JSON.stringify(r, null, 2));} else {diff --git a/src/engine.ts b/src/engine.tsindex 8f9e2106..4526613c 100644--- a/src/engine.ts+++ b/src/engine.ts@@ -92,8 +92,14 @@ export class Graft {* channel. Deterministic and $0: routes structural queries to the wiring* edges and everything else to a lexical rank over concepts + symbols.*/- ask(dir: string, query: string, opts: { limit?: number; source?: boolean; full?: boolean } = {}): AskResult {- return ask(dir, query, { contextDir: this.cfg.contextDir, limit: opts.limit, source: opts.source, full: opts.full });+ ask(dir: string, query: string, opts: { limit?: number; source?: boolean; full?: boolean; in?: string } = {}): AskResult {+ return ask(dir, query, {+ contextDir: this.cfg.contextDir,+ limit: opts.limit,+ source: opts.source,+ full: opts.full,+ in: opts.in,+ });}private _chatModel?: ChatModel;diff --git a/src/graph/scopes.ts b/src/graph/scopes.tsindex 6b64918f..bff80046 100644--- a/src/graph/scopes.ts+++ b/src/graph/scopes.ts@@ -317,6 +317,31 @@ export function scopeOf(path: string, scopes: ScopeV1[]): ScopeV1 {return scopes.find((s) => s.prefix === "") ?? { prefix: "", label: "", markers: [] };}+/** Display form of a scope prefix: "" reads as "(root)", everything else gets+ * a trailing slash. Shared by ask's `matched in:`/`also matched:` footer, the+ * `--in` no-match error, and the multi-scope zero-hit note. */+export function scopeLabel(prefix: string): string {+ return prefix === "" ? "(root)" : `${prefix}/`;+}++/** " — scopes here: a/ · b/" when `scopes` is genuinely multi-scope (>1+ * entries), else "" — the shared clause `ask` appends to its zero-hit note+ * and its `--in` no-match error, so a caller is always told what IS indexed+ * rather than getting a bare miss. */+export function scopesHereClause(scopes: ScopeV1[]): string {+ if (scopes.length <= 1) return "";+ return ` — scopes here: ${scopes.map((s) => scopeLabel(s.prefix)).join(" · ")}`;+}++/** Segment-aware "is `path` at or under `prefix`?" — a plain `path.startsWith`+ * would wrongly let "frontend" match "frontend-utils"; this requires an exact+ * segment boundary, same rule `scopeOf` uses for its own prefix match. Root+ * (`""`) matches every path. Used to filter ask's doc/node set for+ * `--in <path-prefix>`. */+export function pathUnderPrefix(path: string, prefix: string): boolean {+ return prefix === "" || path === prefix || path.startsWith(`${prefix}/`);+}+/** Immediate subdirs of `root` that are themselves git repos (have `.git`).* Used by workspace federation (Task 5). */export function discoverWorkspaceChildren(root: string): string[] {diff --git a/src/mcp/tools.ts b/src/mcp/tools.tsindex 3e3952a3..ea87db84 100644--- a/src/mcp/tools.ts+++ b/src/mcp/tools.ts@@ -44,6 +44,10 @@ export const TOOLS: ToolDef[] = [type: 'boolean',description: 'inline whole definition spans instead of the default ≤8-line crux excerpts',},+ in: {+ type: 'string',+ description: 'narrow to nodes under this path prefix, filtered before scoring (segment-aware, like scopeOf)',+ },},required: ['query'],},@@ -159,7 +163,8 @@ export function callTool(if (!query) return { text: 'graft_ask requires a query', isError: true };const limit = typeof args.limit === 'number' ? args.limit : 5;const engine = new Graft({ contextDir: dirOverride });- const r = engine.ask(root, query, { limit, source: true, full: args.full === true });+ const inArg = typeof args.in === 'string' && args.in ? args.in : undefined;+ const r = engine.ask(root, query, { limit, source: true, full: args.full === true, in: inArg });return { text: formatAsk(r), isError: false };}case 'graft_skeleton': {diff --git a/test/ask.test.ts b/test/ask.test.tsindex a37171d7..e8f22bcf 100644--- a/test/ask.test.ts+++ b/test/ask.test.ts@@ -10,6 +10,7 @@ import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";import { join } from "node:path";import { tmpdir } from "node:os";import { readFileSync } from "node:fs";+import { execFileSync } from "node:child_process";import { buildGraph } from "../src/graph/build.js";import { ask, formatAsk, skeleton, formatSkeleton } from "../src/ask/ask.js";@@ -327,6 +328,167 @@ test("ask on a multi-scope repo: top hits federate both scopes, labeled, with a}});+// ── `--in <path-prefix>`: filter docs before scoring ────────────────────────++/** `prefix/docA.ts` + `prefix-sibling/docB.ts` — a plain `path.startsWith`+ * would wrongly let "prefix" match "prefix-sibling" too; segment-aware+ * matching (same rule as `scopeOf`) must not. */+function siblingPrefixFixture(): string {+ const dir = mkdtempSync(join(tmpdir(), "graft-ask-in-sibling-"));+ mkdirSync(join(dir, "widgets"), { recursive: true });+ mkdirSync(join(dir, "widgets-extra"), { recursive: true });+ writeFileSync(join(dir, "widgets", "a.ts"), `export function needlefind(): number {\n return 1;\n}\n`);+ writeFileSync(join(dir, "widgets-extra", "b.ts"), `export function needlefind2(): number {\n return 2;\n}\n`);+ return dir;+}++test("ask --in: filters to nodes under the prefix, segment-aware ('widgets' must not match 'widgets-extra')", async () => {+ const dir = siblingPrefixFixture();+ try {+ await buildGraph(dir);+ const r = ask(dir, "needlefind", { in: "widgets", limit: 20 });+ assert.ok(r.hits.length > 0, "the widgets/ hit is still found");+ assert.ok(+ r.hits.every((h) => h.pointer.startsWith("widgets/")),+ `every hit must be under widgets/, got: ${r.hits.map((h) => h.pointer).join(", ")}`,+ );+ assert.ok(+ !r.hits.some((h) => h.pointer.startsWith("widgets-extra/")),+ "widgets-extra/ must NOT be pulled in by a naive substring/prefix match",+ );+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+});++/** `filler/` (30 files) all define `zzzcommonword`, making it common GLOBALLY+ * (low idf); `proj/` has `zzzraretoken` (+ a duplicate, so it's the common+ * term LOCALLY once filler/ is filtered out) and `zzzcommonword_b` (rare+ * locally, once filler/ is gone). This flips which one outranks the other+ * between the unfiltered and `--in`-filtered corpora — proof `--in` recomputes+ * idf over the filtered set rather than reusing the global one. */+function idfShiftFixture(): string {+ const dir = mkdtempSync(join(tmpdir(), "graft-ask-in-idf-"));+ mkdirSync(join(dir, "filler"), { recursive: true });+ mkdirSync(join(dir, "proj"), { recursive: true });+ for (let i = 0; i < 30; i++) {+ writeFileSync(join(dir, "filler", `f${i}.ts`), `export function zzzcommonword(): number {\n return ${i};\n}\n`);+ }+ writeFileSync(join(dir, "proj", "docA.ts"), `export function zzzraretoken(): number {\n return 1;\n}\n`);+ writeFileSync(join(dir, "proj", "docC.ts"), `export function zzzraretoken_dup(): number {\n return 2;\n}\n`);+ writeFileSync(join(dir, "proj", "docB.ts"), `export function zzzcommonword_b(): number {\n return 3;\n}\n`);+ return dir;+}++test("ask --in: per-scope idf differs from global — a term's rank flips relative to another between filtered and unfiltered", async () => {+ const dir = idfShiftFixture();+ try {+ await buildGraph(dir);+ const query = "zzzraretoken zzzcommonword";+ const rankOf = (r: ReturnType<typeof ask>["hits"], title: string) => r.findIndex((h) => h.title.startsWith(title));++ const global = ask(dir, query, { limit: 40 });+ const rareGlobal = rankOf(global.hits, "zzzraretoken ");+ const commonBGlobal = rankOf(global.hits, "zzzcommonword_b");+ assert.ok(rareGlobal >= 0 && commonBGlobal >= 0, "both candidates present globally");+ assert.ok(rareGlobal < commonBGlobal, "globally, the rare term (high idf) outranks the diluted common term");++ const filtered = ask(dir, query, { limit: 40, in: "proj" });+ const rareFiltered = rankOf(filtered.hits, "zzzraretoken ");+ const commonBFiltered = rankOf(filtered.hits, "zzzcommonword_b");+ assert.ok(rareFiltered >= 0 && commonBFiltered >= 0, "both candidates present filtered");+ assert.ok(+ commonBFiltered < rareFiltered,+ "filtered to proj/, zzzcommonword_b (now the locally-rare term) overtakes zzzraretoken (now locally-common)",+ );+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+});++test("ask --in: unknown/no-match prefix throws a scope-enumerating error", async () => {+ const dir = multiScopeFixture();+ try {+ await buildGraph(dir);+ assert.throws(+ () => ask(dir, "how are errors handled", { in: "wrong" }),+ /nothing indexed under "wrong\/" — scopes here: .*frontend\/.*backend\/.* \(or any path prefix\)/,+ );+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+});++test("ask --in: unknown prefix on a single-scope repo throws without a scopes-here clause", async () => {+ const dir = makeFixture();+ try {+ await buildGraph(dir);+ assert.throws(() => ask(dir, "addNumbers", { in: "nosuchdir" }), /nothing indexed under "nosuchdir\/"/);+ assert.throws(() => ask(dir, "addNumbers", { in: "nosuchdir" }), (err: unknown) => {+ assert.ok(err instanceof Error);+ assert.doesNotMatch(err.message, /scopes here:/);+ assert.match(err.message, /\(or any path prefix\)/);+ return true;+ });+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+});++test("CLI: `graft ask --in <unknown>` exits 1 with the scope-enumerating error on stderr", async () => {+ const dir = multiScopeFixture();+ try {+ await buildGraph(dir);+ let threw: (Error & { status?: number; stderr?: string }) | undefined;+ try {+ execFileSync(+ process.execPath,+ ["--import", "tsx", "src/cli.ts", "ask", "how are errors handled", dir, "--in", "wrong"],+ { encoding: "utf8", stdio: "pipe" },+ );+ } catch (err) {+ threw = err as Error & { status?: number; stderr?: string };+ }+ assert.ok(threw, "the CLI must exit non-zero");+ assert.equal(threw!.status, 1);+ assert.match(threw!.stderr ?? "", /✗ nothing indexed under "wrong\/"/);+ assert.match(threw!.stderr ?? "", /scopes here:.*frontend\/.*backend\//);+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+});++test("ask: a zero-hit query on a multi-scope graph appends scope enumeration to the empty note", async () => {+ const dir = multiScopeFixture();+ try {+ await buildGraph(dir);+ const r = ask(dir, "zzzznomatchatallxyz");+ assert.equal(r.mode, "empty");+ assert.match(r.note ?? "", /no matching nodes — try different words/);+ assert.match(r.note ?? "", /scopes here: .*frontend\/.*backend\//);+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+});++test("ask --in on the multi-scope fixture: filtering to one scope carries no scope labels, even though the repo is multi-scope", async () => {+ const dir = multiScopeFixture();+ try {+ await buildGraph(dir);+ const r = ask(dir, "how are errors handled", { limit: 10, in: "frontend" });+ assert.ok(r.hits.length > 0);+ assert.ok(+ r.hits.every((h) => h.scope === "frontend"),+ "only frontend/ hits survive the filter",+ );+ assert.equal(r.scopes, undefined, "single scope remaining under the prefix — no fusion metadata");+ const out = formatAsk(r);+ assert.doesNotMatch(out, /\[frontend\/\] |\[backend\/\] |matched in:|also matched:/);+ } 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 producediff --git a/test/mcp-tools.test.ts b/test/mcp-tools.test.tsindex 6ab6e266..22e411e7 100644--- a/test/mcp-tools.test.ts+++ b/test/mcp-tools.test.ts@@ -102,6 +102,18 @@ test('graft_ask returns ranked hits for a built repo', () => {assert.match(r.text, /src\/math\.ts/);});+test('graft_ask: `in` arg round-trips — narrows results to the prefix and is a soft isError on an unknown one', () => {+ const d = builtRepo();+ const ok = callTool(d, 'graft_ask', { query: 'how do I add numbers', in: 'src' });+ assert.equal(ok.isError, false);+ assert.match(ok.text, /src\/math\.ts/);++ const miss = callTool(d, 'graft_ask', { query: 'how do I add numbers', in: 'nosuchdir' });+ assert.equal(miss.isError, true);+ assert.match(miss.text, /nothing indexed under "nosuchdir\/"/);+ assert.match(miss.text, /or any path prefix/);+});+test('graft_check reports the wiring state', () => {const d = builtRepo();const r = callTool(d, 'graft_check', {});