@crvouga/atlas 0.4.0 → 0.6.0

package/dist/server/src/store-api.js

@@ -0,0 +1,180 @@
+/**
+ * @module Store protocol routes
+ *
+ * The `ObjectStore` interface over HTTP at `/api/store`: list keys under `layers/`, read and probe an object, upload one
+ * (checked by `validateUpload`, immutable once stored) and remove a scratch object. This is what `httpStore` talks to. An
+ * upload is told to the report only after it is stored, and a layer's manifest, parsed while it was checked, is handed on so
+ * it is not read again. Everything read is served as untrusted bytes (never sniffed, never run).
+ *
+ * @see docs/server.md#the-store-protocol
+ */
+import { Hono } from 'hono';
+import { isPaged } from '../../reports/src/object-store.js';
+import { readBytes } from '../../reports/src/object-io.js';
+import { UNTRUSTED_HEADERS } from '../../reports/src/attachment-response.js';
+import { classify, isCatalog, Refusal, sameBytes, validateUpload, validKey } from './validate.js';
+/** Read a request body, refusing as soon as it is over the limit rather than after holding it all. */
+export async function readLimited(request, limit) {
+    const declared = Number(request.headers.get('content-length') ?? NaN);
+    if (Number.isFinite(declared) && declared > limit)
+        throw new Refusal(413, `That is ${declared} bytes; the limit is ${limit}`);
+    if (!request.body)
+        return new Uint8Array();
+    const reader = request.body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > limit) {
+                await reader.cancel();
+                throw new Refusal(413, `The body is over the limit of ${limit} bytes`);
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const out = new Uint8Array(size);
+    let at = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, at);
+        at += chunk.byteLength;
+    }
+    return out;
+}
+const decode = (c, prefix) => {
+    try {
+        return decodeURIComponent(new URL(c.req.url).pathname.slice(prefix.length));
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * The store protocol: the seven operations of an object store over HTTP, for what the server keeps. A client
+ * that publishes to it uses the same code that publishes to a folder or a bucket. It differs from a bucket in
+ * that the server checks what it is given, keeps layers immutable, and tells every viewer when something lands.
+ *
+ *   GET    /api/store?prefix=&after=&limit=   a page of keys, in order
+ *   GET    /api/store/<key>                   the object
+ *   HEAD   /api/store/<key>                   does it exist
+ *   PUT    /api/store/<key>                   upload it (publish token, Bearer)
+ *   DELETE /api/store/<key>                   remove a scratch object (publish token, Bearer)
+ */
+/** A plain relative path: no traversal, no backslash, no control characters. */
+const safePath = (value) => value.length > 0 && value.length <= 1024 && !value.startsWith('/') && !value.includes('\\') && !/[\u0000-\u001f]/.test(value) && value.split('/').every(part => part !== '' && part !== '.' && part !== '..');
+/** The Hono app of the store protocol, to be mounted at `/api/store`. Reads need role `read`; writes need `publish` through a Bearer token. */
+export function storeApi(options) {
+    const app = new Hono();
+    const { store, auth } = options;
+    // A layer's manifest is validated when it arrives and its catalog entry follows: what was read the first time serves the second.
+    const recent = new Map();
+    // Serialize only competing writes to the same key. Other uploads retain their concurrency.
+    const writing = new Map();
+    async function exclusive(key, action) {
+        const previous = writing.get(key) ?? Promise.resolve();
+        const next = previous.catch(() => undefined).then(action);
+        writing.set(key, next);
+        try {
+            return await next;
+        }
+        finally {
+            if (writing.get(key) === next)
+                writing.delete(key);
+        }
+    }
+    const refuse = (c, status, message) => c.json({ error: message }, status);
+    app.get('/', async (c) => {
+        const verdict = auth.check(c.req.raw, 'read');
+        if (!verdict.ok)
+            return refuse(c, verdict.status, verdict.message);
+        // Only layers/ is listed: the whole store may hold other things.
+        const prefix = c.req.query('prefix') || 'layers/';
+        const after = c.req.query('after');
+        const limit = Math.max(1, Math.min(Number(c.req.query('limit') ?? 1000) || 1000, 1000));
+        const named = prefix.replace(/\/$/, '');
+        if (prefix !== 'layers/' && !validKey(named)) {
+            // Older layouts keep things outside layers/. A server holds none of them: nothing there, not an error.
+            if (safePath(named))
+                return c.json({ keys: [], next: null });
+            return refuse(c, 422, 'Not a prefix Atlas holds');
+        }
+        if (isPaged(store))
+            return c.json(await store.listPage(prefix, { ...(after === undefined ? {} : { after }), limit }));
+        const all = (await store.listKeys(prefix)).filter(key => after === undefined || key > after);
+        return c.json({ keys: all.slice(0, limit), next: all.length > limit ? all[limit - 1] : null });
+    });
+    const key = (c) => decode(c, '/api/store/');
+    app.on(['GET', 'HEAD'], '/*', async (c) => {
+        const verdict = auth.check(c.req.raw, 'read');
+        if (!verdict.ok)
+            return refuse(c, verdict.status, verdict.message);
+        const name = key(c);
+        if (name === null || !validKey(name)) {
+            if (name !== null && safePath(name))
+                return new Response(c.req.method === 'HEAD' ? null : JSON.stringify({ error: 'Not found' }), { status: 404, headers: { 'content-type': 'application/json' } });
+            return refuse(c, 422, 'Not a key Atlas holds');
+        }
+        const stored = await store.get(name);
+        if (!stored)
+            return new Response(c.req.method === 'HEAD' ? null : JSON.stringify({ error: 'Not found' }), { status: 404, headers: { 'content-type': 'application/json' } });
+        // Everything under layers/ is immutable, so it may be kept for good.
+        // What is stored came from a test run: it is never run, sniffed or embedded, whatever type its uploader gave it.
+        const type = /^[\w.+-]+\/[\w.+-]+(?:\s*;\s*[\w.-]+=[\w.\-"]+)*$/.test(stored.contentType) ? stored.contentType : 'application/octet-stream';
+        const headers = { 'content-type': type, ...UNTRUSTED_HEADERS, 'cache-control': 'public, max-age=31536000, immutable', ...(stored.size ? { 'content-length': String(stored.size) } : {}) };
+        if (c.req.method === 'HEAD') {
+            await stored.body.cancel();
+            return new Response(null, { headers });
+        }
+        return new Response(stored.body, { headers });
+    });
+    app.put('/*', async (c) => {
+        const verdict = auth.check(c.req.raw, 'publish');
+        if (!verdict.ok)
+            return refuse(c, verdict.status, verdict.message);
+        const name = key(c);
+        if (name === null || !validKey(name))
+            return refuse(c, 422, 'Not a key Atlas holds');
+        try {
+            const bytes = await readLimited(c.req.raw, options.maxObjectBytes);
+            return await exclusive(name, async () => {
+                const kind = await validateUpload(name, bytes, store, layer => { recent.set(layer.id, layer); if (recent.size > 8)
+                    recent.delete(recent.keys().next().value); });
+                // A blob's name is the digest of what is in it, which was just checked: one that is there is this one, however it was compressed.
+                const present = kind === 'blob' && (await store.head(name)) ? 'same' : await sameBytes(store, name, bytes);
+                // Scratch objects may be overwritten (an object store's contract says writing a key twice is fine); layers may not.
+                if (present === 'different' && kind !== 'scratch')
+                    throw new Refusal(409, `${name} already exists with other content. Layers are immutable: publish a new one.`);
+                if (present !== 'same')
+                    await store.put(name, bytes, c.req.header('content-type') ?? 'application/octet-stream');
+                // Catalog entries make a layer, spec set or run visible, so everyone is told only once they are in.
+                if (present === 'absent' || isCatalog(kind))
+                    await options.onStored(name, kind, kind === 'layer-catalog' ? recent.get(classify(name)?.id ?? '') : undefined);
+                return c.json({ ok: true, key: name, kind, created: present === 'absent' }, present === 'absent' ? 201 : 200);
+            });
+        }
+        catch (error) {
+            if (error instanceof Refusal)
+                return refuse(c, error.status, error.message);
+            throw error;
+        }
+    });
+    app.delete('/*', async (c) => {
+        const verdict = auth.check(c.req.raw, 'publish');
+        if (!verdict.ok)
+            return refuse(c, verdict.status, verdict.message);
+        const name = key(c);
+        // Nothing a report is made of can be taken away. Only what `atlas report doctor` writes to try the store.
+        if (name === null || classify(name)?.kind !== 'scratch')
+            return refuse(c, 403, 'Layers, specs and runs are never removed through the API');
+        await store.delete(name);
+        return c.body(null, 204);
+    });
+    return app;
+}
+export { readBytes };

package/dist/server/src/validate.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @module Upload validation
+ *
+ * What the server checks before it stores an object, so one bad upload cannot corrupt the report for everyone: the key is
+ * one Atlas writes (`classify`), a layer's content hashes to its id, blobs and spec files are what their names say, a
+ * document's files and a catalog entry's document are already there (so nothing half-uploaded is visible), and a run
+ * passed its privacy scan. Refusals are `Refusal`s carrying the HTTP status to answer. Layers are immutable: the same
+ * bytes again are fine, other bytes under the same key are not.
+ *
+ * @see docs/server.md#what-the-server-refuses
+ */
+import { readUtf8 } from '../../reports/src/object-io.js';
+import type { ObjectStore } from '../../reports/src/object-store.js';
+import type { ReportLayer } from '../../reports/src/layer-types.js';
+/** Why an upload was not accepted. The status is what to answer. */
+export declare class Refusal extends Error {
+    readonly status: 403 | 409 | 413 | 422;
+    constructor(status: 403 | 409 | 413 | 422, message: string);
+}
+/** The kinds of object Atlas writes, by their keys. Anything else is not for a server to hold. */
+declare const KINDS: readonly [{
+    readonly kind: "layer";
+    readonly pattern: RegExp;
+}, {
+    readonly kind: "layer-catalog";
+    readonly pattern: RegExp;
+}, {
+    readonly kind: "blob";
+    readonly pattern: RegExp;
+}, {
+    readonly kind: "spec-body";
+    readonly pattern: RegExp;
+}, {
+    readonly kind: "spec-set";
+    readonly pattern: RegExp;
+}, {
+    readonly kind: "spec-catalog";
+    readonly pattern: RegExp;
+}, {
+    readonly kind: "run-manifest";
+    readonly pattern: RegExp;
+}, {
+    readonly kind: "run-catalog";
+    readonly pattern: RegExp;
+}, {
+    readonly kind: "run-file";
+    readonly pattern: RegExp;
+}, {
+    readonly kind: "scratch";
+    readonly pattern: RegExp;
+}];
+/** What a key names: `layer`, `layer-catalog`, `blob`, `spec-body`, `spec-set`, `spec-catalog`, `run-manifest`, `run-catalog`, `run-file` or `scratch` (what `doctor` writes to try the store). */
+export type UploadKind = (typeof KINDS)[number]['kind'];
+/** Is this a key a client may name? No traversal, no odd characters, and under `layers/`. */
+export declare function validKey(key: string): boolean;
+/** What kind of object a key names and the id inside it (the layer id, the digest…), or null when it is not a key Atlas writes. */
+export declare function classify(key: string): {
+    kind: UploadKind;
+    id: string | null;
+} | null;
+/** Catalog entries are what makes something visible, so they are the last thing a client writes. */
+export declare const isCatalog: (kind: UploadKind) => kind is "layer-catalog" | "spec-catalog" | "run-catalog";
+/**
+ * Check an object before it is stored. What is checked is what would otherwise corrupt the report for everyone:
+ * a layer whose content is not its name, a catalog entry for something not there yet, a run that failed its
+ * privacy scan. Everything that is checked is checked cheaply, from the bytes in hand.
+ */
+export declare function validateUpload(key: string, bytes: Uint8Array, store: ObjectStore, parsedLayer?: (layer: ReportLayer) => void): Promise<UploadKind>;
+/** Is this the same object already? Layers are immutable: the same bytes again is fine, other bytes under the same key is not. */
+export declare function sameBytes(store: ObjectStore, key: string, bytes: Uint8Array): Promise<'absent' | 'same' | 'different'>;
+export { readUtf8 };

package/dist/server/src/validate.js

@@ -0,0 +1,197 @@
+/**
+ * @module Upload validation
+ *
+ * What the server checks before it stores an object, so one bad upload cannot corrupt the report for everyone: the key is
+ * one Atlas writes (`classify`), a layer's content hashes to its id, blobs and spec files are what their names say, a
+ * document's files and a catalog entry's document are already there (so nothing half-uploaded is visible), and a run
+ * passed its privacy scan. Refusals are `Refusal`s carrying the HTTP status to answer. Layers are immutable: the same
+ * bytes again are fine, other bytes under the same key are not.
+ *
+ * @see docs/server.md#what-the-server-refuses
+ */
+import { promisify } from 'node:util';
+import { gunzip } from 'node:zlib';
+import { parseLayerDocument, SpecSetSchema } from '../../schema/src/layer.js';
+import { readUtf8 } from '../../reports/src/object-io.js';
+import { eachLimited } from '../../reports/src/completion-order.js';
+import { sha256Hex } from '../../reports/src/sigv4.js';
+/** Why an upload was not accepted. The status is what to answer. */
+export class Refusal extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+const HEX = '[0-9a-f]{64}';
+const KEY_LENGTH = 1024;
+/** The kinds of object Atlas writes, by their keys. Anything else is not for a server to hold. */
+const KINDS = [
+    { kind: 'layer', pattern: new RegExp(`^layers/manifests/(${HEX})\\.json$`) },
+    { kind: 'layer-catalog', pattern: new RegExp(`^layers/index/\\d{16}-(${HEX})\\.json$`) },
+    { kind: 'blob', pattern: new RegExp(`^layers/blobs/(${HEX})\\.gz$`) },
+    { kind: 'spec-body', pattern: new RegExp(`^layers/specs/blobs/(${HEX})\\.txt$`) },
+    { kind: 'spec-set', pattern: new RegExp(`^layers/specs/sets/(${HEX})\\.json$`) },
+    { kind: 'spec-catalog', pattern: new RegExp(`^layers/specs/index/\\d{16}-.+-[cmu]-(${HEX})\\.json$`) },
+    { kind: 'run-manifest', pattern: /^layers\/runs\/([\w.-]+)\/manifest\.json$/ },
+    { kind: 'run-catalog', pattern: /^layers\/runs\/index\/\d{16}-([\w.-]+)\.json$/ },
+    { kind: 'run-file', pattern: /^layers\/runs\/([\w.-]+)\/.+$/ },
+    { kind: 'scratch', pattern: /^layers\/doctor-[\w-]+\/.+$/ }
+];
+/** Is this a key a client may name? No traversal, no odd characters, and under `layers/`. */
+export function validKey(key) {
+    if (!key || key.length > KEY_LENGTH || !key.startsWith('layers/') || key.includes('\\') || /[\u0000-\u001f]/.test(key))
+        return false;
+    return key.split('/').every(part => part !== '' && part !== '.' && part !== '..');
+}
+/** What kind of object a key names and the id inside it (the layer id, the digest…), or null when it is not a key Atlas writes. */
+export function classify(key) {
+    for (const { kind, pattern } of KINDS) {
+        const match = pattern.exec(key);
+        if (match)
+            return { kind, id: match[1] ?? null };
+    }
+    return null;
+}
+/** Catalog entries are what makes something visible, so they are the last thing a client writes. */
+export const isCatalog = (kind) => kind === 'layer-catalog' || kind === 'spec-catalog' || kind === 'run-catalog';
+const gunzipAsync = promisify(gunzip);
+/** The most a blob may expand to: what a layer may carry in total. A small file that expands to more is refused, not inflated. */
+const MAX_BLOB_BYTES = 2 * 1024 * 1024 * 1024;
+/** Parsed JSON that is not an object (a `null`, a number) names nothing: a refusal, not a crash. */
+function objectOf(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        throw new Refusal(422, 'A catalog entry is a JSON object with the id of what it makes visible');
+    return value;
+}
+async function exists(store, key) {
+    return store.head(key);
+}
+/** Which of `keys` the store does not have, asked 16 at a time (a store far away answers each in its own time). */
+async function missingOf(store, keys) {
+    const absent = new Set();
+    await eachLimited(keys, 16, async (key) => { if (!(await exists(store, key)))
+        absent.add(key); });
+    return keys.filter(key => absent.has(key));
+}
+/**
+ * Check an object before it is stored. What is checked is what would otherwise corrupt the report for everyone:
+ * a layer whose content is not its name, a catalog entry for something not there yet, a run that failed its
+ * privacy scan. Everything that is checked is checked cheaply, from the bytes in hand.
+ */
+export async function validateUpload(key, bytes, store, parsedLayer) {
+    const known = classify(key);
+    if (!known)
+        throw new Refusal(422, `"${key}" is not a key Atlas writes`);
+    // Parsed once, however many of the checks below look at it.
+    let parsed;
+    const json = () => {
+        if (!parsed) {
+            try {
+                parsed = { value: JSON.parse(new TextDecoder().decode(bytes)) };
+            }
+            catch {
+                throw new Refusal(422, `${key} is not JSON`);
+            }
+        }
+        return parsed.value;
+    };
+    switch (known.kind) {
+        case 'layer': {
+            const document = parseLayerDocument(json());
+            if (!document.ok)
+                throw new Refusal(422, document.reason);
+            const raw = json();
+            if (raw.id !== known.id)
+                throw new Refusal(422, 'The layer\'s id is not the one in its key');
+            // The id is the digest of the document without it: a layer cannot be named for something it is not.
+            const { id: _id, ...rest } = raw;
+            if ((await sha256Hex(JSON.stringify(rest))) !== known.id)
+                throw new Refusal(422, 'The layer\'s content does not match its id (it was changed, or written by something that does not follow the format)');
+            const blobs = [...new Set(Object.values(document.layer.bundle).flatMap(entry => entry.parts.map(part => part.blob)))];
+            const missing = await missingOf(store, blobs);
+            if (missing.length)
+                throw new Refusal(409, `The layer needs files that have not been uploaded yet: ${missing.slice(0, 3).join(', ')}. Upload blobs before the manifest.`);
+            // What was just read is what the report folds in: handed on so it is not read from the store again.
+            const { schemaVersion: _version, ...layer } = document.layer;
+            parsedLayer?.(layer);
+            break;
+        }
+        case 'layer-catalog': {
+            const entry = objectOf(json());
+            if (entry.id !== known.id)
+                throw new Refusal(422, 'The catalog entry names another layer than its key does');
+            if (!(await exists(store, `layers/manifests/${known.id}.json`)))
+                throw new Refusal(409, 'That layer has not been uploaded yet. Upload its manifest before its catalog entry.');
+            break;
+        }
+        case 'spec-body':
+            if ((await sha256Hex(bytes)) !== known.id)
+                throw new Refusal(422, 'The spec\'s text does not match the digest in its key');
+            break;
+        case 'spec-set': {
+            const set = SpecSetSchema.safeParse(json());
+            if (!set.success)
+                throw new Refusal(422, `Not a valid spec set: ${set.error.issues[0]?.message ?? 'unknown'}`);
+            if (set.data.id !== known.id)
+                throw new Refusal(422, 'The spec set\'s id is not the one in its key');
+            const lacking = new Set(await missingOf(store, [...new Set(set.data.files.map(file => `layers/specs/blobs/${file.digest}.txt`))]));
+            const first = set.data.files.find(file => lacking.has(`layers/specs/blobs/${file.digest}.txt`));
+            if (first)
+                throw new Refusal(409, `The spec set needs ${first.path}, which has not been uploaded yet`);
+            break;
+        }
+        case 'spec-catalog': {
+            const entry = objectOf(json());
+            if (entry.id !== known.id)
+                throw new Refusal(422, 'The catalog entry names another spec set than its key does');
+            if (!(await exists(store, `layers/specs/sets/${known.id}.json`)))
+                throw new Refusal(409, 'That spec set has not been uploaded yet');
+            break;
+        }
+        case 'run-manifest': {
+            const manifest = json();
+            // The rule the static viewer always had: a run that did not pass its privacy scan is never shared.
+            if (manifest?.privacy?.passed !== true)
+                throw new Refusal(422, `Run ${known.id} is not shared: its privacy scan did not pass (or never ran)`);
+            break;
+        }
+        case 'run-catalog': {
+            if (!(await exists(store, `layers/runs/${known.id}/manifest.json`)))
+                throw new Refusal(409, 'That run has not been uploaded yet. Upload its manifest before its catalog entry.');
+            json();
+            break;
+        }
+        case 'blob': {
+            // The key is the digest of the uncompressed bytes. Checked the way a layer is, so a blob cannot be named for something it is not.
+            let raw;
+            try {
+                raw = new Uint8Array(await gunzipAsync(bytes, { maxOutputLength: MAX_BLOB_BYTES }));
+            }
+            catch {
+                throw new Refusal(422, 'A blob is gzip; this one could not be read as such');
+            }
+            if ((await sha256Hex(raw)) !== known.id)
+                throw new Refusal(422, 'The blob\'s content does not match the digest in its key');
+            break;
+        }
+        case 'run-file':
+        case 'scratch':
+            break;
+    }
+    return known.kind;
+}
+/** Is this the same object already? Layers are immutable: the same bytes again is fine, other bytes under the same key is not. */
+export async function sameBytes(store, key, bytes) {
+    const existing = await store.get(key);
+    if (!existing)
+        return 'absent';
+    const stored = new Uint8Array(await new Response(existing.body).arrayBuffer());
+    if (stored.length !== bytes.length)
+        return 'different';
+    for (let i = 0; i < stored.length; i++)
+        if (stored[i] !== bytes[i])
+            return 'different';
+    return 'same';
+}
+export { readUtf8 };

package/dist/vitest/src/index.d.ts

@@ -1,4 +1,13 @@
+/**
+ * @module Test-runner adapter
+ *
+ * Runs an Atlas config as a test suite in Vitest, `bun test` or any Jest-style runner. The runner's own
+ * `describe`, `it`, `beforeAll` and `expect` are passed in, so this module imports no test framework
+ * and never touches global test state. It owns the mapping from planned paths to tests; the run itself
+ * is `runConfig` from the core.
+ */
 import type { AtlasConfig, RunCommandOptions } from '../../core/src/index.js';
+/** The subset of a Vitest/Jest-style runner's API that `describeAtlas` calls. */
 type Suite = {
     describe: (name: string, fn: () => void) => void;
     it: (name: string, fn: () => void | Promise<void>, timeout?: number) => void;
@@ -8,12 +17,25 @@ type Suite = {
     };
 };
 /**
- * Turn an Atlas config into a test suite: one test per planned path, so any Vitest/Jest-style
- * runner reports each journey and generated path on its own. The whole plan runs once in
- * `beforeAll` (paths share one manifest); each test then reads its path's outcome.
+ * Registers a test suite for an Atlas config: one test that the charts are executable (no structural
+ * lint finding), then one test per planned path, so any Vitest/Jest-style runner reports each journey
+ * and generated path on its own. The whole plan runs once in `beforeAll` (paths share one manifest);
+ * each test then reads its path's outcome. A failed path fails its test with the last attempt's error;
+ * `passed` and `flaky` paths pass; a path that was `not-reached` (blocked by an event with no
+ * implementation) or was not part of the run passes quietly.
+ *
+ * `prepare` runs synchronously when `describeAtlas` is called, so specs that cannot be loaded throw at
+ * collection time. The run writes its output like `atlas run` does.
+ *
+ * @param config the Atlas config to run.
+ * @param suite the runner's `describe`, `it`, `beforeAll` and `expect`.
+ * @param options the `atlas run` options (`mode`, `paths`, `retry`, `output`, `log`, ...);
+ *   `baseDirectory` resolves relative config paths (the current directory when omitted) and `timeoutMs`
+ *   bounds the `beforeAll` (30 minutes by default). Progress lines are discarded unless `log` is given.
  *
- *   import { describe, it, beforeAll, expect } from 'bun:test';
- *   describeAtlas(config, { describe, it, beforeAll, expect });
+ * @example
+ * import { beforeAll, describe, expect, it } from 'bun:test';
+ * describeAtlas(config, { describe, it, beforeAll, expect });
  */
 export declare function describeAtlas<C>(config: AtlasConfig<C>, suite: Suite, options?: RunCommandOptions & {
     baseDirectory?: string;

package/dist/vitest/src/index.js

@@ -1,11 +1,24 @@
 import { prepare, runConfig } from '../../core/src/index.js';
 /**
- * Turn an Atlas config into a test suite: one test per planned path, so any Vitest/Jest-style
- * runner reports each journey and generated path on its own. The whole plan runs once in
- * `beforeAll` (paths share one manifest); each test then reads its path's outcome.
+ * Registers a test suite for an Atlas config: one test that the charts are executable (no structural
+ * lint finding), then one test per planned path, so any Vitest/Jest-style runner reports each journey
+ * and generated path on its own. The whole plan runs once in `beforeAll` (paths share one manifest);
+ * each test then reads its path's outcome. A failed path fails its test with the last attempt's error;
+ * `passed` and `flaky` paths pass; a path that was `not-reached` (blocked by an event with no
+ * implementation) or was not part of the run passes quietly.
  *
- *   import { describe, it, beforeAll, expect } from 'bun:test';
- *   describeAtlas(config, { describe, it, beforeAll, expect });
+ * `prepare` runs synchronously when `describeAtlas` is called, so specs that cannot be loaded throw at
+ * collection time. The run writes its output like `atlas run` does.
+ *
+ * @param config the Atlas config to run.
+ * @param suite the runner's `describe`, `it`, `beforeAll` and `expect`.
+ * @param options the `atlas run` options (`mode`, `paths`, `retry`, `output`, `log`, ...);
+ *   `baseDirectory` resolves relative config paths (the current directory when omitted) and `timeoutMs`
+ *   bounds the `beforeAll` (30 minutes by default). Progress lines are discarded unless `log` is given.
+ *
+ * @example
+ * import { beforeAll, describe, expect, it } from 'bun:test';
+ * describeAtlas(config, { describe, it, beforeAll, expect });
  */
 export function describeAtlas(config, suite, options = {}) {
     const prepared = prepare(config, options.baseDirectory);

package/dist/webdriver/src/driver.d.ts

@@ -4,33 +4,50 @@ import type { Locator } from './protocol.js';
 import { WebDriverSession } from './protocol.js';
 /** What a step points at: a signal (resolved per platform) or a raw WebDriver locator. */
 export type Target = Signal | Locator;
+/** How signals are resolved: `web` evaluates a DOM probe in the page, `native` queries the accessibility tree (an Appium session). */
 export type Mode = 'web' | 'native';
-/** What every event and recogniser receives: the session and user actions logged to the timeline. */
+/**
+ * What every event and recogniser receives from `webdriverDriver`: the open session plus a
+ * `SignalContext` whose targets may also be raw locators. It is created per attempt (or once per run
+ * with `session: 'per-run'`) and carries the actions that are logged to the step timeline.
+ */
 export type WebDriverContext = SignalContext & {
+    /** The open WebDriver session, for protocol calls the context does not wrap (`session.execute`, `session.command`). */
     session: WebDriverSession;
+    /** Whether signals resolve in the DOM (`web`) or the accessibility tree (`native`). */
     mode: Mode;
+    /** What `goto` resolves paths against; undefined when the options set no `baseUrl`. */
     baseUrl: string | undefined;
-    /** Navigate, relative to `baseUrl` (a deep link in a native session). */
+    /** Navigate, relative to `baseUrl` (a deep link in a native session). Without a `baseUrl` the URL is sent as given. */
     goto(url: string): Promise<void>;
-    /** The first visible element a target resolves to, or null. */
+    /** The id of the first visible element a target resolves to, or null. Does not wait. */
     find(target: Target): Promise<string | null>;
+    /** Whether the target resolves to a visible element right now. Does not wait; resolution errors count as not visible. */
     isVisible(target: Target): Promise<boolean>;
+    /** Actions a person does; each is added to the step timeline (with the element's centre as the tap position) and then performed. */
     user: {
+        /** Clicks the target's element, polling up to `actionTimeoutMs` for it to appear; throws `<target> is not on screen` otherwise. `label` is the caption. */
         tap(target: Target, label: string): Promise<void>;
+        /** Clicks the target's element to focus it, then sends `text` as keys (it does not clear existing text); waits and throws like `tap`. */
         type(target: Target, text: string, label: string): Promise<void>;
     };
 };
+/** A WebDriver server binary the driver starts for the run and kills when the driver is disposed. */
 export type WebDriverServer = {
     /** The server binary: `safaridriver`, `chromedriver`, `geckodriver`, `appium`. */
     command: string;
-    /** `{port}` is replaced with the port. Defaults: `--port {port}` (`--port={port}` for chromedriver). */
+    /** `{port}` is replaced with the port. Defaults: `--port {port}` (`--port={port}` for chromedriver and msedgedriver). */
     args?: string[];
+    /** The port to listen on; a free port on 127.0.0.1 is picked when omitted. */
     port?: number;
+    /** How long to wait for the server to answer `GET /status` as ready, in milliseconds (default 30 000). */
     readyTimeoutMs?: number;
 };
+/** Options of `webdriverDriver`. `capabilities` and one of `url` or `server` are required. */
 export type WebDriverDriverOptions = {
-    /** A running WebDriver server; or set `server` to start one for the run. */
+    /** A running WebDriver server (for example `http://127.0.0.1:4723` for Appium); or set `server` to start one for the run. */
     url?: string;
+    /** A server to start for the run; used when `url` is not set. The driver throws on first use if neither is set. */
     server?: WebDriverServer;
     /** W3C capabilities (`alwaysMatch`), e.g. `{ browserName: 'safari' }` or Appium's `platformName`, `appium:app`. */
     capabilities: Record<string, unknown>;
@@ -44,7 +61,9 @@ export type WebDriverDriverOptions = {
     recording?: 'frames' | 'appium' | 'none';
     /** How long a tap waits for its target, in milliseconds (default 15 000). */
     actionTimeoutMs?: number;
+    /** The driver's name in reports; `webdriver:<platformName>` for native sessions, else `webdriver:<browserName>`, when omitted. */
     name?: string;
+    /** Pauses around actions in showcase mode, in milliseconds; 400 before and 900 after when omitted. */
     pacing?: {
         before: number;
         after: number;
@@ -55,15 +74,48 @@ export type WebDriverDriverOptions = {
      */
     concurrency?: number;
 };
-/** A signal as a native locator: test IDs are accessibility identifiers, text is any label, value or text. */
+/**
+ * Translates a signal into an Appium locator: a test ID becomes an `accessibility id`; text, labels
+ * and roles become an XPath over the label, name, value, text and content-desc attributes (a
+ * substring match unless `exact`), with a role narrowed to the matching XCUITest and UiAutomator2
+ * element types.
+ *
+ * @returns the locator, or null when the signal matches by regular expression, which XPath 1.0
+ *   cannot express (the driver then matches it against the page source instead).
+ * @throws Error for a `css` signal, which only works in web sessions.
+ */
 export declare function nativeLocator(signal: Signal): Locator | null;
 /**
- * Drive anything that speaks W3C WebDriver: Safari (safaridriver ships with macOS), Chrome,
- * Firefox and Edge, or a native iOS or Android app through Appium. Signals resolve in the DOM
- * for web sessions and in the accessibility tree for native ones (test IDs are accessibility
+ * Creates a driver for anything that speaks W3C WebDriver: Safari (safaridriver ships with macOS),
+ * Chrome, Firefox and Edge, or a native iOS or Android app through Appium. Signals resolve in the
+ * DOM for web sessions and in the accessibility tree for native ones (test IDs are accessibility
  * identifiers), so one implementation style covers both. Screenshots and the page source are
- * standard; clips are encoded from screenshots, or come from Appium's screen recorder.
+ * standard; clips are encoded from screenshots (FFmpeg on the `PATH`), or come from Appium's screen
+ * recorder.
+ *
+ * The WebDriver server is started lazily on the first attempt (`options.server`) or used as is
+ * (`options.url`); `dispose()` deletes the shared session and kills a server this driver started.
+ * With `session: 'per-attempt'` each attempt opens and deletes its own session. A server that exits
+ * or is not ready in time, and a session the server refuses, reject the attempt that needed them.
+ *
+ * @param options the server, capabilities and behaviour; see `WebDriverDriverOptions`.
+ * @returns a driver whose context is a `WebDriverContext`.
+ * @throws Error on the first attempt when neither `options.url` nor `options.server` is set.
+ *
+ * @example
+ * const driver = webdriverDriver({
+ *   server: { command: 'chromedriver' },
+ *   capabilities: { browserName: 'chrome', 'goog:chromeOptions': { args: ['--headless=new'] } },
+ *   baseUrl: 'http://localhost:3000'
+ * });
  */
 export declare function webdriverDriver(options: WebDriverDriverOptions): Driver<WebDriverContext>;
-/** A state recognised from signals or locators: every `all` visible and no `none` visible. */
+/**
+ * Builds a state implementation recognised from signals or raw locators: every `all` target visible,
+ * one of `any` (when given) and none of `none`. `checks` pair a statement from the state's
+ * `meta.checks` with the target that proves it. A target whose lookup throws counts as not visible.
+ *
+ * @example
+ * states: { 'Visit booked': screen({ all: [text('Booked for')], none: [accessibilityId('book-button')] }) }
+ */
 export declare const screen: (spec: import('../../core/src/signals.js').ScreenSpec<WebDriverContext, Target>) => import('../../core/src/index.js').StateImplementation<WebDriverContext>;