@crvouga/atlas 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,152 @@
+import { closeSync, openSync, readSync, statSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { randomUUID } from 'node:crypto';
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let body = '';
+        req.setEncoding('utf8');
+        req.on('data', (chunk) => (body += chunk));
+        req.on('end', () => resolve(body));
+        req.on('error', reject);
+    });
+}
+/** Parse an HTTP delivery in either CloudEvents content mode (structured, binary or batch). */
+export function cloudEventsFromHttp(headers, body) {
+    const header = (name) => {
+        const value = headers[name];
+        return Array.isArray(value) ? value[0] : value;
+    };
+    const contentType = header('content-type') ?? '';
+    if (contentType.startsWith('application/cloudevents-batch+json'))
+        return JSON.parse(body);
+    if (contentType.startsWith('application/cloudevents+json'))
+        return [JSON.parse(body)];
+    const type = header('ce-type');
+    if (!type)
+        return [];
+    const time = header('ce-time');
+    const subject = header('ce-subject');
+    const extensions = Object.fromEntries(Object.entries(headers)
+        .filter(([k]) => k.startsWith('ce-') && !['ce-specversion', 'ce-id', 'ce-source', 'ce-type', 'ce-time', 'ce-subject'].includes(k))
+        .map(([k, v]) => [k.slice(3), Array.isArray(v) ? v[0] : v]));
+    let data = body;
+    if (contentType.includes('json') && body) {
+        try {
+            data = JSON.parse(body);
+        }
+        catch {
+            data = body;
+        }
+    }
+    return [
+        {
+            ...extensions,
+            specversion: '1.0',
+            id: header('ce-id') ?? randomUUID(),
+            source: header('ce-source') ?? 'unknown',
+            type,
+            ...(time ? { time } : {}),
+            ...(subject ? { subject } : {}),
+            ...(contentType ? { datacontenttype: contentType } : {}),
+            data
+        }
+    ];
+}
+/**
+ * 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.
+ */
+export async function cloudEventsHttpSource(options = {}) {
+    const received = [];
+    const server = createServer(async (req, res) => {
+        try {
+            const events = cloudEventsFromHttp(req.headers, await readBody(req));
+            received.push(...events);
+            res.writeHead(202).end();
+        }
+        catch {
+            res.writeHead(400).end();
+        }
+    });
+    await new Promise((resolve) => server.listen(options.port ?? 0, options.host ?? '127.0.0.1', resolve));
+    const address = server.address();
+    const port = typeof address === 'object' && address ? address.port : options.port;
+    return {
+        name: 'cloudevents-http',
+        url: `http://${options.host ?? '127.0.0.1'}:${port}/`,
+        mark: () => received.length,
+        collect: async (from) => ({ events: received.slice(typeof from === 'number' ? from : 0) }),
+        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. */
+export function logFileSource(file, options = {}) {
+    return {
+        name: `log:${file}`,
+        mark: () => {
+            try {
+                return statSync(file).size;
+            }
+            catch {
+                return 0;
+            }
+        },
+        collect: async (from) => {
+            await new Promise((r) => setTimeout(r, options.settleMs ?? 1_000));
+            const offset = typeof from === 'number' ? from : 0;
+            try {
+                const size = statSync(file).size;
+                const length = Math.max(0, size - offset);
+                const buffer = Buffer.alloc(length);
+                const fd = openSync(file, 'r');
+                readSync(fd, buffer, 0, length, offset);
+                closeSync(fd);
+                return { events: [], text: buffer.toString('utf8') };
+            }
+            catch {
+                return { events: [], text: '' };
+            }
+        }
+    };
+}
+/**
+ * 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.
+ */
+export function correlated(collected, ids) {
+    const wanted = ids.filter(Boolean);
+    if (!wanted.length)
+        return collected;
+    const mentions = (value) => wanted.some((id) => value.includes(id));
+    return {
+        events: collected.events.filter((e) => mentions(JSON.stringify(e))),
+        text: collected.text.split('\n').filter(mentions).join('\n')
+    };
+}
+/**
+ * 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".
+ */
+export function compareBusinessEvents(expected, collected, matchers, hasCloudEvents) {
+    const result = { expected, observed: [], missing: [], noSignal: [], events: collected.events };
+    for (const name of expected) {
+        const matcher = matchers[name];
+        let seen;
+        if (typeof matcher === 'function')
+            seen = matcher(collected.events, collected.text);
+        else if (matcher && 'type' in matcher)
+            seen = collected.events.some((e) => e.type === matcher.type);
+        else if (matcher && 'pattern' in matcher)
+            seen = matcher.pattern.test(collected.text);
+        else
+            seen = hasCloudEvents ? collected.events.some((e) => e.type === name) : null;
+        if (seen === null)
+            result.noSignal.push(name);
+        else if (seen)
+            result.observed.push(name);
+        else
+            result.missing.push(name);
+    }
+    return result;
+}

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

@@ -0,0 +1,113 @@
+import type { HandOff } from './spec/compose.js';
+import type { MachineConfig, StateConfig } from './spec/types.js';
+export type StateValue = string | {
+    [key: string]: StateValue;
+};
+export type Step = {
+    event: string;
+    transitions: string[];
+    handOff: boolean;
+};
+export type Config = {
+    value: StateValue;
+    active: string[];
+};
+/** A configuration's identity: its state value with keys sorted, so equal configurations compare equal. */
+export declare function configKey(value: StateValue): string;
+export declare function activeKeys(value: StateValue): string[];
+/**
+ * A pure simulator over a composed machine: XState computes the next configuration, and this
+ * names which transitions fired, so coverage and the report can talk about transitions.
+ */
+export declare class ChartGraph {
+    readonly config: MachineConfig;
+    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;
+    readonly handOffStates: Map<string, string>;
+    constructor(config: MachineConfig, handOffs?: HandOff[]);
+    node(name: string): StateConfig | undefined;
+    /** The state a transition leads to, by name. */
+    target(source: string, event: string): string | undefined;
+    isLeaf(name: string): boolean;
+    parent(name: string): string | null;
+    stateNames(): string[];
+    /** The parallel regions a state sits in, outermost first: each the child of a parallel ancestor. */
+    regionsOf(state: string): string[];
+    /**
+     * Whether an event can matter to what happens in `regions`: some state that handles it sits in
+     * those regions or outside them (never only in a sibling region). Regions of a statechart
+     * without guards are independent, so exploring one region with the others held still loses
+     * nothing and keeps the search from multiplying across regions.
+     */
+    actsIn(event: string, regions: string[]): boolean;
+    /** Every distinct set of regions a state sits in, the empty set (outside every parallel) first. */
+    regionSets(): string[][];
+    initial(): Config;
+    /** The state value that names `state`: its ancestors down to it, defaults filled in by `resolve`. */
+    valueOf(state: string): StateValue;
+    resolve(value: StateValue): Config;
+    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;
+    step(config: Config, event: string): {
+        config: Config;
+        fired: string[];
+    } | null;
+    /** Hand-off states active in `config` (a child's former final states), with the event each passes on. */
+    pendingHandOffs(config: Config): {
+        state: string;
+        event: string;
+    }[];
+    /**
+     * Replay member- and system-sent events, inserting hand-off events whenever a hand-off state
+     * becomes active, as the composed spec says the parent receives them automatically.
+     */
+    replay(start: Config, events: readonly string[]): {
+        ok: false;
+        steps: (Step & {
+            from: Config;
+            to: Config;
+        })[];
+        config: Config;
+        failedAt: string;
+    } | {
+        ok: true;
+        steps: (Step & {
+            from: Config;
+            to: Config;
+        })[];
+        config: Config;
+        failedAt?: undefined;
+    };
+    /**
+     * Breadth-first from one or several starts at once: every configuration reachable using only
+     * `allowed` events, each with the shortest event path from its nearest start (`origin` is that
+     * start's index; ties go to the earlier start). `firstFired` holds, for every transition, the
+     * shortest way to take it: the configuration it fires from and how that configuration was
+     * reached. Exploration order is fixed by the chart, so the result is deterministic.
+     */
+    explore(start: Config | Config[], allowed: (event: string) => boolean, maxConfigs?: number): {
+        seen: Map<string, {
+            config: Config;
+            path: string[];
+            origin: number;
+        }>;
+        edges: {
+            from: string;
+            event: string;
+            to: string;
+            fired: string[];
+        }[];
+        key: (c: Config) => string;
+        firstFired: Map<string, {
+            from: {
+                config: Config;
+                path: string[];
+                origin: number;
+            };
+            event: string;
+        }>;
+    };
+}

package/dist/core/src/graph.js

@@ -0,0 +1,221 @@
+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. */
+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));
+}
+export function activeKeys(value) {
+    if (typeof value === 'string')
+        return [value];
+    return Object.entries(value).flatMap(([key, child]) => [key, ...activeKeys(child)]);
+}
+/**
+ * A pure simulator over a composed machine: XState computes the next configuration, and this
+ * names which transitions fired, so coverage and the report can talk about transitions.
+ */
+export class ChartGraph {
+    config;
+    machine;
+    nodes = new Map();
+    parentOf = new Map();
+    handOffStates;
+    constructor(config, handOffs = []) {
+        this.config = config;
+        this.machine = createMachine(config);
+        for (const { name, node, trail } of walkStates(config)) {
+            this.nodes.set(name, node);
+            this.parentOf.set(name, trail.at(-1) ?? null);
+        }
+        this.handOffStates = new Map(handOffs.map((h) => [h.finalState, h.event]));
+    }
+    node(name) {
+        return this.nodes.get(name);
+    }
+    /** The state a transition leads to, by name. */
+    target(source, event) {
+        return targetOf(this.nodes.get(source)?.on?.[event]);
+    }
+    isLeaf(name) {
+        return !this.nodes.get(name)?.states;
+    }
+    parent(name) {
+        return this.parentOf.get(name) ?? null;
+    }
+    stateNames() {
+        return [...this.nodes.keys()];
+    }
+    /** The parallel regions a state sits in, outermost first: each the child of a parallel ancestor. */
+    regionsOf(state) {
+        const regions = [];
+        for (let child = state, parent = this.parent(state); parent; child = parent, parent = this.parent(parent)) {
+            if (this.nodes.get(parent)?.type === 'parallel')
+                regions.unshift(child);
+        }
+        return regions;
+    }
+    /**
+     * Whether an event can matter to what happens in `regions`: some state that handles it sits in
+     * those regions or outside them (never only in a sibling region). Regions of a statechart
+     * without guards are independent, so exploring one region with the others held still loses
+     * nothing and keeps the search from multiplying across regions.
+     */
+    actsIn(event, regions) {
+        let handled = false;
+        for (const [name, node] of this.nodes) {
+            if (!node.on?.[event])
+                continue;
+            handled = true;
+            const own = this.regionsOf(name);
+            if (own.every((region, i) => regions[i] === region))
+                return true;
+        }
+        return !handled;
+    }
+    /** Every distinct set of regions a state sits in, the empty set (outside every parallel) first. */
+    regionSets() {
+        const keyed = new Map([['', []]]);
+        for (const name of this.nodes.keys()) {
+            const regions = this.regionsOf(name);
+            keyed.set(regions.join('\u0000'), regions);
+        }
+        return [...keyed.values()];
+    }
+    initial() {
+        const [snapshot] = initialTransition(this.machine);
+        return {
+            value: snapshot.value,
+            active: activeKeys(snapshot.value)
+        };
+    }
+    /** The state value that names `state`: its ancestors down to it, defaults filled in by `resolve`. */
+    valueOf(state) {
+        if (!this.nodes.has(state))
+            throw new Error(`There is no state "${state}"`);
+        const trail = [];
+        for (let n = state; n; n = this.parent(n))
+            trail.unshift(n);
+        return trail.reduceRight((inner, name) => (inner === null ? name : { [name]: inner }), null);
+    }
+    resolve(value) {
+        const snapshot = this.machine.resolveState({ value });
+        return {
+            value: snapshot.value,
+            active: activeKeys(snapshot.value)
+        };
+    }
+    enabledEvents(config) {
+        const events = new Set();
+        for (const name of config.active) {
+            for (const event of Object.keys(this.nodes.get(name)?.on ?? {}))
+                events.add(event);
+        }
+        return [...events];
+    }
+    /** The transitions `event` fires from `config`: in each region, the deepest active state that handles it. */
+    firedBy(config, event) {
+        const candidates = config.active.filter((name) => this.nodes.get(name)?.on?.[event]);
+        const hasActiveDescendantCandidate = (name) => candidates.some((other) => other !== name && this.isDescendant(other, name));
+        return candidates
+            .filter((name) => !hasActiveDescendantCandidate(name))
+            .map((name) => transitionId(name, event));
+    }
+    isDescendant(name, ancestor) {
+        for (let p = this.parentOf.get(name); p; p = this.parentOf.get(p)) {
+            if (p === ancestor)
+                return true;
+        }
+        return false;
+    }
+    step(config, event) {
+        const fired = this.firedBy(config, event);
+        if (fired.length === 0)
+            return null;
+        const snapshot = this.machine.resolveState({ value: config.value });
+        const [next] = transition(this.machine, snapshot, { type: event });
+        const value = next.value;
+        return { config: { value, active: activeKeys(value) }, fired };
+    }
+    /** Hand-off states active in `config` (a child's former final states), with the event each passes on. */
+    pendingHandOffs(config) {
+        return config.active
+            .filter((name) => this.handOffStates.has(name))
+            .map((name) => ({ state: name, event: this.handOffStates.get(name) }));
+    }
+    /**
+     * Replay member- and system-sent events, inserting hand-off events whenever a hand-off state
+     * becomes active, as the composed spec says the parent receives them automatically.
+     */
+    replay(start, events) {
+        let config = start;
+        const steps = [];
+        const settle = () => {
+            for (;;) {
+                const pending = this.pendingHandOffs(config);
+                if (pending.length === 0)
+                    return;
+                const handOff = pending[0];
+                const next = this.step(config, handOff.event);
+                if (!next)
+                    return;
+                steps.push({
+                    event: handOff.event,
+                    transitions: next.fired,
+                    handOff: true,
+                    from: config,
+                    to: next.config
+                });
+                config = next.config;
+            }
+        };
+        for (const event of events) {
+            const next = this.step(config, event);
+            if (!next) {
+                return { ok: false, steps, config, failedAt: event };
+            }
+            steps.push({ event, transitions: next.fired, handOff: false, from: config, to: next.config });
+            config = next.config;
+            settle();
+        }
+        return { ok: true, steps, config };
+    }
+    /**
+     * Breadth-first from one or several starts at once: every configuration reachable using only
+     * `allowed` events, each with the shortest event path from its nearest start (`origin` is that
+     * start's index; ties go to the earlier start). `firstFired` holds, for every transition, the
+     * shortest way to take it: the configuration it fires from and how that configuration was
+     * reached. Exploration order is fixed by the chart, so the result is deterministic.
+     */
+    explore(start, allowed, maxConfigs = 20_000) {
+        const starts = Array.isArray(start) ? start : [start];
+        const key = (c) => configKey(c.value);
+        const seen = new Map();
+        const queue = [];
+        starts.forEach((config, origin) => {
+            if (seen.has(key(config)))
+                return;
+            seen.set(key(config), { config, path: [], origin });
+            queue.push(config);
+        });
+        const edges = [];
+        const firstFired = new Map();
+        for (let head = 0; head < queue.length && seen.size < maxConfigs; head++) {
+            const config = queue[head];
+            const here = seen.get(key(config));
+            for (const event of this.enabledEvents(config).filter(allowed)) {
+                const next = this.step(config, event);
+                if (!next)
+                    continue;
+                edges.push({ from: key(config), event, to: key(next.config), fired: next.fired });
+                for (const t of next.fired)
+                    if (!firstFired.has(t))
+                        firstFired.set(t, { from: here, event });
+                if (!seen.has(key(next.config))) {
+                    seen.set(key(next.config), { config: next.config, path: [...here.path, event], origin: here.origin });
+                    queue.push(next.config);
+                }
+            }
+        }
+        return { seen, edges, key, firstFired };
+    }
+}

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

