@crvouga/atlas 0.4.0 → 0.5.0

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

@@ -0,0 +1,485 @@
+/**
+ * @module The `atlas report` command
+ *
+ * `reportMain` is `atlas report publish | stream | status | merge | doctor | policy`, written so it can be called from code and
+ * tests as well as a terminal: it takes its arguments, environment, working directory, clock, git and standard input as
+ * parameters and returns the exit code. Every command can print a JSON document (`--format json`) instead of prose, and a
+ * command that is wrong throws, which `runReportCommand` turns into a message (or a JSON error) and exit code 2.
+ *
+ * Exit codes: 0 it worked, 1 it ran and the answer is no (a report that does not pass, a store that needs attention, checks
+ * that could not be sent), 2 the command itself was wrong.
+ *
+ * @see docs/integrating.md
+ * @see docs/agents.md
+ */
+import { spawnSync } from 'node:child_process';
+import { readFileSync, statSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { PublishChecksSchema, ReportStatusSchema } from '../../schema/src/layer.js';
+import { readAttachmentFiles } from './attachment-files.js';
+import { backendsOf, layerFilter, value, values, writeStoreOf } from './cli-stores.js';
+import { combineBackends } from './compose.js';
+import { copyStore } from './copy-store.js';
+import { loadDirectoryOutline } from './directory-outline.js';
+import { iamPolicy, inspectStore } from './doctor.js';
+import { checksFromCtrf, checksFromJunit, checksFromManifest } from './ingest.js';
+import { parseWith } from './parse-with.js';
+import { publishChecks } from './publish-checks.js';
+import { createReporter } from './reporter.js';
+import { formatStatusMarkdown, formatStatusText, reportStatus } from './report-status.js';
+import { publishRunBundle } from './run-bundle.js';
+import { collectSpecFiles, latestSpecSet, publishSpecSet } from './spec-set.js';
+import { linkChecksToSpecs } from './spec-link.js';
+import { openStore, storeSpecs } from './store-url.js';
+/** The text `atlas report --help` prints: every subcommand, its flags, what each does and the exit codes. Also the source of the command reference in `docs/reference/cli.md`. */
+export const REPORT_USAGE = `atlas report — layered evidence for any kind of spec
+
+  atlas report publish [--store <dir|s3://bucket/prefix>] [--producer <name>]
+                       ( --ctrf <file> | --junit <file> | --manifest <file> | --checks <file.json> )
+                       [--environment <name>] [--branch <b>] [--sha <s>] [--run-url <u>]
+                       [--spec <path> | --specs <dir>] [--upload-run]
+                       [--param key=value]... [--kind <k>] [--title <t>] [--recorded-at <iso|ms>]
+                       [--attach [role=]<file>]... [--label key=value]... [--link [name=]<url>]...
+                       [--attach-root <dir>]... [--max-attachment-mb <n>] [--max-total-attachment-mb <n>]
+  atlas report stream  [--store <dir|s3://…|https://atlas.example.com>] --producer <name> [--environment <name>]
+                       [--branch <b>] [--sha <s>] [--run-url <u>] [--kind <k>] [--param key=value]...
+                       [--flush-ms 1000] [--batch 100]       (checks as JSON lines on standard input)
+  atlas report status  [--store <dir|s3://…|id=url>]... [--backends <module>]
+                       [--specs <dir>] [--format text|json|markdown]
+                       [--require-environments a,b] [--require-all-specs]
+                       [--branch <name>]... [--ignore-modified]
+  atlas report merge   [--store …]... [--backends <module>] --into <dir|s3://…>
+  atlas report doctor  [--store …]... [--role publisher|reader|both]
+  atlas report policy  --store s3://bucket/prefix [--role publisher|reader|both]
+
+  A store is a directory or s3://bucket/prefix (add ?region=…&endpoint=… for R2, MinIO and the
+  rest). When no --store is given, ATLAS_STORE is used. Keys never go in the URL: set
+  AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or sign in with \`aws sso login\`, or use a role.
+
+  publish   Write one immutable layer: the checks of one producer, on one environment. Safe to repeat.
+            --producer is required, unless the --checks file names one
+            --spec <path>   every check in the report belongs to this spec (a report per feature file)
+            --specs <dir>   link checks to the spec files in <dir> by path, or by the suite, class or
+                            file name the report gives; also publishes the specs themselves, so the
+                            node can show them without a checkout
+            --upload-run    with --manifest: also upload the run's screenshots and clips for the viewer
+            --attach <file>   attach a file to the whole layer: a CI log, a coverage report, a trace archive
+                              (screenshots, videos and traces of a single test go in its CTRF or checks file)
+            --label k=v       a fact about the run, not part of what it checks: build, os, browser
+            --link [n=]<url>  a link to the run, a dashboard, an issue
+            Files a report names (CTRF attachments, JUnit [[ATTACHMENT|path]] lines) come from the report's own
+            folder and each --attach-root, and never from a hidden file or a link out: a report is data from a
+            test run, not instructions. One that is missing or not allowed is skipped with a warning.
+            From a checkout with uncommitted changes the layer is marked "modified".
+  stream    Send checks as they finish: one JSON object per line on standard input (the fields of one
+            check: id, title, status, and any evidence). Each second's worth becomes one layer, so a server
+            shows the run while it is still going. A check sent again with the same id (running, then
+            passed) is replaced by the later. Ends when the input does; exit 1 if anything could not be sent.
+            Point it at an Atlas server with --store https://… and a token in ATLAS_TOKEN.
+  status    Combine every layer of every store, and exit 1 unless the report passes.
+            --specs <dir>          lay the results over these spec files (default: the specs in the store)
+            --require-all-specs    fail while any spec has no results
+            --branch <name>        only layers recorded on this branch (repeatable)
+            --ignore-modified      leave out layers from modified checkouts and unknown origins
+  merge     Copy the layers of several stores into one.
+  doctor    Check that a store works: credentials, listing, writing, and what it holds.
+  policy    Print the least-privilege IAM policy for publishers, readers, or both.
+
+  --backends <module>  A TypeScript or JavaScript module whose default export is a list of
+                       { id, label?, store } (or a function returning it): a device lab, anything
+                       that implements ObjectStore.
+
+  --format json (alias --json)   publish, stream, merge, doctor and status print one JSON document instead of prose
+                       (schemas: publish-result, stream-result, merge-result, doctor-result, report-status). A command
+                       that is wrong is {"ok":false,"error":{"message":…,"code":"usage"}} on standard error.
+  A store may be an Atlas server (https://…): ATLAS_STORE=https://atlas.example.com, with ATLAS_TOKEN.
+
+  Exit codes: 0 ok, 1 the report does not pass (or a check failed), 2 the command was wrong.
+`;
+function gitOutput(args) {
+    const result = spawnSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    return result.status === 0 ? result.stdout.trim() || null : null;
+}
+/** Where the checks ran, from the CI's own variables and then git. Explicit flags win over both. */
+export function detectOrigin(env, git = gitOutput) {
+    const first = (...names) => names.map(name => env[name]).find(value => value) ?? null;
+    const runUrl = env.GITHUB_RUN_ID && env.GITHUB_REPOSITORY ? `${env.GITHUB_SERVER_URL ?? 'https://github.com'}/${env.GITHUB_REPOSITORY}/actions/runs/${env.GITHUB_RUN_ID}` : first('CI_PIPELINE_URL', 'BUILDKITE_BUILD_URL', 'CIRCLE_BUILD_URL');
+    const fromCi = first('GITHUB_SHA', 'CI_COMMIT_SHA', 'BUILDKITE_COMMIT', 'CIRCLE_SHA1');
+    return {
+        sha: fromCi ?? git(['rev-parse', 'HEAD']),
+        branch: first('GITHUB_HEAD_REF', 'GITHUB_REF_NAME', 'CI_COMMIT_REF_NAME', 'BUILDKITE_BRANCH', 'CIRCLE_BRANCH') ?? git(['branch', '--show-current']),
+        runUrl,
+        ci: fromCi !== null
+    };
+}
+/**
+ * Whether the checks ran on exactly the commit they name. A CI checkout does. A developer's worktree
+ * with edits to tracked files does not: its layer is `modified`, shown with a warning and never mistaken
+ * for the commit's own result. Outside git the origin is `unknown`.
+ */
+export function detectFreshness(origin, git = gitOutput) {
+    if (origin.ci)
+        return undefined;
+    if (!origin.sha)
+        return 'unknown';
+    // `git diff` is empty (so null) when clean; untracked files (test output, build products) do not count.
+    return git(['status', '--porcelain', '--untracked-files=no']) ? 'modified' : undefined;
+}
+function keyValue(pair, flag) {
+    const at = pair.indexOf('=');
+    if (at < 1)
+        throw new Error(`${flag} takes key=value (got "${pair}")`);
+    return [pair.slice(0, at), pair.slice(at + 1)];
+}
+/** `--attach <file>`, or `--attach <role>=<file>` when the part before the `=` is not itself a file. */
+function attachmentSpec(spec, base) {
+    const role = /^([a-z][a-z0-9._-]*)=(.+)$/.exec(spec);
+    const exists = (file) => { try {
+        return statSync(path.resolve(base, file)).isFile();
+    }
+    catch {
+        return false;
+    } };
+    if (role && !exists(spec))
+        return { name: path.basename(role[2]), role: role[1], path: role[2] };
+    return { name: path.basename(spec), path: spec };
+}
+/** `--link <url>` or `--link <name>=<url>`. */
+function linkSpec(spec) {
+    const named = /^([^=/:]+)=(.+)$/.exec(spec);
+    return named ? { name: named[1], url: named[2] } : { url: spec };
+}
+function parseTime(text) {
+    if (text === undefined)
+        return null;
+    const numeric = Number(text);
+    const parsed = Number.isFinite(numeric) ? numeric : Date.parse(text);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        throw new Error(`--recorded-at takes an ISO date or epoch milliseconds (got "${text}")`);
+    return parsed;
+}
+function ingest(argv, base) {
+    const read = (file) => readFileSync(path.resolve(base, file), 'utf8');
+    const sources = ['ctrf', 'junit', 'manifest', 'checks'].filter(name => value(argv, name) !== undefined);
+    if (sources.length !== 1)
+        throw new Error('Give exactly one of --ctrf, --junit, --manifest or --checks');
+    const [source] = sources;
+    const file = value(argv, source);
+    // When the report does not say when it ran, the file does: the same file is the same time.
+    const modifiedAtMs = Math.floor(statSync(path.resolve(base, file)).mtimeMs);
+    const sourceDir = path.dirname(path.resolve(base, file));
+    if (source === 'junit')
+        return { ingested: checksFromJunit(read(file)), extra: {}, modifiedAtMs, sourceDir };
+    const json = JSON.parse(read(file));
+    if (source === 'ctrf')
+        return { ingested: checksFromCtrf(json), extra: {}, modifiedAtMs, sourceDir };
+    if (source === 'manifest')
+        return { ingested: checksFromManifest(json), extra: {}, modifiedAtMs, manifestFile: path.resolve(base, file), sourceDir };
+    const given = parseWith(PublishChecksSchema.partial({ producer: true, recordedAtMs: true }), json, file);
+    return { ingested: { checks: given.checks, recordedAtMs: given.recordedAtMs ?? null, tool: null }, extra: given, modifiedAtMs, sourceDir };
+}
+/**
+ * `atlas report …` for a terminal: a mistake in the command or a path is a message on stderr and exit
+ * code 2, so a CI job can tell a broken invocation (2) from a report that does not pass (1).
+ */
+export async function runReportCommand(argv) {
+    try {
+        return await reportMain(argv);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        // With --format json the mistake is a document too, so a caller never has to read prose.
+        process.stderr.write(wantsJson(argv) ? `${JSON.stringify({ ok: false, error: { message, code: 'usage' } })}\n` : `atlas report: ${message}\n`);
+        return 2;
+    }
+}
+/** Does the command ask for a JSON document (`--format json` or `--json`) instead of prose? */
+function wantsJson(argv) {
+    return value(argv, 'format') === 'json' || argv.includes('--json');
+}
+function printChecks(out, label, checks) {
+    out(`${label}\n`);
+    for (const check of checks) {
+        out(`  ${check.ok ? '✓' : '✗'} ${check.name.padEnd(9)} ${check.detail}\n`);
+        if (!check.ok && check.fix)
+            out(`      → ${check.fix}\n`);
+    }
+    return checks.every(check => check.ok);
+}
+/** `atlas report …`. Returns the exit code: 0 passes, 1 does not. Throws on a mistake in the command (see {@link runReportCommand}). */
+export async function reportMain(argv, io = { out: text => process.stdout.write(text) }) {
+    const [command, ...rest] = argv;
+    const base = io.cwd ?? process.cwd();
+    const env = io.env ?? process.env;
+    const clock = io.clock ?? Date.now;
+    if (command === 'publish') {
+        const target = writeStoreOf(value(rest, 'store'), base, env);
+        const { ingested, extra, modifiedAtMs, manifestFile, sourceDir } = ingest(rest, base);
+        // Checked before anything is written: a command that is wrong must not leave the store changed.
+        if (rest.includes('--upload-run') && !manifestFile)
+            throw new Error('--upload-run goes with --manifest <run>/manifest.json');
+        const origin = detectOrigin(env, io.git);
+        const producer = value(rest, 'producer') ?? extra.producer;
+        if (!producer)
+            throw new Error('publish needs --producer <name>: a stable name for this suite, such as "web-e2e" or "gherkin"');
+        const recordedAtMs = parseTime(value(rest, 'recorded-at')) ?? extra.recordedAtMs ?? ingested.recordedAtMs ?? modifiedAtMs;
+        const parameters = Object.fromEntries(values(rest, 'param').map(pair => keyValue(pair, '--param')));
+        const specsDirectory = value(rest, 'specs');
+        const linked = await linkChecksToSpecs(ingested, { base, ...(specsDirectory ? { specsDirectory } : {}), ...(value(rest, 'spec') ? { spec: value(rest, 'spec') } : {}) });
+        const given = extra.specs ?? [];
+        const sha = value(rest, 'sha') ?? extra.sha ?? origin.sha;
+        const branch = value(rest, 'branch') ?? extra.branch ?? origin.branch;
+        const freshness = extra.freshness ?? detectFreshness({ sha, ci: origin.ci && !value(rest, 'sha') }, io.git);
+        // Evidence: the files checks name, the files given with --attach, the labels and links given as flags.
+        // What a report names is data from a test run: only its own folder and the roots given may be attached from.
+        // What `--attach` names is what the person typed.
+        const roots = [sourceDir, ...values(rest, 'attach-root').map(root => path.resolve(base, root))];
+        const maxBytes = Number(value(rest, 'max-attachment-mb') ?? 512) * 1024 * 1024;
+        const budget = { remaining: Number(value(rest, 'max-total-attachment-mb') ?? 2048) * 1024 * 1024 };
+        const warnings = [];
+        let attachedFiles = 0, attachedBytes = 0;
+        const checksWithFiles = [];
+        for (const check of linked.checks) {
+            const read = await readAttachmentFiles(check, roots, { maxBytes, budget });
+            checksWithFiles.push(read.value);
+            attachedFiles += read.attached;
+            attachedBytes += read.bytes;
+            warnings.push(...read.warnings);
+        }
+        const fromFile = await readAttachmentFiles({ attachments: extra.attachments ?? [] }, roots, { maxBytes, budget });
+        const fromFlags = await readAttachmentFiles({ attachments: values(rest, 'attach').map(spec => attachmentSpec(spec, base)) }, [base, ...roots], { maxBytes, budget, trusted: true });
+        const layerAttachments = [...fromFile.value.attachments, ...fromFlags.value.attachments];
+        for (const read of [fromFile, fromFlags]) {
+            attachedFiles += read.attached;
+            attachedBytes += read.bytes;
+            warnings.push(...read.warnings);
+        }
+        const labels = { ...(ingested.labels ?? {}), ...(extra.labels ?? {}), ...Object.fromEntries(values(rest, 'label').map(pair => keyValue(pair, '--label'))) };
+        const links = [...(extra.links ?? []), ...values(rest, 'link').map(linkSpec)];
+        const layer = await publishChecks(target.store, {
+            ...extra,
+            producer,
+            checks: checksWithFiles,
+            // Always set, so a file that was skipped is not passed on by name.
+            attachments: layerAttachments,
+            ...(Object.keys(labels).length ? { labels } : {}),
+            ...(links.length ? { links: links } : {}),
+            specs: [...given, ...linked.specs.filter(entry => !given.some(other => other.path === entry.path))],
+            recordedAtMs,
+            kind: value(rest, 'kind') ?? extra.kind ?? 'checks',
+            ...(value(rest, 'title') ?? extra.title ? { title: (value(rest, 'title') ?? extra.title) } : {}),
+            sha, branch,
+            runUrl: value(rest, 'run-url') ?? extra.runUrl ?? origin.runUrl,
+            ...(freshness ? { freshness } : {}),
+            ...(value(rest, 'environment') ?? extra.environment ? { environment: (value(rest, 'environment') ?? extra.environment) } : {}),
+            parameters: { ...(extra.parameters ?? {}), ...parameters }
+        });
+        const counts = { passed: 0, failed: 0, other: 0 };
+        for (const check of ingested.checks)
+            counts[check.status === 'passed' ? 'passed' : check.status === 'failed' ? 'failed' : 'other'] += 1;
+        const linkedCount = linked.checks.filter(check => check.specPath).length;
+        const hint = linkedCount < linked.checks.length && !value(rest, 'spec') && !specsDirectory ? ' (pass --specs <dir> or --spec <path> to link checks to their specs)' : '';
+        const json = wantsJson(rest);
+        const result = {
+            ok: true, store: target.label,
+            layer: { id: layer.id, producer, environment: layer.environment ?? null, checks: ingested.checks.length, passed: counts.passed, failed: counts.failed, notRun: counts.other, linkedToSpec: linkedCount, ...(freshness ? { freshness } : {}), attachmentFiles: attachedFiles, attachmentBytes: attachedBytes },
+            warnings: warnings.map(warning => `attachment skipped: ${warning}`)
+        };
+        if (!json)
+            io.out(`Published layer ${layer.id.slice(0, 12)}: ${ingested.checks.length} checks (${counts.passed} passed, ${counts.failed} failed, ${counts.other} not run) as "${producer}"${layer.environment ? ` on ${layer.environment}` : ''}${freshness === 'modified' ? ' [from a modified checkout]' : ''}; ${linkedCount} of ${linked.checks.length} linked to a spec${hint}${attachedFiles ? `; ${attachedFiles} attachment file${attachedFiles === 1 ? '' : 's'} (${(attachedBytes / 1024 / 1024).toFixed(1)} MiB)` : ''}\n`);
+        if (!json)
+            for (const warning of warnings)
+                io.out(`! attachment skipped: ${warning}\n`);
+        if (specsDirectory) {
+            const files = await collectSpecFiles(path.resolve(base, specsDirectory));
+            // A spec named with --spec that the directory does not hold (or whose kind is not a spec file) is published too.
+            for (const entry of linked.specs) {
+                if (files.some(file => file.path === entry.path))
+                    continue;
+                const text = value(rest, 'spec') ? await readFile(path.resolve(base, value(rest, 'spec')), 'utf8').catch(() => null) : null;
+                if (text !== null)
+                    files.push({ path: entry.path, text });
+            }
+            // The commit's own time for a clean checkout, so publishing the same commit twice is one set.
+            const committed = !freshness && sha ? Number((io.git ?? gitOutput)(['show', '-s', '--format=%ct', sha])) * 1000 : NaN;
+            const set = await publishSpecSet(target.store, { files, branch, sha, recordedAtMs: Number.isFinite(committed) && committed > 0 ? committed : clock(), ...(freshness ? { freshness } : {}), domain: path.basename(base) || 'product' });
+            result.specSet = { id: set.id, files: set.files.length, branch };
+            if (!json)
+                io.out(`Published spec set ${set.id.slice(0, 12)}: ${set.files.length} specs${branch ? ` from ${branch}` : ''}\n`);
+        }
+        if (rest.includes('--upload-run')) {
+            const run = await publishRunBundle(target.store, path.dirname(manifestFile));
+            result.run = { id: run.id, files: run.files, bytes: run.bytes, alreadyPublished: run.alreadyPublished };
+            if (!json)
+                io.out(run.alreadyPublished ? `Run ${run.id} was already in the store\n` : `Uploaded run ${run.id}: ${run.files} files, ${(run.bytes / 1024 / 1024).toFixed(1)} MiB\n`);
+        }
+        if (json)
+            io.out(`${JSON.stringify(result, null, 2)}\n`);
+        return 0;
+    }
+    if (command === 'stream') {
+        const target = writeStoreOf(value(rest, 'store'), base, env);
+        const producer = value(rest, 'producer');
+        if (!producer)
+            throw new Error('stream needs --producer <name>: a stable name for this suite, such as "web-e2e"');
+        const origin = detectOrigin(env, io.git);
+        const sha = value(rest, 'sha') ?? origin.sha;
+        const branch = value(rest, 'branch') ?? origin.branch;
+        const freshness = detectFreshness({ sha, ci: origin.ci && !value(rest, 'sha') }, io.git);
+        const environment = value(rest, 'environment');
+        const warnings = [];
+        const reporter = createReporter({
+            producer,
+            kind: value(rest, 'kind') ?? 'checks',
+            ...(value(rest, 'title') ? { title: value(rest, 'title') } : {}),
+            sha, branch,
+            runUrl: value(rest, 'run-url') ?? origin.runUrl,
+            ...(freshness ? { freshness } : {}),
+            ...(environment ? { environment } : {}),
+            parameters: Object.fromEntries(values(rest, 'param').map(pair => keyValue(pair, '--param')))
+        }, {
+            store: target.store,
+            flushMs: Number(value(rest, 'flush-ms') ?? 1000),
+            batchSize: Number(value(rest, 'batch') ?? 100),
+            now: clock,
+            onError: (error, willRetry) => { const line = `could not send${willRetry ? ' (will try again)' : ''}: ${error.message}`; if (wantsJson(rest))
+                warnings.push(line);
+            else
+                io.out(`! ${line}\n`); }
+        });
+        let lines = 0;
+        let buffered = '';
+        const decoder = new TextDecoder();
+        const take = (line) => {
+            if (!line.trim())
+                return;
+            lines += 1;
+            try {
+                reporter.check(JSON.parse(line));
+            }
+            catch (error) {
+                warnings.push(`line ${lines} skipped: ${error instanceof Error ? error.message.split('\n')[0] : String(error)}`);
+            }
+        };
+        for await (const chunk of io.stdin ?? process.stdin) {
+            buffered += typeof chunk === 'string' ? chunk : decoder.decode(chunk, { stream: true });
+            let newline;
+            while ((newline = buffered.indexOf('\n')) >= 0) {
+                take(buffered.slice(0, newline));
+                buffered = buffered.slice(newline + 1);
+            }
+        }
+        take(buffered);
+        const result = await reporter.close();
+        if (wantsJson(rest)) {
+            io.out(`${JSON.stringify({ ok: result.lost === 0, producer, environment: environment ?? null, layers: result.layers, checks: result.checks, lost: result.lost, warnings }, null, 2)}\n`);
+            return result.lost ? 1 : 0;
+        }
+        for (const warning of warnings)
+            io.out(`! ${warning}\n`);
+        io.out(`Streamed ${result.checks} checks in ${result.layers} layer${result.layers === 1 ? '' : 's'} as "${producer}"${environment ? ` on ${environment}` : ''}${result.lost ? `; ${result.lost} could not be sent` : ''}\n`);
+        return result.lost ? 1 : 0;
+    }
+    if (command === 'status') {
+        const format = value(rest, 'format') ?? 'text';
+        if (!['text', 'json', 'markdown'].includes(format))
+            throw new Error(`--format takes text|json|markdown (got "${format}")`);
+        const backends = await backendsOf(rest, base, env);
+        const specsDirectory = value(rest, 'specs');
+        // One Atlas server, asked nothing it cannot answer itself: it already holds the layers, so it works out the gate
+        // and only the verdict travels, not every layer.
+        const server = backends.length === 1 && !specsDirectory && !value(rest, 'outline-branch') ? backends[0].server : undefined;
+        if (server) {
+            const query = new URLSearchParams();
+            for (const branch of values(rest, 'branch'))
+                query.append('branch', branch);
+            for (const branch of (env.ATLAS_ONLY_BRANCH ?? '').split(/[\s,]+/).filter(Boolean))
+                query.append('branch', branch);
+            if (rest.includes('--ignore-modified') || env.ATLAS_IGNORE_MODIFIED === '1' || env.ATLAS_IGNORE_MODIFIED === 'true')
+                query.set('ignoreModified', '1');
+            if (value(rest, 'require-environments'))
+                query.set('requireEnvironments', value(rest, 'require-environments'));
+            if (rest.includes('--require-all-specs'))
+                query.set('requireAllSpecs', '1');
+            const answer = ReportStatusSchema.safeParse(await server.status(query));
+            // A verdict this reader cannot read is unknown, never a pass.
+            if (!answer.success)
+                throw new Error(`${server.url} answered something that is not a report status. Upgrade @crvouga/atlas, or ask it with --format json to see it`);
+            const status = answer.data;
+            io.out(format === 'json' ? `${JSON.stringify(answer.data, null, 2)}\n` : format === 'markdown' ? formatStatusMarkdown(status) : formatStatusText(status));
+            return answer.data.ok ? 0 : 1;
+        }
+        let outline = specsDirectory ? await loadDirectoryOutline(path.resolve(base, specsDirectory), { repoRoot: base }) : undefined;
+        if (!outline) {
+            // No checkout to read the specs from: the newest set published to the store is the outline.
+            const found = await latestSpecSet(backends.map(backend => backend.store), value(rest, 'outline-branch')).catch(() => null);
+            if (found)
+                outline = { specs: found.set.files.map(({ path: file, domain, kind, title, fingerprint }) => ({ path: file, domain, kind, title, fingerprint })), sha: found.set.sha, changedFiles: [], readSpec: async () => null };
+        }
+        if (rest.includes('--require-all-specs') && !outline)
+            throw new Error('--require-all-specs needs to know which specs to expect: pass --specs <dir>, or publish with --specs so the store holds a spec set');
+        const include = layerFilter(rest, env);
+        const report = await combineBackends(backends, { ...(outline ? { outline } : {}), ...(include ? { include } : {}) });
+        const status = reportStatus(report, {
+            requireEnvironments: (value(rest, 'require-environments') ?? '').split(',').map(name => name.trim()).filter(Boolean),
+            requireAllSpecs: rest.includes('--require-all-specs')
+        });
+        io.out(format === 'json' ? `${JSON.stringify(status, null, 2)}\n` : format === 'markdown' ? formatStatusMarkdown(status) : formatStatusText(status));
+        return status.ok ? 0 : 1;
+    }
+    if (command === 'merge') {
+        const into = value(rest, 'into');
+        if (!into)
+            throw new Error('merge needs --into <dir or s3://bucket/prefix>');
+        const destination = writeStoreOf(into, base, env, 'into');
+        let copied = 0, skipped = 0, ignored = 0;
+        for (const backend of await backendsOf(rest, base, env)) {
+            const result = await copyStore(backend.store, destination.store);
+            copied += result.copied;
+            skipped += result.skipped;
+            ignored += result.ignored;
+        }
+        if (wantsJson(rest)) {
+            io.out(`${JSON.stringify({ ok: true, into, copied, skipped, ignored }, null, 2)}\n`);
+            return 0;
+        }
+        io.out(`Merged into ${into}: ${copied} objects copied, ${skipped} already there${ignored ? `; ${ignored} objects outside layers/ were not copied (only layers are merged)` : ''}\n`);
+        return 0;
+    }
+    if (command === 'doctor') {
+        const role = (value(rest, 'role') ?? 'both');
+        if (!['publisher', 'reader', 'both'].includes(role))
+            throw new Error(`--role takes publisher|reader|both (got "${role}")`);
+        let healthy = true;
+        const stores = [];
+        for (const backend of await backendsOf(rest, base, env)) {
+            const checks = await inspectStore(backend, { role });
+            stores.push({ id: backend.id, checks });
+            if (wantsJson(rest))
+                healthy = checks.every(check => check.ok) && healthy;
+            else
+                healthy = printChecks(io.out, backend.id, checks) && healthy;
+        }
+        if (wantsJson(rest))
+            io.out(`${JSON.stringify({ ok: healthy, stores }, null, 2)}\n`);
+        else
+            io.out(healthy ? 'All good.\n' : 'Something needs attention (see →).\n');
+        return healthy ? 0 : 1;
+    }
+    if (command === 'policy') {
+        const specs = storeSpecs(values(rest, 'store'), env);
+        const opened = specs.length === 1 ? openStore(specs[0], { base, env }) : null;
+        if (!opened || opened.location.kind !== 's3')
+            throw new Error('policy needs one --store s3://bucket/prefix (or ATLAS_STORE)');
+        const role = (value(rest, 'role') ?? 'both');
+        if (!['publisher', 'reader', 'both'].includes(role))
+            throw new Error(`--role takes publisher|reader|both (got "${role}")`);
+        io.out(`${JSON.stringify(iamPolicy(opened.location, role), null, 2)}\n`);
+        if (opened.location.endpoint)
+            io.out(`\n# ${opened.location.endpoint} is not AWS: this is the AWS form. Grant the same actions in its own policy language.\n`);
+        return 0;
+    }
+    io.out(REPORT_USAGE);
+    return command && command !== '--help' && command !== '-h' ? 2 : 0;
+}

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

@@ -0,0 +1,99 @@
+/**
+ * @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 type { BackendInfo, LayerEvidence, LayerHeader } from './evidence-types.js';
+import type { BackendInput } from './compose.js';
+import type { ReportLayer } from './layer-types.js';
+/** What a viewer needs to show the report, and nothing that is only history. */
+export type EffectiveEvidence = {
+    /** A hash of the report itself: the same on every replica, and different exactly when the report is. Use it as an ETag. */
+    readonly version: string;
+    /** Only layers that fill at least one slot, each with only the rows that win. */
+    readonly layers: readonly LayerEvidence[];
+    readonly backends: readonly BackendInfo[];
+    readonly notices: readonly string[];
+    /** Every layer read, superseded or not. */
+    readonly totalLayers: number;
+};
+/** What changed, told to those who asked to know: the report's new version, and the layers that arrived. */
+export type IndexChange = {
+    readonly version: string;
+    /** Layers read since the last change, newest first, whether or not they won anything. */
+    readonly added: readonly LayerHeader[];
+    readonly totalLayers: number;
+};
+/**
+ * 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 declare class ReportIndex {
+    #private;
+    constructor(backends: readonly BackendInput[], options?: {
+        readonly concurrency?: number;
+        readonly now?: () => number; /** Look at the whole catalog every this many refreshes; in between only its newest page. Default 30. */
+        readonly fullListEvery?: number; /** Leave layers out of the report, as a gate on `main` does. */
+        readonly include?: (layer: LayerHeader) => boolean;
+    });
+    /** Read what is new in every backend and fold it in. Resolves true when the report changed. Calls overlap safely. */
+    refresh(): Promise<boolean>;
+    /**
+     * 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.
+     */
+    refreshNow(): Promise<boolean>;
+    /**
+     * 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: string, indexKey: string, known?: ReportLayer): Promise<void>;
+    /** Be told when the report changes. Returns how to stop. */
+    onChange(listener: (change: IndexChange) => void): () => void;
+    /** Keep refreshing in the background. The first call returns once the first pass has finished. */
+    start(intervalMs: number): Promise<void>;
+    /** Stops the background refresh started by `start`. Safe to call twice. */
+    stop(): void;
+    /** True once a first pass over the backends has finished, so `snapshot` is a report and not an empty guess. */
+    get ready(): boolean;
+    /** The current report, ready to send. Built once per change, and only the layers that changed are rebuilt. */
+    snapshot(): EffectiveEvidence;
+    /**
+     * 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(): {
+        readonly version: string;
+        readonly text: string;
+    };
+    /**
+     * 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: string): {
+        readonly text: string;
+        readonly version: string;
+    } | null;
+    /** For `/readyz` and logs. */
+    stats(): {
+        backends: number;
+        layers: number;
+        slots: number;
+        holding: number;
+        failed: number;
+        refreshedAt: number;
+    };
+}