codesearch-mcp 0.2.2-alpha → 0.3.0-alpha

package/dist/src/project-scope.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveProjectNames = resolveProjectNames;
+exports.listAvailableNames = listAvailableNames;
+const MonorepoAwareDiscoveryService_1 = require("./services/MonorepoAwareDiscoveryService");
+function resolveProjectNames(names, units) {
+    const leaves = (0, MonorepoAwareDiscoveryService_1.toLeafProjects)(units);
+    const targets = [];
+    const seen = new Set();
+    const notFound = [];
+    for (const name of names) {
+        const unit = units.find(u => u.name === name);
+        const matches = unit ? (0, MonorepoAwareDiscoveryService_1.toLeafProjects)([unit]) : [leaves.find(l => l.name === name)].filter((p) => p !== undefined);
+        if (matches.length === 0) {
+            notFound.push(name);
+            continue;
+        }
+        for (const leaf of matches) {
+            if (seen.has(leaf.name))
+                continue;
+            seen.add(leaf.name);
+            targets.push(leaf);
+        }
+    }
+    return { targets, notFound };
+}
+function listAvailableNames(units) {
+    const names = [];
+    for (const unit of units) {
+        names.push(unit.name);
+        if (unit.children && unit.children.length > 0) {
+            for (const child of unit.children)
+                names.push(child.name);
+        }
+    }
+    return names;
+}

package/dist/src/project-selector.d.ts

@@ -2,6 +2,7 @@ export interface Project {
     name: string;
     path: string;
 }
