@crvouga/atlas 0.4.0 → 0.5.0

package/dist/reports/src/snapshot-surface.d.ts

@@ -1,27 +1,38 @@
 import type { ReportStepHit } from './report-types.js';
+/** What drawing a press target found: `none` (no target to draw), `found` (target located, overlay drawn) or `missing` (the path does not resolve in the painted snapshot, overlay hidden). */
 export type HitResult = 'none' | 'found' | 'missing';
 /**
- * Point `html` / `body` / `:root` at the phone viewport, and turn a full
- * browser viewport unit into a percentage of that box.
+ * Rewrites snapshot CSS so it applies inside the phone surface: the selectors `html` and `:root` become `.sr-snap-doc`,
+ * `body` becomes `.sr-snap-body`, and the viewport units `100vh`, `100vw` (and their `d`, `s`, `l` variants) become
+ * `100%` of that box. A regex rewrite, so it is approximate for unusual selectors.
  */
 export declare function scopeSnapshotCss(css: string): string;
-/** Make sure `doc` is our standards-mode shell with `frameCss` installed. */
+/** Makes `doc` the standards-mode shell with `frameCss` installed, replacing its content, unless it already is one. Does nothing when the shell's stylesheet is present, so a later different `frameCss` is not applied. */
 export declare function ensureShell(doc: Document, frameCss: string): void;
-/** Chained first match — mirrors how the UI driver resolves `get(a).get(b)`. */
+/**
+ * Finds the element a gesture targeted: the first `[data-testid]` match of `path[0]` inside `scope`, then the first
+ * match of `path[1]` inside that, and so on. Returns `null` as soon as a step has no match, and for an empty path
+ * returns `null` too. Mirrors how the UI driver resolves `get(a).get(b)`.
+ */
 export declare function resolveHitTarget(scope: ParentNode, path: readonly string[]): Element | null;
-/** Draw the one press overlay on `hit`'s target. */
+/** Draws the one press overlay (a box and a dot at `hit.point`, default the centre) on `hit`'s target in a document, scrolling the target into view if it is outside the viewport. Returns what it found; with no hit it hides the overlay. */
 export declare function drawHit(doc: Document, hit: ReportStepHit | null): HitResult;
 /**
- * Paint one snapshot into `doc` (already a shell) and draw `hit`. `key`
- * identifies the snapshot for parse caching.
+ * Paints one snapshot into `doc` (already a shell, see `ensureShell`) and draws `hit`. `key` identifies the snapshot for
+ * parse caching (256 entries, oldest dropped first): it must change whenever `html` does, or the earlier parse is
+ * reused.
  */
 export declare function paintSnapshot(doc: Document, snap: {
     readonly key: string;
     readonly html: string;
 }, hit: ReportStepHit | null): HitResult;
-/** In-page snapshot surface. No iframe. */
+/** Creates the in-page snapshot surface: a `div.sr-snap` with an open shadow tree, sized to the phone viewport, ready for `paintSnapshotHost`. No iframe. */
 export declare function createSnapshotHost(): HTMLDivElement;
