@crvouga/atlas 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,67 @@
+import type { Driver } from '../../core/src/index.js';
+import type { DomProbeResult, Signal, SignalContext } from '../../core/src/signals.js';
+/** The parts of `Bun.WebView` the driver uses, typed structurally so it builds without Bun's types. */
+export type BunWebView = {
+    readonly url: string;
+    navigate(url: string): Promise<void>;
+    reload(): Promise<void>;
+    evaluate(script: string): Promise<unknown>;
+    screenshot(options?: {
+        format?: 'png' | 'jpeg' | 'webp';
+        quality?: number;
+        encoding?: 'buffer';
+    }): Promise<Uint8Array>;
+    click(x: number, y: number): Promise<void>;
+    type(text: string): Promise<void>;
+    press(key: string, options?: {
+        modifiers?: string[];
+    }): Promise<void>;
+    resize(width: number, height: number): Promise<void>;
+    close(): void;
+};
+/** What every event and recogniser receives: the view, and paced user actions logged to the timeline. */
+export type WebViewContext = SignalContext & {
+    view: BunWebView;
+    baseUrl: string | undefined;
+    /** Navigate, relative to `baseUrl`. */
+    goto(url: string): Promise<void>;
+    /** Run a JavaScript expression in the page and return its JSON result. */
+    evaluate(script: string): Promise<unknown>;
+    /** Where a signal is on screen right now. */
+    find(signal: Signal, options?: {
+        scroll?: boolean;
+    }): Promise<DomProbeResult>;
+    user: {
+        tap(target: Signal, label: string): Promise<void>;
+        type(target: Signal, text: string, label: string): Promise<void>;
+        press(key: string, label?: string): Promise<void>;
+    };
+};
+export type BunWebViewDriverOptions = {
+    /** Where `goto` paths resolve; the implementation's setup decides where to open. */
+    baseUrl?: string | (() => string | Promise<string>);
+    /** Viewport in CSS pixels; a 390×844 phone by default. */
+    width?: number;
+    height?: number;
+    /** `webkit` (macOS default, the system WKWebView) or `chrome` (CDP; the default elsewhere). */
+    backend?: 'webkit' | 'chrome';
+    /** How long a tap waits for its target to show, in milliseconds (default 10 000). */
+    actionTimeoutMs?: number;
+    /** Showcase pacing, in milliseconds. */
+    pacing?: {
+        before: number;
+        after: number;
+    };
+    /** Views open at once (one per worker); 8 when omitted. */
+    concurrency?: number;
+};
+/**
+ * Drive a web app in Bun's built-in headless browser: the system WebKit on macOS (nothing to
+ * install), Chrome over CDP elsewhere. A view starts in milliseconds and screenshots take about
+ * ten, so it is the quickest way to run a chart against a real page. Clips are encoded from
+ * screenshots with FFmpeg. Needs the Bun runtime; there is no fake clock, so time events use the
+ * app's own controls.
+ */
+export declare function bunWebViewDriver(options?: BunWebViewDriverOptions): Driver<WebViewContext>;
+/** A state recognised from its signals in the page: every `all` visible and no `none` visible. */
+export declare const screen: (spec: import('../../core/src/signals.js').ScreenSpec<WebViewContext, Signal>) => import('../../core/src/index.js').StateImplementation<WebViewContext>;

package/dist/bun/src/driver.js

