spiderlint 0.0.0 → 0.143.0

package/dist/progress.js

@@ -0,0 +1,162 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+import { logUpdateStderr } from "log-update";
+import { relative } from "./crawl/scope.js";
+import { log } from "./logger.js";
+const BAR_WIDTH = 20;
+const REDRAW_MS = 1000;
+const ETA_WINDOW = 50;
+const ETA_MIN_SAMPLES = 3;
+const ETA_Z = 2;
+const COUNT_MS = 250;
+// What a run does, in order: the crawl, then the work on its pages, then the rules.
+export const PHASES = ["crawl", "resources", "probes", "site", "lint"];
+// What each phase is called on the status line.
+const PHASE_TEXT = { crawl: "crawling", resources: "linked resources", probes: "external links", site: "site checks", lint: "rules" };
+// The status line: whether it draws, what it shows, the origin trimmed from its URL, the phase and how far inside it.
+const state = { isOn: false, isShown: false, done: 0, total: 0, page: "", step: "", since: 0, origin: "", last: 0, notified: 0, phase: "crawl", count: undefined, intervals: [] };
+// Called on every change of done or known pages; the server’s scan runner sets it.
+const observer = {};
+// Hands every progress change to `listener`, status line or not.
+export function onProgress(listener) {
+    observer.listener = listener;
+}
+// The current counts to the listener, if one is set.
+function notify() {
+    const total = Math.max(state.done, state.total);
+    const range = eta(state.intervals, total - state.done);
+    state.notified = Date.now();
+    observer.listener?.({ done: state.done, total, phase: state.phase, ...(state.count && { step: { ...state.count } }), ...(range && { eta: etaSpan(range) }) });
+}
+// Turns the status line on for an interactive run; `--no-progress`, a pipe or JSON logs keep it off.
+export function enableProgress(isOn) {
+    state.isOn = isOn;
+}
+// Whether the status line draws, so per-page logs can step down to debug.
+export function isProgressOn() {
+    return state.isOn;
+}
+// Moves the run into `phase`, which has `total` things to do when it knows; the status line comes back for it, and the listener hears it at once.
+export function progressPhase(phase, total) {
+    log.debug({ phase, total }, "progress phase");
+    Object.assign(state, { phase, count: total === undefined ? undefined : { done: 0, total }, page: "", step: "", since: Date.now() });
+    if (state.isOn)
+        state.isShown = true;
+    progressDraw();
+    notify();
+}
+// Counts `done` things finished inside the phase; the listener hears it at most four times a second, and the last one always.
+export function progressCount(done) {
+    if (!state.count)
+        return;
+    state.count.done = done;
+    progressDraw();
+    if (done >= state.count.total || Date.now() - state.notified >= COUNT_MS)
+        notify();
+}
+// Clears the status line once the run no longer reports, whichever phase it ended in.
+export function progressEnd() {
+    if (!state.isShown)
+        return;
+    logUpdateStderr.clear();
+    logUpdateStderr.done();
+    state.isShown = false;
+}
+// Names the page and step in flight, timed from now.
+export function progressStep(page, step) {
+    Object.assign(state, { page, step, since: Date.now() });
+}
+// Counts `done` pages finished and clears the step, redrawing at once.
+export function progressDone(done) {
+    const now = Date.now();
+    // One page since the last joins the window; a jump (a resumed store) only moves the baseline.
+    const isSampled = state.isShown || observer.listener !== undefined;
+    if (isSampled && done - state.done === 1)
+        state.intervals = [...state.intervals, (now - state.last) / 1000].slice(-ETA_WINDOW);
+    else if (isSampled)
+        log.debug({ done, previous: state.done, samples: state.intervals.length }, "progress gap not sampled");
+    Object.assign(state, { done, page: "", step: "", since: 0, last: now });
+    progressDraw();
+    notify();
+}
+// Seconds left as [low, high]: `remaining` gaps at the window’s mean, ± ETA_Z σ of their sum and of the mean itself.
+export function eta(intervals, remaining) {
+    const count = intervals.length;
+    if (count < ETA_MIN_SAMPLES || remaining <= 0)
+        return undefined;
+    const mean = intervals.reduce((sum, gap) => sum + gap, 0) / count;
+    const variance = intervals.reduce((sum, gap) => sum + (gap - mean) ** 2, 0) / (count - 1);
+    const spread = ETA_Z * Math.sqrt(variance * (remaining + (remaining * remaining) / count));
+    return [Math.max(0, remaining * mean - spread), remaining * mean + spread];
+}
+// The range as whole numbers in the unit the high end reaches: the low end rounded down, the high end up.
+export function etaSpan(range) {
+    const [size, unit] = range[1] < 60 ? [1, "second"] : range[1] < 3600 ? [60, "minute"] : [3600, "hour"];
+    return { low: Math.floor(range[0] / size), high: Math.ceil(range[1] / size), unit };
+}
+const SUFFIX = { second: "s", minute: "min", hour: "h" };
+// The range as `ETA 2–4 min`, `ETA under 3 min` while the low end is zero, one value when both ends meet.
+export function etaText(range) {
+    if (!range)
+        return "";
+    const { low, high, unit } = etaSpan(range);
+    if (low === high)
+        return `ETA ${high} ${SUFFIX[unit]}`;
+    return low === 0 ? `ETA under ${high} ${SUFFIX[unit]}` : `ETA ${low}–${high} ${SUFFIX[unit]}`;
+}
+// What the run is at: the page in flight while crawling, else the phase with its count.
+function where() {
+    if (state.phase === "crawl")
+        return relative(state.page, state.origin);
+    return `${PHASE_TEXT[state.phase]}${state.count ? ` ${state.count.done}/${state.count.total}` : ""}`;
+}
+// The line as drawn: a bar, done/known, the ETA, the step, the page, seconds on the step.
+function line() {
+    const { done } = state;
+    const total = Math.max(done, state.total);
+    const filled = total > 0 ? Math.min(BAR_WIDTH, Math.round((done / total) * BAR_WIDTH)) : 0;
+    const seconds = state.since > 0 ? `${Math.round((Date.now() - state.since) / 1000)} s` : "";
+    return [`▕${"█".repeat(filled)}${"░".repeat(BAR_WIDTH - filled)}▏`, `${done}/${total}`, etaText(eta(state.intervals, total - done)), state.step, where(), seconds].filter(Boolean).join(" ");
+}
+// Draws the line again in place.
+function progressDraw() {
+    if (state.isShown)
+        logUpdateStderr(line());
+}
+// Writes `text` above the line, or straight to stderr while it is hidden.
+export function progressPrint(text) {
+    if (!state.isShown) {
+        process.stderr.write(text);
+        return;
+    }
+    logUpdateStderr.persist(text);
+    progressDraw();
+}
+// Reads the known total, keeping the last one when the queue cannot answer, and redraws.
+async function refresh(known) {
+    try {
+        state.total = await known();
+    }
+    catch (error) {
+        log.debug({ error: String(error), total: state.total }, "progress total unreadable; last kept");
+    }
+    progressDraw();
+    notify();
+}
+// Redraws each second from `known` until the returned stop runs, which clears the line.
+export function trackProgress(known, origin) {
+    if (!state.isOn && !observer.listener)
+        return () => { };
+    Object.assign(state, { isShown: state.isOn, origin, last: Date.now(), intervals: [], phase: "crawl", count: undefined });
+    const timer = setInterval(() => void refresh(known), REDRAW_MS);
+    timer.unref();
+    return () => {
+        clearInterval(timer);
+        if (state.isShown)
+            logUpdateStderr.clear();
+        if (state.isShown)
+            logUpdateStderr.done();
+        state.isShown = false;
+    };
+}

