@crvouga/atlas 0.8.0 → 0.10.0

package/dist/reports/src/test-catalog.js

@@ -0,0 +1,655 @@
+import { checkSlots } from './evidence-view.js';
+import { combineEvidence, emptyCounts, slotKey, specPath as normalSpecPath } from './layer-merge.js';
+import { RecordedSpecs } from './recorded-specs.js';
+/** The version of the documents this module writes (`TestCatalog`, `TestHistoryDocument`, `RunList`, `RunDetail`). Only optional fields are added within it. */
+export const TEST_CATALOG_VERSION = 1;
+/** Recorded results kept per test, newest first. Older ones are counted in no statistic. */
+export const HISTORY_PER_TEST = 100;
+const FAILURE_RANK = { passed: 0, 'not-run': 1, running: 2, failed: 3 };
+/** How tests are ordered. */
+export const TEST_SORTS = ['spec', 'title', 'recent', 'slowest', 'failures', 'flaky', 'runs'];
+/** The run a layer belongs to: its run URL, else `branch@sha`, else `local`. Layers with the same key are one run. */
+export function runKey(layer) {
+    if (layer.runUrl)
+        return layer.runUrl;
+    if (layer.branch || layer.sha)
+        return `${layer.branch ?? ''}@${layer.sha ?? ''}`;
+    return 'local';
+}
+function shortDetail(detail) {
+    return detail.length > 500 ? `${detail.slice(0, 497)}...` : detail;
+}
+function completed(status) {
+    return status === 'passed' || status === 'failed';
+}
+function entryOf(layer, row, backend) {
+    return materialize({ o: originOf(layer, backend), s: row.status, d: row.durationMs, k: row.kind, t: row.detail, e: row.evidence });
+}
+function originOf(layer, backend) {
+    const parameters = Object.keys(layer.parameters).sort().map(key => `${key}=${layer.parameters[key]}`).join('\u0002');
+    return {
+        at: layer.recordedAtMs, environment: layer.environment, producer: layer.producer, parameters: layer.parameters,
+        branch: layer.branch, sha: layer.sha, runUrl: layer.runUrl, run: runKey(layer), layer: layer.id, backend,
+        place: `${layer.producer}\u0001${layer.environment ?? ''}\u0001${parameters}`,
+    };
+}
+function materialize(held) {
+    const { o } = held;
+    return {
+        at: o.at, status: held.s, durationMs: held.d, environment: o.environment, producer: o.producer, kind: held.k, parameters: o.parameters,
+        branch: o.branch, sha: o.sha, runUrl: o.runUrl, run: o.run, layer: o.layer, backend: o.backend, detail: shortDetail(held.t),
+        ...(held.e ? { evidence: held.e } : {}),
+    };
+}
+/** Newest first; at the same time the more severe, then the larger layer id, so the order is total. */
+function newer(a, b) {
+    return b.o.at - a.o.at || FAILURE_RANK[b.s] - FAILURE_RANK[a.s] || (a.o.layer < b.o.layer ? 1 : a.o.layer > b.o.layer ? -1 : a.o.place < b.o.place ? 1 : a.o.place > b.o.place ? -1 : a.k < b.k ? 1 : a.k > b.k ? -1 : 0);
+}
+/** Whether `next` is a run's better last word on a result than `prior`: completed beats unfinished, then newer, then more severe. */
+function laterInRun(next, prior) {
+    if (completed(next.s) !== completed(prior.s))
+        return completed(next.s);
+    return newer(next, prior) < 0;
+}
+/**
+ * Every recorded result of every test (the newest `HISTORY_PER_TEST` per test, leaving out `running` progress) and the
+ * runs they came from. A run's results are read from that history, so memory follows the number of tests and not the age
+ * of the project: a run older than a test's last hundred results no longer lists that test. Add each layer once with
+ * `add`; the order layers arrive in does not change what it holds. It never decides a status.
+ *
+ * @example
+ * ```ts
+ * const history = new TestHistory();
+ * for (const { layer, rows } of layers) history.add(layer, rows, specs, layer.backend);
+ * const catalog = testCatalog(catalogModel(layers, { history }));
+ * ```
+ */
+export class TestHistory {
+    #bySlot = new Map();
+    #idents = new Map();
+    #runs = new Map();
+    #specs = new RecordedSpecs();
+    #seen = new Set();
+    #rev = 0;
+    #cells = null;
+    /** Changes each time a layer is added. */
+    get rev() {
+        return this.#rev;
+    }
+    /** The specs the added layers recorded. */
+    get specs() {
+        return this.#specs;
+    }
+    /** How many layers were added. */
+    get layers() {
+        return this.#seen.size;
+    }
+    /** Takes in one layer: its header, its rows, the specs it recorded and the backend it was read from. A layer id already added is ignored. */
+    add(layer, rows, specs = [], backend = layer.backend) {
+        if (this.#seen.has(layer.id))
+            return;
+        this.#seen.add(layer.id);
+        this.#rev += 1;
+        this.#specs.add(specs, layer.recordedAtMs);
+        const key = runKey(layer);
+        let run = this.#runs.get(key);
+        if (!run) {
+            run = { key, runUrl: layer.runUrl, branch: layer.branch, sha: layer.sha, start: layer.recordedAtMs, end: layer.recordedAtMs, first: layer.id, producers: new Set(), environments: new Set(), layers: 0 };
+            this.#runs.set(key, run);
+        }
+        // A run is told by its first layer (by time, then id), whatever order its layers arrive in.
+        if (layer.recordedAtMs < run.start || (layer.recordedAtMs === run.start && layer.id < run.first)) {
+            run.start = layer.recordedAtMs;
+            run.first = layer.id;
+            run.branch = layer.branch;
+            run.sha = layer.sha;
+        }
+        run.end = Math.max(run.end, layer.recordedAtMs);
+        run.producers.add(layer.producer);
+        if (layer.environment)
+            run.environments.add(layer.environment);
+        run.layers += 1;
+        const origin = originOf(layer, backend);
+        for (const row of rows) {
+            // "Still running" is progress, not history: a test running now shows it as its current outcome.
+            if (row.status === 'running')
+                continue;
+            const slot = slotKey(row.specPath ?? '', row.id);
+            let ident = this.#idents.get(slot);
+            if (!ident)
+                this.#idents.set(slot, ident = { slot, id: row.id, title: row.title, titledAt: layer.recordedAtMs, specPath: row.specPath });
+            else if (layer.recordedAtMs > ident.titledAt || (layer.recordedAtMs === ident.titledAt && row.title > ident.title)) {
+                ident.title = row.title;
+                ident.titledAt = layer.recordedAtMs;
+            }
+            this.#remember(slot, { o: origin, s: row.status, d: row.durationMs, k: row.kind, t: row.detail, e: row.evidence });
+        }
+    }
+    /** Sorted insert, newest first; past the bound, the oldest is dropped. */
+    #remember(slot, entry) {
+        const list = this.#bySlot.get(slot);
+        if (!list) {
+            this.#bySlot.set(slot, [entry]);
+            return;
+        }
+        let lo = 0, hi = list.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            if (newer(list[mid], entry) <= 0)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        if (lo >= HISTORY_PER_TEST)
+            return;
+        list.splice(lo, 0, entry);
+        if (list.length > HISTORY_PER_TEST)
+            list.pop();
+    }
+    /** The recorded results of one test (by `TestSummary.key`), newest first. Empty when none. */
+    of(key) {
+        return (this.#bySlot.get(key) ?? []).map(materialize);
+    }
+    /** How many runs it knows of. */
+    get runCount() {
+        return this.#runs.size;
+    }
+    /**
+     * Each run's last word on each test, producer, environment, parameter set and kind it recorded, read from history in
+     * one pass and kept until a layer arrives.
+     */
+    #runCells() {
+        if (this.#cells?.rev === this.#rev)
+            return this.#cells.byRun;
+        const byRun = new Map();
+        for (const [slot, list] of this.#bySlot) {
+            const i = this.#idents.get(slot);
+            const best = new Map();
+            for (const held of list) {
+                const cell = `${held.o.run}\u0001${held.o.place}\u0001${held.k}`;
+                const prior = best.get(cell);
+                if (!prior || laterInRun(held, prior))
+                    best.set(cell, held);
+            }
+            for (const r of best.values()) {
+                const cells = byRun.get(r.o.run);
+                if (cells)
+                    cells.push({ i, r });
+                else
+                    byRun.set(r.o.run, [{ i, r }]);
+            }
+        }
+        this.#cells = { rev: this.#rev, byRun };
+        return byRun;
+    }
+    /** Every run, newest first. */
+    runs() {
+        const cells = this.#runCells();
+        return [...this.#runs.values()].map(run => runSummary(run, cells.get(run.key) ?? [])).sort((a, b) => b.endedAtMs - a.endedAtMs || (a.key < b.key ? -1 : 1));
+    }
+    /** One run and its results (failed first, then by spec and title), or null. */
+    run(key) {
+        const run = this.#runs.get(key);
+        if (!run)
+            return null;
+        const cells = this.#runCells().get(key) ?? [];
+        const results = cells.map(({ i, r }) => ({
+            key: i.slot, id: i.id, title: i.title, specPath: i.specPath, environment: r.o.environment, producer: r.o.producer,
+            status: r.s, durationMs: r.d, at: r.o.at, layer: r.o.layer, detail: shortDetail(r.t),
+        }));
+        results.sort((a, b) => FAILURE_RANK[b.status] - FAILURE_RANK[a.status] || compareText(a.specPath ?? '', b.specPath ?? '') || compareText(a.title, b.title) || compareText(a.environment ?? '', b.environment ?? '') || compareText(a.producer, b.producer) || compareText(a.key, b.key));
+        return { run: runSummary(run, cells), results };
+    }
+    /** The keys of the tests one run recorded. */
+    testsIn(key) {
+        return new Set((this.#runCells().get(key) ?? []).map(cell => cell.i.slot));
+    }
+}
+function runSummary(run, cells) {
+    const counts = emptyCounts();
+    const tests = new Set();
+    let total = 0, measured = false;
+    const failed = [];
+    for (const cell of cells) {
+        counts[cell.r.s] += 1;
+        tests.add(cell.i.slot);
+        if (cell.r.d !== null) {
+            total += cell.r.d;
+            measured = true;
+        }
+        if (cell.r.s === 'failed')
+            failed.push(cell);
+    }
+    failed.sort((a, b) => compareText(a.i.slot, b.i.slot) || compareText(a.r.o.place, b.r.o.place) || compareText(a.r.k, b.r.k));
+    const failing = failed.slice(0, 20).map(cell => ({ key: cell.i.slot, title: cell.i.title, environment: cell.r.o.environment, detail: (cell.r.t.split('\n')[0] ?? '').slice(0, 500) }));
+    return {
+        key: run.key, runUrl: run.runUrl, branch: run.branch, sha: run.sha,
+        startedAtMs: run.start, endedAtMs: run.end, spanMs: run.end - run.start,
+        producers: [...run.producers].sort(), environments: [...run.environments].sort(),
+        layers: run.layers, tests: tests.size, counts, totalDurationMs: measured ? total : null, failing,
+    };
+}
+function compareText(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** Durations of a list of numbers (ms), or null when empty. `lastMs` is the first value, so give them newest first. */
+export function durationStats(values) {
+    if (!values.length)
+        return null;
+    const sorted = [...values].sort((a, b) => a - b);
+    const total = sorted.reduce((sum, value) => sum + value, 0);
+    const at = (q) => sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil(q * sorted.length) - 1))];
+    return { count: sorted.length, totalMs: total, avgMs: Math.round(total / sorted.length), p50Ms: at(0.5), p95Ms: at(0.95), minMs: sorted[0], maxMs: sorted.at(-1), lastMs: values[0] };
+}
+/** The spec a path names: the recorded one, or one derived from the path (`specs/<domain>/<name>.<ext>`). */
+export function catalogSpec(path, known) {
+    if (!path)
+        return null;
+    const entry = known(path);
+    const parts = normalSpecPath(path).split('/');
+    const folder = parts.length > 2 && parts[0] === 'specs' ? parts[1] : parts.length > 1 ? parts.at(-2) : '';
+    const base = (parts.at(-1) ?? path).replace(/\.[^.]+$/, '').replace(/[-_]+/g, ' ');
+    return {
+        path: entry?.path ?? normalSpecPath(path),
+        title: entry?.title || (base ? base[0].toUpperCase() + base.slice(1) : path),
+        domain: entry?.domain || folder,
+        kind: entry?.kind || (/\.([^./]+)$/.exec(path)?.[1] ?? 'unknown'),
+    };
+}
+function statsOf(history, outcomes, tags, labels) {
+    // Without history, the current results are all there is.
+    const entries = history.length ? history : outcomes;
+    let passed = 0, failed = 0, firstSeenMs = null, lastSeenMs = null, lastPassedAtMs = null, lastFailedAtMs = null;
+    const durations = [];
+    const runs = new Set();
+    const branches = [];
+    const bySha = new Map();
+    const sequences = new Map();
+    for (const entry of entries) {
+        if (entry.status === 'passed') {
+            passed += 1;
+            lastPassedAtMs ??= entry.at;
+        }
+        if (entry.status === 'failed') {
+            failed += 1;
+            lastFailedAtMs ??= entry.at;
+        }
+        lastSeenMs ??= entry.at;
+        firstSeenMs = entry.at;
+        if (entry.durationMs !== null && completed(entry.status))
+            durations.push(entry.durationMs);
+        runs.add(entry.run);
+        if (entry.branch && !branches.includes(entry.branch) && branches.length < 10)
+            branches.push(entry.branch);
+        if (completed(entry.status)) {
+            const place = `${entry.producer}|${entry.environment ?? ''}|${JSON.stringify(entry.parameters)}`;
+            if (entry.sha) {
+                const sha = `${place}|${entry.sha}`;
+                const seen = bySha.get(sha) ?? new Set();
+                seen.add(entry.status);
+                bySha.set(sha, seen);
+            }
+            const sequence = sequences.get(place) ?? [];
+            sequence.push(entry.status);
+            sequences.set(place, sequence);
+        }
+    }
+    let flips = 0;
+    for (const sequence of sequences.values())
+        for (let i = 1; i < sequence.length; i++)
+            if (sequence[i] !== sequence[i - 1])
+                flips += 1;
+    const mixedSha = [...bySha.values()].some(statuses => statuses.size > 1);
+    const retried = outcomes.some(outcome => outcome.status === 'passed' && (outcome.evidence?.attempts ?? 0) > 1);
+    const said = tags.some(tag => tag.toLowerCase() === 'flaky') || labels.flaky === 'true';
+    const flakyReason = mixedSha ? 'Passed and failed on the same commit' : retried ? 'Passed only after a retry' : said ? 'Marked flaky by its producer' : '';
+    return {
+        results: entries.length, passed, failed, passRate: passed + failed ? passed / (passed + failed) : null,
+        flaky: flakyReason !== '', flakyReason, flips, durations: durationStats(durations),
+        firstSeenMs, lastSeenMs, lastPassedAtMs, lastFailedAtMs, runs: runs.size, branches,
+    };
+}
+function outcomeOf(result) {
+    return entryOf(result.layer, result.row, result.layer.backend);
+}
+function summaryOf(slot, history, known) {
+    const outcomes = slot.outcomes.map(outcomeOf);
+    const tags = new Set();
+    const labels = {};
+    let attachments = 0, steps = 0, attempts = 0;
+    const roles = new Set();
+    for (const outcome of outcomes) {
+        const evidence = outcome.evidence;
+        if (!evidence)
+            continue;
+        for (const tag of evidence.tags)
+            tags.add(tag);
+        Object.assign(labels, evidence.labels);
+        attachments += evidence.attachments;
+        steps += evidence.steps;
+        attempts = Math.max(attempts, evidence.attempts);
+        for (const role of evidence.roles)
+            roles.add(role);
+    }
+    const tagList = [...tags].sort();
+    return {
+        key: slot.key,
+        id: slot.id,
+        title: slot.title,
+        specPath: slot.specPath,
+        spec: catalogSpec(slot.specPath, known),
+        status: slot.status,
+        environments: [...new Set(outcomes.map(outcome => outcome.environment).filter((env) => !!env))].sort(),
+        producers: [...new Set(outcomes.map(outcome => outcome.producer))].sort(),
+        outcomes,
+        stats: statsOf(history?.of(slot.key) ?? [], outcomes, tagList, labels),
+        tags: tagList,
+        labels,
+        evidence: { attachments, steps, attempts, roles: [...roles].sort() },
+        lastRecordedAtMs: slot.latestAtMs,
+        live: slot.live,
+    };
+}
+/** The lowercase text a search matches a test against: title, id, spec, domain, tags, labels, environments and producers. */
+export function haystackOf(test) {
+    return [
+        test.title, test.id, test.specPath ?? '', test.spec?.title ?? '', test.spec?.domain ?? '', ...test.tags,
+        ...Object.entries(test.labels).flatMap(([key, value]) => [key, value]), ...test.environments, ...test.producers,
+    ].join('\n').toLowerCase();
+}
+/** A test's worst current outcome on one environment (`(none)` for results that named none), or its own status when it has no result there. */
+function statusOn(test, environment) {
+    let status = null;
+    for (const outcome of test.outcomes) {
+        if ((outcome.environment ?? '(none)') !== environment)
+            continue;
+        if (status === null || FAILURE_RANK[outcome.status] > FAILURE_RANK[status])
+            status = outcome.status;
+    }
+    return status ?? test.status;
+}
+function group(name, tests, environment = null) {
+    const counts = emptyCounts();
+    const averages = [];
+    for (const test of tests) {
+        counts[environment === null ? test.status : statusOn(test, environment)] += 1;
+        if (test.stats.durations)
+            averages.push(test.stats.durations.avgMs);
+    }
+    return { name, tests: tests.length, counts, avgMs: averages.length ? Math.round(averages.reduce((a, b) => a + b, 0) / averages.length) : null };
+}
+function groupsBy(tests, keys, byEnvironment = false) {
+    const groups = new Map();
+    for (const test of tests)
+        for (const key of keys(test)) {
+            const list = groups.get(key);
+            if (list)
+                list.push(test);
+            else
+                groups.set(key, [test]);
+        }
+    return [...groups].map(([name, list]) => group(name, list, byEnvironment ? name : null)).sort((a, b) => b.tests - a.tests || compareText(a.name, b.name));
+}
+function facet(tests, keys) {
+    const counts = new Map();
+    for (const test of tests)
+        for (const key of new Set(keys(test)))
+            counts.set(key, (counts.get(key) ?? 0) + 1);
+    return [...counts].map(([value, count]) => ({ value, count })).sort((a, b) => b.count - a.count || compareText(a.value, b.value));
+}
+function ref(test, value) {
+    return { key: test.key, title: test.title, specPath: test.specPath, status: test.status, value };
+}
+/**
+ * Builds the tests of a report from its winners (`layers`, as the effective report holds them: each layer with the rows
+ * that win) and, when given, a history. The model is what `testCatalog` and `testHistory` query; build it once per
+ * version and reuse it.
+ */
+export function catalogModel(layers, sources = {}) {
+    const history = sources.history ?? null;
+    const recorded = new RecordedSpecs();
+    if (history)
+        recorded.add(history.specs.entries(), 0);
+    if (sources.specs)
+        recorded.add(sources.specs, 1);
+    const known = (path) => recorded.get(path);
+    const combined = combineEvidence({ specs: [], sha: null, changedFiles: [] }, layers);
+    const slots = checkSlots(combined.unassigned);
+    const tests = slots.map(slot => summaryOf(slot, history, known));
+    const byKey = new Map(tests.map(test => [test.key, test]));
+    const haystacks = new Map(tests.map(test => [test.key, haystackOf(test)]));
+    const counts = emptyCounts();
+    for (const test of tests)
+        counts[test.status] += 1;
+    const averages = tests.flatMap(test => (test.stats.durations ? [test.stats.durations.avgMs] : []));
+    const lastRecordedAtMs = tests.length ? Math.max(...tests.map(test => test.lastRecordedAtMs)) : null;
+    const summary = {
+        tests: tests.length,
+        counts,
+        outcomes: tests.reduce((sum, test) => sum + test.outcomes.length, 0),
+        flaky: tests.filter(test => test.stats.flaky).length,
+        durations: durationStats(averages),
+        measured: averages.length,
+        withAttachments: tests.filter(test => test.evidence.attachments > 0).length,
+        // An environment counts how its own results went, so a failure on one does not show on another.
+        environments: groupsBy(tests, test => test.environments.length ? test.environments : ['(none)'], true),
+        producers: groupsBy(tests, test => test.producers),
+        domains: groupsBy(tests, test => [test.spec?.domain || '(no spec)']),
+        slowest: tests.filter(test => test.stats.durations).sort((a, b) => b.stats.durations.avgMs - a.stats.durations.avgMs || compareText(a.key, b.key)).slice(0, 10).map(test => ref(test, test.stats.durations.avgMs)),
+        flakiest: tests.filter(test => test.stats.flaky).sort((a, b) => b.stats.flips - a.stats.flips || compareText(a.key, b.key)).slice(0, 10).map(test => ref(test, test.stats.flips)),
+        failing: tests.filter(test => test.status === 'failed').sort((a, b) => b.lastRecordedAtMs - a.lastRecordedAtMs || compareText(a.key, b.key)).slice(0, 50).map(test => ref(test, test.stats.failed)),
+        runs: history?.runCount ?? new Set(tests.flatMap(test => test.outcomes.map(outcome => outcome.run))).size,
+        lastRecordedAtMs,
+        history: history !== null,
+    };
+    const specGroups = new Map();
+    for (const test of tests)
+        if (test.spec) {
+            const list = specGroups.get(test.spec.path);
+            if (list)
+                list.push(test);
+            else
+                specGroups.set(test.spec.path, [test]);
+        }
+    const labelKeys = new Set(tests.flatMap(test => Object.keys(test.labels)));
+    const facets = {
+        statuses: facet(tests, test => [test.status, ...(test.stats.flaky ? ['flaky'] : [])]),
+        environments: facet(tests, test => test.environments),
+        producers: facet(tests, test => test.producers),
+        domains: facet(tests, test => [test.spec?.domain || '(no spec)']),
+        specs: [...specGroups].map(([, list]) => { const g = group(list[0].spec.path, list); return { ...list[0].spec, tests: g.tests, counts: g.counts }; }).sort((a, b) => compareText(a.domain, b.domain) || compareText(a.title, b.title)),
+        tags: facet(tests, test => test.tags),
+        branches: facet(tests, test => test.stats.branches),
+        labels: Object.fromEntries([...labelKeys].sort().map(key => [key, facet(tests, test => (test.labels[key] === undefined ? [] : [test.labels[key]]))])),
+    };
+    return { version: sources.version ?? '', generatedAtMs: sources.now ?? Date.now(), tests, byKey, summary, facets, haystacks, history };
+}
+const SORTERS = {
+    spec: (a, b) => compareText(a.spec?.domain ?? '\uffff', b.spec?.domain ?? '\uffff') || compareText(a.spec?.title ?? '\uffff', b.spec?.title ?? '\uffff') || compareText(a.title, b.title),
+    title: (a, b) => compareText(a.title.toLowerCase(), b.title.toLowerCase()),
+    recent: (a, b) => b.lastRecordedAtMs - a.lastRecordedAtMs,
+    slowest: (a, b) => (b.stats.durations?.avgMs ?? -1) - (a.stats.durations?.avgMs ?? -1),
+    failures: (a, b) => FAILURE_RANK[b.status] - FAILURE_RANK[a.status] || b.stats.failed - a.stats.failed || (a.stats.passRate ?? 1) - (b.stats.passRate ?? 1),
+    flaky: (a, b) => Number(b.stats.flaky) - Number(a.stats.flaky) || b.stats.flips - a.stats.flips,
+    runs: (a, b) => b.stats.runs - a.stats.runs,
+};
+/** Whether one test matches a query (everything but sorting and paging). */
+export function matchesQuery(model, test, query, inRun) {
+    const words = (query.q ?? '').toLowerCase().split(/\s+/).filter(Boolean);
+    if (words.length) {
+        const hay = model.haystacks.get(test.key) ?? '';
+        if (!words.every(word => hay.includes(word)))
+            return false;
+    }
+    if (query.status?.length && !query.status.some(status => (status === 'flaky' ? test.stats.flaky : test.status === status)))
+        return false;
+    if (query.environment?.length && !query.environment.some(env => test.environments.includes(env) || (env === '(none)' && !test.environments.length)))
+        return false;
+    if (query.producer?.length && !query.producer.some(producer => test.producers.includes(producer)))
+        return false;
+    if (query.domain?.length && !query.domain.includes(test.spec?.domain || '(no spec)'))
+        return false;
+    if (query.spec?.length && !query.spec.some(path => test.specPath !== null && normalSpecPath(path) === test.specPath))
+        return false;
+    if (query.tag?.length && !query.tag.some(tag => test.tags.includes(tag)))
+        return false;
+    if (inRun && !inRun.has(test.key))
+        return false;
+    return true;
+}
+/** The catalog document for a query: the model's summary and facets, and the matching tests, sorted and paged. */
+export function testCatalog(model, query = {}) {
+    const inRun = query.run && model.history ? model.history.testsIn(query.run) : query.run ? new Set(model.tests.filter(test => test.outcomes.some(outcome => outcome.run === query.run)).map(test => test.key)) : null;
+    const matched = model.tests.filter(test => matchesQuery(model, test, query, inRun));
+    const sorter = SORTERS[query.sort ?? 'spec'] ?? SORTERS.spec;
+    matched.sort((a, b) => sorter(a, b) || compareText(a.key, b.key));
+    const offset = Math.max(0, Math.floor(query.offset ?? 0));
+    const limit = Math.min(20_000, Math.max(0, Math.floor(query.limit ?? 500)));
+    return { schemaVersion: TEST_CATALOG_VERSION, version: model.version, generatedAtMs: model.generatedAtMs, summary: model.summary, facets: model.facets, total: matched.length, offset, limit, tests: matched.slice(offset, offset + limit) };
+}
+/** One test and its recorded results, or null when the report has no test with that key. */
+export function testHistory(model, key) {
+    const test = model.byKey.get(key);
+    if (!test)
+        return null;
+    return { schemaVersion: TEST_CATALOG_VERSION, version: model.version, test, history: model.history?.of(key) ?? test.outcomes };
+}
+/** Every run the history knows of, newest first, `limit` at most (default 100). */
+export function runList(history, version, limit = 100) {
+    const runs = history.runs();
+    return { schemaVersion: TEST_CATALOG_VERSION, version, total: runs.length, runs: runs.slice(0, Math.max(0, limit)) };
+}
+/** One run with every result it recorded, or null when no run has that key. */
+export function runDetail(history, version, key) {
+    const found = history.run(key);
+    return found ? { schemaVersion: TEST_CATALOG_VERSION, version, ...found } : null;
+}
+/** Reads a `TestQuery` from URL search parameters: `q`, `sort`, `offset`, `limit`, `run`, and repeatable or comma-separated `status`, `environment`, `producer`, `domain`, `spec`, `tag`. */
+export function parseTestQuery(params) {
+    const many = (name) => params.getAll(name).flatMap(value => value.split(',')).map(value => value.trim()).filter(Boolean);
+    const number = (name) => { const value = params.get(name); return value !== null && /^\d+$/.test(value) ? Number(value) : undefined; };
+    const sort = params.get('sort');
+    const query = {};
+    const q = params.get('q');
+    if (q)
+        query.q = q;
+    for (const name of ['status', 'environment', 'producer', 'domain', 'spec', 'tag']) {
+        const values = many(name);
+        if (values.length)
+            query[name] = values;
+    }
+    const run = params.get('run');
+    if (run)
+        query.run = run;
+    if (sort && TEST_SORTS.includes(sort))
+        query.sort = sort;
+    const offset = number('offset');
+    const limit = number('limit');
+    if (offset !== undefined)
+        query.offset = offset;
+    if (limit !== undefined)
+        query.limit = limit;
+    return query;
+}
+/** A duration for a person: `850 ms`, `12.3 s`, `4m 05s`. */
+export function formatMs(ms) {
+    if (ms === null || ms === undefined)
+        return '—';
+    if (ms < 1000)
+        return `${Math.round(ms)} ms`;
+    if (ms < 60_000)
+        return `${(ms / 1000).toFixed(ms < 10_000 ? 2 : 1)} s`;
+    const seconds = Math.round(ms / 1000);
+    return `${Math.floor(seconds / 60)}m ${String(seconds % 60).padStart(2, '0')}s`;
+}
+const cell = (text) => text.replaceAll('|', '\\|').replaceAll('\n', ' ');
+const iso = (ms) => (ms === null ? '—' : new Date(ms).toISOString().replace('.000Z', 'Z'));
+const counted = (counts) => `${counts.passed} passed, ${counts.failed} failed, ${counts.running} running, ${counts['not-run']} not run`;
+/** The catalog as Markdown: the summary, insights, groups and the listed tests as a table. */
+export function catalogMarkdown(catalog) {
+    const { summary } = catalog;
+    const lines = [
+        '# Tests',
+        '',
+        `${summary.tests} tests (${counted(summary.counts)}); ${summary.flaky} flaky; ${summary.outcomes} current results across ${summary.environments.length} environments; ${summary.runs} runs. Last recorded ${iso(summary.lastRecordedAtMs)}.`,
+        summary.durations ? `Average test duration ${formatMs(summary.durations.avgMs)} (p50 ${formatMs(summary.durations.p50Ms)}, p95 ${formatMs(summary.durations.p95Ms)}) over ${summary.measured} measured tests.` : 'No test recorded a duration.',
+        '',
+        '## By environment',
+        '',
+        '| Environment | Tests | Passed | Failed | Running | Not run | Avg |',
+        '|---|---:|---:|---:|---:|---:|---:|',
+        ...summary.environments.map(g => `| ${cell(g.name)} | ${g.tests} | ${g.counts.passed} | ${g.counts.failed} | ${g.counts.running} | ${g.counts['not-run']} | ${formatMs(g.avgMs)} |`),
+        '',
+        '## By domain',
+        '',
+        '| Domain | Tests | Passed | Failed | Not run | Avg |',
+        '|---|---:|---:|---:|---:|---:|',
+        ...summary.domains.map(g => `| ${cell(g.name)} | ${g.tests} | ${g.counts.passed} | ${g.counts.failed} | ${g.counts['not-run']} | ${formatMs(g.avgMs)} |`),
+    ];
+    if (summary.failing.length)
+        lines.push('', '## Failing', '', ...summary.failing.map(t => `- ${cell(t.title)} (${t.specPath ?? 'no spec'})`));
+    if (summary.flakiest.length)
+        lines.push('', '## Flaky', '', ...summary.flakiest.map(t => `- ${cell(t.title)}: ${t.value} flips (${t.specPath ?? 'no spec'})`));
+    if (summary.slowest.length)
+        lines.push('', '## Slowest', '', ...summary.slowest.map(t => `- ${cell(t.title)}: ${formatMs(t.value)} average (${t.specPath ?? 'no spec'})`));
+    lines.push('', `## Tests ${catalog.offset + 1}–${catalog.offset + catalog.tests.length} of ${catalog.total}`, '', '| Status | Test | Spec | Environments | Avg | Pass rate | Runs | Last recorded |', '|---|---|---|---|---:|---:|---:|---|', ...catalog.tests.map(t => `| ${t.status}${t.stats.flaky ? ' (flaky)' : ''} | ${cell(t.title)} | ${cell(t.spec ? `${t.spec.title} (${t.spec.path})` : '—')} | ${cell(t.outcomes.map(o => `${o.environment ?? '—'}: ${o.status}`).join(', '))} | ${formatMs(t.stats.durations?.avgMs)} | ${t.stats.passRate === null ? '—' : `${Math.round(t.stats.passRate * 100)}%`} | ${t.stats.runs} | ${iso(t.lastRecordedAtMs)} |`));
+    if (catalog.total > catalog.offset + catalog.tests.length)
+        lines.push('', `More: ask again with offset=${catalog.offset + catalog.tests.length}.`);
+    return `${lines.join('\n')}\n`;
+}
+/** One test's history as Markdown. */
+export function historyMarkdown(document) {
+    const { test } = document;
+    const d = test.stats.durations;
+    return `${[
+        `# ${test.title}`,
+        '',
+        `- Status: ${test.status}${test.stats.flaky ? ` (flaky: ${test.stats.flakyReason})` : ''}`,
+        `- Spec: ${test.spec ? `${test.spec.title} (${test.spec.path}), domain ${test.spec.domain || '—'}` : 'none'}`,
+        `- Id: ${test.id}`,
+        `- Environments: ${test.environments.join(', ') || '—'}; producers: ${test.producers.join(', ')}`,
+        `- Results: ${test.stats.results} recorded, ${test.stats.passed} passed, ${test.stats.failed} failed${test.stats.passRate === null ? '' : `, pass rate ${Math.round(test.stats.passRate * 100)}%`}, in ${test.stats.runs} runs`,
+        `- Duration: ${d ? `avg ${formatMs(d.avgMs)}, p50 ${formatMs(d.p50Ms)}, p95 ${formatMs(d.p95Ms)}, min ${formatMs(d.minMs)}, max ${formatMs(d.maxMs)}, last ${formatMs(d.lastMs)}` : 'not measured'}`,
+        ...(test.tags.length ? [`- Tags: ${test.tags.join(', ')}`] : []),
+        ...(Object.keys(test.labels).length ? [`- Labels: ${Object.entries(test.labels).map(([k, v]) => `${k}=${v}`).join(', ')}`] : []),
+        `- Evidence: ${test.evidence.attachments} attachments${test.evidence.roles.length ? ` (${test.evidence.roles.join(', ')})` : ''}, ${test.evidence.steps} steps`,
+        '',
+        '## Current results',
+        '',
+        '| Environment | Producer | Status | Duration | Branch | Commit | Recorded | Run |',
+        '|---|---|---|---:|---|---|---|---|',
+        ...test.outcomes.map(o => `| ${o.environment ?? '—'} | ${cell(o.producer)} | ${o.status} | ${formatMs(o.durationMs)} | ${cell(o.branch ?? '—')} | ${o.sha?.slice(0, 10) ?? '—'} | ${iso(o.at)} | ${o.runUrl ?? '—'} |`),
+        '',
+        '## History',
+        '',
+        '| Recorded | Environment | Status | Duration | Branch | Commit | Detail |',
+        '|---|---|---|---:|---|---|---|',
+        ...document.history.map(e => `| ${iso(e.at)} | ${e.environment ?? '—'} | ${e.status} | ${formatMs(e.durationMs)} | ${cell(e.branch ?? '—')} | ${e.sha?.slice(0, 10) ?? '—'} | ${cell(e.detail.split('\n')[0] ?? '')} |`),
+    ].join('\n')}\n`;
+}
+/** The run list as Markdown. */
+export function runsMarkdown(list) {
+    return `${[
+        `# Runs (${list.runs.length} of ${list.total})`,
+        '',
+        '| Ended | Branch | Commit | Environments | Tests | Passed | Failed | Not run | Span | Run |',
+        '|---|---|---|---|---:|---:|---:|---:|---:|---|',
+        ...list.runs.map(r => `| ${iso(r.endedAtMs)} | ${cell(r.branch ?? '—')} | ${r.sha?.slice(0, 10) ?? '—'} | ${r.environments.join(', ') || '—'} | ${r.tests} | ${r.counts.passed} | ${r.counts.failed} | ${r.counts['not-run']} | ${formatMs(r.spanMs)} | ${cell(r.key)} |`),
+    ].join('\n')}\n`;
+}
+/** One run as Markdown. */
+export function runMarkdown(detail) {
+    const { run } = detail;
+    return `${[
+        `# Run ${run.key}`,
+        '',
+        `- Branch ${run.branch ?? '—'}, commit ${run.sha ?? '—'}`,
+        `- ${iso(run.startedAtMs)} to ${iso(run.endedAtMs)} (${formatMs(run.spanMs)}); ${run.layers} layers from ${run.producers.join(', ')}`,
+        `- Environments: ${run.environments.join(', ') || '—'}`,
+        `- ${run.tests} tests: ${counted(run.counts)}${run.totalDurationMs === null ? '' : `; ${formatMs(run.totalDurationMs)} of test time`}`,
+        '',
+        '| Status | Test | Spec | Environment | Duration | Detail |',
+        '|---|---|---|---|---:|---|',
+        ...detail.results.map(r => `| ${r.status} | ${cell(r.title)} | ${cell(r.specPath ?? '—')} | ${r.environment ?? '—'} | ${formatMs(r.durationMs)} | ${cell(r.detail.split('\n')[0] ?? '')} |`),
+    ].join('\n')}\n`;
+}