@crvouga/atlas 0.4.0 → 0.5.0

package/dist/reports/src/hash.js

@@ -1,3 +1,11 @@
+/**
+ * @module URL hash routes of the reports viewer
+ *
+ * The explorer keeps its state in the URL hash (`#/test/<id>?view=single&zoom=fit`) so a link reproduces a view.
+ * This module parses a hash into a {@link Route} and builds it back; it is pure and never throws on a missing
+ * value, but `parseHash` throws `URIError` on a malformed percent-escape. Unknown params are carried untouched.
+ */
+/** Parses a `location.hash` (with or without the leading `#` and `/`) into a {@link Route}; an unrecognized path is the list. */
 export function parseHash(hash) {
     const raw = hash.replace(/^#\/?/, '');
     const q = raw.split('?');
@@ -18,6 +26,7 @@ export function parseHash(hash) {
     }
     return { view: 'list', params };
 }
+/** Builds the hash for a route (`#/` or `#/test/<encoded id>`) with its non-empty params encoded; the inverse of {@link parseHash}. */
 export function buildHash(route) {
     const qs = Object.keys(route.params)
         .filter((k) => {
@@ -29,15 +38,19 @@ export function buildHash(route) {
     const path = route.view === 'test' ? `/test/${encodeURIComponent(route.testId)}` : '/';
     return `#${path}${qs ? `?${qs}` : ''}`;
 }
+/** `single` when the `view` param says so, otherwise `multi`. */
 export function viewMode(route) {
     return route.params['view'] === 'single' ? 'single' : 'multi';
 }
+/** The `zoom` param, or `fit` when it is absent. */
 export function zoomMode(route) {
     return route.params['zoom'] || 'fit';
 }
+/** Whether the side panel is shown: true unless `aside=0`. */
 export function showAside(route) {
     return route.params['aside'] !== '0';
 }
+/** Whether press targets are drawn on frames: true unless `press=0`. */
 export function showPress(route) {
     return route.params['press'] !== '0';
 }

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

@@ -0,0 +1,29 @@
+import type { BackendInput } from './compose.js';
+/** Options of {@link reportsHost}. */
+export type ReportsHostOptions = {
+    /** The specs directory, relative to the project. Its files are the outline every layer fills. */
+    readonly specs: string;
+    /**
+     * Where layers are: a directory, an `s3://` URL, or any backend. Several stores are one report: layers
+     * from all of them are laid over the same specs. Default: `ATLAS_STORE`.
+     */
+    readonly stores?: readonly (string | BackendInput)[];
+    /** Groups the specs in the viewer. Default: the repository folder's name, or `product`. */
+    readonly domain?: string;
+};
+/**
+ * The reports half of the viewer, for a project's own stores. Export it from the module that
+ * `ATLAS_REPORTS_MODULE` names:
+ *
+ * ```ts
+ * import { reportsHost } from '@crvouga/atlas/reports/host';
+ * export const reportsDevFetch = reportsHost({ specs: './specs', stores: ['./atlas-reports'] });
+ * ```
+ *
+ * The returned function takes the incoming `Request` and the repository root (relative store paths and `specs`
+ * resolve against it); a path starting `/api/reports` has that prefix removed before routing. The app is built
+ * on first use and rebuilt if the root changes. A store given as a string is opened with `openStore` and gets an
+ * id derived from its location; a failure while answering (for example a wrong `specs` path) is a 500 whose JSON
+ * body names the `specs` directory and the store ids.
+ */
+export declare function reportsHost(options: ReportsHostOptions): (request: Request, repoRoot: string) => Promise<Response>;

package/dist/reports/src/host.js

@@ -0,0 +1,64 @@
+/**
+ * @module Reports host for a project's own stores
+ *
+ * Mounts the reports API (outline of a specs directory, layers from one or more stores) as a plain
+ * `(request, repoRoot) => Response` function, for a dev server or a project's own server to call at
+ * `/api/reports`. It owns opening the stores and lazily building the app once per repository root; the report
+ * logic itself is in `reports-route.ts` and `compose.ts`. Node/Bun only. It forwards only the method, URL and
+ * headers of a request (not the body), so it serves reads.
+ *
+ * @see docs/dogfooding.md
+ */
+import path from 'node:path';
+import { openStore, storeId, storeSpecs } from './store-url.js';
+import { loadDirectoryOutline } from './directory-outline.js';
+import { createReportsApp } from './reports-route.js';
+const PREFIX = '/api/reports';
+/**
+ * The reports half of the viewer, for a project's own stores. Export it from the module that
+ * `ATLAS_REPORTS_MODULE` names:
+ *
+ * ```ts
+ * import { reportsHost } from '@crvouga/atlas/reports/host';
+ * export const reportsDevFetch = reportsHost({ specs: './specs', stores: ['./atlas-reports'] });
+ * ```
+ *
+ * The returned function takes the incoming `Request` and the repository root (relative store paths and `specs`
+ * resolve against it); a path starting `/api/reports` has that prefix removed before routing. The app is built
+ * on first use and rebuilt if the root changes. A store given as a string is opened with `openStore` and gets an
+ * id derived from its location; a failure while answering (for example a wrong `specs` path) is a 500 whose JSON
+ * body names the `specs` directory and the store ids.
+ */
+export function reportsHost(options) {
+    let app;
+    let root = '';
+    return async (request, repoRoot) => {
+        if (!app || root !== repoRoot) {
+            root = repoRoot;
+            // Ids given by the caller are kept; the ones derived from the store step around them.
+            const given = options.stores ?? storeSpecs([], process.env);
+            const used = new Set(given.flatMap((store) => (typeof store === 'string' ? [] : [store.id])));
+            const backends = given.map((store) => {
+                if (typeof store !== 'string')
+                    return store;
+                const opened = openStore(store, { base: repoRoot, env: process.env });
+                const id = storeId(opened.location, used);
+                used.add(id);
+                return { id, label: opened.location.kind === 'directory' ? path.basename(opened.location.directory) : opened.label, store: opened.store };
+            });
+            const specs = path.resolve(repoRoot, options.specs);
+            app = createReportsApp({
+                store: null,
+                backends: backends.map(backend => ({ ...backend, label: backend.label ?? backend.id })),
+                clock: { now: Date.now },
+                timers: { setTimeout: (fn, ms) => setTimeout(fn, ms), clearTimeout: handle => clearTimeout(handle), setInterval: (fn, ms) => setInterval(fn, ms), clearInterval: handle => clearInterval(handle) },
+                outline: () => loadDirectoryOutline(specs, { repoRoot, domain: options.domain ?? (path.basename(repoRoot) || 'product') })
+            });
+            // A wrong path says which one, instead of a bare "Internal Server Error".
+            app.onError((error, c) => c.json({ error: error instanceof Error ? error.message : String(error), specs, stores: backends.map(backend => backend.id) }, 500));
+        }
+        const url = new URL(request.url);
+        const pathname = url.pathname === PREFIX || url.pathname.startsWith(`${PREFIX}/`) ? url.pathname.slice(PREFIX.length) || '/' : url.pathname;
+        return app.request(new Request(`http://reports${pathname}${url.search}`, { method: request.method, headers: request.headers }));
+    };
+}

package/dist/reports/src/html-frame.d.ts

@@ -1,13 +1,12 @@
 import type { FlatFrame } from './frames.js';
-/**
- * A self-contained HTML document for a frame that has no UI snapshot: a
- * Quint step's model state, or any spec step that only recorded text.
- * Painted in the same phone surface as a real snapshot.
- */
 type Section = {
     readonly heading: string;
     readonly body: string;
 };
-/** HTML document of one frame's model or recorded state. */
+/**
+ * The HTML document of one frame's model or recorded state: the step's kind and timings, its title, its error,
+ * its `detail` (shown as a name/value table when every line reads `name = value`, otherwise as preformatted text)
+ * and then one block per extra `sections` entry. Everything from the recording is escaped.
+ */
 export declare function stateFrameHtml(frame: FlatFrame, sections: readonly Section[]): string;
 export {};

package/dist/reports/src/html-frame.js

@@ -1,3 +1,10 @@
+/**
+ * @module HTML cards for frames without a UI snapshot
+ *
+ * Builds a self-contained HTML document for a frame that has no UI snapshot: a Quint step's model state, or any
+ * spec step that only recorded text. It is painted in the same phone surface as a real snapshot. All text taken
+ * from the recording is HTML-escaped and the document carries only its own inline style, no script.
+ */
 import { fmtMs } from './format.js';
 const CARD_CSS = [
     'html,body{margin:0;background:#f4f1ea;color:#1c1915;',
@@ -53,7 +60,11 @@ function sectionBlocks(sections) {
         .map((section) => `<h2>${escapeHtml(section.heading)}</h2><pre>${escapeHtml(section.body)}</pre>`)
         .join('');
 }
-/** HTML document of one frame's model or recorded state. */
+/**
+ * The HTML document of one frame's model or recorded state: the step's kind and timings, its title, its error,
+ * its `detail` (shown as a name/value table when every line reads `name = value`, otherwise as preformatted text)
+ * and then one block per extra `sections` entry. Everything from the recording is escaped.
+ */
 export function stateFrameHtml(frame, sections) {
     const step = frame.step;
     const error = step.error === undefined

package/dist/reports/src/http-store.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @module Atlas server as an ObjectStore
+ *
+ * `httpStore` speaks the server's store protocol (`/api/store`) as an `ObjectStore`, so everything that publishes to a store
+ * (`publishChecks`, spec sets, run uploads, `copyStore`, `createReporter`) publishes to a server unchanged. It retries what a
+ * retry can fix (network errors, 5xx, 429, 408) with jittered backoff, never what it cannot (401, 403, 409, 413, 422), and
+ * every refusal says what to do about it.
+ *
+ * @see docs/server.md#the-store-protocol
+ */
+import type { ObjectStore, PagedListing } from './object-store.js';
+/** How to reach a server: its `url`, the `token` to send (never in the URL), and, for tests and special runtimes, `fetch`, the retry count, the per-attempt timeout and `sleep`. */
+export type HttpStoreOptions = {
+    /** The Atlas server, such as `https://atlas.example.com`. A path on it (`/atlas`) is kept. */
+    readonly url: string;
+    /** A publish or admin token to write with, a read token to read with. Never put it in the URL. */
+    readonly token?: string;
+    readonly fetch?: typeof fetch;
+    /** Retries after the first attempt, for network errors and server errors. Default 4. */
+    readonly retries?: number;
+    /** Per attempt, to start answering, in milliseconds. Default 30 000. */
+    readonly timeoutMs?: number;
+    readonly sleep?: (ms: number) => Promise<void>;
+};
+/** What an Atlas server said no to, with what to do about it. */
+export declare class AtlasHttpError extends Error {
+    readonly status: number | null;
+    readonly retryable: boolean;
+    constructor(message: string, status: number | null, retryable?: boolean);
+}
+/** An `ObjectStore` (with paged listing) over an Atlas server, plus what only a server can answer: `ping` (is it there, and what may this token do) and `status` (the gate, worked out by the server). */
+export type HttpStore = ObjectStore & PagedListing & {
+    /** `https://atlas.example.com`, with no secrets. */
+    readonly label: string;
+    readonly url: string;
+    /** Is the server there, and does it know this token? */
+    ping(): Promise<{
+        readonly ok: boolean;
+        readonly ms: number;
+        readonly role?: string;
+        readonly error?: string;
+    }>;
+    /** The gate, worked out by the server from the layers it holds: the `atlas report status --format json` document. Needs a token that may read. */
+    status(query?: URLSearchParams): Promise<unknown>;
+};
+/**
+ * An {@link ObjectStore} on an Atlas server, over its store protocol (`/api/store`). The server holds the
+ * layers (on its own disk, or in whatever backends it was given), checks what is uploaded, and shows
+ * everyone the combined report at once. Anything that publishes to a store, `publishChecks`, spec sets,
+ * run uploads, `copyStore`, works against it unchanged.
+ */
+export declare function httpStore(options: HttpStoreOptions): HttpStore;

package/dist/reports/src/http-store.js

@@ -0,0 +1,145 @@
+/**
+ * @module Atlas server as an ObjectStore
+ *
+ * `httpStore` speaks the server's store protocol (`/api/store`) as an `ObjectStore`, so everything that publishes to a store
+ * (`publishChecks`, spec sets, run uploads, `copyStore`, `createReporter`) publishes to a server unchanged. It retries what a
+ * retry can fix (network errors, 5xx, 429, 408) with jittered backoff, never what it cannot (401, 403, 409, 413, 422), and
+ * every refusal says what to do about it.
+ *
+ * @see docs/server.md#the-store-protocol
+ */
+import { ObjectStoreWithPrefix } from './store-prefix.js';
+/** What an Atlas server said no to, with what to do about it. */
+export class AtlasHttpError extends Error {
+    status;
+    retryable;
+    constructor(message, status, retryable = false) {
+        super(message);
+        this.status = status;
+        this.retryable = retryable;
+        this.name = 'AtlasHttpError';
+    }
+}
+const encode = (key) => key.split('/').map(encodeURIComponent).join('/');
+function explain(status, base, message) {
+    const said = message ? `: ${message}` : '';
+    switch (status) {
+        case 401: return `${base} wants a token${said}. Set ATLAS_TOKEN (a publish token to upload, a read token to read).`;
+        case 403: return `${base} knows this token but it may not do that${said}. Uploading needs a publish or admin token.`;
+        case 409: return `${base} refused a change to something that already exists${said}`;
+        case 413: return `${base} refused an object that large${said}. Attach big files by uri, or raise the server's limits.maxObjectMiB.`;
+        case 422: return `${base} did not accept it${said}`;
+        default: return `${base} answered ${status}${said}`;
+    }
+}
+/**
+ * An {@link ObjectStore} on an Atlas server, over its store protocol (`/api/store`). The server holds the
+ * layers (on its own disk, or in whatever backends it was given), checks what is uploaded, and shows
+ * everyone the combined report at once. Anything that publishes to a store, `publishChecks`, spec sets,
+ * run uploads, `copyStore`, works against it unchanged.
+ */
+export function httpStore(options) {
+    const base = options.url.replace(/\/+$/, '');
+    const root = `${base}/api/store`;
+    const doFetch = options.fetch ?? fetch;
+    const retries = options.retries ?? 4;
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    const sleep = options.sleep ?? ((ms) => new Promise(resolve => setTimeout(resolve, ms)));
+    const authorization = options.token ? { authorization: `Bearer ${options.token}` } : {};
+    async function request(method, url, init = {}) {
+        for (let attempt = 0;; attempt++) {
+            let failure;
+            try {
+                // The clock is for the server to start answering; a large body may take longer to arrive.
+                const controller = new AbortController();
+                const timer = setTimeout(() => controller.abort(), timeoutMs);
+                let response;
+                try {
+                    response = await doFetch(url, { method, headers: init.contentType ? { ...authorization, 'content-type': init.contentType } : authorization, ...(init.body ? { body: init.body } : {}), signal: controller.signal });
+                }
+                finally {
+                    clearTimeout(timer);
+                }
+                if (response.ok)
+                    return response;
+                if (response.status === 404 && init.allow404) {
+                    await response.body?.cancel();
+                    return null;
+                }
+                const said = await response.json().then((body) => body.error ?? null, () => null);
+                failure = new AtlasHttpError(explain(response.status, base, said), response.status, response.status >= 500 || response.status === 429 || response.status === 408);
+            }
+            catch (error) {
+                failure = new AtlasHttpError(`cannot reach ${base} (${error instanceof Error ? (error.name === 'AbortError' ? `no answer in ${timeoutMs} ms` : error.message) : String(error)})`, null, true);
+            }
+            if (!failure.retryable || attempt >= retries)
+                throw failure;
+            await sleep(Math.random() * Math.min(8_000, 100 * 2 ** attempt));
+        }
+    }
+    const store = {
+        label: base,
+        url: base,
+        async get(key) {
+            const response = await request('GET', `${root}/${encode(key)}`, { allow404: true });
+            if (!response)
+                return null;
+            return { body: response.body ?? new Blob([]).stream(), contentType: response.headers.get('content-type') ?? 'application/octet-stream', size: Number(response.headers.get('content-length') ?? 0) };
+        },
+        async put(key, bytes, contentType) {
+            await (await request('PUT', `${root}/${encode(key)}`, { body: bytes, contentType }))?.arrayBuffer();
+        },
+        async head(key) {
+            return (await request('HEAD', `${root}/${encode(key)}`, { allow404: true })) !== null;
+        },
+        async delete(key) {
+            await (await request('DELETE', `${root}/${encode(key)}`, { allow404: true }))?.arrayBuffer();
+        },
+        async deleteMany(keys) {
+            for (const key of keys)
+                await store.delete(key);
+        },
+        async getUri() {
+            return null;
+        },
+        async listPage(prefix = '', page = {}) {
+            const query = new URLSearchParams({ prefix, limit: String(page.limit ?? 1000) });
+            if (page.after !== undefined)
+                query.set('after', page.after);
+            const response = (await request('GET', `${root}?${query}`));
+            const body = await response.json();
+            if (!Array.isArray(body.keys))
+                throw new AtlasHttpError(`${base} did not answer a listing`, response.status);
+            return { keys: body.keys, next: body.next ?? null };
+        },
+        async listKeys(prefix = '') {
+            const keys = [];
+            for (let after;;) {
+                const page = await store.listPage(prefix, after === undefined ? {} : { after });
+                keys.push(...page.keys);
+                if (page.next === null)
+                    return keys;
+                after = page.next;
+            }
+        },
+        withPrefix(prefix) {
+            return new ObjectStoreWithPrefix(store, prefix);
+        },
+        async status(query = new URLSearchParams()) {
+            const suffix = query.size ? `?${query}` : '';
+            return (await request('GET', `${base}/api/status${suffix}`)).json();
+        },
+        async ping() {
+            const started = performance.now();
+            try {
+                const response = (await request('GET', `${base}/api/server`));
+                const info = await response.json();
+                return { ok: true, ms: Math.round(performance.now() - started), ...(info.role ? { role: info.role } : {}) };
+            }
+            catch (error) {
+                return { ok: false, ms: Math.round(performance.now() - started), error: error instanceof Error ? error.message : String(error) };
+            }
+        }
+    };
+    return store;
+}

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

@@ -1,3 +1,10 @@
+/**
+ * @module HTTP client port
+ *
+ * The one thing the reports readers need from the network, as a type, so a host can supply `fetch`, an
+ * authenticating wrapper or a test double.
+ */
+/** Anything with a `fetch` of the standard signature. The readers only call it; they do not retry or add credentials. */
 export type HttpClient = {
     fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
 };

package/dist/reports/src/http.js

@@ -0,0 +1,6 @@
+/**
+ * @module HTTP client port
+ *
+ * The one thing the reports readers need from the network, as a type, so a host can supply `fetch`, an
+ * authenticating wrapper or a test double.
+ */

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

@@ -0,0 +1,54 @@
+import type { EvidenceCheck } from './explorer-types.js';
+/** The checks an existing test report holds, and when it was recorded when the report says. */
+export type IngestedChecks = {
+    /** One per test, with ids made unique. Attachments that name a file carry a `path` for the publisher to read; see `attachment-files.ts`. */
+    readonly checks: readonly EvidenceCheck[];
+    /**
+     * For each check, in order, the names the report gave its container (suite, class, file), which
+     * can name the spec it checks when the report has no path for it.
+     */
+    readonly hints?: readonly (readonly string[])[];
+    /** When the report says the run ended (or started), epoch milliseconds; null when it does not say. */
+    readonly recordedAtMs: number | null;
+    /** The tool that wrote the report, when it says. */
+    readonly tool: string | null;
+    /** What the report says about the run as a whole: the tool, the build, the platform. */
+    readonly labels?: Readonly<Record<string, string>>;
+};
+/** Never silently count two checks as one: the first check with an id keeps it and a repeat becomes `<id> #2`, `<id> #3`, ... in input order. */
+export declare function uniqueChecks(checks: readonly EvidenceCheck[]): EvidenceCheck[];
+/**
+ * A [CTRF](https://ctrf.io) report (`results.tests`). A check's id is its file, its suites and its
+ * name, so the same test keeps the same id in every run. Skipped, pending and other results are
+ * `not-run`: never a pass; a status this function does not know is also `not-run`.
+ *
+ * Also carries what CTRF has beyond the outcome as evidence: tags, labels (browser, device, flaky, run environment
+ * and tool), steps, attachments (files by `path`, `url` as `uri`, inline screenshot, stdout/stderr, trace), retry
+ * attempts, a snippet annotation and `extra` under the `ctrf.extra` extension. `recordedAtMs` is `summary.stop`,
+ * else `summary.start`. Throws `Not a CTRF report: results.tests is missing` when there is no `results.tests` array.
+ *
+ * @param report The parsed CTRF JSON.
+ */
+export declare function checksFromCtrf(report: unknown): IngestedChecks;
+/**
+ * A JUnit XML report: one check per `<testcase>`, identified by its file or class and its name (`file or classname > name`).
+ *
+ * A case with a `<failure>` (an assertion that did not hold) or an `<error>` (an exception) is `failed`, one with
+ * `<skipped>` is `not-run`, any other is `passed`. Durations are seconds converted to milliseconds. Properties become labels, `<system-out>`/`<system-err>` become log
+ * attachments, and a Jenkins `[[ATTACHMENT|path]]` line in the output attaches that file by `path`. `recordedAtMs`
+ * is the newest `<testsuite timestamp>` (a timestamp with no offset is read as UTC). Throws
+ * `Not a JUnit report: no <testsuite> found` when the text has no test cases and no `<testsuite`.
+ */
+export declare function checksFromJunit(xml: string): IngestedChecks;
+/**
+ * An Atlas run (`manifest.json`): one check per path. A path's key, which the same start and
+ * events give in every run, is its id. A flaky path passed. While the run is still going, a
+ * running path is `running` and a queued one `not-run`, so a snapshot never reads as finished.
+ *
+ * Every check's `specPath` is the run's root chart file under its spec directory. A run is still going when
+ * `run.finishedAt` is `null`. `recordedAtMs` is `run.finishedAt`, else `run.startedAt` plus `run.durationMs`.
+ * Throws `Not an Atlas manifest: run and paths are required` when `paths` or `run.id` is missing.
+ *
+ * @param manifest The parsed `manifest.json` of an Atlas run.
+ */
+export declare function checksFromManifest(manifest: unknown): IngestedChecks;