spiderlint 0.0.0 → 0.143.0

package/dist/facts/transport.js

@@ -0,0 +1,200 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+import { X509Certificate } from "node:crypto";
+import { log } from "../logger.js";
+const DAY = 86_400_000;
+// OpenSSL curve names to the NIST ones a certificate policy speaks.
+const CURVES = { prime256v1: "P-256", secp384r1: "P-384", secp521r1: "P-521" };
+const REDACTED = "[redacted]";
+const SECRET = new Set(["authorization", "proxy-authorization", "cookie"]);
+// got's phase names to the facts document's.
+const PHASES = { wait: "wait", dns: "dns", tcp: "tcp", tls: "tls", request: "request", firstByte: "ttfb", download: "download", total: "total" };
+// Measured phases in milliseconds; a phase the connection skipped stays absent.
+export function timingFacts(transport) {
+    const timing = {};
+    const phases = Object.entries(transport.timings?.phases ?? {});
+    for (const [phase, value] of phases) {
+        const name = PHASES[phase];
+        if (name && value !== undefined)
+            timing[name] = value;
+    }
+    return timing;
+}
+// A got `beforeRequest` hook wrapping the request function got-scraping chose, so each 103 of the last hop lands in `hints`.
+export function earlyHintsHook(url, hints) {
+    const listen = (request) => request.on("information", (info) => {
+        const link = info.headers?.link;
+        log.debug({ url, status: info.statusCode, link }, "informational response received");
+        if (info.statusCode === 103)
+            hints.push({ ...(link && { link: [link].flat().join(", ") }) });
+    });
+    return (options) => {
+        hints.length = 0;
+        const inner = options.getRequestFunction();
+        options.request = (target, native, callback) => {
+            const made = inner(target, native, callback);
+            if (made instanceof Promise)
+                void made.then(listen);
+            else
+                listen(made);
+            return made;
+        };
+    };
+}
+// Seconds a cookie lives: `Max-Age` first, else `Expires` against `now`, undefined for a session cookie (RFC 6265 §5.3).
+function lifetime(flags, now) {
+    const maxAge = Number(flags.get("max-age") || NaN);
+    if (Number.isSafeInteger(maxAge))
+        return maxAge;
+    const expires = Date.parse(flags.get("expires") ?? "");
+    return Number.isNaN(expires) ? undefined : Math.round((expires - now) / 1000);
+}
+// Name and flags of each Set-Cookie; values never leave this function.
+export function cookieFacts(setCookie, date) {
+    const now = Date.parse(String(date)) || Date.now();
+    const lines = setCookie === undefined ? [] : [setCookie].flat();
+    return lines.map((line) => {
+        const [pair = "", ...attributes] = line.split(";").map((part) => part.trim());
+        const flags = new Map(attributes.map((attribute) => {
+            const [key = "", value] = attribute.split("=", 2);
+            return [key.toLowerCase(), value?.trim()];
+        }));
+        const sameSite = flags.get("samesite");
+        const path = flags.get("path");
+        const domain = flags.get("domain");
+        const maxAge = lifetime(flags, now);
+        return { name: pair.split("=", 1)[0] ?? "", secure: flags.has("secure"), "http-only": flags.has("httponly"), ...(sameSite && { "same-site": sameSite }), ...(path !== undefined && { path }), ...(domain !== undefined && { domain }), ...(maxAge !== undefined && { "max-age": maxAge }) };
+    });
+}
+// Cache-status headers a CDN sets, each to a pattern its hit value matches.
+const CACHE_HITS = [
+    ["cf-cache-status", /^(?:hit|stale|revalidated|updating)$/i],
+    ["x-cache", /\bhit\b/i],
+    ["x-vercel-cache", /^(?:hit|stale|prerender)$/i],
+    ["cdn-cache", /^hit$/i],
+    ["cache-status", /;\s*hit\b/i],
+];
+// Seconds the response `Date`, taken mid-second, runs ahead of our clock at the midpoint of `sent` and `firstByte`, or undefined when absent, unparsable or served from a cache.
+export function dateSkew(url, headers, sent, firstByte) {
+    const date = Date.parse(String([headers.date].flat()[0] ?? ""));
+    const age = Number([headers.age].flat()[0] ?? 0);
+    const hit = CACHE_HITS.find(([name, pattern]) => pattern.test(String([headers[name]].flat()[0] ?? "")))?.[0];
+    const isCached = age > 0 || hit !== undefined;
+    log.debug({ url, date: headers.date, age, hit, sent, firstByte }, "response date read");
+    const isMeasured = sent !== undefined && firstByte !== undefined && !isCached && !Number.isNaN(date);
+    return isMeasured ? Math.round((date + 500 - (sent + firstByte) / 2) / 1000) : undefined;
+}
+// One redirect hop to `url`, from the status and raw headers of the response that sent it there.
+export function redirectHop(url, status, raw) {
+    const headers = redactHeaders(raw);
+    const by = [headers["x-redirect-by"] ?? headers["redirect-by"]].flat()[0];
+    log.debug({ url, status, by }, "redirect hop recorded");
+    return { url, status, headers, ...(by && { by }) };
+}
+// A got `beforeRedirect` hook appending each hop the request follows to `hops`.
+export function redirectHook(hops) {
+    return (options, response) => {
+        hops.push(redirectHop(String(options.url), response.statusCode, response.headers));
+    };
+}
+// Response headers with credentials and cookie values replaced, and HTTP/2 pseudo-headers dropped, before anything is stored or reported.
+export function redactHeaders(headers) {
+    const out = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (value === undefined || name.startsWith(":"))
+            continue;
+        if (SECRET.has(name))
+            out[name] = REDACTED;
+        else if (name === "set-cookie")
+            out[name] = [value].flat().map((line) => line.replace(/^([^=;]*)=[^;]*/, (_pair, name) => `${name}=${REDACTED}`));
+        else
+            out[name] = value;
+    }
+    return out;
+}
+// `DNS:a, IP Address:b` to `[a, b]`.
+function subjectAltNames(raw) {
+    return (raw ?? "")
+        .split(",")
+        .map((entry) => entry.trim().replace(/^[^:]+:/, ""))
+        .filter((entry) => entry.length > 0);
+}
+function isoDate(raw) {
+    const time = raw ? Date.parse(raw) : NaN;
+    return Number.isNaN(time) ? undefined : new Date(time).toISOString();
+}
+// The leaf's public key as type, size and curve; absent when the certificate does not parse.
+function keyFacts(raw) {
+    if (!raw?.length)
+        return undefined;
+    try {
+        const key = new X509Certificate(raw).publicKey;
+        const { modulusLength, namedCurve } = key.asymmetricKeyDetails ?? {};
+        const type = key.asymmetricKeyType === "ec" ? "EC" : key.asymmetricKeyType?.startsWith("rsa") ? "RSA" : key.asymmetricKeyType === "ed25519" ? "Ed25519" : String(key.asymmetricKeyType);
+        return { type, ...(modulusLength && { bits: modulusLength }), ...(namedCurve && { curve: CURVES[namedCurve] ?? namedCurve }) };
+    }
+    catch (error) {
+        log.debug({ error: String(error) }, "peer certificate key unreadable");
+        return undefined;
+    }
+}
+// Signature algorithms from the leaf up to, not including, a self-signed root.
+function signatureFacts(leaf) {
+    const algorithms = [];
+    try {
+        for (let cert = leaf; cert?.raw?.length && algorithms.length < 10; cert = cert.issuerCertificate) {
+            const x509 = new X509Certificate(cert.raw);
+            if (cert !== leaf && x509.checkIssued(x509))
+                break;
+            algorithms.push(x509.signatureAlgorithm ?? "unknown");
+            if (cert.issuerCertificate === cert)
+                break;
+        }
+    }
+    catch (error) {
+        log.debug({ error: String(error), read: algorithms.length }, "peer certificate chain unreadable");
+    }
+    return algorithms;
+}
+// This connection's TLS observation; absent on a plain-text socket.
+export function tlsFacts(socket, now = Date.now()) {
+    if (typeof socket?.getPeerCertificate !== "function")
+        return undefined;
+    const cert = socket.getPeerCertificate(true);
+    const key = keyFacts(cert.raw);
+    const notAfter = isoDate(cert.valid_to);
+    const error = socket.authorizationError;
+    return {
+        ...(socket.getProtocol() && { protocol: socket.getProtocol() }),
+        ...(socket.getCipher()?.name && { cipher: socket.getCipher().name }),
+        ...(socket.alpnProtocol && { alpn: socket.alpnProtocol }),
+        authorized: socket.authorized,
+        ...(error && { error: String(error) }),
+        cert: {
+            ...(cert.subject?.CN && { subject: String(cert.subject.CN) }),
+            ...((cert.issuer?.O ?? cert.issuer?.CN) && { issuer: String(cert.issuer.O ?? cert.issuer.CN) }),
+            ...(isoDate(cert.valid_from) && { "not-before": isoDate(cert.valid_from) }),
+            ...(notAfter && { "not-after": notAfter, "days-left": Math.floor((Date.parse(notAfter) - now) / DAY) }),
+            san: subjectAltNames(cert.subjectaltname),
+            ...(cert.fingerprint256 && { fingerprint256: cert.fingerprint256 }),
+            ...(key && { key }),
+            ...(cert.raw?.length && { signatures: signatureFacts(cert) }),
+        },
+    };
+}
+// Raises to HTTP/3 a page a cold TCP connection carried while it advertises h3 for its own authority on an origin QUIC already served.
+export function servedVersions(pages) {
+    const quic = new Set(pages.filter((page) => page.http.version === "3.0").map((page) => page.url.origin));
+    for (const page of pages) {
+        if (page.http.version === undefined || page.http.version === "3.0" || !quic.has(page.url.origin))
+            continue;
+        const { hostname, port } = new URL(page.url.href);
+        const own = new Set([`:${port || "443"}`, `${hostname}:${port || "443"}`]);
+        const offers = page.http.parsed?.["alt-svc"]?.value;
+        const isAdvertised = Array.isArray(offers) && offers.some((offer) => offer.protocol === "h3" && own.has(offer.authority ?? ""));
+        log.debug({ url: page.url.href, observed: page.http.version, isAdvertised }, "http version of a page carried over tcp");
+        if (isAdvertised)
+            page.http.version = "3.0";
+    }
+}

