scenescout 3.14.1 → 3.16.0

package/dist/engine/check.js

@@ -12,9 +12,11 @@
  */
 import { createHash } from "node:crypto";
 import { BROWSER_ENGINES } from "../browsers.js";
+import { BASELINE_MODES, baselineEvidence, baselineFingerprint, countStatuses, describeChange, parseThreshold, VISUAL_RULE, } from "./baseline.js";
 import { flowStepEvidence } from "./flow.js";
 import { parseLimitFlag } from "./limits.js";
-import { redactSecrets } from "./memory.js";
+import { redactRoute, redactSecrets } from "./memory.js";
+import { SARIF_ANCHOR_FALLBACKS, checkSarifAnchor, sarifFileFor, sarifLocation } from "./sarif.js";
 import { httpErrorDetail, httpStatusOf } from "./oracles.js";
 export const CHECK_SEVERITIES = ["high", "medium", "low"];
 export const FAIL_ON = [...CHECK_SEVERITIES, "never"];
@@ -65,7 +67,11 @@ export const CHECK_RULES = {
         title: "Control covered by pinned chrome",
         help: "A fixed or sticky element sits on top of the control, so clicks land on it instead.",
     },
-    "clipped-control": { severity: "medium", title: "Control unreachable", help: "The control is clipped inside a container that cannot scroll." },
+    "clipped-control": {
+        severity: "medium",
+        title: "Control unreachable",
+        help: "The control is clipped inside a container that cannot scroll and has no control beside it to page it.",
+    },
     "offpage-control": { severity: "medium", title: "Control outside the page", help: "The control is laid out where no scrolling can reach it." },
     "overlapping-controls": { severity: "low", title: "Controls overlap", help: "Two controls in the same layer cover most of each other." },
     "broken-image": { severity: "medium", title: "Broken image", help: "The browser could not render the image." },
