@crvouga/atlas 0.3.0 → 0.5.0

package/dist/reports/src/evidence-detail.js

@@ -0,0 +1,92 @@
+import { contentTypeOf } from './media-types.js';
+function count(holder) {
+    return (holder.attachments?.length ?? 0) + (holder.steps?.length ?? 0) + (holder.annotations?.length ?? 0) + (holder.attempts?.length ?? 0) + (holder.tags?.length ?? 0) + (holder.links?.length ?? 0) + Object.keys(holder.labels ?? {}).length + Object.keys(holder.extensions ?? {}).length;
+}
+/**
+ * What a result carries beyond its outcome, as counts and short facts. It rides in every row of the
+ * report so a list can show "3 attachments, 12 steps" without opening anything; the evidence itself is
+ * read when someone asks for it. Undefined when there is none.
+ *
+ * Several holders (for example a check and its layer) are summed: `attachments` also counts those on steps and
+ * attempts, `steps` counts only each holder's own top-level steps, tags are de-duplicated, and for a repeated
+ * label the later holder wins. `roles` are the attachments' roles (or, without one, what their media type or file
+ * name implies), sorted and distinct.
+ */
+export function summarizeEvidence(...holders) {
+    if (!holders.some(holder => count(holder) > 0))
+        return undefined;
+    const roles = new Set();
+    const tags = new Set();
+    const labels = {};
+    let attachments = 0, steps = 0, annotations = 0, attempts = 0, links = 0;
+    const attachmentsOf = (list) => { for (const item of list ?? []) {
+        attachments += 1;
+        roles.add(item.role ?? roleOfType(item.contentType ?? contentTypeOf(item.name)));
+    } };
+    for (const holder of holders) {
+        attachmentsOf(holder.attachments);
+        // Attachments on steps and attempts are part of the check too.
+        for (const step of holder.steps ?? [])
+            attachmentsOf(step.attachments);
+        for (const attempt of holder.attempts ?? []) {
+            attachmentsOf(attempt.attachments);
+            for (const step of attempt.steps ?? [])
+                attachmentsOf(step.attachments);
+        }
+        steps += holder.steps?.length ?? 0;
+        annotations += holder.annotations?.length ?? 0;
+        attempts += holder.attempts?.length ?? 0;
+        links += holder.links?.length ?? 0;
+        for (const tag of holder.tags ?? [])
+            tags.add(tag);
+        Object.assign(labels, holder.labels);
+    }
+    return { attachments, steps, annotations, attempts, links, tags: [...tags], labels, roles: [...roles].sort() };
+}
+/** A role to show when a producer gave none, from the media type: `image`, `video`, `audio`, `snapshot` (text/html), `text` (text, JSON, XML) or `file`. Roles are an open vocabulary; a producer's own role always wins. */
+export function roleOfType(contentType) {
+    const type = (contentType ?? '').toLowerCase();
+    if (type.startsWith('image/'))
+        return 'image';
+    if (type.startsWith('video/'))
+        return 'video';
+    if (type.startsWith('audio/'))
+        return 'audio';
+    if (type === 'text/html')
+        return 'snapshot';
+    if (type.startsWith('text/') || type.includes('json') || type.includes('xml'))
+        return 'text';
+    return 'file';
+}
+/** One result's evidence, from a layer: the first check with id `checkId` (in a part of kind `kind`, when given) plus the layer's own evidence. Null when the layer holds no such check. */
+export function checkDetailOf(layer, checkId, kind) {
+    for (const part of layer.parts) {
+        if (kind !== undefined && part.kind !== kind)
+            continue;
+        const check = part.checks.find(item => item.id === checkId);
+        if (check)
+            return { layer: layer.id, kind: part.kind, check, run: runEvidence(layer) };
+    }
+    return null;
+}
+/** What a layer carries as a whole (its tags, labels, links, attachments, annotations and extensions; not its parts' checks). Absent fields stay absent. */
+export function runEvidence(layer) {
+    const { tags, labels, links, attachments, annotations, extensions } = layer;
+    return { ...(tags ? { tags } : {}), ...(labels ? { labels } : {}), ...(links ? { links } : {}), ...(attachments ? { attachments } : {}), ...(annotations ? { annotations } : {}), ...(extensions ? { extensions } : {}) };
+}
+/** Every distinct bundle key (`bundleKey`) that the attachments of a holder, its steps and its attempts point to, so a layer's files can be copied. Attachments held by `uri` or inline `text` have none. */
+export function bundleKeysOf(holder) {
+    const keys = new Set();
+    const take = (list) => { for (const item of list ?? [])
+        if (item.bundleKey)
+            keys.add(item.bundleKey); };
+    take(holder.attachments);
+    for (const step of holder.steps ?? [])
+        take(step.attachments);
+    for (const attempt of holder.attempts ?? []) {
+        take(attempt.attachments);
+        for (const step of attempt.steps ?? [])
+            take(step.attachments);
+    }
+    return [...keys];
+}