package/dist/facts/types.js

@@ -0,0 +1,4 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+export {};

package/dist/facts/vendors.js

@@ -0,0 +1,76 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+import { readFileSync } from "node:fs";
+import picomatch from "picomatch";
+import { parse } from "yaml";
+import { log } from "../logger.js";
+const FILE = new URL("../../vendors/paths.yaml", import.meta.url);
+const PROVIDERS = new URL("../../vendors/dns.yaml", import.meta.url);
+const cache = {};
+// The provider every one of `names` belongs to; none when they span providers, or one serves none of them.
+export function dnsProvider(names) {
+    cache.providers ??= parse(readFileSync(PROVIDERS, "utf8")).map((entry) => ({ ...entry, isMatch: picomatch(entry.match) }));
+    const found = new Set(names.map((name) => cache.providers?.find((entry) => entry.isMatch(name.toLowerCase().replace(/\.$/, "")))));
+    const [entry] = found;
+    log.debug({ names, providers: [...found].map((candidate) => candidate?.provider) }, "dns provider matched");
+    return found.size === 1 ? entry : undefined;
+}
+// The shipped list, read and compiled once.
+export function vendorPaths() {
+    if (cache.paths)
+        return cache.paths;
+    cache.paths = parse(readFileSync(FILE, "utf8")).map((entry) => ({ ...entry, isMatch: picomatch(entry.match, { dot: true }) }));
+    log.debug({ entries: cache.paths.length }, "vendor paths loaded");
+    return cache.paths;
+}
+// The first entry whose glob matches the URL’s path, when it is of `kind`.
+export function vendorPath(href, kind) {
+    if (!URL.canParse(href))
+        return undefined;
+    const entry = vendorPaths().find((candidate) => candidate.isMatch(new URL(href).pathname));
+    return entry?.kind.includes(kind) ? entry : undefined;
+}
+// Each page’s anchors into a vendor path as `html.links.vendor`, and each origin’s detected vendor features as `site.origins.*.vendor`; `isOn` false clears both.
+export function vendorFacts(pages, site, isOn) {
+    const byOrigin = new Map();
+    for (const page of pages) {
+        if (page.html)
+            delete page.html.links.vendor;
+        if (!isOn)
+            continue;
+        const anchors = page.html ? [...page.html.links.internal, ...page.html.links.external] : [];
+        const linked = anchors.flatMap((href) => {
+            const entry = vendorPath(href, "page");
+            return entry ? [{ href, entry }] : [];
+        });
+        const loads = [...(page.resources ?? []).map((resource) => resource.url), ...(page.html?.scripts ?? []).flatMap((script) => script.src ?? [])];
+        const loaded = loads.flatMap((href) => vendorPath(href, "resource") ?? []);
+        if (page.html && linked.length > 0)
+            page.html.links.vendor = Object.fromEntries(linked.map(({ entry, href }) => [href, entry.vendor]));
+        const features = [...linked.map(({ entry }) => entry), ...loaded].flatMap((entry) => entry.feature ?? []);
+        if (features.length > 0)
+            byOrigin.set(page.url.origin, new Set([...(byOrigin.get(page.url.origin) ?? []), ...features]));
+        log.debug({ url: page.url.href, links: linked.length, resources: loaded.length, features }, "vendor paths found");
+    }
+    const origins = Object.values(site.origins ?? {});
+    for (const facts of origins)
+        delete facts.vendor;
+    for (const [origin, features] of byOrigin)
+        site.origins = { ...site.origins, [origin]: { ...site.origins?.[origin], vendor: { features: [...features].toSorted((a, b) => a.localeCompare(b)) } } };
+    log.debug({ isOn, origins: Object.fromEntries([...byOrigin].map(([origin, features]) => [origin, [...features]])) }, "vendor features detected");
+}
+// Site findings about a vendor’s resource carry the vendor, so formatters list them apart from the site’s own.
+export function attributeVendors(findings, isOn) {
+    if (!isOn)
+        return;
+    const attributed = findings
+        .filter((finding) => finding.scope === "site")
+        .flatMap((finding) => {
+        const entry = vendorPath(finding.url, "resource");
+        if (entry)
+            finding.vendor = entry.vendor;
+        return entry ? [finding.rule] : [];
+    });
+    log.debug({ findings: attributed.length, rules: [...new Set(attributed)] }, "vendor findings attributed");
+}

