dungbeetle 0.1.1

package/dist/runner.js

@@ -0,0 +1,352 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { compareSnapshots } from "./compare.js";
+import { decodePng, renderDiffImage } from "./diff/pixel.js";
+import { stableStringify } from "./json.js";
+import { startManagedLifecycle } from "./lifecycle.js";
+import { baselinePathForTarget, MissingBaselineError, readBaseline, writeBaseline } from "./baselines.js";
+import { captureTarget } from "./capture.js";
+import { captureTypes } from "./captures/registry.js";
+import { canonicalizeSnapshot } from "./snapshot.js";
+export async function updateBaselines(options) {
+    return runSnapshots({
+        ...options,
+        mode: "update"
+    });
+}
+export async function testBaselines(options) {
+    return runSnapshots({
+        ...options,
+        mode: "test"
+    });
+}
+async function runSnapshots(options) {
+    const cwd = path.resolve(options.cwd ?? process.cwd());
+    const startedAt = new Date();
+    const lifecycle = [];
+    const results = [];
+    const managedLifecycle = await startManagedLifecycle(options.config.lifecycle, cwd);
+    lifecycle.push(...managedLifecycle.runs);
+    try {
+        const targets = filterTargets(options.config.lifecycle.capture, options.targets);
+        const ordered = new Array(targets.length);
+        const run = (target) => runTarget(target, options.config, cwd, options.mode, options.includeSnapshots ?? false);
+        // Capture in original order, but batch consecutive parallel-safe targets
+        // (web) into a bounded concurrent pool — their browser launches/fetches no
+        // longer serialize. Non-parallel-safe kinds (performance, terminal, desktop)
+        // are barriers: each runs alone so, e.g., a k6 measurement isn't skewed by a
+        // concurrent capture. Results are written by index, so the report order is
+        // unchanged regardless of completion order.
+        let i = 0;
+        while (i < targets.length) {
+            const target = targets[i];
+            if (captureTypes[target.kind].parallelSafe) {
+                const batch = [];
+                while (i < targets.length &&
+                    captureTypes[targets[i].kind].parallelSafe) {
+                    batch.push(i);
+                    i += 1;
+                }
+                await mapWithConcurrency(batch, CAPTURE_CONCURRENCY, async (index) => {
+                    ordered[index] = await run(targets[index]);
+                });
+            }
+            else {
+                ordered[i] = await run(target);
+                i += 1;
+            }
+        }
+        results.push(...ordered);
+    }
+    finally {
+        lifecycle.push(...(await managedLifecycle.stop()));
+    }
+    const lifecyclePassed = lifecycle.every((run) => {
+        return run.exitCode === 0 || (run.phase === "start" && run.exitCode === null);
+    });
+    const snapshotsPassed = results.length > 0 &&
+        results.every((result) => {
+            return options.mode === "update" ? result.status === "updated" : result.status === "passed";
+        });
+    return {
+        kind: "dungbeetle-run",
+        mode: options.mode,
+        passed: lifecyclePassed && snapshotsPassed,
+        project: options.config.project.name,
+        startedAt: startedAt.toISOString(),
+        finishedAt: new Date().toISOString(),
+        lifecycle,
+        results
+    };
+}
+async function runTarget(target, config, cwd, mode, includeSnapshots) {
+    const baselinePath = baselinePathForTarget(config.baselinesDir, target.name, cwd);
+    // Canonical candidate snapshot + screenshot, kept in scope so they can be
+    // attached even when the baseline is missing (so a reviewer can see the
+    // capture and promote it to a first version).
+    let candidateJson;
+    let candidateScreenshot;
+    let candidateScreenshots = {};
+    try {
+        const snapshot = await captureTarget(target, {
+            config,
+            cwd
+        });
+        const canonical = canonicalizeForBaseline(snapshot);
+        candidateJson = includeSnapshots ? stableStringify(canonical) : undefined;
+        candidateScreenshot = screenshotBuffer(snapshot);
+        candidateScreenshots = namedScreenshotBuffers(snapshot);
+        if (mode === "update") {
+            // Read the previous screenshot before overwriting so an update can still
+            // show before/after of the baseline we are replacing.
+            const previousScreenshot = await readScreenshotArtifact(baselinePath);
+            const previousScreenshots = await readNamedScreenshotArtifacts(baselinePath, Object.keys(candidateScreenshots));
+            await writeBaseline(baselinePath, canonical);
+            await writeScreenshotArtifact(baselinePath, snapshot);
+            await writeNamedScreenshotArtifacts(baselinePath, candidateScreenshots);
+            const result = {
+                name: target.name,
+                kind: target.kind,
+                status: "updated",
+                baselinePath,
+                diff: "",
+                ...(candidateJson ? { snapshot: candidateJson } : {})
+            };
+            attachScreenshot(result, target, candidateScreenshot, previousScreenshot, config, {
+                includeDiff: Boolean(previousScreenshot)
+            });
+            attachNamedScreenshots(result, candidateScreenshots, previousScreenshots, config, {
+                includeDiff: true
+            });
+            return result;
+        }
+        const baseline = await readBaseline(baselinePath);
+        const baselineScreenshot = await readScreenshotArtifact(baselinePath);
+        const baselineScreenshots = await readNamedScreenshotArtifacts(baselinePath, unionMarkers(baseline, candidateScreenshots));
+        const comparison = compareSnapshots(baseline, canonical, {
+            comparison: config.comparison,
+            target,
+            baselineScreenshot,
+            candidateScreenshot,
+            baselineScreenshots,
+            candidateScreenshots
+        });
+        const status = comparison.equal ? "passed" : "failed";
+        const result = {
+            name: target.name,
+            kind: target.kind,
+            status,
+            baselinePath,
+            diff: comparison.rendered,
+            ...(comparison.pixel ? { pixel: comparison.pixel } : {}),
+            ...(candidateJson ? { snapshot: candidateJson } : {})
+        };
+        // Always surface before/after screenshots for web targets when we have them,
+        // so passing and failing runs both render the captured view. The red diff
+        // overlay is only meaningful — and only included — when the run failed.
+        attachScreenshot(result, target, candidateScreenshot, baselineScreenshot, config, {
+            includeDiff: status === "failed",
+            images: comparison.screenshotImages
+        });
+        attachNamedScreenshots(result, candidateScreenshots, baselineScreenshots, config, {
+            includeDiff: status === "failed",
+            imagesByMarker: comparison.screenshotImagesByMarker
+        });
+        return result;
+    }
+    catch (error) {
+        if (error instanceof MissingBaselineError) {
+            const result = {
+                name: target.name,
+                kind: target.kind,
+                status: "missing",
+                baselinePath,
+                diff: "",
+                ...(candidateJson ? { snapshot: candidateJson } : {}),
+                error: error.message
+            };
+            // No baseline to compare against, but we still captured the candidate —
+            // surface it so the report shows what the target looks like now.
+            attachScreenshot(result, target, candidateScreenshot, undefined, config, {
+                includeDiff: false
+            });
+            attachNamedScreenshots(result, candidateScreenshots, {}, config, {
+                includeDiff: false
+            });
+            return result;
+        }
+        return {
+            name: target.name,
+            kind: target.kind,
+            status: "error",
+            baselinePath,
+            diff: "",
+            error: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
+function canonicalizeForBaseline(snapshot) {
+    return canonicalizeSnapshot(snapshot);
+}
+// The baseline JSON only stores a screenshot digest, so write the actual PNG
+// next to the baseline (e.g. dungbeetle.snapshots/home.png) for human inspection
+// and to enable tolerant pixel comparison on later runs.
+async function writeScreenshotArtifact(baselinePath, snapshot) {
+    const buffer = screenshotBuffer(snapshot);
+    if (!buffer) {
+        return;
+    }
+    const pngPath = screenshotPathFor(baselinePath);
+    await mkdir(path.dirname(pngPath), { recursive: true });
+    await writeFile(pngPath, buffer);
+}
+async function readScreenshotArtifact(baselinePath) {
+    try {
+        return await readFile(screenshotPathFor(baselinePath));
+    }
+    catch {
+        return undefined;
+    }
+}
+// Named per-marker screenshots (game): the artifact carries a
+// `screenshots: {marker: {data}}` map; each marker's PNG is written alongside
+// the baseline as `<name>.<marker>.png`, mirroring web's single `<name>.png`.
+export function namedScreenshotBuffers(snapshot) {
+    const screenshots = snapshot.screenshots;
+    const buffers = {};
+    for (const [marker, shot] of Object.entries(screenshots ?? {})) {
+        if (typeof shot?.data === "string") {
+            buffers[marker] = Buffer.from(shot.data, "base64");
+        }
+    }
+    return buffers;
+}
+function markerScreenshotPathFor(baselinePath, marker) {
+    const base = baselinePath.endsWith(".json")
+        ? baselinePath.slice(0, -".json".length)
+        : baselinePath;
+    return `${base}.${marker}.png`;
+}
+async function writeNamedScreenshotArtifacts(baselinePath, buffers) {
+    for (const [marker, buffer] of Object.entries(buffers)) {
+        const pngPath = markerScreenshotPathFor(baselinePath, marker);
+        await mkdir(path.dirname(pngPath), { recursive: true });
+        await writeFile(pngPath, buffer);
+    }
+}
+async function readNamedScreenshotArtifacts(baselinePath, markers) {
+    const buffers = {};
+    for (const marker of markers) {
+        try {
+            buffers[marker] = await readFile(markerScreenshotPathFor(baselinePath, marker));
+        }
+        catch {
+            // No stored PNG for this marker — digest-only comparison still applies.
+        }
+    }
+    return buffers;
+}
+// Markers to read baseline PNGs for: whatever the candidate captured plus
+// whatever the canonical baseline says it had (so removals still render).
+function unionMarkers(baseline, candidateScreenshots) {
+    const markers = new Set(Object.keys(candidateScreenshots));
+    const stored = baseline?.screenshots;
+    if (stored && typeof stored === "object") {
+        for (const marker of Object.keys(stored)) {
+            markers.add(marker);
+        }
+    }
+    return [...markers];
+}
+function attachNamedScreenshots(result, candidates, baselines, config, options) {
+    const markers = new Set([...Object.keys(candidates), ...Object.keys(baselines)]);
+    const screenshots = {};
+    for (const marker of markers) {
+        const candidate = candidates[marker];
+        if (!candidate) {
+            // Marker removed: surface the baseline image alone so the report shows
+            // what disappeared.
+            const baseline = baselines[marker];
+            if (baseline) {
+                screenshots[marker] = { baseline: baseline.toString("base64") };
+            }
+            continue;
+        }
+        const baseline = baselines[marker];
+        const comparison = buildScreenshotComparison(baseline, candidate, config.comparison.pixelTolerance, 
+        // Unlike the single-screenshot path, only changed markers get a diff
+        // overlay — a failed game run shouldn't render red overlays for the
+        // markers that still match.
+        options.includeDiff && Boolean(baseline) && !baseline?.equals(candidate), options.imagesByMarker?.[marker]);
+        if (comparison) {
+            screenshots[marker] = comparison;
+        }
+    }
+    if (Object.keys(screenshots).length > 0) {
+        result.screenshots = screenshots;
+    }
+}
+// Attach a before/after (and optional diff) screenshot to a web result when a
+// candidate image is available, mutating the result in place.
+function attachScreenshot(result, target, candidate, baseline, config, options) {
+    if (!captureTypes[target.kind].hasScreenshots || !candidate) {
+        return;
+    }
+    const screenshot = buildScreenshotComparison(baseline, candidate, config.comparison.pixelTolerance, options.includeDiff, options.images);
+    if (screenshot) {
+        result.screenshot = screenshot;
+    }
+}
+export function buildScreenshotComparison(baseline, candidate, pixelTolerance, includeDiff, 
+// Decoded images reused from the comparison so the diff path decodes each PNG
+// once. Absent on the update/missing paths, which decode on demand here.
+images) {
+    const comparison = {
+        candidate: candidate.toString("base64")
+    };
+    if (baseline) {
+        comparison.baseline = baseline.toString("base64");
+        if (includeDiff) {
+            const before = images?.baseline ?? decodePng(baseline);
+            const after = images?.candidate ?? decodePng(candidate);
+            const diff = renderDiffImage(before, after, pixelTolerance);
+            if (diff) {
+                comparison.diff = diff.toString("base64");
+            }
+        }
+    }
+    return comparison;
+}
+export function screenshotBuffer(snapshot) {
+    const screenshot = snapshot.screenshot;
+    if (!screenshot || typeof screenshot.data !== "string") {
+        return undefined;
+    }
+    return Buffer.from(screenshot.data, "base64");
+}
+function screenshotPathFor(baselinePath) {
+    return baselinePath.replace(/\.json$/, ".png");
+}
+// Max parallel-safe captures in flight at once. Bounded so a suite with many web
+// targets doesn't launch an unbounded number of browsers or flood a dev server.
+const CAPTURE_CONCURRENCY = 4;
+// Run `fn` over `items` with at most `limit` in flight, awaiting all. `runTarget`
+// catches its own errors (returning an error result), so a worker never rejects.
+async function mapWithConcurrency(items, limit, fn) {
+    let cursor = 0;
+    const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        while (cursor < items.length) {
+            const index = cursor;
+            cursor += 1;
+            await fn(items[index]);
+        }
+    });
+    await Promise.all(workers);
+}
+function filterTargets(targets, selectedNames) {
+    if (!selectedNames || selectedNames.length === 0) {
+        return targets;
+    }
+    const selected = new Set(selectedNames);
+    return targets.filter((target) => selected.has(target.name));
+}

package/dist/snapshot.d.ts

@@ -0,0 +1,48 @@
+import type { CaptureTarget } from "./config.js";
+export type SnapshotKind = CaptureTarget["kind"];
+export type CanonicalTerminal = {
+    kind: "terminal";
+    exitCode?: number | null;
+    signal?: string | null;
+    stdout?: unknown;
+    stderr?: unknown;
+};
+export type CanonicalWeb = {
+    kind: "web";
+    root?: unknown;
+    driver?: unknown;
+    accessibility?: unknown;
+    screenshot?: unknown;
+};
+export type CanonicalPerformance = {
+    kind: "performance";
+    tool?: unknown;
+    metrics?: unknown;
+};
+export type CanonicalDesktop = {
+    kind: "desktop";
+    root?: unknown;
+    tool?: unknown;
+};
+export type CanonicalCheck = {
+    kind: "check";
+    tool?: unknown;
+    data?: unknown;
+};
+export type CanonicalApi = {
+    kind: "api";
+    status?: unknown;
+    headers?: unknown;
+    bodyType?: unknown;
+    body?: unknown;
+};
+export type CanonicalGame = {
+    kind: "game";
+    engine?: unknown;
+    markers?: unknown;
+    screenshots?: unknown;
+};
+export type CanonicalSnapshot = CanonicalApi | CanonicalCheck | CanonicalTerminal | CanonicalWeb | CanonicalPerformance | CanonicalDesktop | CanonicalGame;
+export declare function snapshotKind(value: unknown): SnapshotKind | undefined;
+export declare function canonicalizeSnapshot(value: unknown): unknown;
+export declare function canonicalizeRecord(value: Record<string, unknown>): unknown;

package/dist/snapshot.js

@@ -0,0 +1,37 @@
+import { captureTypes, isCaptureKind } from "./captures/registry.js";
+import { isRecord } from "./guards.js";
+// Single source of truth for "is this a tagged snapshot, and of which kind?".
+// Returns undefined for plain objects and unknown kinds (which fall back to the
+// generic structural comparison). The known-kind set is derived from the capture
+// registry.
+export function snapshotKind(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    return isCaptureKind(value.kind) ? value.kind : undefined;
+}
+export function canonicalizeSnapshot(value) {
+    if (Array.isArray(value)) {
+        return value.map(canonicalizeSnapshot);
+    }
+    if (!isRecord(value)) {
+        return value;
+    }
+    // Known capture kinds canonicalize through their registered handler; anything
+    // else (plain nested objects, unknown kinds) gets the generic record handling.
+    if (isCaptureKind(value.kind)) {
+        return captureTypes[value.kind].canonicalize(value);
+    }
+    return canonicalizeRecord(value);
+}
+// Generic record canonicalization: recurse into nested values and drop volatile
+// runtime metadata. Shared by the generic fallback above and by capture kinds
+// (e.g. performance) that have no dedicated canonical shape.
+export function canonicalizeRecord(value) {
+    return Object.fromEntries(Object.entries(value)
+        .filter(([key]) => !isRuntimeMetadataKey(key))
+        .map(([key, nested]) => [key, canonicalizeSnapshot(nested)]));
+}
+function isRuntimeMetadataKey(key) {
+    return key === "durationMs" || key === "cwd" || key === "source";
+}

package/dist/terminal/ansi.d.ts

@@ -0,0 +1,21 @@
+import type { MaskRule } from "../config.js";
+export type AnsiStyle = {
+    bold?: boolean;
+    dim?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    inverse?: boolean;
+    foreground?: string;
+    background?: string;
+};
+export type TerminalSegment = {
+    text: string;
+    style: AnsiStyle;
+};
+export type NormalizedTerminalStream = {
+    text: string;
+    segments: TerminalSegment[];
+};
+export declare function stripAnsi(value: string): string;
+export declare function stripControlChars(value: string): string;
+export declare function normalizeAnsiStream(value: string, maskRules?: MaskRule[]): NormalizedTerminalStream;

package/dist/terminal/ansi.js

@@ -0,0 +1,144 @@
+import { applyMaskRules, normalizeLineEndings } from "../normalization.js";
+const foregroundColors = new Map([
+    [30, "black"],
+    [31, "red"],
+    [32, "green"],
+    [33, "yellow"],
+    [34, "blue"],
+    [35, "magenta"],
+    [36, "cyan"],
+    [37, "white"],
+    [90, "bright-black"],
+    [91, "bright-red"],
+    [92, "bright-green"],
+    [93, "bright-yellow"],
+    [94, "bright-blue"],
+    [95, "bright-magenta"],
+    [96, "bright-cyan"],
+    [97, "bright-white"]
+]);
+const backgroundColors = new Map([
+    [40, "black"],
+    [41, "red"],
+    [42, "green"],
+    [43, "yellow"],
+    [44, "blue"],
+    [45, "magenta"],
+    [46, "cyan"],
+    [47, "white"],
+    [100, "bright-black"],
+    [101, "bright-red"],
+    [102, "bright-green"],
+    [103, "bright-yellow"],
+    [104, "bright-blue"],
+    [105, "bright-magenta"],
+    [106, "bright-cyan"],
+    [107, "bright-white"]
+]);
+export function stripAnsi(value) {
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: matching ANSI escape sequences requires the ESC (U+001B) control character.
+    return value.replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, "");
+}
+// Neutralize C0/C1 control characters (keeping tab and newline) before printing
+// content that originates from a stored baseline, a tool's output, or a server
+// response. Capture-time normalization only strips freshly captured streams;
+// content read back from disk or the network reaches the reviewer's terminal
+// verbatim, so raw escapes (CSI, OSC clipboard writes, title spoofing, CR line
+// overwrites that hide a regression) would otherwise pass straight through.
+export function stripControlChars(value) {
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: intentionally matching control chars to remove them.
+    return value.replace(/[\x00-\x08\x0B-\x1F\x7F-\x9F]/g, "");
+}
+export function normalizeAnsiStream(value, maskRules = []) {
+    const normalized = normalizeLineEndings(value);
+    const segments = [];
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: matching ANSI SGR sequences requires the ESC (U+001B) control character.
+    const ansiPattern = /\u001b\[([0-9;]*)m/g;
+    let style = {};
+    let cursor = 0;
+    let text = "";
+    let match = ansiPattern.exec(normalized);
+    while (match !== null) {
+        appendSegment(normalized.slice(cursor, match.index));
+        style = applySgrCodes(style, parseCodes(match[1] ?? ""));
+        cursor = match.index + match[0].length;
+        match = ansiPattern.exec(normalized);
+    }
+    appendSegment(normalized.slice(cursor));
+    return {
+        text: applyMaskRules(text, maskRules),
+        segments: segments.map((segment) => ({
+            ...segment,
+            text: applyMaskRules(segment.text, maskRules)
+        }))
+    };
+    function appendSegment(raw) {
+        if (!raw) {
+            return;
+        }
+        const stripped = stripAnsi(raw);
+        text += stripped;
+        segments.push({
+            text: stripped,
+            style: { ...style }
+        });
+    }
+}
+function parseCodes(raw) {
+    if (!raw) {
+        return [0];
+    }
+    return raw.split(";").map((code) => {
+        const parsed = Number.parseInt(code, 10);
+        return Number.isNaN(parsed) ? 0 : parsed;
+    });
+}
+function applySgrCodes(style, codes) {
+    let next = { ...style };
+    for (const code of codes) {
+        if (code === 0) {
+            next = {};
+        }
+        else if (code === 1) {
+            next.bold = true;
+        }
+        else if (code === 2) {
+            next.dim = true;
+        }
+        else if (code === 3) {
+            next.italic = true;
+        }
+        else if (code === 4) {
+            next.underline = true;
+        }
+        else if (code === 7) {
+            next.inverse = true;
+        }
+        else if (code === 22) {
+            delete next.bold;
+            delete next.dim;
+        }
+        else if (code === 23) {
+            delete next.italic;
+        }
+        else if (code === 24) {
+            delete next.underline;
+        }
+        else if (code === 27) {
+            delete next.inverse;
+        }
+        else if (code === 39) {
+            delete next.foreground;
+        }
+        else if (code === 49) {
+            delete next.background;
+        }
+        else if (foregroundColors.has(code)) {
+            next.foreground = foregroundColors.get(code);
+        }
+        else if (backgroundColors.has(code)) {
+            next.background = backgroundColors.get(code);
+        }
+    }
+    return next;
+}

package/dist/terminal/capture.d.ts

@@ -0,0 +1,30 @@
+import type { MaskRule } from "../config.js";
+import { type NormalizedTerminalStream } from "./ansi.js";
+export type TerminalCaptureOptions = {
+    command: string;
+    cwd?: string;
+    timeoutMs?: number;
+    maskRules?: MaskRule[];
+};
+export type TerminalCapture = {
+    kind: "terminal";
+    command: string;
+    cwd: string;
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    durationMs: number;
+    stdout: NormalizedTerminalStream;
+    stderr: NormalizedTerminalStream;
+};
+export declare function captureTerminal(options: TerminalCaptureOptions): Promise<TerminalCapture>;
+export type ShellResult = {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+};
+export declare function runShellCommand(options: {
+    command: string;
+    cwd: string;
+    timeoutMs: number;
+}): Promise<ShellResult>;