dungbeetle 0.1.1

package/dist/captures/web.js

@@ -0,0 +1,248 @@
+import { createHash } from "node:crypto";
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+import { asNodes, coerceSnapshot, compareScreenshot, render } from "../compare/shared.js";
+import { structuralChanges } from "../diff/structural.js";
+import { diffDomTrees, renderTreeChanges } from "../diff/tree.js";
+import { isRecord } from "../guards.js";
+import { canonicalizeSnapshot } from "../snapshot.js";
+import { createDomSnapshot } from "../web/domSnapshot.js";
+import { capturePlaywrightWeb } from "../web/playwrightCapture.js";
+// Web has its own sub-dispatch: a Playwright driver, a local HTML fixture, or a
+// lightweight URL fetch — all of which normalize to a `web` snapshot.
+async function captureWebTarget(target, { config, cwd }) {
+    if (target.screenshotFile) {
+        const filePath = path.resolve(cwd, target.screenshotFile);
+        const data = await readFile(filePath);
+        return {
+            kind: "web",
+            source: filePath,
+            capturedAt: "masked",
+            root: [],
+            driver: "file",
+            screenshot: { mimeType: "image/png", data: data.toString("base64") }
+        };
+    }
+    if (target.driver === "playwright") {
+        return capturePlaywrightWeb(target, {
+            maskRules: config.normalization.masks,
+            timeoutMs: target.timeoutMs ?? config.lifecycle.wait.timeoutMs
+        });
+    }
+    if (target.html) {
+        const htmlPath = path.resolve(cwd, target.html);
+        const html = await readFile(htmlPath, "utf8");
+        return createDomSnapshot(html, {
+            source: htmlPath,
+            maskRules: config.normalization.masks
+        });
+    }
+    if (target.url) {
+        const response = await fetch(target.url, {
+            signal: AbortSignal.timeout(target.timeoutMs ?? config.lifecycle.wait.timeoutMs)
+        });
+        if (!response.ok) {
+            throw new Error(`Web target "${target.name}" returned HTTP ${response.status} for ${target.url}.`);
+        }
+        return createDomSnapshot(await response.text(), {
+            source: target.url,
+            maskRules: config.normalization.masks
+        });
+    }
+    throw new Error(`Web target "${target.name}" must provide an html fixture path or url.`);
+}
+function compareWeb(baseline, candidate, options) {
+    const sections = [];
+    const webTarget = options.target?.kind === "web" ? options.target : undefined;
+    const tree = diffDomTrees(asNodes(baseline.root), asNodes(candidate.root));
+    if (!tree.equal) {
+        sections.push(renderTreeChanges(tree.changes));
+    }
+    if (baseline.driver !== candidate.driver) {
+        sections.push(`~ driver: ${String(baseline.driver)} → ${String(candidate.driver)}`);
+    }
+    if (baseline.accessibility !== undefined || candidate.accessibility !== undefined) {
+        const a11y = structuralChanges(baseline.accessibility, candidate.accessibility, {
+            numericTolerance: options.comparison.numericTolerance
+        });
+        for (const change of a11y) {
+            sections.push(`~ accessibility ${change.path}: ${render(change.before)} → ${render(change.after)}`);
+        }
+    }
+    const screenshot = compareScreenshot(baseline, candidate, options, webTarget?.pixelTolerance ?? options.comparison.pixelTolerance);
+    // "strict" (default): a screenshot change beyond tolerance gates the run.
+    // "advisory": the DOM is the gate — the change is reported, not failed.
+    const advisory = [];
+    if (screenshot.line) {
+        if (webTarget?.screenshotMode === "advisory") {
+            advisory.push(`${screenshot.line} (advisory — the DOM is the gate)`);
+        }
+        else {
+            sections.push(screenshot.line);
+        }
+    }
+    return {
+        equal: sections.length === 0,
+        rendered: [...sections, ...advisory].join("\n"),
+        pixel: screenshot.pixel,
+        ...(screenshot.images ? { screenshotImages: screenshot.images } : {})
+    };
+}
+// Screenshots are reduced to a content digest so baselines stay small and
+// reviewable: the raw base64 blob never lands in the diffable JSON, but a pixel
+// change still shows up as a changed hash. The PNG itself is written alongside
+// the baseline by the runner for human inspection.
+export function digestScreenshot(screenshot) {
+    const data = typeof screenshot.data === "string" ? screenshot.data : "";
+    const buffer = Buffer.from(data, "base64");
+    return {
+        mimeType: screenshot.mimeType ?? "image/png",
+        byteLength: buffer.byteLength,
+        sha256: createHash("sha256").update(buffer).digest("hex")
+    };
+}
+function canonicalizeWeb(value) {
+    const canonical = {
+        kind: value.kind,
+        root: canonicalizeSnapshot(value.root)
+    };
+    if (value.driver !== undefined) {
+        canonical.driver = value.driver;
+    }
+    if (value.accessibility !== undefined && value.accessibility !== null) {
+        canonical.accessibility = canonicalizeSnapshot(value.accessibility);
+    }
+    if (isRecord(value.screenshot)) {
+        canonical.screenshot = digestScreenshot(value.screenshot);
+    }
+    return canonical;
+}
+async function validateWebTarget(target, cwd) {
+    const checks = [];
+    if (target.screenshotFile) {
+        const filePath = path.resolve(cwd, target.screenshotFile);
+        const present = await access(filePath).then(() => true, () => false);
+        checks.push(present
+            ? {
+                name: "web-target",
+                severity: "pass",
+                target: target.name,
+                message: `Screenshot file exists at ${filePath}.`
+            }
+            : {
+                name: "web-target",
+                severity: "warn",
+                target: target.name,
+                message: `Screenshot file is missing at ${filePath} — run the browser tests that produce it first.`
+            });
+        return checks;
+    }
+    if (target.html) {
+        checks.push(await validateHtmlTarget(target, cwd));
+    }
+    else if (target.url) {
+        checks.push({
+            name: "web-target",
+            severity: "pass",
+            target: target.name,
+            message: `Web target "${target.name}" has a URL.`
+        });
+    }
+    else {
+        checks.push({
+            name: "web-target",
+            severity: "fail",
+            target: target.name,
+            message: `Web target "${target.name}" must configure html or url.`
+        });
+    }
+    if (target.driver === "playwright") {
+        checks.push(await validatePlaywrightTarget(target));
+    }
+    return checks;
+}
+async function validateHtmlTarget(target, cwd) {
+    const htmlPath = path.resolve(cwd, target.html ?? "");
+    try {
+        await access(htmlPath);
+        return {
+            name: "web-target",
+            severity: "pass",
+            target: target.name,
+            message: `HTML fixture exists at ${htmlPath}.`
+        };
+    }
+    catch {
+        return {
+            name: "web-target",
+            severity: "fail",
+            target: target.name,
+            message: `HTML fixture is missing at ${htmlPath}.`
+        };
+    }
+}
+async function validatePlaywrightTarget(target) {
+    const executablePath = target.browser?.executablePath ?? process.env.DUNGBEETLE_CHROMIUM_EXECUTABLE_PATH;
+    if (executablePath) {
+        try {
+            await access(executablePath);
+            return {
+                name: "playwright-browser",
+                severity: "pass",
+                target: target.name,
+                message: `Playwright browser executable exists at ${executablePath}.`
+            };
+        }
+        catch {
+            return {
+                name: "playwright-browser",
+                severity: "fail",
+                target: target.name,
+                message: `Playwright browser executable was not found at ${executablePath}.`
+            };
+        }
+    }
+    if (target.browser?.channel) {
+        return {
+            name: "playwright-browser",
+            severity: "warn",
+            target: target.name,
+            message: `Playwright will use browser channel "${target.browser.channel}". Ensure it is installed on this machine.`
+        };
+    }
+    return {
+        name: "playwright-browser",
+        severity: "warn",
+        target: target.name,
+        message: "Playwright target has no browser executable or channel. Set browser.executablePath, browser.channel, or DUNGBEETLE_CHROMIUM_EXECUTABLE_PATH."
+    };
+}
+export const web = {
+    kind: "web",
+    hasScreenshots: true,
+    parallelSafe: true,
+    capture: (target, ctx) => captureWebTarget(target, ctx),
+    canonicalize: canonicalizeWeb,
+    compare: (baseline, candidate, options) => compareWeb(coerceSnapshot(baseline), coerceSnapshot(candidate), options),
+    validateConfig: (target, { label, issues }) => {
+        const webTarget = target;
+        if (!webTarget.html && !webTarget.url && !webTarget.screenshotFile) {
+            issues.push(`${label} (web "${webTarget.name}") must configure "html", "url", or "screenshotFile".`);
+        }
+        if (webTarget.screenshotFile && (webTarget.html || webTarget.url || webTarget.driver)) {
+            issues.push(`${label} (web "${webTarget.name}") sets "screenshotFile" alongside a page capture — use one source.`);
+        }
+        if (webTarget.screenshotMode !== undefined &&
+            webTarget.screenshotMode !== "strict" &&
+            webTarget.screenshotMode !== "advisory") {
+            issues.push(`${label} (web "${webTarget.name}") has unknown screenshotMode "${String(webTarget.screenshotMode)}" — use "strict" or "advisory".`);
+        }
+        if (webTarget.driver && webTarget.driver !== "fetch" && webTarget.driver !== "playwright") {
+            issues.push(`${label} (web "${webTarget.name}") has unknown driver "${webTarget.driver}".`);
+        }
+        if (webTarget.driver === "playwright" && !webTarget.url) {
+            issues.push(`${label} (web "${webTarget.name}") uses the playwright driver and must set "url".`);
+        }
+    },
+    doctorChecks: (target, cwd) => validateWebTarget(target, cwd)
+};

