@crvouga/atlas 0.4.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,35 +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;
 };
-/** A run announcement with the fields the live layer can trust. Null when it cannot be a run. */
+/**
+ * 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

@@ -17,7 +17,11 @@ function readParameters(value) {
             parameters[key] = item;
     return parameters;
 }
-/** A run announcement with the fields the live layer can trust. Null when it cannot be a run. */
+/**
+ * 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;
@@ -38,6 +42,7 @@ export function liveRunRecord(value) {
 /** 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}`;
 }
@@ -50,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();

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,55 +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;
 };
@@ -74,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,78 +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. 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;
 /** 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,6 +86,7 @@ export function evidenceView(combined) {
     }
     return { specs, unassigned: checkSlots(combined.unassigned), total: addSummaries([...specs.values()].map(entry => entry.summary)) };
 }
+/** 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) {
@@ -90,6 +98,7 @@ export function sourceSelection(excluded) {
         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';
 }
@@ -101,6 +110,7 @@ export function versionOf(layer) {
 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) {
     const selection = sourceSelection(excluded);
     return !selection.backends.includes(layer.backend)
@@ -119,6 +129,7 @@ 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),

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

@@ -1,50 +1,87 @@
-/** Commit-scoped definitions and independently produced evidence. */
+/**
+ * @module Explorer data types
+ *
+ * The plain shapes the reports explorer shares between the store readers, the API routes and the viewer: a spec
+ * entry, a commit's spec inventory, the four result statuses, measurements, checks and parts. They are types only
+ * and carry no behaviour. The vocabulary matches the layer document (`docs/report-contract.md`): `status` is the
+ * closed set of four, everything else about a check is open.
+ */
+/** Commit-scoped definitions and independently produced evidence. One spec of the outline a report is laid over. */
 export type SpecEntry = {
+    /** `specs/<path inside the specs directory>`. The `specPath` a check uses to say which spec it belongs to. */
     readonly path: string;
+    /** Groups specs in the viewer (by default the project's folder name). */
     readonly domain: string;
+    /** The notation: `gherkin`, `quint`, `dmn`, `alloy`, `openslo`, a file extension, or `document`. An open vocabulary. */
     readonly kind: string;
     readonly title: string;
+    /** A fingerprint of the spec's text, so a reader can warn when a spec changed since a layer recorded it. Opaque. */
     readonly fingerprint?: string;
 };
+/** The specs of one commit. */
 export type SpecInventory = {
+    /** The 40-hex-digit commit. */
     readonly sha: string;
     readonly entries: readonly SpecEntry[];
 };
+/** The four result statuses. The only closed vocabulary in the format: `not-run` is never a pass and `running` is not done. */
 export type EvidenceStatus = 'passed' | 'failed' | 'running' | 'not-run';
+/** A number a check recorded. Exceeding `limit` is shown and never fails the check by itself. */
 export type EvidenceMeasurement = {
     readonly name: string;
     readonly value: number;
+    /** The unit of `value` and `limit`, such as `ms`. */
     readonly unit: string;
+    /** The allowance for `value`, in the same unit, when there is one. */
     readonly limit?: number;
 };
-export type EvidenceCheck = {
+/** What a check may carry beyond its outcome. All optional and open: see docs/extending.md. */
+export type EvidenceExtras = Partial<Pick<import('../../schema/src/layer.js').Check, 'tags' | 'labels' | 'links' | 'steps' | 'attachments' | 'annotations' | 'attempts' | 'extensions'>>;
+/** One check of a part, as recorded. */
+export type EvidenceCheck = EvidenceExtras & {
+    /** Stable across runs; the newer result replaces the older one only if both used the same id. */
     readonly id: string;
     readonly title: string;
     readonly status: EvidenceStatus;
+    /** Why the check has this status, for a person. */
     readonly detail: string;
+    /** The spec the check belongs to, as `specs/<path>`. */
     readonly specPath?: string;
     readonly measurements: readonly EvidenceMeasurement[];
+    /** How long the check took, when the producer measured it. */
+    readonly durationMs?: number;
 };
 /** `kind` is an open producer key; new parts need no protocol change. */
-export type ReportPart = {
+export type ReportPart = EvidenceExtras & {
+    /** `modified`: recorded from a checkout with uncommitted changes; `unknown`: origin not captured. Advisory; never changes a status. */
     readonly freshness?: 'unknown' | 'modified';
+    /** String choices that make a result its own slot (a device, a seed). */
     readonly parameters?: Readonly<Record<string, string>>;
+    /** The commit the part was recorded at. */
     readonly sha: string;
+    /** The part's id; when the part is published it is the `producer` of the layer made from it. */
     readonly id: string;
+    /** Open category (`behavior`, `performance`, ...); part of the slot. */
     readonly kind: string;
     readonly title: string;
+    /** When the checks ran, epoch milliseconds. */
     readonly recordedAtMs: number;
     readonly checks: readonly EvidenceCheck[];
 };
+/** The part of a {@link ReportPart} that a spec run's evidence file carries: its `kind`, `title` and `checks`. */
 export type ReportPartOutput = Pick<ReportPart, 'kind' | 'title' | 'checks'>;
+/** What the explorer shows for one commit: its specs (or null when none were recorded) and the parts recorded against it. */
 export type ExplorerData = {
     readonly inventory: SpecInventory | null;
     readonly parts: readonly ReportPart[];
+    /** A message to show instead of data, when something could not be read. */
     readonly notice?: string;
 };
+/** The checkout a workspace reads from. */
 export type WorkspaceVersion = {
     readonly sha: string;
     readonly branch: string;
+    /** True when the checkout has uncommitted changes. */
     readonly dirty: boolean;
 };
 /** Only composition roots provide checkout content; it is never CI evidence. */

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

@@ -0,0 +1,8 @@
+/**
+ * @module Explorer data types
+ *
+ * The plain shapes the reports explorer shares between the store readers, the API routes and the viewer: a spec
+ * entry, a commit's spec inventory, the four result statuses, measurements, checks and parts. They are types only
+ * and carry no behaviour. The vocabulary matches the layer document (`docs/report-contract.md`): `status` is the
+ * closed set of four, everything else about a check is open.
+ */