@@ -78,7 +84,11 @@ export const CHECK_RULES = {
     contrast: { severity: "low", title: "Text contrast below WCAG", help: "Text needs 4.5:1 (3:1 when large) against its background." },
     "focus-indicator": { severity: "low", title: "No visible focus indicator", help: "Tabbing to the control changes nothing on screen." },
     "horizontal-scroll": { severity: "medium", title: "Page scrolls sideways", help: "Content is wider than the viewport." },
-    "tiny-target": { severity: "low", title: "Small click target", help: "Below the 24px WCAG 2.2 target-size minimum." },
+    "tiny-target": {
+        severity: "low",
+        title: "Small click target",
+        help: "Below the 24px WCAG 2.2 target-size minimum, measured on what the user clicks (a native input's label or drop zone), with another target inside its 24px circle.",
+    },
     "clipped-text": { severity: "low", title: "Text clipped", help: "Text is wider than its box and cut off without an ellipsis." },
     "image-aspect": { severity: "low", title: "Image distorted", help: "The rendered box does not match the image's proportions." },
     "flow-step-failed": {
@@ -86,6 +96,11 @@ export const CHECK_RULES = {
         title: "Saved flow broke",
         help: "A step of a flow saved in .scenescout/flows could not be done, or what it expected was not there. The evidence names the flow, the step and what happened instead.",
     },
+    [VISUAL_RULE]: {
+        severity: "high",
+        title: "Differs from its visual baseline",
+        help: "A page or element listed in the baselines' targets.json no longer looks like its baseline (--baseline compare): more of its pixels changed than --baseline-threshold allows, or its size changed. It is also filed when the page or element could not be captured at all, or its baseline cannot be used (half there, unreadable, or taken with other settings). An intended change is approved by running the check with --baseline update (and committing the new baseline, where the project keeps baselines in a folder it commits).",
+    },
 };
 /**
  * Rules whose measurement is exact and whose meaning depends on a convention
@@ -107,12 +122,19 @@ export const WORTH_A_LOOK_RULES = {
         help: "Links with no underline, in the same colour as the page's body text. In running text a reader cannot tell them from the text around them; in navigation this styling is common, and the check cannot tell the two apart.",
         convention: "a visible link style (an underline or a distinct colour) wherever links appear, navigation included",
     },
+    "scrolled-out-controls": {
+        title: "Controls scrolled out of view sideways",
+        help: "Controls inside a horizontally scrolling container (a wide table's last column, say) lie outside its visible width at this viewport, so only a sideways scroll of the container shows them. A wide table that scrolls is a common, deliberate layout; it matters where a project keeps every row's actions in view.",
+        convention: "row actions and other controls that stay in view without a sideways scroll of their container at this viewport width",
+    },
 };
 export const CHECK_RULE_IDS = [...Object.keys(CHECK_RULES), ...Object.keys(WORTH_A_LOOK_RULES)];
 export function isWorthALookRule(rule) {
     return Object.prototype.hasOwnProperty.call(WORTH_A_LOOK_RULES, rule);
 }
-const SEVERITY_RANK = { high: 0, medium: 1, low: 2 };
+export const SEVERITY_RANK = { high: 0, medium: 1, low: 2 };
+/** The route a defect of the app's shared shell is charged to: one fix, however many pages show it. */
+export const SHARED_CHROME_ROUTE = "(shared chrome)";
 /** Snapshot refs (`e12`) are numbered per run; evidence carrying them would never match itself twice. */
 function stripRefs(line) {
     return line.replace(/\be\d+\s+/g, "").trim();
@@ -166,6 +188,8 @@ export function geometryRule(line) {
         return "offpage-control";
     if (/ overlaps /.test(line))
         return "overlapping-controls";
+    if (/ scrolled out of view inside a horizontally scrolling container /.test(line))
+        return "scrolled-out-controls";
     return "layout-issue";
 }
 /**
@@ -180,16 +204,28 @@ export function geometryRule(line) {
  *
  * A fact under a worth-a-look rule goes to `worthALook` instead, deduplicated
  * the same way; the two lists never share an entry.
+ *
+ * Visual baselines add one issue per target that is not met (baseline.ts
+ * decides which). Each target is its own fact already, so these skip the
+ * dedup, and their fingerprint comes from the target, not the evidence: the
+ * evidence carries this run's percentage, and the same target changing by a
+ * different amount is still the same alert.
  */
-export function checkFindings(routes, origin, ignore = [], flows = []) {
+export function checkFindings(routes, origin, ignore = [], flows = [], baselines = null) {
     const byKey = new Map();
     const looks = new Map();
+    /** Evidence as it is written: no origin, no secret, and bounded. */
+    const cleanEvidence = (evidence) => redactSecrets(withoutOrigin(evidence, origin)).slice(0, 300);
     const add = (rule, evidence, route, opts = {}) => {
         if (ignore.includes(rule))
             return;
-        const clean = redactSecrets(withoutOrigin(evidence, origin)).slice(0, 300);
+        const clean = cleanEvidence(evidence);
         const key = `${rule}\u0000${clean}`;
-        const found = byKey.get(key) ?? looks.get(key);
+        const issue = byKey.get(key);
+        // A fact a crawled page and a flow both show points at the flow: the flow is the file that reproduces it.
+        if (issue && opts.flow && !issue.flow)
+            issue.flow = opts.flow;
+        const found = issue ?? looks.get(key);
         if (found) {
             if (!found.routes.includes(route))
                 found.routes.push(route);
@@ -206,6 +242,7 @@ export function checkFindings(routes, origin, ignore = [], flows = []) {
             evidence: clean,
             routes: [route],
             ...(opts.embed ? { embed: opts.embed } : {}),
+            ...(opts.flow ? { flow: opts.flow } : {}),
             fingerprint,
         });
     };
@@ -238,17 +275,32 @@ export function checkFindings(routes, origin, ignore = [], flows = []) {
         for (const p of r.placeholderOnly)
             add("placeholder-only-label", p, route);
         for (const d of r.design)
-            add(d.rule, d.detail, d.chrome ? "(shared chrome)" : route);
+            add(d.rule, d.detail, d.chrome ? SHARED_CHROME_ROUTE : route);
     }
     for (const f of flows) {
         for (const { path, violation } of f.violations)
-            add(violationRule(violation), violation.detail, path, { embed: violation.embed });
+            add(violationRule(violation), violation.detail, path, { embed: violation.embed, flow: f.file });
         // A refused step is not the app's defect: the check reports it as "could not run" (refusedFlowReason).
         if (f.outcome.status === "failed")
-            add("flow-step-failed", flowStepEvidence(f), f.outcome.path);
+            add("flow-step-failed", flowStepEvidence(f), f.outcome.path, { flow: f.file });
+    }
+    const visual = [];
+    if (baselines && !ignore.includes(VISUAL_RULE)) {
+        for (const r of baselines.results) {
+            const evidence = baselineEvidence(r, baselines);
+            if (evidence === null)
+                continue;
+            visual.push({
+                rule: VISUAL_RULE,
+                severity: CHECK_RULES[VISUAL_RULE].severity,
+                evidence: cleanEvidence(evidence),
+                routes: [r.path],
+                fingerprint: baselineFingerprint(baselines.engine, r),
+            });
+        }
     }
     return {
-        issues: [...byKey.values()].sort((a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity] || a.rule.localeCompare(b.rule)),
+        issues: [...byKey.values(), ...visual].sort((a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity] || a.rule.localeCompare(b.rule)),
         worthALook: [...looks.values()].sort((a, b) => a.rule.localeCompare(b.rule)),
     };
 }
@@ -290,15 +342,8 @@ export function withoutOwnResponse(r) {
     const own = httpErrorDetail("GET", r.url.replace(/#.*$/, ""), r.status);
     return { ...r, violations: r.violations.filter((v) => !(v.kind === "http_error" && v.detail === own)) };
 }
-/**
- * Routes are links the app printed, and a link can carry a token
- * (`?reset=…`, `?api_key=…`). Evidence is redacted where issues are built;
- * this does the same for every route string before anything is written.
- */
-export function redactRoute(route) {
-    // The trailing "[n secrets redacted]" note belongs to prose; in a route it would read as part of the path.
-    return redactSecrets(route).replace(/ \[\d+ secrets? redacted\]$/, "");
-}
+/** Lives beside redactSecrets so the baselines' file names (baseline.ts) use it too; exported here as before. */
+export { redactRoute };
 export function redactRoutes(routes) {
     const clean = redactRoute;
     return routes.map((r) => ({
@@ -308,6 +353,16 @@ export function redactRoutes(routes) {
         violations: r.violations.map((v) => ({ ...v, url: clean(v.url) })),
     }));
 }
+/**
+ * The same redaction for visual baselines: a target's path, and the reason a
+ * picture could not be taken, which can quote a URL the app redirected to.
+ */
+export function redactBaselineRun(run) {
+    return {
+        ...run,
+        results: run.results.map((r) => ({ ...r, path: redactRoute(r.path), ...(r.detail !== undefined ? { detail: redactSecrets(r.detail) } : {}) })),
+    };
+}
 /** The same redaction for what flows measured: the page paths and the request URLs their violations quote. */
 export function redactFlowRuns(runs) {
     return runs.map((f) => ({
@@ -365,9 +420,19 @@ export const CHECK_OPTION_NAMES = [
     "gate-retests",
     "action-timeout-ms",
     "nav-timeout-ms",
+    "baseline",
+    "baselines",
+    "baseline-threshold",
+    "sarif-file-anchor",
 ];
 export const MAX_CHECK_ROUTES = 150;
+/** Link discovery rounds: each crawl reveals the routes its pages link to. Past a few, a site is paginating rather than revealing. */
+export const MAX_DISCOVERY_ROUNDS = 6;
 export const DEFAULT_CHECK_ROUTES = 50;
+/** A path given on the command line, resolved from the directory the command runs in; the same on every platform. */
+export function resolveArgPath(cwd, p) {
+    return p.startsWith("/") || /^[A-Za-z]:[\\/]/.test(p) ? p : `${cwd.replace(/[\\/]$/, "")}/${p}`;
+}
 /** Parse `scenescout check` arguments. Every mistake is a sentence, never a half-configured run. */
 export function parseCheckArgs(args, cwd) {
     const positional = [];
@@ -461,7 +526,23 @@ export function parseCheckArgs(args, cwd) {
     const gateRetests = oneOf("gate-retests", GATE_RETESTS, DEFAULT_SETTINGS.gateRetests);
     if (!gateRetests)
         return { ok: false, error: `--gate-retests must be one of ${GATE_RETESTS.join(", ")}` };
-    const resolve = (p) => (p.startsWith("/") || /^[A-Za-z]:[\\/]/.test(p) ? p : `${cwd.replace(/[\\/]$/, "")}/${p}`);
+    const baseline = oneOf("baseline", BASELINE_MODES, "off");
+    if (!baseline)
+        return { ok: false, error: `--baseline must be one of ${BASELINE_MODES.join(", ")}` };
+    const threshold = parseThreshold(flags.get("baseline-threshold"));
+    if (!threshold.ok)
+        return threshold;
+    const baselinesDir = flags.get("baselines");
+    if (baselinesDir !== undefined && baselinesDir.trim() === "")
+        return { ok: false, error: "--baselines needs a directory" };
+    // A setting that would do nothing is a mistake to point out, not to ignore: the check would run without the baselines asked for.
+    if (baseline === "off" && (baselinesDir !== undefined || flags.has("baseline-threshold"))) {
+        return { ok: false, error: "--baselines and --baseline-threshold apply only with --baseline compare or --baseline update" };
+    }
+    const anchor = flags.has("sarif-file-anchor") ? checkSarifAnchor(flags.get("sarif-file-anchor")) : undefined;
+    if (anchor && !anchor.ok)
+        return anchor;
+    const resolve = (p) => resolveArgPath(cwd, p);
     return {
         ok: true,
         options: {
@@ -482,6 +563,10 @@ export function parseCheckArgs(args, cwd) {
             flowWrites,
             onRefusedStep,
             gateRetests,
+            baseline,
+            ...(baselinesDir !== undefined ? { baselinesDir: resolve(baselinesDir) } : {}),
+            baselineThreshold: threshold.value,
+            ...(anchor ? { sarifFileAnchor: anchor.value } : {}),
         },
     };
 }
@@ -535,10 +620,13 @@ export function describeSettings(result) {
 }
 const SARIF_LEVEL = { high: "error", medium: "warning", low: "note" };
 /**
- * SARIF 2.1.0, for code-scanning dashboards. A UI check has no source file to
- * point at, so each result's location is the route, relative to the checked
- * app (the APP base id). Fingerprints come from the evidence, not the
- * location, so a preview deployment on a new URL does not reopen every alert.
+ * SARIF 2.1.0, for code-scanning dashboards. Code scanning keeps a result
+ * only when its location is a repository file, so each result points at one
+ * (sarif.ts says which) and carries its routes in logical locations, in
+ * `properties.routes` and in its message. Fingerprints come from the
+ * evidence, not the location, so a preview deployment on a new URL does not
+ * reopen every alert; an unmet visual baseline's comes from its target and
+ * browser instead.
  */
 const RETEST_SARIF_RULE = {
     id: "open-finding-reproduces",
@@ -547,39 +635,39 @@ const RETEST_SARIF_RULE = {
     help: { text: "A finding an earlier run filed and left open failed the same way when its page loaded again. It gates according to --gate-retests." },
     defaultConfiguration: { level: "error" },
 };
-function sarifLocation(route) {
-    return route === "(shared chrome)"
-        ? {
-            physicalLocation: { artifactLocation: { uri: "", uriBaseId: "APP" } },
-            message: { text: "the app's shared shell, on every page that renders it" },
-        }
-        : { physicalLocation: { artifactLocation: { uri: route.replace(/^\//, ""), uriBaseId: "APP" } } };
+function routeLocation(file, route) {
+    return route === SHARED_CHROME_ROUTE ? sarifLocation(file, route, "the app's shared shell, on every page that renders it") : sarifLocation(file, route);
 }
-export function toSarif(result, toolVersion) {
+/** Where a result was seen, for its message: the first three routes and how many more. */
+function onRoutes(routes) {
+    return ` — on ${routes.slice(0, 3).join(", ")}${routes.length > 3 ? ` and ${routes.length - 3} more` : ""}`;
+}
+/** `files` defaults to package.json as the anchor, with no flows directory; the CLI always passes what it resolved. */
+export function toSarif(result, toolVersion, files = { anchor: SARIF_ANCHOR_FALLBACKS[0] }) {
     const used = [...new Set(result.issues.map((i) => i.rule))];
     const lookRules = [...new Set(result.worthALook.map((o) => o.rule))];
-    const base = new URL(result.url);
     const reproducing = retestGateFailures(result);
     const refused = result.flows.filter((f) => f.outcome.status === "refused");
     const issueResults = result.issues.map((i) => ({
         ruleId: i.rule,
         level: SARIF_LEVEL[i.severity],
         message: {
-            text: `${CHECK_RULES[i.rule].title}: ${i.evidence}${i.routes.length > 1 ? ` (on ${i.routes.length} routes)` : ""}${i.embed ? ` (in an embed of ${i.embed})` : ""}`,
+            text: `${CHECK_RULES[i.rule].title}: ${i.evidence}${i.embed ? ` (in an embed of ${i.embed})` : ""}${onRoutes(i.routes)}`,
         },
-        locations: i.routes.slice(0, 10).map(sarifLocation),
+        locations: i.routes.slice(0, 10).map((route) => routeLocation(sarifFileFor(files, i.flow), route)),
         partialFingerprints: { "scenescoutCheck/v1": i.fingerprint },
+        properties: { routes: i.routes, ...(i.flow ? { flow: i.flow } : {}) },
     }));
     // Always "note", whatever --fail-on says: a result a code-scanning dashboard shows, never one that reads as an error.
     const lookResults = result.worthALook.map((o) => ({
         ruleId: o.rule,
         level: "note",
         message: {
-            text: `Worth a look — ${WORTH_A_LOOK_RULES[o.rule].title}: ${o.evidence}${o.routes.length > 1 ? ` (on ${o.routes.length} routes)` : ""}. A defect only if your project uses ${o.convention}.`,
+            text: `Worth a look — ${WORTH_A_LOOK_RULES[o.rule].title}: ${o.evidence}${onRoutes(o.routes)}. A defect only if your project uses ${o.convention}.`,
         },
-        locations: o.routes.slice(0, 10).map(sarifLocation),
+        locations: o.routes.slice(0, 10).map((route) => routeLocation(files.anchor, route)),
         partialFingerprints: { "scenescoutCheck/v1": o.fingerprint },
-        properties: { tier: "worth-a-look", convention: o.convention },
+        properties: { tier: "worth-a-look", convention: o.convention, routes: o.routes },
     }));
     // Only the re-tests that fail the gate are results: a reviewer reading code scanning sees what failed it.
     const retestResults = reproducing.map((r) => ({
@@ -587,9 +675,10 @@ export function toSarif(result, toolVersion) {
         // The severity the finding was filed at, as the page rules map theirs; an unknown one reads as the worst.
         level: SARIF_LEVEL[CHECK_SEVERITIES.includes(r.severity) ? r.severity : "high"],
         message: {
-            text: `Open finding still reproduces: [${r.severity}] ${r.title} (${r.id}) — ${r.signatures.join(", ")} (gated by --gate-retests ${result.settings.gateRetests})`,
+            text: `Open finding still reproduces: [${r.severity}] ${r.title} (${r.id}) — ${r.signatures.join(", ")}${onRoutes([r.path])} (gated by --gate-retests ${result.settings.gateRetests})`,
         },
-        locations: [{ physicalLocation: { artifactLocation: { uri: r.path.replace(/^\//, ""), uriBaseId: "APP" } } }],
+        locations: [routeLocation(files.anchor, r.path)],
+        properties: { routes: [r.path] },
         partialFingerprints: { "scenescoutCheck/v1": createHash("sha256").update(`retest\u0000${r.id}`).digest("hex").slice(0, 32) },
     }));
     return {
@@ -633,7 +722,7 @@ export function toSarif(result, toolVersion) {
                         })),
                     },
                 ],
-                originalUriBaseIds: { APP: { uri: `${base.origin}/` } },
+                properties: { app: new URL(result.url).origin },
                 results: [...issueResults, ...lookResults, ...retestResults],
             },
         ],
@@ -659,10 +748,126 @@ function code(text) {
     const pad = longest > 0 ? " " : "";
     return `${fence}${pad}${text}${pad}${fence}`;
 }
+/** The first three routes as code spans, and how many more. */
 function routeList(routes) {
     const shown = routes.slice(0, 3).map(code);
     return shown.join(", ") + (routes.length > 3 ? ` and ${routes.length - 3} more` : "");
 }
+const BASELINE_MARK = {
+    matches: "✓",
+    changed: "✗",
+    "no-baseline": "○",
+    unusable: "✗",
+    "not-captured": "⊘",
+    updated: "↻",
+};
+/** One target's line in the report. */
+function baselineLine(r, run) {
+    const what = `${BASELINE_MARK[r.status]} ${code(r.element)} on ${code(r.path)}`;
+    const notes = [r.platformNote, r.partial]
+        .filter(Boolean)
+        .map((n) => ` _(${cell(n)})_`)
+        .join("");
+    switch (r.status) {
+        case "matches":
+            return `- ${what}: ${run.mode === "update" ? `within the threshold of its baseline (${r.diff?.percent ?? 0}% changed), which was left as it was` : `matches (${r.diff?.percent ?? 0}% changed)`}${notes}`;
+        case "changed": {
+            const files = r.files ? ` — expected ${code(r.files.expected)}, now ${code(r.files.actual)}, diff ${code(r.files.diff)}` : "";
+            return `- ${what}: ${r.diff ? describeChange(r.diff, run.threshold) : "it no longer matches its baseline"}${files}${notes}`;
+        }
+        case "no-baseline":
+            return `- ${what}: no baseline yet${notes}`;
+        case "unusable":
+            return `- ${what}: its baseline cannot be used: ${cell(r.detail ?? "no reason given")}`;
+        case "not-captured":
+            return `- ${what}: could not be captured: ${cell(r.detail ?? "no reason given")}${run.mode === "update" ? "; its baseline was not written" : ""}`;
+        case "updated":
+            return `- ${what}: baseline written to ${code(r.baseline)} (${cell(r.detail ?? "updated")})${notes}`;
+    }
+}
+/** The report's section on visual baselines: every target and what became of it. */
+function formatBaselines(run) {
+    const c = countStatuses(run.results);
+    const counts = [
+        ["changed", "changed"],
+        ["unusable", "unusable"],
+        ["not-captured", "not captured"],
+        ["no-baseline", "no baseline yet"],
+        ["updated", "updated"],
+        ["matches", run.mode === "update" ? "left as they were" : "match"],
+    ]
+        .filter(([k]) => c[k] > 0)
+        .map(([k, label]) => `${c[k]} ${label}`)
+        .join(" · ");
+    const lines = [
+        `## Visual baselines (${run.results.length})`,
+        "",
+        `${run.mode === "update" ? "Updated" : "Compared"} in ${run.engine}, baselines in ${code(run.dir)} · ${run.threshold}% of a picture's pixels may change · ${counts}`,
+        "",
+        ...run.results.map((r) => baselineLine(r, run)),
+    ];
+    if (c.changed > 0)
+        lines.push("", "The pictures are beside this report, under `visual/` (in the job's artifact on CI): the baseline, the picture now, and the changed pixels in red.");
+    if (c["no-baseline"] > 0 || c.unusable > 0) {
+        lines.push("", "A target with no baseline yet is listed and never fails; one whose baseline cannot be used fails until it is taken again. Run the check with `--baseline update` to take them.");
+    }
+    if (run.results.some((r) => r.platformNote)) {
+        lines.push("", "_Some baselines were taken on another operating system. Each one draws text differently, so a change there may be the system's rather than the app's: take baselines where the check runs._");
+    }
+    return lines;
+}
+/** One markdown list item for an issue: its title, rule, evidence and routes. */
+export function issueLine(i) {
+    return `**${CHECK_RULES[i.rule].title}** \`${i.rule}\`: ${cell(i.evidence)}${i.embed ? ` _(in an embed of ${i.embed}: its behaviour, not the app's)_` : ""} — ${routeList(i.routes)}`;
+}
+/** The issues, one section per severity, worst first. Shared by the check's report and the first run's. */
+export function issueSections(issues) {
+    const lines = [];
+    for (const sev of CHECK_SEVERITIES) {
+        const of = issues.filter((i) => i.severity === sev);
+        if (of.length === 0)
+            continue;
+        lines.push("", `## ${sev[0].toUpperCase()}${sev.slice(1)} (${of.length})`, "");
+        for (const i of of)
+            lines.push(`- ${issueLine(i)}`);
+    }
+    return lines;
+}
+const WORTH_A_LOOK_INTRO = "Measured exactly, and defects only under a convention of your project that the check cannot see.";
+/** The worth-a-look section, or nothing when there is none. `gated`: the report is a gate's, so say these never fail it. */
+export function worthALookSection(observations, gated = true) {
+    if (observations.length === 0)
+        return [];
+    const lines = [
+        "",
+        `## Worth a look (${observations.length})`,
+        "",
+        `${WORTH_A_LOOK_INTRO} They are not counted above${gated ? " and never fail the gate, at any --fail-on" : ""}.`,
+        "",
+    ];
+    for (const o of observations) {
+        lines.push(`- **${WORTH_A_LOOK_RULES[o.rule].title}** \`${o.rule}\`: ${cell(o.evidence)} — a defect only if your project uses ${o.convention} — ${routeList(o.routes)}`);
+    }
+    return lines;
+}
+/** The table of routes measured, with each one's status, controls and issue count. */
+export function routesTable(result) {
+    const lines = ["", "## Routes", "", "| Route | Status | Controls | Issues |", "|---|---|---|---|"];
+    for (const r of result.routes) {
+        const n = result.issues.filter((i) => i.routes.includes(r.path)).length;
+        const status = (r.loadError !== undefined ? "did not load" : r.loginRedirect ? `${r.status ?? "?"} → sign-in` : String(r.status ?? "?")) +
+            (r.auditError ? ` (design not measured: ${cell(r.auditError.slice(0, 80))})` : "");
+        // Plain text, not a code span: inside a table cell a code span keeps the backslashes cell() adds.
+        lines.push(`| ${cell(r.path)} | ${status} | ${r.elements} | ${n} |`);
+    }
+    return lines;
+}
+/** The routes known and not visited, as one line; nothing when every known route was visited. */
+export function unvisitedLine(unvisited, why) {
+    if (unvisited.length === 0)
+        return [];
+    return ["", `Not visited (${why}): ${unvisited.slice(0, 20).map(code).join(", ")}${unvisited.length > 20 ? " …" : ""}`];
+}
 /** The human report: the verdict first, then what failed it, then everything else. */
 export function formatCheck(result) {
     const { passed, counts, failing, retestsFailing, couldNotRun } = summarise(result);
@@ -672,6 +877,8 @@ export function formatCheck(result) {
     lines.push(`${result.url} · ${result.routes.length} route(s) · mode ${result.mode} · gate: ${result.failOn === "never" ? "report only" : `fail on ${result.failOn}${result.failOn === "low" ? "" : " or worse"}`}`);
     lines.push("");
     const unaudited = unauditedRoutes(result.routes).length;
+    // Nothing compared is not a match: a target with no baseline yet is named beside the verdict, as an unmeasured design is.
+    const uncompared = result.baselines?.mode === "compare" ? countStatuses(result.baselines.results)["no-baseline"] : 0;
     const failingText = retestsFailing > 0
         ? `${failing} failing the gate (${failing - retestsFailing} issue(s), ${retestsFailing} re-tested finding(s))`
         : `${failing} issue(s) at the gate's severity`;
@@ -680,35 +887,14 @@ export function formatCheck(result) {
             ? `${couldNotRun > 0 ? "passed" : "**PASSED**"} — ${counts.high} high · ${counts.medium} medium · ${counts.low} low`
             : `${couldNotRun > 0 ? "failed" : "**FAILED**"} — ${failingText} · ${counts.high} high · ${counts.medium} medium · ${counts.low} low`) +
         (unaudited > 0 ? ` · design not measured on ${unaudited} route(s)` : "") +
+        (uncompared > 0 ? ` · ${uncompared} visual target(s) not compared: no baseline yet` : "") +
         (result.worthALook.length > 0 ? ` · ${result.worthALook.length} worth a look, never gated` : ""));
     // Right under the verdict: what a green check was allowed to do is part of what it means.
     lines.push("", `Settings — ${describeSettings(result)}`);
-    for (const sev of CHECK_SEVERITIES) {
-        const of = result.issues.filter((i) => i.severity === sev);
-        if (of.length === 0)
-            continue;
-        lines.push("", `## ${sev[0].toUpperCase()}${sev.slice(1)} (${of.length})`, "");
-        for (const i of of) {
-            lines.push(`- **${CHECK_RULES[i.rule].title}** \`${i.rule}\`: ${cell(i.evidence)}${i.embed ? ` _(in an embed of ${i.embed}: its behaviour, not the app's)_` : ""} — ${routeList(i.routes)}`);
-        }
-    }
-    if (result.worthALook.length > 0) {
-        lines.push("", `## Worth a look (${result.worthALook.length})`, "", "Measured exactly, and defects only under a convention of your project that the check cannot see. They are not counted above and never fail the gate, at any --fail-on.", "");
-        for (const o of result.worthALook) {
-            lines.push(`- **${WORTH_A_LOOK_RULES[o.rule].title}** \`${o.rule}\`: ${cell(o.evidence)} — a defect only if your project uses ${o.convention} — ${routeList(o.routes)}`);
-        }
-    }
-    lines.push("", "## Routes", "", "| Route | Status | Controls | Issues |", "|---|---|---|---|");
-    for (const r of result.routes) {
-        const n = result.issues.filter((i) => i.routes.includes(r.path)).length;
-        const status = (r.loadError !== undefined ? "did not load" : r.loginRedirect ? `${r.status ?? "?"} → sign-in` : String(r.status ?? "?")) +
-            (r.auditError ? ` (design not measured: ${cell(r.auditError.slice(0, 80))})` : "");
-        // Plain text, not a code span: inside a table cell a code span keeps the backslashes cell() adds.
-        lines.push(`| ${cell(r.path)} | ${status} | ${r.elements} | ${n} |`);
-    }
-    if (result.unvisited.length > 0) {
-        lines.push("", `Not visited (over --max-routes): ${result.unvisited.slice(0, 20).map(code).join(", ")}${result.unvisited.length > 20 ? " …" : ""}`);
-    }
+    lines.push(...issueSections(result.issues));
+    lines.push(...worthALookSection(result.worthALook));
+    lines.push(...routesTable(result));
+    lines.push(...unvisitedLine(result.unvisited, "over --max-routes"));
     if (result.flows.length > 0 || result.skippedFlows.length > 0) {
         lines.push("", `## Flows (${result.flows.length})`, "");
         for (const f of result.flows) {
@@ -726,6 +912,8 @@ export function formatCheck(result) {
         for (const s of result.skippedFlows)
             lines.push(`- skipped ${code(s.file)}: ${cell(s.reason)}`);
     }
+    if (result.baselines)
+        lines.push("", ...formatBaselines(result.baselines));
     if (result.retest && result.retest.open > 0) {
         const { open, results } = result.retest;
         lines.push("", `## Open findings re-tested (${results.length} of ${open})`, "");
@@ -778,6 +966,7 @@ export function toSummaryJson(result, toolVersion) {
             ...(r.auditError !== undefined ? { designNotMeasured: r.auditError } : {}),
         })),
         unvisited: result.unvisited,
+        ...(result.timeBudget ? { timeBudget: result.timeBudget } : {}),
         ignored: result.ignored,
         flows: result.flows.map((f) => ({
             name: f.name,
@@ -790,6 +979,7 @@ export function toSummaryJson(result, toolVersion) {
         })),
         skippedFlows: result.skippedFlows,
         retest: result.retest,
+        baselines: result.baselines ?? null,
         issues: result.issues,
         // Apart from `issues` and `counts`, which the gate reads: none of these is counted or gated.
         worthALook: result.worthALook,