@crvouga/atlas 0.4.0 → 0.5.0

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

@@ -1,8 +1,10 @@
 /**
- * A commit's report, streamed from a reports API into a Solid store the
- * viewer renders as it grows: the test list fills in source by source, and
- * a test's steps and frame files stream in the first time it is opened.
- * Transport and time are injected; nothing here touches a global.
+ * @module Remote commit report
+ *
+ * A commit's report, streamed from a reports API into a Solid store the viewer renders as it grows: the test list
+ * fills in source by source, and a test's steps and frame files stream in the first time it is opened. Transport and
+ * time are injected (`http`, `timers`, `fetcher`); nothing here touches a global. It reads only: it never writes to
+ * the API. It serves the older commit-keyed recordings (see `protocol.ts`), not layers.
  */
 import type { Timers } from './clock.js';
 import type { CommitRecord, SourceRecord } from './protocol.js';
@@ -11,29 +13,48 @@ import type { HttpClient } from './http.js';
 import { type Accessor } from 'solid-js';
 import type { ReportFetcher } from './fetcher.js';
 import type { ReportTestLoader } from './report-loader.js';
+/** What `createRemoteReport` needs: transport, timers, and which commit to open. */
 export type RemoteReportArgs = {
+    /** The HTTP client used for the event stream. */
     readonly http: HttpClient;
+    /** Timer functions for the reconnect wait. */
     readonly timers: Timers;
     /** The reports API root (`https://api.example.com/api/reports`). */
     readonly apiBase: string;
+    /** The full 40-hex commit sha to open. */
     readonly sha: string;
     /** Cached reads (sources, stylesheet, one test, one frame file). */
     readonly fetcher: ReportFetcher;
 };
+/** Where the commit stream is: `connecting` before the first event, `live` while tailing a running commit, `complete` or `missing` once it ended for good, `error` after a stream failed (it retries). */
 export type RemoteReportPhase = 'connecting' | 'live' | 'complete' | 'missing' | 'error';
+/** An open report: reactive data that grows as the stream delivers, and the handles to load more or stop. */
 export type RemoteReport = {
+    /** The tests of the commit as a Solid store; steps and frame files fill in when a test is loaded. */
     readonly data: ReportData;
+    /** The commit record, `null` until the stream sends it (or when none exists). */
     readonly commit: Accessor<CommitRecord | null>;
+    /** The stream's phase. */
     readonly phase: Accessor<RemoteReportPhase>;
+    /** The source records received so far. */
     readonly sources: Accessor<readonly SourceRecord[]>;
+    /** The stylesheet snapshots render with: `undefined` until read, `''` when there is none. */
     readonly frameCss: Accessor<string | undefined>;
+    /** Loads one test's timeline and frame files on demand. */
     readonly loader: ReportTestLoader;
+    /** Stops the stream and any pending reconnect. Safe to call more than once. */
     readonly dispose: () => void;
 };
-/** Read an SSE response body, handing each message to `onEvent`. */
+/**
+ * Reads a Server-Sent Events response body to its end, handing each message's parsed `data` to `onEvent` in order.
+ * Throws `reports API answered <status>` when the response is not ok or has no body; rejects when the stream breaks
+ * or a message is not JSON.
+ */
 export declare function readEventStream<T>(response: Response, onEvent: (event: T) => void): Promise<void>;
 /**
- * Open a commit's report. The commit stream reconnects on its own (sending
- * the sources it already holds) until the commit is complete or missing.
+ * Opens a commit's report and starts streaming it. The commit stream reconnects on its own (sending the sources it
+ * already holds as `?have=`; after a failure it waits 3 seconds first) until the commit is complete or missing, or
+ * `dispose` is called. Sources and the stylesheet are also read from the query cache so a revisit paints at once.
+ * Call this inside a Solid root: it creates signals and a store.
  */
 export declare function createRemoteReport(args: RemoteReportArgs): RemoteReport;

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

