@crvouga/atlas 0.4.0 → 0.5.0

package/dist/reports/src/publish-checks.js

@@ -0,0 +1,122 @@
+/**
+ * @module Publishing checks as a layer
+ *
+ * `publishChecks` turns the checks of one producer into one immutable layer in any store: the whole integration for a suite
+ * that has no timeline to record. Attachments of any kind are stored by content (the same screenshot attached ten times is
+ * stored once). Nothing here reads a clock or the environment, so the same input is always the same layer and a retried CI
+ * step changes nothing.
+ *
+ * @see docs/integrating.md
+ * @see docs/extending.md
+ */
+import { PublishChecksSchema } from '../../schema/src/layer.js';
+import { writeBundle } from './bundle.js';
+import { normalizeEnvironment } from './layer-axes.js';
+import { publishLayerBundle } from './layer-store.js';
+import { contentTypeOf } from './media-types.js';
+import { parseWith } from './parse-with.js';
+import { sha256Hex } from './sigv4.js';
+/** A small text value stays in the layer's own document; anything longer is stored as a file. */
+const INLINE_TEXT_BYTES = 8 * 1024;
+const encoder = new TextEncoder();
+function decodeBase64(text) {
+    const binary = atob(text);
+    return Uint8Array.from(binary, char => char.charCodeAt(0));
+}
+/**
+ * Move the bytes of every attachment, at every level, into the layer: a file by its content (so the same
+ * screenshot attached ten times is stored once), referred to by `bundleKey`. What a producer wrote as `data`,
+ * `base64` or a long `text` becomes a reference; a short `text` stays inline; a `uri` is left alone.
+ */
+async function materialize(holder, entries, limit) {
+    const out = { ...holder };
+    if (Array.isArray(out.attachments)) {
+        out.attachments = await Promise.all(out.attachments.map(async (given) => {
+            const { path: file, base64, data, ...kept } = given;
+            if (file !== undefined)
+                throw new Error(`publishChecks: attachment "${String(kept.name)}" names a file (path). Reading files is the command line's job: read it and pass its bytes as data`);
+            const text = typeof kept.text === 'string' ? kept.text : undefined;
+            let bytes = data ?? (base64 === undefined ? null : decodeBase64(base64));
+            if (!bytes && text !== undefined && encoder.encode(text).length > INLINE_TEXT_BYTES)
+                bytes = encoder.encode(text);
+            if (!bytes)
+                return { ...kept, ...(text !== undefined ? { bytes: encoder.encode(text).length } : {}) };
+            if (bytes.length > limit)
+                throw new Error(`publishChecks: attachment "${String(kept.name)}" is ${bytes.length} bytes, over the limit of ${limit}. Store it elsewhere and attach its uri`);
+            const sha256 = await sha256Hex(bytes);
+            const contentType = kept.contentType ?? contentTypeOf(String(kept.name));
+            entries.set(`attachments/${sha256}`, { key: `attachments/${sha256}`, bytes, contentType });
+            const { text: _inline, ...rest } = kept;
+            return { ...rest, contentType, bundleKey: `attachments/${sha256}`, bytes: bytes.length, sha256 };
+        }));
+    }
+    if (Array.isArray(out.steps))
+        out.steps = await Promise.all(out.steps.map(step => materialize(step, entries, limit)));
+    if (Array.isArray(out.attempts))
+        out.attempts = await Promise.all(out.attempts.map(attempt => materialize(attempt, entries, limit)));
+    return out;
+}
+/**
+ * Publish the checks of one producer as one immutable layer. This is the whole integration for a
+ * suite that has no timelines to record: Gherkin scenarios, a Quint run, a DMN table test, an SLO
+ * evaluation, a linter, anything that ends in "this check passed or failed".
+ *
+ * A check may carry whatever evidence its framework has: attachments of any media type (screenshots,
+ * videos, traces, logs, DOM snapshots…), timeline steps, annotations, retries, tags, labels, links and
+ * namespaced `extensions`. All of it is optional (docs/extending.md).
+ *
+ * Nothing here reads a clock: `recordedAtMs` is when the checks ran, given by the caller. Publishing
+ * the same input twice therefore writes the same layer, and a retried CI step changes nothing.
+ * Each check's `id` is its identity across runs. It must be stable and unique within the layer.
+ */
+export async function publishChecks(store, input, options = {}) {
+    const args = parseWith(PublishChecksSchema, input, 'publishChecks');
+    const seen = new Set();
+    for (const check of args.checks) {
+        if (seen.has(check.id))
+            throw new Error(`publishChecks: check id "${check.id}" appears twice; a check keeps one id across runs, so ids must be unique`);
+        seen.add(check.id);
+    }
+    const limit = options.maxAttachmentBytes ?? 512 * 1024 * 1024;
+    const entries = new Map();
+    const checks = await Promise.all(args.checks.map(check => materialize(check, entries, limit)));
+    const layerEvidence = await materialize({ attachments: args.attachments }, entries, limit);
+    const total = [...entries.values()].reduce((sum, entry) => sum + entry.bytes.length, 0);
+    const totalLimit = options.maxTotalAttachmentBytes ?? 2 * 1024 * 1024 * 1024;
+    if (total > totalLimit)
+        throw new Error(`publishChecks: attachments total ${total} bytes, over the limit of ${totalLimit}. Attach the largest by uri, or publish in several layers`);
+    const environment = normalizeEnvironment(args.environment ?? args.parameters.environment);
+    const { environment: _folded, ...parameters } = args.parameters;
+    const part = {
+        sha: args.sha ?? '',
+        id: args.producer,
+        kind: args.kind,
+        title: args.title ?? args.producer,
+        recordedAtMs: args.recordedAtMs,
+        checks: checks
+    };
+    // Key order is part of the layer's identity: build it the one way.
+    const summary = {
+        ...(args.freshness ? { freshness: args.freshness } : {}),
+        producer: args.producer,
+        recordedAtMs: args.recordedAtMs,
+        sha: args.sha,
+        branch: args.branch,
+        runUrl: args.runUrl,
+        ...(environment ? { environment } : {}),
+        parameters: Object.fromEntries(Object.entries(parameters).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))),
+        specs: args.specs,
+        parts: [part],
+        source: null,
+        recording: null,
+        ...(args.tags?.length ? { tags: args.tags } : {}),
+        ...(args.labels && Object.keys(args.labels).length ? { labels: Object.fromEntries(Object.entries(args.labels).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) } : {}),
+        ...(args.links?.length ? { links: args.links } : {}),
+        ...(layerEvidence.attachments?.length ? { attachments: layerEvidence.attachments } : {}),
+        ...(args.annotations?.length ? { annotations: args.annotations } : {}),
+        ...(args.extensions && Object.keys(args.extensions).length ? { extensions: args.extensions } : {})
+    };
+    const bundle = entries.size ? await writeBundle(store, (async function* () { for (const entry of [...entries.values()].sort((a, b) => (a.key < b.key ? -1 : 1)))
+        yield entry; })(), 'layers/blobs/') : {};
+    return publishLayerBundle(store, summary, bundle);
+}