@@ -0,0 +1,90 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { recordFrames } from '../../core/src/index.js';
+import { DOM_PROBE, describeSignal, signatureScreen, toWire } from '../../core/src/signals.js';
+function webViewConstructor() {
+    const bun = globalThis.Bun;
+    if (!bun?.WebView) {
+        throw new Error('bunWebViewDriver needs the Bun runtime with Bun.WebView: run atlas with `bun --bun atlas run` (or `bunx --bun atlas run`)');
+    }
+    return bun.WebView;
+}
+function contextFor(view, baseUrl, timeline, options) {
+    const timeoutMs = options.actionTimeoutMs ?? 10_000;
+    const find = async (signal, { scroll = false } = {}) => (await view.evaluate(`(${DOM_PROBE})(${JSON.stringify(toWire(signal))}, ${scroll})`));
+    const waitFor = async (signal) => {
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            const found = await find(signal, { scroll: true });
+            if (found.visible && found.x !== undefined && found.y !== undefined)
+                return { x: found.x, y: found.y };
+            if (Date.now() > deadline)
+                throw new Error(`${describeSignal(signal)} is not on screen`);
+            await new Promise((r) => setTimeout(r, 100));
+        }
+    };
+    const ctx = {
+        view,
+        baseUrl,
+        goto: (url) => view.navigate(baseUrl ? new URL(url, baseUrl).href : url),
+        evaluate: (script) => view.evaluate(script),
+        find,
+        isVisible: async (signal) => (await find(signal)).visible,
+        user: {
+            async tap(target, label) {
+                const { x, y } = await waitFor(target);
+                timeline.add({ kind: 'tap', label, x, y });
+                await view.click(x, y);
+            },
+            async type(target, text, label) {
+                const { x, y } = await waitFor(target);
+                timeline.add({ kind: 'type', label, text, x, y });
+                await view.click(x, y);
+                await view.type(text);
+            },
+            async press(key, label) {
+                timeline.add({ kind: 'tap', label: label ?? key });
+                await view.press(key);
+            }
+        }
+    };
+    return ctx;
+}
+/**
+ * Drive a web app in Bun's built-in headless browser: the system WebKit on macOS (nothing to
+ * install), Chrome over CDP elsewhere. A view starts in milliseconds and screenshots take about
+ * ten, so it is the quickest way to run a chart against a real page. Clips are encoded from
+ * screenshots with FFmpeg. Needs the Bun runtime; there is no fake clock, so time events use the
+ * app's own controls.
+ */
+export function bunWebViewDriver(options = {}) {
+    const width = options.width ?? 390;
+    const height = options.height ?? 844;
+    return {
+        name: 'bun-webview',
+        pacing: options.pacing ?? { before: 400, after: 900 },
+        concurrency: options.concurrency ?? 8,
+        async open({ timeline }) {
+            const WebView = webViewConstructor();
+            const view = new WebView({ width, height, headless: true, ...(options.backend ? { backend: options.backend } : {}) });
+            const baseUrl = typeof options.baseUrl === 'function' ? await options.baseUrl() : options.baseUrl;
+            return contextFor(view, baseUrl, timeline, options);
+        },
+        async close(ctx) {
+            ctx.view.close();
+        },
+        async screenshot(ctx, file) {
+            const png = await ctx.view.screenshot({ format: 'png', encoding: 'buffer' });
+            mkdirSync(path.dirname(file), { recursive: true });
+            writeFileSync(file, png);
+            return { png: file };
+        },
+        async record(ctx, workDirectory) {
+            return recordFrames(() => ctx.view.screenshot({ format: 'jpeg', quality: 90, encoding: 'buffer' }), workDirectory, { extension: 'jpg' });
+        },
+        text: async (ctx) => String(await ctx.view.evaluate('document.body ? document.body.innerText : ""')),
+        hold: (_ctx, ms) => new Promise((r) => setTimeout(r, ms))
+    };
+}
+/** A state recognised from its signals in the page: every `all` visible and no `none` visible. */
+export const screen = signatureScreen((ctx, signal) => ctx.isVisible(signal), describeSignal);

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

@@ -0,0 +1,2 @@
+export { bunWebViewDriver, screen, type BunWebView, type BunWebViewDriverOptions, type WebViewContext } from './driver.js';
+export { css, label, role, testId, text, describeSignal, type Signal } from '../../core/src/signals.js';

package/dist/bun/src/index.js

@@ -0,0 +1,2 @@
+export { bunWebViewDriver, screen } from './driver.js';
+export { css, label, role, testId, text, describeSignal } from '../../core/src/signals.js';

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

@@ -0,0 +1 @@
+export declare function main(argv?: string[]): Promise<0 | 1 | 2>;

package/dist/core/src/cli.js

