@crvouga/atlas 0.4.0 → 0.6.0

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.
+ */

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

@@ -1,4 +1,12 @@
 import type { ObjectStore } from './object-store.js';
-/** A per-version marker lets an independent producer appear without a spec run. */
+/**
+ * Writes the marker `versions/<sha>.json` (`{"sha": "<sha>"}`) so an independent producer's commit appears without
+ * a spec run. Writing it again is harmless. Throws `Invalid commit` when `sha` is not a 40-hex-digit commit.
+ */
 export declare function recordExplorerVersion(store: ObjectStore, sha: string): Promise<void>;
+/**
+ * Lists the commits that have a marker, in key order. Keys under `versions/` that are not `<40 hex>.json` are
+ * ignored. A marker that is missing at read time or whose content does not name its own sha is not skipped:
+ * it throws `Invalid explorer version`, so corrupt data fails visibly.
+ */
 export declare function listExplorerVersions(store: ObjectStore): Promise<readonly string[]>;

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

@@ -1,11 +1,28 @@
+/**
+ * @module Explorer version markers
+ *
+ * Marker files `versions/<sha>.json` that list which commits a store has anything recorded for, so the explorer can
+ * show a commit that has parts or specs but no spec run. A store layout older than layers; the markers are small,
+ * immutable and idempotent to write, and are read in place by newer readers.
+ *
+ * @see docs/report-contract.md (stores written before layers existed)
+ */
 import { readUtf8, writeUtf8 } from './object-io.js';
 import { isCommitSha } from './keys.js';
-/** A per-version marker lets an independent producer appear without a spec run. */
+/**
+ * Writes the marker `versions/<sha>.json` (`{"sha": "<sha>"}`) so an independent producer's commit appears without
+ * a spec run. Writing it again is harmless. Throws `Invalid commit` when `sha` is not a 40-hex-digit commit.
+ */
 export async function recordExplorerVersion(store, sha) {
     if (!isCommitSha(sha))
         throw new Error('Invalid commit');
     await writeUtf8(store, `versions/${sha}.json`, JSON.stringify({ sha }), 'application/json');
 }
