@crvouga/atlas 0.3.0 → 0.5.0

package/dist/core/src/events/cloudevents.js

@@ -1,3 +1,15 @@
+/**
+ * @module Business event sources
+ *
+ * Where a run learns which business events actually happened: an HTTP endpoint that accepts
+ * CloudEvents (`cloudEventsHttpSource`), or the lines a log file gains (`logFileSource`), plus the pure
+ * functions that compare what a state expects (`meta.events`) with what was collected. Every source
+ * implements `EventSource`: `mark()` records a position before a step and `collect(mark)` returns only
+ * what arrived after it. An event with no way to be observed is reported as "no signal", never as
+ * missing, so absence of evidence is not read as failure.
+ *
+ * @see docs/statecharts.md
+ */
 import { closeSync, openSync, readSync, statSync } from 'node:fs';
 import { createServer } from 'node:http';
 import { randomUUID } from 'node:crypto';
@@ -10,7 +22,17 @@ function readBody(req) {
         req.on('error', reject);
     });
 }
-/** 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 function cloudEventsFromHttp(headers, body) {
     const header = (name) => {
         const value = headers[name];
@@ -53,8 +75,19 @@ export function cloudEventsFromHttp(headers, body) {
     ];
 }
 /**
- * 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 async function cloudEventsHttpSource(options = {}) {
     const received = [];
@@ -79,7 +112,18 @@ export async function cloudEventsHttpSource(options = {}) {
         close: () => new Promise((resolve) => server.close(() => resolve()))
     };
 }
-/** 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 function logFileSource(file, options = {}) {
     return {
         name: `log:${file}`,
@@ -110,8 +154,9 @@ export function logFileSource(file, options = {}) {
     };
 }
 /**
- * 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 function correlated(collected, ids) {
     const wanted = ids.filter(Boolean);
@@ -124,9 +169,15 @@ export function correlated(collected, ids) {
     };
 }
 /**
- * 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 function compareBusinessEvents(expected, collected, matchers, hasCloudEvents) {
     const result = { expected, observed: [], missing: [], noSignal: [], events: collected.events };

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

@@ -1,19 +1,26 @@
 import type { HandOff } from './spec/compose.js';
 import type { MachineConfig, StateConfig } from './spec/types.js';
+/** An XState state value: a leaf state's name, or an object mapping each active child to its own value (parallel regions have several keys). */
 export type StateValue = string | {
     [key: string]: StateValue;
 };
+/** One event taken during a replay. */
 export type Step = {
     event: string;
+    /** Ids of the transitions that fired (see `transitionId`). */
     transitions: string[];
+    /** True when the event was inserted automatically because a child chart's final state became active. */
     handOff: boolean;
 };
+/** A configuration of the chart: where it is right now. */
 export type Config = {
     value: StateValue;
+    /** Names of every active state, ancestors included (see `activeKeys`). */
     active: string[];
 };
 /** A configuration's identity: its state value with keys sorted, so equal configurations compare equal. */
 export declare function configKey(value: StateValue): string;
