spiderlint 0.0.0 → 0.143.0

package/dist/plugins/html-validate.js

@@ -0,0 +1,191 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+import { HtmlValidate, StaticConfigLoader } from "html-validate";
+import { a11y, document as wholeDocument, recommended, standard } from "html-validate/presets";
+import { log } from "../logger.js";
+import { messageRule } from "./messages.js";
+import { definePlugin } from "./types.js";
+const UPSTREAM = { recommended, document: wholeDocument, standard, a11y };
+const ID = "htmlvalidate";
+const PREFIX = "html-validate/";
+const BASE = ["recommended", "document"];
+// Judges html-validate’s own configuration, never a page.
+const IGNORED = new Set(["deprecated-rule"]);
+const SOURCE = 120;
+// The tag in `body` around `offset`, cut at SOURCE characters.
+function sourceAt(body, offset) {
+    const start = body.lastIndexOf("<", offset);
+    const end = body.indexOf(">", offset);
+    if (start === -1 || end === -1 || offset - start > SOURCE)
+        return undefined;
+    const tag = body.slice(start, end + 1);
+    return tag.length > SOURCE ? `${tag.slice(0, SOURCE)}…` : tag;
+}
+// Same-origin scripts need no SRI, as `resources/sri` already judges; the HTML standard bars only empty and whitespace ids.
+const RULES = { "require-sri": ["error", { target: "crossorigin" }], "valid-id": ["error", { relaxed: true }] };
+const presetNames = (names) => names.map((name) => `html-validate:${name}`);
+// A rendered DOM is Chromium’s serialisation, so the serialisation-style rules are off for it.
+const validators = {
+    http: new HtmlValidate(new StaticConfigLoader({ extends: presetNames(BASE), rules: RULES })),
+    browser: new HtmlValidate(new StaticConfigLoader({ extends: presetNames([...BASE, "browser"]), rules: RULES })),
+};
+// html-validate’s severity as spiderlint’s: 2 or error, 1 or warn, else off.
+function severityOf(entry) {
+    const level = Array.isArray(entry) ? entry[0] : entry;
+    if (level === "error" || level === 2)
+        return "error";
+    return level === "warn" || level === 1 ? "warning" : "off";
+}
+// The enabled rules of html-validate presets, later presets winning, as spiderlint severities.
+function severities(presets) {
+    const entries = presets.flatMap((name) => Object.entries(UPSTREAM[name].rules ?? {}));
+    const merged = Object.fromEntries(entries.map(([id, entry]) => [id, severityOf(entry)]));
+    return Object.fromEntries(Object.entries(merged).filter(([id, severity]) => severity !== "off" && !IGNORED.has(id)));
+}
+// The first line of each html-validate rule description; a rule with none without an element context is exempt.
+export const exempt = new Set();
+const DESCRIPTIONS = new Map();
+const htmlValidateIds = Object.keys(severities(BASE));
+for (const id of htmlValidateIds) {
+    try {
+        const documentation = validators.http.getContextualDocumentationSync({ ruleId: id, context: undefined });
+        const summary = documentation?.description
+            ?.split("\n")
+            .map((line) => line.trim())
+            .find(Boolean);
+        if (summary)
+            DESCRIPTIONS.set(id, summary);
+        else {
+            log.debug({ id }, "html-validate rule has no description");
+            exempt.add(`${PREFIX}${id}`);
+        }
+    }
+    catch {
+        log.debug({ id }, "html-validate rule has no context-free description");
+        exempt.add(`${PREFIX}${id}`);
+    }
+}
+// The page rule of html-validate rule `id`; `fix` is derived from the upstream description when present.
+function rule(id) {
+    return messageRule(ID, PREFIX, id, `https://html-validate.org/rules/${id}.html`, DESCRIPTIONS.get(id));
+}
+// How much each rule matters, inside the error band: broken parsing first,
+// then accessibility, then attributes a browser drops, then serialization style.
+const SCORES = {
+    "no-missing-references": 9.2,
+    "missing-doctype": 9.1,
+    "close-order": 9,
+    "element-permitted-parent": 8.9,
+    "element-required-ancestor": 8.8,
+    "element-permitted-content": 8.7,
+    "no-implicit-close": 8.6,
+    "element-permitted-order": 8.5,
+    "element-permitted-occurrences": 8.4,
+    "element-required-content": 8.3,
+    "element-required-attributes": 8.2,
+    "void-content": 8.1,
+    "no-dup-id": 7.9,
+    "aria-hidden-body": 7.8,
+    "hidden-focusable": 7.7,
+    "no-autoplay": 7.6,
+    "area-alt": 7.5,
+    "multiple-labeled-controls": 7.4,
+    "input-missing-label": 7.3,
+    "empty-heading": 7.2,
+    "valid-autocomplete": 7.2,
+    "no-abstract-role": 7.1,
+    "text-content": 7.1,
+    "heading-level": 7.1,
+    "meta-refresh": 7.1,
+    "unique-landmark": 7,
+    "prefer-native-element": 7,
+    "empty-title": 7,
+    "long-title": 7,
+    "form-dup-name": 7,
+    "map-dup-name": 7,
+    "map-id-name": 7,
+    "wcag/h30": 6.9,
+    "wcag/h37": 6.9,
+    "aria-label-misuse": 6.9,
+    "no-implicit-button-type": 6.9,
+    "no-implicit-input-type": 6.9,
+    "no-redundant-aria-label": 6.9,
+    "no-redundant-for": 6.9,
+    "no-redundant-role": 6.9,
+    "wcag/h32": 6.8,
+    "wcag/h36": 6.8,
+    "wcag/h63": 6.8,
+    "wcag/h67": 6.8,
+    "wcag/h71": 6.8,
+    "autocomplete-password": 6.8,
+    "input-attributes": 6.8,
+    "valid-for": 6.8,
+    "valid-id": 6.8,
+    "attribute-boolean-style": 6.7,
+    "attribute-empty-style": 6.7,
+    "attribute-misuse": 6.7,
+    "attribute-allowed-values": 6.7,
+    "no-dup-attr": 6.7,
+    "no-multiple-main": 6.7,
+    "require-sri": 6.7,
+    "script-element": 6.7,
+    "element-name": 6.7,
+    "close-attr": 6.7,
+    "doctype-html": 6.6,
+    "doctype-style": 6.6,
+    deprecated: 6.6,
+    "no-deprecated-attr": 6.6,
+    "script-type": 6.6,
+    "tel-non-breaking": 6.6,
+    "unrecognized-char-ref": 6.6,
+    "void-style": 6.6,
+    "no-conditional-comment": 6.6,
+    "no-inline-style": 6.6,
+    "no-self-closing": 6.6,
+    "no-raw-characters": 6.6,
+    "attr-case": 6.6,
+    "attr-delimiter": 6.6,
+    "attr-quotes": 6.6,
+    "attr-spacing": 6.6,
+    "element-case": 6.6,
+    "no-trailing-whitespace": 6.6,
+    "no-utf8-bom": 6.6,
+    "no-unused-disable": 6.6,
+    "prefer-button": 6.6,
+    "prefer-tbody": 6.6,
+    "no-dup-class": 6.6,
+};
+// A spiderlint preset from html-validate presets.
+function preset(description, presets) {
+    return { description, rules: Object.fromEntries(Object.entries(severities(presets)).map(([id, severity]) => [`${PREFIX}${id}`, SCORES[id] === undefined ? severity : { severity: severity, score: SCORES[id] }])) };
+}
+// Validates an HTML page’s body; a truncated body would fail on elements the cap cut off, so it is skipped.
+async function extract(page, body) {
+    if (!page.html || page.http.size.truncated) {
+        log.debug({ url: page.url.href, isHtml: page.html !== undefined, truncated: page.http.size.truncated === true }, "html-validate skipped");
+        return;
+    }
+    const mode = page.browser ? "browser" : "http";
+    const report = await validators[mode].validateString(body, page.url.href);
+    const messages = report.results
+        .flatMap((result) => result.messages)
+        .map(({ ruleId, message, severity, line, column, offset, size, selector, context }) => {
+        const source = sourceAt(body, offset);
+        return { rule: ruleId, message, severity, line, column, offset, size, ...(selector && { selector }), ...(source && { source }), ...(context !== undefined && { context: context }) };
+    });
+    log.debug({ url: page.url.href, mode, messages: messages.length }, "html validated");
+    return { messages };
+}
+const rules = Object.fromEntries(Object.keys(severities(BASE)).map((id) => [`${PREFIX}${id}`, rule(id)]));
+export default definePlugin({
+    name: "html-validate",
+    extractors: [{ id: ID, extract }],
+    rules,
+    presets: {
+        "html-validate": preset("Markup validity, accessibility and document structure, checked by html-validate", BASE),
+        "html-validate:standard": preset("Markup that breaks the HTML standard, with no style rules", ["standard"]),
+        "html-validate:a11y": preset("Accessibility defects html-validate can see in the markup", ["a11y"]),
+        "html-validate:document": preset("Defects only a whole document has: doctype, labels, heading levels, SRI", ["document"]),
+    },
+});