@@ -0,0 +1,177 @@
+import { writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { mergeConfigRuns, prepare, runConfig } from './config.js';
+import { lintBundle } from './lint.js';
+import { toMermaid } from './report/formats.js';
+import { toMarkdown } from './report/markdown.js';
+import { composeCharts } from './spec/compose.js';
+import { loadSpecDirectory } from './spec/load.js';
+import { machineToScxml } from './spec/scxml.js';
+const USAGE = `atlas — executable statecharts
+
+  atlas lint   [--config atlas.config.ts | --specs <dir>] [--require-implementations]
+  atlas plan   [--config atlas.config.ts] [--state <name>]
+  atlas run    [--config atlas.config.ts] [--mode fast|showcase] [--workers n] [--state <name>]
+               [--seed <name>]... [--paths id,id] [--shard i/n] [--rerun-failed | --reuse <run-dir>]
+               [--no-retry] [--output <dir>]
+  atlas merge  [--config atlas.config.ts] [--output <dir>] <run-dir> <run-dir>...
+  atlas export --specs <dir> --format scxml|mermaid|markdown|json [--out <file>]
+
+  --workers       path attempts that run at once (default: one per CPU, capped by the driver)
+  --seed          only paths that start from this seed ("start" for paths setup starts); repeatable
+  --shard 2/4     run the second quarter of the plan; merge the shards' runs afterwards
+  --rerun-failed  keep the newest run's passed paths and run only the rest
+`;
+const VALUE_FLAGS = ['config', 'specs', 'format', 'out', 'mode', 'paths', 'seed', 'output', 'workers', 'shard', 'reuse', 'state'];
+/** Arguments that are not flags or flag values. */
+function positionals(argv) {
+    const out = [];
+    for (let i = 1; i < argv.length; i++) {
+        const token = argv[i];
+        if (token.startsWith('--')) {
+            if (VALUE_FLAGS.includes(token.slice(2)))
+                i++;
+            continue;
+        }
+        out.push(token);
+    }
+    return out;
+}
+function parseShard(value) {
+    if (!value)
+        return undefined;
+    const m = value.match(/^(\d+)\/(\d+)$/);
+    if (!m)
+        throw new Error(`--shard takes i/n, like 2/4 (got "${value}")`);
+    return { index: Number(m[1]), count: Number(m[2]) };
+}
+function parseWorkers(value) {
+    if (value === undefined)
+        return undefined;
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 1)
+        throw new Error(`--workers takes a whole number of at least 1 (got "${value}")`);
+    return n;
+}
+function flag(argv, name) {
+    const i = argv.indexOf(`--${name}`);
+    return i >= 0 ? argv[i + 1] : undefined;
+}
+/** Every value of a flag that may be given more than once. */
+function flags(argv, name) {
+    return argv.flatMap((token, i) => (token === `--${name}` && argv[i + 1] !== undefined ? [argv[i + 1]] : []));
+}
+async function loadConfig(file) {
+    const absolute = path.resolve(file);
+    const mod = (await import(pathToFileURL(absolute).href));
+    if (!mod.default)
+        throw new Error(`${file} has no default export (use defineConfig)`);
+    return { config: mod.default, base: path.dirname(absolute) };
+}
+export async function main(argv = process.argv.slice(2)) {
+    const [command] = argv;
+    const configFile = flag(argv, 'config') ?? 'atlas.config.ts';
+    const specs = flag(argv, 'specs');
+    const output = flag(argv, 'output');
+    const state = flag(argv, 'state');
+    if (command === 'export') {
+        if (!specs)
+            throw new Error('export needs --specs <dir>');
+        const bundle = loadSpecDirectory(path.resolve(specs));
+        const composition = composeCharts(bundle);
+        const format = flag(argv, 'format') ?? 'scxml';
+        const exporters = {
+            scxml: () => machineToScxml(composition.machine),
+            mermaid: () => toMermaid(composition.machine),
+            markdown: () => toMarkdown(composition.machine, bundle.journeys),
+            json: () => `${JSON.stringify(composition.machine, null, 2)}\n`
+        };
+        const exporter = exporters[format];
+        if (!exporter)
+            throw new Error(`export --format takes ${Object.keys(exporters).join('|')} (got "${format}")`);
+        const text = exporter();
+        const out = flag(argv, 'out');
+        if (out)
+            writeFileSync(out, text);
+        else
+            process.stdout.write(text);
+        return 0;
+    }
+    if (command === 'lint' && specs) {
+        const { findings } = lintBundle(loadSpecDirectory(path.resolve(specs)));
+        for (const f of findings)
+            process.stdout.write(`✗ [${f.rule}] ${f.message}\n`);
+        process.stdout.write(`${findings.length} problem(s)\n`);
+        return findings.length ? 1 : 0;
+    }
+    if (command === 'merge') {
+        const { config, base } = await loadConfig(configFile);
+        const dirs = positionals(argv);
+        if (dirs.length < 1)
+            throw new Error('merge needs the run directories to compose');
+        const { runDir, manifest, ok } = mergeConfigRuns(config, dirs, { ...(output === undefined ? {} : { output }), ...(state === undefined ? {} : { state }) }, base);
+        const c = manifest.coverage.overall;
+        process.stdout.write(`Merged ${dirs.length} run(s): transitions ${c.transitions.passed}/${c.transitions.total} passed, ${c.transitions.failed} failed\n`);
+        process.stdout.write(`Manifest: ${path.join(runDir, 'manifest.json')}\n`);
+        return ok ? 0 : 1;
+    }
+    if (command === 'lint' || command === 'plan' || command === 'run') {
+        const { config, base } = await loadConfig(configFile);
+        const prepared = prepare(config, base, state === undefined ? {} : { state });
+        const strict = argv.includes('--require-implementations');
+        const structural = prepared.lint.findings.filter((f) => f.rule !== 'implemented');
+        const missing = prepared.lint.findings.filter((f) => f.rule === 'implemented');
+        for (const f of structural)
+            process.stdout.write(`✗ [${f.rule}] ${f.message}\n`);
+        for (const f of missing)
+            process.stdout.write(`${strict ? '✗' : '·'} [${f.rule}] ${f.message}\n`);
+        process.stdout.write(`${structural.length} spec problem(s), ${missing.length} unimplemented\n`);
+        if (command === 'lint')
+            return structural.length || (strict && missing.length) ? 1 : 0;
+        if (command === 'plan') {
+            const { paths, journeys, seeds, unreachable } = prepared.plan;
+            for (const s of seeds)
+                process.stdout.write(`seed ${JSON.stringify(s.name)} at ${s.active.join(' > ')}${s.blocked ? `  [blocked: ${s.blocked}]` : ''}\n`);
+            for (const p of paths) {
+                const from = p.seed ? ` from "${p.seed}"` : '';
+                process.stdout.write(`${p.id.padEnd(14)} ${p.kind.padEnd(9)} ${String(p.steps.length).padStart(2)} steps  ${p.name}${from}${p.blockedBy.length ? `  [blocked: ${p.blockedBy.join('; ')}]` : ''}${p.skipRun ? ' (reported, not run)' : ''}\n`);
+            }
+            for (const j of journeys)
+                process.stdout.write(`journey ${JSON.stringify(j.name)} = ${j.paths.join(' + ')}\n`);
+            const runnable = paths.filter((p) => !p.skipRun);
+            const longest = Math.max(0, ...runnable.map((p) => p.steps.length));
+            const total = runnable.reduce((n, p) => n + p.steps.length, 0);
+            process.stdout.write(`${paths.length} paths (${runnable.length} run, ${total} steps, the longest ${longest}); ${unreachable.length} transitions left uncovered\n`);
+            return 0;
+        }
+        if (structural.length)
+            return 1;
+        const paths = flag(argv, 'paths')?.split(',');
+        const seeds = flags(argv, 'seed');
+        const workers = parseWorkers(flag(argv, 'workers'));
+        const shard = parseShard(flag(argv, 'shard'));
+        const reuse = argv.includes('--rerun-failed') ? 'latest' : flag(argv, 'reuse');
+        const { runDir, manifest, ok } = await runConfig(config, {
+            mode: (flag(argv, 'mode') ?? 'fast'),
+            ...(paths === undefined ? {} : { paths }),
+            ...(seeds.length ? { seeds } : {}),
+            ...(state === undefined ? {} : { state }),
+            retry: !argv.includes('--no-retry'),
+            ...(output === undefined ? {} : { output }),
+            ...(workers === undefined ? {} : { workers }),
+            ...(shard === undefined ? {} : { shard }),
+            ...(reuse === undefined ? {} : { reuse })
+        }, base);
+        const c = manifest.coverage.overall;
+        process.stdout.write(`\nStates ${c.states.passed}/${c.states.total} passed, ${c.states.failed} failed, ${c.states.notReached} not reached\n`);
+        process.stdout.write(`Transitions ${c.transitions.passed}/${c.transitions.total} passed, ${c.transitions.failed} failed, ${c.transitions.notReached} not reached\n`);
+        const j = manifest.journeys;
+        if (j.length)
+            process.stdout.write(`Journeys ${j.filter((x) => x.status === 'passed').length}/${j.length} passed, ${j.filter((x) => x.status === 'failed').length} failed\n`);
+        process.stdout.write(`Manifest: ${path.join(runDir, 'manifest.json')}\n`);
+        return ok ? 0 : 1;
+    }
+    process.stdout.write(USAGE);
+    return command && command !== '--help' && command !== '-h' ? 2 : 0;
+}