spiderlint 0.0.0 → 0.143.0

package/dist/report/human.js

@@ -0,0 +1,220 @@
+// 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 { environmentLocale } from "../i18n.js";
+import { bytes as sized, isLabelled, label, withUnit } from "../facts/labels.js";
+import { fixFor } from "../rules/fix.js";
+import { cachedReads, valuesAt } from "../rules/message.js";
+import { byImportance, scoreOf } from "../rules/score.js";
+import { plain } from "../color.js";
+import { printable, printableFinding } from "./printable.js";
+import { passing } from "./rating.js";
+const ORDER = { error: 0, warning: 1, info: 2, hint: 3 };
+const TONE = { error: "red", warning: "yellow", info: "blue", hint: "dim" };
+const LIST = 5;
+const DETAIL = " ".repeat(10);
+const NESTED = " ".repeat(12);
+const LABEL = 11;
+const PLURAL = { rule: "rules", error: "errors", warning: "warnings", info: "info", hint: "hints", page: "pages", launch: "launches", fetch: "fetches", request: "requests", "TLS probe": "TLS probes", "cached read": "cached reads" };
+const ORANGE = "#ff8700";
+const GRADE_TONE = { S: "green", A: "green", B: "yellow", C: ORANGE, D: ORANGE, E: "red", F: "red" };
+const MINUS = "\u{2212}";
+// The locale’s digits and decimal mark, groups split by a narrow no-break space as SI writes them.
+function number(value, options = {}) {
+    return new Intl.NumberFormat(environmentLocale(), { maximumFractionDigits: 1, ...options })
+        .formatToParts(value)
+        .map((part) => (part.type === "group" ? "\u{202F}" : part.value))
+        .join("");
+}
+// A count and its noun, plural unless it is exactly one.
+function counted(count, noun) {
+    return `${number(count)} ${count === 1 ? noun : (PLURAL[noun] ?? noun)}`;
+}
+// One summary row: a padded label, then its value.
+function row(label, value) {
+    return `${label.padEnd(LABEL)}${value}`;
+}
+// At most `limit` URLs on the detail line, the rest as a count.
+function list(urls, origin, limit) {
+    const shown = urls
+        .slice(0, limit)
+        .map((url) => relative(url, origin))
+        .join(", ");
+    return urls.length > limit ? `${shown} … and ${urls.length - limit} more` : shown;
+}
+// A URL, then what was measured there, each relative to the origin.
+function shown(finding, url, origin) {
+    return [url, ...valuesAt(finding, url, number)].map((text) => relative(text, origin)).join("  ");
+}
+// At most `limit` URLs one per line with their values, the rest as a count.
+function measured(finding, urls, indent, origin, paint, limit) {
+    const lines = urls.slice(0, limit).map((url) => paint("dim", `${indent}${shown(finding, url, origin)}`));
+    return urls.length > limit ? [...lines, paint("dim", `${indent}… and ${urls.length - limit} more`)] : lines;
+}
+// At most `limit` locations, each on its own line under what it locates, the rest as a count.
+function located(locations, indent, paint, limit) {
+    if (!locations || locations.length === 0)
+        return [];
+    const shown = locations.slice(0, limit).map((location) => paint("dim", `${indent}at ${location}`));
+    return locations.length > limit ? [...shown, paint("dim", `${indent}… and ${locations.length - limit} more`)] : shown;
+}
+// A fold’s samples; pages whose locations all match share one list under the URLs.
+function sampled(finding, origin, paint, limit) {
+    const samples = finding.samples ?? [];
+    const byPage = finding.sampleLocations;
+    const isShared = !finding.data && new Set(samples.map((url) => JSON.stringify(byPage?.[url] ?? []))).size === 1;
+    return isShared ? [paint("dim", `${DETAIL}e.g. ${list(samples, origin, limit)}`), ...located(byPage?.[samples[0]], NESTED, paint, limit)] : samples.flatMap((url) => [paint("dim", `${DETAIL}e.g. ${shown(finding, url, origin)}`), ...located(byPage?.[url], NESTED, paint, limit)]);
+}
+function heading(finding, paint) {
+    return `  ${paint(TONE[finding.severity], `${finding.severity.padEnd(7)} ${scoreOf(finding).toFixed(1)}`)} ${paint("bold", finding.rule)}`;
+}
+function shortMessage(finding, origin) {
+    return origin ? finding.message.replaceAll(`${origin}/`, "/") : finding.message;
+}
+// Page findings sharing severity, score, rule and sentence bundle together, by template when they carry one; folds and aggregates stay alone.
+export function bundle(findings) {
+    const bundles = new Map();
+    for (const [index, finding] of findings.entries()) {
+        const isPlain = finding.occurrences === undefined && !finding.urls;
+        const key = isPlain ? `${finding.severity}\t${scoreOf(finding)}\t${finding.rule}\t${finding.text === undefined ? finding.message : `${finding.text}\t${JSON.stringify(finding.variables ?? {})}`}` : String(index);
+        bundles.set(key, [...(bundles.get(key) ?? []), finding]);
+    }
+    return bundles.values().toArray();
+}
+// A bundle prints its message once, then every page on its own line.
+function bundled(same, origin, paint, limit) {
+    const first = same[0];
+    return [`${heading(first, paint)} — ${same.length} pages: ${shortMessage(first, origin)}`, ...same.flatMap((finding) => [paint("dim", `${DETAIL}${shown(finding, finding.url, origin)}`), ...located(finding.locations, NESTED, paint, limit)])];
+}
+// A fold shows its samples; an aggregate its URL list, and its own URL when that is not one of them.
+function line(finding, origin, paint, limit) {
+    const url = relative(finding.url, origin);
+    const message = shortMessage(finding, origin);
+    const head = heading(finding, paint);
+    if (finding.occurrences !== undefined) {
+        const pages = `${finding.sampled === undefined ? `${finding.occurrences} pages` : `${finding.occurrences} of ${finding.sampled} sampled pages`}${finding.groups ? ` in ${finding.groups.join(", ")}` : ""}`;
+        return [`${head} — ${pages} (${Math.round((finding.coverage ?? 0) * 100)}%): ${message}`, ...sampled(finding, origin, paint, limit)];
+    }
+    if (!finding.urls)
+        return [`${head} ${url}: ${message}`, ...measured(finding, Object.hasOwn(finding.data ?? {}, finding.url) ? [finding.url] : [], DETAIL, origin, paint, limit), ...located(finding.locations, DETAIL, paint, limit)];
+    const subject = finding.urls.includes(finding.url) ? "—" : `${url}:`;
+    const urls = finding.data ? measured(finding, finding.urls, DETAIL, origin, paint, limit) : [paint("dim", `${DETAIL}${list(finding.urls, origin, limit)}`)];
+    return [`${head} ${subject} ${message}`, ...urls, ...located(finding.locations, DETAIL, paint, limit)];
+}
+// The grade and the rulesets it was earned under; a dash when nothing was judged.
+function ratingValue(rating, paint) {
+    return rating ? `${paint(GRADE_TONE[rating.grade], paint("bold", rating.grade))} (${rating.rulesets.join(", ")})` : "– (no checks ran)";
+}
+// A signed change against the last run, green when it fell and red when it grew; nothing when equal or unknown.
+function change(now, before, paint) {
+    return before === undefined || now === before ? "" : ` ${paint(now < before ? "green" : "red", `${now < before ? MINUS : "+"}${number(Math.abs(now - before))}`)}`;
+}
+// The rule’s fix filled for this finding, then its docs, under the finding.
+function explanation(guide, finding, paint) {
+    return [guide?.fix ? `${paint("dim", `${DETAIL}fix  `)}${fixFor(guide.fix, finding)}` : "", guide?.docs ? paint("dim", `${DETAIL}docs ${guide.docs}`) : ""].filter(Boolean);
+}
+// Findings by importance (score times the share of pages touched) then rule then URL, bundled, each followed by its explanation when `guides` is given.
+function listed(findings, origin, paint, limit, total, guides) {
+    findings.sort(byImportance(total));
+    return bundle(findings).flatMap((same) => {
+        const first = same[0];
+        return [...(same.length > 1 ? bundled(same, origin, paint, limit) : line(first, origin, paint, limit)), ...(guides ? explanation(guides[first.rule], first, paint) : [])];
+    });
+}
+// The shared origin once on top, findings grouped by group then rule, site-wide ones next, then each vendor’s, hints last and only counted unless `isHintListed`, the fact statistics with `isStats`, then the totals; `isFull` lists every URL and location, `isExplained` each fix.
+export function formatHuman(report, paint = plain, isFull = false, _lang, isHintListed = false, isExplained = false, isStats = false) {
+    const limit = isFull ? Infinity : LIST;
+    const guides = isExplained ? (report.rules ?? {}) : undefined;
+    const origin = singleOrigin(report.pages.map((page) => page.url.href));
+    const out = origin ? [paint(["bold", "underline"], origin)] : [];
+    const groups = new Map();
+    const vendors = new Map();
+    const findings = report.findings.map((finding) => printableFinding(finding));
+    const hints = findings.filter((finding) => finding.severity === "hint");
+    for (const finding of findings) {
+        if (finding.severity === "hint")
+            continue;
+        const [sections, key] = finding.vendor ? [vendors, finding.vendor] : [groups, finding.scope === "site" ? "site" : finding.group];
+        sections.set(key, [...(sections.get(key) ?? []), finding]);
+    }
+    for (const [group, findings] of groups) {
+        const pages = report.summary.groups[group] ?? 0;
+        out.push(group === "site" ? paint("bold", "site") : `${paint("bold", group)} ${paint("dim", `(${counted(pages, "page")})`)}`, ...listed(findings, origin, paint, limit, report.pages.length, guides));
+    }
+    for (const [vendor, findings] of vendors)
+        out.push(`${paint("bold", vendor)} ${paint("dim", "(vendor)")}`, ...listed(findings, origin, paint, limit, report.pages.length, guides));
+    if (hints.length > 0)
+        out.push(`${paint("bold", "hints")} ${paint("dim", `(${counted(hints.length, "hint")})`)}`, ...(isHintListed ? listed(hints, origin, paint, limit, report.pages.length, guides) : [paint("dim", `${DETAIL}--show-hints lists them`)]));
+    out.push(...cachedRow(findings, paint));
+    if (isFull)
+        out.push("", ...passedRows(report.summary, paint));
+    if (isStats)
+        out.push("", ...statRows(report.summary.stats ?? {}, paint));
+    out.push("", ...totals(report.summary, paint), ...costRows(report.summary.cost).map((line) => paint("dim", line)));
+    return out.join("\n");
+}
+// How many observations behind the findings came from a cache, by bucket, and how to read them again; nothing when none did.
+function cachedRow(findings, paint) {
+    const reads = cachedReads(findings);
+    if (reads.length === 0)
+        return [];
+    const buckets = [...new Set(reads.map((read) => read.bucket))].join(", ");
+    return ["", paint("dim", `${counted(reads.length, "cached read")} behind these findings (${buckets}); --refresh reads them again`)];
+}
+// Every rule that failed nowhere with the pages it covered, under a count; nothing when none ran.
+function passedRows({ checked }, paint) {
+    const rules = passing(checked);
+    return rules.length === 0 ? [] : [paint("bold", `passed ${counted(rules.length, "rule")}`), ...rules.map(([id, rule]) => `  ${paint("green", "✓")} ${id} ${paint("dim", counted(rule.pages, "page"))}`)];
+}
+// Pages, size, time, rules, checks, findings with their change since the last run, and the rating, one row each; findings are counted before folding.
+function totals({ pages, bytes, durationMs, statuses, rules, checks, findings, rating, previous }, paint) {
+    const answers = Object.entries(statuses).map(([status, count]) => `${number(count)} × ${status}`);
+    const shown = Object.keys(ORDER).filter((severity) => severity !== "hint" || (findings.hint ?? 0) > 0);
+    const severities = shown.map((severity) => `${(findings[severity] ?? 0) > 0 ? paint(TONE[severity], counted(findings[severity], severity)) : counted(0, severity)}${change(findings[severity], previous?.findings[severity], paint)}`);
+    const since = previous ? paint("dim", ` since ${new Date(previous.started).toLocaleString(environmentLocale(), { dateStyle: "short", timeStyle: "short" })}`) : "";
+    return [
+        row("pages", answers.length > 0 ? `${number(pages)} (${answers.join(", ")})` : number(pages)),
+        row("size", sized(bytes, number)),
+        row("time", number(durationMs / 1000, { style: "unit", unit: "second" })),
+        row("rules", number(rules)),
+        row("checks", `${number(checks.passed)} of ${number(checks.total)} passed`),
+        row("findings", `${number(findings.total)}${change(findings.total, previous?.findings.total, paint)} (${severities.join(", ")})${since}`),
+        row("rating", ratingValue(rating, paint)),
+    ];
+}
+// A measured value in the unit `path` carries, if any.
+export function measure(value, path = "") {
+    return withUnit(path, value, number);
+}
+// Rows as aligned columns, the first padded at its end and the rest at their start, the header bold.
+export function aligned(rows, paint) {
+    const widths = rows[0].map((_, column) => Math.max(...rows.map((row) => (row[column] ?? "").length)));
+    const lines = rows.map((row) => row
+        .map((cell, column) => (column === 0 ? cell.padEnd(widths[0]) : cell.padStart(widths[column])))
+        .join("  ")
+        .trimEnd());
+    return [paint("bold", lines[0]), ...lines.slice(1)];
+}
+// One aligned row per labelled numeric fact by its label: pages, then min, median, p95, max and total in its unit, under a header.
+export function statRows(stats, paint) {
+    const cells = Object.entries(stats)
+        .filter(([path]) => isLabelled(path))
+        .map(([path, stat]) => [printable(label(path) ?? path), measure(stat.count), ...[stat.min, stat.median, stat.p95, stat.max, stat.total].map((value) => (value === undefined ? "–" : measure(value, path)))]);
+    return cells.length === 0 ? [row("stats", "none")] : aligned([["stats", "pages", "min", "median", "p95", "max", "total"], ...cells], paint);
+}
+// Browsers launched and pages they rendered, plain HTTP fetches, resource requests, extractor runs and cache hits, one row each.
+function costRows({ browser, http, resources, extractors, extractorsCached = {} }) {
+    const runs = Object.entries(extractors).map(([id, count]) => `${id} ×${number(count)}`);
+    const hits = Object.entries(extractorsCached).map(([id, count]) => `${id} ×${number(count)}`);
+    return [
+        browser ? row("browser", `${browser.name}, ${counted(browser.pages, "page")} in ${counted(browser.launches, "launch")}${browser.tlsProbes > 0 ? `, ${counted(browser.tlsProbes, "TLS probe")}` : ""}`) : "",
+        http ? row("http", `${counted(http.pages, "fetch")}${http.revalidated > 0 ? ` (${number(http.revalidated)} revalidated)` : ""}`) : "",
+        browser || http ? "" : row("fetch", "none"),
+        resources
+            ? row("resources", `${counted(resources.requests, "request")}${resources.cached > 0 ? ` (${number(resources.cached)} more from cache${resources.failuresCached ? `, ${counted(resources.failuresCached, "failure")}` : ""})` : ""}${resources.logged > 0 ? ` (${number(resources.logged)} more from the browser)` : ""}`)
+            : "",
+        runs.length > 0 ? row("extractors", runs.join(", ")) : "",
+        hits.length > 0 ? row("cached", hits.join(", ")) : "",
+    ].filter(Boolean);
+}

