@parity/product-lab 0.0.1-placeholder → 0.1.0

package/entrypoints/cli/src/report-command.js

@@ -0,0 +1,207 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { compatibilityMarkdown } from "@parity/product-lab/domain/suites";
+import { renderCompatibilityHtml } from "./reports/compatibility-html.js";
+import { suiteEvidence } from "./reports/evidence-report.js";
+import { renderMarkdownSummary } from "./reports/markdown.js";
+import { renderPrComment } from "./reports/pr-comment.js";
+import { RunRecording } from "@parity/product-lab/domain/recordings";
+export const REPORT_USAGE = `Usage: product-lab report compare <previous> <current> [--out <dir>] [--notify-dir <dir>] [--json]
+       product-lab report summary <run> [--markdown | --json]
+       product-lab report comment <run> [--recordings <dir>] [--label <text>] [--run-url <url>]
+                                  [--artifact <name> | --video-base <url>] [--out <file>]
+
+summary: one suite run (its report directory, or its product-lab-suite.json) as Markdown
+(the default, --markdown) for a CI job summary or a PR comment: the verdict, rows by status,
+scenario and checkpoint counts (planned, executed, unsupported, not reported), planning,
+critical path and total time, per row the environment start (cold, warm or attached, as the
+environment declares it) and where its time went, and what each row ran with. A value the
+record does not carry is printed as "not measured", never as zero. --json prints the record's
+counts and timings. \`product-lab test --suite\` also writes it as summary.md.
+
+comment: the pull request comment of one suite run (backlog 52), self-replacing by its marker: the verdict, then per
+scenario its row, result, time and, from its run recording, where it is in each identity's video (\`--video\` runs).
+  --recordings <dir>   the recordings directory the run wrote to (<lab>/.product-lab/recordings, or
+                       PRODUCT_LAB_RECORDINGS_DIR); without it no scenario shows a recording or video
+  --label <text>       the heading's label (default: <suite>-suite)
+  --run-url <url>      the workflow run, linked under the table
+  --artifact <name>    the artifact holding the videos: each scenario's start is given as text ("starts at 0:42"),
+                       since an artifact is a zip and cannot be seeked into
+  --video-base <url>   a direct address serving the recordings directory's videos/: each video becomes a link that
+                       seeks to the scenario (#t=start,end)
+  --out <file>         write the comment there as well as printing it
+
+Compare two runs of one suite (typically consecutive nightly runs): each report directory
+of \`product-lab test --suite <name> --report-dir <dir>\` (or its product-lab-suite.json).
+Every scenario whose result changed is a regression, a recovery, a new failure or lost
+coverage, with its cause from what each row recorded running (its combination: resolved
+versions, the hosts and chain runtimes the run observed, the lab's source tree):
+  host | runtime | app | binary | tool   only that kind of component changed
+  several                                 more than one kind changed and no row isolates one
+  combination                             every change passes the scenario in another row
+  none                                    nothing recorded changed (drift, an unrecorded input, a flake)
+  unknown                                 the runs record nothing that could say
+  not-run                                 the scenario no longer runs (unsupported, not selected)
+with the evidence (versions, digests, failing step and error), what to do and a
+reproduction command. Still-failing scenarios are listed, not reported again.
+  --out <dir>          where compatibility.json, compatibility.md and compatibility.html go
+                       (default: <current>/compatibility)
+  --notify-dir <dir>   send the notifications (one per changed row) to this directory: each as
+                       Markdown and JSON, deduplicated by key in sent.json (default: send none).
+                       A GitHub comment or issue sender is not built (it needs GitHub).
+  --json               print the whole result as JSON
+  Exit code (compare): 0 when nothing regressed, newly failed or lost coverage; 1 when something did;
+  (summary): 0 when the record was read; 1 when it cannot be; 2 on a usage error for either.`;
+function readSuiteRecord(location) {
+    const path = resolve(location);
+    const file = /\.json$/i.test(path) ? path : join(path, "product-lab-suite.json");
+    let data;
+    try {
+        data = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`No readable suite run at ${file}: give the report directory of a \`product-lab test --suite <name>\` run (its --report-dir), or its product-lab-suite.json (${error instanceof Error ? error.message : String(error)})`);
+    }
+    if (!data || typeof data.id !== "string" || typeof data.suite !== "string" || !Array.isArray(data.rows) || !data.plan)
+        throw new Error(`${file} is not a suite record (id, suite, plan and rows)`);
+    return data;
+}
+function runSummary(location, json, out) {
+    let record;
+    try {
+        record = readSuiteRecord(location);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+    if (json) {
+        out(`${JSON.stringify({ id: record.id, suite: record.suite, status: record.status, counts: record.counts ?? null, timings: record.timings ?? null, rows: record.rows.map((row) => ({ id: row.id, status: row.status, counts: row.counts ?? null, timings: row.timings ?? null })) }, null, 2)}\n`);
+        return 0;
+    }
+    out(renderMarkdownSummary(suiteEvidence(record, new Date())));
+    return 0;
+}
+function readRecordings(directory) {
+    if (!directory || !existsSync(directory))
+        return [];
+    const found = [];
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        const file = join(directory, entry.name, "recording.json");
+        if (!entry.isDirectory() || !existsSync(file))
+            continue;
+        let recording;
+        try {
+            recording = RunRecording.from(JSON.parse(readFileSync(file, "utf8")));
+        }
+        catch (error) {
+            console.error(`Skipped ${file}: ${error instanceof Error ? error.message : String(error)}`);
+            continue;
+        }
+        found.push(recording);
+    }
+    return found;
+}
+function runComment(location, values, out) {
+    let record;
+    try {
+        record = readSuiteRecord(location);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+    const text = renderPrComment(record, readRecordings(values.recordings ? resolve(values.recordings) : undefined), {
+        label: values.label ?? `${record.suite}-suite`,
+        ...(values["run-url"] ? { runUrl: values["run-url"] } : {}),
+        ...(values.artifact ? { artifact: values.artifact } : {}),
+        ...(values["video-base"] ? { videoBase: values["video-base"] } : {}),
+    });
+    if (values.out)
+        writeFileSync(resolve(values.out), text);
+    out(text);
+    return 0;
+}
+function directoryOf(location) {
+    const path = resolve(location);
+    try {
+        return statSync(path).isDirectory() ? path : dirname(path);
+    }
+    catch {
+        return /\.json$/i.test(path) ? dirname(path) : path;
+    }
+}
+export async function runReportCommand(runtime, argv, out = (text) => process.stdout.write(text)) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        strict: true,
+        options: {
+            help: { type: "boolean", short: "h" },
+            out: { type: "string" },
+            "notify-dir": { type: "string" },
+            json: { type: "boolean" },
+            markdown: { type: "boolean" },
+            recordings: { type: "string" },
+            label: { type: "string" },
+            "run-url": { type: "string" },
+            artifact: { type: "string" },
+            "video-base": { type: "string" },
+        },
+    });
+    if (values.help) {
+        out(`${REPORT_USAGE}\n`);
+        return 0;
+    }
+    const [subcommand, previous, current, ...extra] = positionals;
+    if (subcommand === "summary") {
+        if (!previous || current !== undefined || (values.json && values.markdown) || values.out || values["notify-dir"]) {
+            console.error(`Give one suite run directory, and at most one of --markdown and --json.\n${REPORT_USAGE}`);
+            return 2;
+        }
+        return runSummary(previous, !!values.json, out);
+    }
+    if (subcommand === "comment") {
+        if (!previous || current !== undefined || values.json || values.markdown || values["notify-dir"] || (values.artifact && values["video-base"])) {
+            console.error(`Give one suite run directory, and at most one of --artifact and --video-base.\n${REPORT_USAGE}`);
+            return 2;
+        }
+        return runComment(previous, values, out);
+    }
+    if (subcommand !== "compare" || !previous || !current || extra.length || values.markdown) {
+        console.error(`${subcommand && subcommand !== "compare" ? `Unknown report command ${subcommand}. ` : ""}Give two suite run directories.\n${REPORT_USAGE}`);
+        return 2;
+    }
+    const result = await runtime.compareSuiteRuns({
+        previous: resolve(previous),
+        current: resolve(current),
+        ...(values["notify-dir"] ? { notify: { kind: "file", directory: resolve(values["notify-dir"]) } } : {}),
+    });
+    const { report } = result;
+    const directory = resolve(values.out ?? join(directoryOf(current), "compatibility"));
+    mkdirSync(directory, { recursive: true });
+    const files = { json: join(directory, "compatibility.json"), markdown: join(directory, "compatibility.md"), html: join(directory, "compatibility.html") };
+    writeFileSync(files.json, `${JSON.stringify(result, null, 2)}\n`);
+    writeFileSync(files.markdown, `${compatibilityMarkdown(report).trimEnd()}\n`);
+    writeFileSync(files.html, renderCompatibilityHtml(report, new Date()));
+    if (values.json)
+        out(`${JSON.stringify(result, null, 2)}\n`);
+    else {
+        out(`Compatibility of ${report.lab ?? "the lab"} suite ${report.suite}: ${report.previous.id} → ${report.current.id}\n${report.summary}\n`);
+        for (const change of report.changes.filter((item) => item.change !== "blocked"))
+            out(`  ${change.change} ${change.row}: ${change.scenario.name}: cause ${change.cause}${change.blamed.length ? ` (${change.blamed.join(", ")})` : ""}${change.failureClass ? `, ${change.failureClass}` : ""}\n    ${change.action}\n`);
+        if (report.counts.blocked)
+            out(`  ${report.counts.blocked} scenario(s) that passed before did not run after an earlier failure in their row (fail fast)\n`);
+        for (const receipt of result.receipts)
+            out(`  notification ${receipt.status} (${receipt.notifier}): ${receipt.title}${receipt.location ? ` → ${receipt.location}` : ""}\n`);
+        if (!result.notifications.length)
+            out("  No result changed: no notification.\n");
+        else if (!values["notify-dir"])
+            out(`  ${result.notifications.length} notification(s) not sent (no --notify-dir).\n`);
+        out(`Report: ${files.html}, ${files.markdown}, ${files.json}\n`);
+    }
+    return report.counts.regressions || report.counts.newFailures || report.counts.lost ? 1 : 0;
+}