package/dist/reports/src/publish.d.ts

@@ -5,50 +5,83 @@ import type { CommitRecord, SourceRecord } from './protocol.js';
 import type { SourceIdentity } from './source-content.js';
 /** The run id every spec suite writes its bucket under. */
 export declare const SPEC_RUN_ID = "latest";
+/** What `openCommit` needs to start a commit's run. */
 export type OpenCommitArgs = {
+    /** The full 40-hex commit sha. */
     readonly sha: string;
     readonly branch: string;
+    /** The CI run publishing this commit, or `null`. */
     readonly runUrl: string | null;
+    /** When the run started, epoch milliseconds; it also orders the commit list (newest first). */
     readonly startedAtMs: number;
     /** Stylesheet the commit's HTML snapshots render with. */
     readonly frameCss: string;
-    /** Concurrent CI attempts own independent commit-local files. */
+    /** Concurrent CI attempts own independent commit-local files. Letters, digits, `.`, `_`, `:` and `-`; see `publicationStore`. */
     readonly publicationId?: string;
 };
 /**
- * Mark a commit's run as started and list it (newest first). Its snapshot
- * stylesheet goes up first, so a test is viewable the moment it lands.
+ * Marks a commit's run as started and lists it (newest first), returning the `running` record.
+ *
+ * Writes the snapshot stylesheet first, so a test is viewable the moment it lands, then `commit.json`, then the
+ * `index/` entry that lists the commit, and, only when `publicationId` is given, last the pointer that tells readers
+ * to look under that attempt. With a `publicationId` the stylesheet and record are written in the attempt's scope, not
+ * the shared one. Calling it again for the same sha and attempt rewrites the same keys. Store errors reject.
  */
 export declare function openCommit(store: ObjectStore, args: OpenCommitArgs): Promise<CommitRecord>;