package/dist/fold/index.js

@@ -0,0 +1,94 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+import { log } from "../logger.js";
+import { said } from "../rules/message.js";
+import { cell } from "../rules/run.js";
+import { levelOf, round, scoreOf } from "../rules/score.js";
+const HETEROGENEOUS = 0.2;
+// The guide of the advisory folding raises, which no ruleset carries.
+export const HETEROGENEOUS_GUIDE = { facts: ["group"], fix: "Split the group’s `match` so each template gets its own group, then check with `spiderlint list-groups`." };
+// What a group’s result says: rule, sentence and locations, when every finding in it says the same; else none, and it never merges.
+function signature(findings) {
+    const said = new Set(findings.map((finding) => JSON.stringify([finding.rule, finding.text ?? finding.message, finding.variables ?? {}, finding.locations ?? []])));
+    return said.size === 1 ? said.values().next().value : undefined;
+}
+// The fold of one group’s findings: its samples, their locations and data, the worst score.
+function folded(findings, group, failed, applicable, isSampled) {
+    const samples = [...new Set(findings.map((finding) => finding.url))].slice(0, 3);
+    const first = findings[0];
+    const located = samples.map((url) => [url, findings.filter((finding) => finding.url === url).flatMap((finding) => finding.locations ?? [])]).filter(([, locations]) => locations.length > 0);
+    const { locations: _locations, data: _data, evidence: _evidence, ...shared } = first;
+    const score = round(Math.max(...findings.map((finding) => scoreOf(finding))));
+    const kept = findings.filter((finding) => samples.includes(finding.url));
+    const data = Object.assign({}, ...kept.map((finding) => finding.data ?? {}));
+    const evidence = new Map(kept.flatMap((finding) => finding.evidence ?? []).map((read) => [`${read.bucket}:${read.key}`, read])).values().toArray();
+    return {
+        ...shared,
+        group,
+        severity: levelOf(score),
+        score,
+        scope: "group",
+        occurrences: failed,
+        coverage: Number((failed / applicable).toFixed(2)),
+        samples,
+        url: samples[0],
+        ...(isSampled && { sampled: applicable }),
+        ...(located.length > 0 && { sampleLocations: Object.fromEntries(located) }),
+        ...(Object.keys(data).length > 0 && { data }),
+        ...(evidence.length > 0 && { evidence }),
+    };
+}
+// Groups failing a rule whole with the same result become one site finding naming them; a result one group alone shows stays its own.
+function merged(results) {
+    const [only] = results;
+    if (only && results.length === 1)
+        return only.folded ? [only.folded] : only.findings;
+    const findings = results.flatMap((result) => result.findings).toSorted((a, b) => a.url.localeCompare(b.url));
+    const failed = results.reduce((sum, result) => sum + result.failed, 0);
+    const applicable = results.reduce((sum, result) => sum + result.applicable, 0);
+    const { group: _group, ...shared } = folded(findings, "", failed, applicable, results.some((result) => result.isSampled));
+    return [{ ...shared, scope: "site", groups: results.map((result) => result.group) }];
+}
+// Per (group, rule): one template-level finding once failures saturate the group, and one site finding where several groups fail the same way.
+export function fold(run, options) {
+    const out = run.findings.filter((finding) => finding.scope !== "page");
+    const byCell = new Map();
+    for (const finding of run.findings) {
+        if (finding.scope !== "page")
+            continue;
+        const key = cell(finding.group, finding.rule);
+        byCell.set(key, [...(byCell.get(key) ?? []), finding]);
+    }
+    const saturated = new Map();
+    for (const [key, unordered] of byCell) {
+        const [group, rule] = key.split("\t");
+        const findings = unordered.toSorted((a, b) => a.url.localeCompare(b.url));
+        const failed = new Set(findings.map((finding) => finding.url)).size;
+        const applicable = run.applicable.get(key) ?? failed;
+        const ratio = failed / applicable;
+        const isFolded = options !== false && applicable >= options.min && ratio >= options.threshold;
+        const isSampled = run.sampled?.has(key) === true;
+        const result = options === false || (!isFolded && failed < applicable) ? undefined : signature(findings);
+        log.debug({ group, rule, failed, applicable, ratio: Number(ratio.toFixed(2)), folded: isFolded, isSaturated: result !== undefined }, "fold");
+        if (result !== undefined) {
+            saturated.set(result, [...(saturated.get(result) ?? []), { group, findings, failed, applicable, isSampled, ...(isFolded && { folded: folded(findings, group, failed, applicable, isSampled) }) }]);
+            continue;
+        }
+        if (isFolded) {
+            out.push(folded(findings, group, failed, applicable, isSampled));
+            continue;
+        }
+        out.push(...findings);
+        if (options !== false && applicable >= options.min && ratio > HETEROGENEOUS) {
+            out.push({ rule: "groups/heterogeneous", severity: "info", score: 2, scope: "group", url: findings[0]?.url, group, ...said("{rule} fails on {count} of {total} pages; the group likely spans two templates", { rule, count: failed, total: applicable }) });
+        }
+    }
+    for (const [key, results] of saturated) {
+        if (results.length > 1)
+            log.debug({ key, groups: results.map((result) => result.group), findings: results.reduce((sum, result) => sum + result.findings.length, 0) }, "groups merged into one site finding");
+        out.push(...merged(results));
+    }
+    log.debug({ before: run.findings.length, after: out.length }, "fold done");
+    return out;
+}

