dungbeetle 0.1.1

package/dist/reporters.d.ts

@@ -0,0 +1,11 @@
+import type { RunnerReport } from "./runner.js";
+export type ConsoleReportOptions = {
+    /** Emit ANSI colour. Defaults to auto-detection of stdout. */
+    color?: boolean;
+    /** Emit emoji/unicode glyphs. Defaults to auto-detection of the terminal. */
+    unicode?: boolean;
+};
+export declare function renderConsoleReport(report: RunnerReport, options?: ConsoleReportOptions): string;
+export declare function writeJsonReport(filePath: string, report: RunnerReport): Promise<void>;
+export declare function renderHtmlReport(report: RunnerReport): string;
+export declare function writeHtmlReport(filePath: string, report: RunnerReport): Promise<void>;

package/dist/reporters.js

@@ -0,0 +1,314 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { stableStringify } from "./json.js";
+import { stripControlChars } from "./terminal/ansi.js";
+import { BRAND_NAME } from "./brand.js";
+import { colorEnabled, formatDuration, makePalette, makeSymbols, unicodeEnabled } from "./tty.js";
+const STATUS_ORDER = ["passed", "updated", "failed", "missing", "error"];
+export function renderConsoleReport(report, options = {}) {
+    const color = options.color ?? colorEnabled(process.stdout);
+    const unicode = options.unicode ?? unicodeEnabled();
+    const palette = makePalette(color);
+    const symbols = makeSymbols(unicode);
+    const headTone = report.passed ? palette.green : palette.red;
+    const headIcon = report.passed ? symbols.passed : symbols.failed;
+    const headWord = report.passed ? "PASS" : "FAIL";
+    const lines = [];
+    // Header banner: status, project, and mode.
+    lines.push(`${headIcon} ${palette.bold(headTone(headWord))} ${palette.dim(symbols.arrow)} ` +
+        `${palette.bold(report.project)} ${palette.dim(symbols.arrow)} ${report.mode}`);
+    // Summary counts, one coloured chip per non-zero status.
+    lines.push(`${palette.dim("Snapshots")}  ${summaryCounts(report.results, palette)}`);
+    if (report.lifecycle.length > 0) {
+        lines.push(`${palette.dim("Lifecycle")}  ${report.lifecycle
+            .map((run) => `${run.phase}${palette.dim(":")}${run.exitCode ?? "signal"}`)
+            .join(palette.dim(", "))}`);
+    }
+    for (const result of report.results) {
+        lines.push("");
+        lines.push(renderResultLine(result, palette, symbols));
+        lines.push(`  ${palette.dim(result.baselinePath)}`);
+        if (result.error) {
+            lines.push(`  ${palette.red(stripControlChars(result.error))}`);
+        }
+        if (result.diff) {
+            lines.push(colorizeDiff(result.diff, palette));
+        }
+    }
+    // Footer: overall result and elapsed wall-clock time.
+    const elapsed = elapsedMs(report.startedAt, report.finishedAt);
+    lines.push("");
+    lines.push(`${headIcon} ${palette.bold(headTone(headWord))} ` +
+        `${palette.dim(`${symbols.clock ? `${symbols.clock} ` : ""}${formatDuration(elapsed)}`)}`);
+    return lines.join("\n");
+}
+export async function writeJsonReport(filePath, report) {
+    const resolvedPath = path.resolve(filePath);
+    await mkdir(path.dirname(resolvedPath), { recursive: true });
+    // Screenshots are kept in the JSON report (not just the HTML) so `dungbeetle push`
+    // carries them to the server, where the run page renders them too.
+    await writeFile(resolvedPath, `${stableStringify(report)}\n`, "utf8");
+}
+export function renderHtmlReport(report) {
+    const status = report.passed ? "PASS" : "FAIL";
+    // Spot-check ergonomics: surface what needs attention (failed / missing /
+    // error) expanded at the top, and tuck passing/updated targets behind a
+    // collapsed <details> so a quick scan lands on the regressions, not the noise.
+    const attention = report.results.filter((result) => result.status === "failed" || result.status === "missing" || result.status === "error");
+    const ok = report.results.filter((result) => result.status === "passed" || result.status === "updated");
+    const lifecycleRows = report.lifecycle
+        .map((run) => {
+        return `<tr><td>${escapeHtml(run.phase)}</td><td><code>${escapeHtml(run.command)}</code></td><td>${escapeHtml(String(run.exitCode ?? "running"))}</td><td>${run.durationMs}</td></tr>`;
+    })
+        .join("\n");
+    const resultsHtml = report.results.length === 0
+        ? "<p>No snapshot targets ran.</p>"
+        : [
+            attention.length > 0
+                ? attention.map(renderResultSection).join("\n")
+                : "<p>No failing targets.</p>",
+            ok.length > 0
+                ? `<details class="passing"><summary>${ok.length} passing/updated target${ok.length === 1 ? "" : "s"}</summary>\n${ok
+                    .map(renderResultSection)
+                    .join("\n")}\n</details>`
+                : ""
+        ]
+            .filter((part) => part.length > 0)
+            .join("\n");
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <title>${BRAND_NAME} ${escapeHtml(report.project)} ${escapeHtml(report.mode)} report</title>
+    <style>
+      /* Dark by default, matching the product's dark-first surfaces (docs,
+         cloud review UI); screenshots keep a light backing since captured
+         pages are usually light. */
+      :root { color-scheme: dark; font-family: system-ui, sans-serif; }
+      body { margin: 2rem; line-height: 1.5; background: #121514; color: #e8ecea; }
+      code, pre { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+      a { color: #3ad17f; }
+      .summary { border: 1px solid #ffffff24; border-radius: 0.5rem; padding: 1rem; background: #191d1b; }
+      .chips { display: flex; flex-wrap: wrap; gap: 0.4rem; }
+      .status { border-radius: 999px; padding: 0.1rem 0.5rem; font-size: 0.8rem; }
+      .passed, .updated { background: #3ad17f26; color: #3ad17f; }
+      .failed, .missing, .error { background: #ff7b7226; color: #ff7b72; }
+      .result { border-top: 1px solid #ffffff24; margin-top: 1.5rem; padding-top: 1rem; }
+      .diff { background: #ffffff0d; border-radius: 0.5rem; overflow-x: auto; padding: 1rem; }
+      .diff .add { color: #3ad17f; }
+      .diff .del { color: #ff7b72; }
+      .diff .ctx { opacity: 0.75; }
+      .pixel { color: #9aa8a1; font-size: 0.95rem; }
+      details.passing { margin-top: 1.5rem; }
+      details.passing > summary { cursor: pointer; font-weight: 600; padding: 0.5rem 0; }
+      .screenshots { display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: 1rem; margin-top: 1rem; }
+      .screenshots figure { margin: 0; }
+      .screenshots figcaption { font-weight: 600; margin-bottom: 0.3rem; }
+      .screenshots img { width: 100%; height: auto; border: 1px solid #ffffff2e; border-radius: 0.5rem; background: #fff; }
+      table { border-collapse: collapse; width: 100%; }
+      th, td { border: 1px solid #ffffff24; padding: 0.4rem; text-align: left; }
+    </style>
+  </head>
+  <body>
+    <h1>${BRAND_NAME} ${escapeHtml(report.mode)} report: ${status}</h1>
+    <section class="summary">
+      <p><strong>Project:</strong> ${escapeHtml(report.project)}</p>
+      <p><strong>Started:</strong> ${escapeHtml(report.startedAt)}</p>
+      <p><strong>Finished:</strong> ${escapeHtml(report.finishedAt)}</p>
+      <p><strong>Snapshots:</strong></p>
+      <div class="chips">${summaryChipsHtml(report.results)}</div>
+    </section>
+    <h2>Lifecycle</h2>
+    ${report.lifecycle.length > 0
+        ? `<table><thead><tr><th>Phase</th><th>Command</th><th>Exit</th><th>Duration ms</th></tr></thead><tbody>${lifecycleRows}</tbody></table>`
+        : "<p>No lifecycle commands ran.</p>"}
+    <h2>Results</h2>
+    ${resultsHtml}
+  </body>
+</html>
+`;
+}
+// One result block: status badge, baseline, error, the (colourised) diff, the
+// pixel-diff summary when present, and the before/after/diff screenshots.
+function renderResultSection(result) {
+    return [
+        '<section class="result">',
+        `<h2>${escapeHtml(result.kind)}:${escapeHtml(result.name)} <span class="status ${escapeHtml(result.status)}">${escapeHtml(result.status.toUpperCase())}</span></h2>`,
+        `<p><strong>Baseline:</strong> <code>${escapeHtml(result.baselinePath)}</code></p>`,
+        result.error ? `<p class="error">${escapeHtml(result.error)}</p>` : "",
+        result.diff ? renderDiffHtml(result.diff) : "<p>No diff.</p>",
+        result.pixel ? renderPixelSummary(result.pixel) : "",
+        renderScreenshots(result.screenshot),
+        renderNamedScreenshots(result.screenshots),
+        "</section>"
+    ].join("\n");
+}
+// Named per-marker screenshots (game targets): one before/after/diff block per
+// marker, headed by the marker name, in stable alphabetical order.
+function renderNamedScreenshots(screenshots) {
+    if (!screenshots) {
+        return "";
+    }
+    return Object.keys(screenshots)
+        .sort()
+        .map((marker) => [
+        `<h3 class="marker">${escapeHtml(marker)}</h3>`,
+        renderScreenshots(screenshots[marker])
+    ].join("\n"))
+        .join("\n");
+}
+// Colour the diff like the console — additions green, removals red, context
+// dimmed — by the leading marker, so a regression reads at a glance. Each line is
+// escaped, then wrapped in a span; the escaped content is preserved verbatim.
+function renderDiffHtml(diff) {
+    const body = diff
+        .split("\n")
+        .map((line) => {
+        const trimmed = line.trimStart();
+        const cls = trimmed.startsWith("+") || trimmed.startsWith("{+")
+            ? "add"
+            : trimmed.startsWith("-") || trimmed.startsWith("[-")
+                ? "del"
+                : "ctx";
+        return `<span class="${cls}">${escapeHtml(line)}</span>`;
+    })
+        .join("\n");
+    return `<pre class="diff">${body}</pre>`;
+}
+// A compact, scannable read of a screenshot pixel diff (web targets): how many
+// pixels changed, the ratio, whether it cleared tolerance, and a dimension note.
+function renderPixelSummary(pixel) {
+    const changed = pixel.changedPixels.toLocaleString("en-US");
+    const total = pixel.totalPixels.toLocaleString("en-US");
+    const pct = (pixel.changedRatio * 100).toFixed(2);
+    const tolerance = pixel.withinTolerance ? "within tolerance" : "over tolerance";
+    const dims = pixel.dimensionsMatch ? `${pixel.width}×${pixel.height}` : "dimensions differ";
+    return `<p class="pixel"><strong>Pixels:</strong> ${changed} / ${total} changed · ${pct}% · ${escapeHtml(tolerance)} · ${escapeHtml(dims)}</p>`;
+}
+// Coloured status chips for the summary, one per non-empty status.
+function summaryChipsHtml(results) {
+    const counts = new Map();
+    for (const result of results) {
+        counts.set(result.status, (counts.get(result.status) ?? 0) + 1);
+    }
+    const chips = STATUS_ORDER.filter((status) => counts.has(status)).map((status) => `<span class="status ${status}">${escapeHtml(status)} ${counts.get(status)}</span>`);
+    return chips.length > 0 ? chips.join("\n") : '<span class="dim">none</span>';
+}
+export async function writeHtmlReport(filePath, report) {
+    const resolvedPath = path.resolve(filePath);
+    await mkdir(path.dirname(resolvedPath), { recursive: true });
+    await writeFile(resolvedPath, renderHtmlReport(report), "utf8");
+}
+function statusTone(status, palette) {
+    switch (status) {
+        case "passed":
+            return palette.green;
+        case "updated":
+            return palette.cyan;
+        case "missing":
+            return palette.yellow;
+        case "failed":
+        case "error":
+            return palette.red;
+        default:
+            return (value) => value;
+    }
+}
+function statusIcon(status, symbols) {
+    switch (status) {
+        case "passed":
+            return symbols.passed;
+        case "updated":
+            return symbols.updated;
+        case "missing":
+            return symbols.missing;
+        case "error":
+            return symbols.error;
+        default:
+            return symbols.failed;
+    }
+}
+function renderResultLine(result, palette, symbols) {
+    const tone = statusTone(result.status, palette);
+    const icon = statusIcon(result.status, symbols);
+    const label = `${result.kind}${palette.dim(":")}${palette.bold(result.name)}`;
+    return `${icon} ${tone(result.status.toUpperCase())} ${label}`;
+}
+function summaryCounts(results, palette) {
+    const counts = new Map();
+    for (const result of results) {
+        counts.set(result.status, (counts.get(result.status) ?? 0) + 1);
+    }
+    const chips = STATUS_ORDER.filter((status) => counts.has(status)).map((status) => {
+        const tone = statusTone(status, palette);
+        return `${tone(status)}${palette.dim("=")}${tone(String(counts.get(status)))}`;
+    });
+    return chips.length > 0 ? chips.join("  ") : palette.dim("none");
+}
+// Colour diff lines by their leading marker: additions green, removals red,
+// and inline word markers ({+ +} / [- -]) tinted too, so failures read at a
+// glance. Falls back to plain indented text when colour is disabled.
+function colorizeDiff(diff, palette) {
+    // The baseline side of the diff is read verbatim from a committed file, so it
+    // can carry raw terminal escapes; strip them before printing to the reviewer.
+    return stripControlChars(diff)
+        .split("\n")
+        .map((line) => {
+        const trimmed = line.trimStart();
+        let rendered = line;
+        if (trimmed.startsWith("+") || trimmed.startsWith("{+")) {
+            rendered = palette.green(line);
+        }
+        else if (trimmed.startsWith("-") || trimmed.startsWith("[-")) {
+            rendered = palette.red(line);
+        }
+        else {
+            rendered = palette.dim(line);
+        }
+        return `  ${rendered}`;
+    })
+        .join("\n");
+}
+function elapsedMs(startedAt, finishedAt) {
+    const start = Date.parse(startedAt);
+    const end = Date.parse(finishedAt);
+    if (Number.isNaN(start) || Number.isNaN(end)) {
+        return 0;
+    }
+    return end - start;
+}
+// Embed the before/after (and optional diff) screenshots as inline data URIs so
+// the HTML report stays a single self-contained file. Returns an empty string
+// when the result has no screenshots (non-web targets, passing tests).
+function renderScreenshots(screenshot) {
+    if (!screenshot) {
+        return "";
+    }
+    const figures = [
+        figureFor("Before", screenshot.baseline),
+        figureFor("After", screenshot.candidate),
+        figureFor("Diff", screenshot.diff)
+    ].filter((figure) => figure.length > 0);
+    if (figures.length === 0) {
+        return "";
+    }
+    return `<div class="screenshots">${figures.join("\n")}</div>`;
+}
+function figureFor(caption, base64) {
+    if (!base64) {
+        return "";
+    }
+    return [
+        "<figure>",
+        `<figcaption>${escapeHtml(caption)}</figcaption>`,
+        `<img alt="${escapeHtml(caption)} screenshot" src="data:image/png;base64,${base64}">`,
+        "</figure>"
+    ].join("\n");
+}
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}

package/dist/runner.d.ts

@@ -0,0 +1,48 @@
+import { type ScreenshotImages } from "./compare.js";
+import type { CaptureTarget, DungbeetleConfig, ComparisonConfig } from "./config.js";
+import { type PixelDiffResult } from "./diff/pixel.js";
+import { type LifecycleRun } from "./lifecycle.js";
+import { type SnapshotArtifact } from "./capture.js";
+export type SnapshotStatus = "passed" | "failed" | "missing" | "updated" | "error";
+export type ScreenshotComparison = {
+    baseline?: string;
+    candidate?: string;
+    diff?: string;
+};
+export type SnapshotResult = {
+    name: string;
+    kind: CaptureTarget["kind"];
+    status: SnapshotStatus;
+    baselinePath: string;
+    diff: string;
+    pixel?: PixelDiffResult;
+    screenshot?: ScreenshotComparison;
+    screenshots?: Record<string, ScreenshotComparison>;
+    snapshot?: string;
+    error?: string;
+};
+export type RunnerReport = {
+    kind: "dungbeetle-run";
+    mode: "test" | "update";
+    passed: boolean;
+    project: string;
+    startedAt: string;
+    finishedAt: string;
+    lifecycle: LifecycleRun[];
+    results: SnapshotResult[];
+};
+export declare function updateBaselines(options: {
+    config: DungbeetleConfig;
+    cwd?: string;
+    targets?: string[];
+    includeSnapshots?: boolean;
+}): Promise<RunnerReport>;
+export declare function testBaselines(options: {
+    config: DungbeetleConfig;
+    cwd?: string;
+    targets?: string[];
+    includeSnapshots?: boolean;
+}): Promise<RunnerReport>;
+export declare function namedScreenshotBuffers(snapshot: SnapshotArtifact): Record<string, Buffer>;
+export declare function buildScreenshotComparison(baseline: Buffer | undefined, candidate: Buffer, pixelTolerance: ComparisonConfig["pixelTolerance"], includeDiff: boolean, images?: ScreenshotImages): ScreenshotComparison | undefined;
+export declare function screenshotBuffer(snapshot: SnapshotArtifact): Buffer | undefined;