@reticlehq/server 3.8.2 → 3.10.0

package/dist/features/compare/build-readings.js

@@ -0,0 +1,250 @@
+/**
+ * Drive one build through an action plan and read what it shows after each planned sequence.
+ *
+ * The page is read only after it settles: read, wait, read again, until two reads in a row match,
+ * up to `SETTLE_READS` reads. A page that never settles (a slideshow) gives its last read.
+ *
+ * A sequence that starts another planned sequence is not driven on its own: the longer one is
+ * driven, and the page is read after each of its steps. Each planned sequence is read once, in the
+ * first run that reaches it, and the order is the same on every build.
+ *
+ * Each reading also holds what the app did since the sequence's first action: its network calls and
+ * console errors and warnings (`effect-lines.ts`), read from the cursor that first action returned.
+ *
+ * A step that could not be done (the control is not there, or the action was refused) is recorded
+ * for that sequence and each longer one in the run. A driver that lost its browser session throws
+ * `DriverLostError`: that says nothing about the build, so the caller makes the whole run invalid.
+ */
+import { ActionType } from '@reticlehq/core';
+import { isPendingLine } from './outside/effect-lines.js';
+import { ControlKind, FaultKind, firstRef, longestRuns, refFor, sequenceKey, stepLabel, } from './action-plan.js';
+import { structureLines } from './visible-content.js';
+const FAULT_ANSWER = {
+    [FaultKind.SERVER]: { status: 500, body: '{"error":"fault"}' },
+    [FaultKind.ABORT]: { abort: true },
+    [FaultKind.EMPTY]: { status: 200, body: '[]' },
+};
+/** The start page again: an empty query keeps the url as it is. */
+const RELOAD = '';
+/** The driver lost its browser session. The run says nothing about the build. */
+export class DriverLostError extends Error {
+    name = 'DriverLostError';
+}
+export const SETTLE_READS = 4;
+export const SETTLE_GAP_MS = 400;
+/** The first action of every sequence. */
+export const START_STEP = 'open the start page';
+/** Elapsed times in a page's own log ("0.04s") change between two runs. Keep whole seconds. */
+const ELAPSED = /(?<![\w.])(\d+\.\d+)(?:s\b|$)/g;
+/** An elapsed time in milliseconds ("3ms", "1400 ms"). */
+const ELAPSED_MS = /(?<![\w.])(\d+(?:\.\d+)?) ?ms\b/g;
+const MS_PER_S = 1000;
+/** A line with its sub-second elapsed times rounded to whole seconds. */
+const roundTimes = (line) => line
+    .replace(ELAPSED_MS, (_, n) => `${String(Math.round(Number(n) / MS_PER_S))}s`)
+    .replace(ELAPSED, (_, n) => `${String(Math.round(Number(n)))}s`);
+/**
+ * What a person sees on the page, one line for each element, with the role of each control and
+ * structure element kept (`structureLines`) and sub-second times rounded.
+ */
+export function pageLines(tree) {
+    return structureLines(tree).map(roundTimes);
+}
+const same = (a, b) => a.length === b.length && a.every((line, i) => line === b[i]);
+/** Read the page once it stops changing. */
+export async function settledRead(driver, sleep) {
+    let tree = await driver.read();
+    let lines = pageLines(tree);
+    for (let i = 1; i < SETTLE_READS; i += 1) {
+        await sleep(SETTLE_GAP_MS);
+        const nextTree = await driver.read();
+        const next = pageLines(nextTree);
+        tree = nextTree;
+        const settled = same(next, lines);
+        lines = next;
+        if (settled) {
+            return { tree, lines, settled: true };
+        }
+    }
+    return { tree, lines, settled: false };
+}
+/** What the app did since `since`, with times rounded like page text. None before the first act. */
+async function effectsSince(driver, since) {
+    return since === undefined ? [] : (await driver.effects(since)).map(roundTimes);
+}
+/** The ref of `target`, reading again while the page is still settling. */
+async function locate(driver, tree, target, sleep) {
+    let now = tree;
+    for (let i = 1; i < SETTLE_READS; i += 1) {
+        const ref = refFor(now, target);
+        if (ref !== undefined) {
+            return { ref, tree: now };
+        }
+        await sleep(SETTLE_GAP_MS);
+        now = await driver.read();
+    }
+    const ref = refFor(now, target);
+    return ref === undefined ? { tree: now } : { ref, tree: now };
+}
+/**
+ * Do one step on the page `tree` shows. `ok` is false when it could not be done. `since` is the
+ * cursor from before its first action.
+ */
+async function perform(driver, step, tree, sleep) {
+    if ('wait' === step.action) {
+        await sleep(step.ms);
+        return { ok: true };
+    }
+    if ('goto' === step.action) {
+        return { ok: true === (await driver.goto?.(step.query)) };
+    }
+    if ('fault' === step.action) {
+        const rule = { urlContains: step.path, method: step.method, ...FAULT_ANSWER[step.fault] };
+        // Loaded again, so the requests the start page makes on load also see the fault.
+        const set = true === (await driver.mock?.([rule]));
+        return { ok: set && true === (await driver.goto?.(RELOAD)) };
+    }
+    if ('press' === step.action) {
+        const ref = firstRef(tree);
+        return ref === undefined ? { ok: false } : driver.act(ref, ActionType.PRESS, step.key);
+    }
+    const acts = 'fillall' === step.action
+        ? step.fields.map((f) => ({ action: 'fill', target: f.target, value: f.value }))
+        : [step];
+    let now = tree;
+    let since;
+    for (const act of acts) {
+        // A text probe is one click, never part of "fill every field".
+        if (act.target.text !== undefined) {
+            return driver.act({ text: act.target.text }, ControlKind.CLICK);
+        }
+        const found = await locate(driver, now, act.target, sleep);
+        now = found.tree;
+        if (found.ref === undefined) {
+            return { ok: false };
+        }
+        const value = 'click' === act.action ? undefined : act.value;
+        const done = await driver.act(found.ref, act.action, value);
+        since ??= done.since;
+        if (!done.ok) {
+            return { ok: false };
+        }
+    }
+    return since === undefined ? { ok: true } : { ok: true, since };
+}
+/**
+ * Drive one sequence from a fresh load, for the plan, or undefined when a step could not be done.
+ *
+ * For a sequence that ends in a wait, the page is also read, settled, before the wait. The wait is
+ * `active` when the page did not settle before it, a network call was still pending before it, or
+ * the page changed during it.
+ */
+export async function probeSequence(driver, seq, sleep) {
+    if (!(await driver.open())) {
+        return undefined;
+    }
+    let tree = await driver.read();
+    let since;
+    let busy = false;
+    let before;
+    for (const [i, step] of seq.entries()) {
+        const last = i === seq.length - 1;
+        if (last && 'wait' === step.action) {
+            const read = await settledRead(driver, sleep);
+            const pending = (await effectsSince(driver, since)).some(isPendingLine);
+            busy = !read.settled || pending;
+            before = read.lines;
+        }
+        const done = await perform(driver, step, tree, sleep);
+        if (!done.ok) {
+            return undefined;
+        }
+        since ??= done.since;
+        // The last step is followed by the settled read.
+        if (!last) {
+            tree = await driver.read();
+        }
+    }
+    const after = await settledRead(driver, sleep);
+    const changed = before !== undefined && !same(before, after.lines);
+    const effects = await effectsSince(driver, since);
+    return { tree: after.tree, active: busy || changed, effects };
+}
+const labelsOf = (seq) => [START_STEP, ...seq.map(stepLabel)];
+/**
+ * Drive the plan on one build. With `readState`, the app's stored data is read after each sequence
+ * is read, and its lines (`outside/state-sources.ts`) follow the page and effect lines.
+ */
+export async function readBuild(driver, plan, sleep, readState) {
+    const planned = new Set(plan.map(sequenceKey));
+    const out = new Map();
+    const isNew = (seq) => {
+        const key = sequenceKey(seq);
+        return planned.has(key) && !out.has(key);
+    };
+    /** The cursor of the current run's first action. */
+    let since;
+    /** Read after `seq`: settled and recorded the first time, else one read for the refs. */
+    /** Set while a run is tried again: the step that failed on the first pass. */
+    let retrying;
+    const take = async (seq) => {
+        if (!isNew(seq)) {
+            return driver.read();
+        }
+        const read = await settledRead(driver, sleep);
+        const lines = [...read.lines, ...(await effectsSince(driver, since))];
+        if (readState !== undefined) {
+            lines.push(...(await readState()));
+        }
+        out.set(sequenceKey(seq), {
+            actions: labelsOf(seq),
+            lines,
+            ...(retrying === undefined ? {} : { retriedAt: retrying }),
+        });
+        return read.tree;
+    };
+    const failFrom = (run, from, failedAt) => {
+        for (let n = from; n <= run.length; n += 1) {
+            const seq = run.slice(0, n);
+            if (isNew(seq)) {
+                out.set(sequenceKey(seq), { actions: labelsOf(seq), failedAt });
+            }
+        }
+    };
+    /** One pass over `run` from a fresh page. Returns the failed step's index, or undefined when every step was done. */
+    const pass = async (run) => {
+        since = undefined;
+        let tree = await take([]);
+        for (const [i, step] of run.entries()) {
+            const done = await perform(driver, step, tree, sleep);
+            if (!done.ok) {
+                return i;
+            }
+            since ??= done.since;
+            tree = await take(run.slice(0, i + 1));
+        }
+        return undefined;
+    };
+    for (const run of longestRuns(plan)) {
+        if (!(await driver.open())) {
+            failFrom(run, 0, START_STEP);
+            continue;
+        }
+        let failed = await pass(run);
+        // A step that fails once can be timing (a select whose options load late, on a loaded machine): try the run
+        // ONE more time from a fresh page before it counts as a step the build could not do. A real breakage fails
+        // again. Never silently: the readings the retry records carry `retriedAt`, and the comparison lists them,
+        // because a fault that comes and goes is a fault. Readings already taken are kept.
+        const first = failed === undefined ? undefined : run[failed];
+        if (first !== undefined && (await driver.open())) {
+            retrying = stepLabel(first);
+            failed = await pass(run);
+            retrying = undefined;
+        }
+        if (failed !== undefined) {
+            const step = run[failed];
+            failFrom(run, failed + 1, step === undefined ? START_STEP : stepLabel(step));
+        }
+    }
+    return out;
+}