package/dist/plugins/htmlhint.js

@@ -0,0 +1,95 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+import { HTMLHint } from "htmlhint/dist/core/core.js";
+import { log } from "../logger.js";
+import { messageRule } from "./messages.js";
+import { definePlugin } from "./types.js";
+const ID = "htmlhint";
+const PREFIX = "htmlhint/";
+const SOURCE = 120;
+// htmlhint’s default ruleset, every rule of which reports an error.
+const DEFAULT = Object.fromEntries(Object.keys(HTMLHint.defaultRuleset).map((id) => [id, "error"]));
+// Rules htmlhint ships off that judge a defect rather than a house style, at the level each reports.
+const EXTRA = {
+    "alt-require": "warning",
+    "attr-no-unnecessary-whitespace": "error",
+    "attr-unsafe-chars": "warning",
+    "attr-value-no-duplication": "error",
+    "attr-whitespace": "error",
+    "button-type-require": "warning",
+    "doctype-html5": "warning",
+    "frame-title-require": "warning",
+    "h1-require": "warning",
+    "html-lang-require": "warning",
+    "id-class-ad-disabled": "warning",
+    "input-requires-label": "warning",
+    "main-require": "warning",
+    "meta-charset-require": "error",
+    "meta-description-require": "error",
+    "meta-viewport-require": "error",
+    "tag-no-obsolete": "error",
+    "tagname-specialchars": "error",
+};
+const RULESET = Object.fromEntries(Object.keys({ ...DEFAULT, ...EXTRA }).map((id) => [id, true]));
+// How much each rule matters, inside its own level’s band; absent keeps the band’s base.
+const SCORES = {
+    "tag-pair": 9,
+    "id-unique": 8.4,
+    "src-not-empty": 8.2,
+    "attr-no-duplication": 7.8,
+    "title-require": 7.6,
+    "spec-char-escape": 7.4,
+    "doctype-first": 7,
+    "tagname-lowercase": 6.8,
+    "attr-lowercase": 6.8,
+    "attr-value-double-quotes": 6.6,
+    "meta-charset-require": 7.8,
+    "meta-viewport-require": 7.6,
+    "meta-description-require": 7.2,
+    "tag-no-obsolete": 7,
+    "tagname-specialchars": 6.8,
+    "attr-value-no-duplication": 6.8,
+    "attr-whitespace": 6.6,
+    "attr-no-unnecessary-whitespace": 6.6,
+    "alt-require": 6.2,
+    "input-requires-label": 6,
+    "h1-require": 5.8,
+    "html-lang-require": 5.6,
+    "main-require": 5.4,
+    "frame-title-require": 4.6,
+    "button-type-require": 4.8,
+    "attr-unsafe-chars": 4.4,
+    "doctype-html5": 4.2,
+    "id-class-ad-disabled": 3.6,
+};
+// htmlhint’s rule descriptions, keyed by ID; `fix` is derived from them where present.
+const DESCRIPTIONS = new Map();
+for (const [id, rule] of Object.entries(HTMLHint.rules))
+    if (rule?.description)
+        DESCRIPTIONS.set(id, rule.description);
+// Lints an HTML page’s body; a truncated body would fail on tags the cap cut off, so it is skipped.
+async function extract(page, body) {
+    if (!page.html || page.http.size.truncated) {
+        log.debug({ url: page.url.href, isHtml: page.html !== undefined, truncated: page.http.size.truncated === true }, "htmlhint skipped");
+        return;
+    }
+    const hints = HTMLHint.verify(body, RULESET);
+    const messages = hints.map(({ rule, type, message, line, col, raw }) => ({ rule: rule.id, type, message, line, column: col, ...(raw && { source: raw.length > SOURCE ? `${raw.slice(0, SOURCE)}…` : raw }) }));
+    log.debug({ url: page.url.href, rules: Object.keys(RULESET).length, messages: messages.length }, "html hinted");
+    return { messages };
+}
+// A spiderlint preset from rule levels, each rule scored by how much it matters.
+function preset(description, levels) {
+    return { description, rules: Object.fromEntries(Object.entries(levels).map(([id, severity]) => [`${PREFIX}${id}`, SCORES[id] === undefined ? severity : { severity, score: SCORES[id] }])) };
+}
+const rules = Object.fromEntries(Object.keys(RULESET).map((id) => [`${PREFIX}${id}`, messageRule(ID, PREFIX, id, `https://htmlhint.com/rules/${id}`, DESCRIPTIONS.get(id))]));
+export default definePlugin({
+    name: "htmlhint",
+    extractors: [{ id: ID, extract }],
+    rules,
+    presets: {
+        htmlhint: preset("Markup defects htmlhint reports by default: unpaired tags, duplicate IDs and attributes, a missing doctype or title", DEFAULT),
+        "htmlhint:extra": preset("Defects htmlhint ships off: missing alt, labels, lang, meta tags, obsolete tags, unsafe attribute characters", EXTRA),
+    },
+});