package/dist/groups/assign.js

@@ -0,0 +1,45 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+import picomatch from "picomatch";
+import { ConfigError } from "../config/index.js";
+import { log } from "../logger.js";
+// `re:` is a regex, `content-type:` a response type prefix, anything else a picomatch glob.
+function matcher(group, entry) {
+    if (entry.startsWith("re:")) {
+        try {
+            const regex = new RegExp(entry.slice(3));
+            return (facts) => regex.test(facts.url.pathname + facts.url.search);
+        }
+        catch (error) {
+            throw new ConfigError(`group ${group}: ${entry}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (entry.startsWith("content-type:")) {
+        const type = entry.slice("content-type:".length).toLowerCase();
+        return (facts) => String(facts.http.headers["content-type"] ?? "")
+            .toLowerCase()
+            .startsWith(type);
+    }
+    const glob = picomatch(entry);
+    return (facts) => glob(facts.url.pathname + facts.url.search);
+}
+// Ordered as declared; `default` is appended when the config omits it.
+export function compileGroups(groups) {
+    const compiled = Object.entries(groups)
+        .filter(([name]) => name !== "default")
+        .map(([name, config]) => ({ name, matchers: (config.match ?? []).map((entry) => matcher(name, entry)) }));
+    return [...compiled, { name: "default", matchers: [] }];
+}
+// First group with a matching entry wins; `default` catches the rest.
+export function assignGroup(facts, groups) {
+    for (const group of groups) {
+        const matched = group.matchers.findIndex((match) => match(facts));
+        if (matched === -1)
+            continue;
+        log.debug({ url: facts.url.href, group: group.name, matched }, "group assigned");
+        return group.name;
+    }
+    log.debug({ url: facts.url.href, group: "default" }, "group assigned");
+    return "default";
+}

package/dist/groups/sample.js

@@ -0,0 +1,60 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+import { log } from "../logger.js";
+import { assignGroup, compileGroups } from "./assign.js";
+export const SAMPLE_DEFAULT = 3;
+// Slots per (group, expensive extractor), capped by the group’s `sample`; cheap extractors are never counted.
+export class Sampler {
+    #groups;
+    #caps;
+    #taken = new Map();
+    // Extractor IDs each group’s rules read; absent, every extractor serves every group.
+    #wanted;
+    constructor(groups, wanted) {
+        this.#groups = compileGroups(groups);
+        this.#wanted = wanted;
+        this.#caps = new Map(Object.entries(groups).map(([name, group]) => [name, group.sample === "all" ? Infinity : (group.sample ?? SAMPLE_DEFAULT)]));
+    }
+    #key(group, id) {
+        return `${group}\t${id}`;
+    }
+    groupOf(page) {
+        return assignGroup(page, this.#groups);
+    }
+    // The cap of `group`; Infinity for `sample: all`.
+    cap(group) {
+        return this.#caps.get(group) ?? SAMPLE_DEFAULT;
+    }
+    // Counts a page that already carries `id`’s facts.
+    seed(page, id) {
+        const key = this.#key(this.groupOf(page), id);
+        this.#taken.set(key, (this.#taken.get(key) ?? 0) + 1);
+    }
+    // Every cheap extractor `page`’s group reads, and each expensive one while the group has a slot left, which it reserves.
+    take(page, active) {
+        const group = this.groupOf(page);
+        const cap = this.cap(group);
+        const wanted = this.#wanted?.get(group);
+        const read = wanted ? active.filter((extractor) => wanted.has(extractor.id)) : active;
+        log.debug({ url: page.url.href, group, active: active.length, read: read.length }, "group extractors");
+        return read.filter((extractor) => {
+            if (extractor.cost !== "expensive")
+                return true;
+            const key = this.#key(group, extractor.id);
+            const taken = this.#taken.get(key) ?? 0;
+            const isTaken = taken < cap;
+            log.debug({ url: page.url.href, group, extractor: extractor.id, taken, cap, isTaken }, "sampling");
+            if (isTaken)
+                this.#taken.set(key, taken + 1);
+            return isTaken;
+        });
+    }
+    // Frees the slot of each expensive extractor in `chosen` that added no facts.
+    release(page, chosen, added) {
+        const group = this.groupOf(page);
+        const unused = chosen.filter((extractor) => extractor.cost === "expensive" && !added.includes(extractor.id));
+        for (const extractor of unused)
+            this.#taken.set(this.#key(group, extractor.id), (this.#taken.get(this.#key(group, extractor.id)) ?? 1) - 1);
+    }
+}

package/dist/i18n.js

@@ -0,0 +1,92 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+import { readFileSync } from "node:fs";
+import { po } from "gettext-parser";
+import { log } from "./logger.js";
+// Languages with a catalog under `locales/`, English first as the source language.
+export const LANGUAGES = ["en", "es", "uk"];
+const LOCALES = new URL("../locales/", import.meta.url);
+const catalogs = new Map();
+// The catalog of `lang`, read once; a missing or broken file is an empty catalog, so strings stay English.
+function catalog(lang) {
+    const cached = catalogs.get(lang);
+    if (cached)
+        return cached;
+    const entries = new Map();
+    try {
+        const parsed = po.parse(readFileSync(new URL(`${lang}/LC_MESSAGES/messages.po`, LOCALES)));
+        const translations = Object.entries(parsed.translations[""] ?? {});
+        for (const [msgid, entry] of translations)
+            if (msgid && entry.msgstr[0])
+                entries.set(msgid, entry.msgstr[0]);
+        log.debug({ lang, entries: entries.size }, "catalog loaded");
+    }
+    catch (error) {
+        log.warn({ lang, error: String(error) }, `${lang} catalog not loaded, strings stay English:`);
+    }
+    catalogs.set(lang, entries);
+    return entries;
+}
+// The language tags of an `Accept-Language` header or POSIX locale (`uk_UA.UTF-8`) with a positive q-value, best first.
+function ranked(accept) {
+    const parts = (accept ?? "").split(",").map((part) => {
+        const [tag = "", ...parameters] = part.trim().split(";");
+        const q = Number(parameters
+            .map((parameter) => parameter.trim())
+            .find((parameter) => parameter.startsWith("q="))
+            ?.slice(2) ?? 1);
+        return { tag: tag.trim(), q: Number.isFinite(q) ? q : 0 };
+    });
+    return parts
+        .filter((entry) => entry.q > 0 && entry.tag !== "")
+        .toSorted((a, b) => b.q - a.q)
+        .map((entry) => entry.tag);
+}
+// The best language `accept` names that has a catalog, by q-value; English when none has.
+export function negotiate(accept) {
+    const lang = ranked(accept)
+        .map((tag) => tag.toLowerCase().split(/[-_.@]/, 1)[0] ?? "")
+        .find((tag) => LANGUAGES.includes(tag)) ?? "en";
+    log.debug({ accept, lang }, "language negotiated");
+    return lang;
+}
+// The first tag `accept` names that `Intl` can format, as a BCP 47 locale (`de-DE`); undefined when none.
+export function readerLocale(accept) {
+    for (const tag of ranked(accept)) {
+        const bare = tag.replace(/[.@].*$/, "").replaceAll("_", "-");
+        if (["*", "c", "posix"].includes(bare.toLowerCase()))
+            continue;
+        try {
+            const [locale] = Intl.getCanonicalLocales(bare);
+            if (locale && Intl.NumberFormat.supportedLocalesOf(locale).length > 0) {
+                log.debug({ accept, locale }, "reader locale chosen");
+                return locale;
+            }
+        }
+        catch {
+            log.debug({ tag }, "language tag not a locale");
+        }
+    }
+    return undefined;
+}
+// The language the process environment names, as gettext reads it.
+export function environmentLanguage() {
+    return negotiate(process.env.LC_ALL || process.env.LC_MESSAGES || process.env.LANG);
+}
+// The locale the process environment writes numbers in: `LC_NUMERIC`, then `LC_ALL`, then `LANG`.
+export function environmentLocale() {
+    return readerLocale(process.env.LC_NUMERIC || process.env.LC_ALL || process.env.LANG);
+}
+// Strings and text direction in `lang`; numbers, dates and units in `locale`, `lang` unless named.
+export function translator(lang, locale = lang) {
+    const entries = lang === "en" ? new Map() : catalog(lang);
+    const format = (options) => new Intl.NumberFormat(locale, { maximumFractionDigits: 1, ...options });
+    return {
+        lang,
+        locale,
+        dir: new Intl.Locale(lang).getTextInfo().direction,
+        _: (msgid, variables = {}) => (entries.get(msgid) ?? msgid).replaceAll(/\{(\w+)\}/g, (match, key) => (Object.hasOwn(variables, key) ? String(variables[key]) : match)),
+        number: (value, options = {}) => format(options).format(value),
+    };
+}