package/dist/features/compare/compare-diff.d.ts

@@ -0,0 +1,62 @@
+/** One step of one journey, as one build showed it. */
+export interface StepReading {
+    /** The journey's position in the run. The same on every build, because every build gets one list. */
+    journey: number;
+    /** The step's position in its journey. */
+    step: number;
+    /** What was done to reach this step, in order, ending with this step's own action. */
+    actions: readonly string[];
+    /** The visible lines after the step. Absent when the step could not be done. */
+    lines?: readonly string[];
+}
+export declare const DifferenceKind: {
+    /** The step was done on both builds, and they show different lines. */
+    readonly CHANGED: "changed";
+    /** The reference did the step, and the candidate could not. */
+    readonly UNREACHED: "unreached";
+};
+export type DifferenceKind = (typeof DifferenceKind)[keyof typeof DifferenceKind];
+export interface Difference {
+    /** A hash of the difference's lines: the same lines give the same id on every run. */
+    id: string;
+    kind: DifferenceKind;
+    /** The actions that first reached it. */
+    actions: readonly string[];
+    /** Lines only the reference shows. */
+    removed: readonly string[];
+    /** Lines only the candidate shows. */
+    added: readonly string[];
+    /** At how many steps this same difference was seen. */
+    seen: number;
+}
+export interface Comparison {
+    differences: Difference[];
+    /** Steps both builds did, and were compared. */
+    compared: number;
+    /** Steps the reference did on only one of its two runs, so they were not compared. */
+    unstable: number;
+    /** Lines that differed but were ignored, because they also differed between the reference runs. */
+    ignored: number;
+}
+/** A short stable id for a difference: the hash of what it holds. */
+export declare const differenceId: (content: unknown) => string;
+/** Lines only in `a` (removed) and only in `b` (added). */
+export declare function lineDiff(a: readonly string[], b: readonly string[]): {
+    removed: string[];
+    added: string[];
+};
+/**
+ * The lines of `got` that differ from `ours`, with the noise removed. A line that differs between
+ * `ours` and `repeat` (two runs of the reference) is noise, and so is a line `alsoNoise` names.
+ * `ignored` counts the lines removed as noise.
+ */
+export declare function maskedDiff(ours: readonly string[], repeat: readonly string[], got: readonly string[], alsoNoise?: (line: string) => boolean): {
+    removed: string[];
+    added: string[];
+    ignored: number;
+};
+/**
+ * Every difference between the candidate and the reference, in the order the reference reached it.
+ * `again` is the second run of the reference, which sets what is noise.
+ */
+export declare function compareReadings(reference: readonly StepReading[], again: readonly StepReading[], candidate: readonly StepReading[]): Comparison;