@@ -1,8 +1,10 @@
 /**
- * A commit's report, streamed from a reports API into a Solid store the
- * viewer renders as it grows: the test list fills in source by source, and
- * a test's steps and frame files stream in the first time it is opened.
- * Transport and time are injected; nothing here touches a global.
+ * @module Remote commit report
+ *
+ * A commit's report, streamed from a reports API into a Solid store the viewer renders as it grows: the test list
+ * fills in source by source, and a test's steps and frame files stream in the first time it is opened. Transport and
+ * time are injected (`http`, `timers`, `fetcher`); nothing here touches a global. It reads only: it never writes to
+ * the API. It serves the older commit-keyed recordings (see `protocol.ts`), not layers.
  */
 import { splitViewerTestId, viewerTestId, } from './keys.js';
 import { SseDecoder } from './protocol.js';
@@ -10,7 +12,11 @@ import { batch, createSignal } from 'solid-js';
 import { createStore, produce } from 'solid-js/store';
 /** Wait before reconnecting a stream that failed. */
 const RETRY_MS = 3_000;
-/** Read an SSE response body, handing each message to `onEvent`. */
+/**
+ * Reads a Server-Sent Events response body to its end, handing each message's parsed `data` to `onEvent` in order.
+ * Throws `reports API answered <status>` when the response is not ok or has no body; rejects when the stream breaks
+ * or a message is not JSON.
+ */
 export async function readEventStream(response, onEvent) {
     if (!response.ok || response.body === null) {
         throw new Error(`reports API answered ${String(response.status)}`);
@@ -253,8 +259,10 @@ async function loadCached(ctx) {
     }
 }
 /**
- * Open a commit's report. The commit stream reconnects on its own (sending
- * the sources it already holds) until the commit is complete or missing.
+ * Opens a commit's report and starts streaming it. The commit stream reconnects on its own (sending the sources it
+ * already holds as `?have=`; after a failure it waits 3 seconds first) until the commit is complete or missing, or
+ * `dispose` is called. Sources and the stylesheet are also read from the query cache so a revisit paints at once.
+ * Call this inside a Solid root: it creates signals and a store.
  */
 export function createRemoteReport(args) {
     const [store, setStore] = createStore({

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

@@ -0,0 +1,51 @@
+/**
+ * @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
+ */
+/** 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 declare const REPORT_USAGE = "atlas report \u2014 layered evidence for any kind of spec\n\n  atlas report publish [--store <dir|s3://bucket/prefix>] [--producer <name>]\n                       ( --ctrf <file> | --junit <file> | --manifest <file> | --checks <file.json> )\n                       [--environment <name>] [--branch <b>] [--sha <s>] [--run-url <u>]\n                       [--spec <path> | --specs <dir>] [--upload-run]\n                       [--param key=value]... [--kind <k>] [--title <t>] [--recorded-at <iso|ms>]\n                       [--attach [role=]<file>]... [--label key=value]... [--link [name=]<url>]...\n                       [--attach-root <dir>]... [--max-attachment-mb <n>] [--max-total-attachment-mb <n>]\n  atlas report stream  [--store <dir|s3://\u2026|https://atlas.example.com>] --producer <name> [--environment <name>]\n                       [--branch <b>] [--sha <s>] [--run-url <u>] [--kind <k>] [--param key=value]...\n                       [--flush-ms 1000] [--batch 100]       (checks as JSON lines on standard input)\n  atlas report status  [--store <dir|s3://\u2026|id=url>]... [--backends <module>]\n                       [--specs <dir>] [--format text|json|markdown]\n                       [--require-environments a,b] [--require-all-specs]\n                       [--branch <name>]... [--ignore-modified]\n  atlas report merge   [--store \u2026]... [--backends <module>] --into <dir|s3://\u2026>\n  atlas report doctor  [--store \u2026]... [--role publisher|reader|both]\n  atlas report policy  --store s3://bucket/prefix [--role publisher|reader|both]\n\n  A store is a directory or s3://bucket/prefix (add ?region=\u2026&endpoint=\u2026 for R2, MinIO and the\n  rest). When no --store is given, ATLAS_STORE is used. Keys never go in the URL: set\n  AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or sign in with `aws sso login`, or use a role.\n\n  publish   Write one immutable layer: the checks of one producer, on one environment. Safe to repeat.\n            --producer is required, unless the --checks file names one\n            --spec <path>   every check in the report belongs to this spec (a report per feature file)\n            --specs <dir>   link checks to the spec files in <dir> by path, or by the suite, class or\n                            file name the report gives; also publishes the specs themselves, so the\n                            node can show them without a checkout\n            --upload-run    with --manifest: also upload the run's screenshots and clips for the viewer\n            --attach <file>   attach a file to the whole layer: a CI log, a coverage report, a trace archive\n                              (screenshots, videos and traces of a single test go in its CTRF or checks file)\n            --label k=v       a fact about the run, not part of what it checks: build, os, browser\n            --link [n=]<url>  a link to the run, a dashboard, an issue\n            Files a report names (CTRF attachments, JUnit [[ATTACHMENT|path]] lines) come from the report's own\n            folder and each --attach-root, and never from a hidden file or a link out: a report is data from a\n            test run, not instructions. One that is missing or not allowed is skipped with a warning.\n            From a checkout with uncommitted changes the layer is marked \"modified\".\n  stream    Send checks as they finish: one JSON object per line on standard input (the fields of one\n            check: id, title, status, and any evidence). Each second's worth becomes one layer, so a server\n            shows the run while it is still going. A check sent again with the same id (running, then\n            passed) is replaced by the later. Ends when the input does; exit 1 if anything could not be sent.\n            Point it at an Atlas server with --store https://\u2026 and a token in ATLAS_TOKEN.\n  status    Combine every layer of every store, and exit 1 unless the report passes.\n            --specs <dir>          lay the results over these spec files (default: the specs in the store)\n            --require-all-specs    fail while any spec has no results\n            --branch <name>        only layers recorded on this branch (repeatable)\n            --ignore-modified      leave out layers from modified checkouts and unknown origins\n  merge     Copy the layers of several stores into one.\n  doctor    Check that a store works: credentials, listing, writing, and what it holds.\n  policy    Print the least-privilege IAM policy for publishers, readers, or both.\n\n  --backends <module>  A TypeScript or JavaScript module whose default export is a list of\n                       { id, label?, store } (or a function returning it): a device lab, anything\n                       that implements ObjectStore.\n\n  --format json (alias --json)   publish, stream, merge, doctor and status print one JSON document instead of prose\n                       (schemas: publish-result, stream-result, merge-result, doctor-result, report-status). A command\n                       that is wrong is {\"ok\":false,\"error\":{\"message\":\u2026,\"code\":\"usage\"}} on standard error.\n  A store may be an Atlas server (https://\u2026): ATLAS_STORE=https://atlas.example.com, with ATLAS_TOKEN.\n\n  Exit codes: 0 ok, 1 the report does not pass (or a check failed), 2 the command was wrong.\n";
+type Env = Readonly<Record<string, string | undefined>>;
+type Git = (args: readonly string[]) => string | null;
+/** What `reportMain` is given besides arguments: where output goes (`out`), and, for tests and embedding, the environment, working directory, git, clock and standard input (`stdin`, where `stream` reads checks from). Defaults are the real ones. */
+export type ReportIo = {
+    readonly out: (text: string) => void; /** Where `stream` reads checks from. Default: standard input. */
+    readonly stdin?: AsyncIterable<string | Uint8Array>;
+    readonly env?: Env;
+    readonly cwd?: string;
+    readonly git?: Git;
+    readonly clock?: () => number;
+};
+/** Where the checks ran, from the CI's own variables and then git. Explicit flags win over both. */
+export declare function detectOrigin(env: Env, git?: Git): {
+    sha: string | null;
+    branch: string | null;
+    runUrl: string | null;
+    ci: boolean;
+};
+/**
+ * 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 declare function detectFreshness(origin: {
+    sha: string | null;
+    ci: boolean;
+}, git?: Git): 'modified' | 'unknown' | undefined;
+/**
+ * `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 declare function runReportCommand(argv: readonly string[]): Promise<number>;
+/** `atlas report …`. Returns the exit code: 0 passes, 1 does not. Throws on a mistake in the command (see {@link runReportCommand}). */
+export declare function reportMain(argv: readonly string[], io?: ReportIo): Promise<number>;
+export {};