package/dist/report/agent.js

@@ -0,0 +1,122 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { writeAtomic } from "../cache/index.js";
+import { relative, singleOrigin } from "../crawl/scope.js";
+import { isRanked } from "../facts/flatten.js";
+import { log } from "../logger.js";
+import { fixFor } from "../rules/fix.js";
+import { cachedReads, inEnglish, valuesAt } from "../rules/message.js";
+import { utc } from "../facts/read-note.js";
+import { importance, scoreOf } from "../rules/score.js";
+import { bundle } from "./human.js";
+import { passing } from "./rating.js";
+import { printable, printableFinding } from "./printable.js";
+// Pages a fix clears: a fold’s occurrences, an aggregate’s URLs, else the one page.
+function clears(finding) {
+    return finding.occurrences ?? finding.urls?.length ?? 1;
+}
+// The origin to re-audit for a finding: the audited one, else its URL’s, else the host it names.
+function originOf(finding, shared) {
+    return shared || (URL.canParse(finding.url) ? new URL(finding.url).origin : `https://${finding.url}`);
+}
+// Findings grouped by rule, rules by their most important finding (score times the share of pages touched) then the pages they clear, findings within a rule by the same.
+export function ordered(findings, pages) {
+    const byRule = new Map();
+    for (const finding of findings)
+        byRule.set(finding.rule, [...(byRule.get(finding.rule) ?? []), finding]);
+    const total = (same) => same.reduce((sum, finding) => sum + clears(finding), 0);
+    const top = (same) => Math.max(...same.map((finding) => importance(finding, pages)));
+    const rules = byRule
+        .values()
+        .map((same) => same.toSorted((a, b) => importance(b, pages) - importance(a, pages) || clears(b) - clears(a) || a.url.localeCompare(b.url)))
+        .toArray();
+    return rules.toSorted((a, b) => top(b) - top(a) || total(b) - total(a) || a[0].rule.localeCompare(b[0].rule));
+}
+// Where a finding sits: a fold’s samples, an aggregate’s URLs, or its pages, each with its values and locations.
+function where(same, origin) {
+    const finding = same[0];
+    const named = (url, owner) => [relative(url, origin), ...valuesAt(owner, url, inEnglish).map((value) => relative(value, origin))].join(": ");
+    const at = (url, locations, owner = finding) => [`- ${named(url, owner)}`, ...(locations ?? []).map((location) => `  - at ${location}`)];
+    if (finding.occurrences !== undefined) {
+        const pages = finding.sampled === undefined ? `${finding.occurrences} pages` : `${finding.occurrences} of ${finding.sampled} sampled pages`;
+        return [`Where: ${pages} ${finding.groups ? `in groups ${finding.groups.join(", ")}` : `of group ${finding.group}`} (${Math.round((finding.coverage ?? 0) * 100)} %), for example:`, ...(finding.samples ?? []).flatMap((url) => at(url, finding.sampleLocations?.[url]))];
+    }
+    if (finding.urls)
+        return [`Where: ${named(finding.url, finding)}, used by or shared with:`, ...finding.urls.flatMap((url) => at(url, undefined)), ...(finding.locations ?? []).map((location) => `- at ${location}`)];
+    return same.length > 1 ? [`Where: ${same.length} pages:`, ...same.flatMap((page) => at(page.url, page.locations, page))] : [`Where: ${named(finding.url, finding)}`, ...(finding.locations ?? []).map((location) => `- at ${location}`)];
+}
+// The reads a bundle took from a cache, so the agent knows a fix may already be live.
+function cached(same, origin) {
+    const reads = cachedReads(same);
+    return reads.length === 0 ? [] : ["From the cache (`--refresh` reads them again):", ...reads.map((read) => `- ${relative(read.key, origin) || read.key}${read.at ? `, read ${utc(read.at)}` : ""}`)];
+}
+// One self-contained task over findings sharing rule and message: rule and severity, message, place, what the rule reads and expects, the fix and how to prove it.
+function block(same, guide, origin) {
+    const finding = same[0];
+    const target = originOf(finding, origin);
+    const reads = guide?.facts.length ? `Reads: ${guide.facts.map((fact) => `\`${fact}\``).join(", ")}${guide.expect ? `, expects \`${JSON.stringify(guide.expect)}\`` : ""}` : "";
+    const facts = finding.scope === "page" && guide?.expect ? `, and \`spiderlint show-facts ${finding.samples?.[0] ?? finding.url}\` shows \`${guide.facts[0]}\` meeting it` : "";
+    const fix = guide?.fix ? `Fix: ${fixFor(guide.fix, finding)}` : guide?.docs ? `Fix: follow ${guide.docs}` : "";
+    return [
+        `## ${finding.rule} (${finding.severity} ${scoreOf(finding).toFixed(1)})`,
+        "",
+        origin ? finding.message.replaceAll(`${origin}/`, "/") : finding.message,
+        "",
+        ...where(same, origin),
+        ...cached(same, origin),
+        ...[reads, fix, guide?.fix && guide.docs ? `Docs: ${guide.docs}` : ""].filter(Boolean),
+        `Done when: \`spiderlint audit ${target}/ --rules ${finding.rule}\` reports no ${finding.rule} finding${facts}.`,
+    ].join("\n");
+}
+// The origin every finding shares, from the pages, else from the findings when the report was stored without them.
+function sharedOrigin(report) {
+    return singleOrigin(report.pages.length > 0 ? report.pages.map((page) => page.url.href) : report.findings.map((finding) => finding.url));
+}
+// Findings a coding agent acts on: hints only when listed.
+function actionable(report, isHintListed) {
+    const findings = report.findings.filter((finding) => isHintListed || finding.severity !== "hint").map((finding) => printableFinding(finding));
+    log.debug({ findings: findings.length, hints: report.findings.length - findings.length, isHintListed }, "agent findings chosen");
+    return findings;
+}
+// CO2, bytes, requests and timings as one Markdown table, so an agent weighs a fix against the site; nothing without statistics.
+function statistics(stats = {}) {
+    const rows = Object.entries(stats)
+        .filter(([path]) => isRanked(path))
+        .map(([path, stat]) => `| \`${printable(path).replaceAll("|", String.raw `\|`)}\` | ${[stat.count, stat.min, stat.median, stat.p95, stat.max, stat.total ?? "–"].join(" | ")} |`);
+    return rows.length === 0 ? [] : [["# Site statistics", "", "| Fact | Pages | Min | Median | p95 | Max | Total |", "| --- | --: | --: | --: | --: | --: | --: |", ...rows].join("\n")];
+}
+// How many checks and rules came out clean, as one line; the list stays in `json`.
+function passed({ checks, checked }) {
+    return [`Checks passed: ${checks.passed} of ${checks.total}; ${passing(checked).length} rules failed nowhere.`];
+}
+// One block per finding after folding, no colour, then the fact statistics; the shared origin once on top and URLs under it relative.
+export function formatAgent(report, _paint, _isFull, _lang, isHintListed = false) {
+    const origin = sharedOrigin(report);
+    const blocks = ordered(actionable(report, isHintListed), report.pages.length).flatMap((rule) => bundle(rule).map((same) => block(same, report.rules?.[same[0].rule], origin)));
+    return [`# spiderlint findings${origin ? ` for ${origin}` : ""}`, ...(blocks.length > 0 ? blocks : ["No findings."]), ...passed(report.summary), ...statistics(report.summary.stats)].join("\n\n");
+}
+// One Markdown prompt per rule, by file name, the same findings always giving the same bytes.
+export function agentFiles(report, isHintListed = false) {
+    const origin = sharedOrigin(report);
+    const files = new Map();
+    const rules = ordered(actionable(report, isHintListed), report.pages.length);
+    for (const same of rules) {
+        const rule = same[0].rule;
+        const title = `# spiderlint: ${rule}${origin ? ` on ${origin}` : ""}`;
+        files.set(`${rule.replaceAll(/[^a-z0-9.-]+/gi, "-")}.md`, `${[title, ...bundle(same).map((bundled) => block(bundled, report.rules?.[rule], origin))].join("\n\n")}\n`);
+    }
+    log.debug({ files: files.size }, "agent files rendered");
+    return files;
+}
+// Writes each rule’s prompt into `directory`, atomically, so a reader never sees half a file.
+export async function writeAgentFiles(directory, report, isHintListed = false) {
+    await mkdir(directory, { recursive: true });
+    const files = agentFiles(report, isHintListed);
+    const entries = [...files];
+    for (const [name, content] of entries)
+        await writeAtomic(path.join(directory, name), content);
+    log.info({ directory, files: files.size }, `${files.size} agent prompts written to ${directory}`);
+}

