@crvouga/atlas 0.3.0 → 0.5.0

package/dist/core/src/report/formats.d.ts

@@ -1,3 +1,13 @@
+/**
+ * @module Run report formats
+ *
+ * Pure converters from a run's manifest (or a chart) to the formats other tools read: JUnit XML, CTRF
+ * JSON, WebVTT captions and a Mermaid state diagram. They take plain data, do no I/O and are
+ * deterministic. The manifest is read through a minimal structural type, so only the fields named
+ * there are required of it.
+ *
+ * @see docs/statecharts.md
+ */
 import type { MachineConfig } from '../spec/types.js';
 import type { TimelineEntry } from '../run/types.js';
 type ManifestLike = {
@@ -23,9 +33,19 @@ type ManifestLike = {
         }[];
     }[];
 };
-/** JUnit XML (the format every CI system reads): one test case per path. */
+/**
+ * Renders the manifest as JUnit XML (the format every CI system reads): one test case per path,
+ * with `classname` the path kind (`journey` or `generated`). A failed path is a `failure` carrying
+ * the last attempt's error, a `not-reached` path is `skipped` (with the blocking reason when there is
+ * one), and a flaky path passes with a note in `system-out`. The suite time is the run duration in seconds.
+ */
 export declare function toJUnit(manifest: ManifestLike): string;
-/** CTRF (Common Test Report Format, https://ctrf.io) JSON. */
+/**
+ * Renders the manifest as CTRF (Common Test Report Format, https://ctrf.io) JSON: one test per
+ * path, its steps as `steps`. `flaky` paths are `passed` with `flaky: true`, `not-reached` is
+ * `skipped`, and the failed path's trace (if any) is attached. Per-test `duration` is always 0:
+ * only the run's start and stop times are recorded.
+ */
 export declare function toCtrf(manifest: ManifestLike): {
     reportFormat: string;
     specVersion: string;
@@ -62,8 +82,18 @@ export declare function toCtrf(manifest: ManifestLike): {
         }[];
     };
 };
-/** WebVTT captions for a clip, one cue per timeline entry. */
+/**
+ * Renders WebVTT captions for a clip, one cue per timeline entry. A cue lasts until the next entry
+ * (or the clip's end), at least 500 ms and at most 4 s.
+ *
+ * @param timeline the step's entries, with `atMs` relative to the start of the clip.
+ * @param durationMs the clip's length in milliseconds.
+ */
 export declare function toWebVtt(timeline: TimelineEntry[], durationMs: number): string;
-/** A Mermaid `stateDiagram-v2` of a machine, with nested and parallel states. */
+/**
+ * Renders a machine as a Mermaid `stateDiagram-v2` with nested and parallel states. States get
+ * short ids (`s0`, `s1`, ... in order of first use) and keep their names as labels; `:` and `;` in event
+ * names are replaced by spaces because Mermaid reads them as syntax. Written as `chart.mmd` in every run.
+ */
 export declare function toMermaid(machine: MachineConfig): string;
 export {};

package/dist/core/src/report/formats.js

@@ -1,6 +1,11 @@
 import { targetOf } from '../spec/types.js';
 const xml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