package/dist/reports/src/evidence-live.d.ts

@@ -1,29 +1,65 @@
+/**
+ * @module Live evidence from running suites
+ *
+ * Shows results the moment each test finishes, before its package has been collected into an archived layer. A
+ * running suite announces itself with a record under `active/` in the local store (see {@link LiveRunRecord});
+ * this module reads the test reports that suite has written so far into a temporary layer (id `live-<source>`,
+ * `live: true`) and drops it once the archived layer arrives or after a short linger. Live layers are a viewing
+ * aid only (this module writes nothing), and an unreadable or half-written report is skipped, not guessed at.
+ */
 import type { Clock } from './clock.js';
 import type { ActiveRun, LayerEvidence, LayerHeader } from './evidence-types.js';
+import type { LayerParameters } from './layer-types.js';
 import type { ObjectStore } from './object-store.js';
 /** What a running spec suite announces under `active/` in the local store. */
 export type LiveRunRecord = {
+    /** The package directory the suite runs in, relative to the repository (`libs/chess`); with `bucket`, it names the source. */
     readonly packageDir: string;
+    /** The suite's bucket within the package (`part-2`); where the run writes each finished test. */
     readonly bucket: string;
+    /** When the run started, epoch milliseconds. A new value for the same source means a new run: tracking restarts. */
     readonly startedAtMs: number;
+    /** How many checks the run expects to execute, when known. */
     readonly plannedChecks?: number;
+    /** The client this suite is checking. A different client does not replace it. */
+    readonly environment?: string;
+    /** Other string choices that make the results their own slot; non-string or empty values are dropped on reading. */
+    readonly parameters?: LayerParameters;
 };
+/**
+ * Validates a parsed `active/` announcement and keeps only the fields the live layer can trust (the environment is
+ * normalised to its slug, parameters are string-to-string). Null when `packageDir`, `bucket` or a numeric
+ * `startedAtMs` is missing, so garbage in `active/` is ignored rather than shown.
+ */
+export declare function liveRunRecord(value: unknown): LiveRunRecord | null;
 /** How the host reaches the results a spec run has written so far. */
 export type LiveSource = {
-    /** The bucket the run writes each finished test into, or null when it cannot be read. */
+    /** The bucket the run writes each finished test into, or null when it cannot be read (the run is then not tracked). */
     readonly bucket: (run: LiveRunRecord) => ObjectStore | null;
-    /** The checkout the runs execute. */
+    /** The checkout the runs execute: its commit and branch, stamped on every live layer. Asked once per refresh pass. */
     readonly origin?: () => Promise<{
         readonly sha: string | null;
         readonly branch: string | null;
     }>;
-    /** The stylesheet the runs' snapshots render with. */
+    /** The stylesheet the runs' snapshots render with (served as `frame.css`). */
     readonly frameCss?: () => Promise<string | null>;
 };
