scenescout 3.14.1 → 3.16.0

package/dist/engine/open.js

@@ -0,0 +1,118 @@
+/**
+ * Opening the live view and the report in the user's default browser.
+ *
+ * The live view's address and the report's path are printed in tool results,
+ * but a person in a chat client may never see or follow them. The `open`
+ * setting has the engine open them itself: the live view when a session
+ * attaches, the report when scout_report writes it.
+ *
+ * Whether to open is decided here, by a pure function of the setting and the
+ * environment, so every case is table-tested. Opening goes through the
+ * platform opener with no shell, and only ever hands it a loopback URL or an
+ * absolute file path. The live view's own rules (loopback only, a token on
+ * every path, ADR 7) are unchanged: opening an address reaches nobody new.
+ *
+ * Nothing here imports Playwright, and the spawn is injected, so a test never
+ * launches a browser.
+ */
+import path from "node:path";
+import { isCiEnv } from "./capture.js";
+/** The environment variable that sets `open` for every session of the server. A `scout_attach` `open` wins over it. */
+export const OPEN_ENV = "SCENESCOUT_OPEN";
+export const OPEN_CHOICES = ["live", "report", "both", "none"];
+/** `SCENESCOUT_OPEN`, or undefined when unset. A value outside the choices is refused rather than ignored. */
+export function openChoiceFromEnv(env) {
+    const raw = (env[OPEN_ENV] ?? "").trim();
+    if (raw === "")
+        return undefined;
+    if (!OPEN_CHOICES.includes(raw))
+        throw new Error(`${OPEN_ENV} must be one of ${OPEN_CHOICES.join(", ")}, not ${JSON.stringify(raw)}`);
+    return raw;
+}
+/**
+ * Nobody would see a window opened from here: a session over SSH, where the
+ * browser would open on the remote machine if at all, or a Linux or other
+ * Unix machine with no display server. macOS and Windows always have one.
+ */
+export function noDisplay(env, platform) {
+    if (env.SSH_CONNECTION || env.SSH_TTY)
+        return true;
+    if (platform === "darwin" || platform === "win32")
+        return false;
+    return !env.DISPLAY && !env.WAYLAND_DISPLAY;
+}
+const both = (choice, why) => ({
+    live: choice === "live" || choice === "both",
+    report: choice === "report" || choice === "both",
+    why,
+});
+/**
+ * What opens. A setting, from the attach or the environment, is followed as
+ * given. With none, both open on a local desktop session, whether the
+ * session's browser is headed or headless and whatever the MCP client
+ * declares: what a client declares is outside this project's control, and a
+ * person in a chat client is the one who most needs the page opened. Nothing
+ * opens in CI or where no display would show it. A developer who wants no
+ * tabs sets SCENESCOUT_OPEN=none.
+ */
+export function decideOpen(choice, ctx) {
+    if (choice)
+        return both(choice, `open is set to ${choice}`);
+    if (isCiEnv(ctx.env))
+        return both("none", "a CI run");
+    if (noDisplay(ctx.env, ctx.platform))
+        return both("none", "no display to show a window on");
+    return both("both", "a local desktop session");
+}
+/**
+ * Only what the engine itself produced may be opened: the live view's
+ * loopback address (plain http, no credentials) or an absolute path to a file.
+ * Anything else — a remote URL, a relative path, something that could read as
+ * an option to the opener — is refused.
+ */
+export function openableTarget(target) {
+    if (target === "" || /[\0-\x1f\x7f]/.test(target) || target.startsWith("-"))
+        return false;
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(target)) {
+        let u;
+        try {
+            u = new URL(target);
+        }
+        catch {
+            return false;
+        }
+        return u.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(u.hostname) && !u.username && !u.password;
+    }
+    return path.isAbsolute(target) || path.win32.isAbsolute(target);
+}
+/**
+ * The platform's opener, run directly with the target as its only argument.
+ * Windows' `start` is a cmd.exe built-in and cannot run without a shell, so
+ * Windows uses the URL protocol handler `start` itself relies on.
+ */
+export function openerCommand(platform, target) {
+    if (platform === "darwin")
+        return { command: "open", args: [target] };
+    if (platform === "win32")
+        return { command: "rundll32", args: ["url.dll,FileProtocolHandler", target] };
+    return { command: "xdg-open", args: [target] };
+}
+/**
+ * Hand a target to the platform opener. Refuses a target openableTarget does
+ * not accept. The opener runs detached and is not waited for; a failure to
+ * start it (no xdg-open installed, say) arrives later through onError.
+ */
+export function openInBrowser(target, deps) {
+    if (!openableTarget(target))
+        return { ok: false, why: "only the live view's loopback address or an absolute file path is opened" };
+    const { command, args } = openerCommand(deps.platform, target);
+    try {
+        const child = deps.spawn(command, args, { shell: false, stdio: "ignore", detached: true });
+        child.on("error", (err) => deps.onError(`${command} could not start: ${err.message}`));
+        child.unref();
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, why: `${command} could not start: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}

package/dist/engine/oracles.js

@@ -1,4 +1,15 @@
 import { redactSecrets } from "./memory.js";
+/** Every kind of violation the oracles record. One list, so the report's plain wording can be held equal to it. */
+export const ORACLE_KINDS = [
+    "console_error",
+    "page_error",
+    "request_failed",
+    "http_error",
+    "dom_injection",
+    "refused_empty",
+    "false_success",
+    "postmessage_token",
+];
 /** How an HTTP error violation states its request. One formatter, so a reader of the detail (the check) cannot drift from its writer. */
 export function httpErrorDetail(method, url, status) {
     return `${method} ${url.slice(0, 200)} → HTTP ${status}`;
@@ -21,6 +32,19 @@ export function redactViolation(v) {
 }
 /** How long after a write-policy block a generic "fetch failed" error is still attributed to it. */
 export const POLICY_BLOCK_WINDOW_MS = 2000;
+/**
+ * How a block surfaces in an error's wording: the browser's own lines for a
+ * dropped request or the stand-in 403, the status as HTTP clients word their
+ * rejection ("Request failed with status code 403", "403 Forbidden"), and the
+ * stand-in body's own sentence echoed into an error. A 403 alone with neither
+ * word is left out: "Error 403 at line 12" is not the policy.
+ */
+const POLICY_INDUCED_RE = [
+    /ERR_BLOCKED_BY_CLIENT|Failed to fetch|NetworkError when attempting to fetch|Load failed|the server responded with a status of 403\b/i,
+    /\bstatus(?: code)?:? 403\b/i,
+    /\b403\b[^\n]{0,40}\b(?:forbidden|refused)\b|\b(?:forbidden|refused)\b[^\n]{0,40}\b403\b/i,
+    /refused by the tester's [a-z-]+ write policy/i,
+];
 /**
  * Is this console or page error a consequence of the tester's OWN write-policy
  * block rather than something the app did?
@@ -42,7 +66,7 @@ export function isPolicyInduced(v, msSincePolicyBlock) {
         return false;
     if (v.kind !== "page_error" && v.kind !== "console_error")
         return false;
-    return /ERR_BLOCKED_BY_CLIENT|Failed to fetch|NetworkError when attempting to fetch|Load failed|the server responded with a status of 403\b/i.test(v.detail);
+    return POLICY_INDUCED_RE.some((re) => re.test(v.detail));
 }
 /**
  * The request a console message is the browser's own echo of, or null when it
@@ -106,6 +130,78 @@ export class EmbedRequestLog {
         return key === null ? null : (this.byKey.get(key) ?? null);
     }
 }
+/** How long after a replay ends the browser's console echo of its failure is still taken for the replay's. */
+export const REPLAY_ECHO_WINDOW_MS = 2000;
+/**
+ * Addresses the tester is calling with scout_request, so the browser's console
+ * echo of a refused probe ("Failed to load resource: … 403") is known as the
+ * tester's and not charged to the page. The request itself is matched by
+ * identity in the monitor; the echo carries only an address, so it is matched
+ * by address while the replay is in flight and for a short window after, which
+ * is when the browser prints it. Bounded, dropping the oldest.
+ */
+export class ReplayLog {
+    cap;
+    /** Address → until when an echo of it is the replay's (Infinity while in flight). */
+    until = new Map();
+    constructor(cap = 200) {
+        this.cap = cap;
+    }
+    begin(url) {
+        const key = requestKey(url);
+        this.until.delete(key);
+        this.until.set(key, Infinity);
+        if (this.until.size > this.cap)
+            this.until.delete(this.until.keys().next().value);
+    }
+    end(url, now) {
+        const key = requestKey(url);
+        if (this.until.has(key))
+            this.until.set(key, now + REPLAY_ECHO_WINDOW_MS);
+    }
+    /** Whether a console message is the browser's echo of a replay's failed load. */
+    echoes(text, locationUrl, pageUrl, now) {
+        const key = failedLoadEchoOf(text, locationUrl, pageUrl);
+        if (key === null)
+            return false;
+        const until = this.until.get(key);
+        if (until === undefined)
+            return false;
+        if (now > until) {
+            this.until.delete(key);
+            return false;
+        }
+        return true;
+    }
+}
+/**
+ * Wording of a router cancelling a route change on purpose. Some client-side
+ * routers can only stop a navigation (to keep a dirty form, say) by throwing
+ * from their route-change event, and the apps that use them filter this
+ * sentinel out of their own error monitoring. Narrow on purpose: it must name
+ * the route and the cancelling.
+ */
+const ROUTE_CANCEL_RE = /\brout(?:e|ing)\b.{0,40}\b(?:abort|cancel)|\b(?:abort|cancel)\w*\b.{0,40}\brout(?:e|ing)\b/i;
+/**
+ * Is this uncaught page error a router deliberately cancelling a route change,
+ * rather than a crash? Only for a click that left the URL where it was, and
+ * then only when the message says so, or when the click asked for a route
+ * change and the page put up a confirmation instead. Still reported, at
+ * medium with a note: the error is real and uncaught, but the user never sees
+ * it, and ranking it with crashes made every such page argue it away.
+ */
+export function isRouteCancellation(message, c) {
+    if (!c.byClick || c.urlChanged)
+        return false;
+    return ROUTE_CANCEL_RE.test(message) || (c.viaLink && c.dialogOpened);
+}
+/** Appended to a page error read as a route-change cancellation, saying which evidence it was read on. */
+export function routeCancelNote(message) {
+    const why = ROUTE_CANCEL_RE.test(message)
+        ? "the click left the URL unchanged and the error says the route change was cancelled"
+        : "the click on a link left the URL unchanged and the page opened a dialog instead";
+    return ` (likely a router cancelling the route change on purpose: ${why}; reported at medium, check what the page showed before filing)`;
+}
 /**
  * Invariant oracles: passive listeners that record violations regardless of
  * what the agent is doing. The engine drains the buffer after every action and
@@ -124,6 +220,11 @@ export class OracleMonitor {
             // Benign noise: failed favicon / source map fetches show up as console errors.
             if (/favicon|source map/i.test(text))
                 return;
+            // The browser's echo of the tester's own scout_request: its answer was in that tool's result.
+            if (this.replays.echoes(text, msg.location().url, page.url(), Date.now())) {
+                this.replayAttributed += 1;
+                return;
+            }
             this.record({
                 kind: "console_error",
                 severity: "high",
@@ -150,6 +251,10 @@ export class OracleMonitor {
                 return;
             if (BENIGN_URL_RE.test(req.url()))
                 return;
+            if (this.isReplay(req)) {
+                this.replayAttributed += 1;
+                return;
+            }
             if (this.refusedByPolicy(req)) {
                 this.policyAttributed += 1;
                 return;
@@ -170,6 +275,12 @@ export class OracleMonitor {
             // reported here on every page load teaches the driver to ignore http_error.
             if (BENIGN_URL_RE.test(res.url()))
                 return;
+            // The tester's own scout_request: a probe of a boundary is meant to be
+            // refused, and its answer was in that tool's result, not the page's.
+            if (this.isReplay(res.request())) {
+                this.replayAttributed += 1;
+                return;
+            }
             // The write policy's own stand-in refusal, matched by request identity
             // like a dropped one: the server never said this.
             if (this.refusedByPolicy(res.request())) {
@@ -205,6 +316,44 @@ export class OracleMonitor {
      * errors look the same.
      */
     policyAttributed = 0;
+    isReplay = () => false;
+    replays = new ReplayLog();
+    /** Failures of the tester's own scout_request calls, kept out of the page's violations and counted. */
+    replayAttributed = 0;
+    /**
+     * The engine knows which requests are its own scout_request replays, by
+     * identity; their failures are the tester's probes, not the page's.
+     */
+    setReplayCheck(check) {
+        this.isReplay = check;
+    }
+    /** A scout_request call to this address is starting: the browser's echo of its failure is the tester's. */
+    replayStarted(url) {
+        this.replays.begin(url);
+    }
+    /** That call has returned; its echo is still expected for a short window. */
+    replayEnded(url) {
+        this.replays.end(url, Date.now());
+    }
+    /** Whether a page error was recorded since `since` (ms) and not yet drained. */
+    hasPageErrorSince(since) {
+        return this.buffer.some((v) => v.kind === "page_error" && Date.parse(v.at) >= since);
+    }
+    /**
+     * Re-rank the page errors this click raised that read as a router
+     * cancelling a route change (isRouteCancellation). Done before the drain, so
+     * the action's result, the session log and the report all see one verdict.
+     */
+    downgradeRouteCancellations(since, c) {
+        for (const v of this.buffer) {
+            if (v.kind !== "page_error" || v.severity !== "high" || Date.parse(v.at) < since)
+                continue;
+            if (!isRouteCancellation(v.detail, c))
+                continue;
+            v.severity = "medium";
+            v.detail += routeCancelNote(v.detail);
+        }
+    }
     embedOfRequest = () => null;
     embedRequests = new EmbedRequestLog();
     /**
@@ -241,7 +390,7 @@ export class OracleMonitor {
      * it is reported through here rather than by a page event.
      */
     noteContradiction(c, url) {
-        this.record({ kind: c.kind, severity: "high", detail: c.detail, url });
+        this.record({ kind: c.kind, severity: c.severity ?? "high", detail: c.detail, url });
     }
     /**
      * The page posted a token-shaped value with targetOrigin "*" (postmessage.ts).
@@ -299,6 +448,22 @@ export class OracleMonitor {
         return out;
     }
 }
+/**
+ * Violations a plan run with onViolation "continue" goes on past: an error
+ * status, and the console's echo of one. They say a step's page answered
+ * badly, which in a sweep of independent steps (tabs, filters, pages) is a
+ * result to list, not a reason the next step cannot run. Anything else (an
+ * uncaught exception, a failed request, typed markup coming back, a page
+ * contradicting the server, a token posted to any origin) stops a plan either way.
+ */
+export const CONTINUABLE_KINDS = new Set(["http_error", "console_error"]);
+/** Whether these violations, drained after one plan step, end the plan. Repeats of already-reported violations never do. */
+export function planStopsAt(violations, rule) {
+    const fresh = violations.filter((v) => !v.repeat);
+    if (fresh.length === 0)
+        return false;
+    return rule === "stop" || fresh.some((v) => !CONTINUABLE_KINDS.has(v.kind));
+}
 export function formatViolations(violations) {
     if (violations.length === 0)
         return "";

package/dist/engine/plain.js

@@ -0,0 +1,268 @@
+/**
+ * The report in plain words, for a reader who does not read request
+ * signatures and route patterns: a QA tester, a product owner, anyone who
+ * needs to act on a finding without decoding it first.
+ *
+ * It is a view over the same findings the technical report prints, never a
+ * replacement: each item keeps its technical detail one click away, and the
+ * `report` setting chooses which parts a document carries. Everything here is
+ * pure string work, so the wording and the step translation are table-tested.
+ */
+import { seenOnOf } from "./memory.js";
+/** Which parts a report carries: the plain view and the technical one ("both"), or one of them. */
+export const REPORT_AUDIENCES = ["both", "qa", "dev"];
+/** Both, so nobody loses the part they rely on unless they ask to. */
+export const DEFAULT_REPORT_AUDIENCE = "both";
+/**
+ * The plain wording for every finding category and every oracle kind, in one
+ * table. contract-test holds its keys equal to FINDING_CATEGORIES and
+ * ORACLE_KINDS, so a new category or oracle cannot ship without its words.
+ */
+export const PLAIN_WORDING = {
+    // Finding categories.
+    "console-error": { problem: "The page reported an error behind the scenes", expected: "The page works without reporting errors." },
+    "page-error": { problem: "Something on the page broke while it was being used", expected: "The page keeps working while it is used." },
+    "http-error": { problem: "The server refused or failed a request", expected: "The action completes, or the page says clearly why it could not." },
+    network: { problem: "A request to the server did not get through", expected: "The page loads what it needs, or says what is missing." },
+    "dead-end": { problem: "A path led nowhere", expected: "Every link and button leads somewhere useful, with a way back." },
+    "ux-confusing": { problem: "Something is confusing to use", expected: "It is clear what to do and what happened." },
+    "ux-polish": { problem: "Something feels unfinished", expected: "The page looks finished and consistent." },
+    visual: { problem: "Something looks wrong on screen", expected: "Everything is visible, readable and in its place." },
+    a11y: { problem: "Some people cannot use this part", expected: "Everyone can use it, including with a keyboard or a screen reader." },
+    "permission-leak": { problem: "Someone can see or do something they should not", expected: "Each person sees and does only what their role allows." },
+    "data-inconsistency": { problem: "The information shown does not add up", expected: "The same information agrees everywhere it is shown." },
+    "stale-state": { problem: "The page shows out-of-date information", expected: "The page shows the current state after every change." },
+    "data-loss": { problem: "Work or information was lost", expected: "What a person enters is kept." },
+    performance: { problem: "Something is too slow", expected: "The page responds without a noticeable wait." },
+    security: { problem: "A security weakness", expected: "The app keeps people's data and accounts safe." },
+    "missing-testid": { problem: "A control automated tests cannot find reliably", expected: "Every control can be found reliably by automated tests." },
+    other: { problem: "Something else is wrong", expected: "The app behaves the way a person using it would expect." },
+    // Oracle kinds: what the automatic checks notice on every page.
+    console_error: { problem: "The page reported an error behind the scenes", expected: "The page works without reporting errors." },
+    page_error: { problem: "Something on the page broke while it was being used", expected: "The page keeps working while it is used." },
+    request_failed: { problem: "A request to the server did not get through", expected: "The page loads what it needs, or says what is missing." },
+    http_error: { problem: "The server refused or failed a request", expected: "The action completes, or the page says clearly why it could not." },
+    dom_injection: { problem: "Text typed into a field came back as part of the page itself", expected: "What a person types is always shown as plain text." },
+    refused_empty: {
+        problem: "The server refused a request and the page showed nothing instead of an error",
+        expected: "When something fails, the page says so.",
+    },
+    false_success: { problem: "The page said something worked when the server had refused it", expected: "The page reports only what really happened." },
+    postmessage_token: { problem: "The page handed a sign-in token to any site that asked", expected: "Sign-in details go only to the app's own pages." },
+};
+/** The words for a category or oracle kind; one the table does not know (an older finding's) reads as "other". */
+export function plainWording(kind) {
+    return Object.prototype.hasOwnProperty.call(PLAIN_WORDING, kind) ? PLAIN_WORDING[kind] : PLAIN_WORDING.other;
+}
+/** Severity as its effect on the people using the app. */
+export const IMPACT = { high: "Blocks users", medium: "Annoying", low: "Cosmetic" };
+/** What a control's role is called in a sentence. */
+const ROLE_WORD = {
+    button: "button",
+    link: "link",
+    textbox: "field",
+    searchbox: "search box",
+    combobox: "list",
+    listbox: "list",
+    checkbox: "checkbox",
+    radio: "option",
+    switch: "switch",
+    tab: "tab",
+    menuitem: "menu item",
+    option: "option",
+    spinbutton: "field",
+    slider: "slider",
+    row: "row",
+    cell: "cell",
+};
+/** `role "name"` as "the "name" button"; a target that is not that shape is quoted as it is. */
+function control(target) {
+    const m = /^(\w+) "(.*)"$/.exec(target.trim());
+    if (!m)
+        return target.trim();
+    const word = ROLE_WORD[m[1]] ?? m[1];
+    return m[2] ? `the "${m[2]}" ${word}` : `the unnamed ${word}`;
+}
+/** One action-log step, split into what was done, to what, and on which page. */
+function splitStep(line) {
+    const at = line.lastIndexOf(" @ ");
+    const head = at >= 0 ? line.slice(0, at) : line;
+    const url = at >= 0 ? line.slice(at + 3) : "";
+    const space = head.indexOf(" ");
+    return space < 0 ? { action: head, target: "", url } : { action: head.slice(0, space), target: head.slice(space + 1), url };
+}
+/** Actions that move to a page, and so start the steps that matter. */
+const OPENS = new Set(["navigate", "crawl"]);
+/**
+ * One repro step as a person would do it, or null for a step only the tester
+ * takes (a snapshot, a screenshot, an audit, the write policy's own notes).
+ */
+export function plainStep(line) {
+    const { action: raw, target, url } = splitStep(line);
+    // A plan's step is the same action, run from a list.
+    const action = raw.replace(/^plan:/, "");
+    if (OPENS.has(action))
+        return `Go to ${url || target}`;
+    let m;
+    if ((m = /^click(?:×(\d+))?$/.exec(action))) {
+        const times = Number(m[1] ?? 1);
+        const verb = times === 2 ? "Double-click" : times > 2 ? `Click ${times} times on` : "Click";
+        return `${verb} ${control(target)}`;
+    }
+    if (action === "type") {
+        const t = /^(\w+ ".*") ← ("(?:[^"\\]|\\.)*")( \+ Enter)?/.exec(target);
+        if (!t)
+            return `Type into ${control(target)}`;
+        return `Type ${t[2]} into ${control(t[1])}${t[3] ? " and press Enter" : ""}`;
+    }
+    if (action === "select") {
+        const s = /^(\w+ ".*") = (.*)$/.exec(target);
+        return s ? `Choose "${s[2]}" in ${control(s[1])}` : `Choose an option in ${control(target)}`;
+    }
+    if (action === "upload") {
+        const u = / ← (.+?) \(/.exec(target);
+        return u ? `Attach the file "${u[1]}"` : "Attach a file";
+    }
+    if (action === "hover")
+        return `Point at ${control(target)}`;
+    if (action === "press")
+        return `Press ${target}`;
+    if (action === "scroll")
+        return target ? `Scroll ${target}` : "Scroll the page";
+    if (action === "back")
+        return "Go back to the previous page";
+    return null;
+}
+/** The page a step was on, for the first step when the trace has no navigation of its own. */
+function pageOf(line) {
+    return line ? splitStep(line).url : "";
+}
+/**
+ * A finding's repro trace as numbered steps a person can follow. It starts at
+ * the last time the run went to a page, since what came before that was on
+ * another page; when it never did, it starts by going to the page the trace
+ * began on. Steps only the tester takes are left out.
+ */
+export function plainSteps(repro) {
+    let start = -1;
+    for (let i = repro.length - 1; i >= 0; i--) {
+        if (OPENS.has(splitStep(repro[i]).action.replace(/^plan:/, ""))) {
+            start = i;
+            break;
+        }
+    }
+    const steps = (start >= 0 ? repro.slice(start) : repro).map(plainStep).filter((s) => s !== null);
+    if (start < 0) {
+        const first = pageOf(repro[0]);
+        if (first)
+            steps.unshift(`Go to ${first}`);
+    }
+    return steps;
+}
+/** A relative path inside the run's folder, safe to put in a document: no scheme, no `..`, nothing absolute. */
+export function isSafeRelativePath(p) {
+    return /^[A-Za-z0-9._-][A-Za-z0-9._/-]*$/.test(p) && !p.split("/").includes("..") && !p.includes("//");
+}
+/**
+ * The picture of a finding, as a path relative to the run's folder, or
+ * undefined. A finding's own picture comes first: `picture`, a path relative
+ * to the run's folder, is the slot a capture taken when a finding is filed
+ * fills, and no finding carries one yet. On a recorded run the last frame on
+ * screen before the finding was filed stands in. A value that is not a safe relative path is ignored, since the file is
+ * read back without a schema and the path goes into a page.
+ */
+export function pictureOf(f, lastFrame) {
+    const own = f.picture;
+    for (const p of [own, lastFrame])
+        if (typeof p === "string" && isSafeRelativePath(p))
+            return p;
+    return undefined;
+}
+const count = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+/** "a, b and c". */
+function joinAnd(parts) {
+    return parts.length <= 1 ? parts.join("") : `${parts.slice(0, -1).join(", ")} and ${parts[parts.length - 1]}`;
+}
+/** The short summary that opens the plain section. */
+export function plainSummary(input) {
+    const lines = [];
+    const { current } = input;
+    const by = (s) => current.filter((f) => f.severity === s).length;
+    const where = input.routes && input.routes.total > 0 ? ` It went to ${input.routes.visited} of the ${input.routes.total} pages it knew about.` : "";
+    if (current.length === 0) {
+        lines.push(`This run found no problems.${where}`);
+    }
+    else {
+        const split = [
+            ["high", "blocks users", "block users"],
+            ["medium", "is annoying", "are annoying"],
+            ["low", "is cosmetic", "are cosmetic"],
+        ]
+            .filter(([s]) => by(s) > 0)
+            .map(([s, one, many]) => `${by(s)} ${by(s) === 1 ? one : many}`);
+        lines.push(`This run found ${count(current.length, "problem")}: ${joinAnd(split)}.${where}`);
+    }
+    const elsewhere = input.audience === "qa" ? "" : " They are listed in the technical detail below.";
+    if (input.historical > 0) {
+        lines.push(``, `${count(input.historical, "problem")} found by earlier runs ${input.historical === 1 ? "was" : "were"} not checked again this time.${elsewhere}`);
+    }
+    if (input.worthALook > 0) {
+        lines.push(``, `${count(input.worthALook, "observation")} ${input.worthALook === 1 ? "is a problem" : "are problems"} only if your project follows a particular convention, so ${input.worthALook === 1 ? "it is" : "they are"} not counted here.${elsewhere}`);
+    }
+    const kinds = new Map();
+    for (const v of input.violations)
+        kinds.set(v.kind, (kinds.get(v.kind) ?? 0) + 1);
+    if (kinds.size > 0) {
+        lines.push(``, `While it worked, the automatic checks noticed:`, ``);
+        for (const [kind, n] of [...kinds.entries()].sort((a, b) => b[1] - a[1]))
+            lines.push(`- ${plainWording(kind).problem} (${n === 1 ? "once" : `${n} times`})`);
+    }
+    if (input.gaps.length > 0) {
+        lines.push(``, `The run left ${count(input.gaps.length, "thing")} unchecked.${input.audience === "qa" ? "" : " The gap ledger below says which."}`);
+        if (input.audience === "qa") {
+            lines.push(``);
+            for (const g of input.gaps)
+                lines.push(`- ${g}`);
+        }
+    }
+    return lines;
+}
+/** One finding in plain words, with its technical detail folded beneath it. */
+export function plainFinding(f, index, input) {
+    const words = plainWording(f.category);
+    // One cause in a shared part of the app is seen on every page that shows it.
+    const also = seenOnOf(f);
+    const lines = [
+        `### ${index}. ${f.title}`,
+        ``,
+        `**${IMPACT[f.severity]}** · ${words.problem} · on ${f.url}${also.length > 0 ? `, and also seen on ${also.join(", ")}` : ""}`,
+        ``,
+    ];
+    const picture = pictureOf(f, input.lastFrames?.get(f.id));
+    if (picture)
+        lines.push(`![What the page showed](${picture})`, ``);
+    const steps = plainSteps(f.repro);
+    if (steps.length > 0) {
+        lines.push(`**What was done:**`, ``);
+        steps.forEach((s, i) => lines.push(`${i + 1}. ${s}`));
+        lines.push(``);
+    }
+    lines.push(`**What was expected:** ${words.expected}`, ``, `**What happened:** ${f.detail.replace(/\r?\n+/g, " ")}`, ``);
+    lines.push(`<details><summary>Technical detail</summary>`, ``);
+    // "Finding id", not "Id": the HTML and the live view hang a finding's recorded
+    // frames under the list that names its "Id", and that is the full entry's.
+    lines.push(`- **Finding id:** \`${f.id}\` · **Category:** ${f.category} · **Severity:** ${f.severity}`);
+    if (f.evidence)
+        lines.push(`- **Evidence:** \`${f.evidence}\``);
+    lines.push(`- **Route:** \`${f.state}\``);
+    if (input.audience !== "qa")
+        lines.push(`- The full entry, with the repro trace and a test skeleton, is under the same id in the technical detail below.`);
+    lines.push(``, `</details>`, ``);
+    return lines;
+}
+/** The whole plain section: the summary, then each problem this run found, worst first. */
+export function formatPlainSection(input) {
+    const lines = [`## In plain words`, ``, ...plainSummary(input), ``, ...(input.tickets ?? [])];
+    input.current.forEach((f, i) => lines.push(...plainFinding(f, i + 1, input)));
+    return lines;
+}