-/** JUnit XML (the format every CI system reads): one test case per path. */
+/**
+ * Renders the manifest as JUnit XML (the format every CI system reads): one test case per path,
+ * with `classname` the path kind (`journey` or `generated`). A failed path is a `failure` carrying
+ * the last attempt's error, a `not-reached` path is `skipped` (with the blocking reason when there is
+ * one), and a flaky path passes with a note in `system-out`. The suite time is the run duration in seconds.
+ */
 export function toJUnit(manifest) {
     const cases = manifest.paths.map((p) => {
         const body = p.status === 'failed'
@@ -24,7 +29,12 @@ export function toJUnit(manifest) {
         ''
     ].join('\n');
 }
-/** CTRF (Common Test Report Format, https://ctrf.io) JSON. */
+/**
+ * Renders the manifest as CTRF (Common Test Report Format, https://ctrf.io) JSON: one test per
+ * path, its steps as `steps`. `flaky` paths are `passed` with `flaky: true`, `not-reached` is
+ * `skipped`, and the failed path's trace (if any) is attached. Per-test `duration` is always 0:
+ * only the run's start and stop times are recorded.
+ */
 export function toCtrf(manifest) {
     const status = (s) => (s === 'passed' ? 'passed' : s === 'failed' ? 'failed' : s === 'flaky' ? 'passed' : 'skipped');
     const tests = manifest.paths.map((p) => ({
@@ -62,7 +72,13 @@ function vttTime(ms) {
     const pad = (n, w = 2) => String(n).padStart(w, '0');
     return `${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}:${pad(d.getUTCSeconds())}.${pad(d.getUTCMilliseconds(), 3)}`;
 }
-/** WebVTT captions for a clip, one cue per timeline entry. */
+/**
+ * Renders WebVTT captions for a clip, one cue per timeline entry. A cue lasts until the next entry
+ * (or the clip's end), at least 500 ms and at most 4 s.
+ *
+ * @param timeline the step's entries, with `atMs` relative to the start of the clip.
+ * @param durationMs the clip's length in milliseconds.
+ */
 export function toWebVtt(timeline, durationMs) {
     const cues = timeline.map((e, i) => {
         const end = Math.min(timeline[i + 1]?.atMs ?? durationMs, e.atMs + 4_000);
@@ -71,7 +87,11 @@ export function toWebVtt(timeline, durationMs) {
     });
     return `WEBVTT\n\n${cues.join('\n\n')}\n`;
 }
-/** A Mermaid `stateDiagram-v2` of a machine, with nested and parallel states. */
+/**
+ * Renders a machine as a Mermaid `stateDiagram-v2` with nested and parallel states. States get
+ * short ids (`s0`, `s1`, ... in order of first use) and keep their names as labels; `:` and `;` in event
+ * names are replaced by spaces because Mermaid reads them as syntax. Written as `chart.mmd` in every run.
+ */
 export function toMermaid(machine) {
     const ids = new Map();
     const id = (name) => {

package/dist/core/src/report/markdown.d.ts

@@ -1,8 +1,23 @@
+/**
+ * @module Markdown chart map
+ *
+ * Renders a chart (usually the composed product) as a Markdown document for the people who own the
+ * product, not for developers: plain Markdown with internal links, so it renders on any code host
+ * and diffs with the chart. Pure and deterministic.
+ */
 import type { Journey, MachineConfig } from '../spec/types.js';
 /**
  * A readable map of a chart for the people who own the product: one section per area (parallel
  * regions apart), each state with what it means, what the user sees, and every event that can
  * happen there and where it leads, then the named journeys. Plain Markdown, so it renders on any
  * code host and diffs with the chart.
+ *
+ * Top-level states become sections, and each region of a top-level parallel state gets its own. A
+ * `snapshot` is shown only when it contains whitespace (so an identifier-like snapshot is left out),
+ * and a state with `confidence: 'assumed'` is marked as unconfirmed. Links use GitHub's heading anchors.
+ *
+ * @param machine the chart, composed if child charts should be inlined.
+ * @param journeys the named journeys to list at the end; none by default.
+ * @see docs/statecharts.md
  */
 export declare function toMarkdown(machine: MachineConfig, journeys?: Journey[]): string;

package/dist/core/src/report/markdown.js

@@ -47,6 +47,14 @@ const cell = (text) => text.replace(/\|/g, '\\|').replace(/\s*\n\s*/g, ' ');
  * regions apart), each state with what it means, what the user sees, and every event that can
  * happen there and where it leads, then the named journeys. Plain Markdown, so it renders on any
  * code host and diffs with the chart.
+ *
+ * Top-level states become sections, and each region of a top-level parallel state gets its own. A
+ * `snapshot` is shown only when it contains whitespace (so an identifier-like snapshot is left out),
+ * and a state with `confidence: 'assumed'` is marked as unconfirmed. Links use GitHub's heading anchors.
+ *
+ * @param machine the chart, composed if child charts should be inlined.
+ * @param journeys the named journeys to list at the end; none by default.
+ * @see docs/statecharts.md
  */
 export function toMarkdown(machine, journeys = []) {
     const sections = sectionsOf(machine);

package/dist/core/src/run/clients.d.ts

@@ -1,4 +1,5 @@
 import type { Driver, EventImplementation, Implementation, StateImplementation } from './types.js';
+/** Options for `combineDrivers`. */
 export type CombineDriversOptions = {
     /**
      * `focused` (default) screenshots the client a state is recognised on; `all` also screenshots
@@ -13,16 +14,36 @@ export type CombineDriversOptions = {
  * act on (`onClient`, `combineImplementations`), so screenshots and clips come from that client's
  * screen. Timeline entries are tagged with the client that made them.
  *
- *   combineDrivers({ member: webdriverDriver(appiumIos), operator: playwrightDriver(), api: httpDriver(url) })
+ * The combined driver's `concurrency` is the smallest of the drivers' (1 for any that give none),
+ * its `pacing` is the first driver's that has one, and its name lists `<client>:<driver name>`.
+ * If any client fails to open, the ones that did open are closed and the open throws naming that client.
+ * Closing returns the first client's trace as `trace` and every client's in `traces`. Without
+ * a `focus`, `screenshot` and `record` use the first driver that supports them and `text` joins every
+ * client's text.
+ *
+ * @throws Error when `drivers` is empty.
+ * @see docs/statecharts.md
+ *
+ * @example
+ * const driver = combineDrivers<{ member: Page; api: HttpClient }>({
+ *   member: playwrightDriver(),
+ *   api: httpDriver('http://127.0.0.1:4000')
+ * });
  */
 export declare function combineDrivers<M extends Record<string, unknown>>(drivers: {
     [K in keyof M]: Driver<M[K]>;
 }, options?: CombineDriversOptions): Driver<M>;
-/** A state implementation written for one client's context, lifted to a multi-client context. */
+/**
+ * Lifts a state implementation written against one client's context to the combined context and
+ * sets its `client`, so its screenshot comes from that client's screen.
+ */
 export declare function onClient<K extends string, C>(client: K, impl: StateImplementation<C>): StateImplementation<Record<K, C>>;
-/** An event implementation written for one client's context, lifted to a multi-client context. */
+/**
+ * Lifts an event implementation written against one client's context to the combined context and
+ * sets its `client`, so its clip comes from that client's screen and its timeline entries are tagged with it.
+ */
 export declare function onClient<K extends string, C>(client: K, impl: EventImplementation<C>): EventImplementation<Record<K, C>>;
-/** Part of an implementation: what one client does and shows, or what spans clients. */
+/** Part of an implementation (any subset of its fields): what one client does and shows, or what spans clients. */
 export type ImplementationPart<C> = Partial<Implementation<C>>;
 /**
  * Merge per-client implementations into one. Each client's part is written against that client's
@@ -30,6 +51,21 @@ export type ImplementationPart<C> = Partial<Implementation<C>>;
  * driver work unchanged; `shared` holds what needs several clients at once (read an id on one
  * screen, act on it on another). `shared.setup` runs first (seed data), then each client's setup
  * in the order the clients are listed. An event or state implemented twice is an error.
+ *
+ * A seed with the same name in several parts runs `shared`'s first, then each client's; the combined
+ * seed's `at` is the first one's and its `how` joins all of them. Correlation ids are pooled,
+ * and `canStart` returns the first reason any part gives.
+ *
+ * @param parts the implementation of each client, against that client's own context.
+ * @param shared events, states, seeds and setup that need several clients at once, against the combined context.
+ * @throws Error when an event or state is implemented by more than one part (including `shared`).
+ * @see docs/statecharts.md
+ *
+ * @example
+ * const implementation = combineImplementations<{ member: SignalContext; api: HttpClient }>(
+ *   { member: { events: {}, states: {} }, api: { events: {}, states: {} } },
+ *   { setup: async ({ api }) => void (await api.post('/test/reset')) }
+ * );
  */
 export declare function combineImplementations<M extends Record<string, unknown>>(parts: {
     [K in keyof M]?: ImplementationPart<M[K]>;
@@ -37,6 +73,9 @@ export declare function combineImplementations<M extends Record<string, unknown>
 /**
  * Merge parts of one implementation written against the same context, such as one file per area
  * of a large chart (sign-up, checkout, results). Events, states and seeds must each be
- * implemented once; setups run in order, and correlation ids are pooled.
+ * implemented once; setups run in order, `canStart` returns the first reason any part gives, and
+ * correlation ids are pooled without duplicates.
+ *
+ * @throws Error when an event, state or seed appears in more than one part.
  */
 export declare function mergeImplementations<C>(...parts: ImplementationPart<C>[]): Implementation<C>;

package/dist/core/src/run/clients.js

@@ -1,3 +1,14 @@
+/**
+ * @module Multi-client composition
+ *
+ * Lets one run drive several clients at once (a phone, a desktop browser, an API) by combining their
+ * drivers into one driver whose context is a record keyed by client name, and their implementations
+ * into one implementation. Each event and state records which client it acts on, which decides whose
+ * screen is photographed and recorded. Owns no driver behaviour of its own; it only routes to the
+ * drivers it is given.
+ *
+ * @see docs/statecharts.md
+ */
 import path from 'node:path';
 const inClientDirectory = (file, client) => path.join(path.dirname(file), client, path.basename(file));
 /**
@@ -7,7 +18,21 @@ const inClientDirectory = (file, client) => path.join(path.dirname(file), client
  * act on (`onClient`, `combineImplementations`), so screenshots and clips come from that client's
  * screen. Timeline entries are tagged with the client that made them.
  *
- *   combineDrivers({ member: webdriverDriver(appiumIos), operator: playwrightDriver(), api: httpDriver(url) })
+ * The combined driver's `concurrency` is the smallest of the drivers' (1 for any that give none),
+ * its `pacing` is the first driver's that has one, and its name lists `<client>:<driver name>`.
+ * If any client fails to open, the ones that did open are closed and the open throws naming that client.
+ * Closing returns the first client's trace as `trace` and every client's in `traces`. Without
+ * a `focus`, `screenshot` and `record` use the first driver that supports them and `text` joins every
+ * client's text.
+ *
+ * @throws Error when `drivers` is empty.
+ * @see docs/statecharts.md
+ *
+ * @example
+ * const driver = combineDrivers<{ member: Page; api: HttpClient }>({
+ *   member: playwrightDriver(),
+ *   api: httpDriver('http://127.0.0.1:4000')
+ * });
  */
 export function combineDrivers(drivers, options = {}) {
     const names = Object.keys(drivers);
@@ -95,6 +120,7 @@ export function combineDrivers(drivers, options = {}) {
     };
 }
 const scoped = (tools, client) => ({ ...tools, timeline: tools.timeline.for(client) });
+/** Lifts a state or an event implementation to a client of a multi-client context (see the overloads above); a value with `recognize` is a state. */
 export function onClient(client, impl) {
     if ('recognize' in impl) {
         const { recognize, lookIn, settle, checks, ...rest } = impl;
@@ -121,6 +147,21 @@ export function onClient(client, impl) {
  * driver work unchanged; `shared` holds what needs several clients at once (read an id on one
  * screen, act on it on another). `shared.setup` runs first (seed data), then each client's setup
  * in the order the clients are listed. An event or state implemented twice is an error.
+ *
+ * A seed with the same name in several parts runs `shared`'s first, then each client's; the combined
+ * seed's `at` is the first one's and its `how` joins all of them. Correlation ids are pooled,
+ * and `canStart` returns the first reason any part gives.
+ *
+ * @param parts the implementation of each client, against that client's own context.
+ * @param shared events, states, seeds and setup that need several clients at once, against the combined context.
+ * @throws Error when an event or state is implemented by more than one part (including `shared`).
+ * @see docs/statecharts.md
+ *
+ * @example
+ * const implementation = combineImplementations<{ member: SignalContext; api: HttpClient }>(
+ *   { member: { events: {}, states: {} }, api: { events: {}, states: {} } },
+ *   { setup: async ({ api }) => void (await api.post('/test/reset')) }
+ * );
  */
 export function combineImplementations(parts, shared = {}) {
     const clients = Object.keys(parts);
@@ -197,7 +238,10 @@ export function combineImplementations(parts, shared = {}) {
 /**
  * Merge parts of one implementation written against the same context, such as one file per area
  * of a large chart (sign-up, checkout, results). Events, states and seeds must each be
- * implemented once; setups run in order, and correlation ids are pooled.
+ * implemented once; setups run in order, `canStart` returns the first reason any part gives, and
+ * correlation ids are pooled without duplicates.
+ *
+ * @throws Error when an event, state or seed appears in more than one part.
  */
 export function mergeImplementations(...parts) {
     const events = {};

package/dist/core/src/run/execute.d.ts

@@ -17,6 +17,7 @@ export type Shard = {
 };
 /** What a run reports about: the spec, the scope, and the implementation's metadata. */
 export type RunContext<C> = {
+    /** The loaded charts. Their files are re-read (to hash them into `specVersion`) when the manifest is built. */
     bundle: SpecBundle;
     composition: Composition;
     graph: ChartGraph;
@@ -24,20 +25,27 @@ export type RunContext<C> = {
     implementation: Implementation<C>;
     /** The journeys of the plan, as the paths they are cut into; journeys are reported from them. */
     journeys?: PlannedJourney[];
+    /** The plan's seeds, reported in the manifest with the paths that start from and verify each. */
     seeds?: PlannedSeed[];
+    /** How a business event name is recognised, by name; see `EventMatcher`. */
     eventMatchers?: Record<string, EventMatcher>;
     privacy?: PrivacyRules;
     /** Recorded in the manifest as the run's environment. */
     environment?: Record<string, unknown>;
 };
+/** Everything `runPaths` needs: the `RunContext`, the paths to run and how to run them. */
 export type RunOptions<C> = RunContext<C> & {
+    /** The whole plan, in plan order. Paths marked `skipRun` are reported but not run. The manifest covers all of them. */
     paths: PlannedPath[];
     driver: Driver<C>;
     mode: RunMode;
     /** Runs land in `<outputRoot>/<run-id>/`. */
     outputRoot: string;
+    /** Whether a failed path runs a second time to tell flaky from broken; true unless `false`. */
     retry?: boolean;
+    /** How long to wait for a state to be recognised after an event, in milliseconds; 45 000 when omitted. */
     stepTimeoutMs?: number;
+    /** Where business events come from. Sources named with a `log:` prefix are treated as log files, not CloudEvents sources. */
     eventSources?: EventSource[];
     /** Path attempts that run at once, capped by the driver's `concurrency`; 1 when omitted. */
     workers?: number;
@@ -48,6 +56,7 @@ export type RunOptions<C> = RunContext<C> & {
         runDir: string;
         outcomes: Record<string, PathOutcome>;
     };
+    /** Receives progress lines; writes to stdout when omitted. */
     log?: (line: string) => void;
 };
 type StepResult = {
@@ -83,44 +92,68 @@ type Observed = {
  */
 export type PathOutcome = {
     id: string;
+    /** The path's `key`; outcomes are matched across runs by it, not by `id`. */
     key: string;
+    /** `failed` when the last attempt failed, `flaky` when the first failed and the retry passed, `not-reached` when the path stopped at a blocked event, else `passed`. */
     status: Status;
     attempts: Attempt[];
     steps: StepResult[];
     stoppedAt: string | null;
     observed: Observed[];
+    /** Where and why the last attempt failed; `null` when it did not. */
     failure: {
         state: string;
         recognizer: RecognizerResult | null;
         looksLike: string[];
         shot: Image | null;
     } | null;
+    /** Privacy findings from the text the driver reported; they fail the run. */
     leaks: string[];
+    /** Wall-clock milliseconds for all attempts of the path. */
     durationMs: number;
     /** How long the last attempt took to seed (or set up) and recognise its start. */
     setupMs?: number;
     /** The run the outcome was taken from, when it was reused rather than run again. */
     reusedFrom?: string;
 };
-/** A rough cost of a path before it has ever run: setting it up, then each step. */
+/** A rough cost in milliseconds of a path that has never run (5 s to set up, 2.5 s a step); used to order and shard paths. */
 export declare const estimateMs: (p: PlannedPath) => number;
 /**
  * The paths one shard runs: longest first onto the least loaded shard, by the plan alone, so
  * every machine computes the same split. Paths reported without running go to the first shard.
  */
 export declare function shardPaths(paths: PlannedPath[], shard: Shard): PlannedPath[];
-/** The plan keys and outcomes a run wrote, for merging shards and reusing passed paths. */
+/**
+ * Reads the `outcomes.json` of a run directory: the run id and each finished path's outcome by key.
+ * Returns `null` when the file is missing or unreadable, never throws.
+ */
 export declare function readOutcomes(runDir: string): {
     runId: string;
     outcomes: Record<string, PathOutcome>;
 } | null;
-/** How long each path took in the newest run under `outputRoot` that recorded it, by path key. */
+/**
+ * Milliseconds each path took, by path key, taken from the newest of the last 10 runs under
+ * `outputRoot` that ran it (outcomes reused from elsewhere are ignored). Empty when the directory
+ * does not exist. `runPaths` uses it to start the slowest paths first.
+ */
 export declare function durationHistory(outputRoot: string): Record<string, number>;
-/** The newest run under `outputRoot` that wrote outcomes. */
+/** The directory of the newest run under `outputRoot` that wrote `outcomes.json` (run ids sort by time), or `null`. */
 export declare function latestRun(outputRoot: string): string | null;
 /**
- * Fold path outcomes into the run's report, in plan order: the same plan and outcomes always give
- * the same manifest, however many workers ran them, in whatever order they finished.
+ * Folds path outcomes into the run's manifest object, in plan order: the same plan and outcomes
+ * always give the same manifest, however many workers ran them, in whatever order they finished.
+ *
+ * A state or transition is `passed` when a path reached it, `flaky` when only a flaky path did,
+ * `failed` when any failure touched it (a failed check fails its state), else `not-reached`. Reaching a
+ * state also marks its ancestors reached. The whole manifest is scanned for privacy findings, and any
+ * finding sets `privacy.passed` to false. Reads the chart files (for `specVersion`) and runs `git`
+ * in the current directory (for `commit` and `branch`, `null` when that fails). Apart from the
+ * wall-clock fields (`finishedAt`, `updatedAt`, `durationMs`) and those that depend on the working
+ * directory (`commit`, `branch`, `specDirectory`), two folds of the same outcomes are identical.
+ *
+ * @param outcomes finished or in-progress outcomes by path key; a path with none is `queued` or `running`.
+ * @param run.activePaths ids of the paths in flight; they are reported `running` and not counted complete.
+ * @param run.extra extra fields merged into `run` of the manifest (workers, shard, reused, mergedFrom).
  */
 export declare function buildManifest<C>(context: RunContext<C>, paths: PlannedPath[], outcomes: Map<string, PathOutcome>, run: {
     id: string;
@@ -305,8 +338,13 @@ export declare function buildManifest<C>(context: RunContext<C>, paths: PlannedP
         mermaid: string;
     };
 };
+/** The manifest object `buildManifest` returns; it is what `manifest.json` contains. */
 export type Manifest = ReturnType<typeof buildManifest>;
-/** Write a run's manifest, reports and outcomes; returns the manifest. */
+/**
+ * Writes a run's `junit.xml`, `ctrf.json`, `chart.mmd`, `outcomes.json` and `manifest.json` into
+ * `runDir` (each through a temporary file and a rename, so a reader never sees half a file) and returns
+ * the manifest. `outcomes.json` holds only finished paths, not those in `run.activePaths`.
+ */
 export declare function writeRun<C>(runDir: string, context: RunContext<C>, paths: PlannedPath[], outcomes: Map<string, PathOutcome>, run: Parameters<typeof buildManifest>[3]): {
     $schema: string;
     schemaVersion: number;
@@ -480,9 +518,14 @@ export declare function writeRun<C>(runDir: string, context: RunContext<C>, path
     };
 };
 /**
- * Compose the outcomes of several runs of the same plan (the shards of one run, or a rerun of the
- * paths that failed) into one run, folded in plan order. Media are copied in, so the merged run
- * stands on its own. Later runs win when two ran the same path.
+ * Composes the outcomes of several runs of the same plan (the shards of one run, or a rerun and
+ * the run before it) into one new run directory under `options.outputRoot`, folded in plan order. Media are
+ * copied in, so the merged run stands on its own. Later entries of `runDirs` win when two ran the same
+ * path; outcomes whose key is not in `paths` are ignored. The merged run's mode and driver name are
+ * taken from the run manifests unless `options` gives them.
+ *
+ * @returns the new `runDir`, its `manifest`, and `ok` (privacy passed and no path failed).
+ * @throws Error when a run directory has no `outcomes.json`.
  */
 export declare function mergeRuns<C>(context: RunContext<C>, paths: PlannedPath[], runDirs: string[], options: {
     outputRoot: string;
@@ -668,12 +711,22 @@ export declare function mergeRuns<C>(context: RunContext<C>, paths: PlannedPath[
     ok: boolean;
 };
 /**
- * Run planned paths against a system through a driver. Paths start from their seed (or the
- * implementation's `setup`) and run on a pool of workers, longest first, each attempt in its own
- * driver context; every state is recognised from the outside after every step; a failed path is
- * retried once to tell flaky from broken. The manifest is rewritten as each path finishes, from
- * all outcomes so far in plan order, so a crash keeps what ran and the order paths finished in
- * never changes the report.
+ * Runs planned paths against a system through a driver and writes the run to
+ * `<outputRoot>/<timestamp>-<mode>/`. Paths start from their seed (or the implementation's
+ * `setup`) and run on a pool of workers, longest first (by earlier timings, else `estimateMs`),
+ * each attempt in its own driver context; every state is recognised from the outside after every step;
+ * a failed path is retried once to tell flaky from broken. The manifest is rewritten as each path
+ * finishes, from all outcomes so far in plan order, so a crash keeps what ran and the order paths
+ * finished in never changes the report.
+ *
+ * Workers are capped by `driver.concurrency` (1 if the driver gives none) and by the number of paths.
+ * Without `implementation.correlate`, a run on several workers reports business events as "no
+ * signal" rather than guess which attempt they belong to. While it runs it installs
+ * `uncaughtException` and `unhandledRejection` handlers that log and swallow stray errors from
+ * drivers, and removes them when it ends. Passed paths of `options.reuse` are kept instead of re-run.
+ *
+ * @returns the run directory, the final manifest, and `ok` (privacy passed and no path failed).
+ * @see docs/statecharts.md
  */
 export declare function runPaths<C>(options: RunOptions<C>): Promise<{
     runDir: string;

package/dist/core/src/run/execute.js

@@ -1,3 +1,16 @@
+/**
+ * @module Path runner and manifest
+ *
+ * Runs planned paths against the product through a driver and turns what happened into a run: a
+ * directory holding `manifest.json`, `junit.xml`, `ctrf.json`, `chart.mmd`, `outcomes.json` and `media/`.
+ * The invariants: the manifest is a pure fold of the plan and the per-path outcomes in plan order (so
+ * worker scheduling, sharding and reruns never change the report); it is rewritten atomically after
+ * every path so a crash keeps what ran; a failed path is retried once, and passing the second time is
+ * `flaky`. This module is the only one that touches the driver and the file system for a run. Its
+ * outputs follow the manifest schema in `packages/schema` (`schemaVersion: 1`).
+ *
+ * @see docs/statecharts.md
+ */
 import { execSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
@@ -25,7 +38,7 @@ function specVersion(bundle) {
 const relative = (root, file) => path.relative(root, file).split(path.sep).join('/');
 const pad = (n) => String(n).padStart(2, '0');
 const sameStates = (a, b) => a.length === b.length && [...a].sort().join('|') === [...b].sort().join('|');
-/** A rough cost of a path before it has ever run: setting it up, then each step. */
+/** A rough cost in milliseconds of a path that has never run (5 s to set up, 2.5 s a step); used to order and shard paths. */
 export const estimateMs = (p) => 5_000 + 2_500 * p.steps.length;
 /**
  * The paths one shard runs: longest first onto the least loaded shard, by the plan alone, so
@@ -73,7 +86,10 @@ function copyMedia(outcome, from, to) {
         cpSync(source, path.join(to, file));
     }
 }
-/** The plan keys and outcomes a run wrote, for merging shards and reusing passed paths. */
+/**
+ * Reads the `outcomes.json` of a run directory: the run id and each finished path's outcome by key.
+ * Returns `null` when the file is missing or unreadable, never throws.
+ */
 export function readOutcomes(runDir) {
     const file = path.join(runDir, 'outcomes.json');
     if (!existsSync(file))
@@ -86,7 +102,11 @@ export function readOutcomes(runDir) {
         return null;
     }
 }
-/** How long each path took in the newest run under `outputRoot` that recorded it, by path key. */
+/**
+ * Milliseconds each path took, by path key, taken from the newest of the last 10 runs under
+ * `outputRoot` that ran it (outcomes reused from elsewhere are ignored). Empty when the directory
+ * does not exist. `runPaths` uses it to start the slowest paths first.
+ */
 export function durationHistory(outputRoot) {
     const history = {};
     if (!existsSync(outputRoot))
@@ -104,7 +124,7 @@ export function durationHistory(outputRoot) {
     }
     return history;
 }
-/** The newest run under `outputRoot` that wrote outcomes. */
+/** The directory of the newest run under `outputRoot` that wrote `outcomes.json` (run ids sort by time), or `null`. */
 export function latestRun(outputRoot) {
     if (!existsSync(outputRoot))
         return null;
@@ -114,8 +134,20 @@ export function latestRun(outputRoot) {
     return runs.length ? path.join(outputRoot, runs.at(-1)) : null;
 }
 /**
- * Fold path outcomes into the run's report, in plan order: the same plan and outcomes always give
- * the same manifest, however many workers ran them, in whatever order they finished.
+ * Folds path outcomes into the run's manifest object, in plan order: the same plan and outcomes
+ * always give the same manifest, however many workers ran them, in whatever order they finished.
+ *
+ * A state or transition is `passed` when a path reached it, `flaky` when only a flaky path did,
+ * `failed` when any failure touched it (a failed check fails its state), else `not-reached`. Reaching a
+ * state also marks its ancestors reached. The whole manifest is scanned for privacy findings, and any
+ * finding sets `privacy.passed` to false. Reads the chart files (for `specVersion`) and runs `git`
+ * in the current directory (for `commit` and `branch`, `null` when that fails). Apart from the
+ * wall-clock fields (`finishedAt`, `updatedAt`, `durationMs`) and those that depend on the working
+ * directory (`commit`, `branch`, `specDirectory`), two folds of the same outcomes are identical.
+ *
+ * @param outcomes finished or in-progress outcomes by path key; a path with none is `queued` or `running`.
+ * @param run.activePaths ids of the paths in flight; they are reported `running` and not counted complete.
+ * @param run.extra extra fields merged into `run` of the manifest (workers, shard, reused, mergedFrom).
  */
 export function buildManifest(context, paths, outcomes, run) {
     const { implementation: impl, graph, scope } = context;
@@ -406,7 +438,11 @@ function writeAtomic(file, text) {
     writeFileSync(temporary, text);
     renameSync(temporary, file);
 }
-/** Write a run's manifest, reports and outcomes; returns the manifest. */
+/**
+ * Writes a run's `junit.xml`, `ctrf.json`, `chart.mmd`, `outcomes.json` and `manifest.json` into
+ * `runDir` (each through a temporary file and a rename, so a reader never sees half a file) and returns
+ * the manifest. `outcomes.json` holds only finished paths, not those in `run.activePaths`.
+ */
 export function writeRun(runDir, context, paths, outcomes, run) {
     const manifest = buildManifest(context, paths, outcomes, run);
     writeAtomic(path.join(runDir, 'junit.xml'), toJUnit(manifest));
@@ -419,9 +455,14 @@ export function writeRun(runDir, context, paths, outcomes, run) {
 }
 const newRunId = (mode) => `${new Date().toISOString().replace(/[:.]/g, '-')}-${mode}`;
 /**
- * Compose the outcomes of several runs of the same plan (the shards of one run, or a rerun of the
- * paths that failed) into one run, folded in plan order. Media are copied in, so the merged run
- * stands on its own. Later runs win when two ran the same path.
+ * Composes the outcomes of several runs of the same plan (the shards of one run, or a rerun and
+ * the run before it) into one new run directory under `options.outputRoot`, folded in plan order. Media are
+ * copied in, so the merged run stands on its own. Later entries of `runDirs` win when two ran the same
+ * path; outcomes whose key is not in `paths` are ignored. The merged run's mode and driver name are
+ * taken from the run manifests unless `options` gives them.
+ *
+ * @returns the new `runDir`, its `manifest`, and `ok` (privacy passed and no path failed).
+ * @throws Error when a run directory has no `outcomes.json`.
  */
 export function mergeRuns(context, paths, runDirs, options) {
     const outcomes = new Map();
@@ -461,12 +502,22 @@ export function mergeRuns(context, paths, runDirs, options) {
     return { runDir, manifest, ok: manifest.privacy.passed && manifest.paths.every((r) => r.status !== 'failed') };
 }
 /**
- * Run planned paths against a system through a driver. Paths start from their seed (or the
- * implementation's `setup`) and run on a pool of workers, longest first, each attempt in its own
- * driver context; every state is recognised from the outside after every step; a failed path is
- * retried once to tell flaky from broken. The manifest is rewritten as each path finishes, from
- * all outcomes so far in plan order, so a crash keeps what ran and the order paths finished in
- * never changes the report.
+ * Runs planned paths against a system through a driver and writes the run to
+ * `<outputRoot>/<timestamp>-<mode>/`. Paths start from their seed (or the implementation's
+ * `setup`) and run on a pool of workers, longest first (by earlier timings, else `estimateMs`),
+ * each attempt in its own driver context; every state is recognised from the outside after every step;
+ * a failed path is retried once to tell flaky from broken. The manifest is rewritten as each path
+ * finishes, from all outcomes so far in plan order, so a crash keeps what ran and the order paths
+ * finished in never changes the report.
+ *
+ * Workers are capped by `driver.concurrency` (1 if the driver gives none) and by the number of paths.
+ * Without `implementation.correlate`, a run on several workers reports business events as "no
+ * signal" rather than guess which attempt they belong to. While it runs it installs
+ * `uncaughtException` and `unhandledRejection` handlers that log and swallow stray errors from
+ * drivers, and removes them when it ends. Passed paths of `options.reuse` are kept instead of re-run.
+ *
+ * @returns the run directory, the final manifest, and `ok` (privacy passed and no path failed).
+ * @see docs/statecharts.md
  */
 export async function runPaths(options) {
     const { driver, implementation: impl, graph, scope } = options;