+/** Names of every state in a state value, each parent before its children. */
 export declare function activeKeys(value: StateValue): string[];
 /**
  * A pure simulator over a composed machine: XState computes the next configuration, and this
@@ -21,16 +28,26 @@ export declare function activeKeys(value: StateValue): string[];
  */
 export declare class ChartGraph {
     readonly config: MachineConfig;
+    /** The XState machine built from the composed config, used for transition semantics. */
     readonly machine: import("xstate").StateMachine<import("xstate").MachineContext, import("xstate").AnyEventObject, Record<string, import("xstate").AnyActorRef>, import("xstate").ProvidedActor, import("xstate").ParameterizedObject, import("xstate").ParameterizedObject, string, import("xstate").StateValue, string, unknown, {} | null | undefined, import("xstate").EventObject, import("xstate").MetaObject, any, import("xstate").MetaObject>;
     private readonly nodes;
     private readonly parentOf;
+    /** Hand-off state name to the event it passes to the parent chart. */
     readonly handOffStates: Map<string, string>;
+    /**
+     * @param config the composed machine (`composeCharts(bundle).machine`).
+     * @param handOffs the composition's hand-offs; without them `replay` inserts none.
+     */
     constructor(config: MachineConfig, handOffs?: HandOff[]);
+    /** The config of the state called `name`, or `undefined` when there is none. */
     node(name: string): StateConfig | undefined;
     /** The state a transition leads to, by name. */
     target(source: string, event: string): string | undefined;
+    /** Whether the state has no child states. */
     isLeaf(name: string): boolean;
+    /** The name of the enclosing state, or `null` for a top-level state (or an unknown name). */
     parent(name: string): string | null;
+    /** Every state name in the composed chart, parents before children. */
     stateNames(): string[];
     /** The parallel regions a state sits in, outermost first: each the child of a parallel ancestor. */
     regionsOf(state: string): string[];
@@ -43,14 +60,18 @@ export declare class ChartGraph {
     actsIn(event: string, regions: string[]): boolean;
     /** Every distinct set of regions a state sits in, the empty set (outside every parallel) first. */
     regionSets(): string[][];
+    /** The configuration the chart starts in. */
     initial(): Config;
     /** The state value that names `state`: its ancestors down to it, defaults filled in by `resolve`. */
     valueOf(state: string): StateValue;
+    /** Fills a partial state value in with each parent's initial child, returning a complete configuration. */
     resolve(value: StateValue): Config;
+    /** Names of the events some active state handles (a state's own or an ancestor's), without duplicates. Whether the event moves anything is for `step` to say. */
     enabledEvents(config: Config): string[];
     /** The transitions `event` fires from `config`: in each region, the deepest active state that handles it. */
     firedBy(config: Config, event: string): string[];
     private isDescendant;
+    /** Takes `event` from `config`: the next configuration and the transition ids that fired, or `null` when no active state handles the event. */
     step(config: Config, event: string): {
         config: Config;
         fired: string[];

package/dist/core/src/graph.js

@@ -1,3 +1,14 @@
+/**
+ * @module Chart graph simulator
+ *
+ * A pure, deterministic simulator over a composed machine (see `composeCharts`): given a
+ * configuration and an event it computes the next configuration and names the transitions that
+ * fired. The planner, linter and runner all use it to reason about a chart without running
+ * the product. It never executes guards or actions (the linter rejects charts that have them), and
+ * it identifies states by name alone, so names must be unique across the composed product.
+ *
+ * @see docs/statecharts.md
+ */
 import { createMachine, initialTransition, transition } from 'xstate';
 import { targetOf, transitionId, walkStates } from './spec/types.js';
 /** A configuration's identity: its state value with keys sorted, so equal configurations compare equal. */
@@ -5,6 +16,7 @@ export function configKey(value) {
     const canonical = (v) => typeof v === 'string' ? v : Object.fromEntries(Object.keys(v).sort().map((k) => [k, canonical(v[k])]));
     return JSON.stringify(canonical(value));
 }
+/** Names of every state in a state value, each parent before its children. */
 export function activeKeys(value) {
     if (typeof value === 'string')
         return [value];
@@ -16,10 +28,16 @@ export function activeKeys(value) {
  */
 export class ChartGraph {
     config;
+    /** The XState machine built from the composed config, used for transition semantics. */
     machine;
     nodes = new Map();
     parentOf = new Map();
+    /** Hand-off state name to the event it passes to the parent chart. */
     handOffStates;
+    /**
+     * @param config the composed machine (`composeCharts(bundle).machine`).
+     * @param handOffs the composition's hand-offs; without them `replay` inserts none.
+     */
     constructor(config, handOffs = []) {
         this.config = config;
         this.machine = createMachine(config);
@@ -29,6 +47,7 @@ export class ChartGraph {
         }
         this.handOffStates = new Map(handOffs.map((h) => [h.finalState, h.event]));
     }
+    /** The config of the state called `name`, or `undefined` when there is none. */
     node(name) {
         return this.nodes.get(name);
     }
@@ -36,12 +55,15 @@ export class ChartGraph {
     target(source, event) {
         return targetOf(this.nodes.get(source)?.on?.[event]);
     }
+    /** Whether the state has no child states. */
     isLeaf(name) {
         return !this.nodes.get(name)?.states;
     }
+    /** The name of the enclosing state, or `null` for a top-level state (or an unknown name). */
     parent(name) {
         return this.parentOf.get(name) ?? null;
     }
+    /** Every state name in the composed chart, parents before children. */
     stateNames() {
         return [...this.nodes.keys()];
     }
@@ -81,6 +103,7 @@ export class ChartGraph {
         }
         return [...keyed.values()];
     }
+    /** The configuration the chart starts in. */
     initial() {
         const [snapshot] = initialTransition(this.machine);
         return {
@@ -97,6 +120,7 @@ export class ChartGraph {
             trail.unshift(n);
         return trail.reduceRight((inner, name) => (inner === null ? name : { [name]: inner }), null);
     }
+    /** Fills a partial state value in with each parent's initial child, returning a complete configuration. */
     resolve(value) {
         const snapshot = this.machine.resolveState({ value });
         return {
@@ -104,6 +128,7 @@ export class ChartGraph {
             active: activeKeys(snapshot.value)
         };
     }
+    /** Names of the events some active state handles (a state's own or an ancestor's), without duplicates. Whether the event moves anything is for `step` to say. */
     enabledEvents(config) {
         const events = new Set();
         for (const name of config.active) {
@@ -127,6 +152,7 @@ export class ChartGraph {
         }
         return false;
     }
+    /** Takes `event` from `config`: the next configuration and the transition ids that fired, or `null` when no active state handles the event. */
     step(config, event) {
         const fired = this.firedBy(config, event);
         if (fired.length === 0)

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

@@ -1,3 +1,14 @@
+/**
+ * @module Atlas core
+ *
+ * The public entry point of `@crvouga/atlas`: define a config (`defineConfig`), then load, lint, plan
+ * and run executable statecharts against a real product through a driver, and write a manifest of the
+ * results. This file only re-exports, grouped by stage: spec (types, load, SCXML, composition), graph,
+ * lint, plan, run (drivers, implementations, execution), business events, privacy, report formats and
+ * config. It does no work at import time. Browser-safe parts are also available from `./spec`.
+ *
+ * @see docs/statecharts.md
+ */
 export * from './spec/types.js';
 export { parseChart, parseJourneys, loadSpecDirectory, bundleOf, childChartIds } from './spec/load.js';
 export { scxmlToMachine, machineToScxml, scxmlToken, ATLAS_NS } from './spec/scxml.js';

package/dist/core/src/index.js

@@ -1,3 +1,14 @@
+/**
+ * @module Atlas core
+ *
+ * The public entry point of `@crvouga/atlas`: define a config (`defineConfig`), then load, lint, plan
+ * and run executable statecharts against a real product through a driver, and write a manifest of the
+ * results. This file only re-exports, grouped by stage: spec (types, load, SCXML, composition), graph,
+ * lint, plan, run (drivers, implementations, execution), business events, privacy, report formats and
+ * config. It does no work at import time. Browser-safe parts are also available from `./spec`.
+ *
+ * @see docs/statecharts.md
+ */
 export * from './spec/types.js';
 export { parseChart, parseJourneys, loadSpecDirectory, bundleOf, childChartIds } from './spec/load.js';
 export { scxmlToMachine, machineToScxml, scxmlToken, ATLAS_NS } from './spec/scxml.js';

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

@@ -1,9 +1,25 @@
+/**
+ * @module Spec linter
+ *
+ * Decides whether a spec bundle is executable before anything runs: pure structure, reachable states,
+ * no silent dead ends, journeys that replay, and (optionally) an implementation for everything in scope.
+ * It reports problems as findings rather than throwing, except when the charts cannot be composed at
+ * all. The `rule` of a finding is a stable short name (`pure`, `naming`, `meta`, `reachable`,
+ * `dead-end`, `journey`, `implemented`). `runConfig` refuses to run when any finding other than
+ * `implemented` exists.
+ *
+ * @see docs/statecharts.md
+ */
 import type { SpecBundle } from './spec/types.js';
 import { ChartGraph } from './graph.js';
+/** One problem found by `lintBundle`. */
 export type LintFinding = {
+    /** Which check found it: `pure`, `naming`, `meta`, `reachable`, `dead-end`, `journey` or `implemented`. */
     rule: string;
+    /** A sentence for a person, naming the state, event or journey concerned. */
     message: string;
 };
+/** Options for `lintBundle`. */
 export type LintOptions = {
     /** Meta fields every state must carry; `description` by default. */
     requiredMeta?: readonly string[];
@@ -12,6 +28,7 @@ export type LintOptions = {
         states: ReadonlySet<string>;
         events: ReadonlySet<string>;
     };
+    /** The event and state names the implementation provides. When given, anything in scope without one is an `implemented` finding. */
     implementations?: {
         events: ReadonlySet<string>;
         states: ReadonlySet<string>;
@@ -21,6 +38,19 @@ export type LintOptions = {
  * Checks a spec bundle is executable: pure (no guards, actions, context or delays), every state
  * reachable, no dead ends without `meta.deadEnd`, every journey replays to its `endsIn` states, and
  * (when implementations are given) every event and state in scope has one.
+ *
+ * Findings are returned, never thrown. Each leaf state counts as having an exit when it or any
+ * ancestor handles an event; final states are exempt from the dead-end rule. `requiredMeta` applies
+ * to states, not to the chart's root. Only leaf states need recognisers.
+ *
+ * @returns `findings`; the `composition` and `graph` it built (reuse them rather than composing
+ *   again); each journey with its `replay`; and the names in `unimplemented`.
+ * @throws Error when the charts cannot be composed (a missing or cyclic child chart, a child final
+ *   with nowhere to go); the message lists the findings gathered so far.
+ *
+ * @example
+ * const { findings } = lintBundle(loadSpecDirectory('./specs'));
+ * if (findings.length) throw new Error(findings.map((f) => f.message).join('\n'));
  */
 export declare function lintBundle(bundle: SpecBundle, options?: LintOptions): {
     findings: LintFinding[];

package/dist/core/src/lint.js

@@ -59,6 +59,19 @@ function sanitized(bundle) {
  * Checks a spec bundle is executable: pure (no guards, actions, context or delays), every state
  * reachable, no dead ends without `meta.deadEnd`, every journey replays to its `endsIn` states, and
  * (when implementations are given) every event and state in scope has one.
+ *
+ * Findings are returned, never thrown. Each leaf state counts as having an exit when it or any
+ * ancestor handles an event; final states are exempt from the dead-end rule. `requiredMeta` applies
+ * to states, not to the chart's root. Only leaf states need recognisers.
+ *
+ * @returns `findings`; the `composition` and `graph` it built (reuse them rather than composing
+ *   again); each journey with its `replay`; and the names in `unimplemented`.
+ * @throws Error when the charts cannot be composed (a missing or cyclic child chart, a child final
+ *   with nowhere to go); the message lists the findings gathered so far.
+ *
+ * @example
+ * const { findings } = lintBundle(loadSpecDirectory('./specs'));
+ * if (findings.length) throw new Error(findings.map((f) => f.message).join('\n'));
  */
 export function lintBundle(bundle, options = {}) {
     const findings = [];

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

@@ -2,30 +2,43 @@ import type { Config, StateValue } from './graph.js';
 import type { ChartGraph } from './graph.js';
 import type { Composition } from './spec/compose.js';
 import type { SpecBundle } from './spec/types.js';
+/** The part of the composed product one run covers, as computed by `chartScope`. */
 export type ChartScope = {
+    /** The id of the chart being run. */
     chart: string;
     /** Set when the run covers one state of the chart and what is inside it. */
     state?: string;
     /** The configuration each generated path starts from. */
     start: StateValue;
+    /** A phrase describing the start for reports. */
     startLabel: string;
+    /** Names of the states in scope. */
     states: Set<string>;
+    /** Ids of the transitions in scope (see `transitionId`): the ones the run must cover. */
     transitions: Set<string>;
+    /** Names of the events of those transitions. */
     events: Set<string>;
     /** Transitions that enter the chart from outside it. */
     entries: Set<string>;
 };
+/** One event of a planned path, with the transitions it fires and the active states before and after. A hand-off step is inserted automatically and is not driven by the implementation's events. */
 export type PlannedStep = {
     event: string;
+    /** Ids of the transitions the event fires (see `transitionId`). */
     transitions: string[];
     handOff: boolean;
+    /** Names of the active states before the step. */
     from: string[];
+    /** Names of the active states after the step. */
     to: string[];
 };
+/** One sequence of events to run against the product from a start point. */
 export type PlannedPath = {
+    /** `journey-<n>` or `generated-<n>`, numbered in plan order. Stable for a given plan; use `key` to match across plans. */
     id: string;
     /** The same start and events give the same key on any machine and in any run. */
     key: string;
+    /** The journey's name, or `Covers: <state> → <event>` for a generated path. */
     name: string;
     kind: 'journey' | 'generated';
     description: string;
@@ -36,15 +49,18 @@ export type PlannedPath = {
     seed?: string;
     /** The journeys this stretch belongs to: a stretch several journeys share is run once. */
     journeys?: string[];
+    /** Why the path cannot fully run: `Start: <reason>` when its start cannot be set up, then the blocked events on it. Empty when it can run in full. */
     blockedBy: string[];
     /** A blocked path whose runnable part other paths already cover: reported, not run. */
     skipRun?: boolean;
 };
+/** What to narrow a run to; all fields are optional and combine in `chartScope`. */
 export type ScopeOptions = {
     /** The chart to run; the root chart (the whole product) when omitted. */
     chart?: string;
     /** Where generated paths start; the root's initial configuration when omitted. */
     start?: StateValue;
+    /** A phrase describing the start for reports; `The start of the chart` when omitted. */
     startLabel?: string;
     /** Only these events enter the chart from outside it; every entering transition when omitted. */
     entryEvents?: string[];
@@ -56,23 +72,32 @@ export type ScopeOptions = {
 };
 /**
  * The part of the composed product a run covers: every state of `chart`, the transitions that
- * enter it from outside, and the hand-offs back to its parent.
+ * enter it from outside, and the hand-offs back to its parent. With `options.state`, the scope is
+ * that state, everything inside it, and the transitions into and out of it.
+ *
+ * @throws Error when `options.state` names a state that does not exist.
  */
 export declare function chartScope(bundle: SpecBundle, composition: Composition, graph: ChartGraph, options?: ScopeOptions): ChartScope;
 /** A named seed: a configuration the implementation can put the system in directly. */
 export type SeedPoint = {
     name: string;
+    /** The configuration the seed produces, as a state name or a full state value. */
     at: StateValue;
+    /** The reason the seed cannot be used yet. A blocked seed starts no path. */
     blocked?: string;
+    /** Events this seed is a variant for: it starts only paths that take one of them, and they start only from it. */
     for?: string[];
+    /** The state the seed leaves on screen; in a parallel state it picks the region the first event must act in. */
     shows?: string;
 };
 /** A journey as the paths it is cut into, one per seeded stretch, in order. */
 export type PlannedJourney = {
     name: string;
     description: string;
+    /** Ids of the paths the journey is cut into, in order. */
     paths: string[];
 };
+/** Inputs to `planChart` that come from the implementation rather than the charts. */
 export type PlanOptions = {
     /** Events that cannot run yet; paths stop before them. */
     isBlocked?: (event: string) => boolean;
@@ -88,6 +113,10 @@ export type PlanOptions = {
 };
 /** The steps a path can actually run: everything before its first blocked event. */
 export declare function runnableSteps(steps: PlannedStep[], isBlocked: (event: string) => boolean): PlannedStep[];
+/**
+ * A 16-hex-character key for a path: a SHA-256 of its seed name, start configuration and event names.
+ * Identical on every machine and run; it is how reruns, merges and layers match a path across runs.
+ */
 export declare function pathKey(seed: string | undefined, start: Config, events: string[]): string;
 /**
  * Paths for one chart. Every path starts at a start point: the scope's start (through `setup`)
@@ -96,6 +125,15 @@ export declare function pathKey(seed: string | undefined, start: Config, events:
  * journeys become one path. Then the shortest extra path from the nearest start point is added
  * for every transition still uncovered, and extra paths that are a prefix of another path are
  * dropped. Everything is ordered by the chart and the journeys, so the plan is deterministic.
+ *
+ * Paths stop before blocked events. A path whose start cannot be set up gets a `Start:` entry in
+ * `blockedBy`, and a blocked path whose runnable steps add no coverage gets `skipRun`. The generated
+ * paths are searched first avoiding blocked events, then (for what remains) allowing them.
+ *
+ * @returns `paths` (journey paths first, then generated, with ids assigned), `unreachable` (ids of
+ *   in-scope transitions no startable path takes), `journeys` (the paths each journey is cut into),
+ *   and `seeds` (each seed's name and active states, with `blocked` when it cannot be seeded yet).
+ * @see docs/statecharts.md
  */
 export declare function planChart(bundle: SpecBundle, graph: ChartGraph, scope: ChartScope, options?: PlanOptions): {
     paths: PlannedPath[];

package/dist/core/src/plan.js

@@ -1,9 +1,23 @@
+/**
+ * @module Run planner
+ *
+ * Decides, from the charts alone, which paths a run executes: the curated journeys (cut at seeded
+ * configurations), plus the shortest generated path to every transition the journeys leave uncovered.
+ * It also computes the scope of a run (all of the product, one chart, or one state). Pure and
+ * deterministic: the same bundle, scope, seeds and blocked events give the same paths, ids and keys on
+ * any machine, which is what lets shards and reruns be composed. It never runs the product.
+ *
+ * @see docs/statecharts.md
+ */
 import { createHash } from 'node:crypto';
 import { configKey } from './graph.js';
 import { splitTransitionId, transitionId, walkStates } from './spec/types.js';
 /**
  * The part of the composed product a run covers: every state of `chart`, the transitions that
- * enter it from outside, and the hand-offs back to its parent.
+ * enter it from outside, and the hand-offs back to its parent. With `options.state`, the scope is
+ * that state, everything inside it, and the transitions into and out of it.
+ *
+ * @throws Error when `options.state` names a state that does not exist.
  */
 export function chartScope(bundle, composition, graph, options = {}) {
     const chart = options.chart ?? bundle.root;
@@ -105,6 +119,10 @@ export function runnableSteps(steps, isBlocked) {
     const stop = steps.findIndex((s) => isBlocked(s.event));
     return stop < 0 ? steps : steps.slice(0, stop);
 }
+/**
+ * A 16-hex-character key for a path: a SHA-256 of its seed name, start configuration and event names.
+ * Identical on every machine and run; it is how reruns, merges and layers match a path across runs.
+ */
 export function pathKey(seed, start, events) {
     return createHash('sha256')
         .update(JSON.stringify([seed ?? null, configKey(start.value), events]))
@@ -119,6 +137,15 @@ const leaves = (graph, active) => active.filter((n) => graph.isLeaf(n));
  * journeys become one path. Then the shortest extra path from the nearest start point is added
  * for every transition still uncovered, and extra paths that are a prefix of another path are
  * dropped. Everything is ordered by the chart and the journeys, so the plan is deterministic.
+ *
+ * Paths stop before blocked events. A path whose start cannot be set up gets a `Start:` entry in
+ * `blockedBy`, and a blocked path whose runnable steps add no coverage gets `skipRun`. The generated
+ * paths are searched first avoiding blocked events, then (for what remains) allowing them.
+ *
+ * @returns `paths` (journey paths first, then generated, with ids assigned), `unreachable` (ids of
+ *   in-scope transitions no startable path takes), `journeys` (the paths each journey is cut into),
+ *   and `seeds` (each seed's name and active states, with `blocked` when it cannot be seeded yet).
+ * @see docs/statecharts.md
  */
 export function planChart(bundle, graph, scope, options = {}) {
     const isBlocked = options.isBlocked ?? (() => false);

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

@@ -1,8 +1,35 @@
+/**
+ * @module Privacy scanning
+ *
+ * Keeps real personal data out of the media and manifests a run produces and shares: patterns for
+ * data that must never appear, an allow-list for synthetic emails, and an allow-list of hosts a run may
+ * target. Findings describe what matched without repeating it. These are pure functions of their input;
+ * the runner applies them to the text a driver reports after each step and to the finished manifest.
+ *
+ * @see docs/statecharts.md
+ */
 import type { PrivacyRules } from './run/types.js';
 /** Defaults that fit any product: no real-looking emails, SSNs or card numbers in media or manifests. */
 export declare const DEFAULT_PRIVACY: Required<PrivacyRules>;
+/**
+ * Combines a project's `PrivacyRules` with `DEFAULT_PRIVACY`: its `deny` and `allowEmails` are added
+ * to the defaults, while its `allowHosts`, when given, replaces the default hosts (so list loopback
+ * again if you still need it).
+ */
 export declare function mergePrivacy(rules?: PrivacyRules): Required<PrivacyRules>;
-/** What in `text` looks like real personal data, described without repeating it. */
+/**
+ * Scans `text` for real-looking personal data and returns one description per finding, each
+ * prefixed by `where` and never containing the matched text (an email is shortened to its first
+ * letter and domain). Flags emails not matching `rules.allowEmails` and anything matching a
+ * `rules.deny` pattern. Returns an empty array when the text is clean.
+ *
+ * @param rules the merged rules (`mergePrivacy`).
+ */
 export declare function privacyFindings(text: string, where: string, rules: Required<PrivacyRules>): string[];
-/** Refuse to run against anything but the allowed hosts (loopback by default). */
+/**
+ * Throws unless every URL's hostname is in `rules.allowHosts` (loopback by default), so a run
+ * cannot touch a real environment by accident.
+ *
+ * @throws Error naming the first refused host, or a `TypeError` for a URL that does not parse.
+ */
 export declare function assertAllowedTarget(urls: string[], rules: Required<PrivacyRules>): void;

package/dist/core/src/privacy.js

@@ -11,6 +11,11 @@ export const DEFAULT_PRIVACY = {
     allowEmails: [/@example\.(com|org|net)$/i, /\.(test|example|invalid|localhost|local)$/i],
     allowHosts: ['127.0.0.1', 'localhost', '::1', '[::1]']
 };
+/**
+ * Combines a project's `PrivacyRules` with `DEFAULT_PRIVACY`: its `deny` and `allowEmails` are added
+ * to the defaults, while its `allowHosts`, when given, replaces the default hosts (so list loopback
+ * again if you still need it).
+ */
 export function mergePrivacy(rules = {}) {
     return {
         deny: [...DEFAULT_PRIVACY.deny, ...(rules.deny ?? [])],
@@ -18,7 +23,14 @@ export function mergePrivacy(rules = {}) {
         allowHosts: rules.allowHosts ?? DEFAULT_PRIVACY.allowHosts
     };
 }
-/** What in `text` looks like real personal data, described without repeating it. */
+/**
+ * Scans `text` for real-looking personal data and returns one description per finding, each
+ * prefixed by `where` and never containing the matched text (an email is shortened to its first
+ * letter and domain). Flags emails not matching `rules.allowEmails` and anything matching a
+ * `rules.deny` pattern. Returns an empty array when the text is clean.
+ *
+ * @param rules the merged rules (`mergePrivacy`).
+ */
 export function privacyFindings(text, where, rules) {
     const findings = [];
     for (const email of text.match(EMAIL) ?? []) {
@@ -32,7 +44,12 @@ export function privacyFindings(text, where, rules) {
             findings.push(`${where}: something shaped like ${name}`);
     return findings;
 }
-/** Refuse to run against anything but the allowed hosts (loopback by default). */
+/**
+ * Throws unless every URL's hostname is in `rules.allowHosts` (loopback by default), so a run
+ * cannot touch a real environment by accident.
+ *
+ * @throws Error naming the first refused host, or a `TypeError` for a URL that does not parse.
+ */
 export function assertAllowedTarget(urls, rules) {
     for (const url of urls) {
         const host = new URL(url).hostname;