scenescout 3.15.0 → 3.17.0

package/dist/engine/export.js

@@ -0,0 +1,877 @@
+/**
+ * `scenescout export`: the rules for turning a project's findings into issues
+ * where a team works, in GitHub or Jira. Which findings go, what each issue
+ * says, the marker a later export recognises it by, what is already filed and
+ * how many one export may file. Nothing here touches the network or the disk:
+ * src/export-run.ts reads the files and sends the requests, so every rule in
+ * this file is table-tested in export-test without a tracker.
+ *
+ * Issue text is written by a model and quotes the app under test, and a
+ * tracker renders it: GitHub turns `@name` into a notification, `#12` into a
+ * cross-reference and an address into a link. Every piece of that text is
+ * made inert before it goes into an issue.
+ */
+import { createHash } from "node:crypto";
+import { readFindingPicture } from "./capture.js";
+import { readFindings } from "./ci.js";
+import { isWorthALook, redactSecrets } from "./memory.js";
+import { retryAfterMs } from "./provider.js";
+import { answerTicket } from "./tickets.js";
+const TRACKERS = ["github", "jira"];
+export const TRACKER_LABEL = { github: "GitHub", jira: "Jira" };
+export const SEVERITIES = ["high", "medium", "low"];
+const SEVERITY_RANK = { high: 0, medium: 1, low: 2 };
+/** Every option `scenescout export` accepts. guide-test holds the configuration reference equal to it. */
+export const EXPORT_OPTION_NAMES = [
+    "to",
+    "repo",
+    "jira-url",
+    "jira-project",
+    "jira-issue-type",
+    "jira-link-type",
+    "jira-update",
+    "project",
+    "min-severity",
+    "only",
+    "max-issues",
+    "severity-map",
+    "labels",
+    "screenshots",
+    "refile-closed",
+    "include-worth-a-look",
+    "dry-run",
+    "yes",
+];
+const SWITCHES = new Set(["refile-closed", "include-worth-a-look", "dry-run", "yes"]);
+/** Options someone might reach for to pass a credential. Each is refused with where the credential comes from instead. */
+const CREDENTIAL_FLAGS = new Set(["token", "github-token", "gh-token", "jira-token", "api-token", "jira-api-token", "jira-email", "email", "password"]);
+/** The label every exported issue carries. A later export lists the issues with it and reads their markers. */
+export const MARKER_LABEL = "scenescout";
+const DEFAULT_MAX_ISSUES = 20;
+const MAX_ISSUES_BOUNDS = [1, 100];
+const DEFAULT_JIRA_ISSUE_TYPE = "Bug";
+/** The link from a Jira issue to the ticket whose criterion it fails. Every Jira Cloud site has it; `none` links nothing. */
+const DEFAULT_JIRA_LINK_TYPE = "Relates";
+const DEFAULT_GITHUB_API_URL = "https://api.github.com";
+/** What a severity becomes: a label on GitHub, a priority in Jira. `--severity-map` replaces any of them. */
+export const DEFAULT_SEVERITY_MAP = {
+    github: { high: "severity: high", medium: "severity: medium", low: "severity: low" },
+    jira: { high: "High", medium: "Medium", low: "Low" },
+};
+/**
+ * Exit 0: the export did what it set out to, filing up to the cap (anything
+ * over it waits for the next export) or, on a dry run, listing. Exit 2: it
+ * could not finish, or a screenshot could not be attached to an issue it filed.
+ */
+export const EXIT_EXPORT = { done: 0, couldNotExport: 2 };
+/** A finding id that can sit in a marker and be read back out of one. Ids are short hashes; anything else is not exported. */
+const FINDING_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+const MAX_ONLY = 200;
+const MAX_LABELS = 10;
+/** GitHub's own limit on a label's name, used for Jira labels and priorities too. */
+const MAX_LABEL_LENGTH = 50;
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "[::1]", "::1"]);
+/**
+ * An address a credential may be sent to: https, or plain http only to this
+ * machine; no user or password in it, since the credential comes from the
+ * environment; and no query or fragment, since paths are joined onto it.
+ */
+export function checkTrackerUrl(raw, name) {
+    let u;
+    try {
+        u = new URL(raw.trim());
+    }
+    catch {
+        return { ok: false, error: `${name} is not a URL: ${oneLine(raw, 120)}` };
+    }
+    if (u.username || u.password)
+        return { ok: false, error: `${name} must carry no credentials: they are read from the environment` };
+    if (u.search || u.hash)
+        return { ok: false, error: `${name} must have no query or fragment` };
+    const secure = u.protocol === "https:" || (u.protocol === "http:" && LOOPBACK_HOSTS.has(u.hostname));
+    if (!secure)
+        return { ok: false, error: `${name} must be https (plain http only to 127.0.0.1 or localhost): a credential is sent to it` };
+    return { ok: true, value: u.toString().replace(/\/+$/, "") };
+}
+/** The text of a name or label: one line, no control characters, within a length. */
+function plainName(raw, what, max) {
+    const value = raw.trim();
+    if (!value)
+        return { ok: false, error: `${what} is empty` };
+    if (/[\u0000-\u001f\u007f-\u009f]/.test(value))
+        return { ok: false, error: `${what} has a control character` };
+    if (value.length > max)
+        return { ok: false, error: `${what} is longer than ${max} characters` };
+    return { ok: true, value };
+}
+/**
+ * `--severity-map high=P1,medium=P2,low=P3`. A severity left out keeps its
+ * default; one given an empty name (`low=`) gets no label or priority; `none`
+ * maps no severity at all.
+ */
+function parseSeverityMap(raw, to) {
+    const map = { ...DEFAULT_SEVERITY_MAP[to] };
+    if (raw === undefined)
+        return { ok: true, value: map };
+    if (raw.trim() === "none")
+        return { ok: true, value: { high: null, medium: null, low: null } };
+    const seen = new Set();
+    for (const part of raw.split(",")) {
+        const eq = part.indexOf("=");
+        if (eq < 0)
+            return { ok: false, error: "--severity-map takes severity=name pairs, e.g. high=P1,medium=P2,low=P3, or none" };
+        const key = part.slice(0, eq).trim().toLowerCase();
+        if (!SEVERITIES.includes(key))
+            return { ok: false, error: `--severity-map: ${oneLine(key, 40)} is not high, medium or low` };
+        if (seen.has(key))
+            return { ok: false, error: `--severity-map names ${key} twice` };
+        seen.add(key);
+        const name = part.slice(eq + 1);
+        if (name.trim() === "") {
+            map[key] = null;
+            continue;
+        }
+        const checked = plainName(name, `--severity-map's name for ${key}`, MAX_LABEL_LENGTH);
+        if (!checked.ok)
+            return checked;
+        map[key] = checked.value;
+    }
+    return { ok: true, value: map };
+}
+/** `--labels a,b`: at most ten, each a valid label for the tracker. Jira labels cannot hold a space. */
+function parseLabels(raw, to) {
+    if (raw === undefined)
+        return { ok: true, value: [] };
+    const out = [];
+    for (const part of raw.split(",")) {
+        const checked = plainName(part, "a --labels label", MAX_LABEL_LENGTH);
+        if (!checked.ok)
+            return checked;
+        if (to === "jira" && /\s/.test(checked.value))
+            return { ok: false, error: `Jira labels cannot contain spaces: ${oneLine(checked.value, 60)}` };
+        if (checked.value.toLowerCase() === MARKER_LABEL || out.some((l) => l.toLowerCase() === checked.value.toLowerCase()))
+            continue;
+        out.push(checked.value);
+    }
+    if (out.length > MAX_LABELS)
+        return { ok: false, error: `--labels takes at most ${MAX_LABELS} labels` };
+    return { ok: true, value: out };
+}
+export function parseExportArgs(args, cwd, env) {
+    const known = new Set(EXPORT_OPTION_NAMES);
+    const flags = new Map();
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (!a.startsWith("--"))
+            return { ok: false, error: `unexpected argument ${a}: export takes options only (the findings come from --project)` };
+        const eq = a.indexOf("=");
+        const name = eq > 0 ? a.slice(2, eq) : a.slice(2);
+        if (CREDENTIAL_FLAGS.has(name))
+            return {
+                ok: false,
+                error: `there is no --${name}: credentials are read from the environment only (GH_TOKEN or GITHUB_TOKEN for GitHub; JIRA_EMAIL and JIRA_API_TOKEN for Jira)`,
+            };
+        if (!known.has(name))
+            return { ok: false, error: `unknown option --${name}` };
+        if (flags.has(name))
+            return { ok: false, error: `--${name} is given twice` };
+        if (SWITCHES.has(name)) {
+            if (eq > 0)
+                return { ok: false, error: `--${name} takes no value` };
+            flags.set(name, "true");
+            continue;
+        }
+        const value = eq > 0 ? a.slice(eq + 1) : args[i + 1];
+        if (value === undefined || (eq < 0 && value.startsWith("--")))
+            return { ok: false, error: `--${name} needs a value` };
+        if (eq < 0)
+            i += 1;
+        flags.set(name, value);
+    }
+    const to = flags.get("to");
+    if (to === undefined)
+        return { ok: false, error: "say where the issues go: --to github or --to jira" };
+    if (!TRACKERS.includes(to))
+        return { ok: false, error: `--to must be one of ${TRACKERS.join(", ")}` };
+    const tracker = to;
+    const otherTrackers = { github: ["jira-url", "jira-project", "jira-issue-type", "jira-link-type", "jira-update"], jira: ["repo"] };
+    for (const name of otherTrackers[tracker])
+        if (flags.has(name))
+            return { ok: false, error: `--${name} is not an option of --to ${tracker}` };
+    let target;
+    if (tracker === "github") {
+        const repo = flags.get("repo");
+        if (repo === undefined)
+            return { ok: false, error: "--to github needs --repo owner/name" };
+        if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo) || repo.split("/").some((part) => /^\.+$/.test(part)))
+            return { ok: false, error: `--repo is not owner/name: ${oneLine(repo, 120)}` };
+        const apiUrl = checkTrackerUrl(env.GITHUB_API_URL?.trim() || DEFAULT_GITHUB_API_URL, "GITHUB_API_URL");
+        if (!apiUrl.ok)
+            return apiUrl;
+        target = { to: "github", github: { repo, apiUrl: apiUrl.value } };
+    }
+    else {
+        const rawUrl = flags.get("jira-url") ?? env.JIRA_BASE_URL?.trim();
+        if (!rawUrl)
+            return { ok: false, error: "--to jira needs the site's address: --jira-url https://your-site.atlassian.net, or JIRA_BASE_URL" };
+        const baseUrl = checkTrackerUrl(rawUrl, flags.has("jira-url") ? "--jira-url" : "JIRA_BASE_URL");
+        if (!baseUrl.ok)
+            return baseUrl;
+        const projectKey = (flags.get("jira-project") ?? env.JIRA_PROJECT_KEY ?? "").trim();
+        if (!projectKey)
+            return { ok: false, error: "--to jira needs a project key: --jira-project KEY, or JIRA_PROJECT_KEY" };
+        if (!/^[A-Z][A-Z0-9_]{1,49}$/.test(projectKey))
+            return {
+                ok: false,
+                error: `the Jira project key is not a key (capital letters, digits and underscores, starting with a letter): ${oneLine(projectKey, 60)}`,
+            };
+        const issueType = plainName(flags.get("jira-issue-type") ?? env.JIRA_ISSUE_TYPE ?? DEFAULT_JIRA_ISSUE_TYPE, "the Jira issue type", 60);
+        if (!issueType.ok)
+            return issueType;
+        const rawLinkType = flags.get("jira-link-type") ?? env.JIRA_LINK_TYPE ?? DEFAULT_JIRA_LINK_TYPE;
+        const linkType = rawLinkType.trim().toLowerCase() === "none" ? null : plainName(rawLinkType, "the Jira link type", 60);
+        if (linkType && !linkType.ok)
+            return linkType;
+        const update = flags.get("jira-update") ?? "on";
+        if (update !== "on" && update !== "off")
+            return { ok: false, error: "--jira-update must be on or off" };
+        target = {
+            to: "jira",
+            jira: { baseUrl: baseUrl.value, projectKey, issueType: issueType.value, linkType: linkType ? linkType.value : null, update: update === "on" },
+        };
+    }
+    const minSeverity = flags.get("min-severity") ?? "low";
+    if (!SEVERITIES.includes(minSeverity))
+        return { ok: false, error: `--min-severity must be one of ${SEVERITIES.join(", ")}` };
+    let only;
+    if (flags.has("only")) {
+        only = [
+            ...new Set(flags
+                .get("only")
+                .split(/[\s,]+/)
+                .filter(Boolean)),
+        ];
+        if (only.length === 0)
+            return { ok: false, error: "--only needs finding ids, comma-separated" };
+        if (only.length > MAX_ONLY)
+            return { ok: false, error: `--only takes at most ${MAX_ONLY} ids` };
+        const bad = only.find((id) => !FINDING_ID_RE.test(id));
+        if (bad !== undefined)
+            return { ok: false, error: `--only: ${oneLine(bad, 70)} is not a finding id` };
+    }
+    let maxIssues = DEFAULT_MAX_ISSUES;
+    if (flags.has("max-issues")) {
+        const n = Number(flags.get("max-issues"));
+        const [lo, hi] = MAX_ISSUES_BOUNDS;
+        if (!Number.isInteger(n) || n < lo || n > hi)
+            return { ok: false, error: `--max-issues must be a whole number from ${lo} to ${hi}` };
+        maxIssues = n;
+    }
+    const severityMap = parseSeverityMap(flags.get("severity-map"), tracker);
+    if (!severityMap.ok)
+        return severityMap;
+    const labels = parseLabels(flags.get("labels"), tracker);
+    if (!labels.ok)
+        return labels;
+    const screenshots = flags.get("screenshots") ?? "on";
+    if (screenshots !== "on" && screenshots !== "off")
+        return { ok: false, error: "--screenshots must be on or off" };
+    if (flags.has("dry-run") && flags.has("yes"))
+        return { ok: false, error: "--dry-run and --yes contradict each other: give one" };
+    const resolve = (p) => (p.startsWith("/") || /^[A-Za-z]:[\\/]/.test(p) ? p : `${cwd.replace(/[\\/]$/, "")}/${p}`);
+    return {
+        ok: true,
+        options: {
+            ...target,
+            projectDir: resolve(flags.get("project") ?? cwd),
+            minSeverity: minSeverity,
+            ...(only ? { only } : {}),
+            maxIssues,
+            severityMap: severityMap.value,
+            labels: labels.value,
+            screenshots: screenshots === "on",
+            refileClosed: flags.has("refile-closed"),
+            includeWorthALook: flags.has("include-worth-a-look"),
+            dryRun: !flags.has("yes"),
+        },
+    };
+}
+/** The tracker's credentials, from the environment and nowhere else. An error names the variables to set, never a value. */
+export function trackerCredentials(to, env) {
+    if (to === "github") {
+        const fromGh = env.GH_TOKEN?.trim();
+        const token = fromGh || env.GITHUB_TOKEN?.trim();
+        if (!token)
+            return { ok: false, error: "no GitHub token: set GH_TOKEN or GITHUB_TOKEN to a token that can create issues in the repository" };
+        return { ok: true, headers: { authorization: `Bearer ${token}` }, source: fromGh ? "GH_TOKEN" : "GITHUB_TOKEN" };
+    }
+    const email = env.JIRA_EMAIL?.trim();
+    const token = env.JIRA_API_TOKEN?.trim();
+    const missing = [email ? null : "JIRA_EMAIL", token ? null : "JIRA_API_TOKEN"].filter((n) => n !== null);
+    if (!email || !token)
+        return { ok: false, error: `no Jira credentials: set JIRA_EMAIL and JIRA_API_TOKEN (missing: ${missing.join(", ")})` };
+    return { ok: true, headers: { authorization: `Basic ${Buffer.from(`${email}:${token}`).toString("base64")}` }, source: "JIRA_EMAIL and JIRA_API_TOKEN" };
+}
+/**
+ * Every string that must never be printed: each credential variable that is
+ * set, whichever tracker the export is for and whether or not the set is
+ * complete, and the encoded header Jira's would make. A credential pasted
+ * into an option by mistake is redacted from the refusal too.
+ */
+export function credentialSecrets(env) {
+    const values = [env.GH_TOKEN, env.GITHUB_TOKEN, env.JIRA_API_TOKEN].map((v) => v?.trim() ?? "").filter((v) => v.length > 0);
+    const email = env.JIRA_EMAIL?.trim();
+    const jiraToken = env.JIRA_API_TOKEN?.trim();
+    if (email && jiraToken)
+        values.push(Buffer.from(`${email}:${jiraToken}`).toString("base64"));
+    return values;
+}
+/** The findings an export files, from memory.json as read: open defects at or above the minimum severity. */
+export function selectFindings(memory, o) {
+    const listed = memory && typeof memory === "object" ? memory.findings : undefined;
+    const all = readFindings(memory).filter((f) => FINDING_ID_RE.test(f.id));
+    const readable = new Set(all);
+    const unreadable = (Array.isArray(listed) ? listed : []).flatMap((entry, i) => readable.has(entry)
+        ? []
+        : [entry && typeof entry === "object" && typeof entry.id === "string" ? oneLine(entry.id, 70) : `#${i + 1}`]);
+    const counts = { open: 0, resolved: 0, worthALook: 0, belowSeverity: 0 };
+    const only = o.only ? new Set(o.only) : null;
+    const leftOut = [];
+    const candidates = [];
+    for (const f of all) {
+        const named = only?.has(f.id) ?? false;
+        if (only && !named)
+            continue;
+        let reason = null;
+        if (f.status === "resolved") {
+            counts.resolved++;
+            reason = "resolved";
+        }
+        else {
+            counts.open++;
+            if (isWorthALook(f) && !o.includeWorthALook) {
+                counts.worthALook++;
+                reason = "worth a look (add --include-worth-a-look)";
+            }
+            else if (SEVERITY_RANK[f.severity] > SEVERITY_RANK[o.minSeverity]) {
+                counts.belowSeverity++;
+                reason = `below --min-severity ${o.minSeverity}`;
+            }
+        }
+        if (reason === null)
+            candidates.push(f);
+        else if (named)
+            leftOut.push({ id: f.id, reason });
+    }
+    candidates.sort((a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity] || timeOf(a.foundAt) - timeOf(b.foundAt) || a.id.localeCompare(b.id));
+    const ids = new Set(all.map((f) => f.id));
+    return { candidates, counts, unreadable, unknownOnly: (o.only ?? []).filter((id) => !ids.has(id)), leftOut };
+}
+function timeOf(iso) {
+    const t = typeof iso === "string" ? Date.parse(iso) : NaN;
+    return Number.isNaN(t) ? 0 : t;
+}
+const isObject = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+const MAX_CRITERIA_PER_ISSUE = 10;
+/**
+ * Which criteria each finding shows failing, from the tickets and verdicts in
+ * memory.json, answered as the report answers them (tickets.ts answerTicket):
+ * a fail from any session decides a criterion, and a verdict on a criterion
+ * reworded since is left behind. Entries that do not read are skipped: a
+ * ticket is context for an issue, never a reason to refuse an export.
+ */
+export function failedCriteriaByFinding(memory) {
+    const out = new Map();
+    if (!isObject(memory))
+        return out;
+    const tickets = (Array.isArray(memory.tickets) ? memory.tickets : []).filter((t) => isObject(t) &&
+        typeof t.id === "string" &&
+        Array.isArray(t.criteria) &&
+        t.criteria.every((c) => isObject(c) && typeof c.id === "string" && typeof c.text === "string"));
+    const verdicts = (Array.isArray(memory.criterionVerdicts) ? memory.criterionVerdicts : []).filter((v) => isObject(v) &&
+        typeof v.ticket === "string" &&
+        typeof v.criterion === "string" &&
+        typeof v.verdict === "string" &&
+        Array.isArray(v.findings) &&
+        v.findings.every((id) => typeof id === "string") &&
+        typeof v.confidence === "number" &&
+        typeof v.session === "string");
+    for (const ticket of tickets)
+        for (const answer of answerTicket(ticket, verdicts)) {
+            if (answer.verdict !== "fail")
+                continue;
+            for (const id of answer.findings) {
+                const list = out.get(id) ?? [];
+                if (list.length < MAX_CRITERIA_PER_ISSUE)
+                    list.push({ ticket: ticket.id, criterion: answer.criterion.id, text: answer.criterion.text });
+                out.set(id, list);
+            }
+        }
+    return out;
+}
+/** A ticket id that is a Jira issue key, so the issue can be linked to it: "PROJ-12", not "#12" or "T1". */
+export function isJiraKey(id) {
+    return /^[A-Z][A-Z0-9_]{1,49}-[1-9]\d{0,9}$/.test(id);
+}
+/** The Jira tickets an issue is linked to: each failed criterion's ticket that is a Jira key, once. */
+export function ticketsToLink(criteria) {
+    return [...new Set(criteria.map((c) => c.ticket).filter(isJiraKey))];
+}
+/** The finding's own picture (scout_finding, #347), as a path under `.scenescout/`, when the path is one the engine writes. */
+export function findingPicture(f) {
+    const p = readFindingPicture(f);
+    return p ? { rel: p.file, ...(p.at ? { at: p.at } : {}) } : null;
+}
+// ── the marker ──────────────────────────────────────────────────────────────
+/** The first line of a GitHub issue's body: an HTML comment, so it is not shown. */
+export function githubMarker(id) {
+    return `<!-- scenescout-finding: ${id} -->`;
+}
+/** The finding ids a GitHub issue's body carries markers for. Escaped text never matches: its `<` is `&lt;`. */
+export function findingIdsInGithubBody(body) {
+    if (typeof body !== "string")
+        return [];
+    return [...body.matchAll(/<!-- scenescout-finding: ([A-Za-z0-9_-]{1,64}) -->/g)].map((m) => m[1]);
+}
+/**
+ * A Jira description cannot hide text, so the marker is a last, short line.
+ * It carries the revision of the summary and description it was written
+ * with, so a later export can tell whether anyone has edited them since.
+ */
+function jiraMarkerText(id, revision) {
+    return `scenescout-finding: ${id} rev ${revision}`;
+}
+/**
+ * The finding ids a Jira description (Atlassian Document Format, as the API
+ * returns it) carries markers for. Model-written text has the marker's word
+ * broken by a zero-width space, so only a marker this export wrote, or one a
+ * person copied in on purpose, is read.
+ */
+export function findingIdsInJiraDescription(description) {
+    if (description === null || description === undefined)
+        return [];
+    const text = typeof description === "string" ? description : JSON.stringify(description);
+    return [...text.matchAll(/scenescout-finding: ([A-Za-z0-9_-]{1,64})/g)].map((m) => m[1]);
+}
+/** The revision a Jira issue's marker for this finding records, or null when it records none (an issue filed before revisions were kept). */
+export function jiraMarkerRevision(description, id) {
+    const text = typeof description === "string" ? description : JSON.stringify(description ?? "");
+    // An id is letters, digits, "_" and "-" (FINDING_ID_RE), none of which is special in a pattern.
+    if (!FINDING_ID_RE.test(id))
+        return null;
+    return new RegExp(`scenescout-finding: ${id} rev ([0-9a-f]{16})\\b`).exec(text)?.[1] ?? null;
+}
+/** The node types and marks a description SceneScout writes is made of (jiraDescription). */
+const OWN_NODES = new Set(["doc", "paragraph", "text", "heading", "bulletList", "orderedList", "listItem", "codeBlock", "rule"]);
+const OWN_MARKS = new Set(["code"]);
+/**
+ * Every text node of a document, in order, leaving out the marker's
+ * paragraph, and a token for every node or mark SceneScout never writes: a
+ * picture, a mention, a link card or emoji a person pasted carries no text,
+ * and must still count as an edit.
+ */
+function textsOf(node, out = []) {
+    if (Array.isArray(node)) {
+        for (const n of node)
+            textsOf(n, out);
+        return out;
+    }
+    if (!isObject(node))
+        return out;
+    if (node.type === "paragraph" && /scenescout-finding: /.test(JSON.stringify(node.content ?? "")))
+        return out;
+    if (!OWN_NODES.has(String(node.type)))
+        out.push(`\u0001node:${String(node.type)}:${JSON.stringify(node.attrs ?? null)}`);
+    for (const mark of Array.isArray(node.marks) ? node.marks : [])
+        if (!isObject(mark) || !OWN_MARKS.has(String(mark.type)))
+            out.push(`\u0001mark:${JSON.stringify(mark)}`);
+    if (node.type === "text" && typeof node.text === "string")
+        out.push(node.text);
+    textsOf(node.content, out);
+    return out;
+}
+/**
+ * The revision of an issue's summary and description: a hash of their text,
+ * with the marker's paragraph and all white space left out, and of anything
+ * in them SceneScout does not write. Not the whole document, so the
+ * attributes Jira adds to the nodes SceneScout wrote do not change it, while
+ * any word, picture, mention or link a person adds, removes or rewords does.
+ */
+export function jiraRevision(summary, description) {
+    const text = [typeof summary === "string" ? summary : "", ...textsOf(description)].join("").replace(/\s+/g, "");
+    return createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+// ── inert text ──────────────────────────────────────────────────────────────
+/** One line: control, bidirectional-override and line-break characters become spaces; runs of space collapse; at most `max`. */
+export function oneLine(text, max) {
+    let s = String(text ?? "")
+        .replace(/[\u0000-\u001f\u007f-\u009f\u200e\u200f\u202a-\u202e\u2066-\u2069]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (s.length > max)
+        s = `${s.slice(0, max - 1)}…`;
+    return s;
+}
+/**
+ * Zero-width spaces where a tracker would otherwise act on text: after `@`
+ * (a mention, an email autolink), inside `://` and `www.` (a link), between
+ * `#` or `GH-` and a number (a cross-reference), and inside the marker's word
+ * (so quoted text cannot claim to be another finding's issue).
+ */
+function breakTriggers(s) {
+    return s
+        .replace(/@/g, "@\u200b")
+        .replace(/:\/\//g, ":\u200b//")
+        .replace(/www\./gi, (m) => `${m.slice(0, 3)}\u200b.`)
+        .replace(/#(?=\d)/g, "#\u200b")
+        .replace(/\bgh-(?=\d)/gi, (m) => `${m.slice(0, 2)}\u200b-`)
+        .replace(/scenescout-finding/gi, (m) => `${m.slice(0, 10)}\u200b${m.slice(10)}`);
+}
+/**
+ * Text for a GitHub Markdown body: one line, HTML-escaped, every Markdown
+ * punctuation mark backslash-escaped, and every trigger broken. The escaping
+ * of the `/scenescout qa` reply (action/qa-action.mjs `inert`), which
+ * export-test holds it to, plus `$` (GitHub renders `$…$` as maths), the
+ * cross-reference and marker breaks, and no bidirectional or C1 control
+ * characters.
+ */
+export function inertMarkdown(text, max = 160) {
+    return breakTriggers(oneLine(text, max)
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/([\\`*_{}[\]()#+!|~$])/g, "\\$1"));
+}
+/** Text a tracker shows as it is (an issue title, a Jira text node): one line, every trigger broken, nothing escaped. */
+export function inertPlain(text, max = 160) {
+    return breakTriggers(oneLine(text, max));
+}
+// ── what an issue says ──────────────────────────────────────────────────────
+const MAX_TITLE = 200;
+const MAX_DETAIL = 4000;
+const MAX_STEP = 300;
+const MAX_STEPS = 20;
+const MAX_EVIDENCE = 2000;
+/** A finding's fields as they are rendered: redacted again on the way out, and of the right type whatever the file held. */
+function fieldsOf(f) {
+    const text = (v) => redactSecrets(typeof v === "string" ? v : "");
+    const url = text(f.url);
+    const route = redactSecrets(typeof f.state === "string" && f.state ? f.state.split("#")[0] : pathOf(url));
+    return {
+        title: text(f.title),
+        detail: text(f.detail),
+        evidence: text(f.evidence),
+        url,
+        route,
+        category: typeof f.category === "string" && f.category ? redactSecrets(f.category) : "other",
+        repro: (Array.isArray(f.repro) ? f.repro : []).filter((s) => typeof s === "string").map((s) => redactSecrets(s)),
+        runs: Number.isInteger(f.runs) && f.runs > 0 ? f.runs : 1,
+        foundAt: dateOf(f.foundAt),
+        regressedAt: f.regressedAt ? dateOf(f.regressedAt) : null,
+        verdict: f.verdict && ["gone", "present", "changed"].includes(f.verdict) ? `${f.verdict}${f.verifiedAt ? ` (${dateOf(f.verifiedAt)})` : ""}` : null,
+        convention: isWorthALook(f) ? text(f.convention) || "a convention of the project" : null,
+    };
+}
+function pathOf(url) {
+    try {
+        const u = new URL(url);
+        return `${u.pathname}${u.search}`;
+    }
+    catch {
+        return url;
+    }
+}
+function dateOf(iso) {
+    const t = timeOf(iso);
+    return t ? new Date(t).toISOString().slice(0, 10) : "unknown";
+}
+function frameName(rel) {
+    return rel.split("/").pop() || rel;
+}
+/** The line saying which criteria a finding fails, one per criterion. */
+function criterionLine(c, inert) {
+    return `${inert(c.ticket, 60)} ${inert(c.criterion, 20)}: ${inert(c.text, 300)}`;
+}
+/** Why an issue has no screenshots: the run recorded none, or the ones it recorded are gone. */
+function noFramesSentence(ctx) {
+    return ctx.framesLeftOut
+        ? "None: the run's frames of these steps are missing, too large, or were rewritten by a later run."
+        : "None: only a recorded run keeps a frame of each step (scout_attach with record: true).";
+}
+/** The issue's title, as both trackers take it. Both refuse one past 255 characters, which the breaks could otherwise reach. */
+function issueTitle(f) {
+    const title = inertPlain(fieldsOf(f).title, MAX_TITLE);
+    return (title.length > 250 ? `${title.slice(0, 249)}…` : title) || "SceneScout finding";
+}
+/** Every label an issue carries: the marker label first, then the severity's, then the extras, with no repeats. */
+function issueLabels(ctx) {
+    const out = [];
+    for (const l of [MARKER_LABEL, ...(ctx.severityName ? [ctx.severityName] : []), ...ctx.labels])
+        if (!out.some((x) => x.toLowerCase() === l.toLowerCase()))
+            out.push(l);
+    return out;
+}
+/** A GitHub issue for a finding: its title, a Markdown body whose first line is the hidden marker, and its labels. */
+export function githubIssue(f, ctx) {
+    const x = fieldsOf(f);
+    const rows = [
+        ["Severity", f.severity],
+        ["Category", inertMarkdown(x.category, 40)],
+        ["Page", inertMarkdown(x.route, 200)],
+        ["Address", inertMarkdown(x.url, 300)],
+        ["Last found", x.foundAt],
+        ["Runs that found it", String(x.runs)],
+    ];
+    if (x.regressedAt)
+        rows.push(["Regressed", `${x.regressedAt}: it had been marked resolved`]);
+    if (x.verdict)
+        rows.push(["Last re-test", inertMarkdown(x.verdict, 60)]);
+    if (x.convention !== null)
+        rows.push(["Tier", `worth a look: a defect only if the project uses ${inertMarkdown(x.convention, 200)}`]);
+    const steps = x.repro.slice(-MAX_STEPS);
+    const lines = [
+        githubMarker(f.id),
+        "",
+        `> ${inertMarkdown(x.detail || x.title, MAX_DETAIL)}`,
+        "",
+        "| | |",
+        "|---|---|",
+        ...rows.map(([k, v]) => `| ${k} | ${v} |`),
+        "",
+        "### Steps to reproduce",
+        "",
+        ...(steps.length > 0 ? steps.map((s, i) => `${i + 1}. ${inertMarkdown(s, MAX_STEP)}`) : ["No steps were recorded with this finding."]),
+        "",
+        "### Evidence",
+        "",
+        x.evidence ? inertMarkdown(x.evidence, MAX_EVIDENCE) : "No machine evidence was recorded with this finding.",
+        "",
+    ];
+    if (ctx.criteria?.length)
+        lines.push("### Acceptance criteria it fails", "", ...ctx.criteria.map((c) => `- ${criterionLine(c, inertMarkdown)}`), "");
+    if (ctx.screenshots !== "off") {
+        lines.push("### Screenshots", "");
+        if (ctx.picture)
+            lines.push(`The picture taken when it was filed is in the run's \`.scenescout/\` folder, not attached (GitHub's API cannot upload a file to an issue): ${inertMarkdown(ctx.picture, 200)}`, "");
+        if (ctx.screenshots.length === 0)
+            lines.push(ctx.picture ? "No frames of the steps before it were kept." : noFramesSentence(ctx));
+        else
+            lines.push("Not attached: GitHub's API cannot upload a file to an issue. The run kept these frames of the steps before it was last found, in its `.scenescout/` folder:", "", ...ctx.screenshots.map((s) => `- ${inertMarkdown(s, 200)}`));
+        lines.push("");
+    }
+    lines.push("---", `Filed by SceneScout from finding \`${f.id}\`. A later \`scenescout export\` finds this issue by its \`${MARKER_LABEL}\` label and the hidden marker in this description, and does not file it again.`, "");
+    return { title: issueTitle(f), body: lines.join("\n"), labels: issueLabels(ctx) };
+}
+/** A text node; ADF refuses an empty one, so empty text becomes a dash. */
+const text = (t, marks) => ({ type: "text", text: t || "-", ...(marks ? { marks } : {}) });
+const paragraph = (...content) => ({ type: "paragraph", content });
+const heading = (t) => ({ type: "heading", attrs: { level: 3 }, content: [text(t)] });
+const listItems = (items) => items.map((t) => ({ type: "listItem", content: [paragraph(text(t))] }));
+/**
+ * The description of a Jira issue for a finding, in Atlassian Document Format.
+ * Every text node holds plain text, so nothing in it is markup. Its last line
+ * is the marker, which records the revision of the summary and the rest of
+ * the description (jiraRevision).
+ */
+export function jiraDescription(f, ctx) {
+    const x = fieldsOf(f);
+    const facts = [
+        `Severity: ${f.severity}`,
+        `Category: ${inertPlain(x.category, 40)}`,
+        `Page: ${inertPlain(x.route, 200)}`,
+        `Address: ${inertPlain(x.url, 300)}`,
+        `Last found: ${x.foundAt}`,
+        `Runs that found it: ${x.runs}`,
+        ...(x.regressedAt ? [`Regressed: ${x.regressedAt}: it had been marked resolved`] : []),
+        ...(x.verdict ? [`Last re-test: ${inertPlain(x.verdict, 60)}`] : []),
+        ...(x.convention !== null ? [`Tier: worth a look: a defect only if the project uses ${inertPlain(x.convention, 200)}`] : []),
+    ];
+    const steps = x.repro.slice(-MAX_STEPS).map((s) => inertPlain(s, MAX_STEP));
+    const content = [
+        paragraph(text(inertPlain(x.detail || x.title, MAX_DETAIL))),
+        { type: "bulletList", content: listItems(facts) },
+        heading("Steps to reproduce"),
+        steps.length > 0 ? { type: "orderedList", content: listItems(steps) } : paragraph(text("No steps were recorded with this finding.")),
+        heading("Evidence"),
+        x.evidence
+            ? { type: "codeBlock", content: [text(inertPlain(x.evidence, MAX_EVIDENCE))] }
+            : paragraph(text("No machine evidence was recorded with this finding.")),
+    ];
+    if (ctx.criteria?.length)
+        content.push(heading("Acceptance criteria it fails"), { type: "bulletList", content: listItems(ctx.criteria.map((c) => criterionLine(c, inertPlain))) });
+    if (ctx.screenshots !== "off") {
+        content.push(heading("Screenshots"));
+        if (ctx.picture)
+            content.push(paragraph(text(`Attached: ${inertPlain(uploadName(ctx.picture, ctx.pictureAt), 100)}, the picture taken when it was filed.`)));
+        if (ctx.screenshots.length > 0)
+            content.push(paragraph(text(`Attached: ${ctx.screenshots.map((s, i) => inertPlain(uploadName(s, ctx.screenshotTimes?.[i]), 100)).join(", ")}, the frames of the steps before it was last found.`)));
+        else
+            content.push(paragraph(text(ctx.picture ? "No frames of the steps before it were kept." : noFramesSentence(ctx))));
+    }
+    const revision = jiraRevision(issueTitle(f), content);
+    content.push({ type: "rule" }, paragraph(text("Filed by SceneScout. A later export finds this issue by this line, and updates it while nobody has edited its summary or description: "), text(jiraMarkerText(f.id, revision), [{ type: "code" }])));
+    return { type: "doc", version: 1, content };
+}
+/** The fields of a new Jira issue for a finding. An update sets only `summary` and `description` (jiraEditFields). */
+export function jiraIssueFields(f, ctx) {
+    return {
+        project: { key: ctx.projectKey },
+        issuetype: { name: ctx.issueType },
+        summary: issueTitle(f),
+        description: jiraDescription(f, ctx),
+        labels: issueLabels({ severityName: null, labels: ctx.labels }),
+        ...(ctx.severityName ? { priority: { name: ctx.severityName } } : {}),
+    };
+}
+/** The fields an update of a Jira issue sets: the summary and description SceneScout writes, and nothing a team sets in triage (priority, labels, assignee). */
+export function jiraEditFields(f, ctx) {
+    return { summary: issueTitle(f), description: jiraDescription(f, ctx) };
+}
+/** What an update does to an open issue filed earlier. Nothing is ever removed: a file or link someone took off is added again only while the finding still calls for it. */
+export function planJiraUpdate(f, state, wanted) {
+    const recorded = jiraMarkerRevision(state.description, f.id);
+    let fields;
+    if (recorded === null)
+        fields = "no-revision";
+    // A second finding's marker was put there by a person (the marker's paragraph is not hashed), and a rewrite would drop it.
+    else if (jiraRevision(state.summary, state.description) !== recorded || findingIdsInJiraDescription(state.description).some((id) => id !== f.id))
+        fields = "edited";
+    else
+        fields = jiraMarkerRevision(wanted.description, f.id) === recorded ? "same" : "change";
+    const held = new Set(state.attachments);
+    const linked = new Set(state.links);
+    return { fields, attach: [...new Set(wanted.files)].filter((n) => !held.has(n)), link: wanted.tickets.filter((k) => !linked.has(k)) };
+}
+// ── screenshots ─────────────────────────────────────────────────────────────
+/** Most frames one issue names or attaches: the steps right before the finding was last found. */
+const MAX_SCREENSHOTS = 3;
+/** Frames older than this before a finding's time belong to some earlier step of the run, not to the finding. */
+const FRAME_WINDOW_MS = 10 * 60_000;
+/** How far a frame file's modification time may be from its step's time and still be that step's picture. */
+const FRAME_MTIME_SLACK_MS = 2 * 60_000;
+/**
+ * The frames kept for a finding: from the session that filed it, the last few
+ * steps before it was last found (`foundAt` moves each time a run finds it
+ * again), within a window. A finding with no session names none, since
+ * another session's frame would be another page.
+ */
+export function framesFor(f, log, most = MAX_SCREENSHOTS) {
+    const found = timeOf(f.foundAt);
+    if (!f.session || !found)
+        return [];
+    return log
+        .filter((e) => typeof e.frame === "string" && e.frame !== "" && e.session === f.session)
+        .map((e) => ({ frame: e.frame, at: e.at, t: timeOf(e.at) }))
+        .filter((e) => e.t > 0 && e.t <= found && found - e.t <= FRAME_WINDOW_MS)
+        .sort((a, b) => a.t - b.t)
+        .slice(-most)
+        .map(({ frame, at }) => ({ frame, at }));
+}
+/** Whether a frame file is still the picture written at its step: a later run reusing the session's name rewrites the same file names. */
+export function frameIsOriginal(stepAt, mtimeMs) {
+    const t = timeOf(stepAt);
+    return t > 0 && Math.abs(mtimeMs - t) <= FRAME_MTIME_SLACK_MS;
+}
+/**
+ * What one export does with each candidate: skip what the tracker already
+ * holds, file the rest up to the cap, and leave what is over the cap for the
+ * next export, which files it because these are skipped by then. `existing`
+ * null means the tracker was not asked (a dry run with no credentials).
+ */
+export function planExport(candidates, existing, cap) {
+    let toFile = 0;
+    return candidates.map((finding) => {
+        const issue = existing?.get(finding.id);
+        if (issue)
+            return { finding, outcome: "already-filed", issue };
+        if (toFile >= cap)
+            return { finding, outcome: "over-cap" };
+        toFile++;
+        return { finding, outcome: "file" };
+    });
+}
+/**
+ * Fold another issue into what is already filed for a finding. An open issue
+ * wins over a closed one, then the earlier one, so a finding filed twice by
+ * hand still reads as filed once.
+ */
+export function rememberFiled(map, id, issue) {
+    const held = map.get(id);
+    if (!held || (issue.open && !held.open) || (issue.open === held.open && issue.number < held.number))
+        map.set(id, issue);
+}
+// ── talking to a tracker ────────────────────────────────────────────────────
+/** The longest a rate limit may ask an export to wait before it gives up and says when to try again. */
+export const MAX_RATE_WAIT_MS = 60_000;
+/** How long GitHub asks a client to wait after a secondary rate limit that names no time. */
+const SECONDARY_LIMIT_WAIT_MS = 60_000;
+/**
+ * Whether a response is a rate limit, and how long it asks to wait: 429
+ * always is; a 403 only when it says so, by `retry-after`, by
+ * `x-ratelimit-remaining: 0` (GitHub's primary limit) or by its message
+ * (GitHub's secondary limit, which may send neither header and then asks for
+ * a minute). Any other 403 is a permission the token lacks. `waitMs` null:
+ * no wait was named.
+ */
+export function rateLimit(status, header, nowMs, message = "") {
+    if (status !== 429 && status !== 403)
+        return { limited: false };
+    const named = retryAfterMs(header("retry-after")?.trim(), nowMs);
+    if (named !== undefined)
+        return { limited: true, waitMs: named };
+    if (header("x-ratelimit-remaining")?.trim() === "0") {
+        const reset = Number(header("x-ratelimit-reset"));
+        return { limited: true, waitMs: Number.isFinite(reset) && reset > 0 ? Math.max(0, reset * 1000 - nowMs) : null };
+    }
+    if (status === 403 && /rate limit/i.test(message))
+        return { limited: true, waitMs: SECONDARY_LIMIT_WAIT_MS };
+    return status === 429 ? { limited: true, waitMs: null } : { limited: false };
+}
+/** What a tracker said when it refused a request, as one short line: GitHub's `message` and `errors`, Jira's `errorMessages` and `errors`. */
+export function trackerMessage(body) {
+    if (!body || typeof body !== "object")
+        return "";
+    const b = body;
+    const parts = [];
+    if (typeof b.message === "string")
+        parts.push(b.message);
+    if (Array.isArray(b.errorMessages))
+        parts.push(...b.errorMessages.filter((m) => typeof m === "string"));
+    if (Array.isArray(b.errors))
+        for (const e of b.errors) {
+            if (typeof e === "string")
+                parts.push(e);
+            else if (e && typeof e === "object") {
+                const o = e;
+                const said = [o.field, o.message ?? o.code].filter((v) => typeof v === "string").join(": ");
+                if (said)
+                    parts.push(said);
+            }
+        }
+    else if (b.errors && typeof b.errors === "object")
+        for (const [field, message] of Object.entries(b.errors))
+            if (typeof message === "string")
+                parts.push(`${field}: ${message}`);
+    return oneLine(parts.join("; "), 300);
+}
+/**
+ * The name a picture or frame is attached to a Jira issue under: its file
+ * name after the time it was taken. File names repeat (a session's frames
+ * are numbered from one again when a later run reuses its name, and a
+ * finding's picture keeps its name when it is retaken), so the name alone
+ * cannot say whether an issue already holds this picture.
+ */
+export function uploadName(rel, at) {
+    const t = timeOf(at);
+    const name = frameName(rel);
+    return t
+        ? `${new Date(t)
+            .toISOString()
+            .replace(/[-:]/g, "")
+            .replace(/\.\d+Z$/, "Z")}-${name}`
+        : name;
+}
+/** A line about a finding for the terminal: its severity, its title (no control characters, so no terminal escapes) and its id. */
+export function findingLine(f) {
+    return `${f.severity.padEnd(6)}  ${oneLine(redactSecrets(f.title), 100)}  [finding ${f.id}]`;
+}