package/entrypoints/cli/src/reports/compatibility-html.d.ts

@@ -0,0 +1,2 @@
+import { type CompatibilityReport } from "@parity/product-lab/domain/suites";
+export declare function renderCompatibilityHtml(report: CompatibilityReport, generatedAt: Date): string;

package/entrypoints/cli/src/reports/compatibility-html.js

@@ -0,0 +1,76 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { reproductionCommand } from "@parity/product-lab/domain/suites";
+import { badge, html, REPORT_STYLE } from "./html.js";
+const EXTRA_STYLE = `.badge.regression,.badge.new-failure{background:#fbdada;color:#8a1616}.badge.recovery{background:#d6f5df;color:#135c2a}.badge.lost,.badge.blocked{background:#fdf1cf;color:#6b4a00}
+section.regression,section.new-failure{border-color:#e7a3a3}section.recovery{border-color:#9fd8ae}section.lost{border-color:#e8d08a}
+table{border-collapse:collapse;margin:.5rem 0;width:100%}th,td{border:1px solid #d8dbe3;padding:.25rem .5rem;text-align:left;vertical-align:top}th{background:#f5f6f9}
+.cause{font-weight:600}code{font-size:.85rem}`;
+const side = (entry) => (entry ? `${html(entry.version)}${entry.detail ? ` <span class="muted">${html(entry.detail)}</span>` : ""}` : '<span class="muted">not recorded</span>');
+function components(changes) {
+    if (!changes.length)
+        return '<p class="muted">No recorded component changed in this row.</p>';
+    return `<table><tr><th>Component</th><th>Change</th><th>Previous</th><th>Current</th></tr>${changes
+        .map((change) => `<tr><td><code>${html(change.id)}</code></td><td>${html(change.change)}</td><td>${side(change.from)}</td><td>${side(change.to)}</td></tr>`)
+        .join("")}</table>`;
+}
+function change(item) {
+    const failure = item.current.failure ?? item.previous.failure;
+    const facts = [
+        `<dt>cause</dt><dd class="cause">${html(item.cause)}${item.blamed.length ? ` (${item.blamed.map((id) => `<code>${html(id)}</code>`).join(", ")})` : ""}${item.failureClass ? `; ${html(item.failureClass)}` : ""}</dd>`,
+        `<dt>scenario</dt><dd>${html(item.scenario.name)}${item.scenario.uri ? ` <span class="muted">${html(item.scenario.uri)}</span>` : ""}</dd>`,
+        `<dt>previous</dt><dd>${html(item.previous.status)}${item.previous.reason ? ` (${html(item.previous.reason)})` : ""}</dd>`,
+        `<dt>current</dt><dd>${html(item.current.status)}${item.current.reason ? ` (${html(item.current.reason)})` : ""}</dd>`,
+        failure
+            ? `<dt>failure</dt><dd>${failure.where === "step" ? `at the step <code>${html(failure.step ?? "?")}</code>` : failure.where === "hook" ? `in the hook <code>${html(failure.step ?? "?")}</code>` : "before any scenario reported"}<pre class="error">${html(failure.error)}</pre></dd>`
+            : "",
+        item.exonerated.length ? `<dt>passes elsewhere</dt><dd>${item.exonerated.map((entry) => `<code>${html(entry.component)}</code> ${html(entry.version)} in row ${html(entry.row)} (${html(entry.run)} run)`).join("<br>")}</dd>` : "",
+        item.unrecorded.length ? `<dt>not recorded</dt><dd>${html(item.unrecorded.join(", "))}</dd>` : "",
+        `<dt>why</dt><dd>${html(item.explanation)}</dd>`,
+        `<dt>what to do</dt><dd>${html(item.action)}</dd>`,
+        item.reproduce
+            ? `<dt>reproduce</dt><dd><code>${html(reproductionCommand(item.reproduce))}</code> <span class="muted">(from the lab's directory)</span>${item.reproduce.versionsManifest ? `<br>versions: <code>${html(item.reproduce.versionsManifest)}</code>` : ""}</dd>`
+            : "",
+    ].join("");
+    return `<section class="${html(item.change)}"><h2>${badge(item.change)} ${html(item.scenario.name)} <span class="muted">row ${html(item.row)}</span></h2><dl>${facts}</dl>${components(item.changed)}</section>`;
+}
+function blocked(changes) {
+    const byRow = new Map();
+    for (const item of changes)
+        if (item.change === "blocked")
+            byRow.set(item.row, [...(byRow.get(item.row) ?? []), item.scenario.name]);
+    return [...byRow].map(([row, names]) => `<section class="lost"><h2>${badge("blocked")} row ${html(row)}</h2><p>${names.length} scenario(s) that passed before did not run after the failure above (fail fast): ${html(names.join("; "))}.</p></section>`).join("\n");
+}
+function combination(entries) {
+    const rows = Object.entries(entries);
+    if (!rows.length)
+        return '<p class="muted">No versions recorded.</p>';
+    return `<table><tr><th>Component</th><th>Version</th><th>Digests</th><th>Origin</th></tr>${rows
+        .map(([id, entry]) => `<tr><td><code>${html(id)}</code></td><td>${html(entry.version)}${entry.detail ? `<br><span class="muted">${html(entry.detail)}</span>` : ""}</td><td>${Object.entries(entry.digests)
+        .map(([name, value]) => `${html(name)} <code>${html(value)}</code>`)
+        .join("<br>")}</td><td>${html(entry.origin)}</td></tr>`)
+        .join("")}</table>`;
+}
+export function renderCompatibilityHtml(report, generatedAt) {
+    const status = report.counts.regressions || report.counts.newFailures ? "failed" : report.actionable ? "changed" : "passed";
+    const rows = report.rows
+        .map((row) => `<tr><td>${html(row.id)}</td><td>${badge(row.previous?.status ?? "absent")}</td><td>${badge(row.current?.status ?? "absent")}</td><td>${html(row.changed.map((item) => item.id).join(", ") || "none")}</td><td>${row.unchanged}</td><td>${row.stillFailing.length}</td></tr>`)
+        .join("");
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Compatibility: ${html(report.lab ?? "lab")} ${html(report.suite)}</title>
+<style>
+${REPORT_STYLE}${EXTRA_STYLE}
+</style></head>
+<body>
+<h1>${badge(status)} Compatibility: ${html(report.lab ?? "lab")} suite ${html(report.suite)}</h1>
+<p class="reason">${html(report.summary)}</p>
+<p class="muted">previous ${html(report.previous.id)}${report.previous.directory ? ` (${html(report.previous.directory)})` : ""}; current ${html(report.current.id)}${report.current.directory ? ` (${html(report.current.directory)})` : ""}; written ${html(generatedAt.toISOString())}</p>
+<section><h2>Rows</h2><table><tr><th>Row</th><th>Previous</th><th>Current</th><th>Components changed</th><th>Unchanged</th><th>Still failing</th></tr>${rows}</table></section>
+${report.changes.length ? report.changes.filter((item) => item.change !== "blocked").map(change).join("\n") : '<section class="passed"><p>No result changed, so nobody is notified.</p></section>'}
+${blocked(report.changes)}
+<h2>Versions per row (current run)</h2>
+${report.rows.map((row) => `<section><h2>${html(row.id)}</h2>${combination(row.combination)}</section>`).join("\n")}
+</body></html>
+`;
+}

package/entrypoints/cli/src/reports/evidence-report.d.ts

@@ -0,0 +1,46 @@
+import type { SuiteCombination } from "@parity/product-lab/domain/suites";
+import type { FeatureRunRecord, SuiteCounts, SuiteRunRecord, SuiteScenarioCounts, SuiteRowTimings, SuiteTimings } from "@parity/product-lab/ports/driving";
+export interface EvidenceRow {
+    id: string;
+    status: string;
+    reason?: string;
+    tags?: string;
+    environment?: string;
+    host?: string;
+    candidates?: Record<string, string>;
+    versionsManifest?: string;
+    /** What the row ran with: resolved versions, what its run observed, the lab's source (suite rows that ran). */
+    combination?: SuiteCombination;
+    durationMs?: number;
+    /** Suite rows: scenario and checkpoint counts (absent in older records). */
+    counts?: SuiteScenarioCounts;
+    /** Suite rows: measured timings (absent for a row that did not start, and in older records). */
+    timings?: SuiteRowTimings;
+    run?: FeatureRunRecord;
+}
+export interface EvidenceReport {
+    /** A suite run (rows with counts, timings and combinations) or one `product-lab test` run. */
+    kind: "suite" | "run";
+    title: string;
+    id: string;
+    status: "passed" | "failed";
+    reason: string;
+    /** When the report was written (wall clock). */
+    generatedAt: string;
+    durationMs: number;
+    budgetMs?: number;
+    affected?: {
+        source: string;
+        changed: readonly string[];
+        scopes: readonly string[];
+        selection: string;
+        reason: string;
+    };
+    /** Suites: rows by status and scenario/checkpoint counts (absent in older records). */
+    counts?: SuiteCounts;
+    /** Suites: planning, critical path and total (absent in older records). */
+    timings?: SuiteTimings;
+    rows: EvidenceRow[];
+}
+export declare function suiteEvidence(record: SuiteRunRecord, generatedAt: Date): EvidenceReport;
+export declare function runEvidence(record: FeatureRunRecord, generatedAt: Date, passed: boolean, reason: string): EvidenceReport;

package/entrypoints/cli/src/reports/evidence-report.js

@@ -0,0 +1,31 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export function suiteEvidence(record, generatedAt) {
+    return {
+        kind: "suite",
+        title: `product-lab test --suite ${record.suite}`,
+        id: record.id,
+        status: record.status,
+        reason: record.reason,
+        generatedAt: generatedAt.toISOString(),
+        durationMs: Math.round(record.finishedAt - record.startedAt),
+        ...(record.budgetMs !== undefined ? { budgetMs: record.budgetMs } : {}),
+        ...(record.plan.affected ? { affected: record.plan.affected } : {}),
+        ...(record.counts ? { counts: record.counts } : {}),
+        ...(record.timings ? { timings: record.timings } : {}),
+        rows: record.rows,
+    };
+}
+export function runEvidence(record, generatedAt, passed, reason) {
+    const durationMs = Math.round((record.finishedAt ?? record.startedAt) - record.startedAt);
+    return {
+        kind: "run",
+        title: "product-lab test",
+        id: record.id,
+        status: passed ? "passed" : "failed",
+        reason,
+        generatedAt: generatedAt.toISOString(),
+        durationMs,
+        rows: [{ id: record.id, status: passed ? "passed" : "failed", ...(record.selection.tags ? { tags: record.selection.tags } : {}), ...(record.selection.environment ? { environment: record.selection.environment } : {}), durationMs, run: record }],
+    };
+}

package/entrypoints/cli/src/reports/host-bypass.d.ts

@@ -0,0 +1,3 @@
+import { type HostBypassEvidence } from "@parity/product-lab/domain";
+/** Complete, unclipped text for reports and recordings, including unknown and unattributed ledger entries. */
+export declare function hostBypassLines(evidence: HostBypassEvidence | undefined): string[];

package/entrypoints/cli/src/reports/host-bypass.js

@@ -0,0 +1,17 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { hostBypassVerdict } from "@parity/product-lab/domain";
+export function hostBypassLines(evidence) {
+    if (!evidence)
+        return ["Host bypass: not recorded (coverage unknown)."];
+    return [
+        `Host bypass: ${hostBypassVerdict(evidence)}; scope ${evidence.scope}`,
+        ...evidence.gaps.map((gap) => `Coverage gap: ${gap}`),
+        ...evidence.apps.flatMap((app) => [
+            `${app.actor} / ${app.app}: ${app.verdict}; policy ${app.policy.mode}${app.policy.mode === "allow" ? `; reason: ${app.policy.reason}` : ""}`,
+            ...app.gaps.map((gap) => `  Coverage gap: ${gap}`),
+            ...app.connections.map((connection) => `  Direct ${connection.operation} via ${connection.transport} from ${connection.source}: ${connection.endpoint}; steps ${connection.steps.map((step) => step + 1).join(", ") || "unattributed"}; ${JSON.stringify(connection)}`),
+        ]),
+        ...evidence.ledger.map((entry) => `Finalized ${entry.chain} #${entry.block.number}[${entry.index}] ${entry.hash}: ${entry.category}; decoded ${entry.decoded}; ${entry.reason}; ${JSON.stringify(entry)}`),
+    ];
+}

