Skip to content

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

Prioritize distinct files before sibling spans (#137)

Buseong Kimf960b1eafd2f
diff --git a/src/ask/ask.ts b/src/ask/ask.ts
index 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: boolea
const 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: boolea
const 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 = {}): AskResul
if (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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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 ONE
diff --git a/test/workspace.test.ts b/test/workspace.test.ts
index 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>/", as
rmSync(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);