package/dist/plugins/icons.js

@@ -0,0 +1,302 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+import { load } from "cheerio";
+import sharp from "sharp";
+import { optimize } from "svgo";
+import { reason } from "../crawl/fetch.js";
+import { RobotsDisallowed } from "../crawl/probe.js";
+import { log } from "../logger.js";
+import { mediaType } from "./origin.js";
+import { definePlugin } from "./types.js";
+const ID = "icons";
+const APPLE = "180x180";
+const ICO_SIZES = ["16x16", "32x32"];
+const SVG = "image/svg+xml";
+const MAX_PIXELS = 50_000_000;
+// A fill or stroke paint, as an attribute or a style declaration.
+const PAINT = /\b(?:fill|stroke)\s*[:=]\s*["']?\s*([^"';\s>]+)/gi;
+// Paints that add no colour of their own.
+const UNPAINTED = new Set(["none", "transparent", "currentcolor", "inherit"]);
+// Media types an icon may declare, by the format they name.
+const TYPES = { "image/png": "png", "image/x-icon": "ico", "image/vnd.microsoft.icon": "ico", [SVG]: "svg", "image/jpeg": "jpeg", "image/gif": "gif", "image/webp": "webp", "image/avif": "avif" };
+// The lower-cased tokens of a `rel`, `sizes` or `purpose` value.
+const tokens = (value) => (value ?? "").toLowerCase().split(/\s+/).filter(Boolean);
+// The sizes an ICO directory lists, 0 standing for 256.
+function icoSizes(bytes) {
+    const count = bytes.byteLength >= 6 ? bytes.readUInt16LE(4) : 0;
+    const sizes = [];
+    for (let entry = 0; entry < count && 6 + (entry + 1) * 16 <= bytes.byteLength; entry += 1) {
+        const offset = 6 + entry * 16;
+        sizes.push(`${bytes[offset] || 256}x${bytes[offset + 1] || 256}`);
+    }
+    return sizes;
+}
+// The format, pixel sizes and opacity of an icon body; an unrecognised body has no format.
+async function measure(url, bytes) {
+    if (bytes.subarray(0, 4).equals(Buffer.from([0, 0, 1, 0])))
+        return { format: "ico", sizes: icoSizes(bytes) };
+    const text = bytes.subarray(0, 1024).toString("utf8");
+    if (/<svg[\s>]/i.test(text)) {
+        const svg = bytes.toString("utf8");
+        const colours = new Set(svg
+            .matchAll(PAINT)
+            .map((match) => String(match[1]).toLowerCase())
+            .filter((paint) => !UNPAINTED.has(paint))).size;
+        try {
+            optimize(svg);
+            return { format: "svg", ...(colours > 0 && { colours }) };
+        }
+        catch (error) {
+            log.debug({ url, error: reason(error) }, "SVG icon does not parse");
+            return { format: "svg", xml: false };
+        }
+    }
+    try {
+        const image = sharp(bytes, { limitInputPixels: MAX_PIXELS });
+        const metadata = await image.metadata();
+        const stats = metadata.format === "png" ? await image.stats() : undefined;
+        const opaque = stats?.isOpaque;
+        return { format: metadata.format, sizes: [`${metadata.width}x${metadata.height}`], ...(opaque !== undefined && { opaque }) };
+    }
+    catch (error) {
+        log.debug({ url, error: reason(error) }, "icon is no image");
+        return {};
+    }
+}
+// Every icon URL fetched once per origin, on its own host through the delegated probe.
+function fetcher(origin, context) {
+    const files = new Map();
+    const fetchOne = async (url) => {
+        try {
+            const answer = await (new URL(url).origin === origin ? context.fetch : context.delegated)(url, { redirect: "follow", binary: true });
+            const isOk = answer.status >= 200 && answer.status <= 299;
+            const measured = isOk && answer.bytes ? await measure(url, answer.bytes) : {};
+            log.debug({ url, status: answer.status, ...measured }, "icon fetched");
+            return { status: answer.status, type: mediaType(answer), ...measured };
+        }
+        catch (error) {
+            log.debug({ url, error: reason(error) }, "icon unreachable");
+            return { status: 0, error: error instanceof RobotsDisallowed ? "robots.txt disallows it" : reason(error) };
+        }
+    };
+    return (url) => {
+        if (!files.has(url))
+            files.set(url, fetchOne(url));
+        return files.get(url);
+    };
+}
+// The icons the origin’s pages link, one entry per source, URL, sizes and type.
+function linkedIcons(pages) {
+    const found = new Map();
+    for (const page of pages) {
+        const links = page.html?.head.links ?? [];
+        for (const link of links) {
+            const relation = tokens(link.rel);
+            const source = relation.includes("mask-icon") ? "mask-icon" : relation.some((token) => token.startsWith("apple-touch-icon")) ? "apple-touch-icon" : relation.includes("icon") ? "icon" : undefined;
+            if (!source || !link.href)
+                continue;
+            const icon = { url: link.href, source, ...(link.sizes && { sizes: link.sizes }), ...(link.type && { type: link.type.toLowerCase() }), ...(link.color && { color: link.color }) };
+            found.set(JSON.stringify(icon), icon);
+        }
+        const metas = page.html?.metas ?? [];
+        for (const meta of metas)
+            if (meta.name.toLowerCase() === "msapplication-tileimage" && URL.canParse(meta.content, page.url.href))
+                found.set(`tile ${meta.content}`, { url: new URL(meta.content, page.url.href).href, source: "ms-tile" });
+    }
+    return found.values().toArray();
+}
+// The icons each linked manifest lists; a manifest that does not answer or parse lists none, `manifest/parse` reports it.
+async function manifestIcons(pages, origin, context) {
+    const urls = new Set(pages.flatMap((page) => (page.html?.head.links ?? []).filter((link) => tokens(link.rel).includes("manifest") && link.href).map((link) => link.href)));
+    const icons = [];
+    for (const url of urls) {
+        try {
+            const answer = await (new URL(url).origin === origin ? context.fetch : context.delegated)(url, { redirect: "follow" });
+            const listed = JSON.parse(answer.body).icons;
+            const entries = Array.isArray(listed) ? listed : [];
+            for (const icon of entries) {
+                if (typeof icon.src !== "string" || !URL.canParse(icon.src, answer.url))
+                    continue;
+                icons.push({ url: new URL(icon.src, answer.url).href, source: "manifest", ...(typeof icon.sizes === "string" && { sizes: icon.sizes }), ...(typeof icon.type === "string" && { type: icon.type.toLowerCase() }) });
+            }
+            log.debug({ url, icons: icons.length }, "manifest icons read");
+        }
+        catch (error) {
+            log.debug({ url, error: reason(error) }, "manifest icons unreadable");
+        }
+    }
+    return icons;
+}
+// browserconfig.xml’s tile images, and what is wrong with the file; one nobody names and that answers 404 is absent.
+async function browserConfig(pages, origin, context) {
+    const named = pages.flatMap((page) => (page.html?.metas ?? []).filter((meta) => meta.name.toLowerCase() === "msapplication-config" && meta.content.toLowerCase() !== "none" && URL.canParse(meta.content, page.url.href)).map((meta) => new URL(meta.content, page.url.href).href));
+    const url = named[0] ?? `${origin}/browserconfig.xml`;
+    let answer;
+    try {
+        answer = await (new URL(url).origin === origin ? context.fetch : context.delegated)(url, { redirect: "follow" });
+    }
+    catch (error) {
+        log.debug({ url, error: reason(error) }, "browserconfig.xml unreachable");
+        answer = { status: 0, body: "", url };
+    }
+    log.debug({ url, status: answer.status, isNamed: named.length > 0 }, "browserconfig.xml fetched");
+    if (answer.status < 200 || answer.status > 299)
+        return { tiles: [], problems: named.length > 0 ? [`${url} answers ${answer.status || "nothing"}`] : [] };
+    const $ = load(answer.body, { xml: true });
+    if ($("browserconfig msapplication").length === 0)
+        return { tiles: [], problems: [`${url} does not parse as a browserconfig document`] };
+    const tiles = $("browserconfig msapplication tile *[src]")
+        .map((_, element) => String($(element).attr("src")))
+        .get()
+        .filter((named) => URL.canParse(named, answer.url))
+        .map((named) => new URL(named, answer.url).href);
+    return { tiles, problems: [] };
+}
+const isOk = (file) => file !== undefined && file.status >= 200 && file.status <= 299;
+// What is wrong with fetching `url`, when something is: no answer, not 2xx, or no image in the body.
+function unusable(url, file) {
+    if (!file || file.error)
+        return `${url} does not answer${file?.error ? ` (${file.error})` : ""}`;
+    if (!isOk(file))
+        return `${url} answers ${file.status}`;
+    return file.format ? undefined : `${url} is not an image (${file.type || "no type"})`;
+}
+// Favicon: a linked icon or /favicon.ico, each a real image, an ICO carrying 16 and 32 px.
+function faviconProblems(declared, files, root) {
+    const linked = declared.filter((icon) => icon.source === "icon");
+    const rootFile = files[root];
+    if (linked.length === 0 && !isOk(rootFile))
+        return [`no <link rel=icon> and ${root} answers ${rootFile?.status || "nothing"}`];
+    const judged = [...new Set([...linked.map((icon) => icon.url), ...(isOk(rootFile) ? [root] : [])])];
+    return judged.flatMap((url) => {
+        const file = files[url];
+        const problem = unusable(url, file);
+        if (problem)
+            return [problem];
+        const missing = file?.format === "ico" ? ICO_SIZES.filter((size) => !file.sizes?.includes(size)) : [];
+        return missing.length > 0 ? [`${url} holds ${file?.sizes?.join(", ") || "no image"}, not ${ICO_SIZES.join(" and ")}`] : [];
+    });
+}
+// SVG favicon: one linked with its media type, parsing as XML.
+function svgProblems(declared, files) {
+    const svgs = declared.filter((icon) => icon.source === "icon" && (icon.type === SVG || files[icon.url]?.format === "svg" || new URL(icon.url).pathname.endsWith(".svg")));
+    if (svgs.length === 0)
+        return ["no <link rel=icon> names an SVG, which scales and can follow dark mode"];
+    return svgs.flatMap((icon) => {
+        const file = files[icon.url];
+        const problem = unusable(icon.url, file);
+        if (problem)
+            return [problem];
+        if (file?.xml === false)
+            return [`${icon.url} does not parse as XML`];
+        return icon.type === SVG ? [] : [`${icon.url} is linked without type="${SVG}"`];
+    });
+}
+// Apple touch icon: linked, or at /apple-touch-icon.png for pages linking none; an opaque PNG, one of them 180×180.
+function appleProblems(declared, files, root, unlinked) {
+    const linked = declared.filter((icon) => icon.source === "apple-touch-icon");
+    const problems = unlinked > 0 && !isOk(files[root]) ? [`${unlinked} pages link no apple-touch-icon and ${root} answers ${files[root]?.status || "nothing"}`] : [];
+    const judged = [...linked, ...(unlinked > 0 && isOk(files[root]) ? [{ url: root, source: "apple-touch-icon" }] : [])];
+    for (const icon of judged) {
+        const file = files[icon.url];
+        const problem = unusable(icon.url, file);
+        if (problem)
+            problems.push(problem);
+        else if (file?.format !== "png")
+            problems.push(`${icon.url} is ${file?.format}, not PNG`);
+        else if (file.opaque === false)
+            problems.push(`${icon.url} has transparent pixels, which iOS draws black`);
+    }
+    const sizes = judged.map((icon) => ("sizes" in icon && icon.sizes ? tokens(icon.sizes)[0] : files[icon.url]?.sizes?.[0]));
+    if (judged.length > 0 && !sizes.includes(APPLE))
+        problems.push(`no apple-touch-icon is ${APPLE} (got ${sizes.map((size) => size ?? "unknown").join(", ")})`);
+    return problems;
+}
+// Safari pinned tab: a single-colour SVG with a `color`, judged only when linked.
+function maskProblems(declared, files) {
+    return declared
+        .filter((icon) => icon.source === "mask-icon")
+        .flatMap((icon) => {
+        const problem = unusable(icon.url, files[icon.url]);
+        if (problem)
+            return [problem];
+        const colours = files[icon.url]?.colours ?? 0;
+        return [...(files[icon.url]?.format === "svg" ? [] : [`${icon.url} is not an SVG`]), ...(colours > 1 ? [`${icon.url} paints ${colours} colours, not one`] : []), ...(icon.color ? [] : [`${icon.url} is linked without a color`])];
+    });
+}
+// Windows tiles: each `msapplication-TileImage` and browserconfig.xml tile answers with an image.
+function tileProblems(declared, files, config) {
+    const urls = [...new Set([...declared.filter((icon) => icon.source === "ms-tile").map((icon) => icon.url), ...config.tiles])];
+    return [...config.problems, ...urls.flatMap((url) => unusable(url, files[url]) ?? [])];
+}
+// Declared sizes and type against the measured file; an SVG is any size.
+function sizeProblems(declared, files) {
+    const problems = new Set();
+    for (const icon of declared) {
+        const file = files[icon.url];
+        if (!file?.format)
+            continue;
+        const claimed = tokens(icon.sizes).filter((size) => size !== "any");
+        const wrong = file.format === "svg" ? [] : claimed.filter((size) => !file.sizes?.includes(size));
+        if (wrong.length > 0)
+            problems.add(`${icon.url} declares ${claimed.join(" ")} but is ${file.sizes?.join(" ") ?? "unmeasured"}`);
+        const format = icon.type && TYPES[icon.type];
+        if (icon.type && format !== file.format)
+            problems.add(`${icon.url} declares ${icon.type} but is ${file.format}`);
+    }
+    return [...problems];
+}
+// Every icon the origin’s pages, manifest and browserconfig.xml name, fetched once, measured and judged.
+const icons = {
+    id: ID,
+    per: "origin",
+    crawled: true,
+    version: "2",
+    async extract(origin, context) {
+        const pages = context.pages.filter((page) => page.html !== undefined);
+        if (pages.length === 0)
+            return;
+        const get = fetcher(origin, context);
+        const declared = [...linkedIcons(pages), ...(await manifestIcons(pages, origin, context))];
+        const config = await browserConfig(pages, origin, context);
+        const favicon = `${origin}/favicon.ico`;
+        const apple = `${origin}/apple-touch-icon.png`;
+        const unlinked = pages.filter((page) => (page.html?.head.links ?? []).every((link) => tokens(link.rel).every((token) => !token.startsWith("apple-touch-icon")))).length;
+        const urls = [...new Set([...declared.map((icon) => icon.url), ...config.tiles, favicon, apple])];
+        const files = Object.fromEntries(await Promise.all(urls.map(async (url) => [url, await get(url)])));
+        log.debug({ origin, declared: declared.length, files: urls.length, unlinked }, "icons measured");
+        return {
+            declared,
+            files,
+            favicon: faviconProblems(declared, files, favicon),
+            svg: svgProblems(declared, files),
+            "apple-touch": appleProblems(declared, files, apple, unlinked),
+            "mask-icon": maskProblems(declared, files),
+            "ms-tile": tileProblems(declared, files, config),
+            "declared-size": sizeProblems(declared, files),
+        };
+    },
+};
+// A rule over one of the per-origin problem lists.
+function problemRule(check, severity, score, message, documentation, fix) {
+    // eslint-disable-next-line unicorn/no-incorrect-template-string-interpolation -- {got} is the rule message placeholder
+    return { fact: `site.origins.*.${ID}.${check}`, expect: { maxItems: 0 }, message: `${message}: {got}`, severity, score, docs: documentation, fix };
+}
+export default definePlugin({
+    name: ID,
+    sites: [icons],
+    presets: {
+        icons: {
+            description: "Favicons and platform icons fetched and measured: the favicon, SVG, Apple touch, Safari pinned tab and Windows tile icons, and every declared size",
+            rules: {
+                "icons/favicon": problemRule("favicon", "warning", 4.6, "the favicon is missing or broken", "https://developers.google.com/search/docs/appearance/favicon-in-search", "Link an icon with <link rel=icon>, or serve /favicon.ico as an ICO holding 16 and 32 px images."),
+                "icons/svg": problemRule("svg", "hint", 0.6, "no usable SVG favicon", "https://developer.mozilla.org/docs/Web/HTML/Reference/Attributes/rel#icon", `Link a well-formed SVG with <link rel=icon type="${SVG}">.`),
+                "icons/apple-touch": problemRule("apple-touch", "warning", 3.8, "the Apple touch icon is missing or unfit", "https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/ConfiguringWebApplications/ConfiguringWebApplications.html", "Serve an opaque 180×180 PNG at /apple-touch-icon.png, or link one with <link rel=apple-touch-icon>."),
+                "icons/mask-icon": problemRule("mask-icon", "hint", 0.4, "the Safari pinned tab icon is unusable; since Safari 12 an SVG rel=icon serves instead", "https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/pinnedTabs/pinnedTabs.html", "Link a single-colour SVG with a color attribute, or drop rel=mask-icon."),
+                "icons/ms-tile": problemRule("ms-tile", "info", 1.4, "a Windows tile image or browserconfig.xml is broken", "https://learn.microsoft.com/previous-versions/windows/internet-explorer/ie-developer/platform-apis/dn320426(v=vs.85)", "Serve every image msapplication-TileImage and browserconfig.xml name, or remove them."),
+                "icons/declared-size": problemRule("declared-size", "warning", 4.2, "icons are not the size or type they declare", "https://developer.mozilla.org/docs/Web/HTML/Reference/Attributes/sizes", "Make each icon’s sizes and type match the file, or correct the declaration."),
+            },
+        },
+    },
+});