package/entrypoints/cli/src/reports/html.d.ts

@@ -0,0 +1,6 @@
+import type { EvidenceReport } from "./evidence-report.js";
+/** The reports' shared style sheet (the evidence report and the compatibility report look alike). */
+export declare const REPORT_STYLE = "body{font:14px/1.45 system-ui,-apple-system,sans-serif;margin:2rem auto;max-width:1100px;padding:0 1rem;color:#1d2433}\nh1{font-size:1.4rem}h2{font-size:1.1rem;margin:.2rem 0}\n.badge{display:inline-block;padding:0 .45rem;border-radius:.3rem;font-size:.8rem;font-weight:600;background:#e6e8ee;color:#1d2433}\n.badge.passed{background:#d6f5df;color:#135c2a}.badge.failed,.badge.over-budget,.badge.empty,.badge.undefined,.badge.ambiguous{background:#fbdada;color:#8a1616}\n.badge.unsupported,.badge.skipped,.badge.pending{background:#fdf1cf;color:#6b4a00}\nsection{border:1px solid #d8dbe3;border-radius:.5rem;padding:.8rem 1rem;margin:1rem 0}\nsection.failed,section.over-budget,section.empty{border-color:#e7a3a3}\ndl{display:grid;grid-template-columns:max-content 1fr;gap:.2rem 1rem;margin:.5rem 0}dt{color:#5b6475}dd{margin:0}\n.muted{color:#6b7385;font-size:.85rem}.reason{font-weight:500}\npre{background:#f5f6f9;padding:.5rem;border-radius:.3rem;overflow:auto;white-space:pre-wrap;overflow-wrap:anywhere;max-height:30rem}\npre.error{background:#fdecec}\nol.steps{padding-left:1.2rem}li.hook{color:#6b7385}ol.steps>li.hook:has(>details.hooks){list-style:none;margin-left:-1.2rem}\nimg.attachment{max-width:100%;border:1px solid #d8dbe3;margin:.3rem 0}\ndetails.scenario{margin:.4rem 0}\ndetails.attachment{margin:.2rem 0}details.attachment>summary{color:#5b6475;font-size:.85rem;cursor:pointer}\nul.readings{list-style:none;margin:.2rem 0;padding-left:.2rem}ul.readings li{overflow-wrap:anywhere}\nul.readings .ok{color:#135c2a}ul.readings .failed{color:#8a1616;font-weight:500}\nul.combination{margin:0;padding-left:1rem}\n";
+export declare const html: (value: unknown) => string;
+export declare const badge: (status: string) => string;
+export declare function renderHtmlReport(report: EvidenceReport, readImage?: (path: string) => string | undefined): string;

