@crvouga/atlas 0.3.0 → 0.5.0

package/dist/reports/src/report-index.js

@@ -0,0 +1,337 @@
+/**
+ * @module Incremental report index
+ *
+ * `ReportIndex` is the report, maintained as layers arrive. Each immutable layer is read once and folded into the winning
+ * result of every slot it fills, then dropped unless it still holds a winner, so memory follows the number of checks and not
+ * the age of the project. The winner rule is a total order, so folding is exact in any order and equals combining every layer
+ * from scratch (a test proves it over random partial runs). It also keeps what each layer sends (rows, JSON, a digest) until
+ * that layer changes, so taking in a result costs one layer, answers viewers a version hash, a cached JSON text and a delta,
+ * and tells listeners what arrived.
+ *
+ * @see docs/report-contract.md
+ * @see docs/server.md#performance
+ */
+import { createHash } from 'node:crypto';
+import { eachLimited } from './completion-order.js';
+import { LAYER_INDEX, layerSummary, readLayer } from './layer-store.js';
+import { layerEvidence, layerResultKeys, replaces } from './layer-merge.js';
+import { readUtf8 } from './object-io.js';
+import { isPaged } from './object-store.js';
+const RETRY_FAILED_MS = 5 * 60_000;
+/** Versions a viewer may still be holding, remembered so it can be sent only what changed. */
+const REMEMBERED_VERSIONS = 256;
+const REMEMBERED_REMOVALS = 4096;
+/**
+ * The report, maintained as layers arrive. Each layer is read once and folded into the winning result
+ * of every slot it fills, then dropped unless it still holds a winner. Because the winner rule is a
+ * total order, folding is exact in any order, so this equals combining every layer from scratch, with
+ * memory proportional to the number of checks and not to how long the project has existed.
+ *
+ * It reads only immutable layers (`layers/index/…`), which is what makes "read once" correct.
+ */
+export class ReportIndex {
+    #backends;
+    #concurrency;
+    #now;
+    #winners = new Map();
+    #held = new Map();
+    /** The smallest backend id a layer was found in, so attribution does not depend on read order. */
+    #attribution = new Map();
+    #folded = new Set();
+    #failed = new Map();
+    #available = new Map();
+    /** Counts every change to what the report shows. A layer remembers the count at which it last changed. */
+    #rev = 0;
+    /** The counts at which versions were seen, oldest first. */
+    #versions = new Map();
+    /** Layers that stopped holding any winner, and when. Older removals are forgotten; `#forgotten` says how far. */
+    #removed = [];
+    #forgotten = 0;
+    #refreshing = null;
+    #timer = null;
+    #refreshedAt = 0;
+    #cached = null;
+    #include;
+    #fullListEvery;
+    #listeners = new Set();
+    #added = [];
+    #announced = '';
+    #passes = 0;
+    /** Layers handed over by an uploader, read one at a time in the order they came. */
+    #accepting = Promise.resolve();
+    constructor(backends, options = {}) {
+        this.#backends = backends;
+        this.#include = options.include ?? (() => true);
+        this.#fullListEvery = Math.max(1, options.fullListEvery ?? 30);
+        this.#concurrency = options.concurrency ?? 64;
+        this.#now = options.now ?? Date.now;
+    }
+    /** Read what is new in every backend and fold it in. Resolves true when the report changed. Calls overlap safely. */
+    refresh() {
+        this.#refreshing ??= this.#refresh().finally(() => { this.#refreshing = null; });
+        return this.#refreshing;
+    }
+    /**
+     * A refresh that surely starts after this call: one already under way may have looked before whatever
+     * made the caller ask. Used when something was just written.
+     */
+    async refreshNow() {
+        const running = this.#refreshing;
+        const earlier = running ? await running.catch(() => false) : false;
+        return (await this.refresh()) || earlier;
+    }
+    /**
+     * Take in a layer an uploader has just written, from its catalog entry, without listing anything. Entries
+     * are read one after another; one already known is ignored. The regular refresh still reconciles the rest.
+     */
+    accept(backendId, indexKey, known) {
+        const backend = this.#backends.find(item => item.id === backendId);
+        if (!backend)
+            return Promise.resolve();
+        this.#accepting = this.#accepting.then(async () => {
+            const mark = `${backend.id}|${indexKey}`;
+            if (this.#folded.has(mark))
+                return;
+            await this.#load(backend, indexKey, known);
+            this.#emit();
+        }).catch(() => { });
+        return this.#accepting;
+    }
+    /** Be told when the report changes. Returns how to stop. */
+    onChange(listener) {
+        this.#listeners.add(listener);
+        return () => { this.#listeners.delete(listener); };
+    }
+    #emit() {
+        if (!this.#listeners.size && !this.#added.length)
+            return;
+        const { version, totalLayers } = this.snapshot();
+        // Say it once per distinct report, and whenever layers arrived (they are news even if nothing they hold wins).
+        if (version === this.#announced && !this.#added.length)
+            return;
+        this.#announced = version;
+        const added = this.#added.sort((a, b) => b.recordedAtMs - a.recordedAtMs || (a.id < b.id ? -1 : 1));
+        this.#added = [];
+        for (const listener of this.#listeners) {
+            try {
+                listener({ version, added, totalLayers });
+            }
+            catch { /* a listener that fails does not stop the others */ }
+        }
+    }
+    /** Keep refreshing in the background. The first call returns once the first pass has finished. */
+    async start(intervalMs) {
+        await this.refresh();
+        this.#timer = setInterval(() => { void this.refresh().catch(() => { }); }, intervalMs);
+        this.#timer.unref?.();
+    }
+    /** Stops the background refresh started by `start`. Safe to call twice. */
+    stop() {
+        if (this.#timer)
+            clearInterval(this.#timer);
+        this.#timer = null;
+    }
+    /** True once a first pass over the backends has finished, so `snapshot` is a report and not an empty guess. */
+    get ready() {
+        return this.#refreshedAt > 0;
+    }
+    async #refresh() {
+        const before = this.#rev;
+        const fresh = [];
+        // The whole catalog on the first pass and now and then; otherwise only its newest end, where new layers sort.
+        const full = this.#passes++ % this.#fullListEvery === 0;
+        await Promise.all(this.#backends.map(async (backend) => {
+            try {
+                const consider = (key) => { if (!this.#folded.has(`${backend.id}|${key}`) && !this.#recentlyFailed(`${backend.id}|${key}`))
+                    fresh.push({ backend, key }); };
+                if (!full && isPaged(backend.store)) {
+                    // Newest first: pages of keys we already know mean nothing newer is behind them.
+                    for (let after;;) {
+                        const page = await backend.store.listPage(LAYER_INDEX, { ...(after === undefined ? {} : { after }), limit: 1000 });
+                        let unknown = 0;
+                        for (const key of page.keys) {
+                            if (!this.#folded.has(`${backend.id}|${key}`))
+                                unknown += 1;
+                            consider(key);
+                        }
+                        if (page.next === null || unknown < page.keys.length)
+                            break;
+                        after = page.next;
+                    }
+                }
+                else {
+                    for (const key of await backend.store.listKeys(LAYER_INDEX))
+                        consider(key);
+                }
+                this.#available.set(backend.id, true);
+                this.#failed.delete(`${backend.id}|`);
+            }
+            catch (error) {
+                this.#available.set(backend.id, false);
+                this.#failed.set(`${backend.id}|`, { at: this.#now(), message: `${backend.label ?? backend.id} is unavailable: ${error instanceof Error ? error.message : String(error)}` });
+            }
+        }));
+        // Oldest first or newest first gives the same report; newest first shows recent work soonest.
+        fresh.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : a.backend.id < b.backend.id ? -1 : 1));
+        await eachLimited(fresh, this.#concurrency, ({ backend, key }) => this.#load(backend, key));
+        this.#refreshedAt = this.#now();
+        this.#emit();
+        return this.#rev !== before;
+    }
+    async #load(backend, key, known) {
+        const mark = `${backend.id}|${key}`;
+        try {
+            let layer;
+            let id;
+            if (known && key.endsWith(`-${known.id}.json`)) {
+                // The caller has just written and read this layer: its entry names it, so there is nothing to look up.
+                id = known.id;
+                layer = known;
+            }
+            else {
+                const raw = await readUtf8(backend.store, key);
+                id = raw ? JSON.parse(raw).id : undefined;
+                layer = id ? await readLayer(backend.store, id) : null;
+            }
+            if (!id || !layer)
+                throw new Error('an indexed layer is missing');
+            this.#fold(layerEvidence(layerSummary(layer), backend.id), backend.id);
+            this.#folded.add(mark);
+            this.#failed.delete(mark);
+            this.#refreshedAt ||= this.#now();
+        }
+        catch (error) {
+            this.#failed.set(mark, { at: this.#now(), message: `${backend.label ?? backend.id}: a layer could not be read, so its outcome is unknown (${error instanceof Error ? error.message : String(error)})` });
+        }
+    }
+    #recentlyFailed(mark) {
+        const failure = this.#failed.get(mark);
+        return failure !== undefined && this.#now() - failure.at < RETRY_FAILED_MS;
+    }
+    #fold(evidence, backend) {
+        const id = evidence.id;
+        const known = this.#attribution.get(id);
+        if (known !== undefined) {
+            // The same immutable layer in another backend: one layer, attributed to the backend that sorts first.
+            if (backend < known) {
+                this.#attribution.set(id, backend);
+                const held = this.#held.get(id);
+                if (held)
+                    this.#touch(held);
+                else
+                    this.#rev += 1;
+            }
+            return;
+        }
+        this.#attribution.set(id, backend);
+        if (!this.#include(evidence.layer))
+            return;
+        this.#added.push({ ...evidence.layer, backend });
+        const wins = new Set();
+        const keyOf = layerResultKeys(evidence.layer);
+        for (const row of evidence.rows) {
+            const key = keyOf(row);
+            const result = { key, slot: '', layer: evidence.layer, row, parameters: evidence.layer.parameters, warning: null };
+            const prior = this.#winners.get(key);
+            if (prior && !replaces(result, prior))
+                continue;
+            if (prior)
+                this.#release(prior.layer.id, key);
+            this.#winners.set(key, result);
+            wins.add(key);
+        }
+        if (wins.size) {
+            this.#held.set(id, { evidence, wins, rev: ++this.#rev, entry: null, json: null, digest: null });
+        }
+    }
+    /** What this layer sends has changed. */
+    #touch(held) {
+        held.rev = ++this.#rev;
+        held.entry = held.json = held.digest = null;
+    }
+    #release(layerId, key) {
+        const held = this.#held.get(layerId);
+        if (!held)
+            return;
+        held.wins.delete(key);
+        if (held.wins.size) {
+            this.#touch(held);
+            return;
+        }
+        this.#held.delete(layerId);
+        this.#removed.push({ id: layerId, rev: ++this.#rev });
+        if (this.#removed.length > REMEMBERED_REMOVALS)
+            this.#forgotten = this.#removed.splice(0, this.#removed.length - REMEMBERED_REMOVALS).at(-1).rev;
+    }
+    #entryOf(held) {
+        if (!held.entry) {
+            const id = held.evidence.id;
+            const rows = [...held.wins].map(key => this.#winners.get(key).row);
+            held.entry = { id, layer: { ...held.evidence.layer, backend: this.#attribution.get(id) ?? held.evidence.layer.backend }, rows, fingerprints: held.evidence.fingerprints };
+        }
+        return held.entry;
+    }
+    /** The current report, ready to send. Built once per change, and only the layers that changed are rebuilt. */
+    snapshot() {
+        return this.#current().value;
+    }
+    #current() {
+        const backends = this.#backends.map(backend => ({ id: backend.id, label: backend.label ?? backend.id, live: false, available: this.#available.get(backend.id) ?? false })).sort((a, b) => (a.id < b.id ? -1 : 1));
+        const notices = [...new Set([...this.#failed.values()].map(failure => failure.message))].sort();
+        const key = [this.#rev, this.#folded.size, backends.map(item => (item.available ? 1 : 0)).join(''), notices.join('\n')].join('|');
+        if (this.#cached?.key === key)
+            return this.#cached;
+        const held = [...this.#held.values()];
+        held.sort((a, b) => b.evidence.layer.recordedAtMs - a.evidence.layer.recordedAtMs || (a.evidence.id < b.evidence.id ? -1 : a.evidence.id > b.evidence.id ? 1 : 0));
+        const layers = held.map(item => this.#entryOf(item));
+        // A layer's rows are fixed by its id and which of its slots it holds, so a digest of those says when the report differs.
+        const hash = createHash('sha256');
+        for (const item of held) {
+            item.digest ??= `${item.evidence.id}|${this.#attribution.get(item.evidence.id) ?? ''}|${[...item.wins].join('\u0001')}`;
+            hash.update(item.digest).update('\n');
+        }
+        hash.update(JSON.stringify([backends, notices, this.#attribution.size]));
+        const version = hash.digest('hex').slice(0, 20);
+        if (!this.#versions.has(version)) {
+            this.#versions.set(version, this.#rev);
+            if (this.#versions.size > REMEMBERED_VERSIONS)
+                this.#versions.delete(this.#versions.keys().next().value);
+        }
+        this.#cached = { key, value: { version, layers, backends, notices, totalLayers: this.#attribution.size }, json: null, held };
+        return this.#cached;
+    }
+    /**
+     * The report as JSON text: exactly what `JSON.stringify({ ...snapshot(), active: [] })` writes, put together from
+     * the text of each layer, which is written once. `active` is what a store without live runs always sends: none.
+     */
+    json() {
+        const current = this.#current();
+        if (current.json === null) {
+            const { value, held } = current;
+            current.json = `{"version":${JSON.stringify(value.version)},"layers":[${held.map(item => (item.json ??= JSON.stringify(this.#entryOf(item)))).join(',')}],"backends":${JSON.stringify(value.backends)},"notices":${JSON.stringify(value.notices)},"totalLayers":${value.totalLayers},"active":[]}`;
+        }
+        return { version: current.value.version, text: current.json };
+    }
+    /**
+     * What differs between the report a viewer holds (named by its version) and the current one: the layers that
+     * changed in full, and the ids of those that no longer hold a winner. Null when that version is not remembered,
+     * and the viewer should ask for the whole report. See `applyEffectiveDelta`.
+     */
+    delta(since) {
+        const current = this.#current();
+        const base = this.#versions.get(since);
+        if (base === undefined || base < this.#forgotten)
+            return null;
+        const changed = current.held.filter(item => item.rev > base);
+        const gone = [...new Set(this.#removed.filter(item => item.rev > base && !this.#held.has(item.id)).map(item => item.id))];
+        const { value } = current;
+        return {
+            version: value.version,
+            text: `{"version":${JSON.stringify(value.version)},"base":${JSON.stringify(since)},"delta":true,"layers":[${changed.map(item => (item.json ??= JSON.stringify(this.#entryOf(item)))).join(',')}],"removed":${JSON.stringify(gone)},"backends":${JSON.stringify(value.backends)},"notices":${JSON.stringify(value.notices)},"totalLayers":${value.totalLayers},"active":[]}`
+        };
+    }
+    /** For `/readyz` and logs. */
+    stats() {
+        return { backends: this.#backends.length, layers: this.#attribution.size, slots: this.#winners.size, holding: this.#held.size, failed: this.#failed.size, refreshedAt: this.#refreshedAt };
+    }
+}

package/dist/reports/src/report-loader.d.ts

@@ -1,3 +1,10 @@
+/**
+ * @module Test loading state
+ *
+ * The state of loading one recorded test into the viewer, and the interface a report gives the viewer to load tests on
+ * demand. Types only.
+ */
+/** Where loading a test is: `ready`, `loading` (with how many frame files have arrived and how many there are, when known), `missing`, or `error` with a message to show. */
 export type TestLoad = {
     readonly kind: 'ready';
 } | {
@@ -16,7 +23,10 @@ export type TestLoad = {
  * (a standalone HTML file).
  */
 export type ReportTestLoader = {
+    /** Starts loading a test's timeline if it has not started (or failed before). Returns at once. */
     readonly load: (testId: string) => void;
+    /** Starts fetching one frame file of a test if it is not held or already being fetched. */
     readonly ensureBlob?: (testId: string, file: string) => void;
+    /** The current load state of a test; reactive where the host is. */
     readonly state: (testId: string) => TestLoad;
 };

package/dist/reports/src/report-loader.js

@@ -0,0 +1,6 @@
+/**
+ * @module Test loading state
+ *
+ * The state of loading one recorded test into the viewer, and the interface a report gives the viewer to load tests on
+ * demand. Types only.
+ */

package/dist/reports/src/report-parts.d.ts

@@ -1,10 +1,36 @@
 import type { ObjectStore } from './object-store.js';
 import type { EvidenceStatus, ReportPart } from './explorer-types.js';
+/** The status of a whole part: `failed` if any check failed, else `running` if any is running, else `not-run` if it has no checks or any is `not-run`, else `passed`. */
 export declare function partStatus(part: ReportPart): EvidenceStatus;
+/**
+ * Throws unless `part` is well formed: a 40-hex `sha`, an `id` usable as a key segment, a non-empty `kind` and
+ * `title`, a non-negative safe-integer `recordedAtMs`, string `parameters` values, and checks with a unique non-empty
+ * `id`, non-empty `title`, a string `detail`, one of the four statuses and finite-number measurements with a name and
+ * unit. The error is `Invalid report part`, `Invalid report parameters`, `Invalid evidence check` or `Invalid evidence
+ * measurement`; it does not say which field.
+ */
 export declare function validatePart(part: ReportPart): void;
-/** Each producer owns a separate key, independent of the spec-run attempt. */
+/**
+ * Stores a part and publishes it as a layer. Validates first (`validatePart`, which throws and writes nothing).
+ *
+ * Each producer owns a separate key, `commits/<sha>/parts/<id>/<recordedAtMs>-<sha256 of the JSON>.json`, independent
+ * of the spec-run attempt, so republishing identical content rewrites the same key. It then records the commit as an
+ * explorer version and publishes a layer (producer `part.id`, environment from the `environment` parameter, the
+ * commit's branch and run URL when a commit record exists, the commit's spec inventory) with no captured files.
+ */
 export declare function publishPart(store: ObjectStore, part: ReportPart): Promise<void>;
-/** Latest result per producer, sorted stably; corrupt evidence fails visibly. */
+/**
+ * Reads the latest part of every producer for a commit (see `latestParts`), sorted by kind then id.
+ *
+ * Throws `Invalid commit` for a sha that is not 40 hex, a validation error (see `validatePart`) or a `SyntaxError` for
+ * a part that is corrupt, `Report part disappeared` when a listed part vanishes, and `Report part belongs to another
+ * commit` when a part's `sha` or `id` does not match its key. Corrupt evidence fails visibly; it is never skipped.
+ */
 export declare function readParts(store: ObjectStore, sha: string): Promise<readonly ReportPart[]>;
-/** Ties are conservative and independent of write/list order. */
+/**
+ * Keeps one part per producer id and sorts by kind then id. The newer `recordedAtMs` wins; at the same time the more
+ * severe status wins (`failed`, then `running`, then `not-run`, then `passed`); at the same status the greater JSON
+ * text wins, so the answer is independent of write and list order. This is not the layer winner rule: here a newer
+ * unfinished part replaces an older completed one.
+ */
 export declare function latestParts(parts: readonly ReportPart[]): readonly ReportPart[];

package/dist/reports/src/report-parts.js

@@ -1,3 +1,12 @@
+/**
+ * @module Report parts of a commit
+ *
+ * Reads, writes and validates "parts": one producer's checks for one commit, stored under
+ * `commits/<sha>/parts/<producer>/` in the older commit-keyed layout. Publishing a part also publishes it as an
+ * immutable layer, so it composes with everything else; reading parts picks the latest per producer for the explorer.
+ * A part that is corrupt or belongs to another commit fails visibly instead of being skipped.
+ */
+import { normalizeEnvironment } from './layer-axes.js';
 import { publishLayer } from './layer-store.js';
 import { readCommit } from './read.js';
 import { readInventory } from './spec-inventory.js';
@@ -6,6 +15,7 @@ import { inCompletionOrder } from './completion-order.js';
 import { recordExplorerVersion } from './explorer-versions.js';
 import { isCommitSha, isKeySegment } from './keys.js';
 const STATUSES = new Set(['passed', 'failed', 'running', 'not-run']);
+/** The status of a whole part: `failed` if any check failed, else `running` if any is running, else `not-run` if it has no checks or any is `not-run`, else `passed`. */
 export function partStatus(part) {
     const statuses = part.checks.map((check) => check.status);
     if (statuses.includes('failed'))
@@ -16,6 +26,13 @@ export function partStatus(part) {
         return 'not-run';
     return 'passed';
 }
+/**
+ * Throws unless `part` is well formed: a 40-hex `sha`, an `id` usable as a key segment, a non-empty `kind` and
+ * `title`, a non-negative safe-integer `recordedAtMs`, string `parameters` values, and checks with a unique non-empty
+ * `id`, non-empty `title`, a string `detail`, one of the four statuses and finite-number measurements with a name and
+ * unit. The error is `Invalid report part`, `Invalid report parameters`, `Invalid evidence check` or `Invalid evidence
+ * measurement`; it does not say which field.
+ */
 export function validatePart(part) {
     if (!isCommitSha(part.sha) ||
         !isKeySegment(part.id) ||
@@ -57,7 +74,14 @@ function partsPrefix(sha) {
         throw new Error('Invalid commit');
     return `commits/${sha}/parts/`;
 }
-/** Each producer owns a separate key, independent of the spec-run attempt. */
+/**
+ * Stores a part and publishes it as a layer. Validates first (`validatePart`, which throws and writes nothing).
+ *
+ * Each producer owns a separate key, `commits/<sha>/parts/<id>/<recordedAtMs>-<sha256 of the JSON>.json`, independent
+ * of the spec-run attempt, so republishing identical content rewrites the same key. It then records the commit as an
+ * explorer version and publishes a layer (producer `part.id`, environment from the `environment` parameter, the
+ * commit's branch and run URL when a commit record exists, the commit's spec inventory) with no captured files.
+ */
 export async function publishPart(store, part) {
     validatePart(part);
     const json = JSON.stringify(part);
@@ -68,12 +92,20 @@ export async function publishPart(store, part) {
     await writeUtf8(store, `${partsPrefix(part.sha)}${part.id}/${part.recordedAtMs}-${hash}.json`, json, 'application/json');
     await recordExplorerVersion(store, part.sha);
     const commit = await readCommit(store, part.sha);
+    const environment = normalizeEnvironment(part.parameters?.environment);
     await publishLayer(store, {
         ...(part.freshness ? { freshness: part.freshness } : {}), producer: part.id, recordedAtMs: part.recordedAtMs, sha: part.sha, branch: commit?.branch ?? null, runUrl: commit?.runUrl ?? null,
+        ...(environment ? { environment } : {}),
         parameters: part.parameters ?? {}, specs: (await readInventory(store, part.sha))?.entries ?? [], parts: [part], source: null, recording: null,
     }, (async function* () { })());
 }
-/** Latest result per producer, sorted stably; corrupt evidence fails visibly. */
+/**
+ * Reads the latest part of every producer for a commit (see `latestParts`), sorted by kind then id.
+ *
+ * Throws `Invalid commit` for a sha that is not 40 hex, a validation error (see `validatePart`) or a `SyntaxError` for
+ * a part that is corrupt, `Report part disappeared` when a listed part vanishes, and `Report part belongs to another
+ * commit` when a part's `sha` or `id` does not match its key. Corrupt evidence fails visibly; it is never skipped.
+ */
 export async function readParts(store, sha) {
     const keys = await store.listKeys(partsPrefix(sha));
     const parts = [];
@@ -91,7 +123,12 @@ export async function readParts(store, sha) {
         parts.push(part);
     return latestParts(parts);
 }
-/** Ties are conservative and independent of write/list order. */
+/**
+ * Keeps one part per producer id and sorts by kind then id. The newer `recordedAtMs` wins; at the same time the more
+ * severe status wins (`failed`, then `running`, then `not-run`, then `passed`); at the same status the greater JSON
+ * text wins, so the answer is independent of write and list order. This is not the layer winner rule: here a newer
+ * unfinished part replaces an older completed one.
+ */
 export function latestParts(parts) {
     const latest = new Map();
     const rank = { passed: 0, 'not-run': 1, running: 2, failed: 3 };

package/dist/reports/src/report-status.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @module The report gate
+ *
+ * Reduces a combined report to a pass or fail with reasons (`reportStatus`) and renders that result as text or
+ * markdown. The JSON of `ReportStatus` is a stable contract (`schemaVersion` 1); the text and markdown are for people
+ * and are not. The gate fails closed: no checks, a failed or still-running check, an unreadable layer or backend
+ * (a notice), a missing required environment, or (when asked) a spec with no result each make it fail.
+ *
+ * @see docs/report-contract.md#statuses-and-the-gate
+ */
+import { type ReportStatus } from '../../schema/src/layer.js';
+import { type CombinedReport } from './compose.js';
+/** Extra conditions for the gate beyond "all checks pass". */
+export type StatusOptions = {
+    /** Environments that must have at least one check, such as `ios,android`. A missing one fails the gate. */
+    readonly requireEnvironments?: readonly string[];
+    /** Fail when any spec of the outline has no result at all. */
+    readonly requireAllSpecs?: boolean;
+};
+/**
+ * The gate. A report passes only when it has checks, none failed, none is still running, every
+ * layer and backend could be read, and every required environment is present. Unknown never passes.
+ *
+ * Returns a `ReportStatus` (schemaVersion 1): `ok` is true exactly when `reasons` is empty. Reasons name, in order: no
+ * checks (or none completed), failed checks, running checks, specs without results (only with `requireAllSpecs`),
+ * each required environment with no checks (the name is normalised, so `iOS` means `ios`), then every notice of the
+ * report (an unreadable layer or backend). `failing` lists each failed or running winner, in a fixed order that does
+ * not depend on read order; diagnostic `performance` checks are left out unless nothing else was recorded.
+ *
+ * @example
+ * const status = reportStatus(await combineBackends(backends), { requireEnvironments: ['ios'] });
+ * if (!status.ok) throw new Error(status.reasons.join('\n'));
+ *
+ * @see docs/report-contract.md#atlas-report-status
+ */
+export declare function reportStatus(report: CombinedReport, options?: StatusOptions): ReportStatus;
+/**
+ * Renders a status as plain text for a terminal: a `PASS`/`FAIL` line with totals, one line per environment, each
+ * failing or running check with where it ran and the first line of its detail, notices, reasons and specs with no
+ * results. Ends with a newline. For people: the layout is not a contract; parse `--format json` instead.
+ */
+export declare function formatStatusText(status: ReportStatus): string;
+/**
+ * Renders a status as GitHub-flavoured markdown for a pull request comment or `$GITHUB_STEP_SUMMARY`: a heading with
+ * totals, a table per environment, a table of failing checks (`|` and newlines in cells are escaped) and the reasons.
+ * Ends with a newline. For people: the layout is not a contract.
+ */
+export declare function formatStatusMarkdown(status: ReportStatus): string;