+/** What `publishSource` needs to publish one package bucket of recorded tests. */
 export type PublishSourceArgs = {
-    /** Execution completion time, separate from a virtual timeline clock. */
+    /** Execution completion time, separate from a virtual timeline clock. Epoch milliseconds. Default: the latest test's `endedAtMs`. */
     readonly recordedAtMs?: number;
+    /** Recorded on the layer: `modified` when the run was from a checkout with uncommitted changes, `unknown` when its origin is unknown. */
     readonly freshness?: 'unknown' | 'modified';
     /** The client this run checked: desktop web, mobile web, iOS, Android, or another recorded name. */
     readonly environment?: string;
+    /** Choices other than the client that make this its own slot (see `LayerParameters`). */
     readonly parameters?: LayerParameters;
+    /** The full 40-hex commit sha the run is for. */
     readonly sha: string;
+    /** Repo-relative package dir; with `bucket` it forms the source id (`libs-chess--part-2`). */
     readonly packageDir: string;
+    /** The bucket under the package's report dir (`part-2`, `all`). */
     readonly bucket: string;
     /** The package's local report bucket (`.cache/harness-report/<bucket>`). */
     readonly local: ObjectStore;
+    /** The run id the tests were written under in `local`. Default: `latest` (`SPEC_RUN_ID`). */
     readonly runId?: string;
     /** Only a passing execution is reusable under its exact task hash. */
     readonly identity?: SourceIdentity;
+    /** Forces the source's status to `failed`; any other value is ignored and the status is computed from the tests. */
     readonly status?: ReportTestStatus;
 };
 /**
- * Copy one package bucket into the store: every test (runner outcomes
- * applied) and its frame files, then the source record, last, so a reader
- * that sees the record can read every test it names. Null when the bucket
- * recorded no test.
+ * Copies one package bucket into the store: every test (runner outcomes from the bucket's `junit.xml` applied) and its
+ * frame files, then the source record last, so a reader that sees the record can read every test it names; finally it
+ * archives the source as an immutable layer. Returns the record, or `null` when the bucket recorded no test and
+ * neither `identity` nor `status` was given.
+ *
+ * The source's status is `failed` when `args.status` is `failed`, else `failed` if any test failed, `skipped` if all
+ * were skipped, else `passed`. A passing source with an `identity` is stored once, content-addressed by its task
+ * hash, and referenced from the commit; any other source gets its files in the commit's bundle. When the bucket has no
+ * `ui-quality` or `performance` part of its own, a `performance` part with a 50 ms allowance is derived from the
+ * tests. Throws on a source id that is not a valid key segment, a part that fails `validatePart`, or a store error;
+ * a failure part-way leaves unreferenced content, never a record that names missing content.
  */
 export declare function publishSource(store: ObjectStore, args: PublishSourceArgs): Promise<SourceRecord | null>;
+/** What `closeCommit` needs to finish a commit's run. */
 export type CloseCommitArgs = {
+    /** The full 40-hex commit sha. */
     readonly sha: string;
+    /** When the run ended, epoch milliseconds. */
     readonly endedAtMs: number;
+    /** The attempt given to `openCommit`, when it was given one. */
     readonly publicationId?: string;
+    /** `failed` forces the commit's status to `failed`; any other value is ignored. */
     readonly status?: ReportTestStatus;
 };
-/** Mark a commit's run complete, with the worst status of its sources. */
+/**
+ * Marks a commit's run `complete` and returns the record, with the worst status of its sources: `failed` if
+ * `args.status` is `failed` or any source failed, `skipped` when there are no sources or all were skipped, else
+ * `passed`. Throws `no open report for <sha>; openCommit runs first` when the commit was never opened. Calling it
+ * again rewrites the record with the sources present at that time.
+ */
 export declare function closeCommit(store: ObjectStore, args: CloseCommitArgs): Promise<CommitRecord>;

package/dist/reports/src/publish.js