package/entrypoints/cli/src/reports/html.js

@@ -0,0 +1,178 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { hostBypassAudit } from "@parity/product-lab/shell/host-bypass-words";
+import { hostBypassLines } from "./host-bypass.js";
+import { readingBlockWords, sideReadings } from "@parity/product-lab/domain/checks";
+import { checkpointCounts, combinationEntries, duration as measured, environmentStart, rowCountsText, rowTimings, scenarioCounts } from "./metrics-text.js";
+const MAX_INLINE = 20_000;
+export const REPORT_STYLE = `body{font:14px/1.45 system-ui,-apple-system,sans-serif;margin:2rem auto;max-width:1100px;padding:0 1rem;color:#1d2433}
+h1{font-size:1.4rem}h2{font-size:1.1rem;margin:.2rem 0}
+.badge{display:inline-block;padding:0 .45rem;border-radius:.3rem;font-size:.8rem;font-weight:600;background:#e6e8ee;color:#1d2433}
+.badge.passed{background:#d6f5df;color:#135c2a}.badge.failed,.badge.over-budget,.badge.empty,.badge.undefined,.badge.ambiguous{background:#fbdada;color:#8a1616}
+.badge.unsupported,.badge.skipped,.badge.pending{background:#fdf1cf;color:#6b4a00}
+section{border:1px solid #d8dbe3;border-radius:.5rem;padding:.8rem 1rem;margin:1rem 0}
+section.failed,section.over-budget,section.empty{border-color:#e7a3a3}
+dl{display:grid;grid-template-columns:max-content 1fr;gap:.2rem 1rem;margin:.5rem 0}dt{color:#5b6475}dd{margin:0}
+.muted{color:#6b7385;font-size:.85rem}.reason{font-weight:500}
+pre{background:#f5f6f9;padding:.5rem;border-radius:.3rem;overflow:auto;white-space:pre-wrap;overflow-wrap:anywhere;max-height:30rem}
+pre.error{background:#fdecec}
+ol.steps{padding-left:1.2rem}li.hook{color:#6b7385}ol.steps>li.hook:has(>details.hooks){list-style:none;margin-left:-1.2rem}
+img.attachment{max-width:100%;border:1px solid #d8dbe3;margin:.3rem 0}
+details.scenario{margin:.4rem 0}
+details.attachment{margin:.2rem 0}details.attachment>summary{color:#5b6475;font-size:.85rem;cursor:pointer}
+ul.readings{list-style:none;margin:.2rem 0;padding-left:.2rem}ul.readings li{overflow-wrap:anywhere}
+ul.readings .ok{color:#135c2a}ul.readings .failed{color:#8a1616;font-weight:500}
+ul.combination{margin:0;padding-left:1rem}
+`;
+export const html = (value) => String(value).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+const clip = (text) => (text.length > MAX_INLINE ? `${text.slice(0, MAX_INLINE)}\n… (${text.length - MAX_INLINE} more characters in the run's report)` : text);
+export const badge = (status) => `<span class="badge ${html(status)}">${html(status)}</span>`;
+const verdictWords = (verdict, policy) => policy?.startsWith("allowed: ") ? `${verdict === "allowed" ? "allowed" : `${verdict}; allowed`} by its policy: ${policy.slice("allowed: ".length)}` : `${verdict}${policy ? `; ${policy}` : ""}`;
+const hostBypass = (evidence) => {
+    const raw = `<pre>${html(hostBypassLines(evidence).join("\n"))}</pre>`;
+    if (!evidence)
+        return `<details class="host-bypass"><summary>Host check: not recorded</summary>${raw}</details>`;
+    const audit = hostBypassAudit(evidence, { name: (id) => id });
+    const people = audit.people.flatMap((person) => [`${person.who}'s ${person.app}${person.host ? ` (${person.host})` : ""}: ${verdictWords(person.verdict, person.policy)}`, ...person.traffic.map((row) => `${person.who}: ${row.words}`)]);
+    const said = [...audit.why, ...audit.groups.map((group) => group.words), ...audit.explained.map((kind) => kind.words), ...people];
+    return `<details class="host-bypass"><summary>Host check: ${html(audit.headline)}</summary>${said.length ? `<ul>${said.map((line) => `<li>${html(line)}</li>`).join("")}</ul>` : ""}${raw}</details>`;
+};
+const duration = (ms) => (ms === undefined ? "" : ms < 1000 ? `${Math.round(ms)} ms` : `${(ms / 1000).toFixed(1)} s`);
+function readingsOf(json) {
+    if (!json || typeof json !== "object")
+        return [];
+    const calls = json.calls;
+    return [...sideReadings(json), ...(Array.isArray(calls) ? calls.flatMap((call) => sideReadings(call)) : [])];
+}
+function readingLines(readings) {
+    if (!readings.length)
+        return "";
+    const line = (reading) => {
+        const where = (reading.side === "chain" ? readingBlockWords(reading.at) : undefined) ?? reading.place;
+        const said = reading.ok ? reading.found : `expected ${reading.expected}; found ${reading.found}`;
+        return `<li class="${reading.ok ? "ok" : "failed"}">${reading.ok ? "✓" : "✗"} ${reading.side}, ${html(where)}: ${html(said)}</li>`;
+    };
+    return `<ul class="readings">${readings.map(line).join("")}</ul>`;
+}
+const size = (text) => (text.length < 1024 ? `${text.length} B` : `${Math.round(text.length / 1024)} KB`);
+const plural = (count, one, many = `${one}s`) => `${count} ${count === 1 ? one : many}`;
+function jsonSummary(json, text) {
+    const record = json && typeof json === "object" && !Array.isArray(json) ? json : undefined;
+    const readings = readingsOf(json);
+    const counted = readings.length ? `, ${plural(readings.length, "reading")}` : "";
+    if (record?.productLab === "step" && Array.isArray(record.calls)) {
+        const owners = [...new Set(record.calls.map((call) => call.owner).filter((owner) => typeof owner === "string"))];
+        return `call trace: ${plural(record.calls.length, "call")}${owners.length ? ` (${owners.join(", ")})` : ""}${counted}, ${size(text)}`;
+    }
+    if (readings.length && record && Object.keys(record).length === 1)
+        return `${plural(readings.length, "reading")}: ${readings.map((reading) => (reading.side === "chain" ? readingBlockWords(reading.at) : undefined) ?? reading.place).join(", ")}`;
+    if (Array.isArray(json))
+        return `data: ${plural(json.length, "item")}, ${size(text)}`;
+    const keys = record ? Object.keys(record) : [];
+    return `data: ${keys.slice(0, 5).join(", ")}${keys.length > 5 ? `, and ${keys.length - 5} more` : ""}${counted}, ${size(text)}`;
+}
+function textSummary(text) {
+    const lines = text.split("\n");
+    const first = lines.find((line) => line.trim())?.trim() ?? "";
+    return `text: ${first.length > 90 ? `${first.slice(0, 90)}…` : first}${lines.length > 1 ? ` (${plural(lines.length, "line")})` : ""}`;
+}
+function attachment(item, readImage) {
+    if (item.json !== undefined) {
+        const text = JSON.stringify(item.json, null, 2);
+        return `${readingLines(readingsOf(item.json))}<details class="attachment"><summary>${html(jsonSummary(item.json, text))}</summary><pre class="attachment">${html(clip(text))}</pre></details>`;
+    }
+    if (item.text !== undefined)
+        return `<details class="attachment"><summary>${html(textSummary(item.text))}</summary><pre class="attachment">${html(clip(item.text))}</pre></details>`;
+    if (item.path && item.mime.startsWith("image/")) {
+        const data = readImage(item.path);
+        return data ? `<img class="attachment" alt="${html(item.path)}" src="${html(data)}">` : `<p class="attachment">image: ${html(item.path)}</p>`;
+    }
+    return `<p class="attachment">${html(item.mime)}${item.path ? `: ${html(item.path)}` : ""}</p>`;
+}
+function stepItem(step, readImage, number) {
+    const error = [step.error, step.abortDetail].filter(Boolean).join("; ");
+    return `<li class="${html(step.status)}${step.hidden ? " hook" : ""}"${number === undefined ? "" : ` value="${number}"`}>${badge(step.status)} ${html(step.hidden ? step.name || "hook" : [step.keyword, step.name].filter(Boolean).join(" "))} <span class="muted">${duration(step.durationMs)}</span>${error ? `<pre class="error">${html(clip(error))}</pre>` : ""}${hostBypass(step.hostBypass)}${step.attachments.map((entry) => attachment(entry, readImage)).join("")}</li>`;
+}
+function hookGroup(hooks, readImage) {
+    const ms = hooks.reduce((total, hook) => total + (hook.durationMs ?? 0), 0);
+    return `<li class="hook"><details class="hooks"><summary>${hooks.length === 1 ? "1 hook" : `${hooks.length} hooks`} passed, ${duration(ms) || "0 ms"}</summary><ol>${hooks.map((hook) => stepItem(hook, readImage)).join("")}</ol></details></li>`;
+}
+function scenario(item, readImage) {
+    const parts = [];
+    let hooks = [];
+    const flush = () => {
+        if (hooks.length)
+            parts.push(hookGroup(hooks, readImage));
+        hooks = [];
+    };
+    let number = 0;
+    for (const step of item.steps) {
+        if (step.hidden && step.status === "passed" && !step.error)
+            hooks.push(step);
+        else {
+            flush();
+            parts.push(stepItem(step, readImage, ++number));
+        }
+    }
+    flush();
+    return `<details class="scenario"${item.status === "passed" ? "" : " open"}><summary>${badge(item.status)} ${html(item.name)} <span class="muted">${html(item.uri)}${item.line ? `:${item.line}` : ""} ${html(item.tags.join(" "))}</span></summary>${hostBypass(item.hostBypass)}<ol class="steps">${parts.join("")}</ol></details>`;
+}
+function suiteRowFacts(item) {
+    const combination = combinationEntries(item.combination);
+    return [
+        `<dt>scenarios</dt><dd>${html(scenarioCounts(item.counts, item.status))}</dd>`,
+        item.status === "unsupported" ? "" : `<dt>checkpoints</dt><dd>${html(checkpointCounts(item.counts))}</dd>`,
+        `<dt>environment start</dt><dd>${html(environmentStart(item))}</dd>`,
+        ...rowTimings(item).map(([label, value]) => `<dt>${html(label)}</dt><dd>${html(value)}</dd>`),
+        combination.length ? `<dt>combination</dt><dd><ul class="combination">${combination.map(([id, text]) => `<li><code>${html(id)}</code> ${html(text)}</li>`).join("")}</ul></dd>` : "",
+    ];
+}
+function suiteSummary(report) {
+    if (report.kind !== "suite")
+        return "";
+    if (!report.counts && !report.timings)
+        return `<section class="summary"><h2>Counts and timings</h2><p class="muted">not measured (this record was written without them)</p></section>`;
+    const facts = [
+        report.counts ? `<dt>rows</dt><dd>${html(rowCountsText(report.counts.rows))}</dd>` : "",
+        report.counts ? `<dt>scenarios</dt><dd>${html(scenarioCounts(report.counts.scenarios))}</dd>` : "",
+        report.counts ? `<dt>checkpoints</dt><dd>${html(checkpointCounts(report.counts.scenarios))}</dd>` : "",
+        report.timings ? `<dt>planning</dt><dd>${html(measured(report.timings.planMs))}</dd>` : "",
+        report.timings ? `<dt>critical path</dt><dd>${html(measured(report.timings.criticalPathMs))} (rows run one after the other)</dd>` : "",
+        report.timings ? `<dt>total</dt><dd>${html(measured(report.timings.totalMs))}</dd>` : "",
+    ].join("");
+    return `<section class="summary"><h2>Counts and timings</h2><dl>${facts}</dl></section>`;
+}
+function row(item, readImage, suite) {
+    const facts = [
+        item.tags ? `<dt>tags</dt><dd><code>${html(item.tags)}</code></dd>` : "",
+        item.environment ? `<dt>environment</dt><dd>${html(item.environment)}</dd>` : "",
+        item.host ? `<dt>host</dt><dd>${html(item.host)}</dd>` : "",
+        item.candidates && Object.keys(item.candidates).length
+            ? `<dt>versions</dt><dd>${Object.entries(item.candidates).map(([component, selector]) => `${html(component)}@${html(selector)}`).join(", ")}</dd>`
+            : `<dt>versions</dt><dd>locked</dd>`,
+        item.versionsManifest ? `<dt>resolution</dt><dd><code>${html(item.versionsManifest)}</code></dd>` : "",
+        item.run ? `<dt>run</dt><dd>${html(item.run.id)} (${html(item.run.status)}${item.run.error ? `: ${html(item.run.error)}` : ""}), report <code>${html(item.run.report)}</code></dd>` : "",
+        ...(suite ? suiteRowFacts(item) : [item.durationMs !== undefined ? `<dt>time</dt><dd>${duration(item.durationMs)}</dd>` : ""]),
+    ].join("");
+    const scenarios = (item.run?.scenarios ?? []).map((entry) => scenario(entry, readImage)).join("");
+    return `<section class="row ${html(item.status)}"><h2>${badge(item.status)} ${html(item.id)}</h2>${item.reason ? `<p class="reason">${html(item.reason)}</p>` : ""}<dl>${facts}</dl>${scenarios || (item.run ? '<p class="muted">No scenario ran.</p>' : "")}</section>`;
+}
+export function renderHtmlReport(report, readImage = () => undefined) {
+    const affected = report.affected
+        ? `<section class="affected"><h2>Affected selection</h2><p>${html(report.affected.reason)} (${html(report.affected.selection)}; scopes: ${html(report.affected.scopes.join(", ") || "none")})</p><p class="muted">${html(report.affected.source)}</p><details><summary>${report.affected.changed.length} changed path(s)</summary><pre>${html(report.affected.changed.join("\n"))}</pre></details></section>`
+        : "";
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${html(report.title)}: ${html(report.status)}</title>
+<style>
+${REPORT_STYLE}</style></head>
+<body>
+<h1>${badge(report.status)} ${html(report.title)}</h1>
+<p class="reason">${html(report.reason)}</p>
+<p class="muted">${html(report.id)}; ${duration(report.durationMs)}${report.budgetMs !== undefined ? ` of a ${duration(report.budgetMs)} budget` : ""}; written ${html(report.generatedAt)}</p>
+${suiteSummary(report)}
+${affected}
+${report.rows.map((item) => row(item, readImage, report.kind === "suite")).join("\n")}
+</body></html>
+`;
+}

package/entrypoints/cli/src/reports/junit.d.ts

@@ -0,0 +1,2 @@
+import type { EvidenceReport } from "./evidence-report.js";
+export declare function renderJunit(report: EvidenceReport): string;