@@ -0,0 +1,17 @@
+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';
+export { composeCharts, type Composition, type HandOff } from './spec/compose.js';
+export { ChartGraph, activeKeys, configKey, type Config, type StateValue } from './graph.js';
+export { lintBundle, type LintFinding, type LintOptions } from './lint.js';
+export { chartScope, pathKey, planChart, runnableSteps, type ChartScope, type PlannedJourney, type PlannedPath, type PlannedStep, type PlanOptions, type ScopeOptions, type SeedPoint } from './plan.js';
+export * from './run/types.js';
+export { buildManifest, durationHistory, estimateMs, latestRun, mergeRuns, readOutcomes, runPaths, shardPaths, writeRun, type Manifest, type PathOutcome, type PlannedSeed, type RunContext, type RunOptions, type Shard } from './run/execute.js';
+export { combineDrivers, combineImplementations, mergeImplementations, onClient, type CombineDriversOptions, type ImplementationPart } from './run/clients.js';
+export { recordFrames, type FrameRecorderOptions } from './run/frames.js';
+export { httpDriver, httpClient, type HttpClient, type HttpDriverOptions, type HttpRequestOptions, type HttpResponse } from './run/http.js';
+export { cloudEventsHttpSource, cloudEventsFromHttp, logFileSource, compareBusinessEvents, correlated, type CloudEvent, type BusinessEventResult } from './events/cloudevents.js';
+export { DEFAULT_PRIVACY, mergePrivacy, privacyFindings, assertAllowedTarget } from './privacy.js';
+export { toJUnit, toCtrf, toWebVtt, toMermaid } from './report/formats.js';
+export { toMarkdown } from './report/markdown.js';
+export { defineConfig, mergeConfigRuns, prepare, runConfig, type AtlasConfig, type PrepareOptions, type RunCommandOptions } from './config.js';

