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
Rank bounded file evidence before span projection (#205)
Buseong Kimc6b5fe3559b7
diff --git a/src/ask/ask.ts b/src/ask/ask.tsindex 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 = {}): AskResulconst 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 = {}): AskResulif (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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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 asdiff --git a/test/ask.test.ts b/test/ask.test.tsindex 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