@@ -1,3 +1,16 @@
+/**
+ * @module Publishing commit-keyed recordings
+ *
+ * The write side of the older, commit-keyed shared store: what CI runs after a spec suite recorded timelines with
+ * screenshots. `openCommit` starts a commit, `publishSource` copies one package bucket's recorded tests into the store
+ * (and also archives it as an immutable layer, so it composes with every other layer), and `closeCommit` finishes the
+ * commit. Pure over two injected `ObjectStore`s, the local report bucket a test run wrote and the shared store, so it
+ * runs the same against a directory, S3 or memory. Writes go content first, then the record that names it, so a
+ * reader that sees a record can read everything it names. Plain checks from JUnit, CTRF or a checks file do not go
+ * through here: they use `publishChecks`.
+ *
+ * @see docs/report-backends.md
+ */
 import { archiveSourceLayer } from './layer-source.js';
 import { normalizeEnvironment } from './layer-axes.js';
 import { performancePart } from './performance-part.js';
@@ -21,8 +34,12 @@ export const SPEC_RUN_ID = 'latest';
 const WRITE_WIDTH = 32;
 const JSON_TYPE = 'application/json; charset=utf-8';
 /**
- * Mark a commit's run as started and list it (newest first). Its snapshot
- * stylesheet goes up first, so a test is viewable the moment it lands.
+ * Marks a commit's run as started and lists it (newest first), returning the `running` record.
+ *
+ * Writes the snapshot stylesheet first, so a test is viewable the moment it lands, then `commit.json`, then the
+ * `index/` entry that lists the commit, and, only when `publicationId` is given, last the pointer that tells readers
+ * to look under that attempt. With a `publicationId` the stylesheet and record are written in the attempt's scope, not
+ * the shared one. Calling it again for the same sha and attempt rewrites the same keys. Store errors reject.
  */
 export async function openCommit(store, args) {
     const { frameCss, publicationId, ...fields } = args;
@@ -83,10 +100,17 @@ async function publishSnapshots(store, args, tests, contentPrefix) {
     });
 }
 /**
- * Copy one package bucket into the store: every test (runner outcomes
- * applied) and its frame files, then the source record, last, so a reader
- * that sees the record can read every test it names. Null when the bucket
- * recorded no test.
+ * Copies one package bucket into the store: every test (runner outcomes from the bucket's `junit.xml` applied) and its
+ * frame files, then the source record last, so a reader that sees the record can read every test it names; finally it
+ * archives the source as an immutable layer. Returns the record, or `null` when the bucket recorded no test and
+ * neither `identity` nor `status` was given.
+ *
+ * The source's status is `failed` when `args.status` is `failed`, else `failed` if any test failed, `skipped` if all
+ * were skipped, else `passed`. A passing source with an `identity` is stored once, content-addressed by its task
+ * hash, and referenced from the commit; any other source gets its files in the commit's bundle. When the bucket has no
+ * `ui-quality` or `performance` part of its own, a `performance` part with a 50 ms allowance is derived from the
+ * tests. Throws on a source id that is not a valid key segment, a part that fails `validatePart`, or a store error;
+ * a failure part-way leaves unreferenced content, never a record that names missing content.
  */
 export async function publishSource(store, args) {
     const runId = args.runId ?? SPEC_RUN_ID;
@@ -152,7 +176,12 @@ async function sourceEvidence(local, sha, source, tests) {
         validatePart({ ...part, sha, id: source, recordedAtMs: 0 });
     return { evidence };
 }
-/** Mark a commit's run complete, with the worst status of its sources. */
+/**
+ * Marks a commit's run `complete` and returns the record, with the worst status of its sources: `failed` if
+ * `args.status` is `failed` or any source failed, `skipped` when there are no sources or all were skipped, else
+ * `passed`. Throws `no open report for <sha>; openCommit runs first` when the commit was never opened. Calling it
+ * again rewrites the record with the sources present at that time.
+ */
 export async function closeCommit(store, args) {
     if (args.publicationId !== undefined)
         store = publicationStore(store, args.publicationId);

package/dist/reports/src/read.d.ts

@@ -1,60 +1,90 @@
 /**
- * Read side of the shared reports store: what a reports API serves. Pure over
- * an injected {@link ObjectStore}, {@link Clock} and {@link Timers}; nothing
- * here imports a runtime or an HTTP framework.
+ * @module Reading commit-keyed recordings
+ *
+ * The read side of the older, commit-keyed shared store: what the reports API serves for a commit (its record, its
+ * sources, each test's timeline and frame files) and the event streams that deliver them. Pure over an injected
+ * `ObjectStore`, `Clock` and `Timers`; nothing here imports a runtime or an HTTP framework. Every read goes through
+ * `reportStore`, so a commit published by an attempt (`publicationId`) is read from that attempt's records.
+ *
+ * @see docs/report-backends.md
  */
 import type { Clock, Timers } from './clock.js';
 import type { RunReport } from './report-types.js';
 import type { ObjectStore, StoredObject } from './object-store.js';
 import type { CommitEvent, CommitPage, CommitRecord, SourceRecord, TestEvent } from './protocol.js';
+/** Reads a commit's record, or `null` when it is missing or not valid JSON. */
 export declare function readCommit(store: ObjectStore, sha: string): Promise<CommitRecord | null>;
+/** Reads the stylesheet a commit's snapshots render with, or `null` when the commit has none. */
 export declare function readFrameCss(store: ObjectStore, sha: string): Promise<StoredObject | null>;
 /**
- * Newest commits first, `limit` per page. A commit published twice (a rerun)
- * has two index entries; only the newer one is ever listed, on any page.
+ * Lists commits newest first, `limit` per page (at least 1).
+ *
+ * A commit published twice (a rerun) has two index entries; only the newer one is ever listed, on any page.
+ * `cursor` is the previous page's `cursor`; `null` starts at the newest. The returned `cursor` is `null` on the last
+ * page. An index entry whose commit record is missing or unreadable is left out, so a page may hold fewer than
+ * `limit` commits. Store errors reject.
  */
 export declare function listCommits(store: ObjectStore, options: {
     readonly limit: number;
     readonly cursor: string | null;
 }): Promise<CommitPage>;
+/** How `commitEvents` tails a running commit. */
 export type CommitEventsOptions = {
+    /** Time source for `tailMs`. */
     readonly clock: Clock;
+    /** Timer functions used to wait `pollMs` between listings. */
     readonly timers: Timers;
     /** Sources the client already holds (a reconnect): never sent again. */
     readonly have?: ReadonlySet<string>;
-    /** How often a running commit is re-listed for new sources. */
+    /** How often, in milliseconds, a running commit is re-listed for new sources. */
     readonly pollMs: number;
-    /** A running commit's stream ends after this long; the client reconnects. */
+    /** A running commit's stream ends after this many milliseconds; the client reconnects. */
     readonly tailMs: number;
 };
 /**
- * The commit, then every source in the order its read finishes. While the
- * commit is running, its sources are re-listed every `pollMs` and each new
- * one is sent as it lands, until the commit completes or `tailMs` passes.
- * The state is read before each listing, so a listing after `complete` is
- * the final one.
+ * Streams a commit as events: the commit record, then every source in the order its read finishes. While the
+ * commit is running, its sources are re-listed every `pollMs` and each new one is sent as it lands, until the commit
+ * completes or `tailMs` passes. The state is read before each listing, so a listing after `complete` is the final
+ * one. A `commit` event is sent again when the commit's state changes.
+ *
+ * Ends with `{ type: 'end', state }`: `missing` when there is no commit record and no source, `complete` when the
+ * commit closed, `running` when `tailMs` passed first (reconnect with `have` to continue). A source is never sent
+ * twice in one stream, nor one listed in `options.have`. Trap: a source is counted as sent as soon as it is listed,
+ * so one whose record cannot be read at that moment is not retried in the same stream.
  */
 export declare function commitEvents(store: ObjectStore, sha: string, options: CommitEventsOptions): AsyncGenerator<CommitEvent>;
-/** One test's timeline, without its frame files. */
+/**
+ * Reads one test's timeline (`RunReport`) without its frame files, or `null` when the source or test is not in the
+ * commit. A timeline stored as a reusable source is parsed leniently (`null` if not JSON); one in the commit's bundle
+ * throws if its bytes are not JSON.
+ */
 export declare function readTestReport(store: ObjectStore, args: {
     readonly sha: string;
     readonly source: string;
     readonly testId: string;
 }): Promise<RunReport | null>;
+/** One frame file's content. */
 export type FrameBody = {
+    /** The file's bytes. */
     readonly bytes: Uint8Array;
+    /** The media type the file was stored with. */
     readonly contentType: string;
 };
-/** One frame file's bytes, or null when the test never wrote it. */
+/** Reads one frame file of a test, or `null` when the test never wrote it. Throws `Invalid report frame` when `file` is not a safe relative frame path. */
 export declare function readFrameBody(store: ObjectStore, args: {
     readonly sha: string;
     readonly source: string;
     readonly testId: string;
     readonly file: string;
 }): Promise<FrameBody | null>;
-/** Every source record of a commit, in the order each read finishes. */
+/** Lists every source record of a commit, in the order each read finishes. A source whose record cannot be read is left out. */
 export declare function listSourceRecords(store: ObjectStore, sha: string): Promise<SourceRecord[]>;
-/** A test's report, then each of its frame files as its read finishes. */
+/**
+ * Streams a test as events: its report, then each frame file the report names as its read finishes, then
+ * `{ type: 'end', found: true }`. A test that is not in the commit yields only `{ type: 'end', found: false }`. A frame
+ * the report names but the store lacks is skipped. Text media (`html`, `json`, `text`) arrive as inline text, the rest
+ * as base64.
+ */
 export declare function testEvents(store: ObjectStore, args: {
     readonly sha: string;
     readonly source: string;

package/dist/reports/src/read.js

@@ -1,7 +1,12 @@
 /**
- * Read side of the shared reports store: what a reports API serves. Pure over
- * an injected {@link ObjectStore}, {@link Clock} and {@link Timers}; nothing
- * here imports a runtime or an HTTP framework.
+ * @module Reading commit-keyed recordings
+ *
+ * The read side of the older, commit-keyed shared store: what the reports API serves for a commit (its record, its
+ * sources, each test's timeline and frame files) and the event streams that deliver them. Pure over an injected
+ * `ObjectStore`, `Clock` and `Timers`; nothing here imports a runtime or an HTTP framework. Every read goes through
+ * `reportStore`, so a commit published by an attempt (`publicationId`) is read from that attempt's records.
+ *
+ * @see docs/report-backends.md
  */
 import { readUtf8 } from './object-io.js';
 import { inCompletionOrder } from './completion-order.js';
@@ -24,15 +29,21 @@ async function readJson(store, key) {
         return null;
     }
 }
+/** Reads a commit's record, or `null` when it is missing or not valid JSON. */
 export async function readCommit(store, sha) {
     return readJson(await reportStore(store, sha), commitKey(sha));
 }
+/** Reads the stylesheet a commit's snapshots render with, or `null` when the commit has none. */
 export async function readFrameCss(store, sha) {
     return (await reportStore(store, sha)).get(frameCssKey(sha));
 }
 /**
- * Newest commits first, `limit` per page. A commit published twice (a rerun)
- * has two index entries; only the newer one is ever listed, on any page.
+ * Lists commits newest first, `limit` per page (at least 1).
+ *
+ * A commit published twice (a rerun) has two index entries; only the newer one is ever listed, on any page.
+ * `cursor` is the previous page's `cursor`; `null` starts at the newest. The returned `cursor` is `null` on the last
+ * page. An index entry whose commit record is missing or unreadable is left out, so a page may hold fewer than
+ * `limit` commits. Store errors reject.
  */
 export async function listCommits(store, options) {
     const seen = new Set();
@@ -73,11 +84,15 @@ async function* newSources(store, sha, sent) {
     }
 }
 /**
- * The commit, then every source in the order its read finishes. While the
- * commit is running, its sources are re-listed every `pollMs` and each new
- * one is sent as it lands, until the commit completes or `tailMs` passes.
- * The state is read before each listing, so a listing after `complete` is
- * the final one.
+ * Streams a commit as events: the commit record, then every source in the order its read finishes. While the
+ * commit is running, its sources are re-listed every `pollMs` and each new one is sent as it lands, until the commit
+ * completes or `tailMs` passes. The state is read before each listing, so a listing after `complete` is the final
+ * one. A `commit` event is sent again when the commit's state changes.
+ *
+ * Ends with `{ type: 'end', state }`: `missing` when there is no commit record and no source, `complete` when the
+ * commit closed, `running` when `tailMs` passed first (reconnect with `have` to continue). A source is never sent
+ * twice in one stream, nor one listed in `options.have`. Trap: a source is counted as sent as soon as it is listed,
+ * so one whose record cannot be read at that moment is not retried in the same stream.
  */
 export async function* commitEvents(store, sha, options) {
     const startedAt = options.clock.now();
@@ -133,7 +148,11 @@ function frameBlob(obj, media) {
         }
         : { contentType: obj.contentType, base64: bytesToBase64(obj.bytes) };
 }
-/** One test's timeline, without its frame files. */
+/**
+ * Reads one test's timeline (`RunReport`) without its frame files, or `null` when the source or test is not in the
+ * commit. A timeline stored as a reusable source is parsed leniently (`null` if not JSON); one in the commit's bundle
+ * throws if its bytes are not JSON.
+ */
 export async function readTestReport(store, args) {
     store = await reportStore(store, args.sha);
     const prefix = await sourceTestPrefix(store, args);
@@ -147,7 +166,7 @@ export async function readTestReport(store, args) {
         ? null
         : JSON.parse(new TextDecoder().decode(obj.bytes));
 }
-/** One frame file's bytes, or null when the test never wrote it. */
+/** Reads one frame file of a test, or `null` when the test never wrote it. Throws `Invalid report frame` when `file` is not a safe relative frame path. */
 export async function readFrameBody(store, args) {
     store = await reportStore(store, args.sha);
     if (!isFramePath(args.file))
@@ -164,7 +183,7 @@ export async function readFrameBody(store, args) {
         ? null
         : { bytes: obj.bytes, contentType: obj.contentType };
 }
-/** Every source record of a commit, in the order each read finishes. */
+/** Lists every source record of a commit, in the order each read finishes. A source whose record cannot be read is left out. */
 export async function listSourceRecords(store, sha) {
     const out = [];
     for await (const source of newSources(store, sha, new Set())) {
@@ -172,7 +191,12 @@ export async function listSourceRecords(store, sha) {
     }
     return out;
 }
-/** A test's report, then each of its frame files as its read finishes. */
+/**
+ * Streams a test as events: its report, then each frame file the report names as its read finishes, then
+ * `{ type: 'end', found: true }`. A test that is not in the commit yields only `{ type: 'end', found: false }`. A frame
+ * the report names but the store lacks is skipped. Text media (`html`, `json`, `text`) arrive as inline text, the rest
+ * as base64.
+ */
 export async function* testEvents(store, args) {
     store = await reportStore(store, args.sha);
     const prefix = await sourceTestPrefix(store, args);

package/dist/reports/src/recording-bundle.d.ts

@@ -1,22 +1,33 @@
 /**
- * A report test with its frame files in memory: what a viewer renders. Text
- * media are inline, binary media base64.
+ * @module In-memory recorded test
+ *
+ * Types for a recorded test with its frame files held in memory, which is what a viewer renders and what a publisher
+ * copies: text media inline, binary media as base64.
  */
 import type { ReportTestStatus, RunReport } from './report-types.js';
 /** One embedded frame file: text media inline, binary media as base64. */
 export type HtmlReportBlob = {
+    /** The media type of the file. */
     readonly contentType: string;
+    /** The file's content for text media. */
     readonly text?: string;
+    /** The file's content for binary media, base64-encoded. */
     readonly base64?: string;
 };
+/** One recorded test: its timeline and its frame files. */
 export type HtmlReportTest = {
+    /** The test's timeline. */
     readonly report: RunReport;
     /** Keyed by the blob's `file` (relative to the test dir). */
     readonly blobs: Readonly<Record<string, HtmlReportBlob>>;
 };
+/** The tests of one run held in memory. */
 export type HtmlReportBundle = {
     readonly runId: string;
+    /** The run's overall outcome. */
     readonly status: ReportTestStatus;
+    /** When the run was last updated, epoch milliseconds. */
     readonly updatedAtMs: number;
+    /** The run's tests. */
     readonly tests: readonly HtmlReportTest[];
 };

package/dist/reports/src/recording-bundle.js

@@ -1,4 +1,6 @@
 /**
- * A report test with its frame files in memory: what a viewer renders. Text
- * media are inline, binary media base64.
+ * @module In-memory recorded test
+ *
+ * Types for a recorded test with its frame files held in memory, which is what a viewer renders and what a publisher
+ * copies: text media inline, binary media as base64.
  */

package/dist/reports/src/recording-keys.d.ts

@@ -1,9 +1,23 @@
-/** Object-store key layout for one report bucket. */
+/**
+ * @module Key layout of one report bucket
+ *
+ * Where a test run writes its recordings inside one local report bucket (an `ObjectStore`): `runs/index.json`,
+ * `runs/<runId>/manifest.json` and `runs/<runId>/tests/<testId>/report.json` plus the test's frame files beside it.
+ * Pure string functions. Neither id is validated here; callers sanitise them (`sanitizeRunId`, `sanitizeTestId`).
+ */
+/** The key of the index of the runs in a bucket. */
 export declare const RUNS_INDEX_KEY = "runs/index.json";
+/** The key prefix of one run, without a trailing slash: `runs/<runId>`. */
 export declare function runPrefix(runId: string): string;
+/** The key of a run's manifest: `runs/<runId>/manifest.json`. */
 export declare function runManifestKey(runId: string): string;
+/** The key prefix of one test, without a trailing slash: `runs/<runId>/tests/<testId>`. With an empty `testId` it ends in `/tests/`, which lists all tests of the run. */
 export declare function testPrefix(runId: string, testId: string): string;
+/** The key of a test's timeline: `runs/<runId>/tests/<testId>/report.json`. */
 export declare function testReportKey(runId: string, testId: string): string;
+/** The key of one frame file of a test: the test prefix and `frameFile` with any leading `/` removed. With an empty `frameFile` it is the test's prefix with a trailing slash. */
 export declare function testFrameKey(runId: string, testId: string, frameFile: string): string;
+/** The file extension for a snapshot media kind (`html`, `png`, `json`, `txt`, `bin`, `mp4`); an unknown kind is `bin`. */
 export declare function mediaExtension(media: string): string;
+/** The media type for a snapshot media kind (`html`, `png`, `json`, `text`, `bytes`, `video`); an unknown kind is `application/octet-stream`. */
 export declare function contentTypeForMedia(media: string): string;

package/dist/reports/src/recording-keys.js

@@ -1,21 +1,34 @@
-/** Object-store key layout for one report bucket. */
+/**
+ * @module Key layout of one report bucket
+ *
+ * Where a test run writes its recordings inside one local report bucket (an `ObjectStore`): `runs/index.json`,
+ * `runs/<runId>/manifest.json` and `runs/<runId>/tests/<testId>/report.json` plus the test's frame files beside it.
+ * Pure string functions. Neither id is validated here; callers sanitise them (`sanitizeRunId`, `sanitizeTestId`).
+ */
+/** The key of the index of the runs in a bucket. */
 export const RUNS_INDEX_KEY = 'runs/index.json';
+/** The key prefix of one run, without a trailing slash: `runs/<runId>`. */
 export function runPrefix(runId) {
     return `runs/${runId}`;
 }
+/** The key of a run's manifest: `runs/<runId>/manifest.json`. */
 export function runManifestKey(runId) {
     return `${runPrefix(runId)}/manifest.json`;
 }
+/** The key prefix of one test, without a trailing slash: `runs/<runId>/tests/<testId>`. With an empty `testId` it ends in `/tests/`, which lists all tests of the run. */
 export function testPrefix(runId, testId) {
     return `${runPrefix(runId)}/tests/${testId}`;
 }
+/** The key of a test's timeline: `runs/<runId>/tests/<testId>/report.json`. */
 export function testReportKey(runId, testId) {
     return `${testPrefix(runId, testId)}/report.json`;
 }
+/** The key of one frame file of a test: the test prefix and `frameFile` with any leading `/` removed. With an empty `frameFile` it is the test's prefix with a trailing slash. */
 export function testFrameKey(runId, testId, frameFile) {
     const rel = frameFile.replace(/^\/+/, '');
     return `${testPrefix(runId, testId)}/${rel}`;
 }
+/** The file extension for a snapshot media kind (`html`, `png`, `json`, `txt`, `bin`, `mp4`); an unknown kind is `bin`. */
 export function mediaExtension(media) {
     switch (media) {
         case 'html':
@@ -34,6 +47,7 @@ export function mediaExtension(media) {
             return 'bin';
     }
 }
+/** The media type for a snapshot media kind (`html`, `png`, `json`, `text`, `bytes`, `video`); an unknown kind is `application/octet-stream`. */
 export function contentTypeForMedia(media) {
     switch (media) {
         case 'html':