package/dist/report/index.js

@@ -0,0 +1,16 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+import { definePlugin } from "../plugins/types.js";
+import { formatAgent } from "./agent.js";
+import { formatCheckstyle } from "./checkstyle.js";
+import { formatCsv } from "./csv.js";
+import { formatHtml } from "./html.js";
+import { formatHuman } from "./human.js";
+import { formatJson } from "./json.js";
+import { formatSarif } from "./sarif.js";
+// The bundled report formats.
+export default definePlugin({
+    name: "report",
+    formatters: { human: formatHuman, json: formatJson, sarif: formatSarif, checkstyle: formatCheckstyle, csv: formatCsv, html: formatHtml, agent: formatAgent },
+});

package/dist/report/json.js

@@ -0,0 +1,8 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+import { scoreOf } from "../rules/score.js";
+// Summary, findings and their rules’ docs; facts stay behind `spiderlint show-facts <url>`.
+export function formatJson(report) {
+    return JSON.stringify({ summary: report.summary, findings: report.findings.map((finding) => ({ ...finding, score: scoreOf(finding) })), ...(report.rules && { rules: report.rules }) }, undefined, 2);
+}

package/dist/report/printable.js

@@ -0,0 +1,29 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+// C0 and C1 controls, newline and tab included, and the bidi overrides and isolates.
+const UNPRINTABLE = /[\p{Cc}\u{202A}-\u{202E}\u{2066}-\u{2069}]/gu;
+// Site text with every control shown as a `\u{…}` escape, so it can neither drive a terminal nor forge a line.
+export function printable(text) {
+    return text.replaceAll(UNPRINTABLE, (char) => String.raw `\u{${char.codePointAt(0).toString(16)}}`);
+}
+// Every string datum of a record printable.
+function datums(data) {
+    return Object.fromEntries(Object.entries(data).map(([key, datum]) => [key, typeof datum === "string" ? printable(datum) : datum]));
+}
+// A finding whose site-derived strings are all printable.
+export function printableFinding(finding) {
+    const lines = (values) => values?.map((value) => printable(value));
+    return {
+        ...finding,
+        url: printable(finding.url),
+        message: printable(finding.message),
+        ...(finding.locations && { locations: lines(finding.locations) }),
+        ...(finding.urls && { urls: lines(finding.urls) }),
+        ...(finding.samples && { samples: lines(finding.samples) }),
+        ...(finding.variables && { variables: datums(finding.variables) }),
+        ...(finding.data && { data: Object.fromEntries(Object.entries(finding.data).map(([url, data]) => [printable(url), datums(data)])) }),
+        ...(finding.evidence && { evidence: finding.evidence.map((read) => ({ ...read, key: printable(read.key) })) }),
+        ...(finding.sampleLocations && { sampleLocations: Object.fromEntries(Object.entries(finding.sampleLocations).map(([url, found]) => [printable(url), lines(found)])) }),
+    };
+}