package/dist/core/src/index.js

@@ -0,0 +1,17 @@
+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';
+export { composeCharts } from './spec/compose.js';
+export { ChartGraph, activeKeys, configKey } from './graph.js';
+export { lintBundle } from './lint.js';
+export { chartScope, pathKey, planChart, runnableSteps } from './plan.js';
+export * from './run/types.js';
+export { buildManifest, durationHistory, estimateMs, latestRun, mergeRuns, readOutcomes, runPaths, shardPaths, writeRun } from './run/execute.js';
+export { combineDrivers, combineImplementations, mergeImplementations, onClient } from './run/clients.js';
+export { recordFrames } from './run/frames.js';
+export { httpDriver, httpClient } from './run/http.js';
+export { cloudEventsHttpSource, cloudEventsFromHttp, logFileSource, compareBusinessEvents, correlated } from './events/cloudevents.js';
+export { DEFAULT_PRIVACY, mergePrivacy, privacyFindings, assertAllowedTarget } from './privacy.js';
+export { toJUnit, toCtrf, toWebVtt, toMermaid } from './report/formats.js';
+export { toMarkdown } from './report/markdown.js';
+export { defineConfig, mergeConfigRuns, prepare, runConfig } from './config.js';

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

@@ -0,0 +1,53 @@
+import type { SpecBundle } from './spec/types.js';
+import { ChartGraph } from './graph.js';
+export type LintFinding = {
+    rule: string;
+    message: string;
+};
+export type LintOptions = {
+    /** Meta fields every state must carry; `description` by default. */
+    requiredMeta?: readonly string[];
+    /** Only these states and events need implementations (a chart being brought up). */
+    scope?: {
+        states: ReadonlySet<string>;
+        events: ReadonlySet<string>;
+    };
+    implementations?: {
+        events: ReadonlySet<string>;
+        states: ReadonlySet<string>;
+    };
+};
+/**
+ * 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.
+ */
+export declare function lintBundle(bundle: SpecBundle, options?: LintOptions): {
+    findings: LintFinding[];
+    composition: import('./index.js').Composition;
+    graph: ChartGraph;
+    journeys: {
+        journey: import('./index.js').Journey;
+        replay: {
+            ok: false;
+            steps: (import('./graph.js').Step & {
+                from: import('./graph.js').Config;
+                to: import('./graph.js').Config;
+            })[];
+            config: import('./graph.js').Config;
+            failedAt: string;
+        } | {
+            ok: true;
+            steps: (import('./graph.js').Step & {
+                from: import('./graph.js').Config;
+                to: import('./graph.js').Config;
+            })[];
+            config: import('./graph.js').Config;
+            failedAt?: undefined;
+        };
+    }[];
+    unimplemented: {
+        events: string[];
+        states: string[];
+    };
+};