package/dist/check/capture.d.ts

@@ -0,0 +1,15 @@
+import type { CaptureTarget } from "../config.js";
+import { type CheckParser } from "./parsers.js";
+export type CheckTarget = Extract<CaptureTarget, {
+    kind: "check";
+}>;
+export type CheckSnapshot = {
+    kind: "check";
+    tool: string;
+    data: Record<string, unknown>;
+};
+export declare function checkParserFor(target: CheckTarget): CheckParser;
+export declare function captureCheck(target: CheckTarget, options: {
+    cwd: string;
+    timeoutMs: number;
+}): Promise<CheckSnapshot>;

package/dist/check/capture.js

@@ -0,0 +1,76 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { parseJsonFile } from "../json.js";
+import { runShellCommand } from "../terminal/capture.js";
+import { checkParsers } from "./parsers.js";
+export function checkParserFor(target) {
+    const parser = checkParsers[target.tool];
+    if (!parser) {
+        throw new Error(`Check target "${target.name}" uses unknown tool "${target.tool}". ` +
+            `Available: ${Object.keys(checkParsers).join(", ")}.`);
+    }
+    return parser;
+}
+// Capture a check snapshot, then normalize via the tool parser. Modes:
+//  - command only (or parser default): run it, read stdout.
+//  - output only: ingest an existing report file, run nothing.
+//  - command + output (or parser defaults, e.g. test runners): run the
+//    command, then read the report file it wrote.
+export async function captureCheck(target, options) {
+    const parser = checkParserFor(target);
+    const command = target.command ?? (target.output ? undefined : parser.defaultCommand);
+    const outputFile = target.output ?? (target.command ? undefined : parser.defaultOutput);
+    let stdout = "";
+    if (command) {
+        const result = await runShellCommand({
+            command,
+            cwd: options.cwd,
+            timeoutMs: target.timeoutMs ?? options.timeoutMs
+        });
+        const detail = result.stderr.trim();
+        const exit = result.exitCode ?? `signal ${String(result.signal)}`;
+        // A null exit code means the process was killed by a signal — for a check
+        // command that is the timeout's SIGTERM (see runShellCommand.killTree). Unlike
+        // a non-zero exit, a signal-kill is never "findings exist"; the run was cut off
+        // mid-execution, so `toleratesNonZeroExit` must NOT wave it through. Otherwise a
+        // timed-out `phpunit --log-junit` would fall through to reading whatever stale
+        // report a previous run left on disk and report a stale PASS.
+        if (result.exitCode === null) {
+            throw new Error(`Check target "${target.name}": \`${command}\` was killed (${exit}) before it completed` +
+                `${detail ? `:\n${detail}` : "."}`);
+        }
+        // Some tools (phpstan, test runners) exit non-zero when they *found*
+        // something — for those the findings are the snapshot, so failure is only
+        // missing/unparseable output below.
+        if (result.exitCode !== 0 && !parser.toleratesNonZeroExit) {
+            throw new Error(`Check target "${target.name}": \`${command}\` exited with ${exit}${detail ? `:\n${detail}` : "."}`);
+        }
+        stdout = result.stdout;
+        if (result.exitCode !== 0 && !outputFile && stdout.trim() === "") {
+            throw new Error(`Check target "${target.name}": \`${command}\` exited with ${exit} and produced no output` +
+                `${detail ? `:\n${detail}` : "."}`);
+        }
+    }
+    let rawText;
+    let source;
+    if (outputFile) {
+        source = path.resolve(options.cwd, outputFile);
+        try {
+            rawText = await readFile(source, "utf8");
+        }
+        catch {
+            throw new Error(`Check target "${target.name}": expected report at ${source}` +
+                `${command ? ` after \`${command}\`` : ""}, but it could not be read.`);
+        }
+    }
+    else {
+        source = command;
+        rawText = stdout;
+    }
+    const raw = parser.format === "text" ? rawText : parseJsonFile(rawText, source);
+    return {
+        kind: "check",
+        tool: parser.tool,
+        data: parser.normalize(raw, { cwd: options.cwd })
+    };
+}

package/dist/check/junit.d.ts

@@ -0,0 +1,9 @@
+export type JUnitCase = {
+    name: string;
+    suite: string;
+    file?: string;
+    status: "passed" | "failed" | "error" | "skipped";
+    type?: string;
+    message?: string;
+};
+export declare function parseJUnit(xml: string): JUnitCase[];

package/dist/check/junit.js

@@ -0,0 +1,51 @@
+// Minimal JUnit XML extraction for the check kind's test-runner parsers.
+//
+// Not a general XML parser — it targets the JUnit report shape emitted by
+// PHPUnit/Pest (and most other runners): `<testcase>` elements with attributes
+// and at most one `<failure>` / `<error>` / `<skipped>` child. Kept dependency-
+// free on purpose; the fixtures it is tested against are real runner output.
+const TESTCASE = /<testcase\b([^>]*?)(?:\/>|>([\s\S]*?)<\/testcase>)/g;
+const CHILD = /<(failure|error|skipped)\b([^>]*?)(?:\/>|>([\s\S]*?)<\/\1>)/;
+const ATTR = /([\w.-]+)="([^"]*)"/g;
+function unescapeXml(value) {
+    return value
+        .replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, "$1")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&#(\d+);/g, (_, code) => String.fromCodePoint(Number(code)))
+        .replace(/&amp;/g, "&");
+}
+function attributes(raw) {
+    const attrs = {};
+    for (const match of raw.matchAll(ATTR)) {
+        attrs[match[1]] = unescapeXml(match[2]);
+    }
+    return attrs;
+}
+export function parseJUnit(xml) {
+    if (!/<testsuites?\b/.test(xml)) {
+        throw new Error("Invalid JUnit report: no <testsuite> element found.");
+    }
+    const cases = [];
+    for (const match of xml.matchAll(TESTCASE)) {
+        const attrs = attributes(match[1]);
+        const body = match[2] ?? "";
+        const child = CHILD.exec(body);
+        const status = child
+            ? { failure: "failed", error: "error", skipped: "skipped" }[child[1]]
+            : "passed";
+        const childAttrs = child ? attributes(child[2]) : {};
+        const message = child ? unescapeXml((child[3] ?? "").trim()) : "";
+        cases.push({
+            name: attrs.name ?? "?",
+            suite: attrs.class ?? attrs.classname ?? attrs.file ?? "?",
+            ...(attrs.file ? { file: attrs.file } : {}),
+            status,
+            ...(childAttrs.type ? { type: childAttrs.type } : {}),
+            ...(message ? { message } : {})
+        });
+    }
+    return cases;
+}

package/dist/check/laravel.d.ts

@@ -0,0 +1,2 @@
+import type { CaptureTarget } from "../config.js";
+export declare function detectLaravelTargets(cwd: string): Promise<CaptureTarget[] | null>;

package/dist/check/laravel.js

@@ -0,0 +1,44 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { isRecord } from "../guards.js";
+// Zero-config on-ramp: scaffold check targets for a Laravel app, detected via
+// composer.json's laravel/framework requirement. App-shape surfaces are always
+// included; tool targets only when the tool is actually installed
+// (require/require-dev). Returns null when this isn't a Laravel app.
+export async function detectLaravelTargets(cwd) {
+    let composer;
+    try {
+        composer = JSON.parse(await readFile(path.join(cwd, "composer.json"), "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(composer)) {
+        return null;
+    }
+    const required = isRecord(composer.require) ? composer.require : {};
+    const requiredDev = isRecord(composer["require-dev"]) ? composer["require-dev"] : {};
+    if (!Object.hasOwn(required, "laravel/framework")) {
+        return null;
+    }
+    const has = (pkg) => Object.hasOwn(required, pkg) || Object.hasOwn(requiredDev, pkg);
+    const targets = [
+        { kind: "check", name: "routes", tool: "laravel-routes" },
+        { kind: "check", name: "about", tool: "laravel-about" },
+        { kind: "check", name: "schedule", tool: "laravel-schedule" },
+        { kind: "check", name: "schema", tool: "laravel-schema" }
+    ];
+    if (has("pestphp/pest")) {
+        targets.push({ kind: "check", name: "tests", tool: "pest" });
+    }
+    else if (has("phpunit/phpunit")) {
+        targets.push({ kind: "check", name: "tests", tool: "phpunit" });
+    }
+    if (has("laravel/pint")) {
+        targets.push({ kind: "check", name: "style", tool: "pint" });
+    }
+    if (has("phpstan/phpstan") || has("larastan/larastan") || has("nunomaduro/larastan")) {
+        targets.push({ kind: "check", name: "static-analysis", tool: "phpstan" });
+    }
+    return targets;
+}

package/dist/check/parsers.d.ts

@@ -0,0 +1,12 @@
+export type CheckData = Record<string, unknown>;
+export interface CheckParser {
+    tool: string;
+    defaultCommand: string;
+    defaultOutput?: string;
+    format?: "json" | "text";
+    toleratesNonZeroExit?: boolean;
+    normalize(raw: unknown, options: {
+        cwd: string;
+    }): CheckData;
+}
+export declare const checkParsers: Record<string, CheckParser>;