package/dist/report/rating.js

@@ -0,0 +1,26 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+// The rules that ran and failed nowhere, by ID.
+export function passing(checked = {}) {
+    return Object.entries(checked)
+        .filter(([, rule]) => rule.failed === 0)
+        .toSorted(([a], [b]) => a.localeCompare(b));
+}
+// Lowest score in tenths each grade still reaches, best first; F takes the rest.
+const FLOORS = [
+    [9, "A"],
+    [7, "B"],
+    [6, "C"],
+    [4, "D"],
+    [2, "E"],
+];
+// Grade by share passed, a failed check counting for its cost, 1 at a warning and more as its score rises; S needs no failed check, an error caps at B, nothing judged means no grade.
+export function rate(checks, rulesets) {
+    if (checks.total === 0)
+        return undefined;
+    const floors = checks.errored > 0 ? FLOORS.slice(1) : FLOORS;
+    const share = Math.max(0, checks.total - (checks.cost ?? checks.failed)) / checks.total;
+    const grade = checks.failed === 0 ? "S" : (floors.find(([tenths]) => share * 10 >= tenths)?.[1] ?? "F");
+    return { grade, score: Number(share.toFixed(4)), rulesets };
+}

package/dist/report/sarif.js

@@ -0,0 +1,100 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+import { VERSION } from "../agent.js";
+import { fixFor } from "../rules/fix.js";
+import { inEnglish, valuesAt, writtenAll } from "../rules/message.js";
+import { scoreOf } from "../rules/score.js";
+const SCHEMA = "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json";
+const SECURITY = /^(tls|cookies|dns|mail|sshfp)\/|^http\/(hsts|csp|content-type-options|referrer-policy|frame-options|server-disclosure|permissions-policy|coop|coep|corp|reporting|no-x-xss|deprecated-header)/;
+const LEVEL = { error: "error", warning: "warning", info: "note", hint: "none" };
+function location(uri) {
+    return { physicalLocation: { artifactLocation: { uri } } };
+}
+// A location carrying the values measured there as its message, when there are any.
+function measured(finding, uri) {
+    const values = valuesAt(finding, uri, inEnglish);
+    return { ...location(uri), ...(values.length > 0 && { message: { text: values.join(", ") } }) };
+}
+// Samples beyond the primary location, for a folded or site-wide finding.
+function relatedLocations(finding) {
+    const extra = (finding.samples ?? finding.urls ?? []).filter((url) => url !== finding.url);
+    return extra.length === 0 ? undefined : extra.map((uri, id) => ({ id, ...measured(finding, uri) }));
+}
+// A template’s placeholders as SARIF’s positional `{0}`, in the order its variables are named.
+function positional(text, names) {
+    return text.replaceAll(/\{(\w+)\}/g, (match, name) => (names.includes(name) ? `{${names.indexOf(name)}}` : match));
+}
+// The message: the English text, and for a template its message string ID and arguments (SARIF 2.1.0 §3.11.7).
+function message(finding, ids) {
+    const id = finding.text === undefined ? undefined : ids.get(`${finding.rule}\t${finding.text}`);
+    const variables = writtenAll(finding.variables, inEnglish);
+    return { text: finding.message, ...(id && { id, arguments: Object.values(variables) }) };
+}
+function toResult(finding, ids) {
+    const related = relatedLocations(finding);
+    return {
+        ruleId: finding.rule,
+        level: LEVEL[finding.severity],
+        rank: scoreOf(finding) * 10,
+        message: message(finding, ids),
+        locations: [measured(finding, finding.url)],
+        ...(finding.occurrences !== undefined && { occurrenceCount: finding.occurrences }),
+        ...(related && { relatedLocations: related }),
+        ...(finding.evidence && { properties: { evidence: finding.evidence } }),
+    };
+}
+// One message string ID per distinct template, numbered within its rule, and the rule’s strings by ID.
+function messageStrings(findings) {
+    const ids = new Map();
+    const byRule = new Map();
+    for (const finding of findings) {
+        if (finding.text === undefined || ids.has(`${finding.rule}\t${finding.text}`))
+            continue;
+        const strings = byRule.get(finding.rule) ?? {};
+        const id = `m${Object.keys(strings).length}`;
+        strings[id] = { text: positional(finding.text, Object.keys(finding.variables ?? {})) };
+        ids.set(`${finding.rule}\t${finding.text}`, id);
+        byRule.set(finding.rule, strings);
+    }
+    return { ids, byRule };
+}
+// The rule’s generic fix and docs link, which code scanning shows beside each alert.
+function help({ fix, docs }) {
+    const text = [fix && fixFor(fix), docs].filter(Boolean);
+    const markdown = [fix && fixFor(fix), docs && `[Documentation](${docs})`].filter(Boolean);
+    return text.length === 0 ? {} : { help: { text: text.join("\n\n"), markdown: markdown.join("\n\n") }, ...(docs && { helpUri: docs }) };
+}
+// Code scanning reads the worst score of a security rule’s findings as its CVSS-style severity, "0.0" to "10.0".
+function security(id, findings) {
+    if (!SECURITY.test(id))
+        return {};
+    const worst = Math.max(...findings.filter((finding) => finding.rule === id).map((finding) => scoreOf(finding)));
+    return { properties: { "security-severity": worst.toFixed(1), tags: ["security"] } };
+}
+// One driver rule per distinct rule ID seen in the findings, with its help when the report carries its guide.
+function toRules(findings, strings, guides = {}) {
+    const ids = [...new Set(findings.map((finding) => finding.rule))].toSorted((a, b) => a.localeCompare(b));
+    return ids.map((id) => ({ id, shortDescription: { text: id }, ...(strings.has(id) && { messageStrings: strings.get(id) }), ...(guides[id] && help(guides[id])), ...security(id, findings) }));
+}
+// The run's totals as a SARIF invocation; the summary rides in its property bag.
+function toInvocation({ started, ...summary }) {
+    const endTimeUtc = new Date(Date.parse(started) + summary.durationMs).toISOString();
+    return { executionSuccessful: true, startTimeUtc: started, endTimeUtc, properties: summary };
+}
+// SARIF 2.1.0: one run, one tool. Folded findings carry occurrenceCount + relatedLocations (AGENTS.md ## Folding).
+export function formatSarif(report) {
+    const { ids, byRule } = messageStrings(report.findings);
+    const sarif = {
+        $schema: SCHEMA,
+        version: "2.1.0",
+        runs: [
+            {
+                tool: { driver: { name: "spiderlint", version: VERSION, rules: toRules(report.findings, byRule, report.rules) } },
+                invocations: [toInvocation(report.summary)],
+                results: report.findings.map((finding) => toResult(finding, ids)),
+            },
+        ],
+    };
+    return JSON.stringify(sarif, undefined, 2);
+}

