spiderlint 0.0.0 → 0.143.0

package/dist/plugins/keyboard.js

@@ -0,0 +1,194 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+import { log } from "../logger.js";
+import { pageRule } from "../rules/builtin.js";
+import { said } from "../rules/message.js";
+import { definePlugin } from "./types.js";
+import { DESCRIBE, visit, withPage } from "./visit.js";
+const ID = "keyboard";
+// Tab presses allowed per candidate, beyond the count, and in all.
+const PER_CANDIDATE = 2;
+const SLACK = 10;
+const MAX_PRESSES = 300;
+// Presses focus may rest on one element, as inside a frame or a media player, before it counts as stuck.
+const STUCK = 20;
+const CANDIDATES = `globalThis[Symbol.for("spiderlint.keyboard")]`;
+// A page script defining `look(element)`: the focus-relevant styles of the element, its pseudo-elements, parent and first ten children, outline only when drawn.
+const LOOK = `const PROPERTIES = ["outline-style", "outline-width", "outline-color", "box-shadow", "border-color", "border-width", "background-color", "color", "text-decoration-line"];
+    const read = (node, pseudo) => { const style = getComputedStyle(node, pseudo); return PROPERTIES.filter((name) => style.outlineStyle !== "none" || !name.startsWith("outline-")).map((name) => style.getPropertyValue(name)).join("|"); };
+    const look = (element) => [read(element, null), read(element, "::before"), read(element, "::after"), ...(element.parentElement ? [read(element.parentElement, null)] : []), ...[...element.children].slice(0, 10).map((child) => read(child, null))].join(" / ");`;
+// Lists what a keyboard user must reach and stills transitions, so a focus style reads settled; answers the count.
+const MARK = `(() => {
+    const selector = 'a[href], area[href], button, input:not([type="hidden"]), select, textarea, summary, iframe, [contenteditable=""], [contenteditable="true"], audio[controls], video[controls], [tabindex]';
+    const candidates = [...document.querySelectorAll(selector)].filter((element) => !(Number(element.getAttribute("tabindex")) < 0) && !element.matches(":disabled") && !element.closest("[inert]") && element.checkVisibility({ visibilityProperty: true }));
+    ${CANDIDATES} = candidates;
+    const style = document.createElement("style");
+    style.textContent = "*, *::before, *::after { transition: none !important; }";
+    document.head.append(style);
+    return candidates.length;
+})()`;
+// The focused element: where it sits in the candidates, whether focus shows, what covers it, and where a same-page link leads.
+const INSPECT = `(() => {
+    ${DESCRIBE}
+    let element = document.activeElement;
+    while (element?.shadowRoot?.activeElement) element = element.shadowRoot.activeElement;
+    if (!element || element === document.body || element === document.documentElement) return null;
+    const isAbove = (ancestor, node) => { for (let at = node; at; at = at.parentNode ?? at.host) if (at === ancestor) return true; return false; };
+    ${LOOK}
+    const focused = look(element);
+    let obscuredBy;
+    const box = element.getBoundingClientRect();
+    const [x, y] = [box.left + box.width / 2, box.top + box.height / 2];
+    const hit = x >= 0 && y >= 0 && x < innerWidth && y < innerHeight ? document.elementFromPoint(x, y) : null;
+    if (hit && !isAbove(element, hit) && !isAbove(hit, element)) {
+        for (let node = hit; node; node = node.parentElement) if (["fixed", "sticky"].includes(getComputedStyle(node).position)) { obscuredBy = describe(node).target; break; }
+    }
+    element.blur?.();
+    const visible = look(element) !== focused;
+    element.focus?.({ preventScroll: true });
+    const main = document.querySelector("main, [role=main]");
+    let skipsTo;
+    if (element instanceof HTMLAnchorElement && element.hash && element.href.split("#")[0] === location.href.split("#")[0]) {
+        const id = decodeURIComponent(element.hash.slice(1));
+        const target = document.getElementById(id) ?? document.getElementsByName(id)[0];
+        if (target) skipsTo = { target: describe(target).target, main: Boolean(main && (target === main || target.contains(main) || main.contains(target))) };
+    }
+    return { index: (${CANDIDATES} ?? []).indexOf(element), ...describe(element), visible, ...(obscuredBy && { "obscured-by": obscuredBy }), inMain: Boolean(main?.contains(element)), ...(skipsTo && { skipsTo }) };
+})()`;
+// Candidates Tab never reached and still shown; a radio group counts as reached through any of its radios.
+function missed(reached) {
+    return `(() => {
+        ${DESCRIBE}
+        const candidates = ${CANDIDATES} ?? [];
+        const reached = new Set(${JSON.stringify(reached)});
+        const groups = new Set([...reached].map((index) => candidates[index]).filter((element) => element?.type === "radio").map((element) => element.name));
+        return candidates.filter((element, index) => !reached.has(index) && element.isConnected && element.checkVisibility({ visibilityProperty: true }) && !(element.type === "radio" && groups.has(element.name))).map((element) => describe(element));
+    })()`;
+}
+// Candidate indexes whose focus shows no change once refocused from script, as `INSPECT` compares.
+function unchanged(indexes) {
+    return `(() => {
+        ${LOOK}
+        const candidates = ${CANDIDATES} ?? [];
+        return ${JSON.stringify(indexes)}.filter((index) => {
+            const element = candidates[index];
+            if (!element?.isConnected) return false;
+            element.focus({ preventScroll: true });
+            const focused = look(element);
+            element.blur();
+            return look(element) === focused;
+        });
+    })()`;
+}
+// Presses Tab until focus wraps to its first stop, leaves the page, stops moving, or cycles back to a later stop.
+async function walk(page, url) {
+    const count = (await page.evaluate(MARK));
+    const limit = Math.min(count * PER_CANDIDATE + SLACK, MAX_PRESSES);
+    const stops = [];
+    const seen = new Map();
+    let [complete, still, trap] = [false, 0, undefined];
+    for (let press = 0; press < limit; press += 1) {
+        await page.keyboard.press("Tab");
+        const stop = (await page.evaluate(INSPECT));
+        if (!stop) {
+            complete = stops.length > 0;
+            if (complete)
+                break;
+            continue;
+        }
+        const at = seen.get(stop.index >= 0 ? `#${stop.index}` : stop.target);
+        if (at !== undefined && at === stops.length - 1) {
+            still += 1;
+            if (still < STUCK)
+                continue;
+            trap = stop.target;
+            break;
+        }
+        still = 0;
+        if (at === 0) {
+            complete = true;
+            break;
+        }
+        if (at !== undefined) {
+            trap = stop.target;
+            break;
+        }
+        seen.set(stop.index >= 0 ? `#${stop.index}` : stop.target, stops.length);
+        stops.push(stop);
+    }
+    const unreached = complete ? (await page.evaluate(missed(stops.map((stop) => stop.index).filter((index) => index >= 0)))) : [];
+    const shown = stops.filter((stop) => stop.visible && stop.index >= 0).map((stop) => stop.index);
+    await page.emulateMedia({ forcedColors: "active" });
+    const lost = new Set((await page.evaluate(unchanged(shown))));
+    log.debug({ url, candidates: count, limit, stops: stops.length, complete, trap, unreached: unreached.length, forcedRead: shown.length, forcedLost: lost.size }, "keyboard walked");
+    const [head] = stops;
+    return {
+        stops: stops.map(({ target, html, visible, "obscured-by": obscuredBy, index }) => ({ target, html, visible, ...(obscuredBy && { "obscured-by": obscuredBy }), ...(visible && index >= 0 && { forced: !lost.has(index) }) })),
+        complete,
+        unreached,
+        ...(trap && { trap }),
+        ...(head && { first: { target: head.target, "in-main": head.inMain, ...(head.skipsTo && { "skips-to": head.skipsTo }) } }),
+    };
+}
+// Walks a fresh copy of the rendered page with Tab, leaving the crawler’s own page to the read-only extractors.
+async function extract(page, _body, live) {
+    if (!live || !page.html)
+        return;
+    return withPage(live, async (fresh) => {
+        await visit(fresh, page.url.href);
+        return walk(fresh, page.url.href);
+    });
+}
+const keyboardOf = (page) => page[ID];
+const located = (element) => `${element.target} ${element.html}`;
+const tabWalk = pageRule("keyboard/tab-walk", [`${ID}.trap`, `${ID}.unreached`], (page) => {
+    const facts = keyboardOf(page);
+    if (!facts)
+        return;
+    return [
+        ...(facts.trap ? [{ ...said("keyboard focus is trapped: Tab stops moving or cycles back"), data: { [page.url.href]: { trap: facts.trap } }, value: facts.trap, locations: [facts.trap] }] : []),
+        ...(facts.unreached.length > 0 ? [{ ...said("an interactive element is never reached by Tab"), data: { [page.url.href]: { elements: facts.unreached.length } }, value: facts.unreached, locations: facts.unreached.map((element) => located(element)) }] : []),
+    ];
+}, { docs: "https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html", fix: "Let Tab reach every control: drop negative tabindex from interactive elements, and release focus from any widget that holds it." });
+const focusVisible = pageRule("keyboard/focus-visible", [`${ID}.stops`], (page) => {
+    const hidden = keyboardOf(page)?.stops.filter((stop) => !stop.visible);
+    if (!hidden)
+        return;
+    return hidden.length === 0 ? [] : [{ ...said("an element shows no visible change when focused"), data: { [page.url.href]: { elements: hidden.length } }, value: hidden.map((stop) => stop.target), locations: hidden.map((stop) => located(stop)) }];
+}, { docs: "https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html", fix: "Give `:focus-visible` an outline or box-shadow; never remove the outline without a replacement." });
+const focusObscured = pageRule("keyboard/focus-obscured", [`${ID}.stops`], (page) => {
+    const covered = keyboardOf(page)?.stops.filter((stop) => stop["obscured-by"]);
+    if (!covered)
+        return;
+    return covered.length === 0 ? [] : [{ ...said("a focused element is hidden under fixed or sticky content"), data: { [page.url.href]: { elements: covered.length } }, value: covered.map((stop) => stop.target), locations: covered.map((stop) => `${located(stop)} under ${stop["obscured-by"]}`) }];
+}, { docs: "https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum.html", fix: "Set `scroll-padding-top` to the sticky header’s height, or keep banners from covering the content." });
+const forcedFocus = pageRule("keyboard/forced-focus", [`${ID}.stops`], (page) => {
+    const lost = keyboardOf(page)?.stops.filter((stop) => stop.forced === false);
+    if (!lost)
+        return;
+    return lost.length === 0 ? [] : [{ ...said("an element loses its focus indicator under forced colours"), data: { [page.url.href]: { elements: lost.length } }, value: lost.map((stop) => stop.target), locations: lost.map((stop) => located(stop)) }];
+}, { docs: "https://developer.mozilla.org/docs/Web/CSS/@media/forced-colors", fix: "Add `outline: 2px solid transparent` beside a `box-shadow` focus ring; forced colours drop the shadow and paint the outline." });
+const skipLink = pageRule("keyboard/skip-link", [`${ID}.first`], (page) => {
+    const first = keyboardOf(page)?.first;
+    if (!first)
+        return;
+    return first["in-main"] || first["skips-to"]?.main ? [] : [{ ...said("the first Tab stop is not a link to the main content"), value: first, locations: [first.target] }];
+}, { docs: "https://www.w3.org/WAI/WCAG22/Techniques/general/G1", fix: 'Make the first focusable element `<a href="#main">Skip to content</a>`, pointing at `<main id="main">`.' });
+export default definePlugin({
+    name: "keyboard",
+    extractors: [{ id: ID, mode: "browser", cost: "expensive", inputs: ["resources"], extract }],
+    rules: { "keyboard/tab-walk": tabWalk, "keyboard/focus-visible": focusVisible, "keyboard/focus-obscured": focusObscured, "keyboard/forced-focus": forcedFocus, "keyboard/skip-link": skipLink },
+    presets: {
+        keyboard: {
+            description: "Keyboard use on sampled pages: Tab reaches every control without a trap, focus shows, also under forced colours, and is not covered, a skip link comes first",
+            rules: {
+                "keyboard/tab-walk": { severity: "warning", score: 6.4 },
+                "keyboard/focus-visible": { severity: "warning", score: 6 },
+                "keyboard/focus-obscured": { severity: "warning", score: 5.8 },
+                "keyboard/forced-focus": { severity: "warning", score: 5.4 },
+                "keyboard/skip-link": { severity: "info", score: 2.8 },
+            },
+        },
+    },
+});