package/dist/features/compare/compare-diff.js

@@ -0,0 +1,177 @@
+/**
+ * The differences between what two builds show, after the same actions.
+ *
+ * Each build gives one reading for each step of each journey: the visible lines after that step, or
+ * no lines when the step could not be done. The reference is read two times. A line that differs
+ * between those two runs changes with no change to the build (a clock, a random id), so it is
+ * ignored at that step. A step the reference did on only one of its runs is not compared at all.
+ *
+ * Differences with the same lines are one difference, with one id: a renamed header shows at every
+ * step after it, and a reader needs to see it once.
+ *
+ * A step the candidate could not do is a difference, unless the step before it in the same journey
+ * already showed a difference. That difference is the cause (the button was renamed, so the click
+ * on the old name found nothing), and a reader needs it once.
+ */
+import { createHash } from 'node:crypto';
+export const DifferenceKind = {
+    /** The step was done on both builds, and they show different lines. */
+    CHANGED: 'changed',
+    /** The reference did the step, and the candidate could not. */
+    UNREACHED: 'unreached',
+};
+const ID_LENGTH = 12;
+const HASH = 'sha256';
+const HEX = 'hex';
+/** A short stable id for a difference: the hash of what it holds. */
+export const differenceId = (content) => createHash(HASH).update(JSON.stringify(content)).digest(HEX).slice(0, ID_LENGTH);
+const keyOf = (r) => `${String(r.journey)}:${String(r.step)}`;
+/** The runs of lines only in `a` (removed) and only in `b` (added), from a longest common subsequence. */
+function hunks(a, b) {
+    // ponytail: O(n*m) table; a page is tens to a few hundred lines. Use Myers if pages reach thousands.
+    const table = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
+    const at = (i, j) => table[i]?.[j] ?? 0;
+    for (let i = a.length - 1; i >= 0; i -= 1) {
+        const row = table[i];
+        for (let j = b.length - 1; j >= 0 && row !== undefined; j -= 1) {
+            row[j] = a[i] === b[j] ? at(i + 1, j + 1) + 1 : Math.max(at(i + 1, j), at(i, j + 1));
+        }
+    }
+    const out = [];
+    let open = { removed: [], added: [] };
+    const close = () => {
+        if (open.removed.length > 0 || open.added.length > 0) {
+            out.push(open);
+            open = { removed: [], added: [] };
+        }
+    };
+    let i = 0;
+    let j = 0;
+    while (i < a.length && j < b.length) {
+        if (a[i] === b[j]) {
+            close();
+            i += 1;
+            j += 1;
+        }
+        else if (at(i + 1, j) >= at(i, j + 1)) {
+            open.removed.push(a[i] ?? '');
+            i += 1;
+        }
+        else {
+            open.added.push(b[j] ?? '');
+            j += 1;
+        }
+    }
+    open.removed.push(...a.slice(i));
+    open.added.push(...b.slice(j));
+    close();
+    return out;
+}
+/** Lines only in `a` (removed) and only in `b` (added). */
+export function lineDiff(a, b) {
+    const all = hunks(a, b);
+    return { removed: all.flatMap((h) => h.removed), added: all.flatMap((h) => h.added) };
+}
+/**
+ * The lines of one hunk that are not noise. A reference line that also changed between the two
+ * reference runs is noise, and so is the candidate line in its place: a clock reads 10:01, 10:02 and
+ * 10:03 on three runs, and none of the three is a change to the build.
+ *
+ * A noise line the candidate shows in its place counts first, so a real change next to a counter
+ * in the same hunk is kept.
+ *
+ * ponytail: "in its place" is by count inside the hunk, so a real change next to a clock whose new
+ * value is not noise can still be ignored with it. Align by position if that is seen in practice.
+ */
+function unmasked(hunk, isNoise) {
+    const removed = hunk.removed.filter((line) => !isNoise(line));
+    const addedNoise = hunk.added.filter(isNoise).length;
+    let replaced = Math.max(0, hunk.removed.length - removed.length - addedNoise);
+    const added = hunk.added.filter((line) => {
+        if (isNoise(line)) {
+            return false;
+        }
+        if (replaced > 0) {
+            replaced -= 1;
+            return false;
+        }
+        return true;
+    });
+    return { removed, added };
+}
+/**
+ * The lines of `got` that differ from `ours`, with the noise removed. A line that differs between
+ * `ours` and `repeat` (two runs of the reference) is noise, and so is a line `alsoNoise` names.
+ * `ignored` counts the lines removed as noise.
+ */
+export function maskedDiff(ours, repeat, got, alsoNoise = () => false) {
+    const noise = lineDiff(ours, repeat);
+    const set = new Set([...noise.removed, ...noise.added]);
+    const masked = (line) => set.has(line) || alsoNoise(line);
+    const removed = [];
+    const added = [];
+    let ignored = 0;
+    for (const hunk of hunks(ours, got)) {
+        const kept = unmasked(hunk, masked);
+        removed.push(...kept.removed);
+        added.push(...kept.added);
+        ignored += hunk.removed.length + hunk.added.length - kept.removed.length - kept.added.length;
+    }
+    return { removed, added, ignored };
+}
+/**
+ * Every difference between the candidate and the reference, in the order the reference reached it.
+ * `again` is the second run of the reference, which sets what is noise.
+ */
+export function compareReadings(reference, again, candidate) {
+    const second = new Map(again.map((r) => [keyOf(r), r]));
+    const theirs = new Map(candidate.map((r) => [keyOf(r), r]));
+    const found = new Map();
+    const blocked = new Set();
+    /** Journeys whose last compared step showed a difference. */
+    const differed = new Set();
+    let compared = 0;
+    let unstable = 0;
+    let ignored = 0;
+    const note = (difference, content) => {
+        const id = differenceId(content);
+        const known = found.get(id);
+        if (known === undefined) {
+            found.set(id, { id, seen: 1, ...difference });
+        }
+        else {
+            known.seen += 1;
+        }
+    };
+    for (const ours of reference) {
+        const repeat = second.get(keyOf(ours))?.lines;
+        if (ours.lines === undefined || blocked.has(ours.journey)) {
+            continue;
+        }
+        if (repeat === undefined) {
+            unstable += 1;
+            continue;
+        }
+        const got = theirs.get(keyOf(ours))?.lines;
+        if (got === undefined) {
+            // Only the first step: the steps after it were not tried, and that is the same one cause.
+            blocked.add(ours.journey);
+            if (differed.has(ours.journey)) {
+                continue;
+            }
+            const action = ours.actions.at(-1) ?? '';
+            note({ kind: DifferenceKind.UNREACHED, actions: ours.actions, removed: [], added: [] }, { unreached: action });
+            continue;
+        }
+        compared += 1;
+        const { removed, added, ignored: skipped } = maskedDiff(ours.lines, repeat, got);
+        ignored += skipped;
+        if (0 === removed.length && 0 === added.length) {
+            differed.delete(ours.journey);
+            continue;
+        }
+        differed.add(ours.journey);
+        note({ kind: DifferenceKind.CHANGED, actions: ours.actions, removed, added }, { removed, added });
+    }
+    return { differences: [...found.values()], compared, unstable, ignored };
+}

