spiderlint 0.0.0 → 0.143.0

package/dist/plugins/css.js

@@ -0,0 +1,328 @@
+// SPDX-FileCopyrightText: 2026 Damián Búho <damian.buho@proton.me>
+//
+// SPDX-License-Identifier: AGPL-3.0-only
+import { createHash } from "node:crypto";
+import { createRequire } from "node:module";
+import { Parser } from "htmlparser2";
+import { log } from "../logger.js";
+import { pageRule, resourceRule } from "../rules/builtin.js";
+import { said } from "../rules/message.js";
+import { definePlugin } from "./types.js";
+const ID = "css";
+const require = createRequire(import.meta.url);
+// Messages one style sheet or page keeps.
+const MESSAGES_MAX = 200;
+// Characters of the offending source a message quotes.
+const SOURCE_MAX = 80;
+// The rule a declaration list is wrapped in, so it parses as a style sheet; a type selector no caniuse feature matches.
+const WRAPPER = "a{";
+const SETTINGS = { type: "object", additionalProperties: false, properties: { targets: { type: "string", minLength: 1 } } };
+// The parsers once loading; absent until a run’s rules read `css`.
+const loaded = {};
+const load = () => (loaded.libraries ??= Promise.all([import("css-tree"), import("csstree-validator"), import("lightningcss"), import("postcss"), import("doiuse/lib/Detector.js")]));
+// Vendor-prefixed names and values, which a browser without the vendor ignores by design.
+const VENDOR = /(?:^|[\s(,:])-(?:webkit|moz|ms|o|khtml|apple|epub|xv|wap)-/i;
+// Hacks aimed at old Internet Explorer: `\9`, filters and expressions, `*prop` and `_prop`.
+const HACK = /\\9|progid:|expression\(|^[*_]/i;
+// `@page` and its margin boxes, whose descriptors and at-rules css-tree’s grammar lacks.
+const PAGED = new Set(["page", ...["top", "bottom"].flatMap((edge) => [`${edge}-left-corner`, `${edge}-left`, `${edge}-center`, `${edge}-right`, `${edge}-right-corner`]), ...["left", "right"].flatMap((edge) => [`${edge}-top`, `${edge}-middle`, `${edge}-bottom`])]);
+// `env()`, which css-tree matches inside math functions only, as it skips `var()` everywhere.
+const SUBSTITUTED = /(?<![\w-])env\(/i;
+// Legacy aliases judged by the property they alias, whose grammar css-tree keeps current.
+const ALIASES = { "word-wrap": "overflow-wrap" };
+// lightningcss warnings css-tree already reports, with vendor awareness: unknown at-rules and unclosed input.
+const DEFERRED = new Set(["AtRuleInvalid", "EndOfInput"]);
+// The declaration or selector text around `offset`, between the nearest `;`, `{` or `}` on each side.
+function around(css, offset) {
+    const start = Math.max(...[";", "{", "}"].map((mark) => css.lastIndexOf(mark, offset - 1))) + 1;
+    const ends = [";", "{", "}"].map((mark) => css.indexOf(mark, offset)).filter((index) => index >= 0);
+    const text = css
+        .slice(start, ends.length > 0 ? Math.min(...ends) : css.length)
+        .trim()
+        .replaceAll(/\s+/g, " ");
+    return text.length > SOURCE_MAX ? `${text.slice(0, SOURCE_MAX)}…` : text;
+}
+// The offset of a 1-based line and column in `css`.
+function offsetOf(css, line, column) {
+    let offset = 0;
+    for (let at = 1; at < line; at++)
+        offset = css.indexOf("\n", offset) + 1;
+    return offset + column - 1;
+}
+// A position in a CSS text moved to the document holding it.
+function shift(origin, line, column) {
+    return { line: origin.line + line - 1, column: line === 1 ? origin.column + column - 1 : column };
+}
+// Whether a grammar error is a vendor extension, a known hack, or a gap in css-tree’s grammar rather than a defect.
+function isExempt(error, source) {
+    const name = error.property ?? error.descriptor ?? "";
+    return name.startsWith("-") || HACK.test(name) || error.atrule?.startsWith("-") === true || PAGED.has(error.atrule?.toLowerCase() ?? "") || VENDOR.test(source) || HACK.test(source) || (error.name === "SyntaxMatchError" && SUBSTITUTED.test(source));
+}
+// What a browser drops for a css-tree error: an unknown name is a property, a value outside its grammar a value, the rest a rule or block.
+function kindOf(error) {
+    if (error.name === "SyntaxMatchError")
+        return "value";
+    return /^Unknown (?:property|at-rule descriptor) /.test(error.message) ? "property" : "parse";
+}
+// Whether a node is `@supports` or sits inside it, which guards it from browsers lacking it.
+function isGuarded(node) {
+    for (let parent = node; parent; parent = parent.parent)
+        if (parent.type === "atrule" && parent.name.toLowerCase() === "supports")
+            return true;
+    return false;
+}
+// Every caniuse feature doiuse can detect.
+const FEATURE_IDS = () => Object.keys(require("caniuse-lite").features);
+// Grammar, parse and feature facts of one CSS text: a style sheet, or a declaration list when `isDeclarations`.
+async function lint(css, origin, isDeclarations, element) {
+    const [csstree, { validate }, { transform }, { default: postcss }, { default: Detector }] = await load();
+    const text = isDeclarations ? `${WRAPPER}${css}}` : css;
+    const start = isDeclarations ? { line: origin.line, column: origin.column - WRAPPER.length } : origin;
+    const messages = [];
+    const add = (kind, message, line, column, offset) => {
+        messages.push({ kind, message: message.split("\n", 1)[0], ...shift(start, line, column), source: around(text, offset), ...(element && { in: element }) });
+    };
+    const ast = csstree.parse(text, { positions: true, parseAtrulePrelude: false, parseRulePrelude: false, parseValue: false, parseCustomProperty: false, onParseError: (error) => add("parse", error.message, error.line, error.column, error.offset) });
+    csstree.walk(ast, { visit: "Declaration", enter: (node) => void (node.property = ALIASES[node.property.toLowerCase()] ?? node.property) });
+    for (const error of validate(ast)) {
+        const source = around(text, error.offset);
+        const isNoise = isExempt(error, source);
+        log.debug({ element, line: error.line, column: error.column, error: error.message, source, isNoise }, "css grammar error");
+        if (!isNoise)
+            add(kindOf(error), error.message, error.line, error.column, error.offset);
+    }
+    try {
+        const { warnings } = transform({ filename: "style.css", code: Buffer.from(text), errorRecovery: true });
+        for (const warning of warnings) {
+            const offset = offsetOf(text, warning.loc.line, warning.loc.column);
+            const source = around(text, offset);
+            const isNoise = DEFERRED.has(warning.type) || VENDOR.test(source) || HACK.test(source);
+            log.debug({ element, type: warning.type, line: warning.loc.line, column: warning.loc.column, source, isNoise }, "css parse warning");
+            if (!isNoise)
+                add("parse", warning.message, warning.loc.line, warning.loc.column, offset);
+        }
+    }
+    catch (error) {
+        const loc = error.loc;
+        log.debug({ element, loc, error: error instanceof Error ? error.message : String(error) }, "css did not parse");
+        if (loc)
+            add("parse", error instanceof Error ? error.message : String(error), loc.line, loc.column, offsetOf(text, loc.line, loc.column));
+    }
+    const unique = new Map(messages.map((message) => [`${message.line}:${message.column}`, message])).values().toArray();
+    if (unique.length > MESSAGES_MAX)
+        log.debug({ element, messages: unique.length, kept: MESSAGES_MAX }, "css messages cut");
+    return { messages: unique.slice(0, MESSAGES_MAX), features: features(postcss, Detector, text, start, element) };
+}
+// Each caniuse feature `text` uses outside `@supports`, first where it appears; none when postcss cannot parse it.
+function features(postcss, Detector, text, start, element) {
+    const used = new Map();
+    try {
+        new Detector(FEATURE_IDS()).process(postcss.parse(text), ({ feature, usage, ignore }) => {
+            const at = usage.source?.start;
+            if (!at || ignore.includes(feature) || isGuarded(usage))
+                return;
+            const known = used.get(feature);
+            if (known)
+                known.count++;
+            else
+                used.set(feature, { feature, ...shift(start, at.line, at.column), count: 1, ...(element && { in: element }) });
+        });
+    }
+    catch (error) {
+        log.debug({ element, error: error instanceof Error ? error.message : String(error) }, "css features not detected");
+    }
+    return used.values().toArray();
+}
+// A style sheet’s facts.
+async function extractSheet(url, _contentType, body) {
+    const facts = await lint(new TextDecoder().decode(body), { line: 1, column: 1 }, false);
+    log.debug({ url, messages: facts.messages.length, features: facts.features.length }, "style sheet linted");
+    return facts;
+}
+// Each CSS `<style>` block and `style` attribute of an HTML document, with where its text starts.
+function inlineCss(body) {
+    const lines = [0, ...body.matchAll(/\n/g).map((match) => match.index + 1)];
+    const at = (offset) => {
+        const line = lines.findLastIndex((start) => start <= offset);
+        return { line: line + 1, column: offset - lines[line] + 1 };
+    };
+    const found = [];
+    let styleStart;
+    const parser = new Parser({
+        onopentag(name, attributes) {
+            const tag = body.slice(parser.startIndex, parser.endIndex + 1);
+            const attribute = /\sstyle\s*=\s*["']?/i.exec(tag);
+            if (attribute && attributes.style !== undefined)
+                found.push({ css: attributes.style, origin: at(parser.startIndex + attribute.index + attribute[0].length), isDeclarations: true, element: `<${name} style>` });
+            if (name === "style" && (attributes.type ?? "text/css").toLowerCase() === "text/css")
+                styleStart = parser.endIndex + 1;
+        },
+        onclosetag(name) {
+            if (name !== "style" || styleStart === undefined)
+                return;
+            found.push({ css: body.slice(styleStart, parser.startIndex), origin: at(styleStart), isDeclarations: false, element: "<style>" });
+            styleStart = undefined;
+        },
+    });
+    parser.end(body);
+    return found;
+}
+// Inline blocks already linted, by a hash of their text and where it starts; cleared past `BLOCKS_MAX`.
+const blocks = new Map();
+const BLOCKS_MAX = 4096;
+// Lints a block once per run, however many pages repeat it at the same spot.
+function lintBlock(block) {
+    const hash = createHash("sha256")
+        .update(JSON.stringify([block.css, block.origin, block.isDeclarations, block.element]))
+        .digest("hex");
+    const known = blocks.get(hash);
+    log.debug({ element: block.element, line: block.origin.line, hash: hash.slice(0, 12), isReused: known !== undefined }, "inline css block");
+    if (known)
+        return known;
+    if (blocks.size >= BLOCKS_MAX)
+        blocks.clear();
+    const linted = lint(block.css, block.origin, block.isDeclarations, block.element);
+    blocks.set(hash, linted);
+    return linted;
+}
+// An HTML page’s inline CSS facts; none for a page without any, or cut at `max-body-size`.
+async function extractInline(page, body) {
+    if (!page.html || page.http.size.truncated)
+        return undefined;
+    const found = inlineCss(body);
+    log.debug({ url: page.url.href, blocks: found.length }, "inline css found");
+    if (found.length === 0)
+        return undefined;
+    const linted = await Promise.all(found.map((block) => lintBlock(block)));
+    return {
+        messages: linted.flatMap((facts) => facts.messages).slice(0, MESSAGES_MAX),
+        features: Map.groupBy(linted.flatMap((facts) => facts.features), (used) => used.feature)
+            .values()
+            .map((uses) => ({ ...uses[0], count: uses.reduce((sum, used) => sum + used.count, 0) }))
+            .toArray(),
+    };
+}
+// What each kind of message costs the page, its docs and its fix.
+const KINDS = {
+    parse: {
+        name: "parse-error",
+        says: { sheet: "the style sheet has syntax errors, so browsers drop the rule or block each sits in; used by these pages", inline: "inline CSS has syntax errors, so browsers drop the rule or block each sits in" },
+        docs: "https://www.w3.org/TR/css-syntax-3/#error-handling",
+        fix: 'Close every block and string, and write selectors browsers accept, as in a::before { content: "" }.',
+    },
+    property: {
+        name: "unknown-property",
+        says: { sheet: "the style sheet names properties browsers do not know, so they drop those declarations; used by these pages", inline: "inline CSS names properties browsers do not know, so they drop those declarations" },
+        docs: "https://developer.mozilla.org/docs/Web/CSS/Reference",
+        fix: "Correct the property name, as in color: red for colr: red, or remove the declaration.",
+    },
+    value: {
+        name: "invalid-value",
+        says: { sheet: "the style sheet carries values outside a property’s grammar, so browsers drop those declarations; used by these pages", inline: "inline CSS carries values outside a property’s grammar, so browsers drop those declarations" },
+        docs: "https://developer.mozilla.org/docs/Web/CSS/CSS_values_and_units/Value_definition_syntax",
+        fix: "Give the property a value its grammar accepts, as in margin: calc(-1 * var(--gap)) for margin: -var(--gap).",
+    },
+};
+const cssOf = (resource) => resource[ID];
+const isLinted = (_page, resource) => cssOf(resource) !== undefined;
+// One location line: where, in which element, what, and the source it quotes.
+const located = (message) => [`${message.line}:${message.column}`, message.in, message.message, message.source && `— ${message.source}`].filter(Boolean).join(" ");
+// A style sheet rule, keyed by its URL, and its inline twin per page, over the messages of one kind.
+function kindRules(kind) {
+    const { name, says, docs, fix } = KINDS[kind];
+    const of = (facts) => facts?.messages.filter((message) => message.kind === kind) ?? [];
+    const sheet = resourceRule(`css/${name}`, isLinted, (resource) => {
+        const hits = of(cssOf(resource));
+        return hits.length === 0 ? undefined : { ...said(says.sheet), data: { [resource.url]: { messages: hits.length } }, locations: hits.map((hit) => located(hit)) };
+    }, [`resources.${ID}`], (resource) => of(cssOf(resource)), { docs, fix });
+    const inline = pageRule(`css/inline-${name}`, [`${ID}.messages`], (page) => {
+        const facts = page[ID];
+        const hits = of(facts);
+        return facts && (hits.length === 0 ? [] : [{ ...said(says.inline), data: { [page.url.href]: { messages: hits.length } }, value: hits, locations: hits.map((hit) => located(hit)) }]);
+    }, { docs, fix });
+    return { [`css/${name}`]: sheet, [`css/inline-${name}`]: inline };
+}
+// Targets per query, a bad one remembered as none, so each warns once.
+const targetsByQuery = new Map();
+// The declared browser targets: the `targets` setting, else the working directory’s browserslist config; none warns once.
+function targetsOf(settings) {
+    const browserslist = require("browserslist");
+    const query = settings.targets ?? browserslist.loadConfig({ path: process.cwd() })?.join(", ") ?? "";
+    if (!targetsByQuery.has(query)) {
+        try {
+            targetsByQuery.set(query, query === "" ? undefined : { query, browsers: browserslist(query) });
+        }
+        catch (error) {
+            targetsByQuery.set(query, undefined);
+            log.warn({ query, error: error instanceof Error ? error.message : String(error) }, `css/unsupported skipped, the browser targets "${query}" do not parse:`);
+        }
+        if (query === "")
+            log.info({ cwd: process.cwd() }, "css/unsupported skipped: no browser targets, set org.spiderlint.css.targets or add a .browserslistrc");
+    }
+    return targetsByQuery.get(query);
+}
+// caniuse data per feature, unpacked once.
+const unpacked = new Map();
+// Each browser among `browsers` caniuse marks as lacking `feature`, named with its lowest and highest such version; partial support counts as support.
+function lacking(feature, browsers) {
+    const caniuse = require("caniuse-lite");
+    if (!unpacked.has(feature))
+        unpacked.set(feature, caniuse.features[feature] && caniuse.feature(caniuse.features[feature]));
+    const stats = unpacked.get(feature)?.stats ?? {};
+    const lacks = browsers.map((browser) => browser.split(" ")).filter(([name, version]) => /^[np]\b/.test(stats[name]?.[version] ?? "y"));
+    return Map.groupBy(lacks, ([name]) => name)
+        .entries()
+        .map(([name, entries]) => {
+        const versions = entries.map(([, version]) => version).toSorted((a, b) => a.localeCompare(b, "en", { numeric: true }));
+        const [first, last] = [versions[0], versions.at(-1)];
+        return `${caniuse.agents[name]?.browser ?? name} ${first}${first === last ? "" : `–${last}`}`;
+    })
+        .toArray();
+}
+// The features of `facts` the targets lack, one location each.
+function unsupportedIn(facts, targets) {
+    const lacks = facts.features.map((used) => ({ used, browsers: lacking(used.feature, targets.browsers) })).filter(({ browsers }) => browsers.length > 0);
+    log.debug({ query: targets.query, features: facts.features.length, lacked: lacks.length }, "css features judged");
+    const locations = lacks.map(({ used, browsers }) => [`${used.line}:${used.column}`, used.in, unpacked.get(used.feature)?.title ?? used.feature, `— ${browsers.join(", ")}`].filter(Boolean).join(" "));
+    return lacks.length === 0 ? undefined : { features: lacks.length, locations };
+}
+const UNSUPPORTED = { docs: "https://developer.mozilla.org/docs/Web/CSS/@supports", fix: "Give the feature a fallback declaration before it, or guard it with @supports (display: grid) { … }." };
+// A rule that runs only once browser targets are declared.
+function targeted(rule, settings) {
+    return { meta: rule.meta, check: (...parameters) => (targetsOf(settings) ? rule.check(...parameters) : undefined) };
+}
+// Style sheets using features the declared browser targets lack, keyed by URL.
+const unsupported = (severity, settings) => targeted(resourceRule("css/unsupported", isLinted, (resource) => {
+    const targets = targetsOf(settings);
+    const judged = unsupportedIn(cssOf(resource), targets);
+    return judged && { ...said("the style sheet uses features the browser targets “{query}” lack; used by these pages", { query: targets.query }), data: { [resource.url]: { features: judged.features } }, locations: judged.locations };
+}, [`resources.${ID}`], (resource) => cssOf(resource)?.features, UNSUPPORTED)(severity), settings);
+// Inline CSS using features the declared browser targets lack, per page.
+const inlineUnsupported = (severity, settings) => targeted(pageRule("css/inline-unsupported", [`${ID}.features`], (page) => {
+    const facts = page[ID];
+    const targets = targetsOf(settings);
+    const judged = facts && unsupportedIn(facts, targets);
+    return facts && (judged ? [{ ...said("inline CSS uses features the browser targets “{query}” lack", { query: targets.query }), data: { [page.url.href]: { features: judged.features } }, value: facts.features.length, locations: judged.locations }] : []);
+}, UNSUPPORTED)(severity), settings);
+export default definePlugin({
+    name: "css",
+    settings: SETTINGS,
+    extractors: [{ id: ID, extract: extractInline }],
+    resources: [{ id: ID, types: ["text/css"], extract: extractSheet }],
+    rules: { ...kindRules("parse"), ...kindRules("property"), ...kindRules("value"), "css/unsupported": unsupported, "css/inline-unsupported": inlineUnsupported },
+    presets: {
+        css: {
+            description: "Style sheets and inline CSS as browsers parse them: syntax errors, unknown properties, values outside the grammar, and features the declared browser targets lack",
+            rules: {
+                "css/parse-error": { severity: "warning", score: 5.6 },
+                "css/unknown-property": { severity: "warning", score: 4.6 },
+                "css/invalid-value": { severity: "warning", score: 4.4 },
+                "css/unsupported": { severity: "info", score: 2.2 },
+                "css/inline-parse-error": { severity: "warning", score: 5.2 },
+                "css/inline-unknown-property": { severity: "warning", score: 4.2 },
+                "css/inline-invalid-value": { severity: "warning", score: 4 },
+                "css/inline-unsupported": { severity: "info", score: 1.8 },
+            },
+        },
+    },
+});