package/dist/plugins/lighthouse.js

@@ -0,0 +1,110 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+import { debuggingPort } from "../crawl/browser.js";
+import { log } from "../logger.js";
+import { definePlugin } from "./types.js";
+const ID = "lighthouse";
+// The lab metrics kept, by the Lighthouse audit that measures each.
+const VITALS = { lcp: "largest-contentful-paint", cls: "cumulative-layout-shift", tbt: "total-blocking-time", fcp: "first-contentful-paint", si: "speed-index", ttfb: "server-response-time" };
+// The offending value’s placeholder in a rule message.
+const GOT = "{got}";
+// The Lighthouse run in flight: its marks are process-global and Chromium traces once, so runs queue.
+const lane = { tail: Promise.resolve() };
+// Runs `audit` once every earlier call has settled.
+async function queued(audit) {
+    const previous = lane.tail;
+    const { promise, resolve } = Promise.withResolvers();
+    lane.tail = promise;
+    await previous;
+    try {
+        return await audit();
+    }
+    finally {
+        resolve();
+    }
+}
+// Runs Lighthouse in a new tab of the crawler’s Chromium, reached through its DevTools port; Lighthouse loads on first use.
+async function extract(page, _body, live) {
+    if (!live || !page.html)
+        return;
+    const port = debuggingPort(live);
+    if (port === undefined) {
+        log.debug({ url: page.url.href }, "no DevTools port; no Lighthouse facts");
+        return;
+    }
+    const { default: lighthouse } = await import("lighthouse");
+    log.debug({ url: page.url.href, port }, "Lighthouse queued");
+    const result = await queued(() => lighthouse(page.url.href, { port, output: "json", logLevel: "error" }));
+    const lhr = result?.lhr;
+    if (!lhr)
+        return;
+    if (lhr.runtimeError)
+        throw new Error(`${lhr.runtimeError.code}: ${lhr.runtimeError.message}`);
+    const scores = Object.fromEntries(Object.entries(lhr.categories).flatMap(([id, category]) => (category.score === null ? [] : [[id, category.score]])));
+    const vitals = Object.fromEntries(Object.entries(VITALS).flatMap(([key, audit]) => {
+        const value = lhr.audits[audit]?.numericValue;
+        return value === undefined ? [] : [[key, key === "cls" ? Number(value.toFixed(3)) : Math.round(value)]];
+    }));
+    log.debug({ url: page.url.href, port, scores, vitals, warnings: lhr.runWarnings }, "Lighthouse audited");
+    return { version: lhr.lighthouseVersion, "form-factor": lhr.configSettings.formFactor, scores, vitals };
+}
+// A category score of at least 0.9, Lighthouse’s own green.
+function score(category, label, link, scale) {
+    return { fact: `${ID}.scores.${category}`, expect: { type: "number", minimum: 0.9 }, severity: "warning", score: scale, message: `Lighthouse ${label} score is ${GOT}, under 0.9`, docs: link, fix: `Fix the failing audits Lighthouse lists under ${label}, largest savings first.` };
+}
+// A lab metric at most `limit`, the bound Lighthouse marks good.
+function metric(key, limit, unit, link, scale) {
+    return {
+        fact: `${ID}.vitals.${key}`,
+        expect: { type: "number", maximum: limit },
+        severity: "warning",
+        score: scale,
+        message: `${key.toUpperCase()} is ${GOT}${unit} in the lab, over ${limit}${unit}`,
+        docs: link,
+        fix: `Reduce ${key.toUpperCase()} below ${limit}${unit}; the Lighthouse report names the elements and resources behind it.`,
+    };
+}
+export default definePlugin({
+    name: "lighthouse",
+    extractors: [{ id: ID, mode: "browser", cost: "expensive", cached: false, debugging: true, extract }],
+    presets: {
+        lighthouse: {
+            description: "Lighthouse on sampled pages: performance, accessibility, best-practices and SEO scores, and lab LCP, CLS, TBT and FCP",
+            rules: {
+                "lighthouse/performance": score("performance", "performance", "https://developer.chrome.com/docs/lighthouse/performance/performance-scoring", [
+                    [0, 6.4],
+                    [0.9, 3.3],
+                ]),
+                "lighthouse/accessibility": score("accessibility", "accessibility", "https://developer.chrome.com/docs/lighthouse/accessibility/scoring", [
+                    [0, 6.2],
+                    [0.9, 3.3],
+                ]),
+                "lighthouse/best-practices": score("best-practices", "best-practices", "https://developer.chrome.com/docs/lighthouse/overview", [
+                    [0, 5.6],
+                    [0.9, 3.3],
+                ]),
+                "lighthouse/seo": score("seo", "SEO", "https://developer.chrome.com/docs/lighthouse/overview", [
+                    [0, 5.4],
+                    [0.9, 3.3],
+                ]),
+                "lighthouse/lcp": metric("lcp", 2500, " ms", "https://web.dev/articles/lcp", [
+                    [2500, 3.4],
+                    [6000, 6],
+                ]),
+                "lighthouse/cls": metric("cls", 0.1, "", "https://web.dev/articles/cls", [
+                    [0.1, 3.4],
+                    [0.25, 6],
+                ]),
+                "lighthouse/tbt": metric("tbt", 200, " ms", "https://web.dev/articles/tbt", [
+                    [200, 3.4],
+                    [600, 6],
+                ]),
+                "lighthouse/fcp": metric("fcp", 1800, " ms", "https://web.dev/articles/fcp", [
+                    [1800, 3.4],
+                    [3000, 6],
+                ]),
+            },
+        },
+    },
+});