-/** Paint one snapshot into the shadow tree `createSnapshotHost` built. */
+/**
+ * Paints one snapshot into the shadow tree `createSnapshotHost` built, installs `snap.css` (the frame stylesheet) and
+ * draws `hit`. Painting is skipped, and only the overlay redrawn, when the same `key` and `html` were painted last.
+ * Returns `none` when `host` was not built by `createSnapshotHost`.
+ */
 export declare function paintSnapshotHost(host: HTMLElement, snap: {
     readonly key: string;
     readonly html: string;

package/dist/reports/src/snapshot-surface.js

@@ -1,16 +1,19 @@
-import { cleanSnapshotHtml, PHONE_H, PHONE_W, } from './phone.js';
 /**
- * One long-lived snapshot surface per client panel. Frames are painted by
- * swapping the parsed snapshot DOM into that surface synchronously, so
- * scrubbing never re-parses `frameCss` or refetches fonts. The press target
- * is resolved against the painted DOM with the driver's chained first-match
- * semantics and drawn as a single overlay from real layout.
+ * @module Snapshot surface
+ *
+ * Paints recorded page snapshots (HTML captured at each step of a test) into a phone-sized surface in the viewer and
+ * draws the press target of a gesture on top. One long-lived surface per client panel: frames are painted by swapping
+ * the parsed snapshot DOM into that surface synchronously, so scrubbing never re-parses `frameCss` or refetches fonts.
+ * The press target is resolved against the painted DOM with the driver's chained first-match semantics and drawn as a
+ * single overlay from real layout.
  *
- * The phone paints into an open shadow tree, not an iframe: embedded
- * browsers drop iframe documents, and a shadow tree stays in the page.
- * Snapshot styles sit on the shadow root, and the host is the 390×844
- * viewport the app shell fills.
+ * The phone paints into an open shadow tree, not an iframe: embedded browsers drop iframe documents, and a shadow tree
+ * stays in the page. Snapshot styles sit on the shadow root, and the host is the 390x844 viewport the app shell fills.
+ * Browser-only: needs `document`, `DOMParser` and shadow DOM. Snapshot HTML comes from a test run and is untrusted;
+ * `<script>` elements are removed (`cleanSnapshotHtml`) but nothing else is sanitised, so show it only in a context you
+ * would show that run's pages in.
  */
+import { cleanSnapshotHtml, PHONE_H, PHONE_W, } from './phone.js';
 const FRAME_CSS_ID = 'sr-frame-css';
 const OVERLAY_ID = 'sr-press';
 const SNAP_ATTR = 'data-sr-snap';
@@ -18,8 +21,9 @@ const PARSE_CACHE_MAX = 256;
 const OVERLAY_CSS = `#${OVERLAY_ID}{position:absolute;display:none;pointer-events:none;z-index:2147483647;box-sizing:border-box;border:2px solid #ff5a8a;border-radius:6px;box-shadow:0 0 0 4px rgba(255,90,138,.35)}#${OVERLAY_ID} i{position:absolute;width:14px;height:14px;margin:-7px 0 0 -7px;border-radius:50%;background:#ff5a8a;box-shadow:0 0 0 4px rgba(255,90,138,.35)}`;
 const parseCache = new Map();
 /**
- * Point `html` / `body` / `:root` at the phone viewport, and turn a full
- * browser viewport unit into a percentage of that box.
+ * Rewrites snapshot CSS so it applies inside the phone surface: the selectors `html` and `:root` become `.sr-snap-doc`,
+ * `body` becomes `.sr-snap-body`, and the viewport units `100vh`, `100vw` (and their `d`, `s`, `l` variants) become
+ * `100%` of that box. A regex rewrite, so it is approximate for unusual selectors.
  */
 export function scopeSnapshotCss(css) {
     const scoped = css.replace(/(^|[^\w-])(:root|html|body)(?![\w-])/g, (_match, prefix, token) => `${prefix}${token === 'body' ? '.sr-snap-body' : '.sr-snap-doc'}`);
@@ -56,7 +60,7 @@ function shellHtml(frameCss) {
     const base = `html,body{margin:0}html{position:relative}${OVERLAY_CSS}`;
     return `<!DOCTYPE html><html><head><meta charset="utf-8"><style id="${FRAME_CSS_ID}">${frameCss}${base}</style></head><body></body></html>`;
 }
-/** Make sure `doc` is our standards-mode shell with `frameCss` installed. */
+/** Makes `doc` the standards-mode shell with `frameCss` installed, replacing its content, unless it already is one. Does nothing when the shell's stylesheet is present, so a later different `frameCss` is not applied. */
 export function ensureShell(doc, frameCss) {
     if (doc.getElementById(FRAME_CSS_ID))
         return;
@@ -148,7 +152,11 @@ function syncHead(root, parsed) {
 function testIdSelector(id) {
     return `[data-testid="${id.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"]`;
 }
-/** Chained first match — mirrors how the UI driver resolves `get(a).get(b)`. */
+/**
+ * Finds the element a gesture targeted: the first `[data-testid]` match of `path[0]` inside `scope`, then the first
+ * match of `path[1]` inside that, and so on. Returns `null` as soon as a step has no match, and for an empty path
+ * returns `null` too. Mirrors how the UI driver resolves `get(a).get(b)`.
+ */
 export function resolveHitTarget(scope, path) {
     let current = scope;
     let found = null;
@@ -224,7 +232,7 @@ function drawOn(root, hit) {
     placeOverlay(root, target, hit);
     return 'found';
 }
-/** Draw the one press overlay on `hit`'s target. */
+/** Draws the one press overlay (a box and a dot at `hit.point`, default the centre) on `hit`'s target in a document, scrolling the target into view if it is outside the viewport. Returns what it found; with no hit it hides the overlay. */
 export function drawHit(doc, hit) {
     if (!doc.getElementById('sr-overlay-css')) {
         const style = doc.createElement('style');
@@ -246,8 +254,9 @@ function paintRoot(root, snap, hit) {
     return drawOn(root, hit);
 }
 /**
- * Paint one snapshot into `doc` (already a shell) and draw `hit`. `key`
- * identifies the snapshot for parse caching.
+ * Paints one snapshot into `doc` (already a shell, see `ensureShell`) and draws `hit`. `key` identifies the snapshot for
+ * parse caching (256 entries, oldest dropped first): it must change whenever `html` does, or the earlier parse is
+ * reused.
  */
 export function paintSnapshot(doc, snap, hit) {
     return paintRoot(documentRoot(doc), snap, hit);
@@ -272,7 +281,7 @@ const HOST_LAYOUT = [
     '#root>.themeHost,.dom-root>.themeHost,.dom-root>*>.themeHost',
     `{${HOST_FILL}}`,
 ].join('');
-/** In-page snapshot surface. No iframe. */
+/** Creates the in-page snapshot surface: a `div.sr-snap` with an open shadow tree, sized to the phone viewport, ready for `paintSnapshotHost`. No iframe. */
 export function createSnapshotHost() {
     const host = document.createElement('div');
     host.className = 'sr-snap';
@@ -322,7 +331,11 @@ function installHostCss(root, frameCss) {
     if (style.textContent !== next)
         style.textContent = next;
 }
-/** Paint one snapshot into the shadow tree `createSnapshotHost` built. */
+/**
+ * Paints one snapshot into the shadow tree `createSnapshotHost` built, installs `snap.css` (the frame stylesheet) and
+ * draws `hit`. Painting is skipped, and only the overlay redrawn, when the same `key` and `html` were painted last.
+ * Returns `none` when `host` was not built by `createSnapshotHost`.
+ */
 export function paintSnapshotHost(host, snap, hit) {
     const root = hostRoot(host);
     if (!root)

package/dist/reports/src/source-content.d.ts

@@ -1,27 +1,50 @@
 import type { ObjectStore } from './object-store.js';
 import type { SourceRecord } from './protocol.js';
+/** What makes a recorded source reusable: the exact task that produced it, within a retention window. */
 export type SourceIdentity = {
+    /** The hash of the exact task that produced the source: 16 to 64 lowercase hex digits. */
     readonly taskHash: string;
+    /** The retention window the source belongs to, from `reportGeneration`. A new generation never reuses an older copy, so old content can expire. */
     readonly generation: number;
 };
 type SourceReference = {
     readonly record: SourceRecord;
     readonly contentPrefix: string;
 };
+/** The retention window index for a time: `floor(nowMs / (retentionDays * 86 400 000))`. Throws `Report time must be nonnegative` for a negative or non-finite time and `Report retention must be a positive number of days` for a non-integer or less than 1. */
 export declare function reportGeneration(nowMs: number, retentionDays: number): number;
+/**
+ * The key prefix of a reusable source's content: `content/v2/<generation>/<taskHash>/<source>/`. Throws
+ * `Report identity needs an exact task hash`, `Report generation must be a nonnegative integer` or `Invalid report
+ * source` when an input is malformed.
+ */
 export declare function sourceContentPrefix(identity: SourceIdentity, source: string): string;
+/** Points a commit's source record at reusable content: writes `commits/<sha>/sources/<source>.json` as `{ record, contentPrefix }`. */
 export declare function attachSource(store: ObjectStore, args: {
     readonly sha: string;
     readonly record: SourceRecord;
     readonly contentPrefix: string;
 }): Promise<void>;
+/**
+ * Reuses an earlier passing run of the same task: when the content for `identity` is complete in the store, attaches it
+ * to `sha` and returns its record; otherwise returns `null` and writes nothing. Returns `null` also when the stored
+ * record is for another package or bucket, or did not pass. Throws for a malformed identity or a stored record that is
+ * not JSON.
+ */
 export declare function reuseSource(store: ObjectStore, args: {
     readonly sha: string;
     readonly packageDir: string;
     readonly bucket: string;
     readonly identity: SourceIdentity;
 }): Promise<SourceRecord | null>;
+/**
+ * Reads a commit's record of one source and where its test files live, or `null` when the commit has no such source.
+ * A reference written by `attachSource` yields its content prefix; a plain record yields
+ * `commits/<sha>/tests/<source>/`. Throws `Invalid report content reference` when a reference's prefix does not match
+ * the expected pattern or names another source.
+ */
 export declare function readStoredSource(store: ObjectStore, sha: string, source: string): Promise<SourceReference | null>;
+/** The key prefix of one test's files, `<content prefix><testId>/`, or `null` when the source is not in the commit. Throws `Invalid report test` when `testId` is not a safe key segment. */
 export declare function sourceTestPrefix(store: ObjectStore, args: {
     readonly sha: string;
     readonly source: string;

package/dist/reports/src/source-content.js

@@ -1,7 +1,17 @@
-/** A source can own commit-local files or reference a reusable complete source. */
+/**
+ * @module Source content references
+ *
+ * A source (one package bucket of recorded tests in a commit) either owns commit-local files under
+ * `commits/<sha>/tests/<source>/`, or references a reusable, content-addressed copy under
+ * `content/v2/<generation>/<taskHash>/<source>/` that an identical earlier passing run already uploaded. This module
+ * names those prefixes, writes and resolves the reference, and decides when a copy is reusable. Only a passing source
+ * is ever reused, and a reference whose prefix does not fit the pattern is rejected, so a record cannot point a reader
+ * at another path.
+ */
 import { readUtf8, writeUtf8 } from './object-io.js';
 import { commitPrefix, isKeySegment, sourceId, sourceKey } from './keys.js';
 import { reportStore } from './publication.js';
+/** The retention window index for a time: `floor(nowMs / (retentionDays * 86 400 000))`. Throws `Report time must be nonnegative` for a negative or non-finite time and `Report retention must be a positive number of days` for a non-integer or less than 1. */
 export function reportGeneration(nowMs, retentionDays) {
     if (!Number.isFinite(nowMs) || nowMs < 0)
         throw new Error('Report time must be nonnegative');
@@ -9,6 +19,11 @@ export function reportGeneration(nowMs, retentionDays) {
         throw new Error('Report retention must be a positive number of days');
     return Math.floor(nowMs / (retentionDays * 86_400_000));
 }
+/**
+ * The key prefix of a reusable source's content: `content/v2/<generation>/<taskHash>/<source>/`. Throws
+ * `Report identity needs an exact task hash`, `Report generation must be a nonnegative integer` or `Invalid report
+ * source` when an input is malformed.
+ */
 export function sourceContentPrefix(identity, source) {
     if (!/^[0-9a-f]{16,64}$/.test(identity.taskHash))
         throw new Error('Report identity needs an exact task hash');
@@ -18,9 +33,16 @@ export function sourceContentPrefix(identity, source) {
         throw new Error('Invalid report source');
     return `content/v2/${identity.generation}/${identity.taskHash}/${source}/`;
 }
+/** Points a commit's source record at reusable content: writes `commits/<sha>/sources/<source>.json` as `{ record, contentPrefix }`. */
 export async function attachSource(store, args) {
     await writeUtf8(store, sourceKey(args.sha, args.record.source), JSON.stringify({ record: args.record, contentPrefix: args.contentPrefix }), 'application/json; charset=utf-8');
 }
+/**
+ * Reuses an earlier passing run of the same task: when the content for `identity` is complete in the store, attaches it
+ * to `sha` and returns its record; otherwise returns `null` and writes nothing. Returns `null` also when the stored
+ * record is for another package or bucket, or did not pass. Throws for a malformed identity or a stored record that is
+ * not JSON.
+ */
 export async function reuseSource(store, args) {
     const source = sourceId(args.packageDir, args.bucket);
     const contentPrefix = sourceContentPrefix(args.identity, source);
@@ -36,6 +58,12 @@ export async function reuseSource(store, args) {
     await attachSource(store, { sha: args.sha, record, contentPrefix });
     return record;
 }
+/**
+ * Reads a commit's record of one source and where its test files live, or `null` when the commit has no such source.
+ * A reference written by `attachSource` yields its content prefix; a plain record yields
+ * `commits/<sha>/tests/<source>/`. Throws `Invalid report content reference` when a reference's prefix does not match
+ * the expected pattern or names another source.
+ */
 export async function readStoredSource(store, sha, source) {
     store = await reportStore(store, sha);
     const text = await readUtf8(store, sourceKey(sha, source));
@@ -55,6 +83,7 @@ export async function readStoredSource(store, sha, source) {
         contentPrefix: `${commitPrefix(sha)}tests/${source}/`,
     };
 }
+/** The key prefix of one test's files, `<content prefix><testId>/`, or `null` when the source is not in the commit. Throws `Invalid report test` when `testId` is not a safe key segment. */
 export async function sourceTestPrefix(store, args) {
     if (!isKeySegment(args.testId))
         throw new Error('Invalid report test');

package/dist/reports/src/source-entries.d.ts

@@ -1,4 +1,17 @@
+/**
+ * @module Source file entries
+ *
+ * Streams the files of a recorded source (each test's timeline and its captured frame files) as bundle entries ready to
+ * be packed into blobs. Entries come in a fixed order (tests by id, files by name) so the same source always packs into
+ * the same blobs.
+ */
 import type { HtmlReportTest } from './recording-bundle.js';
 import type { BundleEntry } from './bundle.js';
 import type { PublishSourceArgs } from './publish.js';
+/**
+ * Yields, for each test of `tests` in `testId` order, its `report.json` and then each file the report names (sorted by
+ * name), keyed by the commit-relative layout `commits/<sha>/tests/<source>/<testId>/...`. Frame files are read from
+ * `args.local` under `runId` as the generator is consumed, one at a time. Throws `Missing report snapshot: <file>` when
+ * a named file is absent locally, and a `not a ...` error for an unsafe source, test id or file name.
+ */
 export declare function sourceEntries(args: PublishSourceArgs, source: string, tests: readonly HtmlReportTest[], runId: string): AsyncGenerator<BundleEntry>;

package/dist/reports/src/source-entries.js

@@ -2,6 +2,12 @@ import { testFrameKey } from './recording-keys.js';
 import { capturedFiles } from './frames.js';
 import { remoteTestFileKey, remoteTestReportKey } from './keys.js';
 const JSON_TYPE = 'application/json; charset=utf-8';
+/**
+ * Yields, for each test of `tests` in `testId` order, its `report.json` and then each file the report names (sorted by
+ * name), keyed by the commit-relative layout `commits/<sha>/tests/<source>/<testId>/...`. Frame files are read from
+ * `args.local` under `runId` as the generator is consumed, one at a time. Throws `Missing report snapshot: <file>` when
+ * a named file is absent locally, and a `not a ...` error for an unsafe source, test id or file name.
+ */
 export async function* sourceEntries(args, source, tests, runId) {
     for (const { report } of [...tests].sort((a, b) => a.report.meta.testId < b.report.meta.testId ? -1 : 1)) {
         const { testId } = report.meta;

package/dist/reports/src/source-part.d.ts

@@ -1,4 +1,19 @@
+/**
+ * @module Report parts of a recorded source
+ *
+ * Turns a recorded source (a package bucket's tests with their outcomes) into the report parts (checks grouped by kind)
+ * that become a layer's `parts`. Fail-closed: a source that failed as a whole always carries at least one failed check,
+ * so recorded passes cannot hide a producer that did not complete.
+ */
 import type { ReportPart } from './explorer-types.js';
 import type { SourceRecord } from './protocol.js';
+/**
+ * The main part of a source: its own evidence part (the first one that is not `performance`) re-keyed to the source,
+ * or else one check per test. Check ids become `<source>/<testId>` so two packages can name a test alike. The part's
+ * `kind` is `ui-quality` for the `ui-quality` bucket and `behavior` otherwise (unless its evidence says otherwise); a
+ * skipped test is `not-run`. When the source failed but no check did, a failing `<source>:producer-failure` check is
+ * added.
+ */
 export declare function sourcePart(sha: string, source: SourceRecord): ReportPart;
+/** The parts of a source: `sourcePart`, then each `performance` evidence part as its own part with id `<source>--performance`, re-keyed to the source's time and check ids. */
 export declare function sourceParts(sha: string, source: SourceRecord): readonly ReportPart[];

package/dist/reports/src/source-part.js

@@ -1,4 +1,11 @@
 import { viewerTestId } from './keys.js';
+/**
+ * The main part of a source: its own evidence part (the first one that is not `performance`) re-keyed to the source,
+ * or else one check per test. Check ids become `<source>/<testId>` so two packages can name a test alike. The part's
+ * `kind` is `ui-quality` for the `ui-quality` bucket and `behavior` otherwise (unless its evidence says otherwise); a
+ * skipped test is `not-run`. When the source failed but no check did, a failing `<source>:producer-failure` check is
+ * added.
+ */
 export function sourcePart(sha, source) {
     const kind = source.bucket === 'ui-quality' ? 'ui-quality' : 'behavior';
     const primary = source.evidence?.find((part) => part.kind !== 'performance');
@@ -47,6 +54,7 @@ function withProducerFailure(part, source) {
         ],
     };
 }
+/** The parts of a source: `sourcePart`, then each `performance` evidence part as its own part with id `<source>--performance`, re-keyed to the source's time and check ids. */
 export function sourceParts(sha, source) {
     return [
         sourcePart(sha, source),

package/dist/reports/src/source-reader.d.ts

@@ -1,5 +1,16 @@
+/**
+ * @module Reading a source's files
+ *
+ * Chooses how to read the files of one source of a commit: through its bundle index when it has one, otherwise as
+ * individual objects (stores written before bundles existed stay readable).
+ */
 import type { ObjectStore } from './object-store.js';
 import type { BundleEntry } from './bundle.js';
+/**
+ * Returns a function that reads one file of a source by key, resolving to its bytes and media type or `null` when it is
+ * absent. Reads through the bundle index at `commits/<sha>/bundles/<source>.json` when that has entries, otherwise reads
+ * the key directly from `store`. Throws when the index is present but not JSON.
+ */
 export declare function sourceReader(store: ObjectStore, args: {
     sha: string;
     source: string;

package/dist/reports/src/source-reader.js

@@ -1,4 +1,9 @@
 import { bundleIndexKey, createBundleReader, readBundleIndex } from './bundle.js';
+/**
+ * Returns a function that reads one file of a source by key, resolving to its bytes and media type or `null` when it is
+ * absent. Reads through the bundle index at `commits/<sha>/bundles/<source>.json` when that has entries, otherwise reads
+ * the key directly from `store`. Throws when the index is present but not JSON.
+ */
 export async function sourceReader(store, args) {
     const index = await readBundleIndex(store, bundleIndexKey(args.sha, args.source));
     if (Object.keys(index).length > 0)

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

@@ -1,6 +1,16 @@
+/**
+ * @module Matching recorded tests to specs
+ *
+ * Small lookups from a spec to the recorded tests that ran it, by the source file each test reports. Pure functions
+ * over `HtmlReportTest`.
+ */
 import type { HtmlReportTest } from './recording-bundle.js';
 import type { SpecEntry } from './explorer-types.js';
-/** Resolve original spec paths, including runner absolute paths, without matching another document. */
+/** The tests whose reported `sourceFile` is the spec's path or ends with `/<path>` (so a runner's absolute path matches), after turning backslashes into `/`. A longer name that merely ends with the same letters does not match. */
 export declare function testsForSpec(entry: SpecEntry, tests: readonly HtmlReportTest[]): readonly HtmlReportTest[];
-/** Build once for the inventory; large suites never scan all tests per row. */
+/**
+ * Counts recorded tests per spec path in one pass, so large suites never scan all tests per row. A test's path is its
+ * `sourceFile` (with backslashes turned into `/`) from the first occurrence of `specs/`, wherever that occurs, or the whole
+ * path when there is none; tests with no `sourceFile` are not counted.
+ */
 export declare function specEvidenceCounts(tests: readonly HtmlReportTest[]): ReadonlyMap<string, number>;

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

@@ -1,11 +1,15 @@
-/** Resolve original spec paths, including runner absolute paths, without matching another document. */
+/** The tests whose reported `sourceFile` is the spec's path or ends with `/<path>` (so a runner's absolute path matches), after turning backslashes into `/`. A longer name that merely ends with the same letters does not match. */
 export function testsForSpec(entry, tests) {
     return tests.filter((test) => {
         const path = test.report.meta.sourceFile?.replaceAll('\\', '/') ?? '';
         return path === entry.path || path.endsWith(`/${entry.path}`);
     });
 }
-/** Build once for the inventory; large suites never scan all tests per row. */
+/**
+ * Counts recorded tests per spec path in one pass, so large suites never scan all tests per row. A test's path is its
+ * `sourceFile` (with backslashes turned into `/`) from the first occurrence of `specs/`, wherever that occurs, or the whole
+ * path when there is none; tests with no `sourceFile` are not counted.
+ */
 export function specEvidenceCounts(tests) {
     const counts = new Map();
     for (const test of tests) {

package/dist/reports/src/spec-inventory.d.ts

@@ -1,8 +1,20 @@
 import type { ObjectStore } from './object-store.js';
 import type { SpecEntry, SpecInventory } from './explorer-types.js';
+/** Whether `path` is a safe spec path: starts with `specs/` and no segment is empty, `.`, `..`, or contains a backslash or control character. */
 export declare function isSpecPath(path: string): boolean;
+/**
+ * Describes one spec document: its `path`, a text `fingerprint`, a `kind` (the file extension, `openslo` for
+ * `*.openslo.yaml`, `document` when there is none), a `title` (the first `Feature:` line, else the first `# ` heading,
+ * else the file name) and a `domain` (the folder right under `specs/`, or `Overview` for a file directly in it).
+ * Throws `Invalid spec path` unless `isSpecPath(path)`.
+ */
 export declare function specEntry(path: string, content: string): SpecEntry;
-/** Publish document bodies first; an inventory always names readable content. */
+/**
+ * Publishes a commit's spec documents and its inventory, and returns the inventory (entries sorted by path).
+ * Publish document bodies first; an inventory always names readable content. Throws `Duplicate spec` for a repeated
+ * path (before writing anything), `Invalid spec path` or `Invalid commit` for malformed input. Publishing the same
+ * documents again writes the same keys.
+ */
 export declare function publishInventory(store: ObjectStore, args: {
     readonly sha: string;
     readonly documents: readonly {
@@ -10,5 +22,7 @@ export declare function publishInventory(store: ObjectStore, args: {
         readonly content: string;
     }[];
 }): Promise<SpecInventory>;
+/** Reads a commit's inventory, or `null` when it has none. Throws `Invalid spec inventory` when the stored one is for another sha, malformed, or names an unsafe path, and `Invalid commit` for a bad sha. */
 export declare function readInventory(store: ObjectStore, sha: string): Promise<SpecInventory | null>;
+/** Reads one spec document's text, or `null` when the commit has no inventory or the inventory does not list `path`. Throws `Invalid spec path` for an unsafe path. */
 export declare function readSpecDocument(store: ObjectStore, sha: string, path: string): Promise<string | null>;

package/dist/reports/src/spec-inventory.js

@@ -1,8 +1,16 @@
+/**
+ * @module Spec inventory of a commit
+ *
+ * The older, commit-keyed record of which spec documents a commit has: `commits/<sha>/inventory.json` (the entries) and
+ * `commits/<sha>/specs/<path>` (their bodies). Document bodies are written first, so an inventory always names readable
+ * content. The newer form is the spec set (`spec-set.ts`).
+ */
 import { textFingerprint } from './layer-merge.js';
 import { readUtf8, writeUtf8 } from './object-io.js';
 import { eachLimited } from './completion-order.js';
 import { recordExplorerVersion } from './explorer-versions.js';
 import { isCommitSha } from './keys.js';
+/** Whether `path` is a safe spec path: starts with `specs/` and no segment is empty, `.`, `..`, or contains a backslash or control character. */
 export function isSpecPath(path) {
     return (path.startsWith('specs/') &&
         path
@@ -12,6 +20,12 @@ export function isSpecPath(path) {
             part !== '..' &&
             !/[\\\u0000-\u001f]/.test(part)));
 }
+/**
+ * Describes one spec document: its `path`, a text `fingerprint`, a `kind` (the file extension, `openslo` for
+ * `*.openslo.yaml`, `document` when there is none), a `title` (the first `Feature:` line, else the first `# ` heading,
+ * else the file name) and a `domain` (the folder right under `specs/`, or `Overview` for a file directly in it).
+ * Throws `Invalid spec path` unless `isSpecPath(path)`.
+ */
 export function specEntry(path, content) {
     if (!isSpecPath(path))
         throw new Error('Invalid spec path');
@@ -41,7 +55,12 @@ function documentKey(sha, path) {
     inventoryKey(sha);
     return `commits/${sha}/specs/${encodeURIComponent(path)}`;
 }
-/** Publish document bodies first; an inventory always names readable content. */
+/**
+ * Publishes a commit's spec documents and its inventory, and returns the inventory (entries sorted by path).
+ * Publish document bodies first; an inventory always names readable content. Throws `Duplicate spec` for a repeated
+ * path (before writing anything), `Invalid spec path` or `Invalid commit` for malformed input. Publishing the same
+ * documents again writes the same keys.
+ */
 export async function publishInventory(store, args) {
     const entries = args.documents
         .map((doc) => specEntry(doc.path, doc.content))
@@ -56,6 +75,7 @@ export async function publishInventory(store, args) {
     await recordExplorerVersion(store, args.sha);
     return inventory;
 }
+/** Reads a commit's inventory, or `null` when it has none. Throws `Invalid spec inventory` when the stored one is for another sha, malformed, or names an unsafe path, and `Invalid commit` for a bad sha. */
 export async function readInventory(store, sha) {
     const raw = await readUtf8(store, inventoryKey(sha));
     if (raw === null)
@@ -67,6 +87,7 @@ export async function readInventory(store, sha) {
         throw new Error('Invalid spec inventory');
     return inventory;
 }
+/** Reads one spec document's text, or `null` when the commit has no inventory or the inventory does not list `path`. Throws `Invalid spec path` for an unsafe path. */
 export async function readSpecDocument(store, sha, path) {
     const inventory = await readInventory(store, sha);
     if (!inventory?.entries.some((entry) => entry.path === path))

package/dist/reports/src/spec-link.d.ts

@@ -0,0 +1,28 @@
+import type { EvidenceCheck, SpecEntry } from './explorer-types.js';
+import type { IngestedChecks } from './ingest.js';
+/** Where specs are and how to resolve them for `linkChecksToSpecs`. */
+export type SpecLinks = {
+    /** Every file under this directory is a spec named `specs/<its path>`. Relative to `base`. */
+    readonly specsDirectory?: string;
+    /** Every check in the report belongs to this spec. A path relative to `base`. */
+    readonly spec?: string;
+    /** The directory that relative paths (`specsDirectory`, `spec`) resolve against, usually the repository root. */
+    readonly base: string;
+};
+/**
+ * A test report rarely says which spec a test checks. Say so here, in the order of how sure it is:
+ *
+ * 1. `spec`: the whole report is one spec's checks (a report per feature file).
+ * 2. A path the report gives that is one of the specs.
+ * 3. A name the report gives for the suite, class or file that is a spec's title or file name
+ *    (Cucumber writes the feature's title as the suite), or the first part of a check's title before
+ *    ` > `.
+ *
+ * What cannot be linked stays unlinked, and is reported under no spec rather than a wrong one.
+ * Returns the checks and the specs they now belong to, with fingerprints, so a later reader can warn
+ * when a spec changed after the layer was recorded.
+ */
+export declare function linkChecksToSpecs(ingested: IngestedChecks, links: SpecLinks): Promise<{
+    readonly checks: readonly EvidenceCheck[];
+    readonly specs: readonly SpecEntry[];
+}>;

package/dist/reports/src/spec-link.js

@@ -0,0 +1,70 @@
+/**
+ * @module Linking checks to specs
+ *
+ * Decides which spec each imported check belongs to, so results from a JUnit or CTRF file land under the right spec in
+ * the report. It reads only the specs directory and the one spec file the caller names explicitly; a report is data and
+ * does not choose which files Atlas opens. Uses Node's `fs`.
+ */
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { loadDirectoryOutline, specKindOf } from './directory-outline.js';
+import { specPath, textFingerprint } from './layer-merge.js';
+const words = (value) => value.toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+/** A file's name without the extension of a spec: `user.profile.feature` is `user.profile`, `cart.openslo.yaml` is `cart`. */
+const stem = (file) => path.posix.basename(file).replace(/(\.openslo|\.machine)?\.(feature|qnt|dmn|als|ya?ml|json|scxml|md|txt|xml)$/i, '');
+/**
+ * A test report rarely says which spec a test checks. Say so here, in the order of how sure it is:
+ *
+ * 1. `spec`: the whole report is one spec's checks (a report per feature file).
+ * 2. A path the report gives that is one of the specs.
+ * 3. A name the report gives for the suite, class or file that is a spec's title or file name
+ *    (Cucumber writes the feature's title as the suite), or the first part of a check's title before
+ *    ` > `.
+ *
+ * What cannot be linked stays unlinked, and is reported under no spec rather than a wrong one.
+ * Returns the checks and the specs they now belong to, with fingerprints, so a later reader can warn
+ * when a spec changed after the layer was recorded.
+ */
+export async function linkChecksToSpecs(ingested, links) {
+    const outline = links.specsDirectory ? await loadDirectoryOutline(path.resolve(links.base, links.specsDirectory), { repoRoot: links.base }) : null;
+    const known = new Map((outline?.specs ?? []).map(entry => [entry.path, entry]));
+    const byName = new Map();
+    for (const entry of [...known.values()].sort((a, b) => (a.path < b.path ? -1 : 1))) {
+        for (const name of [words(entry.title), words(stem(entry.path))])
+            if (name && !byName.has(name))
+                byName.set(name, entry.path);
+    }
+    let explicit = null;
+    if (links.spec)
+        explicit = specPath(links.spec);
+    const checks = ingested.checks.map((check, index) => {
+        if (explicit)
+            return { ...check, specPath: explicit };
+        if (check.specPath && known.has(specPath(check.specPath)))
+            return { ...check, specPath: specPath(check.specPath) };
+        const first = check.title.split(/ [>›] /)[0] ?? '';
+        for (const hint of [...(ingested.hints?.[index] ?? []), first]) {
+            const found = byName.get(words(hint)) ?? byName.get(words(stem(hint)));
+            if (found)
+                return { ...check, specPath: found };
+        }
+        return check;
+    });
+    const used = [...new Set(checks.flatMap(check => (check.specPath ? [check.specPath] : [])))].sort();
+    const specs = [];
+    for (const used_ of used) {
+        const entry = known.get(used_);
+        if (entry) {
+            specs.push(entry);
+            continue;
+        }
+        // An explicit spec outside a specs directory: read it where it is, if it is there. Nothing else
+        // a report names is read: a report is data, and does not choose which files Atlas opens.
+        if (used_ !== explicit || !links.spec)
+            continue;
+        const text = await readFile(path.resolve(links.base, links.spec), 'utf8').catch(() => null);
+        if (text !== null)
+            specs.push({ path: used_, domain: path.basename(links.base) || 'product', kind: specKindOf(used_), title: path.posix.basename(used_), fingerprint: textFingerprint(text) });
+    }
+    return { checks, specs };
+}