+export declare function selectSingleProject(units: Project[]): Promise<string | undefined>;
 export declare class ProjectSelector {
     private readonly workspaceDir;
     private included;

package/dist/src/project-selector.js

@@ -34,9 +34,22 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ProjectSelector = void 0;
+exports.selectSingleProject = selectSingleProject;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const prompts_1 = require("@inquirer/prompts");
+async function selectSingleProject(units) {
+    try {
+        return await (0, prompts_1.select)({
+            message: 'Select a project to index',
+            choices: units.map(p => ({ name: p.name, value: p.name })),
+            pageSize: 15,
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
 async function loadLines(filePath) {
     try {
         const content = await fs.promises.readFile(filePath, 'utf-8');
@@ -48,9 +61,6 @@ async function loadLines(filePath) {
         return new Set();
     }
 }
-// Write the set if non-empty, otherwise delete the file so state is deterministic.
-// Previously .ragskip could be left stale (last entry removed but file not rewritten);
-// treating both files the same way avoids that drift.
 async function saveLines(filePath, names) {
     if (names.size > 0) {
         await fs.promises.writeFile(filePath, [...names].sort().join('\n') + '\n');
@@ -76,13 +86,10 @@ class ProjectSelector {
         await this.load();
         const newProjects = allProjects.filter(p => !this.included.has(p.name) && !this.skipped.has(p.name));
         const previouslySelected = allProjects.filter(p => this.included.has(p.name));
-        // Nothing new and something already selected — return silently
         if (newProjects.length === 0 && !forceSelect && previouslySelected.length > 0) {
             return previouslySelected;
         }
-        // No previous selection — treat as implicit --select so the user picks projects now
         const autoSelect = !forceSelect && previouslySelected.length === 0;
-        // In --select / auto-select mode show all non-skipped projects; otherwise only new ones
         const toShow = (forceSelect || autoSelect)
             ? allProjects.filter(p => !this.skipped.has(p.name))
             : newProjects;

package/dist/src/retrieval-eval.d.ts

@@ -0,0 +1,24 @@
+import type { EvalSuite, EvalCase, EvalCategory, CorpusRef, SearchFn, IndexInspector, IRetrievalEvaluator, EvalOutcome, StageName, PairedChange, CaseProgress, EvalResultFile, CompareResult } from './interfaces/IRetrievalEvaluator';
+export declare const STAGE_ORDER: readonly StageName[];
+export declare class EvalSuiteError extends Error {
+    readonly caseId: string | null;
+    readonly field: string | null;
+    constructor(message: string, caseId: string | null, field: string | null);
+}
+export declare function parseSuite(raw: unknown): EvalSuite;
+export declare function corporaOf(suites: EvalSuite[]): CorpusRef[];
+export declare function isUnderRoot(dir: string, root: string): boolean;
+export declare function checkCaseCorpora(cases: EvalCase[], projectDir: (project: string) => Promise<string | null>): Promise<void>;
+export declare function mergeSuites(suites: EvalSuite[]): EvalSuite;
+export declare function signTest(improved: number, worsened: number): number;
+export interface RankedCase {
+    id: string;
+    category: EvalCategory;
+    rank: number | null;
+}
+export declare function pairedChange(from: RankedCase[], to: RankedCase[]): PairedChange;
+export declare const LIVE_GROUP = "live";
+export declare class RetrievalEvaluator implements IRetrievalEvaluator {
+    evaluate(suite: EvalSuite, search: SearchFn, inspect: IndexInspector, onCase?: (p: CaseProgress) => void): Promise<EvalOutcome>;
+}
+export declare function compare(baseline: EvalResultFile, current: EvalResultFile): CompareResult;

package/dist/src/retrieval-eval.js

@@ -0,0 +1,500 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RetrievalEvaluator = exports.LIVE_GROUP = exports.EvalSuiteError = exports.STAGE_ORDER = void 0;
+exports.parseSuite = parseSuite;
+exports.corporaOf = corporaOf;
+exports.isUnderRoot = isUnderRoot;
+exports.checkCaseCorpora = checkCaseCorpora;
+exports.mergeSuites = mergeSuites;
+exports.signTest = signTest;
+exports.pairedChange = pairedChange;
+exports.compare = compare;
+const zod_1 = require("zod");
+const CATEGORIES = ['identifier', 'behaviour', 'concept'];
+exports.STAGE_ORDER = ['vector', 'reranked'];
+const STAGE_SOURCE = { reranked: 'vector' };
+const UNRANKED = 11;
+class EvalSuiteError extends Error {
+    caseId;
+    field;
+    constructor(message, caseId, field) {
+        super(message);
+        this.caseId = caseId;
+        this.field = field;
+        this.name = 'EvalSuiteError';
+    }
+}
+exports.EvalSuiteError = EvalSuiteError;
+const ExpectedAnswerSchema = zod_1.z.object({
+    file: zod_1.z.string().min(1),
+    owner: zod_1.z.string().min(1).optional(),
+});
+const CaseSchema = zod_1.z.object({
+    id: zod_1.z.string().min(1),
+    project: zod_1.z.string().min(1),
+    category: zod_1.z.enum(['identifier', 'behaviour', 'concept']),
+    query: zod_1.z.string().min(1),
+    expect: zod_1.z.array(ExpectedAnswerSchema).min(1),
+    threshold: zod_1.z.number().min(0).max(1).optional(),
+});
+const CorpusSchema = zod_1.z.object({
+    root: zod_1.z.string().min(1).refine(r => !r.startsWith('/') && !r.split('/').includes('..') && !r.endsWith('/'), 'must be a workspace-relative directory'),
+    commit: zod_1.z.string().regex(/^[0-9a-f]{40}$/, 'must be a full 40-hex commit SHA'),
+}).strict();
+const SuiteSchema = zod_1.z.object({
+    version: zod_1.z.literal(1),
+    corpus: CorpusSchema.optional(),
+    cases: zod_1.z.array(CaseSchema),
+});
+function rawCaseId(raw, index) {
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const cases = raw.cases;
+    if (!Array.isArray(cases))
+        return null;
+    const entry = cases[index];
+    if (typeof entry !== 'object' || entry === null)
+        return null;
+    const id = entry.id;
+    return typeof id === 'string' ? id : null;
+}
+function parseSuite(raw) {
+    const result = SuiteSchema.safeParse(raw);
+    if (!result.success) {
+        const issue = result.error.issues[0];
+        const pathParts = issue.path;
+        const caseIndex = typeof pathParts[1] === 'number' ? pathParts[1] : null;
+        const caseId = caseIndex !== null ? rawCaseId(raw, caseIndex) ?? `#${caseIndex}` : null;
+        const field = pathParts.length > 2 ? String(pathParts[pathParts.length - 1]) : pathParts.length === 2 ? 'id' : String(pathParts[0] ?? '');
+        throw new EvalSuiteError(`${issue.message} (case ${caseId ?? '?'}, field ${field})`, caseId, field);
+    }
+    const seen = new Set();
+    for (const c of result.data.cases) {
+        if (seen.has(c.id)) {
+            throw new EvalSuiteError(`Duplicate case id (case ${c.id}, field id)`, c.id, 'id');
+        }
+        seen.add(c.id);
+    }
+    const corpus = result.data.corpus?.root ?? null;
+    return { ...result.data, cases: result.data.cases.map(c => ({ ...c, corpus })) };
+}
+function corporaOf(suites) {
+    const byRoot = new Map();
+    for (const suite of suites) {
+        if (!suite.corpus)
+            continue;
+        const prev = byRoot.get(suite.corpus.root);
+        if (prev && prev.commit !== suite.corpus.commit) {
+            throw new EvalSuiteError(`Corpus ${suite.corpus.root} is declared at two commits: ${prev.commit} and ${suite.corpus.commit}`, null, 'corpus');
+        }
+        byRoot.set(suite.corpus.root, { root: suite.corpus.root, commit: suite.corpus.commit });
+    }
+    return [...byRoot.values()].sort((a, b) => (a.root < b.root ? -1 : a.root > b.root ? 1 : 0));
+}
+function isUnderRoot(dir, root) {
+    return dir === root || dir.startsWith(root + '/');
+}
+async function checkCaseCorpora(cases, projectDir) {
+    for (const c of cases) {
+        if (!c.corpus)
+            continue;
+        const dir = await projectDir(c.project);
+        if (dir === null) {
+            throw new EvalSuiteError(`Project ${c.project} is not indexed, so it cannot be checked against corpus ${c.corpus} (case ${c.id}, field project)`, c.id, 'project');
+        }
+        if (!isUnderRoot(dir, c.corpus)) {
+            throw new EvalSuiteError(`Project ${c.project} (${dir}) is outside corpus ${c.corpus} (case ${c.id}, field project)`, c.id, 'project');
+        }
+    }
+}
+function mergeSuites(suites) {
+    corporaOf(suites);
+    const cases = [];
+    const seen = new Set();
+    for (const suite of suites) {
+        for (const c of suite.cases) {
+            if (seen.has(c.id))
+                throw new EvalSuiteError(`Duplicate case id across suites (case ${c.id}, field id)`, c.id, 'id');
+            seen.add(c.id);
+            cases.push(c);
+        }
+    }
+    return { version: 1, cases };
+}
+function ownerMatches(ownerPath, expectedOwner) {
+    return ownerPath === expectedOwner || ownerPath.startsWith(expectedOwner + '.');
+}
+async function validateCase(c, inspect) {
+    const valid = [];
+    const invalid = [];
+    for (const expected of c.expect) {
+        const indexed = await inspect.isFileIndexed(c.project, expected.file);
+        if (!indexed) {
+            invalid.push(expected);
+            continue;
+        }
+        if (expected.owner) {
+            const owners = await inspect.ownerPathsOfFile(c.project, expected.file);
+            const found = owners.some(o => ownerMatches(o, expected.owner));
+            if (!found) {
+                invalid.push(expected);
+                continue;
+            }
+        }
+        valid.push(expected);
+    }
+    return { valid, invalid };
+}
+function rankOf(hits, valid) {
+    for (let i = 0; i < hits.length; i++) {
+        const hit = hits[i];
+        const matches = valid.some(e => hit.filePath === e.file && (!e.owner || (hit.ownerPath !== null && ownerMatches(hit.ownerPath, e.owner))));
+        if (matches)
+            return { rank: i + 1, matched: hit };
+    }
+    return { rank: null, matched: null };
+}
+function emptyMetrics() {
+    return { count: 0, hit1: 0, hit5: 0, mrr10: 0 };
+}
+function accumulate(ranks) {
+    const n = ranks.length;
+    if (n === 0)
+        return emptyMetrics();
+    let hit1 = 0, hit5 = 0, mrrSum = 0;
+    for (const rank of ranks) {
+        if (rank === 1)
+            hit1++;
+        if (rank !== null && rank <= 5)
+            hit5++;
+        mrrSum += rank !== null ? 1 / rank : 0;
+    }
+    return { count: n, hit1: hit1 / n, hit5: hit5 / n, mrr10: mrrSum / n };
+}
+function stageRank(c, stage) {
+    return c.stages[stage]?.rank ?? null;
+}
+function stageMetrics(cases, stage) {
+    const byCategory = {};
+    for (const category of CATEGORIES) {
+        const subset = cases.filter(c => c.category === category);
+        if (subset.length > 0)
+            byCategory[category] = accumulate(subset.map(c => stageRank(c, stage)));
+    }
+    return { overall: accumulate(cases.map(c => stageRank(c, stage))), byCategory };
+}
+function poolMetricsOf(cases) {
+    const count = cases.length;
+    return {
+        count,
+        recall: count === 0 ? 0 : cases.filter(c => c.poolRank !== null).length / count,
+        short: cases.filter(c => c.short).length,
+    };
+}
+function binomialCdfHalf(k, n) {
+    let pmf = Math.pow(0.5, n);
+    let cdf = pmf;
+    for (let i = 1; i <= k; i++) {
+        pmf = pmf * (n - i + 1) / i;
+        cdf += pmf;
+    }
+    return cdf;
+}
+function signTest(improved, worsened) {
+    const n = improved + worsened;
+    if (n === 0)
+        return 1;
+    return Math.min(1, 2 * binomialCdfHalf(Math.min(improved, worsened), n));
+}
+function pairCounts(pairs) {
+    let improved = 0, worsened = 0, unchanged = 0;
+    for (const p of pairs) {
+        if (p.to < p.from)
+            improved++;
+        else if (p.to > p.from)
+            worsened++;
+        else
+            unchanged++;
+    }
+    return { improved, worsened, unchanged, signTestP: signTest(improved, worsened) };
+}
+function pairedChange(from, to) {
+    const fromById = new Map(from.map(c => [c.id, c.rank]));
+    const pairs = [];
+    for (const c of to) {
+        if (!fromById.has(c.id))
+            continue;
+        pairs.push({ id: c.id, category: c.category, from: fromById.get(c.id) ?? UNRANKED, to: c.rank ?? UNRANKED });
+    }
+    const byCategory = {};
+    for (const category of CATEGORIES) {
+        const subset = pairs.filter(p => p.category === category);
+        if (subset.length > 0)
+            byCategory[category] = pairCounts(subset);
+    }
+    return {
+        overall: pairCounts(pairs),
+        byCategory,
+        hit5Gained: pairs.filter(p => p.from > 5 && p.to <= 5).map(p => p.id),
+        hit5Lost: pairs.filter(p => p.from <= 5 && p.to > 5).map(p => p.id),
+    };
+}
+function rankedCases(cases, stage) {
+    return cases.map(c => ({ id: c.id, category: c.category, rank: stageRank(c, stage) }));
+}
+function stageChangesOf(cases, stages) {
+    const changes = [];
+    for (const to of stages) {
+        const from = STAGE_SOURCE[to];
+        if (from && stages.includes(from)) {
+            changes.push({ from, to, change: pairedChange(rankedCases(cases, from), rankedCases(cases, to)) });
+        }
+    }
+    return changes;
+}
+function reportedStages(stages) {
+    return exports.STAGE_ORDER.filter(s => stages[s] !== undefined);
+}
+function sortedDistinct(values) {
+    return [...new Set(values)].sort((a, b) => {
+        if (a === b)
+            return 0;
+        if (a === null)
+            return -1;
+        if (b === null)
+            return 1;
+        return a < b ? -1 : 1;
+    });
+}
+exports.LIVE_GROUP = 'live';
+function runFigures(cases, stages, shortPool) {
+    const metrics = {};
+    for (const stage of stages)
+        metrics[stage] = stageMetrics(cases, stage);
+    const poolInput = (subset) => subset.map(c => ({ poolRank: c.poolRank, short: shortPool.get(c.id) }));
+    const poolByCategory = {};
+    for (const category of CATEGORIES) {
+        const subset = cases.filter(c => c.category === category);
+        if (subset.length > 0)
+            poolByCategory[category] = poolMetricsOf(poolInput(subset));
+    }
+    return {
+        cases: cases.length,
+        metrics,
+        pool: { overall: poolMetricsOf(poolInput(cases)), byCategory: poolByCategory },
+        stageChanges: stageChangesOf(cases, stages),
+    };
+}
+class RetrievalEvaluator {
+    async evaluate(suite, search, inspect, onCase) {
+        await checkCaseCorpora(suite.cases, p => inspect.projectDir(p));
+        const cases = [];
+        const shortPool = new Map();
+        const invalid = [];
+        const warnings = [];
+        const fetchLimits = [];
+        const efSearches = [];
+        const iterativeScans = [];
+        let stages = null;
+        const total = suite.cases.length;
+        for (const [i, c] of suite.cases.entries()) {
+            const started = Date.now();
+            const report = (result, inv) => onCase?.({ index: i + 1, total, id: c.id, result, invalid: inv, ms: Date.now() - started });
+            const { valid, invalid: invalidExpects } = await validateCase(c, inspect);
+            if (valid.length === 0) {
+                const inv = { id: c.id, reason: 'no valid expected answer', invalidExpects };
+                invalid.push(inv);
+                report(null, inv);
+                continue;
+            }
+            if (invalidExpects.length > 0) {
+                warnings.push({ id: c.id, droppedExpects: invalidExpects });
+            }
+            const hits = await search(c.query, 10, c.project, c.threshold);
+            const caseStages = reportedStages(hits.stages);
+            if (stages === null) {
+                stages = caseStages;
+            }
+            else if (caseStages.join(',') !== stages.join(',')) {
+                throw new Error(`Case ${c.id} reported stages [${caseStages.join(', ')}], but the run's stages are [${stages.join(', ')}]`);
+            }
+            const ranks = {};
+            for (const stage of caseStages)
+                ranks[stage] = rankOf(hits.stages[stage], valid);
+            const result = {
+                id: c.id, project: c.project, category: c.category, query: c.query,
+                stages: ranks,
+                poolRank: rankOf(hits.pool, valid).rank,
+                poolSize: hits.pool.length,
+                rerankFailed: hits.rerankFailed,
+                corpus: c.corpus ?? null,
+            };
+            cases.push(result);
+            shortPool.set(c.id, hits.pool.length < hits.fetchLimit);
+            fetchLimits.push(hits.fetchLimit);
+            efSearches.push(hits.indexParams.efSearch);
+            iterativeScans.push(hits.indexParams.iterativeScan);
+            report(result, null);
+        }
+        const runStages = stages ?? ['vector'];
+        const figures = (subset) => runFigures(subset, runStages, shortPool);
+        const byCorpus = {};
+        for (const key of [...new Set(cases.map(c => c.corpus ?? exports.LIVE_GROUP))].sort()) {
+            byCorpus[key] = figures(cases.filter(c => (c.corpus ?? exports.LIVE_GROUP) === key));
+        }
+        const all = figures(cases);
+        const observed = {
+            fetchLimit: sortedDistinct(fetchLimits),
+            efSearch: sortedDistinct(efSearches),
+            iterativeScan: sortedDistinct(iterativeScans),
+        };
+        return {
+            run: {
+                cases, invalid, warnings,
+                stages: runStages,
+                metrics: all.metrics,
+                pool: all.pool,
+                stageChanges: all.stageChanges,
+                rerankFailures: cases.filter(c => c.rerankFailed).length,
+                byCorpus,
+            },
+            observed,
+        };
+    }
+}
+exports.RetrievalEvaluator = RetrievalEvaluator;
+function metricDelta(baseline, current) {
+    return { baseline, current, delta: current - baseline };
+}
+function metricsDelta(baseline, current) {
+    return {
+        count: metricDelta(baseline.count, current.count),
+        hit1: metricDelta(baseline.hit1, current.hit1),
+        hit5: metricDelta(baseline.hit5, current.hit5),
+        mrr10: metricDelta(baseline.mrr10, current.mrr10),
+    };
+}
+function metricsDeltaByCategory(baseline, current) {
+    const out = {};
+    for (const category of CATEGORIES) {
+        const b = baseline[category];
+        const cur = current[category];
+        if (b && cur)
+            out[category] = metricsDelta(b, cur);
+    }
+    return out;
+}
+function poolValueDelta(baseline, current) {
+    return { baseline, current, delta: baseline === null ? null : current - baseline };
+}
+function poolDelta(baseline, current) {
+    return {
+        recall: poolValueDelta(baseline?.recall ?? null, current.recall),
+        short: poolValueDelta(baseline?.short ?? null, current.short),
+    };
+}
+function formatCondition(value) {
+    return Array.isArray(value) ? `[${value.map(v => (v === null ? 'not sent' : String(v))).join(', ')}]` : String(value);
+}
+function corpusWarningsOf(b, cur) {
+    const warnings = [];
+    if (b.corpora.length === 0)
+        warnings.push('baseline records no corpus');
+    const baseByRoot = new Map(b.corpora.map(c => [c.root, c]));
+    const curByRoot = new Map(cur.corpora.map(c => [c.root, c]));
+    for (const root of [...new Set([...baseByRoot.keys(), ...curByRoot.keys()])].sort()) {
+        const bc = baseByRoot.get(root), cc = curByRoot.get(root);
+        if (!bc) {
+            warnings.push(`corpus ${root} only in the current run`);
+            continue;
+        }
+        if (!cc) {
+            warnings.push(`corpus ${root} only in the baseline`);
+            continue;
+        }
+        if (bc.commit !== cc.commit) {
+            warnings.push(`corpus ${root} commit differs: baseline ${bc.commit} vs current ${cc.commit}`);
+        }
+        else if (bc.fingerprint !== cc.fingerprint) {
+            warnings.push(`corpus ${root} was searched on a different index build: fingerprint ${bc.fingerprint} (${bc.chunks} chunks) vs ${cc.fingerprint} (${cc.chunks} chunks)`);
+        }
+    }
+    const live = (side, n) => `${side} includes ${n} live-corpus case(s); differences may come from code changes`;
+    if (b.liveCases > 0)
+        warnings.push(live('baseline', b.liveCases));
+    if (cur.liveCases > 0)
+        warnings.push(live('current run', cur.liveCases));
+    return warnings;
+}
+function conditionWarningsOf(baseline, current) {
+    const warnings = [];
+    const b = baseline.metadata, cur = current.metadata;
+    if (b.suiteHash !== cur.suiteHash) {
+        warnings.push(`suite differs: baseline ${b.suiteHash} vs current ${cur.suiteHash}`);
+    }
+    if (b.embeddingModel !== cur.embeddingModel) {
+        warnings.push(`embedding model differs: baseline ${b.embeddingModel} vs current ${cur.embeddingModel}`);
+    }
+    if (b.rerankerModel !== cur.rerankerModel) {
+        warnings.push(`reranker differs: baseline ${b.rerankerModel ?? 'none'} vs current ${cur.rerankerModel ?? 'none'}`);
+    }
+    if (!b.conditions)
+        warnings.push('baseline records no search conditions');
+    if (!cur.conditions)
+        warnings.push('current run records no search conditions');
+    if (b.conditions && cur.conditions) {
+        const bc = b.conditions;
+        const cc = cur.conditions;
+        for (const key of [...new Set([...Object.keys(bc), ...Object.keys(cc)])]) {
+            if (!(key in bc))
+                warnings.push(`search condition ${key} recorded only by the current run (${formatCondition(cc[key])})`);
+            else if (!(key in cc))
+                warnings.push(`search condition ${key} recorded only by the baseline (${formatCondition(bc[key])})`);
+            else if (JSON.stringify(bc[key]) !== JSON.stringify(cc[key])) {
+                warnings.push(`${key} differs: baseline ${formatCondition(bc[key])} vs current ${formatCondition(cc[key])}`);
+            }
+        }
+    }
+    warnings.push(...corpusWarningsOf(b, cur));
+    if (baseline.run.rerankFailures > 0)
+        warnings.push(`baseline has ${baseline.run.rerankFailures} rerank failure(s)`);
+    if (current.run.rerankFailures > 0)
+        warnings.push(`current run has ${current.run.rerankFailures} rerank failure(s)`);
+    return warnings;
+}
+function compare(baseline, current) {
+    const stages = [];
+    for (const stage of current.run.stages) {
+        const b = baseline.run.metrics[stage];
+        const cur = current.run.metrics[stage];
+        if (!baseline.run.stages.includes(stage) || !b || !cur)
+            continue;
+        stages.push({
+            stage,
+            overall: metricsDelta(b.overall, cur.overall),
+            byCategory: metricsDeltaByCategory(b.byCategory, cur.byCategory),
+            change: pairedChange(rankedCases(baseline.run.cases, stage), rankedCases(current.run.cases, stage)),
+        });
+    }
+    const unmatchedStages = [
+        ...baseline.run.stages.filter(s => !current.run.stages.includes(s)).map(stage => ({ stage, side: 'baseline' })),
+        ...current.run.stages.filter(s => !baseline.run.stages.includes(s)).map(stage => ({ stage, side: 'current' })),
+    ];
+    const basePool = baseline.legacy ? null : baseline.run.pool;
+    const poolByCategory = {};
+    for (const category of CATEGORIES) {
+        const cur = current.run.pool.byCategory[category];
+        if (!cur)
+            continue;
+        if (basePool === null)
+            poolByCategory[category] = poolDelta(null, cur);
+        else if (basePool.byCategory[category])
+            poolByCategory[category] = poolDelta(basePool.byCategory[category], cur);
+    }
+    return {
+        stages,
+        unmatchedStages,
+        pool: { overall: poolDelta(basePool?.overall ?? null, current.run.pool.overall), byCategory: poolByCategory },
+        conditionWarnings: conditionWarningsOf(baseline, current),
+    };
+}

package/dist/src/search/result-shaping.d.ts

@@ -0,0 +1,4 @@
+export declare const DEFAULT_PER_FILE = 2;
+export declare function limitPerFile<T extends {
+    filePath: string;
+}>(ranked: T[], limit: number, perFile: number): T[];

package/dist/src/search/result-shaping.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PER_FILE = void 0;
+exports.limitPerFile = limitPerFile;
+exports.DEFAULT_PER_FILE = 2;
+function limitPerFile(ranked, limit, perFile) {
+    const taken = [];
+    const perFileCount = new Map();
+    for (const entry of ranked) {
+        if (taken.length >= limit)
+            break;
+        const count = perFileCount.get(entry.filePath) ?? 0;
+        if (count >= perFile)
+            continue;
+        perFileCount.set(entry.filePath, count + 1);
+        taken.push(entry);
+    }
+    return taken;
+}