package/dist/report/stats.js

@@ -0,0 +1,46 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+import { byRank, flatten } from "../facts/flatten.js";
+import { log } from "../logger.js";
+// Numbers that name something rather than measure it.
+const NOMINAL = new Set(["http.status", "co2.version"]);
+// Numbers a total of means nothing: a header’s configured limit, a position in the graph.
+const UNSUMMED = new Set(["crawl.depth", "graph.depth", "graph.rank"]);
+// Whether `path` measures something a total of is meaningful for.
+function isSummable(path) {
+    return !UNSUMMED.has(path) && !path.endsWith(".max-age");
+}
+// Four decimals, enough for grams of CO2e and fractions of a millisecond.
+function rounded(value) {
+    return Math.round(value * 10_000) / 10_000;
+}
+// The middle of an ascending list, the mean of the two middles when even.
+export function median(sorted) {
+    const middle = sorted.length / 2;
+    return sorted.length % 2 === 1 ? sorted[Math.floor(middle)] : (sorted[middle - 1] + sorted[middle]) / 2;
+}
+// The nearest-rank `q` quantile of an ascending list.
+function quantile(sorted, q) {
+    return sorted[Math.max(0, Math.ceil(q * sorted.length) - 1)];
+}
+// Count, min, median, p95, max and total of every numeric page fact, CO2, bytes, requests and timings first.
+export function factStats(pages) {
+    const values = new Map();
+    for (const page of pages) {
+        const leaves = Object.entries(flatten(page));
+        for (const [path, value] of leaves)
+            if (typeof value === "number" && Number.isFinite(value) && !NOMINAL.has(path))
+                values
+                    .set(path, values.get(path) ?? [])
+                    .get(path)
+                    ?.push(value);
+    }
+    const paths = values.keys().toArray().toSorted(byRank);
+    log.debug({ pages: pages.length, facts: paths.length }, "fact statistics computed");
+    return Object.fromEntries(paths.map((path) => {
+        const sorted = values.get(path).toSorted((a, b) => a - b);
+        const total = sorted.reduce((sum, value) => sum + value, 0);
+        return [path, { count: sorted.length, min: sorted[0], median: rounded(median(sorted)), p95: quantile(sorted, 0.95), max: sorted.at(-1), ...(isSummable(path) && { total: rounded(total) }) }];
+    }));
+}