package/dist/report/checkstyle.js

@@ -0,0 +1,22 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+import { printable } from "./printable.js";
+const XML_ESCAPES = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&apos;" };
+function escapeXml(text) {
+    return printable(text).replaceAll(/["&'<>]/g, (char) => XML_ESCAPES[char] ?? char);
+}
+// `line` and `column` from a `line:column selector` location, when the first one has them.
+function position(finding) {
+    const match = /^(\d+):(\d+)/.exec(finding.locations?.[0] ?? "");
+    return match ? ` line="${match[1]}" column="${match[2]}"` : "";
+}
+function toError(finding) {
+    return `    <error${position(finding)} severity="${finding.severity === "hint" ? "info" : finding.severity}" message="${escapeXml(finding.message)}" source="spiderlint.${escapeXml(finding.rule)}"/>`;
+}
+// Checkstyle XML: one `<file>` per URL, in first-seen order, one `<error>` per finding.
+export function formatCheckstyle(report) {
+    const byUrl = Map.groupBy(report.findings, (finding) => finding.url);
+    const files = [...byUrl].map(([url, findings]) => [`  <file name="${escapeXml(url)}">`, ...findings.map((finding) => toError(finding)), "  </file>"].join("\n"));
+    return ['<?xml version="1.0" encoding="UTF-8"?>', '<checkstyle version="10.12.0">', ...files, "</checkstyle>"].join("\n");
+}

package/dist/report/csv.js

@@ -0,0 +1,18 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+import { scoreOf } from "../rules/score.js";
+const COLUMNS = ["severity", "score", "rule", "scope", "group", "url", "message", "occurrences", "locations"];
+// RFC 4180 field: quoted when it holds a quote, comma or line break, quotes doubled.
+export function field(value) {
+    const text = String(value ?? "");
+    return /[\n\r",]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
+}
+function toRow(finding) {
+    const cells = [finding.severity, scoreOf(finding).toFixed(1), finding.rule, finding.scope, finding.group, finding.url, finding.message, finding.occurrences, finding.locations?.join("\n")];
+    return cells.map((cell) => field(cell)).join(",");
+}
+// RFC 4180 CSV with a header row, one row per finding, CRLF line endings.
+export function formatCsv(report) {
+    return [COLUMNS.join(","), ...report.findings.map((finding) => toRow(finding))].join("\r\n");
+}

package/dist/report/html.js

@@ -0,0 +1,266 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+import { relative, singleOrigin } from "../crawl/scope.js";
+import { shippedRules } from "../rules/catalog.js";
+import { fixFor } from "../rules/fix.js";
+import { cachedReads, sentence, valuesAt } from "../rules/message.js";
+import { bytes, isLabelled, label, withUnit } from "../facts/labels.js";
+import { utc } from "../facts/read-note.js";
+import { environmentLanguage, environmentLocale, translator } from "../i18n.js";
+import { impact, pagesOf, scoreOf } from "../rules/score.js";
+import { ordered } from "./agent.js";
+import { bundle } from "./human.js";
+import { passing } from "./rating.js";
+const ORDER = { error: 0, warning: 1, info: 2, hint: 3 };
+const LIST = 5;
+const ENTITIES = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
+// The one stylesheet of the report and the server pages, inline so a saved report stands alone.
+export const STYLE = `
+:root { color-scheme: light dark; --fg: light-dark(#26231c, #ece7da); --muted: light-dark(#6a6454, #a99f88); --bg: light-dark(#f7f5ef, #13110d); --surface: light-dark(#fff, #1b1812); --line: light-dark(#e3ded0, #353025); --accent: light-dark(#7a5c21, #dccfa6); --error: light-dark(#b3261e, #ff8a80); --warning: light-dark(#8a5a00, #ffcc66); --info: light-dark(#1d5fa8, #8ab4f8); --good: light-dark(#1e7a34, #7ee2a8); --good-bg: light-dark(#eef7f0, #14231a); --good-line: light-dark(#b9dcc3, #25492f); --mid: light-dark(#b45d00, #ffb870); --gap: 1.5rem; }
+* { box-sizing: border-box; }
+body { margin: 0 auto; max-inline-size: 68rem; padding: 0 var(--gap) 3rem; font: 1rem/1.6 system-ui, sans-serif; color: var(--fg); background: var(--bg); }
+a { color: var(--accent); overflow-wrap: anywhere; text-underline-offset: .2em; }
+h1 { font-size: 1.75rem; line-height: 1.25; margin-block: 0 .5rem; overflow-wrap: anywhere; }
+h2 { font-size: 1.25rem; margin-block: 3rem 1rem; }
+h3 { font-size: .95rem; font-weight: 600; margin-block: 2rem .75rem; }
+p { margin-block: 0 1rem; }
+small, .muted { color: var(--muted); }
+code { font-size: .9em; overflow-wrap: anywhere; }
+main { padding-block: 2.5rem; }
+.site { display: flex; flex-wrap: wrap; gap: 1rem 2rem; align-items: center; justify-content: space-between; padding-block: 1.5rem; border-block-end: 1px solid var(--line); }
+.site nav { display: flex; gap: 1.5rem; }
+.brand { display: inline-flex; gap: .75rem; align-items: center; color: var(--fg); font-size: 1.15rem; font-weight: 700; letter-spacing: .02em; text-decoration: none; }
+.brand img { display: block; }
+.site nav a, .foot a { text-decoration: none; } .site nav a:hover, .foot a:hover { text-decoration: underline; }
+.foot { display: flex; flex-wrap: wrap; gap: .5rem 1.5rem; padding-block: 1.5rem; border-block-start: 1px solid var(--line); font-size: .9rem; color: var(--muted); }
+.foot p { flex: 1 1 100%; margin: 0; }
+.hero { display: flex; gap: 2rem; align-items: center; padding: 2rem; background: var(--surface); border: 1px solid var(--line); }
+.hero p { margin: 0; }
+.grade { display: grid; place-items: center; inline-size: 5.5rem; block-size: 5.5rem; flex: none; font-size: 2.75rem; font-weight: 700; color: var(--bg); background: var(--muted); }
+.grade-S, .grade-A { background: var(--good); } .grade-B { background: var(--warning); } .grade-C, .grade-D { background: var(--mid); } .grade-E, .grade-F { background: var(--error); }
+.kpis { display: grid; grid-template-columns: repeat(auto-fit, minmax(9.5rem, 1fr)); gap: 1rem; margin-block: 1rem; }
+.kpi { padding: 1rem 1.25rem; background: var(--surface); border: 1px solid var(--line); }
+.kpi b { display: block; font-size: 1.5rem; line-height: 1.3; font-variant-numeric: tabular-nums; }
+.kpi span { color: var(--muted); font-size: .8rem; letter-spacing: .04em; text-transform: uppercase; }
+.kpi.good { background: var(--good-bg); border-color: var(--good-line); } .kpi.good b { color: var(--good); }
+.pills { display: flex; flex-wrap: wrap; gap: .5rem; margin-block-end: 0; }
+.pill { padding: .25rem .75rem; border: 1px solid var(--line); font-size: .875rem; color: var(--muted); }
+.pill.error, .pill.warning, .pill.info { background: var(--surface); }
+.notice { display: flex; flex-wrap: wrap; gap: .5rem 1.5rem; align-items: center; justify-content: space-between; margin-block: 0 1.5rem; padding: 1rem 1.25rem; background: var(--surface); border: 1px solid var(--line); border-inline-start: .25rem solid var(--accent); }
+.notice p { margin: 0; }
+.button, button { display: inline-block; font: inherit; padding: .75rem 1.5rem; border: 0; color: var(--bg); background: var(--accent); text-decoration: none; cursor: pointer; }
+.button:hover, button:hover { filter: brightness(1.1); }
+.rule-card { margin-block: 1rem; background: var(--surface); border: 1px solid var(--line); border-inline-start: .25rem solid var(--muted); }
+.rule-card.error { border-inline-start-color: var(--error); } .rule-card.warning { border-inline-start-color: var(--warning); } .rule-card.info { border-inline-start-color: var(--info); }
+.rule-card.passed { border-inline-start-color: var(--good); } .rule-card.untested { border-inline-start-color: var(--line); }
+.rule-head { display: flex; align-items: baseline; gap: .75rem; padding: 1rem 1.25rem; list-style: none; }
+.rule-card summary::marker { content: ""; } .rule-card summary::-webkit-details-marker { display: none; }
+.rule-head .badge { flex: none; font-weight: 700; font-size: .8rem; letter-spacing: .04em; text-transform: uppercase; font-variant-numeric: tabular-nums; }
+.rule-head code, .rule-head > a { flex: none; }
+.rule-head .rule-message { overflow-wrap: anywhere; }
+.rule-head .rule-arrow { margin-inline-start: auto; flex: none; color: var(--muted); }
+.rule-findings { padding: 0 1.25rem .5rem; } .rule-findings .data { color: var(--muted); font-variant-numeric: tabular-nums; margin-inline-start: .75em; } .rule-findings p { margin-block: .5rem 0; }
+.rule-foot { display: grid; grid-template-columns: minmax(0, 1fr) 10rem 13rem; gap: .5rem 1.5rem; padding: .75rem 1.25rem; border-block-start: 1px solid var(--line); font-size: .85rem; color: var(--muted); font-variant-numeric: tabular-nums; }
+.rule-foot > :nth-last-child(2) { grid-column: 2; } .rule-foot > :last-child { grid-column: 3; text-align: end; }
+table { inline-size: 100%; border-collapse: collapse; background: var(--surface); }
+th, td { text-align: start; vertical-align: top; padding: .75rem 1rem; border-block-end: 1px solid var(--line); }
+th { color: var(--muted); font-weight: 500; font-size: .85rem; }
+.error { color: var(--error); } .warning { color: var(--warning); } .info { color: var(--info); } .hint { color: var(--muted); }
+summary { cursor: pointer; } summary h2, summary h3 { display: inline; margin: 0; } section > details:has(> summary > h2) { margin-block: 3rem 1rem; }
+ul { margin: .5rem 0 0; padding-inline-start: 1.25rem; }
+.tick { color: var(--good); font-weight: 700; }
+h4 { font-size: .9rem; font-weight: 500; color: var(--muted); margin-block: 1.5rem .5rem; }
+form { display: flex; flex-wrap: wrap; gap: .75rem; margin-block: 2rem; }
+form label.muted { flex: 1 1 100%; }
+fieldset { flex: 1 1 100%; border: 0; padding: 0; margin: 1rem 0 0; display: grid; gap: .5rem; } fieldset label { display: block; padding: .75rem 1rem; background: var(--surface); border: 1px solid var(--line); }
+legend { padding: 0; }
+input[type=radio] { flex: none; inline-size: auto; margin-inline-end: .5rem; }
+input { flex: 1 1 20rem; font: inherit; padding: .75rem 1rem; border: 1px solid var(--line); color: inherit; background: var(--surface); }
+progress { inline-size: 100%; block-size: .75rem; accent-color: var(--accent); }
+.alert { border-inline-start: .25rem solid var(--error); padding: 1rem 1.25rem; background: light-dark(#fdecea, #2c1614); }
+.skip { position: absolute; inset-inline-start: 1rem; inset-block-start: -4rem; padding: .5rem 1rem; background: var(--surface); z-index: 1; } .skip:focus { inset-block-start: 1rem; }
+@media (max-width: 40rem) { .hero { flex-direction: column; align-items: flex-start; padding: 1.5rem; } body { padding-inline: 1rem; } .rule-foot { grid-template-columns: minmax(0, 1fr); } .rule-foot > :nth-last-child(2), .rule-foot > :last-child { grid-column: auto; text-align: start; } }
+`;
+// `value` as HTML text or a quoted attribute.
+export function escape(value) {
+    return String(value).replaceAll(/[&<>"']/g, (character) => ENTITIES[character]);
+}
+// A whole page in the translator’s language and direction.
+export function page(t, title, body, head = "") {
+    return `<!DOCTYPE html>\n<html lang="${t.lang}" dir="${t.dir}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="color-scheme" content="light dark"><meta name="theme-color" media="(prefers-color-scheme: light)" content="#f7f5ef"><meta name="theme-color" media="(prefers-color-scheme: dark)" content="#13110d"><title>${escape(title)}</title><style>${STYLE}</style>${head}</head><body>${body}</body></html>\n`;
+}
+// Translated severity names; the rule ID beside them is never translated.
+function severityName(t, severity) {
+    return { error: t._("Error"), warning: t._("Warning"), info: t._("Info"), hint: t._("Hint") }[severity];
+}
+// A link to a crawled http(s) URL, shown relative to the shared origin; anything else is plain text.
+function link(url, origin) {
+    const text = escape(relative(url, origin) || url);
+    return /^https?:\/\//i.test(url) ? `<a href="${escape(url)}" rel="nofollow noopener noreferrer">${text}</a>` : text;
+}
+// A list whose items past the first few fold into a disclosure.
+function items(t, values) {
+    if (values.length === 0)
+        return "";
+    const shown = `<ul>${values
+        .slice(0, LIST)
+        .map((value) => `<li>${value}</li>`)
+        .join("")}</ul>`;
+    return values.length > LIST
+        ? `${shown}<details><summary>${escape(t._("{count} more", { count: t.number(values.length - LIST) }))}</summary><ul>${values
+            .slice(LIST)
+            .map((value) => `<li>${value}</li>`)
+            .join("")}</ul></details>`
+        : shown;
+}
+// Locations under what they locate, as code.
+function locations(t, found) {
+    return items(t, (found ?? []).map((location) => `<code>${escape(location)}</code>`));
+}
+// What was measured at `url`, after it.
+function measured(t, finding, url) {
+    const values = valuesAt(finding, url, t.number);
+    return values.length === 0 ? "" : `<span class="data">${escape(values.join("  "))}</span>`;
+}
+// What a bundle names, how many pages it spans and those pages, each with its values and locations.
+function reach(t, same, origin, total) {
+    const [first] = same;
+    const at = (finding, url, found) => `${link(url, origin)}${measured(t, finding, url)}${locations(t, found)}`;
+    if (same.length > 1)
+        return { subject: "", count: same.length, isWhole: total > 0 && same.length >= total, pages: same.map((finding) => at(finding, finding.url, finding.locations)) };
+    if (first.occurrences !== undefined)
+        return { subject: "", count: first.occurrences, isWhole: (first.coverage ?? 0) >= 1, pages: (first.samples ?? []).map((url) => at(first, url, first.sampleLocations?.[url])) };
+    if (first.urls)
+        return { subject: first.urls.includes(first.url) ? "" : first.url, count: first.urls.length, isWhole: total > 0 && first.urls.length >= total, pages: first.urls.map((url) => at(first, url)) };
+    return { subject: first.url, isWhole: first.scope === "site", pages: [] };
+}
+// The observations a bundle took from a cache, each with when it was read; nothing when every one came fresh.
+function cached(t, same, origin) {
+    const reads = cachedReads(same);
+    if (reads.length === 0)
+        return "";
+    return `<p class="muted">${escape(t._("From the cache, so a refreshed run reads them again:"))}</p>${items(t, reads.map((read) => `${link(read.key, origin)}${read.at ? `<span class="data">${escape(t._("read {at}", { at: utc(read.at) }))}</span>` : ""}`))}`;
+}
+// The rule’s fix filled for this finding, then its docs link; nothing when the rule has neither.
+function remedy(t, guide, finding) {
+    const fix = guide?.fix ? `<p>${escape(t._("Fix: {fix}", { fix: fixFor(guide.fix, finding) }))}</p>` : "";
+    const documentation = guide?.docs && /^https?:\/\//i.test(guide.docs) ? `<p><a href="${escape(guide.docs)}" rel="noopener noreferrer">${escape(t._("Documentation"))}</a></p>` : "";
+    return fix + documentation;
+}
+// Score times pages, summed over a bundle.
+function bundleImpact(same, total) {
+    return same.reduce((sum, finding) => sum + impact(finding, total), 0);
+}
+// One card per bundle: severity, message and subject on its head; expanded, the pages, locations, fix and docs; rule, impact and scope on its foot.
+function entry(t, same, origin, guides, total) {
+    const [first] = same;
+    const { subject, isWhole, pages } = reach(t, same, origin, total);
+    const said = sentence(first, t);
+    const message = origin ? said.replaceAll(`${origin}/`, "/") : said;
+    const hasLocations = same.some((finding) => finding.locations?.length) || Object.keys(first.sampleLocations ?? {}).length > 0;
+    const share = first.occurrences === undefined
+        ? ""
+        : `<p class="muted">${escape(first.sampled === undefined ? t._("Pages: {count} ({share})", { count: t.number(first.occurrences), share: t.number(first.coverage ?? 0, { style: "percent" }) }) : t._("Sampled pages: {count} of {sampled} ({share})", { count: t.number(first.occurrences), sampled: t.number(first.sampled), share: t.number(first.coverage ?? 0, { style: "percent" }) }))}${first.groups ? ` ${escape(t._("Groups: {groups}", { groups: first.groups.join(", ") }))}` : ""}</p>`;
+    const own = same.length === 1 && first.occurrences === undefined && !first.urls ? `${measured(t, first, first.url)}${locations(t, first.locations)}` : "";
+    const listed = isWhole && !hasLocations ? "" : items(t, pages);
+    const pageCount = same.reduce((sum, finding) => sum + pagesOf(finding, total), 0);
+    const scope = isWhole || (total > 0 && pageCount >= total) ? t._("Whole site") : t._("Pages: {count}", { count: t.number(pageCount) });
+    const foot = `<code>${escape(first.rule)}</code><span>${escape(t._("Impact"))}: ${escape(t.number(bundleImpact(same, total), { maximumFractionDigits: 1 }))}</span><span>${escape(t._("Scope"))}: ${escape(scope)}</span>`;
+    return `<article class="rule-card ${first.severity}"><details><summary class="rule-head"><span class="badge ${first.severity}">${escape(severityName(t, first.severity))} ${scoreOf(first).toFixed(1)}</span><span class="rule-message">${escape(message)}${subject ? ` — ${link(subject, origin)}` : ""}</span><span class="rule-arrow" aria-hidden="true">▾</span></summary><div class="rule-findings">${share}${listed}${own}${cached(t, same, origin)}${remedy(t, guides?.[first.rule], first)}</div></details><footer class="rule-foot">${foot}</footer></article>`;
+}
+// One flat card per bundle, the highest impact first, a rule’s bundles in its own order on a tie.
+function rules(t, findings, origin, guides, total) {
+    return bundle(ordered(findings, total).flat())
+        .toSorted((a, b) => bundleImpact(b, total) - bundleImpact(a, total))
+        .map((same) => entry(t, same, origin, guides, total))
+        .join("");
+}
+// A fact’s translated label with its path on hover, or the path as code when it has none.
+function factName(t, path) {
+    const english = label(path);
+    return english ? `<span title="${escape(path)}">${escape(t._(english))}</span>` : `<code>${escape(path)}</code>`;
+}
+// Every labelled numeric fact’s pages, then min, median, p95, max and total in its unit, in a closed disclosure; nothing without statistics.
+function statistics(t, stats = {}) {
+    const rows = Object.entries(stats)
+        .filter(([path]) => isLabelled(path))
+        .map(([path, stat]) => `<tr><td>${factName(t, path)}</td><td>${escape(t.number(stat.count))}</td>${[stat.min, stat.median, stat.p95, stat.max, stat.total].map((value) => `<td>${escape(value === undefined ? "–" : withUnit(path, value, t.number))}</td>`).join("")}</tr>`);
+    const head = [t._("Fact"), t._("Pages"), t._("Minimum"), t._("Median"), t._("95th percentile"), t._("Maximum"), t._("Total")].map((label) => `<th>${escape(label)}</th>`).join("");
+    return rows.length === 0 ? "" : `<section><details><summary><h2>${escape(t._("Statistics"))}</h2></summary><table><thead><tr>${head}</tr></thead><tbody>${rows.join("")}</tbody></table></details></section>`;
+}
+// The rules that ran and failed nowhere, one green card per rule; nothing without any.
+function passed(t, report) {
+    const clean = passing(report.summary.checked);
+    const rows = clean.map(([id, rule]) => {
+        const fix = report.rules?.[id]?.fix;
+        const body = fix ? `<div class="rule-findings"><p class="muted">${escape(fixFor(fix))}</p></div>` : "";
+        const foot = `<span>${escape(t._("Impact"))}: ${escape(t.number(0))}</span><span>${escape(t._("Scope"))}: ${escape(t._("Pages: {count}", { count: t.number(rule.pages) }))}</span>`;
+        return `<details class="rule-card passed"><summary class="rule-head"><span class="tick" aria-hidden="true">✓</span><code>${escape(id)}</code><span class="rule-arrow" aria-hidden="true">▾</span></summary>${body}<footer class="rule-foot">${foot}</footer></details>`;
+    });
+    const counts = { rules: t.number(clean.length), pages: t.number(report.summary.pages), checks: t.number(clean.reduce((sum, [, rule]) => sum + rule.checks, 0)) };
+    const heading = escape(t._("Passed: {rules} rules, {pages} pages, {checks} checks", counts));
+    return rows.length === 0 ? "" : `<section class="passed"><details open><summary><h2>${heading}</h2></summary>${rows.join("")}</details></section>`;
+}
+// The shipped rules that judged nothing, one muted row per rule linked to its docs, with its preset’s description and presets; nothing when every rule ran.
+function untested(t, ids = []) {
+    if (ids.length === 0)
+        return "";
+    const shipped = shippedRules();
+    const rows = ids.map((id) => {
+        const { docs, presets = [] } = shipped.get(id) ?? {};
+        const name = docs && /^https?:\/\//i.test(docs) ? `<a href="${escape(docs)}" rel="noopener noreferrer"><code>${escape(id)}</code></a>` : `<code>${escape(id)}</code>`;
+        const named = presets.length > 0 ? ` <small class="muted">· ${escape(t._("Presets: {names}", { names: presets.map((preset) => preset.name).join(", ") }))}</small>` : "";
+        return `<article class="rule-card untested"><div class="rule-head">${name}<span class="rule-message muted">${escape(presets[0]?.description ?? "")}${named}</span></div></article>`;
+    });
+    const heading = escape(t._("Skipped: {count} rules", { count: t.number(ids.length) }));
+    return `<section class="untested"><details><summary><h2>${heading}</h2></summary><p class="muted">${escape(t._("Rules this scan did not judge: its checks leave them out, or the site has nothing they apply to."))}</p>${rows.join("")}</details></section>`;
+}
+// The rating, the totals, then Findings (whole site, pages by group, vendors, hints), Passed, Statistics and Skipped; a finding’s sentence is translated when its template is catalogued.
+export function reportBody(report, t, title, origin) {
+    const { summary } = report;
+    const { rating } = summary;
+    const started = new Intl.DateTimeFormat(t.locale, { dateStyle: "medium", timeStyle: "short" }).format(new Date(summary.started));
+    const head = `<header class="hero"><p class="grade grade-${rating?.grade ?? "none"}" title="${escape(t._("Rating"))}">${escape(rating?.grade ?? "–")}</p><div><h1>${escape(title)}</h1><p class="muted">${escape(rating ? t._("Rulesets: {names}", { names: rating.rulesets.join(", ") }) : t._("No checks ran"))} · ${escape(started)}</p></div></header>`;
+    const kpi = (value, name, tone = "") => `<div class="kpi${tone && ` ${tone}`}"><b>${escape(value)}</b><span>${escape(name)}</span></div>`;
+    const measured = [
+        kpi(t.number(summary.pages), t._("Pages")),
+        kpi(bytes(summary.bytes, t.number), t._("Size")),
+        kpi(t.number(summary.durationMs / 1000, { style: "unit", unit: "second" }), t._("Time")),
+        kpi(t._("{passed} of {total}", { passed: t.number(summary.checks.passed), total: t.number(summary.checks.total) }), t._("Checks passed"), "good"),
+    ];
+    const counted = Object.keys(ORDER).map((severity) => {
+        const count = summary.findings[severity] ?? 0;
+        return `<span class="pill${count > 0 ? ` ${severity}` : ""}">${escape(`${severityName(t, severity)}: ${t.number(count)}`)}</span>`;
+    });
+    const totals = `<div class="kpis">${measured.join("")}</div><p class="pills">${counted.join("")}</p>`;
+    const groups = new Map();
+    const vendors = new Map();
+    const hints = report.findings.filter((finding) => finding.severity === "hint");
+    for (const finding of report.findings) {
+        if (finding.severity === "hint")
+            continue;
+        const [sections, key] = finding.vendor ? [vendors, finding.vendor] : [groups, finding.scope === "site" ? "" : finding.group];
+        sections.set(key, [...(sections.get(key) ?? []), finding]);
+    }
+    const cards = (findings) => rules(t, findings, origin, report.rules, summary.pages);
+    const site = groups.get("") ?? [];
+    groups.delete("");
+    const isOnlyDefault = groups.keys().every((group) => group === "default") && Object.keys(summary.groups).length <= 1;
+    const byGroup = [...groups].map(([group, findings]) => `${isOnlyDefault ? "" : `<h4>${escape(t._("Group: {name} · Pages: {count}", { name: group, count: t.number(summary.groups[group] ?? 0) }))}</h4>`}${cards(findings)}`);
+    const parts = [
+        site.length > 0 ? `<h3>${escape(t._("Whole site"))}</h3>${cards(site)}` : "",
+        byGroup.length > 0 ? `<h3>${escape(t._("Pages"))}</h3>${byGroup.join("")}` : "",
+        ...[...vendors].map(([vendor, findings]) => `<h3>${escape(t._("Vendor: {name}", { name: vendor }))}</h3>${cards(findings)}`),
+        hints.length > 0 ? `<details><summary><h3>${escape(t._("Hints: {count}", { count: t.number(hints.length) }))}</h3></summary>${cards(hints)}</details>` : "",
+    ].filter(Boolean);
+    const found = `<section><h2>${escape(t._("Findings"))}</h2>${parts.length > 0 ? parts.join("") : `<p>${escape(t._("No findings."))}</p>`}</section>`;
+    return `${head}${totals}${found}${passed(t, report)}${statistics(t, summary.stats)}${untested(t, summary.untested)}`;
+}
+// A standalone page in `lang`, the process locale unless named; colour and `isFull` do not apply, since every list folds into a disclosure.
+export function formatHtml(report, _paint, _isFull, lang) {
+    const t = lang === undefined ? translator(environmentLanguage(), environmentLocale()) : translator(lang);
+    const origin = singleOrigin(report.pages.map((facts) => facts.url.href));
+    const title = origin || t._("spiderlint report");
+    return page(t, title, `<main>${reportBody(report, t, title, origin)}</main>`);
+}