+/** The id of the temporary layer for a source: `live-<source>`. Not a content hash, unlike an archived layer's id. */
 export declare function liveLayerId(source: string): string;
 /**
- * Finished tests of runs that have not been collected into a layer yet, so a
+ * Creates the tracker of finished tests of runs that have not been collected into a layer yet, so a
  * result appears the moment its test ends instead of when its package does.
+ *
+ * The tracker is stateful and meant to live as long as the server: call `refresh` on each poll with the current
+ * `active/` records and the newest archived layers. It returns the live layers (only those with at least one result)
+ * and the runs still in progress with their completed and failed counts. A run that disappears is read one last
+ * time and kept for 30 seconds, or until an archived (non-live) layer of the same producer and environment recorded
+ * at or after its start appears. `find(id)` returns a live layer by `live-<source>` id, and `store(source)` the
+ * bucket its files are read from. A bucket that is being replaced or a report still being written is skipped until
+ * the next pass; `refresh` does not throw for those.
+ *
+ * @param args.live How the host reaches the buckets; without it nothing is tracked.
+ * @param args.backend The backend id stamped on live layers.
  */
 export declare function createLiveEvidence(args: {
     readonly live: LiveSource | undefined;

package/dist/reports/src/evidence-live.js

@@ -1,14 +1,48 @@
 import { eachLimited } from './completion-order.js';
+import { environmentOf } from './evidence-view.js';
 import { sourceId } from './keys.js';
+import { normalizeEnvironment } from './layer-axes.js';
 import { layerEvidence } from './layer-merge.js';
 import { readUtf8 } from './object-io.js';
 import { SPEC_RUN_ID } from './publish.js';
 import { testPrefix } from './recording-keys.js';
 import { sourcePart } from './source-part.js';
 import { suiteStatus } from './status.js';
+function readParameters(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return {};
+    const parameters = {};
+    for (const [key, item] of Object.entries(value))
+        if (typeof item === 'string' && item)
+            parameters[key] = item;
+    return parameters;
+}
+/**
+ * Validates a parsed `active/` announcement and keeps only the fields the live layer can trust (the environment is
+ * normalised to its slug, parameters are string-to-string). Null when `packageDir`, `bucket` or a numeric
+ * `startedAtMs` is missing, so garbage in `active/` is ignored rather than shown.
+ */
+export function liveRunRecord(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const run = value;
+    if (!run.packageDir || !run.bucket || typeof run.startedAtMs !== 'number')
+        return null;
+    const parameters = readParameters(run.parameters);
+    const environment = typeof run.environment === 'string' ? normalizeEnvironment(run.environment) : null;
+    return {
+        packageDir: run.packageDir,
+        bucket: run.bucket,
+        startedAtMs: run.startedAtMs,
+        ...(typeof run.plannedChecks === 'number' ? { plannedChecks: run.plannedChecks } : {}),
+        ...(environment ? { environment } : {}),
+        ...(Object.keys(parameters).length > 0 ? { parameters } : {}),
+    };
+}
 /** A finished run stays visible this long while its layer is being collected. */
 const LINGER_MS = 30_000;
 const REPORT = '/report.json';
+/** The id of the temporary layer for a source: `live-<source>`. Not a content hash, unlike an archived layer's id. */
 export function liveLayerId(source) {
     return `live-${source}`;
 }
@@ -21,8 +55,19 @@ function sourceOf(run) {
     }
 }
 /**
- * Finished tests of runs that have not been collected into a layer yet, so a
+ * Creates the tracker of finished tests of runs that have not been collected into a layer yet, so a
  * result appears the moment its test ends instead of when its package does.
+ *
+ * The tracker is stateful and meant to live as long as the server: call `refresh` on each poll with the current
+ * `active/` records and the newest archived layers. It returns the live layers (only those with at least one result)
+ * and the runs still in progress with their completed and failed counts. A run that disappears is read one last
+ * time and kept for 30 seconds, or until an archived (non-live) layer of the same producer and environment recorded
+ * at or after its start appears. `find(id)` returns a live layer by `live-<source>` id, and `store(source)` the
+ * bucket its files are read from. A bucket that is being replaced or a report still being written is skipped until
+ * the next pass; `refresh` does not throw for those.
+ *
+ * @param args.live How the host reaches the buckets; without it nothing is tracked.
+ * @param args.backend The backend id stamped on live layers.
  */
 export function createLiveEvidence(args) {
     const tracked = new Map();
@@ -46,8 +91,9 @@ export function createLiveEvidence(args) {
             }
         });
         const tests = [...state.metas.values()].sort((a, b) => (a.testId < b.testId ? -1 : a.testId > b.testId ? 1 : 0));