+/**
+ * Lists the commits that have a marker, in key order. Keys under `versions/` that are not `<40 hex>.json` are
+ * ignored. A marker that is missing at read time or whose content does not name its own sha is not skipped:
+ * it throws `Invalid explorer version`, so corrupt data fails visibly.
+ */
 export async function listExplorerVersions(store) {
     const versions = [];
     for (const key of await store.listKeys('versions/')) {

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

@@ -1,6 +1,21 @@
 import type { ObjectStore } from './object-store.js';
+/**
+ * Maps a report API path (with its query) to the file an export stores it under, for example `/evidence?cursor=x`
+ * to `evidence/pages/x.json` and `/` to `index.json`. Files a layer carries (`/blobs/`, `/files/`, `frame.css`,
+ * `report.json`) keep their path so their type stays known by name; everything else gets `.json` appended. Pure.
+ */
 export declare function evidenceFile(path: string): string;
-/** Export the combined report, preserving layer provenance and lazy recording addresses. */
+/**
+ * Exports the combined report, preserving layer provenance and lazy recording addresses.
+ *
+ * `args.fetch` answers report API paths (`/outline`, `/evidence?cursor=`, ...), for example the reports app's own
+ * `request`. Every response is stored in `args.target` under {@link evidenceFile}, each path once. A 404 or 503 for
+ * a path is recorded in `missing` and skipped; any other failure throws, as does a layer catalog that repeats a
+ * page. Live runs are left out and each execution is exported once. Nothing in `target` is deleted.
+ *
+ * @returns `revisions` (distinct commits among the exported layers), `layers` (layers exported) and `missing`
+ * (paths that were not there).
+ */
 export declare function exportEvidence(args: {
     fetch: (path: string) => Promise<Response>;
     target: ObjectStore;

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

@@ -1,21 +1,55 @@
+/**
+ * @module Static export of a report
+ *
+ * Copies what a running reports API serves (outline, spec texts, layer pages, rows, per-result evidence, recorded
+ * files) into an {@link ObjectStore}, one file per URL, so the viewer can be hosted statically. {@link evidenceFile}
+ * is the single mapping from an API path to the exported file name; the exporter writes with it and a static host
+ * must read with it. Only collected layers are exported (a static site has no running suite).
+ */
 import { eachLimited } from './completion-order.js';
+import { bundleKeysOf } from './evidence-detail.js';
 import { recordingPaths } from './evidence-types.js';
 import { distinctHeaders } from './layer-merge.js';
 import { writeUtf8 } from './object-io.js';
 import { capturedFiles } from './frames.js';
+/**
+ * Maps a report API path (with its query) to the file an export stores it under, for example `/evidence?cursor=x`
+ * to `evidence/pages/x.json` and `/` to `index.json`. Files a layer carries (`/blobs/`, `/files/`, `frame.css`,
+ * `report.json`) keep their path so their type stays known by name; everything else gets `.json` appended. Pure.
+ */
 export function evidenceFile(path) {
     const url = new URL(path || '/', 'http://atlas');
     if (url.pathname === '/')
         return 'index.json';
     if (url.pathname === '/evidence' && url.searchParams.has('cursor'))
         return `evidence/pages/${encodeURIComponent(url.searchParams.get('cursor'))}.json`;
+    // One result's evidence: a file per result, named by its check (and kind), beside its layer's own.
+    const detail = /^\/evidence\/detail\/([^/]+)\/([^/]+)$/.exec(url.pathname);
+    if (detail) {
+        const check = url.searchParams.get('check');
+        const kind = url.searchParams.get('kind');
+        return `evidence/detail/${detail[1]}/${detail[2]}${check === null ? '' : `/${encodeURIComponent(check)}${kind ? `~${encodeURIComponent(kind)}` : ''}`}.json`;
+    }
+    // A file a layer carries: kept as it is, with its type known by its name.
+    if (url.pathname.includes('/blobs/'))
+        return url.pathname.slice(1);
     if (url.pathname.endsWith('/spec'))
         return `${url.pathname.slice(1, -5)}/specs/${encodeURIComponent(url.searchParams.get('path') ?? '')}.txt`;
     if (url.pathname.includes('/files/') || url.pathname.endsWith('/frame.css') || url.pathname.endsWith('/report.json'))
         return url.pathname.slice(1);
     return `${url.pathname.slice(1)}.json`;
 }
-/** Export the combined report, preserving layer provenance and lazy recording addresses. */
+/**
+ * Exports the combined report, preserving layer provenance and lazy recording addresses.
+ *
+ * `args.fetch` answers report API paths (`/outline`, `/evidence?cursor=`, ...), for example the reports app's own
+ * `request`. Every response is stored in `args.target` under {@link evidenceFile}, each path once. A 404 or 503 for
+ * a path is recorded in `missing` and skipped; any other failure throws, as does a layer catalog that repeats a
+ * page. Live runs are left out and each execution is exported once. Nothing in `target` is deleted.
+ *
+ * @returns `revisions` (distinct commits among the exported layers), `layers` (layers exported) and `missing`
+ * (paths that were not there).
+ */
 export async function exportEvidence(args) {
     const missing = [];
     const copied = new Map();
@@ -67,6 +101,23 @@ export async function exportEvidence(args) {
             if (layer.sha)
                 revisions.add(layer.sha);
             const rowsText = await copy(`/evidence/rows/${encodeURIComponent(layer.backend)}/${encodeURIComponent(layer.id)}`);
+            // Evidence a result carries: what it says, and every file it points to.
+            if (rowsText) {
+                const withEvidence = JSON.parse(rowsText).rows.filter(row => row.evidence);
+                const copyDetail = async (path) => {
+                    const text = await copy(path);
+                    if (!text)
+                        return;
+                    const read = JSON.parse(text);
+                    const keys = new Set([...bundleKeysOf('check' in read ? read.check : {}), ...bundleKeysOf(read.run)]);
+                    await eachLimited([...keys], 4, key => copy(`/layers/${encodeURIComponent(layer.id)}/blobs/${key.split('/').map(encodeURIComponent).join('/')}`).then(() => { }));
+                };
+                const base = `/evidence/detail/${encodeURIComponent(layer.backend)}/${encodeURIComponent(layer.id)}`;
+                if (layer.evidence)
+                    await copyDetail(base);
+                for (const row of withEvidence)
+                    await copyDetail(`${base}?check=${encodeURIComponent(row.id)}&kind=${encodeURIComponent(row.kind)}`);
+            }
             const recording = layer.recording;
             if (!rowsText || !recording)
                 return;