@crvouga/atlas 0.4.0 → 0.6.0

package/dist/reports/src/aws-credentials.js

@@ -0,0 +1,221 @@
+/**
+ * @module AWS credential lookup
+ *
+ * Finds S3 credentials the way an AWS SDK does, without depending on one: environment variables, web identity
+ * (EKS), ECS container credentials, the shared credentials file, the AWS CLI (SSO, assumed roles) and EC2 instance
+ * metadata. It owns the lookup order, the caching and the early refresh before expiry; it does not sign requests
+ * (that is `sigv4.ts`) or know about buckets (`s3-store.ts`). Credentials are never put in a store URL: they
+ * come from here. Node-only (reads files, spawns `aws`). Nothing runs at import time.
+ *
+ * @see docs/report-contract.md (backends)
+ */
+import { spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { XMLParser } from 'fast-xml-parser';
+let parser;
+/** Built on first use, so importing this module does no work. */
+const xml = { parse: (text) => (parser ??= new XMLParser({ ignoreAttributes: true, parseTagValue: false })).parse(text) };
+async function runCommand(command, args) {
+    return new Promise(resolve => {
+        try {
+            const child = spawn(command, [...args], { stdio: ['ignore', 'pipe', 'ignore'] });
+            let out = '';
+            const timer = setTimeout(() => { child.kill(); resolve(null); }, 20_000);
+            child.stdout.on('data', chunk => { out += String(chunk); });
+            child.on('error', () => { clearTimeout(timer); resolve(null); });
+            child.on('close', code => { clearTimeout(timer); resolve(code === 0 ? out : null); });
+        }
+        catch {
+            resolve(null);
+        }
+    });
+}
+function parseIni(text) {
+    const sections = {};
+    let current = null;
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line || line.startsWith('#') || line.startsWith(';'))
+            continue;
+        const header = /^\[(?:profile\s+)?([^\]]+)\]$/.exec(line);
+        if (header) {
+            current = sections[header[1].trim()] ??= {};
+            continue;
+        }
+        const at = line.indexOf('=');
+        if (current && at > 0)
+            current[line.slice(0, at).trim().toLowerCase()] = line.slice(at + 1).trim();
+    }
+    return sections;
+}
+function expiry(value) {
+    const time = typeof value === 'string' ? Date.parse(value) : NaN;
+    return Number.isFinite(time) ? time : undefined;
+}
+/**
+ * Creates a provider for the credentials an AWS SDK would find, in the same order, with no SDK: environment, web
+ * identity (EKS), container (ECS), shared credentials file, the AWS CLI (which covers SSO and assumed roles),
+ * and EC2 instance metadata. `ATLAS_S3_ACCESS_KEY_ID` / `ATLAS_S3_SECRET_ACCESS_KEY` (and `ATLAS_S3_SESSION_TOKEN`)
+ * come first so one store can use keys that are not the machine's AWS keys, such as Cloudflare R2 tokens.
+ *
+ * Nothing is looked up until the provider is first called. The first source that yields credentials wins and
+ * is cached; a source that throws (for example an STS error) is skipped and reported if no later source works.
+ * When none works the provider rejects with an error that lists every source tried and how to fix it. Set
+ * `ATLAS_NO_AWS_CLI` to skip the `aws` CLI step and `AWS_EC2_METADATA_DISABLED=true` to skip instance metadata.
+ *
+ * @example
+ * const credentials = await credentialChain()();
+ * credentials.accessKeyId;
+ */
+export function credentialChain(options = {}) {
+    const env = options.env ?? process.env;
+    const doFetch = options.fetch ?? fetch;
+    const read = options.readFile ?? ((file) => readFile(file, 'utf8'));
+    const run = options.run ?? runCommand;
+    const now = options.now ?? Date.now;
+    const skew = options.skewMs ?? 5 * 60_000;
+    const home = options.home ?? env.HOME ?? os.homedir();
+    const profile = env.AWS_PROFILE || env.AWS_DEFAULT_PROFILE || 'default';
+    let cached = null;
+    let pending = null;
+    const sources = [
+        {
+            name: 'environment (ATLAS_S3_*)',
+            load: async () => env.ATLAS_S3_ACCESS_KEY_ID && env.ATLAS_S3_SECRET_ACCESS_KEY
+                ? { accessKeyId: env.ATLAS_S3_ACCESS_KEY_ID, secretAccessKey: env.ATLAS_S3_SECRET_ACCESS_KEY, ...(env.ATLAS_S3_SESSION_TOKEN ? { sessionToken: env.ATLAS_S3_SESSION_TOKEN } : {}) }
+                : null
+        },
+        {
+            name: 'environment (AWS_ACCESS_KEY_ID)',
+            load: async () => env.AWS_ACCESS_KEY_ID && env.AWS_SECRET_ACCESS_KEY
+                ? { accessKeyId: env.AWS_ACCESS_KEY_ID, secretAccessKey: env.AWS_SECRET_ACCESS_KEY, ...(env.AWS_SESSION_TOKEN ? { sessionToken: env.AWS_SESSION_TOKEN } : {}) }
+                : null
+        },
+        {
+            name: 'web identity (IRSA)',
+            load: async () => {
+                if (!env.AWS_WEB_IDENTITY_TOKEN_FILE || !env.AWS_ROLE_ARN)
+                    return null;
+                const region = env.AWS_REGION || env.AWS_DEFAULT_REGION || 'us-east-1';
+                const token = (await read(env.AWS_WEB_IDENTITY_TOKEN_FILE)).trim();
+                const url = new URL(env.AWS_STS_ENDPOINT || `https://sts.${region}.amazonaws.com/`);
+                url.search = new URLSearchParams({ Action: 'AssumeRoleWithWebIdentity', Version: '2011-06-15', RoleArn: env.AWS_ROLE_ARN, RoleSessionName: env.AWS_ROLE_SESSION_NAME || 'atlas', WebIdentityToken: token }).toString();
+                const response = await doFetch(url, { method: 'GET', headers: { accept: 'application/xml' } });
+                const body = await response.text();
+                if (!response.ok)
+                    throw new Error(`STS AssumeRoleWithWebIdentity failed (${response.status}): ${body.slice(0, 300)}`);
+                const found = xml.parse(body)?.AssumeRoleWithWebIdentityResponse?.AssumeRoleWithWebIdentityResult?.Credentials;
+                if (!found?.AccessKeyId)
+                    throw new Error('STS returned no credentials');
+                return { accessKeyId: found.AccessKeyId, secretAccessKey: found.SecretAccessKey, sessionToken: found.SessionToken, ...(expiry(found.Expiration) ? { expiresAtMs: expiry(found.Expiration) } : {}) };
+            }
+        },
+        {
+            name: 'container credentials (ECS)',
+            load: async () => {
+                const url = env.AWS_CONTAINER_CREDENTIALS_FULL_URI || (env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI ? `http://169.254.170.2${env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI}` : null);
+                if (!url)
+                    return null;
+                const token = env.AWS_CONTAINER_AUTHORIZATION_TOKEN || (env.AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE ? (await read(env.AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE)).trim() : null);
+                const response = await doFetch(url, { headers: token ? { authorization: token } : {} });
+                if (!response.ok)
+                    throw new Error(`The container credentials endpoint answered ${response.status}`);
+                const found = await response.json();
+                return { accessKeyId: found.AccessKeyId, secretAccessKey: found.SecretAccessKey, sessionToken: found.Token, ...(expiry(found.Expiration) ? { expiresAtMs: expiry(found.Expiration) } : {}) };
+            }
+        },
+        {
+            name: `shared credentials file (profile ${profile})`,
+            load: async () => {
+                const file = env.AWS_SHARED_CREDENTIALS_FILE || path.join(home, '.aws', 'credentials');
+                const text = await read(file).catch(() => null);
+                const section = text ? parseIni(text)[profile] : undefined;
+                return section?.aws_access_key_id && section.aws_secret_access_key
+                    ? { accessKeyId: section.aws_access_key_id, secretAccessKey: section.aws_secret_access_key, ...(section.aws_session_token ? { sessionToken: section.aws_session_token } : {}) }
+                    : null;
+            }
+        },
+        {
+            name: `AWS CLI (profile ${profile})`,
+            load: async () => {
+                // Covers SSO, assumed roles and credential_process: whatever `aws` itself can sign in with.
+                if (env.ATLAS_NO_AWS_CLI)
+                    return null;
+                const out = await run('aws', ['configure', 'export-credentials', '--format', 'process', ...(env.AWS_PROFILE ? ['--profile', env.AWS_PROFILE] : [])]);
+                if (!out)
+                    return null;
+                try {
+                    const found = JSON.parse(out);
+                    return found.AccessKeyId && found.SecretAccessKey ? { accessKeyId: found.AccessKeyId, secretAccessKey: found.SecretAccessKey, ...(found.SessionToken ? { sessionToken: found.SessionToken } : {}), ...(expiry(found.Expiration) ? { expiresAtMs: expiry(found.Expiration) } : {}) } : null;
+                }
+                catch {
+                    return null;
+                }
+            }
+        },
+        {
+            name: 'EC2 instance metadata',
+            load: async () => {
+                if (env.AWS_EC2_METADATA_DISABLED === 'true')
+                    return null;
+                const base = env.AWS_EC2_METADATA_SERVICE_ENDPOINT || 'http://169.254.169.254';
+                const signal = () => AbortSignal.timeout(1_000);
+                try {
+                    const token = await doFetch(`${base}/latest/api/token`, { method: 'PUT', headers: { 'x-aws-ec2-metadata-token-ttl-seconds': '21600' }, signal: signal() });
+                    if (!token.ok)
+                        return null;
+                    const headers = { 'x-aws-ec2-metadata-token': await token.text() };
+                    const roles = await doFetch(`${base}/latest/meta-data/iam/security-credentials/`, { headers, signal: signal() });
+                    const role = (await roles.text()).split('\n')[0]?.trim();
+                    if (!roles.ok || !role)
+                        return null;
+                    const found = await (await doFetch(`${base}/latest/meta-data/iam/security-credentials/${role}`, { headers, signal: signal() })).json();
+                    return { accessKeyId: found.AccessKeyId, secretAccessKey: found.SecretAccessKey, sessionToken: found.Token, ...(expiry(found.Expiration) ? { expiresAtMs: expiry(found.Expiration) } : {}) };
+                }
+                catch {
+                    return null;
+                }
+            }
+        }
+    ];
+    async function resolve() {
+        const failures = [];
+        for (const source of sources) {
+            try {
+                const credentials = await source.load();
+                if (credentials) {
+                    cached = { credentials, source: source.name };
+                    return credentials;
+                }
+            }
+            catch (error) {
+                failures.push(`${source.name}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        throw new Error([
+            'No AWS credentials found for the object store.',
+            'Atlas looked, in order, at: ATLAS_S3_ACCESS_KEY_ID / ATLAS_S3_SECRET_ACCESS_KEY, AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY, EKS web identity, ECS container credentials, ~/.aws/credentials, the AWS CLI (aws sso login), and EC2 instance metadata.',
+            ...failures.map(failure => `  - ${failure}`),
+            'Fix: export AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or run `aws sso login` / `aws configure`, or attach a role to the machine.'
+        ].join('\n'));
+    }
+    const provider = (async () => {
+        if (cached && (cached.credentials.expiresAtMs === undefined || cached.credentials.expiresAtMs - skew > now()))
+            return cached.credentials;
+        // One lookup at a time, however many requests are waiting for credentials.
+        pending ??= resolve().finally(() => { pending = null; });
+        return pending;
+    });
+    provider.invalidate = () => { cached = null; };
+    provider.source = () => cached?.source ?? null;
+    return provider;
+}
+/** Wraps keys that are already known in a {@link CredentialProvider} that never refreshes (its `invalidate` does nothing). */
+export function staticCredentials(credentials) {
+    const provider = (async () => credentials);
+    provider.invalidate = () => { };
+    provider.source = () => 'given to the store';
+    return provider;
+}

package/dist/reports/src/browser-navigation.d.ts

@@ -1,2 +1,16 @@
+/**
+ * @module Browser navigation for the reports viewer
+ *
+ * The one implementation of {@link ReportNavigation} that touches `window` and `document`: the explorer's selection
+ * lives in the URL hash, keys come from `keydown`, and the tab title is `document.title`. Browser-only; nothing
+ * here runs until {@link browserReportNavigation} is called, so importing it is safe in Node.
+ */
 import type { ReportNavigation } from './navigation.js';
+/**
+ * Creates a {@link ReportNavigation} backed by `window.location.hash`, `history`, `keydown` and `document.title`.
+ *
+ * `writeHash` does nothing when the hash is already the given one; otherwise it replaces or pushes a history entry
+ * (no `hashchange` is fired by `replaceState`/`pushState`, so the caller owns re-reading). `subscribeHash` listens to both
+ * `hashchange` and `popstate`. Every `subscribe*` returns its unsubscribe function. Must be called in a browser.
+ */
 export declare function browserReportNavigation(): ReportNavigation;

package/dist/reports/src/browser-navigation.js

@@ -1,3 +1,10 @@
+/**
+ * Creates a {@link ReportNavigation} backed by `window.location.hash`, `history`, `keydown` and `document.title`.
+ *
+ * `writeHash` does nothing when the hash is already the given one; otherwise it replaces or pushes a history entry
+ * (no `hashchange` is fired by `replaceState`/`pushState`, so the caller owns re-reading). `subscribeHash` listens to both
+ * `hashchange` and `popstate`. Every `subscribe*` returns its unsubscribe function. Must be called in a browser.
+ */
 export function browserReportNavigation() {
     return {
         readHash: () => window.location.hash,

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

@@ -1,24 +1,56 @@
 import type { ObjectStore } from './object-store.js';
+/** Uncompressed size of one chunk, in bytes (4 MiB). A file larger than this is split across several chunks. */
 export declare const BUNDLE_BYTES: number;
 type Location = {
     blob: string;
     offset: number;
     size: number;
 };
+/**
+ * Where each file of a bundle is, keyed by the file's key (for a layer, `attachments/<sha256>` and the like).
+ * `parts` lists, in order, the byte ranges (`offset`, `size` within the decompressed blob `blob`, a store key) whose
+ * concatenation is the file.
+ */
 export type BundleIndex = Record<string, {
     contentType: string;
     parts: Location[];
 }>;
+/** One file to bundle, or one file read back. */
 export type BundleEntry = {
+    /** The file's name inside the bundle; the key in the {@link BundleIndex}. A repeated key appends more parts to the same file. */
     key: string;
     bytes: Uint8Array;
+    /** The media type to serve the bytes with. The first entry with a key decides it. */
     contentType: string;
 };
+/** The store key of a commit's bundle index for one source: `commits/<sha>/bundles/<source>.json`. This is the older, per-commit layout; layers hold their index in the layer document instead. */
 export declare function bundleIndexKey(sha: string, source: string): string;
-/** Four bounded compressed chunks in flight, with one small index published last. */
+/**
+ * Writes `entries` as blobs next to `key` and then the index at `key`: up to four compressed chunks in flight,
+ * with the one small index published last, so a reader never finds an index whose blobs have not arrived.
+ *
+ * Trap: blobs go to `<key up to "/bundles/">/blobs/`, so `key` must contain `/bundles/` (as {@link bundleIndexKey}
+ * gives); otherwise the prefix is computed from a wrong slice.
+ */
 export declare function publishBundle(store: ObjectStore, key: string, entries: AsyncIterable<BundleEntry>): Promise<void>;
+/**
+ * Packs `entries` into gzip blobs under `prefix` (for layers, `layers/blobs/`) and returns the index that locates
+ * every file; the caller stores the index (a layer keeps it as its `bundle`).
+ *
+ * The entries are consumed lazily with up to four chunks in flight. A blob that already exists in the store is not
+ * written again (one `head` per distinct blob). The gzip header's timestamp is zeroed, and the blob name is the
+ * SHA-256 of the uncompressed chunk, so the same files in the same order always produce the same blobs. Order of
+ * entries matters for that: chunking follows input order. A store error rejects after started writes settle.
+ */
 export declare function writeBundle(store: ObjectStore, entries: AsyncIterable<BundleEntry>, prefix: string): Promise<BundleIndex>;
-/** Cache only immutable blobs; mutable indexes are read for each request. */
+/**
+ * Creates a reader that returns one file of a bundle by key, or `null` when the key is not in `index` or one of
+ * its blobs is missing from the store.
+ *
+ * Only immutable blobs are cached (the last four decompressed blobs, oldest evicted first, including a cached
+ * "missing" answer); mutable indexes are read for each request. Transport errors from the store reject.
+ */
 export declare function createBundleReader(store: ObjectStore, index: BundleIndex): (key: string) => Promise<BundleEntry | null>;
+/** Reads and parses the bundle index at `key`; an index that is not there is an empty bundle (`{}`). Invalid JSON throws. */
 export declare function readBundleIndex(store: ObjectStore, key: string): Promise<BundleIndex>;
 export {};

package/dist/reports/src/bundle.js

@@ -1,6 +1,20 @@
+/**
+ * @module Bundles of captured files
+ *
+ * Packs many small captured files (screenshots, frames, attachments) into a few gzip-compressed, content-addressed
+ * blobs in an {@link ObjectStore}, and reads single files back out. The bytes of every entry are concatenated into
+ * chunks of at most {@link BUNDLE_BYTES} uncompressed bytes; each chunk is gzipped and stored once at
+ * `<prefix><sha256 of the uncompressed chunk>.gz`, so identical chunks and re-publishes write nothing new. A
+ * {@link BundleIndex} says, per file key, which byte ranges of which blobs hold it. A layer document keeps that
+ * index in its `bundle` field. Blobs are immutable; the index is the only mutable-looking part and is written last.
+ *
+ * @see docs/report-contract.md (where bytes go)
+ */
 import { readObjectBytes, readUtf8, writeUtf8, } from './object-io.js';
 import { eachLimitedStream } from './completion-order.js';
+/** Uncompressed size of one chunk, in bytes (4 MiB). A file larger than this is split across several chunks. */
 export const BUNDLE_BYTES = 4 * 1024 * 1024;
+/** The store key of a commit's bundle index for one source: `commits/<sha>/bundles/<source>.json`. This is the older, per-commit layout; layers hold their index in the layer document instead. */
 export function bundleIndexKey(sha, source) {
     return `commits/${sha}/bundles/${source}.json`;
 }
@@ -67,18 +81,39 @@ async function* chunks(entries) {
     if (pending.length > 0)
         yield pending;
 }
-/** Four bounded compressed chunks in flight, with one small index published last. */
+/**
+ * Writes `entries` as blobs next to `key` and then the index at `key`: up to four compressed chunks in flight,
+ * with the one small index published last, so a reader never finds an index whose blobs have not arrived.
+ *
+ * Trap: blobs go to `<key up to "/bundles/">/blobs/`, so `key` must contain `/bundles/` (as {@link bundleIndexKey}
+ * gives); otherwise the prefix is computed from a wrong slice.
+ */
 export async function publishBundle(store, key, entries) {
     const index = await writeBundle(store, entries, `${key.slice(0, key.indexOf('/bundles/'))}/blobs/`);
     await writeUtf8(store, key, JSON.stringify(index), 'application/json');
 }
+/**
+ * Packs `entries` into gzip blobs under `prefix` (for layers, `layers/blobs/`) and returns the index that locates
+ * every file; the caller stores the index (a layer keeps it as its `bundle`).
+ *
+ * The entries are consumed lazily with up to four chunks in flight. A blob that already exists in the store is not
+ * written again (one `head` per distinct blob). The gzip header's timestamp is zeroed, and the blob name is the
+ * SHA-256 of the uncompressed chunk, so the same files in the same order always produce the same blobs. Order of
+ * entries matters for that: chunking follows input order. A store error rejects after started writes settle.
+ */
 export async function writeBundle(store, entries, prefix) {
     const index = {};
     const writes = { prefix, pending: new Map() };
     await eachLimitedStream(chunks(entries), 4, chunk => flush(store, chunk, index, writes));
     return index;
 }
-/** Cache only immutable blobs; mutable indexes are read for each request. */
+/**
+ * Creates a reader that returns one file of a bundle by key, or `null` when the key is not in `index` or one of
+ * its blobs is missing from the store.
+ *
+ * Only immutable blobs are cached (the last four decompressed blobs, oldest evicted first, including a cached
+ * "missing" answer); mutable indexes are read for each request. Transport errors from the store reject.
+ */
 export function createBundleReader(store, index) {
     const cache = new Map();
     return async (key) => {
@@ -108,6 +143,7 @@ export function createBundleReader(store, index) {
         return { key, bytes, contentType: location.contentType };
     };
 }
+/** Reads and parses the bundle index at `key`; an index that is not there is an empty bundle (`{}`). Invalid JSON throws. */
 export async function readBundleIndex(store, key) {
     const text = await readUtf8(store, key);
     return text === null ? {} : JSON.parse(text);

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

@@ -1,37 +1,68 @@
-/** Shared search, filter, group and sort for reports and the tests inside one. */
+/**
+ * @module Catalog search, filter, group and sort
+ *
+ * The pure view logic behind the viewer's list of reports (and of the tests inside one): given entities and a
+ * query (text, status, grouping, sort), it returns the groups to draw. It owns no data and does no I/O; the
+ * caller maps its own records to {@link CatalogEntity}. Input is never mutated.
+ */
+/** A status filter: one of the four result statuses as the list names them (`skipped` is a check that was `not-run`), or `all`. */
 export type CatalogStatus = 'all' | 'passed' | 'failed' | 'skipped' | 'running';
+/** What the list is grouped by; `none` gives one group named `All`. */
 export type CatalogGroup = 'none' | 'file' | 'status' | 'package' | 'runtime';
+/** How entities are ordered inside a group: `recent` keeps the input order, `name` is by title, `duration` is longest first, `status` is failed first then by title. */
 export type CatalogSort = 'recent' | 'name' | 'duration' | 'status';
+/** How the list is drawn. */
 export type CatalogLayout = 'list' | 'grid';
+/** The user's current choices, mirrored in the URL (see {@link catalogParams}). */
 export type CatalogQuery = {
+    /** Free text; matched case-insensitively as a substring of each entity's `search` text. Blank matches everything. */
     readonly q: string;
     readonly status: CatalogStatus;
     readonly group: CatalogGroup;
     readonly sort: CatalogSort;
     readonly layout: CatalogLayout;
 };
+/** One row of the list: a report or a test, flattened to what the list needs. */
 export type CatalogEntity = {
+    /** Stable identifier of the row. */
     readonly id: string;
     readonly title: string;
+    /** A status string; only `passed`, `failed`, `skipped` and `running` are counted and ranked, any other sorts after them. */
     readonly status: string;
+    /** Duration in milliseconds, or null when unknown (sorted last by `duration`, counted as 0 in a group's total). */
     readonly durationMs: number | null;
     /** Group label for `file` (a source file, or a branch). */
     readonly file: string;
+    /** Group label for `package`; empty groups under `Other`. */
     readonly packageName: string;
+    /** Group label for `runtime`; empty groups under `Other`. */
     readonly runtime: string;
     /** One muted line under the title: a failure, or a date. */
     readonly detail: string;
+    /** Everything the text query may match (title, ids, paths, ...), built by the caller. */
     readonly search: string;
+    /** Where selecting the row navigates, or null when it is not a link. */
     readonly href: string | null;
 };
+/** One drawn group of the list. */
 export type CatalogGroupView = {
     readonly name: string;
+    /** Sum of the members' durations in milliseconds; unknown durations count as 0. */
     readonly durationMs: number;
+    /** How many members have status `failed`. */
     readonly failed: number;
     readonly entities: readonly CatalogEntity[];
 };
+/** Counts entities per status filter (`all` is the total); a status the list does not know is counted only in `all`. */
 export declare function catalogCounts(entities: readonly CatalogEntity[]): Record<CatalogStatus, number>;
-/** The list's search params, dropped when a test route carries frame and zoom. */
+/** Keeps only the list's own URL search params (`q`, `status`, `group`, `sort`, `layout`, `spec`, `tab`, `partq`) and drops empty ones, so a test route's frame and zoom params do not leak into a link back to the list. */
 export declare function catalogParams(params: Readonly<Record<string, string>>): Record<string, string>;
-/** Filter, sort, then one group per chosen key. `recent` keeps input order. */
+/**
+ * Filters entities by the query's status and text, sorts them, then splits them into one group per value of the
+ * chosen key. `recent` keeps input order.
+ *
+ * Group order: for `status`, failed, running, skipped, passed; otherwise alphabetical by name with `Other` (the
+ * label for an empty file, package or runtime) last. With `none` there is a single group named `All`. When
+ * nothing matches, no group is returned.
+ */
 export declare function arrangeCatalog(entities: readonly CatalogEntity[], query: CatalogQuery): readonly CatalogGroupView[];

package/dist/reports/src/catalog.js

@@ -1,10 +1,17 @@
-/** Shared search, filter, group and sort for reports and the tests inside one. */
+/**
+ * @module Catalog search, filter, group and sort
+ *
+ * The pure view logic behind the viewer's list of reports (and of the tests inside one): given entities and a
+ * query (text, status, grouping, sort), it returns the groups to draw. It owns no data and does no I/O; the
+ * caller maps its own records to {@link CatalogEntity}. Input is never mutated.
+ */
 const STATUS_RANK = {
     failed: 0,
     running: 1,
     skipped: 2,
     passed: 3,
 };
+/** Counts entities per status filter (`all` is the total); a status the list does not know is counted only in `all`. */
 export function catalogCounts(entities) {
     const counts = {
         all: entities.length,
@@ -83,7 +90,7 @@ const LIST_KEYS = [
     'tab',
     'partq',
 ];
-/** The list's search params, dropped when a test route carries frame and zoom. */
+/** Keeps only the list's own URL search params (`q`, `status`, `group`, `sort`, `layout`, `spec`, `tab`, `partq`) and drops empty ones, so a test route's frame and zoom params do not leak into a link back to the list. */
 export function catalogParams(params) {
     const out = {};
     for (const key of LIST_KEYS) {
@@ -93,7 +100,14 @@ export function catalogParams(params) {
     }
     return out;
 }
-/** Filter, sort, then one group per chosen key. `recent` keeps input order. */
+/**
+ * Filters entities by the query's status and text, sorts them, then splits them into one group per value of the
+ * chosen key. `recent` keeps input order.
+ *
+ * Group order: for `status`, failed, running, skipped, passed; otherwise alphabetical by name with `Other` (the
+ * label for an empty file, package or runtime) last. With `none` there is a single group named `All`. When
+ * nothing matches, no group is returned.
+ */
 export function arrangeCatalog(entities, query) {
     const shown = entities.filter((entity) => matches(entity, query));
     const sorted = query.sort === 'recent'

package/dist/reports/src/cli-stores.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @module Stores named on a command line
+ *
+ * Turns `--store`, `--backends` and `ATLAS_STORE` into opened backends for the `atlas report` commands, and reads the
+ * small flag grammar those commands share (`--name value`, repeatable). A mistyped directory is an error here, never
+ * an empty store: a gate that read nothing must not read as a pass.
+ *
+ * @see docs/deploying.md
+ */
+import type { BackendInput } from './compose.js';
+import { type OpenedStore } from './store-url.js';
+type Env = Readonly<Record<string, string | undefined>>;
+/** A backend of a command: what `combineBackends` reads, plus, when it came from a URL, how it was opened (`location`, `server`, `s3`). */
+export type CliBackend = BackendInput & Partial<OpenedStore>;
+/** Every value given for `--<name>`, in order. `--name` with nothing after it is ignored. */
+export declare function values(argv: readonly string[], name: string): string[];
+/** The first value given for `--<name>`, or `undefined`. */
+export declare function value(argv: readonly string[], name: string): string | undefined;
+/**
+ * Every store a command reads: `--store` (a directory or `s3://…`, optionally `id=url`), then
+ * `--backends <module>`, or `ATLAS_STORE` when neither is given. A directory that is not there is an
+ * error: a mistyped path must never read as an empty store.
+ */
+export declare function backendsOf(argv: readonly string[], base: string, env: Env): Promise<CliBackend[]>;
+/** The one store a command writes to. A directory is created; a bucket must already exist. */
+export declare function writeStoreOf(flag: string | undefined, base: string, env: Env, name?: string): OpenedStore;
+/**
+ * Which layers take part, from `--branch <name>` (repeatable) and `--ignore-modified`. By default all do:
+ * a report is whatever the newest results are, wherever they were recorded. A gate that must speak for
+ * a branch narrows it; the narrowing is yours to choose, never Atlas's.
+ */
+export declare function layerFilter(argv: readonly string[], env: Env): ((layer: {
+    readonly branch: string | null;
+    readonly freshness?: 'unknown' | 'modified';
+}) => boolean) | undefined;
+export {};

package/dist/reports/src/cli-stores.js

@@ -0,0 +1,73 @@
+/**
+ * @module Stores named on a command line
+ *
+ * Turns `--store`, `--backends` and `ATLAS_STORE` into opened backends for the `atlas report` commands, and reads the
+ * small flag grammar those commands share (`--name value`, repeatable). A mistyped directory is an error here, never
+ * an empty store: a gate that read nothing must not read as a pass.
+ *
+ * @see docs/deploying.md
+ */
+import { existsSync, mkdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { openBackends, openStore, storeSpecs } from './store-url.js';
+/** Every value given for `--<name>`, in order. `--name` with nothing after it is ignored. */
+export function values(argv, name) {
+    return argv.flatMap((token, i) => (token === `--${name}` && argv[i + 1] !== undefined ? [argv[i + 1]] : []));
+}
+/** The first value given for `--<name>`, or `undefined`. */
+export function value(argv, name) {
+    return values(argv, name)[0];
+}
+/**
+ * Every store a command reads: `--store` (a directory or `s3://…`, optionally `id=url`), then
+ * `--backends <module>`, or `ATLAS_STORE` when neither is given. A directory that is not there is an
+ * error: a mistyped path must never read as an empty store.
+ */
+export async function backendsOf(argv, base, env) {
+    const specs = storeSpecs(values(argv, 'store'), env);
+    const backends = openBackends(specs, { base, env });
+    backends.forEach((backend, i) => {
+        const location = backend.location;
+        if (location?.kind === 'directory' && (!existsSync(location.directory) || !statSync(location.directory).isDirectory())) {
+            throw new Error(`Store directory not found: ${specs[i].replace(/^[a-z0-9-]+=/, '')}. If a node failed to publish or upload, fix that first`);
+        }
+    });
+    const used = new Set(backends.map(backend => backend.id));
+    for (const file of values(argv, 'backends')) {
+        const mod = (await import(pathToFileURL(path.resolve(base, file)).href));
+        if (!mod.default)
+            throw new Error(`${file} has no default export: a list of { id, label?, store }`);
+        for (const backend of typeof mod.default === 'function' ? await mod.default() : mod.default) {
+            if (used.has(backend.id))
+                throw new Error(`Two stores are named "${backend.id}"`);
+            used.add(backend.id);
+            backends.push(backend);
+        }
+    }
+    if (!backends.length)
+        throw new Error('Give at least one --store <dir or s3://bucket/prefix> (or --backends <module>), or set ATLAS_STORE');
+    return backends;
+}
+/** The one store a command writes to. A directory is created; a bucket must already exist. */
+export function writeStoreOf(flag, base, env, name = 'store') {
+    const specs = flag ? [flag] : storeSpecs([], env);
+    if (specs.length !== 1)
+        throw new Error(specs.length ? `Give one --${name} to write to (ATLAS_STORE names ${specs.length})` : `Give --${name} <dir or s3://bucket/prefix>, or set ATLAS_STORE`);
+    const opened = openStore(/^([a-z0-9-]+)=(.+)$/.exec(specs[0])?.[2] ?? specs[0], { base, env });
+    if (opened.location.kind === 'directory')
+        mkdirSync(opened.location.directory, { recursive: true });
+    return opened;
+}
+/**
+ * Which layers take part, from `--branch <name>` (repeatable) and `--ignore-modified`. By default all do:
+ * a report is whatever the newest results are, wherever they were recorded. A gate that must speak for
+ * a branch narrows it; the narrowing is yours to choose, never Atlas's.
+ */
+export function layerFilter(argv, env) {
+    const branches = [...values(argv, 'branch'), ...(env.ATLAS_ONLY_BRANCH ?? '').split(/[\s,]+/).filter(Boolean)];
+    const ignoreModified = argv.includes('--ignore-modified') || env.ATLAS_IGNORE_MODIFIED === '1' || env.ATLAS_IGNORE_MODIFIED === 'true';
+    if (!branches.length && !ignoreModified)
+        return undefined;
+    return layer => (!branches.length || (layer.branch !== null && branches.includes(layer.branch))) && (!ignoreModified || layer.freshness === undefined);
+}

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

@@ -1,11 +1,16 @@
 /**
- * Injectable wall / virtual time for deterministic simulation.
- * Production uses {@link wallClock} / {@link wallTimers}.
+ * @module Injectable time
+ *
+ * The two time dependencies of the reports code, as types, so tests and simulations can supply virtual time.
+ * Production hosts pass `{ now: Date.now }` and wrappers over the global timers (see `host.ts`). There is no
+ * default implementation in this module.
  */
+/** The clock a reader or route uses to decide when polling or tailing has run long enough. */
 export type Clock = {
     /** Epoch milliseconds (virtual or wall). */
     readonly now: () => number;
 };
+/** The timer functions the reports code schedules work with; each handle is opaque and only passed back to the matching `clear*`. */
 export type Timers = {
     readonly setTimeout: (fn: () => void, ms: number) => unknown;
     readonly clearTimeout: (handle: unknown) => void;

package/dist/reports/src/clock.js

@@ -1,4 +1,7 @@
 /**
- * Injectable wall / virtual time for deterministic simulation.
- * Production uses {@link wallClock} / {@link wallTimers}.
+ * @module Injectable time
+ *
+ * The two time dependencies of the reports code, as types, so tests and simulations can supply virtual time.
+ * Production hosts pass `{ now: Date.now }` and wrappers over the global timers (see `host.ts`). There is no
+ * default implementation in this module.
  */