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
Prioritize distinct files before sibling spans (#137)
Buseong Kimf960b1eafd2f
diff --git a/src/ask/ask.ts b/src/ask/ask.tsindex 2be6aa8c..434d693e 100644--- a/src/ask/ask.ts+++ b/src/ask/ask.ts@@ -31,6 +31,7 @@ import { normalizePathPrefix } from "../util/paths.js";import { resolveSymbol } from "../graph/traverse.js";import type { EdgeV1, GraphV1, NodeV1, Relation } from "../graph/types.js";import { rankScopesAndFuse } from "./fuse.js";+import { fileFirstRoundRobin } from "./file-selection.js";import { personalizedPageRank } from "./graphrank.js";import { readSourceFile } from "../util/source.js";import { counts, tokenize, type AskIndex, type AskIndexDoc } from "./index-file.js";@@ -63,6 +64,9 @@ export interface AskResult {mode: "structural" | "lexical" | "empty";/** For structural mode: the symbol whose neighbours we walked. */subject?: string;+ /** Authoritative result order. Lexical results preserve each hit's raw+ * relevance score, but select distinct-file leaders before sibling spans, so+ * callers must not re-sort this list by `score`. */hits: AskHit[];note?: string;/** Token-saving estimate, set only in `--source` (retriever) mode: the whole@@ -392,7 +396,14 @@ function matchedIdfShare(return total > 0 ? matched / total : 0;}-function lexical(query: string, corpus: Corpus, limit: number, graphRank: boolean, inPrefix?: string): AskResult {+function lexical(+ query: string,+ corpus: Corpus,+ limit: number,+ graphRank: boolean,+ inPrefix?: string,+ fileFirst = true,+): 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]));@@ -496,6 +507,10 @@ function lexical(query: string, corpus: Corpus, limit: number, graphRank: boolea// Parallel to matchedOf, but over NAME+PATH only (body dropped) — the// match-strength signal exported as `coverageStrong`.const matchedStrongOf = new Map<AskHit, number>();+ // Final listwise selection groups code hits by exact source path. Concepts+ // use singleton pseudo-groups so they remain ordinary ranked candidates+ // without masquerading as every file listed in their sources.+ const selectionGroupOf = new Map<AskHit, string>();// ── Concepts (prose nodes; not in the wiring graph) ──const conceptHits: AskHit[] = [];@@ -514,6 +529,10 @@ function lexical(query: string, corpus: Corpus, limit: number, graphRank: boolea};matchedOf.set(hit, matchedIdfShare(q, [name, body], idf, dfltIdf));matchedStrongOf.set(hit, matchedIdfShare(q, [name], idf, dfltIdf)); // concepts have no path field+ // A concept is one singleton partition even if two source entries reuse+ // the same slug; include its stable encounter index to prevent accidental+ // grouping by frontmatter alone.+ selectionGroupOf.set(hit, `concept:${c.slug}:${conceptHits.length}`);conceptHits.push(hit);}}@@ -528,8 +547,7 @@ function lexical(query: string, corpus: Corpus, limit: number, graphRank: booleaconst docsById = new Map(symbolDocs.map((d) => [d.n.id, d]));const symbolHits: AskHit[] = [];// The single-vs-multi-scope branch keys on `scopesOfGraph` ONLY: one scope- // (or no graph) takes the existing path below completely untouched — that- // branch is a byte-level regression guarantee for single-scope repos.+ // (or no graph) keeps the original local scoring path.const scopes = graph ? scopesOfGraph(graph) : null;let scopeMeta: AskResult["scopes"];// The BM25 length prior, corpus-global like `idf`/`dfltIdf` above. Hoisted out@@ -615,6 +633,7 @@ function lexical(query: string, corpus: Corpus, limit: number, graphRank: boolea// nudge and the hook's coverage gate both read these.matchedOf.set(hit, d ? matchedIdfShare(q, [d.name, d.path, d.body], idf, dfltIdf) : 0);matchedStrongOf.set(hit, d ? strongShare(q, n, d, idf, dfltIdf) : 0);+ selectionGroupOf.set(hit, `file:${n.path}`);symbolHits.push(hit);}// Label + footer only when federation actually happened (or a scope was@@ -677,24 +696,39 @@ function lexical(query: string, corpus: Corpus, limit: number, graphRank: booleaconst d = docsById.get(id);matchedOf.set(hit, d ? matchedIdfShare(q, [d.name, d.path, d.body], idf, dfltIdf) : 0);matchedStrongOf.set(hit, d ? strongShare(q, n, d, idf, dfltIdf) : 0);+ selectionGroupOf.set(hit, `file:${n.path}`);symbolHits.push(hit);}}// Concepts and symbols live on comparable 0..~1.5 scales so they merge fairly:- // concept scores are normalized to their own max, symbol scores are the+ // concept scores are normalized to their own max; symbol scores use the// lexical-normalized + graph-weighted blend.for (const h of conceptHits) h.score = maxConcept > 0 ? h.score / maxConcept : 0;const scored = [...conceptHits, ...symbolHits];scored.sort((a, b) => b.score - a.score || a.title.localeCompare(b.title));+ // Preserve the baseline first-occurrence order of files and the exact top+ // hit, while emitting one representative per file before any second span.+ // A workspace child defers this step until cross-repo fusion has established+ // the final authoritative ranking.+ const selected = fileFirst+ ? fileFirstRoundRobin(+ scored.map((hit, index) => ({+ group: selectionGroupOf.get(hit) ?? `ungrouped:${index}`,+ value: hit,+ })),+ limit,+ )+ : scored;+ const top = selected[0] ?? scored[0];return {query,mode: scored.length ? "lexical" : "empty",- hits: scored.slice(0, limit),+ hits: selected.slice(0, limit),scopes: scopeMeta,- coverage: scored.length && q.size > 0 ? matchedOf.get(scored[0]) ?? 0 : undefined,- coverageStrong: scored.length && q.size > 0 ? matchedStrongOf.get(scored[0]) ?? 0 : undefined,+ coverage: top && q.size > 0 ? matchedOf.get(top) ?? 0 : undefined,+ coverageStrong: top && q.size > 0 ? matchedStrongOf.get(top) ?? 0 : undefined,// 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@@ -725,6 +759,10 @@ export interface AskOptions {* existing multi-scope machinery degrades to its single-scope passthrough* with no scope labels. A prefix matching nothing indexed throws. */in?: string;+ /** @internal Defer file-first projection to a downstream authoritative+ * ranking stage (currently workspace federation). Direct callers should+ * leave this unset. */+ fileFirst?: boolean;}/** Parse a `path:Lx-Ly` pointer into its parts, or null if it isn't one@@ -825,7 +863,7 @@ export function ask(dir: string, query: string, opts: AskOptions = {}): AskResulif (outcome && "result" in outcome) {result = outcome.result;} else {- result = lexical(query, corpus, limit, graphRank, inPrefix);+ result = lexical(query, corpus, limit, graphRank, inPrefix, opts.fileFirst ?? true);// 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) {@@ -833,7 +871,7 @@ export function ask(dir: string, query: string, opts: AskOptions = {}): AskResul}}} else {- result = lexical(query, corpus, limit, graphRank, inPrefix);+ result = lexical(query, corpus, limit, graphRank, inPrefix, opts.fileFirst ?? true);}if (opts.source) {inlineSource(root, result.hits, corpus.graph, opts.full ?? false);diff --git a/src/ask/file-selection.ts b/src/ask/file-selection.tsnew file mode 100644index 00000000..fbbe0031--- /dev/null+++ b/src/ask/file-selection.ts@@ -0,0 +1,45 @@+/** One already-ranked result and the file/partition whose output queue owns it. */+export interface FileFirstCandidate<T> {+ group: string;+ value: T;+}++/**+ * Project an existing ranking through file-first round-robin selection.+ *+ * The input MUST already be in baseline rank order. Map insertion order makes+ * the first pass exactly the baseline first-occurrence order of groups; later+ * passes expose additional spans only after every group has contributed its+ * leader. Concepts can participate without pretending to be source files by+ * receiving singleton group keys.+ *+ * Values are returned by identity and are never mutated.+ */+export function fileFirstRoundRobin<T>(+ ranked: readonly FileFirstCandidate<T>[],+ limit = Number.POSITIVE_INFINITY,+): T[] {+ const cap = Number.isFinite(limit) ? Math.max(0, Math.floor(limit)) : Number.POSITIVE_INFINITY;+ if (cap === 0) return [];++ const grouped = new Map<string, T[]>();+ for (const candidate of ranked) {+ const queue = grouped.get(candidate.group);+ if (queue) queue.push(candidate.value);+ else grouped.set(candidate.group, [candidate.value]);+ }++ const queues = [...grouped.values()];+ const out: T[] = [];+ for (let depth = 0; ; depth += 1) {+ let added = false;+ for (const queue of queues) {+ if (depth >= queue.length) continue;+ out.push(queue[depth]);+ added = true;+ if (out.length >= cap) return out;+ }+ if (!added) break;+ }+ return out;+}diff --git a/src/graph/workspace.ts b/src/graph/workspace.tsindex 3ef30419..3a811327 100644--- a/src/graph/workspace.ts+++ b/src/graph/workspace.ts@@ -38,6 +38,7 @@ import { edgeWalk, resolveSymbol, type Direction } from "./traverse.js";import { wiringPath } from "./write.js";import type { GraphV1 } from "./types.js";import { ask, type AskHit, type AskResult } from "../ask/ask.js";+import { fileFirstRoundRobin } from "../ask/file-selection.js";import { fuseScopes, STRONG_FLOOR, HIGH_FLOOR, type ScopedDoc } from "../ask/fuse.js";import { grepGraph, type GrepGroup, type GrepResult } from "../search/grep.js";import { formatGrepResult, zeroHitNote } from "../search/grep-cli.js";@@ -168,6 +169,12 @@ function prefixPointer(child: string, pointer: string): string {.join(", ");}+/** The exact child-relative file owning a lexical symbol hit. File nodes use a+ * bare path; definition hits append `:Lx-Ly`. */+function hitFile(pointer: string): string {+ return pointer.match(/^(.*):L\d+-L\d+$/)?.[1] ?? pointer;+}+export interface FederateAskOptions {limit?: number;source?: boolean;@@ -253,6 +260,9 @@ export function federateAsk(full: opts.full,graphRank: opts.graphRank,in: childIn,+ // The parent owns the final cross-repo ranking. Selecting inside each+ // child would be undone by fusion and could truncate a hybrid list.+ fileFirst: false,});} catch {continue; // corrupt child, or a sub-scope --in matching nothing here@@ -298,10 +308,25 @@ export function federateAsk(}const fused = fuseScopes(docs);- const hits: AskHit[] = fused.ranked.slice(0, limit).map((rd) => {+ const rankedHits = fused.ranked.map((rd) => {const { child, hit } = back.get(rd.id)!;- return { ...hit, score: rd.score, scope: rd.scope, pointer: prefixPointer(child, hit.pointer) };+ const value: AskHit = {+ ...hit,+ score: rd.score,+ scope: rd.scope,+ pointer: prefixPointer(child, hit.pointer),+ };+ return {+ // Lexical symbols share a file queue. Concepts and structural neighbours+ // remain singleton partitions, so this lexical selection layer cannot+ // reorder `who calls` / `dependencies of` answers.+ group: hit.kind === "symbol"+ ? `file:${child}/${hitFile(hit.pointer)}`+ : `singleton:${child}:${rd.id}`,+ value,+ };});+ const hits = fileFirstRoundRobin(rankedHits, limit);const alsoMatched = [...fused.alsoMatched, ...gatedOut];const note = coverageNote(wg);diff --git a/test/ask-file-selection.test.ts b/test/ask-file-selection.test.tsnew file mode 100644index 00000000..c9640bfd--- /dev/null+++ b/test/ask-file-selection.test.ts@@ -0,0 +1,48 @@+import { test } from "node:test";+import assert from "node:assert/strict";+import { fileFirstRoundRobin } from "../src/ask/file-selection.js";++test("file-first projection preserves file order and emits leaders before sibling spans", () => {+ const ranked = [+ { id: "A1", file: "a.ts", score: 0.95 },+ { id: "A2", file: "a.ts", score: 0.93 },+ { id: "B1", file: "b.ts", score: 0.90 },+ { id: "C1", file: "c.ts", score: 0.88 },+ { id: "A3", file: "a.ts", score: 0.85 },+ { id: "D1", file: "d.ts", score: 0.80 },+ { id: "B2", file: "b.ts", score: 0.70 },+ { id: "D2", file: "d.ts", score: 0.60 },+ ];++ const grouped = ranked.map((value) => ({ group: value.file, value }));+ const projected = fileFirstRoundRobin(grouped);++ assert.deepEqual(projected.map((value) => value.id), [+ "A1", "B1", "C1", "D1", "A2", "B2", "D2", "A3",+ ]);+ assert.deepEqual(+ [...new Set(projected.map((value) => value.file))],+ [...new Set(ranked.map((value) => value.file))],+ "the first pass keeps the baseline first-occurrence file order",+ );+ assert.equal(projected[0], ranked[0], "projection preserves candidate identity and top-1");+ assert.deepEqual(+ fileFirstRoundRobin(grouped, 3).map((value) => value.id),+ ["A1", "B1", "C1"],+ "a bounded prefix does not materialize second spans before file leaders",+ );+});++test("file-first projection treats concepts as singleton partitions", () => {+ const ranked = [+ { id: "A1", group: "file:a.ts" },+ { id: "A2", group: "file:a.ts" },+ { id: "concept", group: "concept:auth:0" },+ { id: "B1", group: "file:b.ts" },+ ];++ const projected = fileFirstRoundRobin(+ ranked.map((value) => ({ group: value.group, value })),+ );+ assert.deepEqual(projected.map((value) => value.id), ["A1", "concept", "B1", "A2"]);+});diff --git a/test/ask.test.ts b/test/ask.test.tsindex ae1f8c3e..c661e996 100644--- a/test/ask.test.ts+++ b/test/ask.test.ts@@ -203,6 +203,45 @@ test("ask reports coverage: 1.0 when every query term hits, low on mostly-off-co}});+test("ask file-first selection preserves baseline file order and delays sibling spans", async () => {+ const dir = mkdtempSync(join(tmpdir(), "graft-ask-file-first-"));+ try {+ writeFileSync(+ join(dir, "a.ts"),+ `export function quartzAlpha(): string { return "quartz"; }\n` ++ `export function quartzBeta(): string { return "quartz"; }\n` ++ `export function quartzGamma(): string { return "quartz"; }\n`,+ );+ writeFileSync(join(dir, "b.ts"), `export function quartzDelta(): string { return "quartz"; }\n`);+ writeFileSync(join(dir, "c.ts"), `export function quartzEpsilon(): string { return "quartz"; }\n`);+ await buildGraph(dir);++ const baseline = ask(dir, "quartz", { graphRank: false, limit: 20, fileFirst: false });+ const pathOf = (pointer: string) => pointer.split(":")[0];+ const baselineFiles = baseline.hits.map((hit) => pathOf(hit.pointer));+ const baselineFileOrder = [...new Set(baselineFiles)];+ assert.ok(baselineFileOrder.length >= 3, "fixture produces at least three ranked files");+ assert.ok(new Set(baselineFiles.slice(0, 3)).size < 3, "baseline prefix contains sibling spans");++ const selected = ask(dir, "quartz", { graphRank: false, limit: 20 });+ const selectedFiles = selected.hits.map((hit) => pathOf(hit.pointer));+ assert.deepEqual(+ selectedFiles.slice(0, baselineFileOrder.length),+ baselineFileOrder,+ "the first pass is the exact baseline first-occurrence file order",+ );+ assert.equal(selected.hits[0].pointer, baseline.hits[0].pointer, "top hit is frozen by construction");+ assert.equal(selected.coverage, baseline.coverage, "top-hit relevance coverage is unchanged");+ assert.equal(selected.coverageStrong, baseline.coverageStrong, "top-hit strength coverage is unchanged");+ assert.ok(+ selectedFiles.slice(baselineFileOrder.length).includes("a.ts"),+ "later rounds retain additional exact spans instead of imposing quota one",+ );+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+});+test("ask finds a symbol by a term that appears only in its body (body-indexing)", async () => {const dir = mkdtempSync(join(tmpdir(), "graft-ask-body-"));try {@@ -412,6 +451,27 @@ test("ask on a multi-scope repo: top hits federate both scopes, labeled, with a}});+test("file-first selection preserves a multi-scope result's top relevance and file order", async () => {+ const dir = multiScopeFixture();+ try {+ await buildGraph(dir);+ const baseline = ask(dir, "how are errors handled", { limit: 30, fileFirst: false });++ const selected = ask(dir, "how are errors handled", { limit: 30 });+ const pathOf = (pointer: string) => pointer.split(":")[0];+ const baselineFileOrder = [...new Set(baseline.hits.map((hit) => pathOf(hit.pointer)))];+ const selectedFiles = selected.hits.map((hit) => pathOf(hit.pointer));++ assert.deepEqual(selectedFiles.slice(0, baselineFileOrder.length), baselineFileOrder);+ assert.equal(selected.hits[0].pointer, baseline.hits[0].pointer);+ assert.equal(selected.coverage, baseline.coverage);+ assert.equal(selected.coverageStrong, baseline.coverageStrong);+ assert.deepEqual(selected.scopes, baseline.scopes, "selection does not alter scope participation metadata");+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+});+/** Cross-seam repro (final-review bug): a monorepo-shaped single-graph repo* with two marker-carrying sub-scopes — `api/` has REAL symbols named for the* query terms; `junk/` has NO such symbol, only a body comment repeating ONEdiff --git a/test/workspace.test.ts b/test/workspace.test.tsindex 24adf340..3f71db21 100644--- a/test/workspace.test.ts+++ b/test/workspace.test.ts@@ -108,6 +108,42 @@ test("ask at the parent federates hits from both children, labeled <child>/", asrmSync(p, { recursive: true, force: true });});+test("workspace ask applies file-first selection after cross-repo fusion", async () => {+ const p = workspaceFx({+ repoA: {+ "a.ts":+ `export function quartzAlphaA() { return "quartz"; }\n` ++ `export function quartzBetaA() { return "quartz"; }\n` ++ `export function quartzGammaA() { return "quartz"; }\n`,+ "b.ts": `export function quartzOmegaB() { return "quartz"; }\n`,+ },+ repoB: {+ // Same basename as repoA proves child identity is part of the group key.+ "a.ts":+ `export function quartzAlphaC() { return "quartz"; }\n` ++ `export function quartzBetaC() { return "quartz"; }\n`,+ "d.ts": `export function quartzOmegaD() { return "quartz"; }\n`,+ },+ });+ try {+ await buildWorkspace(p);+ const r = federateAsk(p, undefined, "quartz", { limit: 8, graphRank: false });+ const files = r.hits.map((hit) => hit.pointer.replace(/:L\d+-L\d+$/, ""));+ const firstPass = [...new Set(files)];++ assert.deepEqual(files.slice(0, firstPass.length), [+ "repoA/a.ts",+ "repoB/a.ts",+ "repoB/d.ts",+ "repoA/b.ts",+ ], "selection runs after raw child results have established the fused file order");+ assert.ok(files.slice(firstPass.length).includes("repoA/a.ts"), "later rounds retain sibling spans");+ assert.ok(files.slice(firstPass.length).includes("repoB/a.ts"), "same-path files in different children stay distinct");+ } finally {+ rmSync(p, { recursive: true, force: true });+ }+});+test("ask inside a single child = standalone (no federation scopes)", async () => {const p = workspaceFx(REPOS);await buildWorkspace(p);