Skip to content

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

Rank bounded file evidence before span projection (#205)

Buseong Kimc6b5fe3559b7
diff --git a/src/ask/ask.ts b/src/ask/ask.ts
index 434d693e..9afff109 100644
--- a/src/ask/ask.ts
+++ b/src/ask/ask.ts
@@ -30,8 +30,17 @@ import {
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 {
+ combineComparableScopes,
+ rankScopesAndFuse,
+ type ScopeRankCandidate,
+} from "./fuse.js";
+import {
+ rankFilesBounded,
+ type FileRankCandidate,
+ type RankedFile,
+} from "./file-rank.js";
+import { fileFirstRoundRobin, roundRobinQueues } 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";
@@ -55,6 +64,30 @@ export interface AskHit {
scope?: string;
}
+/** Internal file-aware ranking group. The first hit is the one document that
+ * participates in a higher-level ranker; the remaining hits are projected only
+ * after every ranked group has emitted its leader. */
+export interface AskRankingGroup {
+ key: string;
+ hits: AskHit[];
+ /** Exact baseline-scored members of this group, in baseline order. Populated
+ * only in opt-in metadata so a workspace top lock never reuses a pooled
+ * leader score for a secondary span. */
+ baselineHits?: AskHit[];
+ coverage: number;
+ coverageStrong: number;
+}
+
+/** Internal metadata used by workspace federation to fuse file documents
+ * before projecting symbol spans. It is opt-in and never appears in normal
+ * CLI/API results. */
+export interface AskRankingMetadata {
+ groups: AskRankingGroup[];
+ baseline: Array<{ group: string; hit: AskHit }>;
+ baselineCoverage?: number;
+ baselineCoverageStrong?: number;
+}
+
/** Max source lines to inline per hit — a definition longer than this is
* truncated with a marker, so one giant function can't blow up the pack. */
const MAX_SPAN_LINES = 80;
@@ -92,6 +125,8 @@ export interface AskResult {
* doc id). Drives formatAsk's `matched in:` / `also matched:` footer.
* Absent on single-scope repos — zero output change there. */
scopes?: { federated: string[]; alsoMatched: { scope: string; bestId: string }[] };
+ /** @internal Opt-in latent file groups plus the exact pre-file-ranking list. */
+ ranking?: AskRankingMetadata;
}
/** First real prose line of a node body (skips headings, markers, blanks). */
@@ -225,6 +260,32 @@ function bm25(
return s;
}
+/** Exact query terms awarded by the existing lexical fields. Bounded ranking uses
+ * presence only: raw name/path/BM25 magnitudes cannot enter the file residual. */
+function matchedLexicalTerms(
+ query: Map<string, number>,
+ name: Map<string, number>,
+ path: Map<string, number>,
+ body: Map<string, number>,
+): Set<string> {
+ const terms = new Set<string>();
+ for (const term of query.keys())
+ if (name.has(term) || path.has(term) || body.has(term)) terms.add(term);
+ return terms;
+}
+
+/** NAME-only query terms behind file-level strong coverage. This intentionally
+ * mirrors {@link strongShare}'s plural folding while excluding file nodes at
+ * the call site. */
+function matchedStrongTerms(
+ query: Map<string, number>,
+ name: Map<string, number>,
+): Set<string> {
+ const terms = new Set<string>();
+ for (const term of query.keys()) if (hasTerm(name, term)) terms.add(term);
+ return terms;
+}
+
// ── Structural intent ──────────────────────────────────────────────────────
const INCOMING = /\b(caller|callers|calls?\s+into|who\s+calls|what\s+calls|called\s+by|used\s+by|uses)\b/;
@@ -396,6 +457,23 @@ function matchedIdfShare(
return total > 0 ? matched / total : 0;
}
+/** Normalized query-term IDF mass used by file-level union coverage. Presence
+ * comes from the exact term-contribution maps, so plural folding cannot
+ * manufacture evidence that the lexical scorer did not award. */
+function normalizedQueryWeights(
+ q: Map<string, number>,
+ idf: Map<string, number>,
+ dfltIdf: number,
+): Map<string, number> {
+ let total = 0;
+ for (const t of q.keys()) total += idf.get(t) ?? dfltIdf;
+ if (total <= 0) return new Map();
+
+ return new Map(
+ [...q.keys()].map((term) => [term, (idf.get(term) ?? dfltIdf) / total]),
+ );
+}
+
function lexical(
query: string,
corpus: Corpus,
@@ -403,6 +481,9 @@ function lexical(
graphRank: boolean,
inPrefix?: string,
fileFirst = true,
+ fileComplement = false,
+ fileTopLock = false,
+ includeRankingMetadata = false,
): 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.
@@ -546,6 +627,36 @@ function lexical(
};
const docsById = new Map(symbolDocs.map((d) => [d.n.id, d]));
const symbolHits: AskHit[] = [];
+ const baselineSymbolHits: AskHit[] = [];
+ const baselineHitById = new Map<string, AskHit>();
+ const fileQueueHitsByGroup = new Map<string, () => AskHit[]>();
+ const baselineQueueHitsByGroup = new Map<string, () => AskHit[]>();
+ const fileGroups: AskRankingGroup[] = [];
+ const needsFileQueues = fileComplement && (fileTopLock || includeRankingMetadata);
+ const makeSymbolHit = (id: string, hitScore: number, scope?: string): AskHit | null => {
+ const n = byId.get(id);
+ if (!n) return null;
+ const hit: AskHit = {
+ kind: "symbol",
+ title: `${n.name} · ${n.kind}`,
+ pointer: n.kind === "file" ? n.path : `${n.path}:${n.span}`,
+ snippet: n.summary?.split("\n")[0].trim() ?? n.signature ?? "",
+ score: hitScore,
+ ...(scope === undefined ? {} : { scope }),
+ };
+ 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}`);
+ return hit;
+ };
+ const symbolTitle = (id: string): string => {
+ const n = byId.get(id);
+ return n ? `${n.name} · ${n.kind}` : id;
+ };
// The single-vs-multi-scope branch keys on `scopesOfGraph` ONLY: one scope
// (or no graph) keeps the original local scoring path.
const scopes = graph ? scopesOfGraph(graph) : null;
@@ -560,6 +671,18 @@ function lexical(
: symbolDocs.length
? symbolDocs.reduce((a, d) => a + bodyLen(d.body), 0) / symbolDocs.length
: 0;
+ // Populated only for bounded file ranking. The baseline path pays no allocation
+ // or matched-term tracking cost, and their scalar lexical path remains exact.
+ const rawLexicalById = new Map<string, number>();
+ const matchedTermsById = new Map<string, Set<string>>();
+ const matchedStrongTermsById = new Map<string, Set<string>>();
+ const fileQueryWeights = fileComplement
+ ? normalizedQueryWeights(q, idf, dfltIdf)
+ : new Map<string, number>();
+ const spanStart = (span: string): number => {
+ const match = span.match(/^L(\d+)-L\d+$/);
+ return match ? Number(match[1]) : Number.POSITIVE_INFINITY;
+ };
if (scopes && scopes.length > 1) {
// ── Multi-scope repo: partition by sub-project and walk each subgraph
// separately — so the big scope can't drown the small one — but score every
@@ -573,6 +696,9 @@ function lexical(
if (list) list.push(d);
else byScope.set(s, [d]);
}
+ let collapsedComponents: ScopeRankCandidate[] = [];
+ let collapsedComponentById: Map<string, ScopeRankCandidate> | undefined;
+ let collapsedFileByRepresentative: Map<string, RankedFile> | undefined;
const fusion = rankScopesAndFuse(
[...byScope.keys()].sort(),
{
@@ -586,12 +712,24 @@ function lexical(
// per-scope now; the statistics are global.
const out = new Map<string, number>();
for (const { n, name, path, body } of docs) {
+ const factor = testFactor(n.path);
const total =
(score(q, name, idf) * 3 +
score(q, path, idf) * 2 +
bm25(q, body, idf, bodyLen(body), avgBodyLen)) *
- testFactor(n.path);
- if (total > 0) out.set(n.id, total);
+ factor;
+ if (total > 0) {
+ out.set(n.id, total);
+ if (fileComplement) {
+ rawLexicalById.set(n.id, total);
+ matchedTermsById.set(
+ n.id,
+ matchedLexicalTerms(q, name, path, body),
+ );
+ if (n.kind !== "file")
+ matchedStrongTermsById.set(n.id, matchedStrongTerms(q, name));
+ }
+ }
}
return out;
},
@@ -612,29 +750,136 @@ function lexical(
})
: new Map<string, number>(),
rankFactor: (_s, id) => testFactor(byId.get(id)?.path ?? ""),
+ collapseCandidates: fileComplement
+ ? (candidates) => {
+ collapsedComponents = [...candidates];
+ collapsedComponentById = new Map(
+ candidates.map((candidate) => [candidate.id, candidate]),
+ );
+ const fileCandidates: FileRankCandidate[] = candidates.map((candidate) => {
+ const n = byId.get(candidate.id);
+ const rawLexical = rawLexicalById.get(candidate.id) ?? 0;
+ return {
+ id: candidate.id,
+ file: n?.path ?? "",
+ kind: n?.kind === "file" ? "file" : "symbol",
+ rawLexical,
+ lexical: candidate.lexical,
+ graph: candidate.graph,
+ rankFactor: candidate.rankFactor,
+ baselineScore: candidate.score,
+ baselineTieKey: symbolTitle(candidate.id),
+ matchedTerms: matchedTermsById.get(candidate.id) ?? new Set<string>(),
+ matchedStrongTerms:
+ matchedStrongTermsById.get(candidate.id) ?? new Set<string>(),
+ eligible: Boolean(n && n.kind !== "file" && rawLexical > 0),
+ spanStart: n ? spanStart(n.span) : undefined,
+ };
+ });
+ const rankedFiles = rankFilesBounded(
+ fileCandidates,
+ fileQueryWeights,
+ );
+ collapsedFileByRepresentative = new Map(
+ rankedFiles.map((file) => [file.representative.id, file]),
+ );
+ return rankedFiles.map((file) => {
+ const component = collapsedComponentById!.get(file.representative.id)!;
+ return {
+ id: file.representative.id,
+ scope: component.scope,
+ score: file.score,
+ };
+ });
+ }
+ : undefined,
},
GRAPH_WEIGHT,
RESCUE_FLOOR,
);
- for (const rd of fusion.ranked) {
- const n = byId.get(rd.id);
- if (!n) continue;
- const hit: AskHit = {
- kind: "symbol",
- title: `${n.name} · ${n.kind}`,
- pointer: n.kind === "file" ? n.path : `${n.path}:${n.span}`,
- snippet: n.summary?.split("\n")[0].trim() ?? n.signature ?? "",
- score: rd.score,
- scope: rd.scope,
- };
- const d = docsById.get(rd.id);
- // Global idf here too, so per-hit coverage means the same thing in a
- // multi-scope repo as it does in a single-scope one — the escalation
- // 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);
+ if (needsFileQueues) {
+ const baselineFusion = combineComparableScopes(
+ collapsedComponents.map(({ id, scope, score }) => ({ id, scope, score })),
+ );
+ const baselineScoreById = new Map(
+ baselineFusion.ranked.map((ranked) => [ranked.id, ranked.score]),
+ );
+ const baselineDisplayOrder = (
+ a: { id: string; score: number },
+ b: { id: string; score: number },
+ ): number =>
+ b.score - a.score || symbolTitle(a.id).localeCompare(symbolTitle(b.id));
+ let baselineTopRanked = baselineFusion.ranked[0];
+ for (const ranked of baselineFusion.ranked.slice(1))
+ if (baselineTopRanked && baselineDisplayOrder(ranked, baselineTopRanked) < 0)
+ baselineTopRanked = ranked;
+ const baselineHitsToBuild = includeRankingMetadata
+ ? [...baselineFusion.ranked].sort(baselineDisplayOrder)
+ : baselineTopRanked
+ ? [baselineTopRanked]
+ : [];
+ for (const ranked of baselineHitsToBuild) {
+ const hit = makeSymbolHit(ranked.id, ranked.score, ranked.scope);
+ if (hit) {
+ baselineSymbolHits.push(hit);
+ baselineHitById.set(ranked.id, hit);
+ }
+ }
+ for (const ranked of fusion.ranked) {
+ const file = collapsedFileByRepresentative?.get(ranked.id);
+ if (!file) continue;
+ const materializeFileQueue = (): AskHit[] => file.queue.flatMap((member, index) => {
+ const component = collapsedComponentById?.get(member.id);
+ if (index > 0) {
+ const baselineHit = baselineHitById.get(member.id);
+ if (baselineHit) return [baselineHit];
+ }
+ const hit = makeSymbolHit(
+ member.id,
+ index === 0
+ ? ranked.score
+ : baselineScoreById.get(member.id) ?? member.baselineScore,
+ component?.scope ?? ranked.scope,
+ );
+ return hit ? [hit] : [];
+ });
+ const materializeBaselineQueue = (): AskHit[] => file.queue.flatMap((member) => {
+ const hit = makeSymbolHit(
+ member.id,
+ baselineScoreById.get(member.id) ?? member.baselineScore,
+ collapsedComponentById?.get(member.id)?.scope ?? ranked.scope,
+ );
+ return hit ? [hit] : [];
+ });
+ const hits = includeRankingMetadata
+ ? materializeFileQueue()
+ : (() => {
+ const leader = file.queue[0];
+ if (!leader) return [];
+ const hit = makeSymbolHit(
+ leader.id,
+ ranked.score,
+ collapsedComponentById?.get(leader.id)?.scope ?? ranked.scope,
+ );
+ return hit ? [hit] : [];
+ })();
+ if (hits.length === 0) continue;
+ const group: AskRankingGroup = {
+ key: `file:${file.file}`,
+ hits,
+ coverage: file.unionCoverage,
+ coverageStrong: file.unionStrongCoverage,
+ };
+ fileQueueHitsByGroup.set(group.key, materializeFileQueue);
+ baselineQueueHitsByGroup.set(group.key, materializeBaselineQueue);
+ fileGroups.push(group);
+ symbolHits.push(hits[0]);
+ }
+ } else {
+ for (const ranked of fusion.ranked) {
+ const hit = makeSymbolHit(ranked.id, ranked.score, ranked.scope);
+ if (hit) symbolHits.push(hit);
+ }
}
// Label + footer only when federation actually happened (or a scope was
// gated out and is worth mentioning) — a query matching one scope of a
@@ -651,14 +896,24 @@ function lexical(
for (const { n, name, path, body } of symbolDocs) {
// Name and path are short identifiers → plain idf-weighted overlap; the body
// is length-normalized via BM25 so long definitions don't win on bulk.
+ const factor = testFactor(n.path);
const total =
(score(q, name, idf) * 3 +
score(q, path, idf) * 2 +
bm25(q, body, idf, bodyLen(body), avgBodyLen)) *
- testFactor(n.path);
+ factor;
if (total > 0) {
lex.set(n.id, total);
maxLex = Math.max(maxLex, total);
+ if (fileComplement) {
+ rawLexicalById.set(n.id, total);
+ matchedTermsById.set(
+ n.id,
+ matchedLexicalTerms(q, name, path, body),
+ );
+ if (n.kind !== "file")
+ matchedStrongTermsById.set(n.id, matchedStrongTerms(q, name));
+ }
}
}
@@ -675,29 +930,126 @@ function lexical(
const candidates = new Set<string>(lex.keys());
for (const [id, p] of pr) if (p >= RESCUE_FLOOR) candidates.add(id);
+ const singleCandidates: Array<{
+ id: string;
+ n: NodeV1;
+ lexical: number;
+ graph: number;
+ rankFactor: number;
+ baseline: number;
+ }> = [];
for (const id of candidates) {
const n = byId.get(id);
if (!n) continue;
- const lexN = maxLex > 0 ? (lex.get(id) ?? 0) / maxLex : 0;
+ const lexical = maxLex > 0 ? (lex.get(id) ?? 0) / maxLex : 0;
+ const graphScore = pr.get(id) ?? 0;
+ const rankFactor = testFactor(n.path);
// Apply the test penalty after normalization too. Applying it only to the
// raw lexical score is not enough: if a test is still the strongest raw
// match, dividing by maxLex restores it to 1.0 and erases the de-rank.
- const blended = (lexN + GRAPH_WEIGHT * (pr.get(id) ?? 0)) * testFactor(n.path);
- if (blended <= 0) continue;
- const hit: AskHit = {
- kind: "symbol",
- title: `${n.name} · ${n.kind}`,
- // A file node points at the whole file (locator, no span) so `--source`
- // never inlines an entire file; symbol nodes keep their exact span.
- pointer: n.kind === "file" ? n.path : `${n.path}:${n.span}`,
- snippet: n.summary?.split("\n")[0].trim() ?? n.signature ?? "",
- score: blended,
- };
- 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);
+ const baseline = (lexical + GRAPH_WEIGHT * graphScore) * rankFactor;
+ if (baseline <= 0) continue;
+ singleCandidates.push({ id, n, lexical, graph: graphScore, rankFactor, baseline });
+ }
+
+ const candidateById = fileComplement
+ ? new Map(singleCandidates.map((candidate) => [candidate.id, candidate]))
+ : undefined;
+ const rankedFiles = fileComplement
+ ? rankFilesBounded(
+ singleCandidates.map((candidate): FileRankCandidate => {
+ const rawLexical = rawLexicalById.get(candidate.id) ?? 0;
+ return {
+ id: candidate.id,
+ file: candidate.n.path,
+ kind: candidate.n.kind === "file" ? "file" : "symbol",
+ rawLexical,
+ lexical: candidate.lexical,
+ graph: candidate.graph,
+ rankFactor: candidate.rankFactor,
+ baselineScore: candidate.baseline,
+ baselineTieKey: symbolTitle(candidate.id),
+ matchedTerms: matchedTermsById.get(candidate.id) ?? new Set<string>(),
+ matchedStrongTerms:
+ matchedStrongTermsById.get(candidate.id) ?? new Set<string>(),
+ eligible: candidate.n.kind !== "file" && rawLexical > 0,
+ spanStart: spanStart(candidate.n.span),
+ };
+ }),
+ fileQueryWeights,
+ )
+ : undefined;
+
+ if (needsFileQueues && rankedFiles) {
+ const baselineCandidateOrder = (
+ a: (typeof singleCandidates)[number],
+ b: (typeof singleCandidates)[number],
+ ): number =>
+ b.baseline - a.baseline ||
+ `${a.n.name} · ${a.n.kind}`.localeCompare(`${b.n.name} · ${b.n.kind}`);
+ let baselineTopCandidate = singleCandidates[0];
+ for (const candidate of singleCandidates.slice(1))
+ if (baselineTopCandidate && baselineCandidateOrder(candidate, baselineTopCandidate) < 0)
+ baselineTopCandidate = candidate;
+ const baselineCandidatesToBuild = includeRankingMetadata
+ ? [...singleCandidates].sort(baselineCandidateOrder)
+ : baselineTopCandidate
+ ? [baselineTopCandidate]
+ : [];
+ for (const candidate of baselineCandidatesToBuild) {
+ const hit = makeSymbolHit(candidate.id, candidate.baseline);
+ if (hit) {
+ baselineSymbolHits.push(hit);
+ baselineHitById.set(candidate.id, hit);
+ }
+ }
+ for (const file of rankedFiles) {
+ const materializeFileQueue = (): AskHit[] => file.queue.flatMap((member, index) => {
+ if (index > 0) {
+ const baselineHit = baselineHitById.get(member.id);
+ if (baselineHit) return [baselineHit];
+ }
+ const hit = makeSymbolHit(
+ member.id,
+ index === 0 ? file.score : member.baselineScore,
+ );
+ return hit ? [hit] : [];
+ });
+ const materializeBaselineQueue = (): AskHit[] => file.queue.flatMap((member) => {
+ const hit = makeSymbolHit(member.id, member.baselineScore);
+ return hit ? [hit] : [];
+ });
+ const hits = includeRankingMetadata
+ ? materializeFileQueue()
+ : (() => {
+ const leader = file.queue[0];
+ if (!leader) return [];
+ const hit = makeSymbolHit(leader.id, file.score);
+ return hit ? [hit] : [];
+ })();
+ if (hits.length === 0) continue;
+ const group: AskRankingGroup = {
+ key: `file:${file.file}`,
+ hits,
+ coverage: file.unionCoverage,
+ coverageStrong: file.unionStrongCoverage,
+ };
+ fileQueueHitsByGroup.set(group.key, materializeFileQueue);
+ baselineQueueHitsByGroup.set(group.key, materializeBaselineQueue);
+ fileGroups.push(group);
+ symbolHits.push(hits[0]);
+ }
+ } else if (rankedFiles) {
+ for (const file of rankedFiles) {
+ const candidate = candidateById?.get(file.representative.id);
+ const hit = candidate ? makeSymbolHit(candidate.id, file.score) : null;
+ if (hit) symbolHits.push(hit);
+ }
+ } else {
+ for (const candidate of singleCandidates) {
+ const hit = makeSymbolHit(candidate.id, candidate.baseline);
+ if (hit) symbolHits.push(hit);
+ }
}
}
@@ -708,20 +1060,114 @@ function lexical(
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,
+ const baselineScored = needsFileQueues
+ ? [...conceptHits, ...baselineSymbolHits].sort(
+ (a, b) => b.score - a.score || a.title.localeCompare(b.title),
)
: scored;
+ const conceptGroups: AskRankingGroup[] = conceptHits.map((hit, index) => ({
+ key: selectionGroupOf.get(hit) ?? `concept:${index}`,
+ hits: [hit],
+ coverage: matchedOf.get(hit) ?? 0,
+ coverageStrong: matchedStrongOf.get(hit) ?? 0,
+ }));
+ const unlockedGroups = [...conceptGroups, ...fileGroups].sort(
+ (a, b) =>
+ b.hits[0].score - a.hits[0].score ||
+ a.hits[0].title.localeCompare(b.hits[0].title),
+ );
+ const sameHit = (a: AskHit, b: AskHit): boolean =>
+ a.kind === b.kind && a.pointer === b.pointer && a.title === b.title;
+ let projectedGroups = unlockedGroups;
+ let lockedGroupKey: string | undefined;
+ if (fileTopLock && fileFirst && baselineScored[0]) {
+ const baselineTop = baselineScored[0];
+ const key = selectionGroupOf.get(baselineTop) ?? "locked:top";
+ lockedGroupKey = key;
+ const existing = unlockedGroups.find((group) => group.key === key);
+ const baselineQueue = includeRankingMetadata || limit > unlockedGroups.length
+ ? baselineQueueHitsByGroup.get(key)?.() ?? baselineScored.filter(
+ (hit) => (selectionGroupOf.get(hit) ?? "") === key,
+ )
+ : [];
+ const locked: AskRankingGroup = existing
+ ? {
+ ...existing,
+ hits: [
+ baselineTop,
+ ...baselineQueue.filter((hit) => !sameHit(hit, baselineTop)),
+ ],
+ }
+ : {
+ key,
+ hits: baselineQueue.length ? baselineQueue : [baselineTop],
+ coverage: matchedOf.get(baselineTop) ?? 0,
+ coverageStrong: matchedStrongOf.get(baselineTop) ?? 0,
+ };
+ projectedGroups = [
+ locked,
+ ...unlockedGroups.filter((group) => group.key !== key),
+ ];
+ }
+
+ // Ranking always sees the complete candidate universe, but a normal bounded
+ // request usually needs only one leader per file. Materialize secondary span
+ // queues only when the requested output can actually reach a second round.
+ if (
+ fileTopLock &&
+ fileFirst &&
+ !includeRankingMetadata &&
+ limit > projectedGroups.length
+ ) {
+ projectedGroups = projectedGroups.map((group) => {
+ if (group.key === lockedGroupKey) return group;
+ const materialize = fileQueueHitsByGroup.get(group.key);
+ return materialize ? { ...group, hits: materialize() } : group;
+ });
+ }
+
+ // File-aware ranking feeds latent groups to the existing file-first frontier.
+ // Leaders are listed first so every file/concept emits once before any
+ // secondary span; each group's remaining queue retains baseline order.
+ const selected = fileTopLock && fileFirst
+ ? roundRobinQueues(projectedGroups.map((group) => group.hits), limit)
+ : fileFirst
+ ? fileFirstRoundRobin(
+ scored.map((hit, index) => ({
+ group: selectionGroupOf.get(hit) ?? `ungrouped:${index}`,
+ value: hit,
+ })),
+ limit,
+ )
+ : scored;
const top = selected[0] ?? scored[0];
+ if (fileTopLock && top?.scope && scopeMeta) {
+ scopeMeta = {
+ federated: [...new Set([top.scope, ...scopeMeta.federated])],
+ alsoMatched: scopeMeta.alsoMatched.filter((match) => match.scope !== top.scope),
+ };
+ }
+ const ranking = includeRankingMetadata && needsFileQueues
+ ? {
+ groups: unlockedGroups.slice(0, limit).map((group) => ({
+ ...group,
+ hits: group.hits.slice(0, limit),
+ baselineHits: baselineScored
+ .filter((hit) => selectionGroupOf.get(hit) === group.key)
+ .slice(0, limit),
+ })),
+ baseline: baselineScored.slice(0, limit).map((hit, index) => ({
+ group: selectionGroupOf.get(hit) ?? `ungrouped:${index}`,
+ hit,
+ })),
+ baselineCoverage: baselineScored[0]
+ ? matchedOf.get(baselineScored[0]) ?? 0
+ : undefined,
+ baselineCoverageStrong: baselineScored[0]
+ ? matchedStrongOf.get(baselineScored[0]) ?? 0
+ : undefined,
+ }
+ : undefined;
return {
query,
mode: scored.length ? "lexical" : "empty",
@@ -729,6 +1175,7 @@ function lexical(
scopes: scopeMeta,
coverage: top && q.size > 0 ? matchedOf.get(top) ?? 0 : undefined,
coverageStrong: top && q.size > 0 ? matchedStrongOf.get(top) ?? 0 : undefined,
+ ...(ranking ? { ranking } : {}),
// 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
@@ -763,6 +1210,14 @@ export interface AskOptions {
* ranking stage (currently workspace federation). Direct callers should
* leave this unset. */
fileFirst?: boolean;
+ /** @internal Bounded file scoring control. */
+ fileComplement?: boolean;
+ /** @internal Exact baseline top-hit lock. Requires bounded file
+ * scoring and composes it with the file-first frontier. */
+ fileTopLock?: boolean;
+ /** @internal Return latent file queues and the exact baseline list so a
+ * workspace parent can fuse files before projecting spans. */
+ includeRankingMetadata?: boolean;
}
/** Parse a `path:Lx-Ly` pointer into its parts, or null if it isn't one
@@ -846,6 +1301,12 @@ export function ask(dir: string, query: string, opts: AskOptions = {}): AskResul
const limit = opts.limit ?? 8;
const corpus = loadCorpus(outDir);
const graphRank = opts.graphRank ?? true;
+ const fileFirst = opts.fileFirst ?? true;
+ // The production path uses bounded file scoring plus an exact baseline top lock.
+ // Internal/raw callers can still request the baseline by disabling
+ // file-first selection. A top lock is projected only on a file-first list.
+ const fileTopLock = opts.fileTopLock ?? fileFirst;
+ const fileComplement = (opts.fileComplement ?? false) || fileTopLock;
// Normalized ONCE, up front, and this value used everywhere below
// (validation, filtering, structural). `ask --in frontend/` must work exactly
// like `--in frontend` — `scopeLabel`/the footer's own `--in <scope>/`
@@ -863,7 +1324,17 @@ 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, opts.fileFirst ?? true);
+ result = lexical(
+ query,
+ corpus,
+ limit,
+ graphRank,
+ inPrefix,
+ fileFirst,
+ fileComplement,
+ fileTopLock,
+ opts.includeRankingMetadata ?? false,
+ );
// 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) {
@@ -871,10 +1342,33 @@ export function ask(dir: string, query: string, opts: AskOptions = {}): AskResul
}
}
} else {
- result = lexical(query, corpus, limit, graphRank, inPrefix, opts.fileFirst ?? true);
+ result = lexical(
+ query,
+ corpus,
+ limit,
+ graphRank,
+ inPrefix,
+ fileFirst,
+ fileComplement,
+ fileTopLock,
+ opts.includeRankingMetadata ?? false,
+ );
}
if (opts.source) {
inlineSource(root, result.hits, corpus.graph, opts.full ?? false);
+ if (result.ranking) {
+ const internalHits = [
+ ...result.ranking.groups.flatMap((group) => group.hits),
+ ...result.ranking.groups.flatMap((group) => group.baselineHits ?? []),
+ ...result.ranking.baseline.map((entry) => entry.hit),
+ ];
+ inlineSource(
+ root,
+ [...new Set(internalHits)],
+ corpus.graph,
+ opts.full ?? false,
+ );
+ }
// The pack is truly substitutive only in retriever mode (spans inlined), so
// the "vs reading whole files" estimate is only honest here.
result.saved = baselineFor(result.hits, corpus.graph);
diff --git a/src/ask/file-rank.ts b/src/ask/file-rank.ts
new file mode 100644
index 00000000..e7309723
--- /dev/null
+++ b/src/ask/file-rank.ts
@@ -0,0 +1,246 @@
+/**
+ * Pure bounded file ranking.
+ *
+ * Binary IDF coverage supplies a bounded residual to one raw-lexical anchor.
+ * Every other real candidate keeps its exact baseline score, and PageRank is
+ * never recomputed or amplified by a file-level multiplier.
+ */
+
+export interface FileRankCandidate {
+ id: string;
+ /** Exact repository-relative source path. */
+ file: string;
+ /** Residual module node, or an exact symbol span. */
+ kind: "file" | "symbol";
+ /** Existing raw lexical score, before the shared normalization denominator. */
+ rawLexical: number;
+ /** Existing normalized lexical component, expected in [0, 1]. */
+ lexical: number;
+ /** Existing normalized PPR component, expected in [0, 1]. */
+ graph: number;
+ /** Existing query-aware final multiplier (for example test de-ranking). */
+ rankFactor: number;
+ /** Exact current score, retained for every non-winning candidate. */
+ baselineScore: number;
+ /** Existing final-list tie key. When present, equal-score candidates keep
+ * the caller's baseline ordering before file-specific fallbacks apply. */
+ baselineTieKey?: string;
+ /** Exact query terms that the existing lexical scorer awarded to this node. */
+ matchedTerms: ReadonlySet<string>;
+ /** Query terms matched in the symbol NAME field only. File/residual nodes
+ * leave this empty so workspace strength gating cannot be cleared by a
+ * coincidental filename or body token. */
+ matchedStrongTerms?: ReadonlySet<string>;
+ /** Only real lexical symbol spans may donate complementary evidence. */
+ eligible: boolean;
+ /** Deterministic anchor/queue tie-break inputs. */
+ emittedTokens?: number;
+ spanStart?: number;
+}
+
+export type FileRepresentativeReason =
+ | "pooled-anchor"
+ | "baseline-symbol"
+ | "baseline-residual";
+
+export interface RankedFile {
+ file: string;
+ /** Concrete existing node that owns the returned file score. */
+ representative: FileRankCandidate;
+ representativeReason: FileRepresentativeReason;
+ /** Raw-lexical symbol that alone may receive the bounded residual. */
+ lexicalAnchor?: FileRankCandidate;
+ /** Existing candidates in deterministic baseline order, representative first. */
+ queue: FileRankCandidate[];
+ unionCoverage: number;
+ unionStrongCoverage: number;
+ anchorCoverage: number;
+ /** A_F * (U_F - A_F) / U_F. */
+ boundedResidual: number;
+ pooledLexical: number;
+ lexicalDelta: number;
+ score: number;
+}
+
+function finitePositive(value: number): boolean {
+ return Number.isFinite(value) && value > 0;
+}
+
+function clamp01(value: number): number {
+ if (!Number.isFinite(value) || value <= 0) return 0;
+ return Math.min(1, value);
+}
+
+function tokenCost(candidate: FileRankCandidate): number {
+ return Number.isFinite(candidate.emittedTokens) && candidate.emittedTokens! >= 0
+ ? candidate.emittedTokens!
+ : Number.POSITIVE_INFINITY;
+}
+
+function startOf(candidate: FileRankCandidate): number {
+ return Number.isFinite(candidate.spanStart) && candidate.spanStart! >= 0
+ ? candidate.spanStart!
+ : Number.POSITIVE_INFINITY;
+}
+
+function coverage(
+ candidate: FileRankCandidate,
+ queryWeights: ReadonlyMap<string, number>,
+): number {
+ let share = 0;
+ for (const term of candidate.matchedTerms) {
+ const weight = queryWeights.get(term);
+ if (finitePositive(weight ?? 0)) share += weight!;
+ }
+ return clamp01(share);
+}
+
+function baselineOrder(a: FileRankCandidate, b: FileRankCandidate): number {
+ const scoreOrder = b.baselineScore - a.baselineScore;
+ if (scoreOrder !== 0) return scoreOrder;
+ if (a.baselineTieKey !== undefined && b.baselineTieKey !== undefined)
+ return a.baselineTieKey.localeCompare(b.baselineTieKey);
+ return (
+ b.rawLexical - a.rawLexical ||
+ tokenCost(a) - tokenCost(b) ||
+ startOf(a) - startOf(b) ||
+ a.id.localeCompare(b.id)
+ );
+}
+
+function lexicalAnchorOrder(
+ a: FileRankCandidate,
+ b: FileRankCandidate,
+ queryWeights: ReadonlyMap<string, number>,
+): number {
+ return (
+ b.rawLexical - a.rawLexical ||
+ coverage(b, queryWeights) - coverage(a, queryWeights) ||
+ tokenCost(a) - tokenCost(b) ||
+ startOf(a) - startOf(b) ||
+ a.id.localeCompare(b.id)
+ );
+}
+
+/**
+ * Rank exact files using the bounded anchor formula:
+ *
+ * a_F = argmax rawLexical among eligible lexical symbols
+ * A_F = coverage(a_F)
+ * U_F = union coverage of eligible lexical symbols
+ * r_F = A_F (U_F - A_F) / U_F
+ * P_F = d_a [ell_a + (1 - ell_a) r_F + 0.5 p_a]
+ * S_F = max(P_F, max_j baseline_j)
+ *
+ * The anchor is the only pooled candidate. Graph-only symbols, residual nodes,
+ * and all other lexical symbols remain exact baseline competitors.
+ */
+export function rankFilesBounded(
+ candidates: readonly FileRankCandidate[],
+ queryWeights: ReadonlyMap<string, number>,
+): RankedFile[] {
+ const groups = new Map<string, FileRankCandidate[]>();
+ for (const candidate of candidates) {
+ if (!candidate.file || !finitePositive(candidate.baselineScore)) continue;
+ const list = groups.get(candidate.file);
+ if (list) list.push(candidate);
+ else groups.set(candidate.file, [candidate]);
+ }
+
+ const ranked: RankedFile[] = [];
+ for (const [file, members] of groups) {
+ const donors = members.filter(
+ (candidate) =>
+ candidate.kind === "symbol" &&
+ candidate.eligible &&
+ finitePositive(candidate.rawLexical) &&
+ finitePositive(candidate.lexical),
+ );
+ donors.sort((a, b) => lexicalAnchorOrder(a, b, queryWeights));
+ const lexicalAnchor = donors[0];
+
+ let unionCoverage = 0;
+ let unionStrongCoverage = 0;
+ let anchorCoverage = 0;
+ let boundedResidual = 0;
+ let pooledLexical = lexicalAnchor ? clamp01(lexicalAnchor.lexical) : 0;
+
+ if (lexicalAnchor) {
+ const unionTerms = new Set<string>();
+ for (const donor of donors)
+ for (const term of donor.matchedTerms) unionTerms.add(term);
+ for (const term of unionTerms) {
+ const weight = queryWeights.get(term);
+ if (finitePositive(weight ?? 0)) unionCoverage += weight!;
+ }
+ unionCoverage = clamp01(unionCoverage);
+ const unionStrongTerms = new Set<string>();
+ for (const donor of donors)
+ for (const term of donor.matchedStrongTerms ?? []) unionStrongTerms.add(term);
+ for (const term of unionStrongTerms) {
+ const weight = queryWeights.get(term);
+ if (finitePositive(weight ?? 0)) unionStrongCoverage += weight!;
+ }
+ unionStrongCoverage = clamp01(unionStrongCoverage);
+ anchorCoverage = coverage(lexicalAnchor, queryWeights);
+ boundedResidual = unionCoverage > 0
+ ? clamp01(
+ anchorCoverage * Math.max(0, unionCoverage - anchorCoverage) /
+ unionCoverage,
+ )
+ : 0;
+ pooledLexical = clamp01(
+ lexicalAnchor.lexical +
+ (1 - clamp01(lexicalAnchor.lexical)) * boundedResidual,
+ );
+ }
+
+ const lexicalDelta = lexicalAnchor
+ ? Math.max(0, pooledLexical - clamp01(lexicalAnchor.lexical))
+ : 0;
+ const ordered = [...members].sort(baselineOrder);
+ const baselineRepresentative = ordered[0]!;
+ const pooledAnchorScore = lexicalAnchor
+ ? clamp01(lexicalAnchor.rankFactor) *
+ (pooledLexical + 0.5 * clamp01(lexicalAnchor.graph))
+ : 0;
+
+ const pooledWins = Boolean(
+ lexicalAnchor && pooledAnchorScore > baselineRepresentative.baselineScore,
+ );
+ const representative = pooledWins ? lexicalAnchor! : baselineRepresentative;
+ const score = pooledWins ? pooledAnchorScore : baselineRepresentative.baselineScore;
+ const representativeReason: FileRepresentativeReason = pooledWins
+ ? "pooled-anchor"
+ : representative.kind === "file"
+ ? "baseline-residual"
+ : "baseline-symbol";
+ const queue = [
+ representative,
+ ...ordered.filter((candidate) => candidate.id !== representative.id),
+ ];
+
+ ranked.push({
+ file,
+ representative,
+ representativeReason,
+ lexicalAnchor,
+ queue,
+ unionCoverage,
+ unionStrongCoverage,
+ anchorCoverage,
+ boundedResidual,
+ pooledLexical,
+ lexicalDelta,
+ score,
+ });
+ }
+
+ ranked.sort(
+ (a, b) =>
+ b.score - a.score ||
+ baselineOrder(a.representative, b.representative) ||
+ a.file.localeCompare(b.file),
+ );
+ return ranked;
+}
diff --git a/src/ask/file-selection.ts b/src/ask/file-selection.ts
index fbbe0031..7289b7e4 100644
--- a/src/ask/file-selection.ts
+++ b/src/ask/file-selection.ts
@@ -43,3 +43,29 @@ export function fileFirstRoundRobin<T>(
}
return out;
}
+
+/** Project already-grouped queues directly. Unlike {@link fileFirstRoundRobin}
+ * this does not flatten and rebuild a grouping map, so a file-aware ranker can
+ * stop as soon as `limit` hits without materializing every tail span twice. */
+export function roundRobinQueues<T>(
+ queues: readonly (readonly 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 out: T[] = [];
+ for (let depth = 0; out.length < cap; 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) break;
+ }
+ if (!added) break;
+ }
+ return out;
+}
diff --git a/src/ask/fuse.ts b/src/ask/fuse.ts
index fc0ca299..f00feb66 100644
--- a/src/ask/fuse.ts
+++ b/src/ask/fuse.ts
@@ -50,6 +50,18 @@ export interface ScopedDoc {
score: number;
}
+/** Components preserved until immediately before comparable-scope combination.
+ * Optional ranking experiments can adjust lexical evidence without having to
+ * reconstruct it from the already blended scalar score. */
+export interface ScopeRankCandidate extends ScopedDoc {
+ /** Repo-global-normalized lexical component. */
+ lexical: number;
+ /** Scope-local normalized PPR component. */
+ graph: number;
+ /** Query-aware final multiplier, such as test-file de-ranking. */
+ rankFactor: number;
+}
+
export interface FusionResult {
/** fused order, best first; carries per-doc scope label + fused score.
* Normalized so the top MULTI-scope fused doc is 1 — but the single-scoring-
@@ -278,6 +290,13 @@ export interface ScopeRankOps {
* graph blending. Use this for priors (such as test-file de-ranking) that
* normalization must not erase. */
rankFactor?(scope: string, id: string): number;
+ /** Optional candidate collapse after lexical + graph components are known
+ * but before comparable scopes are gated and combined. File-aware ranking uses this
+ * to supply exactly one real representative per file. The default path omits
+ * the hook and remains byte-identical. */
+ collapseCandidates?(
+ candidates: readonly ScopeRankCandidate[],
+ ): readonly ScopedDoc[];
}
/**
@@ -318,7 +337,7 @@ export function rankScopesAndFuse(
}
const alsoMatched: FusionResult["alsoMatched"] = [];
- const scoped: ScopedDoc[] = [];
+ const candidatesWithComponents: ScopeRankCandidate[] = [];
// Per-scope raw best, plus the best raw score anywhere in the repo. That
// repo-wide maximum is the shared denominator every scope normalizes by.
@@ -364,11 +383,29 @@ export function rankScopesAndFuse(
for (const [id, p] of pr) if (p >= rescueFloor) candidates.add(id);
for (const id of candidates) {
const lexN = globalMaxLex > 0 ? (lex.get(id) ?? 0) / globalMaxLex : 0;
- const blended = (lexN + graphWeight * (pr.get(id) ?? 0)) * (ops.rankFactor?.(scope, id) ?? 1);
- if (blended > 0) scoped.push({ id, scope, score: blended });
+ const graph = pr.get(id) ?? 0;
+ const rankFactor = ops.rankFactor?.(scope, id) ?? 1;
+ const blended = (lexN + graphWeight * graph) * rankFactor;
+ if (blended > 0) {
+ candidatesWithComponents.push({
+ id,
+ scope,
+ score: blended,
+ lexical: lexN,
+ graph,
+ rankFactor,
+ });
+ }
}
}
+ const scoped: ScopedDoc[] = ops.collapseCandidates
+ ? [...ops.collapseCandidates(candidatesWithComponents)]
+ : candidatesWithComponents.map((candidate) => ({
+ id: candidate.id,
+ scope: candidate.scope,
+ score: candidate.score,
+ }));
const combined = combineComparableScopes(scoped);
return {
ranked: combined.ranked,
diff --git a/test/ask-file-rank.test.ts b/test/ask-file-rank.test.ts
new file mode 100644
index 00000000..e884de8a
--- /dev/null
+++ b/test/ask-file-rank.test.ts
@@ -0,0 +1,280 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+ rankFilesBounded,
+ type FileRankCandidate,
+} from "../src/ask/file-rank.js";
+
+const weights = (...entries: Array<[string, number]>): Map<string, number> => new Map(entries);
+const matched = (...terms: string[]): Set<string> => new Set(terms);
+
+function candidate(
+ value: Partial<FileRankCandidate> & Pick<FileRankCandidate, "id" | "file">,
+): FileRankCandidate {
+ const lexical = value.lexical ?? 0;
+ const graph = value.graph ?? 0;
+ const rankFactor = value.rankFactor ?? 1;
+ return {
+ kind: "symbol",
+ rawLexical: value.rawLexical ?? lexical,
+ lexical,
+ graph,
+ rankFactor,
+ baselineScore: value.baselineScore ?? rankFactor * (lexical + 0.5 * graph),
+ matchedTerms: value.matchedTerms ?? new Set(),
+ eligible: value.eligible ?? lexical > 0,
+ ...value,
+ };
+}
+
+test("bounded residual pools one raw-lexical anchor and leaves every sibling queued at baseline", () => {
+ const candidates = [
+ candidate({
+ id: "anchor", file: "a.ts", rawLexical: 10, lexical: 0.4, graph: 0.2,
+ matchedTerms: matched("alpha"),
+ matchedStrongTerms: matched("alpha"),
+ }),
+ candidate({
+ id: "sibling", file: "a.ts", rawLexical: 8, lexical: 0.3, graph: 0.1,
+ matchedTerms: matched("beta"),
+ matchedStrongTerms: matched("beta"),
+ }),
+ candidate({
+ id: "singleton", file: "b.ts", rawLexical: 9, lexical: 0.9,
+ matchedTerms: matched("alpha", "beta"),
+ }),
+ ];
+
+ const ranked = rankFilesBounded(candidates, weights(["alpha", 0.4], ["beta", 0.6]));
+ const file = ranked.find((entry) => entry.file === "a.ts")!;
+ const singleton = ranked.find((entry) => entry.file === "b.ts")!;
+
+ assert.equal(file.lexicalAnchor?.id, "anchor");
+ assert.equal(file.anchorCoverage, 0.4);
+ assert.equal(file.unionCoverage, 1);
+ assert.equal(file.unionStrongCoverage, 1);
+ assert.ok(Math.abs(file.boundedResidual - 0.24) < 1e-12);
+ assert.ok(Math.abs(file.pooledLexical - 0.544) < 1e-12);
+ assert.ok(Math.abs(file.score - 0.644) < 1e-12);
+ assert.equal(file.representative.id, "anchor");
+ assert.equal(file.representativeReason, "pooled-anchor");
+ assert.equal(singleton.score, candidates[2].baselineScore);
+
+ assert.deepEqual(file.queue.map((candidate) => candidate.id), ["anchor", "sibling"]);
+});
+
+test("equal baseline scores preserve the caller's existing tie order", () => {
+ const [file] = rankFilesBounded([
+ candidate({
+ id: "raw-leader",
+ file: "a.ts",
+ rawLexical: 10,
+ lexical: 0.5,
+ baselineScore: 0.5,
+ baselineTieKey: "Zulu · function",
+ matchedTerms: matched("alpha"),
+ }),
+ candidate({
+ id: "baseline-leader",
+ file: "a.ts",
+ rawLexical: 5,
+ lexical: 0.5,
+ baselineScore: 0.5,
+ baselineTieKey: "Alpha · function",
+ matchedTerms: matched("alpha"),
+ }),
+ ], weights(["alpha", 1]));
+
+ assert.equal(file.representative.id, "baseline-leader");
+ assert.deepEqual(
+ file.queue.map((candidate) => candidate.id),
+ ["baseline-leader", "raw-leader"],
+ );
+});
+
+test("anchor coverage belongs to the raw-lexical anchor, not an independent coverage leader", () => {
+ const candidates = [
+ candidate({
+ id: "raw-anchor", file: "a.ts", rawLexical: 10, lexical: 0.5,
+ matchedTerms: matched("alpha"),
+ }),
+ candidate({
+ id: "coverage-leader", file: "a.ts", rawLexical: 9, lexical: 0.45,
+ matchedTerms: matched("beta", "gamma", "delta"),
+ }),
+ ];
+ const queryWeights = weights(
+ ["alpha", 0.25],
+ ["beta", 0.25],
+ ["gamma", 0.25],
+ ["delta", 0.25],
+ );
+
+ const [file] = rankFilesBounded(candidates, queryWeights);
+ assert.equal(file.lexicalAnchor?.id, "raw-anchor");
+ assert.equal(file.anchorCoverage, 0.25);
+ assert.equal(file.unionCoverage, 1);
+ assert.ok(Math.abs(file.boundedResidual - 0.1875) < 1e-12);
+ assert.ok(Math.abs(file.score - 0.59375) < 1e-12);
+});
+
+test("equal distributed evidence follows (m - 1) / m^2 and shrinks for large files", () => {
+ let previousResidual = Number.POSITIVE_INFINITY;
+ for (const count of [2, 3, 4, 8, 12, 20]) {
+ const queryWeights = new Map<string, number>();
+ const candidates: FileRankCandidate[] = [];
+ for (let index = 0; index < count; index++) {
+ const term = `t${index}`;
+ queryWeights.set(term, 1 / count);
+ candidates.push(candidate({
+ id: `n${String(index).padStart(2, "0")}`,
+ file: "monster.ts",
+ rawLexical: 1,
+ lexical: 0.1,
+ matchedTerms: matched(term),
+ }));
+ }
+
+ const [file] = rankFilesBounded(candidates, queryWeights);
+ const expected = (count - 1) / (count * count);
+ assert.ok(Math.abs(file.boundedResidual - expected) < 1e-12, `m=${count}`);
+ assert.ok(file.boundedResidual <= previousResidual, `m=${count} does not grow`);
+ assert.ok(Math.abs(file.pooledLexical - (0.1 + 0.9 * expected)) < 1e-12);
+ previousResidual = file.boundedResidual;
+ }
+});
+
+test("raw sibling magnitude cannot affect the bounded residual when term presence is unchanged", () => {
+ const make = (siblingRaw: number) => [
+ candidate({
+ id: "anchor", file: "a.ts", rawLexical: 10, lexical: 0.6,
+ matchedTerms: matched("alpha"),
+ }),
+ candidate({
+ id: "sibling", file: "a.ts", rawLexical: siblingRaw, lexical: 0.2,
+ matchedTerms: matched("beta"),
+ }),
+ ];
+ const queryWeights = weights(["alpha", 0.5], ["beta", 0.5]);
+ const [small] = rankFilesBounded(make(1), queryWeights);
+ const [large] = rankFilesBounded(make(9), queryWeights);
+
+ assert.equal(small.lexicalAnchor?.id, "anchor");
+ assert.equal(large.lexicalAnchor?.id, "anchor");
+ assert.equal(small.boundedResidual, large.boundedResidual);
+ assert.equal(small.score, large.score);
+});
+
+test("duplicate terms and singleton files are exact baseline identities", () => {
+ const candidates = [
+ candidate({ id: "a1", file: "a.ts", rawLexical: 8, lexical: 0.8, graph: 0.2, matchedTerms: matched("same") }),
+ candidate({ id: "a2", file: "a.ts", rawLexical: 6, lexical: 0.6, matchedTerms: matched("same") }),
+ candidate({ id: "b1", file: "b.ts", rawLexical: 5, lexical: 0.5, graph: 0.4, matchedTerms: matched("only") }),
+ ];
+ const ranked = rankFilesBounded(candidates, weights(["same", 0.5], ["only", 0.5]));
+ const repeated = ranked.find((file) => file.file === "a.ts")!;
+ const singleton = ranked.find((file) => file.file === "b.ts")!;
+
+ assert.equal(repeated.boundedResidual, 0);
+ assert.equal(repeated.lexicalDelta, 0);
+ assert.equal(repeated.score, candidates[0].baselineScore);
+ assert.equal(singleton.boundedResidual, 0);
+ assert.equal(singleton.score, candidates[2].baselineScore);
+});
+
+test("graph-only and residual winners stay exact baseline competitors", () => {
+ const candidates = [
+ candidate({ id: "lex-a", file: "a.ts", rawLexical: 4, lexical: 0.4, matchedTerms: matched("alpha") }),
+ candidate({ id: "lex-b", file: "a.ts", rawLexical: 3, lexical: 0.3, matchedTerms: matched("beta") }),
+ candidate({
+ id: "residual", file: "a.ts", kind: "file", rawLexical: 8, lexical: 0.8, graph: 0.2,
+ matchedTerms: matched("gamma"), eligible: false,
+ }),
+ candidate({
+ id: "graph", file: "graph.ts", rawLexical: 0, lexical: 0, graph: 0.7,
+ matchedTerms: new Set(), eligible: false,
+ }),
+ ];
+ const ranked = rankFilesBounded(
+ candidates,
+ weights(["alpha", 0.4], ["beta", 0.4], ["gamma", 0.2]),
+ );
+ const residual = ranked.find((file) => file.file === "a.ts")!;
+ const graph = ranked.find((file) => file.file === "graph.ts")!;
+
+ assert.equal(residual.unionCoverage, 0.8, "residual gamma does not enter union coverage");
+ assert.equal(residual.representative.id, "residual");
+ assert.equal(residual.representativeReason, "baseline-residual");
+ assert.equal(residual.score, candidates[2].baselineScore);
+ assert.equal(graph.boundedResidual, 0);
+ assert.equal(graph.representative.id, "graph");
+ assert.equal(graph.score, candidates[3].baselineScore);
+});
+
+test("a graph-only baseline leader receives no complement from lexical siblings", () => {
+ const candidates = [
+ candidate({ id: "lex-a", file: "a.ts", rawLexical: 4, lexical: 0.4, matchedTerms: matched("alpha") }),
+ candidate({ id: "lex-b", file: "a.ts", rawLexical: 3, lexical: 0.3, matchedTerms: matched("beta") }),
+ candidate({
+ id: "graph", file: "a.ts", rawLexical: 0, lexical: 0, graph: 1.6,
+ matchedTerms: new Set(), eligible: false,
+ }),
+ ];
+ const [file] = rankFilesBounded(candidates, weights(["alpha", 0.5], ["beta", 0.5]));
+
+ assert.equal(file.representative.id, "graph");
+ assert.equal(file.representativeReason, "baseline-symbol");
+ assert.equal(file.score, candidates[2].baselineScore);
+});
+
+test("one real node owns the score; max lexical and max PPR are never combined", () => {
+ const candidates = [
+ candidate({ id: "lex-head", file: "a.ts", rawLexical: 10, lexical: 1, graph: 0.05, matchedTerms: matched("alpha") }),
+ candidate({ id: "graph-head", file: "a.ts", rawLexical: 0.1, lexical: 0.01, graph: 1, matchedTerms: matched("beta") }),
+ ];
+ const [file] = rankFilesBounded(candidates, weights(["alpha", 0.5], ["beta", 0.5]));
+
+ assert.equal(file.representative.id, "lex-head");
+ assert.equal(file.lexicalDelta, 0, "a saturated anchor has no lexical headroom");
+ assert.equal(file.score, 1.025);
+ assert.ok(file.score < 1.5);
+});
+
+test("the existing test factor remains outside the complete pooled anchor score", () => {
+ const rankFactor = 0.35;
+ const candidates = [
+ candidate({
+ id: "test-a", file: "a.test.ts", rawLexical: 8, lexical: 0.8, graph: 0.2,
+ rankFactor, baselineScore: rankFactor * 0.9, matchedTerms: matched("alpha"),
+ }),
+ candidate({
+ id: "test-b", file: "a.test.ts", rawLexical: 4, lexical: 0.4,
+ rankFactor, baselineScore: rankFactor * 0.4, matchedTerms: matched("beta"),
+ }),
+ ];
+ const [file] = rankFilesBounded(candidates, weights(["alpha", 0.5], ["beta", 0.5]));
+
+ assert.ok(Math.abs(file.boundedResidual - 0.25) < 1e-12);
+ assert.ok(Math.abs(file.pooledLexical - 0.85) < 1e-12);
+ assert.ok(Math.abs(file.score - rankFactor * (0.85 + 0.1)) < 1e-12);
+});
+
+test("file ranks and queues are deterministic under candidate permutation", () => {
+ const candidates = [
+ candidate({ id: "b", file: "z.ts", rawLexical: 4, lexical: 0.4, matchedTerms: matched("alpha"), spanStart: 8 }),
+ candidate({ id: "a", file: "z.ts", rawLexical: 4, lexical: 0.4, matchedTerms: matched("beta"), spanStart: 2 }),
+ candidate({ id: "c", file: "a.ts", rawLexical: 4, lexical: 0.4, matchedTerms: matched("alpha"), spanStart: 1 }),
+ ];
+ const queryWeights = weights(["alpha", 0.5], ["beta", 0.5]);
+ const project = (input: FileRankCandidate[]) =>
+ rankFilesBounded(input, queryWeights).map((file) => ({
+ file: file.file,
+ representative: file.representative.id,
+ reason: file.representativeReason,
+ anchor: file.lexicalAnchor?.id,
+ queue: file.queue.map((candidate) => candidate.id),
+ score: file.score,
+ }));
+
+ assert.deepEqual(project(candidates), project([candidates[2], candidates[0], candidates[1]]));
+});
diff --git a/test/ask-file-selection.test.ts b/test/ask-file-selection.test.ts
index c9640bfd..bca985a8 100644
--- a/test/ask-file-selection.test.ts
+++ b/test/ask-file-selection.test.ts
@@ -1,6 +1,9 @@
import { test } from "node:test";
import assert from "node:assert/strict";
-import { fileFirstRoundRobin } from "../src/ask/file-selection.js";
+import {
+ fileFirstRoundRobin,
+ roundRobinQueues,
+} from "../src/ask/file-selection.js";
test("file-first projection preserves file order and emits leaders before sibling spans", () => {
const ranked = [
@@ -46,3 +49,20 @@ test("file-first projection treats concepts as singleton partitions", () => {
);
assert.deepEqual(projected.map((value) => value.id), ["A1", "concept", "B1", "A2"]);
});
+
+test("pre-grouped queue projection is equivalent and stops at the requested prefix", () => {
+ const queues = [
+ ["alpha-1", "alpha-2", "alpha-3"],
+ ["beta-1", "beta-2"],
+ ["gamma-1"],
+ ];
+ assert.deepEqual(
+ roundRobinQueues(queues),
+ ["alpha-1", "beta-1", "gamma-1", "alpha-2", "beta-2", "alpha-3"],
+ );
+ assert.deepEqual(
+ roundRobinQueues(queues, 4),
+ ["alpha-1", "beta-1", "gamma-1", "alpha-2"],
+ );
+ assert.deepEqual(roundRobinQueues(queues, 0), []);
+});
diff --git a/test/ask-fusion.test.ts b/test/ask-fusion.test.ts
index e9d15a6d..7ba9e1d1 100644
--- a/test/ask-fusion.test.ts
+++ b/test/ask-fusion.test.ts
@@ -161,6 +161,44 @@ test("rankScopesAndFuse: post-normalization rank factors cannot be erased by a t
);
});
+test("rankScopesAndFuse: optional collapse sees components and supplies the docs combined across scopes", () => {
+ let hookCalled = false;
+ const ops: ScopeRankOps = {
+ lex: () => new Map([["a1", 10], ["a2", 4]]),
+ walk: () => new Map([["a2", 0.8]]),
+ rankFactor: (_scope, id) => (id === "a2" ? 0.5 : 1),
+ collapseCandidates: (candidates) => {
+ hookCalled = true;
+ const byId = new Map(candidates.map((candidate) => [candidate.id, candidate]));
+ assert.deepEqual(
+ {
+ lexical: byId.get("a1")?.lexical,
+ graph: byId.get("a1")?.graph,
+ rankFactor: byId.get("a1")?.rankFactor,
+ baseline: byId.get("a1")?.score,
+ },
+ { lexical: 1, graph: 0, rankFactor: 1, baseline: 1 },
+ );
+ assert.deepEqual(
+ {
+ lexical: byId.get("a2")?.lexical,
+ graph: byId.get("a2")?.graph,
+ rankFactor: byId.get("a2")?.rankFactor,
+ baseline: byId.get("a2")?.score,
+ },
+ { lexical: 0.4, graph: 0.8, rankFactor: 0.5, baseline: 0.4 },
+ );
+ return [{ id: "file-a", scope: "app", score: 1.1 }];
+ },
+ };
+
+ const result = rankScopesAndFuse(["app"], ops, 0.5, 0.05);
+ assert.equal(hookCalled, true);
+ assert.deepEqual(result.ranked, [
+ { id: "file-a", scope: "app", score: 1.1 },
+ ]);
+});
+
test("rankScopesAndFuse: a scope whose best hit is a weak incidental match is excluded from ranked and reported in alsoMatched", () => {
// b's only hit scores 1 against a repo best of 10 — 0.1, well under the 0.25
// participation ratio. An incidental body-comment collision, same shape as
diff --git a/test/ask.test.ts b/test/ask.test.ts
index c661e996..9ef23ca5 100644
--- a/test/ask.test.ts
+++ b/test/ask.test.ts
@@ -242,6 +242,231 @@ test("ask file-first selection preserves baseline file order and delays sibling
}
});
+test("ask bounded file scoring rewards one anchor without moving singleton scores", async () => {
+ const dir = mkdtempSync(join(tmpdir(), "graft-ask-file-complement-"));
+ try {
+ writeFileSync(
+ join(dir, "a.ts"),
+ `export function amberShard(): string { return "amber"; }\n` +
+ `export function cobaltShard(): string { return "cobalt"; }\n`,
+ );
+ writeFileSync(
+ join(dir, "b.ts"),
+ `export function amberCobalt(): string { return "amber cobalt"; }\n`,
+ );
+ await buildGraph(dir);
+
+ const baseline = ask(dir, "amber cobalt", {
+ graphRank: false,
+ limit: 20,
+ fileFirst: false,
+ });
+ const bounded = ask(dir, "amber cobalt", {
+ graphRank: false,
+ limit: 20,
+ fileFirst: false,
+ fileComplement: true,
+ });
+ const byTitle = (hits: AskHit[]) => new Map(hits.map((hit) => [hit.title, hit]));
+ const baselineByTitle = byTitle(baseline.hits);
+ const boundedByTitle = byTitle(bounded.hits);
+
+ const siblingTitles = ["amberShard · function", "cobaltShard · function"];
+ const gains = siblingTitles.map((title) => ({
+ a0: baselineByTitle.get(title)?.score ?? 0,
+ bounded: boundedByTitle.get(title)?.score ?? 0,
+ }));
+ assert.equal(
+ gains.filter((gain) => gain.bounded > gain.a0).length,
+ 1,
+ "only the raw-lexical anchor receives the bounded residual",
+ );
+ assert.ok(
+ Math.max(...gains.map((gain) => gain.bounded)) > Math.max(...gains.map((gain) => gain.a0)),
+ );
+ assert.equal(
+ bounded.hits.filter((hit) => hit.pointer.startsWith("a.ts:")).length,
+ 1,
+ "true file candidates project one representative instead of retaining sibling documents",
+ );
+
+ const singletonBefore = baselineByTitle.get("amberCobalt · function")?.score;
+ const singletonAfter = boundedByTitle.get("amberCobalt · function")?.score;
+ assert.notEqual(singletonBefore, undefined);
+ assert.equal(singletonAfter, singletonBefore, "the unrelated singleton keeps its exact score");
+ assert.deepEqual(
+ bounded.hits.map((hit) => hit.score),
+ [...bounded.hits].map((hit) => hit.score).sort((a, b) => b - a),
+ "the adapter keeps score-sorted symbol selection when file-first is disabled",
+ );
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("default file-aware ranking locks the exact baseline top hit and delays secondary spans", async () => {
+ const dir = mkdtempSync(join(tmpdir(), "graft-ask-a5-lock-"));
+ try {
+ writeFileSync(
+ join(dir, "a.ts"),
+ `export function amberShard(): string { return "amber"; }\n` +
+ `export function cobaltShard(): string { return "cobalt"; }\n`,
+ );
+ writeFileSync(
+ join(dir, "b.ts"),
+ `export function amberCobalt(): string { return "amber cobalt"; }\n`,
+ );
+ await buildGraph(dir);
+ writeFileSync(
+ join(dir, "graft", "a5-concept.md"),
+ `---\nslug: a5-concept\nname: Aardvark amber cobalt\nsources:\n - path: b.ts\n---\n` +
+ `Amber cobalt behavior overview.\n`,
+ );
+
+ const baseline = ask(dir, "amber cobalt", {
+ graphRank: false,
+ limit: 20,
+ fileFirst: false,
+ });
+ const unlocked = ask(dir, "amber cobalt", {
+ graphRank: false,
+ limit: 20,
+ fileFirst: false,
+ fileComplement: true,
+ });
+ const a5 = ask(dir, "amber cobalt", {
+ graphRank: false,
+ limit: 20,
+ });
+ const explicitA5 = ask(dir, "amber cobalt", {
+ graphRank: false,
+ limit: 20,
+ fileFirst: true,
+ fileComplement: true,
+ fileTopLock: true,
+ });
+
+ assert.deepEqual(
+ a5,
+ explicitA5,
+ "the default route is exactly the explicit file-aware configuration",
+ );
+
+ assert.equal(baseline.hits[0].kind, "concept", "fixture gives the baseline a concept top hit");
+ assert.ok(
+ (unlocked.hits.find((hit) => hit.title === "amberShard · function")?.score ?? 0) >
+ (baseline.hits.find((hit) => hit.title === "amberShard · function")?.score ?? 0),
+ "the fixture exercises a live bounded file-score gain under the locked top",
+ );
+ assert.deepEqual(
+ {
+ kind: a5.hits[0].kind,
+ title: a5.hits[0].title,
+ pointer: a5.hits[0].pointer,
+ score: a5.hits[0].score,
+ },
+ {
+ kind: baseline.hits[0].kind,
+ title: baseline.hits[0].title,
+ pointer: baseline.hits[0].pointer,
+ score: baseline.hits[0].score,
+ },
+ "file-aware ranking preserves the exact baseline top candidate, including concepts",
+ );
+ assert.equal(a5.coverage, baseline.coverage);
+ assert.equal(a5.coverageStrong, baseline.coverageStrong);
+
+ const symbolFiles = a5.hits
+ .filter((hit) => hit.kind === "symbol")
+ .map((hit) => hit.pointer.split(":")[0]);
+ assert.deepEqual(symbolFiles.slice(0, 2), ["b.ts", "a.ts"]);
+ assert.ok(
+ symbolFiles.slice(2).includes("a.ts"),
+ "file-aware ranking retains a.ts's second exact span after both files emitted a leader",
+ );
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("bounded file grouping happens before the output limit", async () => {
+ const dir = mkdtempSync(join(tmpdir(), "graft-ask-file-before-limit-"));
+ try {
+ const crowded = Array.from(
+ { length: 45 },
+ (_, index) => `export function crowded${index}(): string { return "needle"; }\n`,
+ ).join("");
+ writeFileSync(join(dir, "crowded.ts"), crowded);
+ writeFileSync(
+ join(dir, "other.ts"),
+ `export function other(): string { return "needle"; }\n`,
+ );
+ await buildGraph(dir);
+
+ const result = ask(dir, "needle", {
+ graphRank: false,
+ limit: 2,
+ fileFirst: false,
+ fileComplement: true,
+ });
+ const files = result.hits.map((hit) => hit.pointer.split(":")[0]);
+
+ assert.equal(result.hits.length, 2);
+ assert.deepEqual(new Set(files), new Set(["crowded.ts", "other.ts"]));
+ const a5 = ask(dir, "needle", {
+ graphRank: false,
+ limit: 2,
+ fileComplement: true,
+ fileTopLock: true,
+ });
+ assert.deepEqual(
+ new Set(a5.hits.map((hit) => hit.pointer.split(":")[0])),
+ new Set(["crowded.ts", "other.ts"]),
+ "file-aware ranking groups the complete candidate set before applying the output limit",
+ );
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("ask bounded file scoring keeps the source first and preserves the outer test penalty", async () => {
+ const dir = mkdtempSync(join(tmpdir(), "graft-ask-file-complement-tests-"));
+ try {
+ writeFileSync(
+ join(dir, "download.ts"),
+ `export function downloadStallFallback(): string { return "download stall fallback"; }\n`,
+ );
+ writeFileSync(
+ join(dir, "download.test.ts"),
+ `export function testDownloadStall(): string { return "download stall"; }\n` +
+ `export function testDownloadFallback(): string { return "download fallback"; }\n`,
+ );
+ await buildGraph(dir);
+
+ const options = { graphRank: false, limit: 20, fileFirst: false } as const;
+ const baseline = ask(dir, "download stall fallback", {
+ ...options,
+ });
+ const bounded = ask(dir, "download stall fallback", {
+ ...options,
+ fileComplement: true,
+ });
+ const scoreByPointer = (hits: AskHit[]) => new Map(hits.map((hit) => [hit.pointer, hit.score]));
+ const baselineScores = scoreByPointer(baseline.hits);
+ const boundedScores = scoreByPointer(bounded.hits);
+
+ assert.match(bounded.hits[0].pointer, /^download\.ts:/, "the source definition remains first");
+ const testPointers = baseline.hits.filter((hit) => hit.pointer.startsWith("download.test.ts:")).map((hit) => hit.pointer);
+ assert.equal(
+ testPointers.filter((pointer) => (boundedScores.get(pointer) ?? 0) > (baselineScores.get(pointer) ?? 0)).length,
+ 1,
+ "only one test-file representative receives the discounted file score",
+ );
+ } 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 {
@@ -472,6 +697,101 @@ test("file-first selection preserves a multi-scope result's top relevance and fi
}
});
+test("bounded scoring applies at most one anchor boost per file before comparable-scope combination", async () => {
+ const dir = multiScopeFixture();
+ try {
+ await buildGraph(dir);
+ const query = "errors handled banner reported serialized logged";
+ const baseline = ask(dir, query, {
+ graphRank: false,
+ limit: 100,
+ fileFirst: false,
+ });
+ const bounded = ask(dir, query, {
+ graphRank: false,
+ limit: 100,
+ fileFirst: false,
+ fileComplement: true,
+ });
+ const before = new Map(baseline.hits.map((hit) => [hit.pointer, hit.score]));
+ const changedByFile = new Map<string, number>();
+ for (const hit of bounded.hits) {
+ const old = before.get(hit.pointer);
+ assert.notEqual(old, undefined, `${hit.pointer} remains the same concrete candidate`);
+ assert.ok(hit.score >= old!, "term pooling never lowers an existing candidate score");
+ if (hit.score > old!) {
+ const file = hit.pointer.split(":")[0];
+ changedByFile.set(file, (changedByFile.get(file) ?? 0) + 1);
+ }
+ }
+ assert.ok(changedByFile.size > 0, "the distributed fixture exercises bounded scoring");
+ for (const [file, count] of changedByFile)
+ assert.equal(count, 1, `${file} contributes exactly one boosted representative`);
+ const emittedFiles = bounded.hits.map((hit) => hit.pointer.split(":")[0]);
+ assert.equal(
+ new Set(emittedFiles).size,
+ emittedFiles.length,
+ "comparable-scope combination consumes one representative per exact file",
+ );
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("file-aware ranking keeps the exact multi-scope baseline top before queue projection", async () => {
+ const dir = multiScopeFixture();
+ try {
+ await buildGraph(dir);
+ const query = "errors handled banner reported serialized logged";
+ const baseline = ask(dir, query, {
+ graphRank: false,
+ limit: 100,
+ fileFirst: false,
+ });
+ const a5 = ask(dir, query, {
+ graphRank: false,
+ limit: 100,
+ fileComplement: true,
+ fileTopLock: true,
+ });
+
+ assert.deepEqual(
+ {
+ kind: a5.hits[0].kind,
+ title: a5.hits[0].title,
+ pointer: a5.hits[0].pointer,
+ score: a5.hits[0].score,
+ scope: a5.hits[0].scope,
+ },
+ {
+ kind: baseline.hits[0].kind,
+ title: baseline.hits[0].title,
+ pointer: baseline.hits[0].pointer,
+ score: baseline.hits[0].score,
+ scope: baseline.hits[0].scope,
+ },
+ );
+ assert.equal(a5.coverage, baseline.coverage);
+ assert.equal(a5.coverageStrong, baseline.coverageStrong);
+ assert.deepEqual(a5.scopes, baseline.scopes);
+
+ const symbolFiles = a5.hits
+ .filter((hit) => hit.kind === "symbol")
+ .map((hit) => hit.pointer.split(":")[0]);
+ const firstDuplicate = symbolFiles.findIndex(
+ (file, index) => symbolFiles.indexOf(file) !== index,
+ );
+ assert.ok(firstDuplicate > 0, "fixture retains at least one secondary span");
+ assert.equal(
+ new Set(symbolFiles.slice(0, firstDuplicate)).size,
+ firstDuplicate,
+ "no secondary span appears before every preceding file leader",
+ );
+ } 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