package/dist/plugins/link-text.js

@@ -0,0 +1,73 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+import { load } from "cheerio";
+import { log } from "../logger.js";
+import { pageRule } from "../rules/builtin.js";
+import { said } from "../rules/message.js";
+import { definePlugin } from "./types.js";
+const ID = "linktext";
+// Link texts that say nothing about their target, per primary language subtag; a language absent here is never judged.
+const GENERIC = {
+    en: ["click here", "click", "here", "read more", "more", "learn more", "more info", "more information", "see more", "details", "continue", "continue reading", "link", "this link", "this", "go"],
+    es: ["haz clic aquí", "clic aquí", "pulsa aquí", "aquí", "leer más", "más", "saber más", "más información", "ver más", "detalles", "continuar", "seguir leyendo", "enlace", "este enlace"],
+    uk: ["натисніть тут", "тут", "читати далі", "читати більше", "детальніше", "докладніше", "більше", "дізнатися більше", "ще", "продовжити", "посилання", "це посилання"],
+};
+// Lower-cased, trimmed of punctuation and arrows, whitespace collapsed.
+function normalise(text, locale) {
+    return text
+        .toLocaleLowerCase(locale)
+        .replaceAll(/\s+/g, " ")
+        .trim()
+        .replaceAll(/[\p{P}\p{S}\s]+$|^[\p{P}\p{S}\s]+/gu, "");
+}
+// Anchors whose accessible name is a generic phrase of the page’s language; a language with no list adds nothing.
+async function extract(page, body) {
+    if (!page.html)
+        return;
+    const locale = page.html.lang?.split("-", 1)[0]?.toLowerCase();
+    const phrases = locale ? GENERIC[locale] : undefined;
+    if (!locale || !phrases) {
+        log.debug({ url: page.url.href, lang: page.html.lang }, "link text skipped: no phrase list for the language");
+        return;
+    }
+    const known = new Set(phrases);
+    const $ = load(body);
+    const labelled = (ids) => ids
+        .split(/\s+/)
+        .map((id) => $(`[id="${id.replaceAll('"', String.raw `\"`)}"]`).text())
+        .join(" ");
+    const generic = $("a[href]")
+        .get()
+        .flatMap((element) => {
+        const anchor = $(element);
+        const alt = anchor
+            .find("img[alt]")
+            .map((_, img) => $(img).attr("alt"))
+            .get()
+            .join(" ");
+        const name = anchor.attr("aria-labelledby") ? labelled(String(anchor.attr("aria-labelledby"))) : (anchor.attr("aria-label") ?? `${anchor.text()} ${alt}`);
+        const text = normalise(name, locale);
+        return known.has(text) ? [{ text, href: String(anchor.attr("href")) }] : [];
+    });
+    log.debug({ url: page.url.href, locale, generic: generic.length }, "link text read");
+    return { locale, generic };
+}
+const generic = pageRule("link-text/generic", [`${ID}.generic`], (page) => {
+    const facts = page[ID];
+    if (!facts)
+        return;
+    const count = facts.generic.length;
+    return count === 0 ? [] : [{ ...said("links say nothing about their targets out of context"), data: { [page.url.href]: { links: count } }, value: facts.generic, locations: facts.generic.map(({ text, href }) => `“${text}” → ${href}`) }];
+}, { docs: "https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html", fix: "Name the target in the link text itself, or give the link an `aria-label` that does." });
+export default definePlugin({
+    name: "link-text",
+    extractors: [{ id: ID, extract }],
+    rules: { "link-text/generic": generic },
+    presets: {
+        "link-text": {
+            description: "Links whose text says where they lead, judged in the page’s own language: English, Spanish and Ukrainian",
+            rules: { "link-text/generic": { severity: "warning", score: 4.6 } },
+        },
+    },
+});

package/dist/plugins/list.js

@@ -0,0 +1,22 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+import { readFile } from "node:fs/promises";
+import { definePlugin } from "./types.js";
+// One URL per line of a file, `-` for stdin, skipping blank lines and `#` comments; they are the whole frontier.
+export default definePlugin({
+    name: "list",
+    sources: [
+        {
+            id: "list",
+            follow: false,
+            urls: async (file, signal) => {
+                const text = await readFile(file === "-" ? "/dev/stdin" : file, { encoding: "utf8", signal });
+                return text
+                    .split(/\r?\n/)
+                    .map((line) => line.trim())
+                    .filter((line) => line.length > 0 && !line.startsWith("#"));
+            },
+        },
+    ],
+});