-        const record = { source, packageDir: state.run.packageDir, bucket: state.run.bucket, status: suiteStatus(tests), updatedAtMs: args.clock.now(), tests };
-        const summary = { id: liveLayerId(source), producer: source, recordedAtMs: record.updatedAtMs, sha: origin.sha, branch: origin.branch, runUrl: null, parameters: {}, specs: [], parts: [sourcePart(origin.sha ?? '', record)], source: record, recording: null };
+        const environment = normalizeEnvironment(state.run.environment ?? state.run.parameters?.environment);
+        const record = { source, packageDir: state.run.packageDir, bucket: state.run.bucket, status: suiteStatus(tests), updatedAtMs: args.clock.now(), ...(environment ? { environment } : {}), ...(state.run.parameters ? { parameters: state.run.parameters } : {}), tests };
+        const summary = { id: liveLayerId(source), producer: source, recordedAtMs: record.updatedAtMs, sha: origin.sha, branch: origin.branch, runUrl: null, ...(environment ? { environment } : {}), parameters: state.run.parameters ?? {}, specs: [], parts: [sourcePart(origin.sha ?? '', record)], source: record, recording: null };
         const evidence = layerEvidence(summary, args.backend);
         const layer = { ...evidence.layer, live: true, recording: { type: 'live', source }, execution: `live:${state.run.startedAtMs}:${tests.length}` };
         state.evidence = { ...evidence, layer };
@@ -98,7 +144,9 @@ export function createLiveEvidence(args) {
                         /* keep what was read while it ran */
                     }
                 }
-                const archived = collected.some(layer => layer.producer === source && !layer.live && layer.recordedAtMs >= state.run.startedAtMs);
+                const declared = normalizeEnvironment(state.run.environment ?? state.run.parameters?.environment) ?? 'unspecified';
+                // A collected layer of another client is a different result, so this suite stays up.
+                const archived = collected.some(layer => layer.producer === source && !layer.live && layer.recordedAtMs >= state.run.startedAtMs && environmentOf(layer) === declared);
                 if (archived || now - state.goneAt > LINGER_MS)
                     tracked.delete(source);
             }

package/dist/reports/src/evidence-types.d.ts

@@ -1,3 +1,13 @@
+/**
+ * @module Report evidence types
+ *
+ * The shapes the report API and the viewer exchange about layers: a layer's header (origin and totals), its rows
+ * (one per check), the backends that contributed, runs in progress, and the address of a recorded test's
+ * timeline. These are the wire shapes of `/api/reports/*`, so within a version they only gain optional fields.
+ * Also holds {@link recordingPaths}, the one place the URL layout of a recording is defined.
+ *
+ * @see docs/report-contract.md
+ */
 import type { EvidenceMeasurement, EvidenceStatus } from './explorer-types.js';
 import type { LayerParameters } from './layer-types.js';
 /** Where a recorded test's timeline and captured files are read from. */
@@ -14,53 +24,101 @@ export type RecordingAddress = {
 };
 /** One store that contributes report layers. */
 export type BackendInfo = {
+    /** Stable backend id (lowercase letters, digits, hyphens); names where a result came from. */
     readonly id: string;
+    /** What a person sees for the backend. */
     readonly label: string;
     /** Spec runs on this machine write here while they are still running. */
     readonly live: boolean;
+    /** False when the backend could not be read; a notice says why, and its results are unknown, not passed. */
     readonly available: boolean;
 };
+/** How many results have each status (`passed`, `failed`, `running`, `not-run`). */
 export type StatusCounts = Readonly<Record<EvidenceStatus, number>>;