package/dist/features/compare/compare-report-html.d.ts

@@ -0,0 +1,6 @@
+import type { compareReportJson } from './behaviour-report.js';
+type CompareReport = ReturnType<typeof compareReportJson>;
+export declare const REPORT_TITLE = "Reticle compare";
+/** The report page for one comparison. */
+export declare function compareReportHtml(report: CompareReport): string;
+export {};

package/dist/features/compare/compare-report-html.js

@@ -0,0 +1,102 @@
+/**
+ * `reticle compare --report <file>`: the comparison as one HTML page a person opens, shares or attaches to CI. It is
+ * built from the `--json` object, so the page and the JSON never disagree. It is self-contained: no script, no external
+ * style, no font. Every value is escaped, because the lines come from the pages under test: a page that shows
+ * `<script>` must not run it inside the report.
+ */
+import { CompareVerdict } from './behaviour-diff.js';
+import { DifferenceKind } from './compare-diff.js';
+export const REPORT_TITLE = 'Reticle compare';
+const TXT = {
+    reference: 'Reference',
+    candidate: 'Candidate',
+    base: 'Base',
+    compared: 'sequences compared',
+    ignored: 'lines ignored (they also changed between two runs of the reference)',
+    unstable: 'not compared: the reference did not do them the same way twice',
+    referenceFailed: 'not compared: the reference could not do them',
+    steps: 'Steps',
+    onlyReference: 'Only the reference shows',
+    onlyCandidate: 'Only the candidate shows',
+    unreached: 'The candidate could not do this step',
+    same: 'No difference in what users see, in the sequences compared.',
+    invalid: 'This run proves nothing, so nothing was proved. Reason:',
+    generated: 'Generated by reticle compare. Nothing was installed in either app.',
+};
+const VERDICT_TEXT = {
+    [CompareVerdict.SAME]: 'SAME',
+    [CompareVerdict.DIFFERENT]: 'DIFFERENT',
+    [CompareVerdict.INVALID]: 'INVALID',
+};
+/** Design values, in one place (the report is outside the app's design system). */
+const STYLE = `
+:root { --bg:#fbfbfa; --fg:#1c1c1a; --muted:#6b6b66; --line:#e4e3df; --card:#ffffff;
+  --same:#1f7a45; --diff:#b42318; --invalid:#8a6d00; --add-bg:#e9f6ee; --rem-bg:#fdecec; --mono:ui-monospace,SFMono-Regular,Menlo,monospace; }
+@media (prefers-color-scheme: dark) { :root { --bg:#141413; --fg:#ecebe7; --muted:#a3a29c; --line:#2c2c29; --card:#1c1c1a;
+  --same:#4cc27e; --diff:#ff7b6b; --invalid:#e0c04a; --add-bg:#16301f; --rem-bg:#3a1a17; } }
+* { box-sizing:border-box } body { margin:0; background:var(--bg); color:var(--fg); font:15px/1.5 system-ui,sans-serif }
+main { max-width:960px; margin:0 auto; padding:24px 16px 48px }
+h1 { font-size:20px; margin:0 0 4px } .verdict { font-weight:700; letter-spacing:.04em }
+.SAME { color:var(--same) } .DIFFERENT { color:var(--diff) } .INVALID { color:var(--invalid) }
+.urls, .counts { color:var(--muted); margin:4px 0 } .urls code { color:var(--fg); overflow-wrap:anywhere }
+.card { background:var(--card); border:1px solid var(--line); border-radius:8px; padding:12px 14px; margin:14px 0 }
+.card h2 { font-size:14px; margin:0 0 6px; color:var(--muted) }
+ol.steps { margin:4px 0 8px 18px; padding:0 } pre { margin:4px 0; padding:8px; border-radius:6px; white-space:pre-wrap;
+  overflow-wrap:anywhere; font:13px/1.45 var(--mono) } .rem { background:var(--rem-bg) } .add { background:var(--add-bg) }
+.side { font-size:13px; color:var(--muted); margin-top:6px } footer { color:var(--muted); font-size:13px; margin-top:28px }
+`;
+const esc = (s) => String(s)
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+function differenceCard(d, n) {
+    const steps = `<ol class="steps">${d.actions.map((a) => `<li>${esc(a)}</li>`).join('')}</ol>`;
+    const seen = `Seen in ${String(d.seen)} sequence${1 === d.seen ? '' : 's'}`;
+    if (d.kind === DifferenceKind.UNREACHED) {
+        return `<section class="card"><h2>#${String(n)} · ${esc(seen)}</h2><div class="side">${TXT.steps}</div>${steps}<div class="side">${TXT.unreached}</div><pre class="rem">${esc(d.failedAt ?? '')}</pre></section>`;
+    }
+    const side = (label, cls, lines) => 0 === lines.length
+        ? ''
+        : `<div class="side">${label}</div><pre class="${cls}">${esc(lines.join('\n'))}</pre>`;
+    return `<section class="card"><h2>#${String(n)} · ${esc(seen)}</h2><div class="side">${TXT.steps}</div>${steps}${side(TXT.onlyReference, 'rem', d.removed)}${side(TXT.onlyCandidate, 'add', d.added)}</section>`;
+}
+/** The report page for one comparison. */
+export function compareReportHtml(report) {
+    const verdict = VERDICT_TEXT[report.verdict] ?? String(report.verdict);
+    const urls = [
+        `${TXT.reference}: <code>${esc(report.reference)}</code>`,
+        `${TXT.candidate}: <code>${esc(report.candidate)}</code>`,
+        ...(report.base === undefined ? [] : [`${TXT.base}: <code>${esc(report.base)}</code>`]),
+    ];
+    const counts = [
+        `<b>${String(report.compared)}</b> of ${String(report.sequences)} ${TXT.compared}`,
+        `<b>${String(report.ignored)}</b> ${TXT.ignored}`,
+        ...(report.unstable > 0 ? [`<b>${String(report.unstable)}</b> ${TXT.unstable}`] : []),
+        ...(report.referenceFailed > 0
+            ? [`<b>${String(report.referenceFailed)}</b> ${TXT.referenceFailed}`]
+            : []),
+    ];
+    let body;
+    if (report.verdict === CompareVerdict.INVALID) {
+        body = `<section class="card"><p>${TXT.invalid}</p><pre>${esc(report.reason ?? '')}</pre></section>`;
+    }
+    else if (0 === report.differences.length) {
+        body = `<section class="card"><p>${TXT.same}</p></section>`;
+    }
+    else {
+        body = report.differences.map((d, i) => differenceCard(d, i + 1)).join('\n');
+    }
+    return [
+        '<!doctype html>',
+        '<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">',
+        `<title>${REPORT_TITLE}: ${verdict}</title><style>${STYLE}</style></head><body><main>`,
+        `<h1>${REPORT_TITLE}: <span class="verdict ${verdict}">${verdict}</span></h1>`,
+        ...urls.map((u) => `<p class="urls">${u}</p>`),
+        `<p class="counts">${counts.join(' · ')}</p>`,
+        body,
+        `<footer>${TXT.generated}</footer>`,
+        '</main></body></html>',
+    ].join('\n');
+}

package/dist/features/compare/compare-report.d.ts

@@ -0,0 +1,15 @@
+import type { CompareResult } from './compare-run.js';
+/** The version of the `--results-json` file this writes. */
+export declare const COMPARE_SCHEMA_VERSION = 1;
+interface Urls {
+    reference: string;
+    candidate: string;
+}
+export declare function compareExit(result: CompareResult): number;
+export declare function compareLines(urls: Urls, result: CompareResult): string[];
+/** The `--results-json` file. Every count the text gives is here too, so nothing is dropped silently. */
+export declare function compareJson(urls: Urls, result: CompareResult): Urls & CompareResult & {
+    schemaVersion: number;
+    identical: boolean;
+};
+export {};