@crvouga/atlas 0.4.0 → 0.5.0

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

@@ -37,6 +37,7 @@ export type WebViewContext = SignalContext & {
         press(key: string, label?: string): Promise<void>;
     };
 };
+/** Options of `bunWebViewDriver`; every field is optional. */
 export type BunWebViewDriverOptions = {
     /** Where `goto` paths resolve; the implementation's setup decides where to open. */
     baseUrl?: string | (() => string | Promise<string>);
@@ -47,7 +48,10 @@ export type BunWebViewDriverOptions = {
     backend?: 'webkit' | 'chrome';
     /** How long a tap waits for its target to show, in milliseconds (default 10 000). */
     actionTimeoutMs?: number;
-    /** Showcase pacing, in milliseconds. */
+    /**
+     * Showcase pacing, in milliseconds: the hold before each event runs and after its state shows (default 400 and
+     * 900).
+     */
     pacing?: {
         before: number;
         after: number;
@@ -56,12 +60,42 @@ export type BunWebViewDriverOptions = {
     concurrency?: number;
 };
 /**
- * Drive a web app in Bun's built-in headless browser: the system WebKit on macOS (nothing to
- * install), Chrome over CDP elsewhere. A view starts in milliseconds and screenshots take about
- * ten, so it is the quickest way to run a chart against a real page. Clips are encoded from
- * screenshots with FFmpeg. Needs the Bun runtime; there is no fake clock, so time events use the
- * app's own controls.
+ * Drives a web app in Bun's built-in headless browser for `atlas run`: the system WebKit on macOS (nothing to
+ * install), Chrome over CDP elsewhere. A view starts in milliseconds and screenshots take about ten, so it is the
+ * quickest way to run a chart against a real page. Each path attempt gets its own view, closed afterwards. Screenshots
+ * are PNG files without a thumbnail. Clips are encoded from screenshots with FFmpeg (no clip is recorded without it).
+ * `user.tap` and `user.type` wait up to `actionTimeoutMs` for the target signal to show, then click its centre; a
+ * target that never shows fails the step with "<signal> is not on screen". Needs the Bun runtime (run
+ * `bun --bun atlas run`), and throws on open without it. There is no fake clock, so time events use the app's own
+ * controls.
+ *
+ * @see docs/statecharts.md
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from '@crvouga/atlas';
+ * import { bunWebViewDriver, screen, text } from '@crvouga/atlas/bun';
+ *
+ * export default defineConfig({
+ *   specs: './specs',
+ *   driver: () => bunWebViewDriver({ baseUrl: 'http://127.0.0.1:4317' }),
+ *   implementation: {
+ *     async setup(ctx) { await ctx.goto('/'); },
+ *     events: {
+ *       // one entry per event of the spec
+ *     },
+ *     states: { 'No todos': screen({ all: [text('Nothing to do yet')] }) }
+ *   }
+ * });
+ * ```
  */
 export declare function bunWebViewDriver(options?: BunWebViewDriverOptions): Driver<WebViewContext>;
-/** A state recognised from its signals in the page: every `all` visible and no `none` visible. */
+/**
+ * Builds a state implementation for a `WebViewContext` from its signals in the page: every `all` signal visible, one
+ * `any` signal visible (when given), no `none` signal visible. It is core's `signatureScreen` over `ctx.isVisible`, so
+ * it takes the same spec as `screen` from `@crvouga/atlas/signals` (`checks`, `transient`, `sameAs`, `lookIn`,
+ * `settle` included).
+ *
+ * @see docs/statecharts.md
+ */
 export declare const screen: (spec: import('../../core/src/signals.js').ScreenSpec<WebViewContext, Signal>) => import('../../core/src/index.js').StateImplementation<WebViewContext>;

package/dist/bun/src/driver.js

@@ -1,3 +1,14 @@
+/**
+ * @module Bun WebView driver
+ *
+ * `bunWebViewDriver()` is the core `Driver` that runs a statechart's paths in Bun's built-in headless browser
+ * (`Bun.WebView`), the quickest way to run a chart against a real page. It provides a `WebViewContext` whose
+ * `user.tap` and `user.type` act on `Signal`s, found by the shared in-page DOM probe from core, so an implementation
+ * written against `SignalContext` runs here and on the other web drivers unchanged. `Bun.WebView` is typed
+ * structurally (`BunWebView`), so this package builds without Bun's types; at run time the Bun runtime is required.
+ *
+ * @see docs/statecharts.md
+ */
 import { mkdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { recordFrames } from '../../core/src/index.js';
@@ -51,11 +62,34 @@ function contextFor(view, baseUrl, timeline, options) {
     return ctx;
 }
 /**
- * Drive a web app in Bun's built-in headless browser: the system WebKit on macOS (nothing to
- * install), Chrome over CDP elsewhere. A view starts in milliseconds and screenshots take about
- * ten, so it is the quickest way to run a chart against a real page. Clips are encoded from
- * screenshots with FFmpeg. Needs the Bun runtime; there is no fake clock, so time events use the
- * app's own controls.
+ * Drives a web app in Bun's built-in headless browser for `atlas run`: the system WebKit on macOS (nothing to
+ * install), Chrome over CDP elsewhere. A view starts in milliseconds and screenshots take about ten, so it is the
+ * quickest way to run a chart against a real page. Each path attempt gets its own view, closed afterwards. Screenshots
+ * are PNG files without a thumbnail. Clips are encoded from screenshots with FFmpeg (no clip is recorded without it).
+ * `user.tap` and `user.type` wait up to `actionTimeoutMs` for the target signal to show, then click its centre; a
+ * target that never shows fails the step with "<signal> is not on screen". Needs the Bun runtime (run
+ * `bun --bun atlas run`), and throws on open without it. There is no fake clock, so time events use the app's own
+ * controls.
+ *
+ * @see docs/statecharts.md
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from '@crvouga/atlas';
+ * import { bunWebViewDriver, screen, text } from '@crvouga/atlas/bun';
+ *
+ * export default defineConfig({
+ *   specs: './specs',
+ *   driver: () => bunWebViewDriver({ baseUrl: 'http://127.0.0.1:4317' }),
+ *   implementation: {
+ *     async setup(ctx) { await ctx.goto('/'); },
+ *     events: {
+ *       // one entry per event of the spec
+ *     },
+ *     states: { 'No todos': screen({ all: [text('Nothing to do yet')] }) }
+ *   }
+ * });
+ * ```
  */
 export function bunWebViewDriver(options = {}) {
     const width = options.width ?? 390;
@@ -86,5 +120,12 @@ export function bunWebViewDriver(options = {}) {
         hold: (_ctx, ms) => new Promise((r) => setTimeout(r, ms))
     };
 }
-/** A state recognised from its signals in the page: every `all` visible and no `none` visible. */
+/**
+ * Builds a state implementation for a `WebViewContext` from its signals in the page: every `all` signal visible, one
+ * `any` signal visible (when given), no `none` signal visible. It is core's `signatureScreen` over `ctx.isVisible`, so
+ * it takes the same spec as `screen` from `@crvouga/atlas/signals` (`checks`, `transient`, `sameAs`, `lookIn`,
+ * `settle` included).
+ *
+ * @see docs/statecharts.md
+ */
 export const screen = signatureScreen((ctx, signal) => ctx.isVisible(signal), describeSignal);

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

@@ -1,2 +1,10 @@
+/**
+ * @module Bun WebView driver entry point (`@crvouga/atlas/bun`)
+ *
+ * Re-exports the Bun WebView driver for statechart runs (`bunWebViewDriver`), its context and option types, `screen`
+ * for recognising states from signals, and the signal constructors. Needs the Bun runtime.
+ *
+ * @see docs/statecharts.md
+ */
 export { bunWebViewDriver, screen, type BunWebView, type BunWebViewDriverOptions, type WebViewContext } from './driver.js';
 export { css, label, role, testId, text, describeSignal, type Signal } from '../../core/src/signals.js';

package/dist/bun/src/index.js

@@ -1,2 +1,10 @@
+/**
+ * @module Bun WebView driver entry point (`@crvouga/atlas/bun`)
+ *
+ * Re-exports the Bun WebView driver for statechart runs (`bunWebViewDriver`), its context and option types, `screen`
+ * for recognising states from signals, and the signal constructors. Needs the Bun runtime.
+ *
+ * @see docs/statecharts.md
+ */
 export { bunWebViewDriver, screen } from './driver.js';
 export { css, label, role, testId, text, describeSignal } from '../../core/src/signals.js';

package/dist/core/src/cli.d.ts

@@ -1 +1,14 @@
-export declare function main(argv?: string[]): Promise<0 | 1 | 2>;
+/**
+ * @module The `atlas` command
+ *
+ * Dispatches `atlas <command>`: the statechart commands (`lint`, `plan`, `run`, `merge`, `export`) and, loaded on demand so
+ * they cost nothing otherwise, `serve`, `dev`, `init` and `report`. Statechart configuration is `atlas.config.ts` (see
+ * `defineConfig`). A command that is wrong prints a message and exits 2; a plan, lint or run that finds problems exits 1.
+ *
+ * @see docs/statecharts.md
+ * @see docs/reference/cli.md
+ */
+/** The text `atlas --help` prints: every command, and the flags of the statechart commands. */
+export declare const USAGE = "atlas \u2014 executable statecharts\n\n  atlas lint   [--config atlas.config.ts | --specs <dir>] [--require-implementations]\n  atlas plan   [--config atlas.config.ts] [--state <name>]\n  atlas run    [--config atlas.config.ts] [--mode fast|showcase] [--workers n] [--state <name>]\n               [--seed <name>]... [--paths id,id] [--shard i/n] [--rerun-failed | --reuse <run-dir>]\n               [--no-retry] [--output <dir>]\n  atlas merge  [--config atlas.config.ts] [--output <dir>] <run-dir> <run-dir>...\n  atlas export --specs <dir> --format scxml|mermaid|markdown|json [--out <file>]\n  atlas serve  [--data <dir>] [--port 8080] [--store <url>]...   the Atlas server: results in, the live report out\n  atlas dev    [--port 5180]                                     the server and the viewer's dev server, on one host\n  atlas init   [--server <url>] [--write]                         integrate this project: detect its suites, print the plan (atlas init --help)\n  atlas report publish|stream|status|merge|doctor|policy \u2026       layered evidence for any kind of spec (atlas report --help)\n\n  --workers       path attempts that run at once (default: one per CPU, capped by the driver)\n  --seed          only paths that start from this seed (\"start\" for paths setup starts); repeatable\n  --shard 2/4     run the second quarter of the plan; merge the shards' runs afterwards\n  --rerun-failed  keep the newest run's passed paths and run only the rest\n";
+/** Runs `atlas` with `argv` (default: the process arguments) and returns the exit code. Throws for a command that is wrong, which the `atlas` binary reports as a message and exit code 2. */
+export declare function main(argv?: string[]): Promise<number>;

package/dist/core/src/cli.js

@@ -1,3 +1,13 @@
+/**
+ * @module The `atlas` command
+ *
+ * Dispatches `atlas <command>`: the statechart commands (`lint`, `plan`, `run`, `merge`, `export`) and, loaded on demand so
+ * they cost nothing otherwise, `serve`, `dev`, `init` and `report`. Statechart configuration is `atlas.config.ts` (see
+ * `defineConfig`). A command that is wrong prints a message and exits 2; a plan, lint or run that finds problems exits 1.
+ *
+ * @see docs/statecharts.md
+ * @see docs/reference/cli.md
+ */
 import { writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -8,7 +18,8 @@ import { toMarkdown } from './report/markdown.js';
 import { composeCharts } from './spec/compose.js';
 import { loadSpecDirectory } from './spec/load.js';
 import { machineToScxml } from './spec/scxml.js';
-const USAGE = `atlas — executable statecharts
+/** The text `atlas --help` prints: every command, and the flags of the statechart commands. */
+export const USAGE = `atlas — executable statecharts
 
   atlas lint   [--config atlas.config.ts | --specs <dir>] [--require-implementations]
   atlas plan   [--config atlas.config.ts] [--state <name>]
@@ -17,6 +28,10 @@ const USAGE = `atlas — executable statecharts
                [--no-retry] [--output <dir>]
   atlas merge  [--config atlas.config.ts] [--output <dir>] <run-dir> <run-dir>...
   atlas export --specs <dir> --format scxml|mermaid|markdown|json [--out <file>]
+  atlas serve  [--data <dir>] [--port 8080] [--store <url>]...   the Atlas server: results in, the live report out
+  atlas dev    [--port 5180]                                     the server and the viewer's dev server, on one host
+  atlas init   [--server <url>] [--write]                         integrate this project: detect its suites, print the plan (atlas init --help)
+  atlas report publish|stream|status|merge|doctor|policy …       layered evidence for any kind of spec (atlas report --help)
 
   --workers       path attempts that run at once (default: one per CPU, capped by the driver)
   --seed          only paths that start from this seed ("start" for paths setup starts); repeatable
@@ -69,8 +84,22 @@ async function loadConfig(file) {
         throw new Error(`${file} has no default export (use defineConfig)`);
     return { config: mod.default, base: path.dirname(absolute) };
 }
+/** Runs `atlas` with `argv` (default: the process arguments) and returns the exit code. Throws for a command that is wrong, which the `atlas` binary reports as a message and exit code 2. */
 export async function main(argv = process.argv.slice(2)) {
     const [command] = argv;
+    // Loaded on demand: lint, plan and run do not pay for the reports.
+    if (command === 'serve') {
+        const { serveMain } = await import('../../server/src/main.js');
+        return serveMain(argv.slice(1), { out: text => process.stdout.write(text) });
+    }
+    if (command === 'dev') {
+        const { devMain } = await import('../../server/src/dev.js');
+        return devMain(argv.slice(1), { out: text => process.stdout.write(text) });
+    }
+    if (command === 'init')
+        return (await import('../../reports/src/init.js')).initMain(argv.slice(1), { out: text => process.stdout.write(text) });
+    if (command === 'report')
+        return (await import('../../reports/src/report-cli.js')).runReportCommand(argv.slice(1));
     const configFile = flag(argv, 'config') ?? 'atlas.config.ts';
     const specs = flag(argv, 'specs');
     const output = flag(argv, 'output');

package/dist/core/src/config.d.ts

@@ -1,6 +1,10 @@
 import type { StateValue } from './graph.js';
 import type { Shard } from './run/execute.js';
 import type { Driver, EventMatcher, EventSource, Implementation, PrivacyRules, RunMode } from './run/types.js';
+/**
+ * Everything a project says about running its specs. `C` is the type of the driver's context
+ * (a Playwright `Page`, a model, ...), which events and states receive.
+ */
 export type AtlasConfig<C = unknown> = {
     /** The directory holding the charts (`*.scxml`, `*.machine.{json,yaml}`) and `journeys.yaml`. */
     specs: string;
@@ -8,6 +12,7 @@ export type AtlasConfig<C = unknown> = {
     chart?: string;
     /** Where generated paths start (an XState state value); the initial state when omitted. */
     start?: StateValue;
+    /** A phrase describing `start` in reports; `The start of the chart` when omitted. */
     startLabel?: string;
     /** Only these events enter the chart from outside it. */
     entryEvents?: string[];
@@ -17,27 +22,61 @@ export type AtlasConfig<C = unknown> = {
     workers?: number;
     /** Runs once before any path: prepare what every seed relies on (reference data, config). */
     beforeRun?: () => Promise<void> | void;
+    /** The driver, or a function that creates it (called once per run, after `beforeRun`). */
     driver: Driver<C> | (() => Driver<C> | Promise<Driver<C>>);
+    /** How to make each event happen and recognise each state. */
     implementation: Implementation<C>;
     /** Where runs are written; `atlas-runs` beside the config when omitted. */
     output?: string;
+    /** Creates the business event sources for a run (called once per run; the run closes them). */
     eventSources?: () => EventSource[] | Promise<EventSource[]>;
+    /** How each business event name from `meta.events` is recognised; by default a CloudEvent whose `type` equals the name. */
     eventMatchers?: Record<string, EventMatcher>;
+    /** Extra privacy rules on top of the defaults. */
     privacy?: PrivacyRules;
     /** URLs the run will reach; checked against `privacy.allowHosts` (loopback by default). */
     targets?: string[];
+    /** Recorded in the manifest as the run's environment (`run.environment`), beside the driver name. */
     environment?: Record<string, unknown>;
+    /** How long to wait for a state to be recognised after an event, in milliseconds; 45 000 when omitted. */
     stepTimeoutMs?: number;
     /** Meta fields every state must carry (default: description). */
     requiredMeta?: string[];
 };
+/**
+ * Declares an Atlas config with types, returning it unchanged. Put it as the default export of
+ * `atlas.config.ts`; the CLI loads the file with `tsx` and defaults to `atlas.config.ts` in the
+ * current directory.
+ *
+ * @see docs/statecharts.md
+ *
+ * @example
+ * export default defineConfig({
+ *   specs: './specs',
+ *   driver: () => functionDriver(() => new TodoModel()),
+ *   implementation: {
+ *     events: { 'Adds a todo': { kind: 'user', how: 'Calls add().', run: async (model) => model.add('x') } },
+ *     states: { 'No todos': { recognize: async (model) => ({ matched: model.count === 0, signals: [] }) } }
+ *   }
+ * });
+ */
 export declare function defineConfig<C>(config: AtlasConfig<C>): AtlasConfig<C>;
-/** Narrow what a config runs from the command line. */
+/** Overrides of a config that the command line can give. */
 export type PrepareOptions = {
     /** Scope the run to this state instead of the config's. */
     state?: string;
 };
-/** Load, lint and plan a config without running anything. */
+/**
+ * Loads, lints and plans a config without running anything (what `atlas lint` and `atlas plan` do).
+ *
+ * @param baseDirectory what a relative `config.specs` resolves against.
+ * @returns the loaded `bundle`; `lint` (findings, composition and graph, including `implemented`
+ *   findings for what the implementation lacks); the run's `scope`; the `plan` (paths, journeys, seeds,
+ *   `unreachable`); and the resolved `specs` directory.
+ * @throws Error when the specs cannot be loaded or composed, when a seed's `shows` is not active where
+ *   it starts, or when a seed's `for` names an event no state handles. Lint findings are returned,
+ *   not thrown.
+ */
 export declare function prepare<C>(config: AtlasConfig<C>, baseDirectory?: string, options?: PrepareOptions): {
     bundle: import('./index.js').SpecBundle;
     lint: {
@@ -82,22 +121,41 @@ export declare function prepare<C>(config: AtlasConfig<C>, baseDirectory?: strin
     };
     specs: string;
 };
+/** The options of `atlas run` that `runConfig` accepts; each overrides the config's own setting. */
 export type RunCommandOptions = PrepareOptions & {
+    /** `fast` when omitted. */
     mode?: RunMode;
     /** Only these paths, by id. */
     paths?: string[];
     /** Only paths that start from these seeds ("start" for paths that `setup` starts). */
     seeds?: string[];
+    /** Whether a failed path runs again to tell flaky from broken; true unless `false`. */
     retry?: boolean;
+    /** Where the run is written; the config's `output`, else `atlas-runs`. */
     output?: string;
+    /** Path attempts at once; the config's `workers`, else one per CPU, always capped by the driver. */
     workers?: number;
     /** Run one shard of the plan; `atlas merge` composes the shards. */
     shard?: Shard;
     /** Keep the passed paths of this run (or the newest run, with "latest") and run the rest. */
     reuse?: string;
+    /** Receives progress lines; stdout when omitted. */
     log?: (line: string) => void;
 };
-/** Run a config end to end and write its manifest and reports. */
+/**
+ * Runs a config end to end and writes the run (manifest, reports, media) under its output
+ * directory, like `atlas run`.
+ *
+ * Refuses to start (throws) when the spec has any structural lint finding (everything but missing
+ * implementations, which just block paths) or when a `targets` URL is not on the privacy allow-list.
+ * Then it calls `beforeRun`, creates the driver and runs the planned paths (filtered by
+ * `options.paths`/`seeds`/`shard`, reusing earlier passes when `options.reuse` is set).
+ *
+ * @returns what `runPaths` returns: the run directory, the manifest and `ok` (false if any path
+ *   failed or the privacy scan found something).
+ * @throws Error also when `reuse` names a run with no outcomes or there is no earlier run for `latest`.
+ * @see docs/statecharts.md
+ */
 export declare function runConfig<C>(config: AtlasConfig<C>, options?: RunCommandOptions, baseDirectory?: string): Promise<{
     runDir: string;
     manifest: {
@@ -285,7 +343,15 @@ export declare function runConfig<C>(config: AtlasConfig<C>, options?: RunComman
     };
     ok: boolean;
 }>;
-/** Compose runs of a config (its shards, or a rerun and the run before it) into one run. */
+/**
+ * Composes runs of a config (its shards, or a rerun and the run before it) into one new run
+ * under the output directory, like `atlas merge`. The plan is recomputed from the config, so the runs
+ * must come from the same specs, implementation and seeds.
+ *
+ * @param runDirs the run directories to compose; later ones win when two ran the same path.
+ * @returns what `mergeRuns` returns: the new run directory, its manifest and `ok`.
+ * @throws Error when a run directory has no `outcomes.json`.
+ */
 export declare function mergeConfigRuns<C>(config: AtlasConfig<C>, runDirs: string[], options?: PrepareOptions & {
     output?: string;
 }, baseDirectory?: string): {

package/dist/core/src/config.js

@@ -1,3 +1,14 @@
+/**
+ * @module Config and programmatic API
+ *
+ * The user-facing entry point: `defineConfig` types a project's `atlas.config.ts`, and `prepare`,
+ * `runConfig` and `mergeConfigRuns` are the programmatic equivalents of `atlas lint`/`plan`, `atlas
+ * run` and `atlas merge`. They wire the pieces together (load specs, lint, scope, plan, run) and add
+ * no behaviour of their own beyond validating the config against the spec. Relative paths in a config
+ * resolve against the `baseDirectory` argument (the config file's directory when called by the CLI).
+ *
+ * @see docs/statecharts.md
+ */
 import { availableParallelism } from 'node:os';
 import path from 'node:path';
 import { lintBundle } from './lint.js';
@@ -5,10 +16,37 @@ import { chartScope, planChart } from './plan.js';
 import { assertAllowedTarget, mergePrivacy } from './privacy.js';
 import { latestRun, mergeRuns, readOutcomes, runPaths, shardPaths } from './run/execute.js';
 import { loadSpecDirectory } from './spec/load.js';
+/**
+ * Declares an Atlas config with types, returning it unchanged. Put it as the default export of
+ * `atlas.config.ts`; the CLI loads the file with `tsx` and defaults to `atlas.config.ts` in the
+ * current directory.
+ *
+ * @see docs/statecharts.md
+ *
+ * @example
+ * export default defineConfig({
+ *   specs: './specs',
+ *   driver: () => functionDriver(() => new TodoModel()),
+ *   implementation: {
+ *     events: { 'Adds a todo': { kind: 'user', how: 'Calls add().', run: async (model) => model.add('x') } },
+ *     states: { 'No todos': { recognize: async (model) => ({ matched: model.count === 0, signals: [] }) } }
+ *   }
+ * });
+ */
 export function defineConfig(config) {
     return config;
 }
-/** Load, lint and plan a config without running anything. */
+/**
+ * Loads, lints and plans a config without running anything (what `atlas lint` and `atlas plan` do).
+ *
+ * @param baseDirectory what a relative `config.specs` resolves against.
+ * @returns the loaded `bundle`; `lint` (findings, composition and graph, including `implemented`
+ *   findings for what the implementation lacks); the run's `scope`; the `plan` (paths, journeys, seeds,
+ *   `unreachable`); and the resolved `specs` directory.
+ * @throws Error when the specs cannot be loaded or composed, when a seed's `shows` is not active where
+ *   it starts, or when a seed's `for` names an event no state handles. Lint findings are returned,
+ *   not thrown.
+ */
 export function prepare(config, baseDirectory = process.cwd(), options = {}) {
     const specs = path.resolve(baseDirectory, config.specs);
     const bundle = loadSpecDirectory(specs);
@@ -60,7 +98,20 @@ const contextOf = (config, prepared) => ({
     ...(config.privacy ? { privacy: config.privacy } : {}),
     ...(config.environment ? { environment: config.environment } : {})
 });
-/** Run a config end to end and write its manifest and reports. */
+/**
+ * Runs a config end to end and writes the run (manifest, reports, media) under its output
+ * directory, like `atlas run`.
+ *
+ * Refuses to start (throws) when the spec has any structural lint finding (everything but missing
+ * implementations, which just block paths) or when a `targets` URL is not on the privacy allow-list.
+ * Then it calls `beforeRun`, creates the driver and runs the planned paths (filtered by
+ * `options.paths`/`seeds`/`shard`, reusing earlier passes when `options.reuse` is set).
+ *
+ * @returns what `runPaths` returns: the run directory, the manifest and `ok` (false if any path
+ *   failed or the privacy scan found something).
+ * @throws Error also when `reuse` names a run with no outcomes or there is no earlier run for `latest`.
+ * @see docs/statecharts.md
+ */
 export async function runConfig(config, options = {}, baseDirectory = process.cwd()) {
     const prepared = prepare(config, baseDirectory, options);
     const structural = prepared.lint.findings.filter((f) => f.rule !== 'implemented');
@@ -93,7 +144,15 @@ export async function runConfig(config, options = {}, baseDirectory = process.cw
         ...(options.log ? { log: options.log } : {})
     });
 }
-/** Compose runs of a config (its shards, or a rerun and the run before it) into one run. */
+/**
+ * Composes runs of a config (its shards, or a rerun and the run before it) into one new run
+ * under the output directory, like `atlas merge`. The plan is recomputed from the config, so the runs
+ * must come from the same specs, implementation and seeds.
+ *
+ * @param runDirs the run directories to compose; later ones win when two ran the same path.
+ * @returns what `mergeRuns` returns: the new run directory, its manifest and `ok`.
+ * @throws Error when a run directory has no `outcomes.json`.
+ */
 export function mergeConfigRuns(config, runDirs, options = {}, baseDirectory = process.cwd()) {
     const prepared = prepare(config, baseDirectory, options);
     return mergeRuns(contextOf(config, prepared), prepared.plan.paths, runDirs.map((d) => path.resolve(d)), { outputRoot: path.resolve(baseDirectory, options.output ?? config.output ?? 'atlas-runs') });

package/dist/core/src/events/cloudevents.d.ts

@@ -11,11 +11,32 @@ export type CloudEvent = {
     data?: unknown;
     [extension: string]: unknown;
 };
-/** Parse an HTTP delivery in either CloudEvents content mode (structured, binary or batch). */
+/**
+ * Parses an HTTP delivery in any CloudEvents content mode: structured (`application/cloudevents+json`),
+ * batch (`application/cloudevents-batch+json`) or binary (`ce-*` headers, with the body as `data`).
+ * A request with none of those (no `ce-type` header and a different content type) yields no events.
+ * In binary mode a missing `ce-id` becomes a random UUID and a missing `ce-source` becomes `unknown`;
+ * other `ce-*` headers become extension attributes; the body is parsed as JSON when the content type
+ * says JSON and it parses, else kept as text.
+ *
+ * @param headers lower-cased header names, as Node's `IncomingMessage.headers`.
+ * @throws SyntaxError when a structured or batch body is not valid JSON.
+ */
 export declare function cloudEventsFromHttp(headers: Record<string, string | string[] | undefined>, body: string): CloudEvent[];
 /**
- * An HTTP endpoint the system under test sends CloudEvents to (any content mode). Point the
- * product's event bus, webhook relay or OpenTelemetry collector's CloudEvents exporter at it.
+ * Starts an HTTP endpoint the system under test sends CloudEvents to (any content mode). Point the
+ * product's event bus, webhook relay or OpenTelemetry collector's CloudEvents exporter at its `url`.
+ *
+ * It answers every valid POST with 202 and an unparseable delivery with 400, and keeps events in
+ * memory. It does no authentication and listens on `127.0.0.1` unless `host` says otherwise, so
+ * only the local machine can reach it by default. `mark()` is the number of events received so far.
+ * Call `close()` to stop the server; `runPaths` does that for the sources it is given.
+ *
+ * @param options.port the port to listen on; an unused port when omitted (read the real one from `url`).
+ * @param options.host the interface to listen on; `127.0.0.1` when omitted.
+ *
+ * @example
+ * eventSources: async () => [await cloudEventsHttpSource({ port: 4318 })]
  */
 export declare function cloudEventsHttpSource(options?: {
     port?: number;
@@ -23,20 +44,38 @@ export declare function cloudEventsHttpSource(options?: {
 }): Promise<EventSource & {
     url: string;
 }>;
-/** Lines appended to a log file during a step, for products whose only event stream is a log. */
+/**
+ * An event source for products whose only event stream is a log file: `collect` returns the text
+ * appended to the file since `mark` (match it with an `{ pattern }` matcher), and no CloudEvents.
+ *
+ * `mark()` is the file's size in bytes (0 when it does not exist). `collect` first waits `settleMs`
+ * for the product to write, then reads from the mark to the end of the file; a missing or
+ * unreadable file gives empty text, and a file that was truncated or rotated since the mark is not
+ * detected. The source's name starts with `log:`, which is how the runner tells it from a CloudEvents source.
+ *
+ * @param file the log file path.
+ * @param options.settleMs how long `collect` waits before reading, in milliseconds; 1000 when omitted.
+ */
 export declare function logFileSource(file: string, options?: {
     settleMs?: number;
 }): EventSource;
+/** The outcome of comparing a state's expected business events with what the sources collected. */
 export type BusinessEventResult = {
+    /** The names listed in the state's `meta.events`. */
     expected: string[];
+    /** Expected names that a matcher (or a CloudEvent of that type) confirmed. */
     observed: string[];
+    /** Expected names that could be observed but were not. */
     missing: string[];
+    /** Expected names with no way to be observed (no matcher and no CloudEvents source). Not a failure. */
     noSignal: string[];
+    /** The CloudEvents collected for this step. */
     events: CloudEvent[];
 };
 /**
- * Keep what belongs to one attempt when attempts run side by side: events and log lines that
- * mention one of its correlation ids. With no ids, everything is kept.
+ * Keeps what belongs to one attempt when attempts run side by side: events (whose JSON mentions an
+ * id) and log lines that contain one of its correlation ids. Empty ids are ignored; with no ids,
+ * everything is kept.
  */
 export declare function correlated(collected: {
     events: CloudEvent[];
@@ -46,9 +85,15 @@ export declare function correlated(collected: {
     text: string;
 };
 /**
- * Compare the business events a state expects with what the sources saw. A business event is
- * observed when its matcher matches; with no matcher, a CloudEvent whose `type` equals the name.
- * Events with neither a matcher nor any CloudEvents source are "no signal", never "missing".
+ * Compares the business events a state expects with what the sources saw, sorting each expected
+ * name into `observed`, `missing` or `noSignal`. A business event is observed when its matcher
+ * matches (a function gets the events and log text; `{ type }` compares CloudEvent types;
+ * `{ pattern }` tests the log text); with no matcher, when a CloudEvent's `type` equals the name.
+ * With neither a matcher nor any CloudEvents source (`hasCloudEvents` false) it is "no signal",
+ * never "missing". Pure.
+ *
+ * @param matchers matchers by business event name.
+ * @param hasCloudEvents whether any non-log source was configured.
  */
 export declare function compareBusinessEvents(expected: string[], collected: {
     events: CloudEvent[];