+/**
+ * What a result (or a run) carries beyond its outcome, as counts and short facts: attachments, steps,
+ * annotations, retries, tags, labels, links. It is only there when there is something. The evidence itself
+ * is read when someone opens the result.
+ */
+export type EvidenceSummary = {
+    /** Attachments on the result, including those on its steps and attempts. */
+    readonly attachments: number;
+    readonly steps: number;
+    readonly annotations: number;
+    /** How many tries were recorded when the check was retried. */
+    readonly attempts: number;
+    readonly links: number;
+    readonly tags: readonly string[];
+    readonly labels: Readonly<Record<string, string>>;
+    /** The distinct roles of its attachments (or what their media types say), to show what kind of evidence there is. */
+    readonly roles: readonly string[];
+};
 /** A report layer's origin and totals. Its checks are read separately, once. */
 export type LayerHeader = {
+    /** The layer's id: 64 hex digits for an archived layer, `live-<source>` for a live one. */
     readonly id: string;
+    /** The id of the backend it was read from (the one whose id sorts first when several hold it). */
     readonly backend: string;
+    /** The suite or tool that made it. Part of the slot. */
     readonly producer: string;
+    /** The package directory of a spec run, when the layer came from one. */
     readonly packageDir: string | null;
+    /** When the checks ran, epoch milliseconds; the newest completed result wins its slot. */
     readonly recordedAtMs: number;
+    /** Provenance: the commit it was recorded at. Never part of the slot. */
     readonly sha: string | null;
+    /** Provenance: the branch it was recorded on. Never part of the slot. */
     readonly branch: string | null;
+    /** The client this layer checked. Null when the layer did not say. */
+    readonly environment: string | null;
+    /** Provenance: the CI run that made it. */
     readonly runUrl: string | null;
+    /** Other string choices that make a result its own slot. */
     readonly parameters: LayerParameters;
+    /** `modified`: recorded from a checkout with uncommitted changes; `unknown`: origin not captured; absent: clean. Advisory; never changes a status. */
     readonly freshness?: 'unknown' | 'modified';
+    /** Where this layer's recorded timelines and captured files are read from, or null when it has none. */
     readonly recording: RecordingAddress | null;
     /** From a spec run that has not been collected into a layer yet. */
     readonly live: boolean;
+    /** Its checks by status. Parts of kind `performance` are not counted when anything else was recorded. */
     readonly counts: StatusCounts;
     /** Equal for the mutable and the archived address of one execution. */
     readonly execution: string;
+    /** What the run as a whole carries: its logs, links and labels. */
+    readonly evidence?: EvidenceSummary;
 };
 /** One check of one report part. */
 export type LayerRow = {
+    /** The kind of the part holding the check (`behavior`, `performance`, ...). Part of the slot. */
     readonly kind: string;
+    /** The check's stable id. Part of the slot. */
     readonly id: string;
     readonly title: string;
     readonly status: EvidenceStatus;
+    /** The spec the check belongs to (`specs/<path>`), or null. */
     readonly specPath: string | null;
+    /** Why it has this status, for a person; empty when there is nothing to add. */
     readonly detail: string;
     readonly measurements: readonly EvidenceMeasurement[];
     /** The recorded test behind this check, when it has a timeline to open. */
     readonly testId: string | null;
     /** What distinguishes this recorded test from another run of the same check. */
     readonly variant: LayerParameters;
+    /** How long the check took, milliseconds, or null when unknown. */
     readonly durationMs: number | null;
+    /** What this result carries beyond its outcome. Absent when nothing. */
+    readonly evidence?: EvidenceSummary;
 };
+/** The checks of one layer, read separately from its header. */
 export type LayerRows = {
+    /** The layer's id. */
     readonly id: string;
     readonly rows: readonly LayerRow[];
     /** Spec path to the fingerprint the layer recorded for it. */
     readonly fingerprints: Readonly<Record<string, string>>;
 };
+/** A layer's rows together with its header: everything composition needs to lay the layer over the specs. */
 export type LayerEvidence = LayerRows & {
     readonly layer: LayerHeader;
 };
@@ -72,17 +130,28 @@ export type ActiveRun = {
     readonly startedAtMs: number;
     /** Spec files the run planned, when the producer recorded it. */
     readonly plannedChecks?: number;
+    /** Checks finished so far: passed, failed or not-run. */
     readonly completed: number;
+    /** Of those, how many failed. */
     readonly failed: number;
 };
+/** One page of the layer listing the viewer reads. */
 export type EvidencePage = {
+    /** The layers on this page, newest first. */
     readonly layers: readonly LayerHeader[];
+    /** Opaque token for the next page, or null at the end. */
     readonly cursor: string | null;
+    /** What could not be read; a gate treats any as unknown, never as a pass. */
     readonly notices: readonly string[];
     readonly backends: readonly BackendInfo[];
+    /** Runs writing results right now. */
     readonly active: readonly ActiveRun[];
 };
-/** The report API paths of one recorded test. */
+/**
+ * The report API paths (relative to the reports API root) of one recorded test: its `report` JSON, a `file(path)`
+ * builder for its captured files (each path segment is URL-encoded), and the `css` its snapshots render with.
+ * The layout depends on where the recording lives: an archived layer, a commit (the older layout) or a live run.
+ */
 export declare function recordingPaths(address: RecordingAddress, testId: string): {
     report: string;
     file: (path: string) => string;

package/dist/reports/src/evidence-types.js

@@ -1,4 +1,8 @@
-/** The report API paths of one recorded test. */
+/**
+ * The report API paths (relative to the reports API root) of one recorded test: its `report` JSON, a `file(path)`
+ * builder for its captured files (each path segment is URL-encoded), and the `css` its snapshots render with.
+ * The layout depends on where the recording lives: an archived layer, a commit (the older layout) or a live run.
+ */
 export function recordingPaths(address, testId) {
     const test = encodeURIComponent(testId);
     const file = (base) => (path) => `${base}/files/${path.split('/').map(encodeURIComponent).join('/')}`;

package/dist/reports/src/evidence-view.d.ts

@@ -1,65 +1,117 @@
+/**
+ * @module The viewer's model of a combined report
+ *
+ * Pure functions that reshape a combined report for display: results grouped per check (a {@link CheckSlot}), rolled
+ * up per spec and overall, the facets by which layers are included or left out, and the history of one check across
+ * layers. They never change a result: statuses come from the composition (`layer-merge.ts`), and a spec with no
+ * recorded check is `none`, never a pass.
+ *
+ * @see docs/report-contract.md
+ */
 import type { EvidenceStatus } from './explorer-types.js';
 import type { LayerEvidence, LayerHeader, LayerRow, StatusCounts } from './evidence-types.js';
 import { type CombinedEvidence, type EvidenceResult } from './layer-merge.js';
 /** Everything the combined report holds for one check. */
 export type CheckSlot = {
+    /** The check's key (its spec path and id), shared by all of its results. */
     readonly key: string;
     readonly id: string;
     readonly title: string;
     readonly specPath: string | null;
-    /** The worst outcome across the check's parameter sets. */
+    /** The worst outcome across the check's parameter sets (failed, then running, then not-run, then passed). */
     readonly status: EvidenceStatus;
-    /** What happened, newest first. One entry per producer and parameter set. */
+    /** What happened, newest first. One entry per producer, environment and parameter set. */
     readonly outcomes: readonly EvidenceResult[];
     /** Recorded timings of the same check. They never change its outcome. */
     readonly diagnostics: readonly EvidenceResult[];
+    /** The newest `recordedAtMs` among all of its results, diagnostics included. */
     readonly latestAtMs: number;
+    /** True when any result comes from a run that is still in progress. */
     readonly live: boolean;
 };
-/** Group the combined results by check, in the order the checks were first seen. */
+/**
+ * Groups the combined results (the winners of the slots) by check, in the order the checks were first seen.
+ * A check's status is the worst of its non-diagnostic results; if it has only diagnostics (timings), those are its
+ * outcomes. The title and id shown are the newest result's.
+ */
 export declare function checkSlots(results: readonly EvidenceResult[]): CheckSlot[];
+/** A spec's rolled-up status: the worst of its checks, or `none` when nothing was recorded for it. */
 export type SpecStatus = EvidenceStatus | 'none';
+/** The rollup of a set of checks (one spec, or the whole report). */
 export type SpecSummary = {
+    /** `failed` if any check failed, else `running`, else `passed` if any passed, else `not-run`; `none` with no checks. */
     readonly status: SpecStatus;
+    /** Checks by their own status. */
     readonly counts: StatusCounts;
     readonly total: number;
+    /** The newest `recordedAtMs` among them, or null with no checks. */
     readonly latestAtMs: number | null;
     readonly live: boolean;
 };
+/** The summary of a spec with no recorded check: status `none`, which is not a pass. */
 export declare const NO_EVIDENCE: SpecSummary;
-/** No recorded check is `none`, never a pass. */
+/** Rolls the checks of one spec up into a {@link SpecSummary}. No recorded check is `none`, never a pass. */
 export declare function summarizeSlots(slots: readonly CheckSlot[]): SpecSummary;
+/** Adds several summaries (for example every spec's) into one, with the same status rule; `none` when they hold no checks at all. */
 export declare function addSummaries(summaries: readonly SpecSummary[]): SpecSummary;
+/** One spec's checks and their rollup. */
 export type SpecEvidence = {
     readonly slots: readonly CheckSlot[];
     readonly summary: SpecSummary;
 };
+/** The combined report as the viewer draws it. */
 export type EvidenceView = {
     /** Keyed by the spec path the outline uses (`specs/...`). */
     readonly specs: ReadonlyMap<string, SpecEvidence>;
     /** Results whose spec is no longer in the outline, or that name no spec. */
     readonly unassigned: readonly CheckSlot[];
+    /** The rollup of the specs in the outline only; `unassigned` results are not counted in it. */
     readonly total: SpecSummary;
 };
+/** Builds the {@link EvidenceView} of a combined report: every spec of the outline gets an entry, with an empty one when it has no results. */
 export declare function evidenceView(combined: CombinedEvidence): EvidenceView;
-/** Sources left out of the combined report. Everything else, including layers that arrive later, contributes. */
+/**
+ * Sources left out of the combined report. An empty list means every layer
+ * on that axis contributes, including layers that arrive later.
+ */
 export type SourceSelection = {
+    /** Backend ids to leave out. */
     readonly backends: readonly string[];
+    /** Branch names to leave out; `Unknown branch` stands for layers with no branch. */
     readonly branches: readonly string[];
+    /** Commit shas to leave out; `unknown` stands for layers with no sha. */
+    readonly versions: readonly string[];
+    /** Environment slugs to leave out; `unspecified` stands for layers with none. */
+    readonly environments: readonly string[];
+    /** Layer ids to leave out. */
     readonly layers: readonly string[];
 };
+/** The selection that leaves nothing out: every layer contributes. */
 export declare const ALL_SOURCES: SourceSelection;
+/** A saved selection from before versions and environments were axes still means "exclude nothing new". */
+export declare function sourceSelection(excluded: Partial<SourceSelection> | null | undefined): SourceSelection;
+/** The branch a layer was recorded on, or `Unknown branch` when it did not say. */
 export declare function branchOf(layer: LayerHeader): string;
-export declare function contributes(layer: LayerHeader, excluded: SourceSelection): boolean;
+/** The commit a layer checked, or `unknown` when the layer did not record one. */
+export declare function versionOf(layer: Pick<LayerHeader, 'sha'>): string;
+/** The client a layer checked, or `unspecified` when it did not say. */
+export declare function environmentOf(layer: Pick<LayerHeader, 'environment'>): string;
+/** Whether a layer takes part given what is left out: false when its backend, branch, commit, environment or id is excluded. Missing axes in `excluded` exclude nothing. */
+export declare function contributes(layer: LayerHeader, excluded: Partial<SourceSelection>): boolean;
+/** One choice on an axis of the sources panel: its value, how many layers have it, and the newest `recordedAtMs` among them. */
 export type SourceFacet = {
     readonly id: string;
     readonly layers: number;
     readonly latestAtMs: number;
 };
+/** Counts the layers per backend, branch, commit and environment, each list newest first (ties by name). */
 export declare function sourceFacets(layers: readonly LayerHeader[]): {
     backends: SourceFacet[];
     branches: SourceFacet[];
+    versions: SourceFacet[];
+    environments: SourceFacet[];
 };
+/** One layer's record of a check. */
 export type HistoryEntry = {
     readonly layer: LayerHeader;
     readonly row: LayerRow;

package/dist/reports/src/evidence-view.js

@@ -10,7 +10,11 @@ function worst(statuses) {
 function newestFirst(a, b) {
     return b.layer.recordedAtMs - a.layer.recordedAtMs || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
 }
-/** Group the combined results by check, in the order the checks were first seen. */
+/**
+ * Groups the combined results (the winners of the slots) by check, in the order the checks were first seen.
+ * A check's status is the worst of its non-diagnostic results; if it has only diagnostics (timings), those are its
+ * outcomes. The title and id shown are the newest result's.
+ */
 export function checkSlots(results) {
     const groups = new Map();
     for (const result of results) {
@@ -38,8 +42,9 @@ export function checkSlots(results) {
         };
     });
 }
+/** The summary of a spec with no recorded check: status `none`, which is not a pass. */
 export const NO_EVIDENCE = { status: 'none', counts: emptyCounts(), total: 0, latestAtMs: null, live: false };
-/** No recorded check is `none`, never a pass. */
+/** Rolls the checks of one spec up into a {@link SpecSummary}. No recorded check is `none`, never a pass. */
 export function summarizeSlots(slots) {
     if (!slots.length)
         return NO_EVIDENCE;
@@ -55,6 +60,7 @@ export function summarizeSlots(slots) {
         live: slots.some(slot => slot.live),
     };
 }
+/** Adds several summaries (for example every spec's) into one, with the same status rule; `none` when they hold no checks at all. */
 export function addSummaries(summaries) {
     const counts = emptyCounts();
     let total = 0, latestAtMs = null, live = false;
@@ -71,6 +77,7 @@ export function addSummaries(summaries) {
     const status = counts.failed ? 'failed' : counts.running ? 'running' : counts.passed ? 'passed' : 'not-run';
     return { status, counts, total, latestAtMs, live };
 }
+/** Builds the {@link EvidenceView} of a combined report: every spec of the outline gets an entry, with an empty one when it has no results. */
 export function evidenceView(combined) {
     const specs = new Map();
     for (const { spec, results } of combined.specs) {
@@ -79,12 +86,38 @@ export function evidenceView(combined) {
     }
     return { specs, unassigned: checkSlots(combined.unassigned), total: addSummaries([...specs.values()].map(entry => entry.summary)) };
 }
-export const ALL_SOURCES = { backends: [], branches: [], layers: [] };
+/** The selection that leaves nothing out: every layer contributes. */
+export const ALL_SOURCES = { backends: [], branches: [], versions: [], environments: [], layers: [] };
+/** A saved selection from before versions and environments were axes still means "exclude nothing new". */
+export function sourceSelection(excluded) {
+    return {
+        backends: excluded?.backends ?? [],
+        branches: excluded?.branches ?? [],
+        versions: excluded?.versions ?? [],
+        environments: excluded?.environments ?? [],
+        layers: excluded?.layers ?? [],
+    };
+}
+/** The branch a layer was recorded on, or `Unknown branch` when it did not say. */
 export function branchOf(layer) {
     return layer.branch ?? 'Unknown branch';
 }
+/** The commit a layer checked, or `unknown` when the layer did not record one. */
+export function versionOf(layer) {
+    return layer.sha ?? 'unknown';
+}
+/** The client a layer checked, or `unspecified` when it did not say. */
+export function environmentOf(layer) {
+    return layer.environment || 'unspecified';
+}
+/** Whether a layer takes part given what is left out: false when its backend, branch, commit, environment or id is excluded. Missing axes in `excluded` exclude nothing. */
 export function contributes(layer, excluded) {
-    return !excluded.backends.includes(layer.backend) && !excluded.branches.includes(branchOf(layer)) && !excluded.layers.includes(layer.id);
+    const selection = sourceSelection(excluded);
+    return !selection.backends.includes(layer.backend)
+        && !selection.branches.includes(branchOf(layer))
+        && !selection.versions.includes(versionOf(layer))
+        && !selection.environments.includes(environmentOf(layer))
+        && !selection.layers.includes(layer.id);
 }
 function facets(layers, id) {
     const found = new Map();
@@ -96,8 +129,14 @@ function facets(layers, id) {
     }
     return [...found].map(([key, facet]) => ({ id: key, ...facet })).sort((a, b) => b.latestAtMs - a.latestAtMs || (a.id < b.id ? -1 : 1));
 }
+/** Counts the layers per backend, branch, commit and environment, each list newest first (ties by name). */
 export function sourceFacets(layers) {
-    return { backends: facets(layers, layer => layer.backend), branches: facets(layers, branchOf) };
+    return {
+        backends: facets(layers, layer => layer.backend),
+        branches: facets(layers, branchOf),
+        versions: facets(layers, versionOf),
+        environments: facets(layers, environmentOf),
+    };
 }
 /** Every layer's own record of one check, newest first. A superseded result stays readable here. */
 export function checkHistory(layers, path, id) {