@ismail-elkorchi/css-parser 0.1.0 → 0.2.0

package/dist/internal/selectors/parser.js

@@ -0,0 +1,702 @@
+import { CSS_WEBREF_DATA } from "../generated/css-data.js";
+import { ResourceGuard } from "../syntax/resources.js";
+import { parseCssComponentValues } from "../syntax/parser.js";
+const SELECTORS = "https://drafts.csswg.org/selectors/";
+const LEGACY_PSEUDO_ELEMENTS = new Set([
+    "after",
+    "before",
+    "first-letter",
+    "first-line"
+]);
+const FORGIVING_SELECTOR_LIST_PSEUDOS = new Set(["is", "where"]);
+const NTH_PSEUDOS = new Set([
+    "nth-child",
+    "nth-last-child",
+    "nth-of-type",
+    "nth-last-of-type"
+]);
+const EXCLUDED_OBSOLETE_PSEUDOS = new Set(["matches"]);
+function knownPseudos(kind, functional) {
+    const prefix = kind === "class" ? ":" : "::";
+    const names = CSS_WEBREF_DATA.selectors.flatMap((selector) => {
+        if (!selector.startsWith(prefix) ||
+            (kind === "class" && selector.startsWith("::"))) {
+            return [];
+        }
+        const notation = selector.slice(prefix.length);
+        const isFunctional = notation.endsWith("()");
+        const name = isFunctional ? notation.slice(0, -2) : notation;
+        return isFunctional === functional && !EXCLUDED_OBSOLETE_PSEUDOS.has(name)
+            ? [name]
+            : [];
+    });
+    return new Set(names);
+}
+const FUNCTIONAL_PSEUDO_CLASSES = knownPseudos("class", true);
+const NON_FUNCTIONAL_PSEUDO_CLASSES = knownPseudos("class", false);
+const FUNCTIONAL_PSEUDO_ELEMENTS = knownPseudos("element", true);
+const NON_FUNCTIONAL_PSEUDO_ELEMENTS = knownPseudos("element", false);
+function lowerAscii(value) {
+    return value.replace(/[A-Z]/gu, (character) => character.toLowerCase());
+}
+function frozen(values) {
+    return Object.freeze(values);
+}
+function isDelim(value, codePoint) {
+    return value?.kind === "delim" && value.value === codePoint;
+}
+function position(offset, line, column) {
+    return Object.freeze({ offset, line, column });
+}
+function emptySpan() {
+    const start = position(0, 1, 1);
+    return Object.freeze({ start, end: start });
+}
+function coveringSpan(values) {
+    const first = values[0];
+    const last = values.at(-1);
+    return first === undefined || last === undefined
+        ? emptySpan()
+        : Object.freeze({ start: first.span.start, end: last.span.end });
+}
+function joinedSpan(start, end) {
+    return Object.freeze({ start: start.start, end: end.end });
+}
+function splitAtCommas(values) {
+    const groups = [[]];
+    for (const value of values) {
+        if (value.kind === "comma")
+            groups.push([]);
+        else
+            groups.at(-1)?.push(value);
+    }
+    return Object.freeze(groups.map((group) => Object.freeze(group)));
+}
+function significant(values) {
+    return Object.freeze(values.filter((value) => value.kind !== "whitespace"));
+}
+class SelectorParser {
+    values;
+    #guard;
+    #diagnostics = [];
+    #depth = 0;
+    #hasDepth = 0;
+    constructor(values, options, priorUsage) {
+        this.values = values;
+        this.#guard = new ResourceGuard(options.limits, options.signal, priorUsage);
+    }
+    parse(syntaxErrors) {
+        const parsed = this.#parseList(this.values, false, false, true);
+        const errors = Object.freeze([...syntaxErrors, ...this.#diagnostics]);
+        if (syntaxErrors.length > 0 ||
+            !parsed.valid ||
+            parsed.selectors.length === 0) {
+            return Object.freeze({
+                ok: false,
+                errors,
+                usage: this.#usage()
+            });
+        }
+        const value = Object.freeze({
+            selectors: parsed.selectors,
+            span: coveringSpan(this.values)
+        });
+        this.#node();
+        return Object.freeze({
+            ok: true,
+            value,
+            errors,
+            usage: this.#usage()
+        });
+    }
+    #parseList(values, forgiving, relative, allowPseudoElements) {
+        return this.#nested(() => {
+            const selectors = [];
+            let valid = true;
+            for (const group of splitAtCommas(values)) {
+                this.#guard.step();
+                const diagnosticStart = this.#diagnostics.length;
+                const localDiagnostics = [];
+                const parser = new ComplexSelectorParser(group, relative, allowPseudoElements, this.#guard, (code, message, span) => {
+                    localDiagnostics.push(Object.freeze({
+                        kind: "selector",
+                        code,
+                        message,
+                        span,
+                        specRef: `${SELECTORS}#grammar`
+                    }));
+                }, (functionBlock, kind) => this.#pseudoArgument(functionBlock, kind));
+                const selector = parser.parse();
+                if (selector === null) {
+                    valid = false;
+                    if (forgiving) {
+                        this.#diagnostics.splice(diagnosticStart);
+                    }
+                    else {
+                        this.#diagnostics.push(...localDiagnostics);
+                    }
+                }
+                else {
+                    this.#diagnostics.push(...localDiagnostics);
+                    selectors.push(selector);
+                }
+            }
+            return Object.freeze({
+                selectors: frozen(selectors),
+                valid: forgiving || valid
+            });
+        });
+    }
+    #pseudoArgument(value, kind) {
+        const name = lowerAscii(value.name);
+        if ((kind === "class" && NON_FUNCTIONAL_PSEUDO_CLASSES.has(name)) ||
+            (kind === "element" && NON_FUNCTIONAL_PSEUDO_ELEMENTS.has(name))) {
+            this.#diagnostic("invalid-pseudo", `:${kind === "element" ? ":" : ""}${name} is not functional.`, value.span);
+            return null;
+        }
+        if (kind === "class" &&
+            FORGIVING_SELECTOR_LIST_PSEUDOS.has(name)) {
+            const parsed = this.#parseList(value.value, true, false, false);
+            return Object.freeze({
+                kind: "selector-list",
+                selectors: parsed.selectors,
+                forgiving: true,
+                relative: false
+            });
+        }
+        if (kind === "class" && name === "not") {
+            const parsed = this.#parseList(value.value, false, false, false);
+            if (!parsed.valid || parsed.selectors.length === 0) {
+                this.#diagnostic("invalid-pseudo", ":not() requires at least one valid selector.", value.span);
+                return null;
+            }
+            return Object.freeze({
+                kind: "selector-list",
+                selectors: parsed.selectors,
+                forgiving: false,
+                relative: false
+            });
+        }
+        if (kind === "class" && name === "has") {
+            if (this.#hasDepth > 0) {
+                this.#diagnostic("invalid-pseudo", ":has() cannot be nested.", value.span);
+                return null;
+            }
+            this.#hasDepth += 1;
+            let parsed;
+            try {
+                parsed = this.#parseList(value.value, false, true, false);
+            }
+            finally {
+                this.#hasDepth -= 1;
+            }
+            if (!parsed.valid || parsed.selectors.length === 0) {
+                this.#diagnostic("invalid-pseudo", ":has() requires at least one valid relative selector.", value.span);
+                return null;
+            }
+            return Object.freeze({
+                kind: "selector-list",
+                selectors: parsed.selectors,
+                forgiving: false,
+                relative: true
+            });
+        }
+        if (kind === "class" && NTH_PSEUDOS.has(name)) {
+            return this.#parseNth(value);
+        }
+        if (kind === "class" && name === "dir") {
+            const parts = significant(value.value);
+            if (parts.length !== 1 || parts[0]?.kind !== "ident") {
+                this.#diagnostic("invalid-pseudo", ":dir() requires one identifier.", value.span);
+                return null;
+            }
+        }
+        if (kind === "class" && name === "lang") {
+            const ranges = splitAtCommas(value.value);
+            if (ranges.length === 0 ||
+                ranges.some((range) => {
+                    const parts = significant(range);
+                    return parts.length !== 1 ||
+                        (parts[0]?.kind !== "ident" && parts[0]?.kind !== "string");
+                })) {
+                this.#diagnostic("invalid-pseudo", ":lang() requires a comma-separated list of identifiers or strings.", value.span);
+                return null;
+            }
+        }
+        if (kind === "element" && name === "slotted") {
+            const parsed = this.#parseList(value.value, false, false, false);
+            if (!parsed.valid || parsed.selectors.length !== 1) {
+                this.#diagnostic("invalid-pseudo", "::slotted() requires one compound selector.", value.span);
+                return null;
+            }
+            return Object.freeze({
+                kind: "selector-list",
+                selectors: parsed.selectors,
+                forgiving: false,
+                relative: false
+            });
+        }
+        return Object.freeze({
+            kind: "raw",
+            value: Object.freeze([...value.value])
+        });
+    }
+    #parseNth(value) {
+        const parts = [...value.value];
+        let ofIndex = -1;
+        for (let index = 0; index < parts.length; index += 1) {
+            const part = parts[index];
+            if (part?.kind === "ident" && lowerAscii(part.value) === "of") {
+                ofIndex = index;
+                break;
+            }
+        }
+        const formulaValues = significant(ofIndex < 0 ? parts : parts.slice(0, ofIndex));
+        const formula = formulaValues.map((part) => {
+            if (part.kind === "ident")
+                return part.value;
+            if (part.kind === "number")
+                return part.representation;
+            if (part.kind === "dimension") {
+                return `${part.representation}${part.unit}`;
+            }
+            return part.kind === "delim"
+                ? String.fromCodePoint(part.value)
+                : "";
+        }).join("");
+        const coefficients = parseAnPlusB(formula);
+        if (coefficients === null) {
+            this.#diagnostic("invalid-nth", "Expected an An+B expression.", value.span);
+            return null;
+        }
+        let of = Object.freeze([]);
+        if (ofIndex >= 0) {
+            const name = lowerAscii(value.name);
+            if (name !== "nth-child" && name !== "nth-last-child") {
+                this.#diagnostic("invalid-nth", `:${name}() does not accept an of selector list.`, value.span);
+                return null;
+            }
+            const parsed = this.#parseList(parts.slice(ofIndex + 1), false, false, false);
+            if (!parsed.valid || parsed.selectors.length === 0) {
+                this.#diagnostic("invalid-nth", "The of clause requires a selector list.", value.span);
+                return null;
+            }
+            of = parsed.selectors;
+        }
+        return Object.freeze({
+            kind: "nth",
+            ...coefficients,
+            of
+        });
+    }
+    #diagnostic(code, message, span) {
+        this.#diagnostics.push(Object.freeze({
+            kind: "selector",
+            code,
+            message,
+            span,
+            specRef: `${SELECTORS}#grammar`
+        }));
+    }
+    #node() {
+        this.#guard.createNode(this.#depth);
+    }
+    #usage() {
+        return this.#guard.snapshot();
+    }
+    #nested(operation) {
+        this.#depth += 1;
+        try {
+            this.#guard.createNode(this.#depth);
+            return operation();
+        }
+        finally {
+            this.#depth -= 1;
+        }
+    }
+}
+class ComplexSelectorParser {
+    relative;
+    allowPseudoElements;
+    guard;
+    diagnostic;
+    pseudoArgument;
+    #values;
+    #index = 0;
+    #failed = false;
+    constructor(values, relative, allowPseudoElements, guard, diagnostic, pseudoArgument) {
+        this.relative = relative;
+        this.allowPseudoElements = allowPseudoElements;
+        this.guard = guard;
+        this.diagnostic = diagnostic;
+        this.pseudoArgument = pseudoArgument;
+        this.#values = values;
+    }
+    parse() {
+        this.#skipWhitespace();
+        const leadingCombinator = this.relative ? this.#explicitCombinator() : null;
+        if (leadingCombinator !== null)
+            this.#skipWhitespace();
+        const compounds = [];
+        const combinators = [];
+        const first = this.#compound();
+        if (first === null) {
+            if (!this.#failed) {
+                this.#fail("empty-selector", "Expected a compound selector.", coveringSpan(this.#values));
+            }
+            return null;
+        }
+        compounds.push(first);
+        while (this.#index < this.#values.length) {
+            const hadWhitespace = this.#skipWhitespace();
+            let combinator = this.#explicitCombinator();
+            if (combinator === null && hadWhitespace)
+                combinator = " ";
+            if (combinator === null) {
+                this.#fail("invalid-selector", "Expected a combinator or the end of the selector.", this.#currentSpan());
+                return null;
+            }
+            this.#skipWhitespace();
+            const compound = this.#compound();
+            if (compound === null) {
+                this.#fail("invalid-combinator", "A combinator must be followed by a compound selector.", this.#currentSpan());
+                return null;
+            }
+            combinators.push(combinator);
+            compounds.push(compound);
+        }
+        const span = joinedSpan(compounds[0]?.span ?? coveringSpan(this.#values), compounds.at(-1)?.span ?? coveringSpan(this.#values));
+        this.guard.createNode(1);
+        return Object.freeze({
+            leadingCombinator,
+            compounds: frozen(compounds),
+            combinators: frozen(combinators),
+            span
+        });
+    }
+    #compound() {
+        const start = this.#index;
+        const type = this.#typeSelector();
+        const simples = [];
+        let pseudoElementSeen = false;
+        for (;;) {
+            this.guard.step();
+            const simple = this.#simpleSelector();
+            if (simple === null)
+                break;
+            if (pseudoElementSeen &&
+                simple.kind !== "pseudo-class" &&
+                simple.kind !== "pseudo-element") {
+                this.#fail("invalid-selector", "Only pseudo selectors may follow a pseudo-element.", simple.span);
+                return null;
+            }
+            if (!this.allowPseudoElements &&
+                simple.kind === "pseudo-element") {
+                this.#fail("invalid-selector", "Pseudo-elements are not allowed in this selector list.", simple.span);
+                return null;
+            }
+            if (simple.kind === "pseudo-element")
+                pseudoElementSeen = true;
+            simples.push(simple);
+        }
+        if (type === null && simples.length === 0)
+            return null;
+        const consumed = this.#values.slice(start, this.#index);
+        this.guard.createNode(2);
+        return Object.freeze({
+            type,
+            simples: frozen(simples),
+            span: coveringSpan(consumed)
+        });
+    }
+    #typeSelector() {
+        const start = this.#index;
+        const first = this.#values[this.#index];
+        const firstName = this.#nameOrStar(first);
+        const startsEmptyNamespace = isDelim(first, 0x7c);
+        if (firstName === null && !startsEmptyNamespace)
+            return null;
+        let namespace = null;
+        let name = firstName;
+        if (startsEmptyNamespace) {
+            namespace = "";
+            this.#index += 1;
+            name = this.#nameOrStar(this.#values[this.#index]);
+            if (name === null) {
+                this.#index = start;
+                return null;
+            }
+            this.#index += 1;
+        }
+        else if (isDelim(this.#values[this.#index + 1], 0x7c) &&
+            !isDelim(this.#values[this.#index + 2], 0x7c)) {
+            namespace = firstName;
+            this.#index += 2;
+            name = this.#nameOrStar(this.#values[this.#index]);
+            if (name === null) {
+                this.#index = start;
+                return null;
+            }
+            this.#index += 1;
+        }
+        else {
+            this.#index += 1;
+        }
+        if (name === null) {
+            this.#index = start;
+            return null;
+        }
+        const span = coveringSpan(this.#values.slice(start, this.#index));
+        this.guard.createNode(3);
+        return Object.freeze({
+            kind: "type",
+            namespace,
+            name,
+            universal: name === "*",
+            span
+        });
+    }
+    #simpleSelector() {
+        const value = this.#values[this.#index];
+        if (value?.kind === "hash" && value.hashType === "id") {
+            this.#index += 1;
+            this.guard.createNode(3);
+            return Object.freeze({ kind: "id", value: value.value, span: value.span });
+        }
+        if (isDelim(value, 0x2e)) {
+            const name = this.#values[this.#index + 1];
+            if (name?.kind !== "ident")
+                return null;
+            this.#index += 2;
+            this.guard.createNode(3);
+            return Object.freeze({
+                kind: "class",
+                value: name.value,
+                span: joinedSpan(value?.span ?? name.span, name.span)
+            });
+        }
+        if (value?.kind === "simple-block" &&
+            value.associatedToken === "open-square") {
+            this.#index += 1;
+            return this.#attribute(value);
+        }
+        if (value?.kind === "colon")
+            return this.#pseudo();
+        if (isDelim(value, 0x26)) {
+            this.#index += 1;
+            this.guard.createNode(3);
+            return Object.freeze({ kind: "nesting", span: value?.span ?? emptySpan() });
+        }
+        return null;
+    }
+    #attribute(block) {
+        const parts = significant(block.value);
+        let index = 0;
+        const firstName = this.#nameOrStar(parts[index]);
+        const emptyNamespace = isDelim(parts[index], 0x7c);
+        let namespace = null;
+        let name = firstName;
+        if (emptyNamespace) {
+            namespace = "";
+            index += 1;
+            name = this.#nameOrStar(parts[index]);
+            index += 1;
+        }
+        else if (isDelim(parts[index + 1], 0x7c) &&
+            !isDelim(parts[index + 2], 0x3d)) {
+            namespace = firstName;
+            index += 2;
+            name = this.#nameOrStar(parts[index]);
+            index += 1;
+        }
+        else {
+            index += 1;
+        }
+        if (name === null || name === "*") {
+            this.#fail("invalid-attribute", "Expected an attribute name.", block.span);
+            return null;
+        }
+        let matcher = null;
+        let expected = null;
+        let modifier = null;
+        if (index < parts.length) {
+            const first = parts[index];
+            const second = parts[index + 1];
+            if (isDelim(first, 0x3d)) {
+                matcher = "=";
+                index += 1;
+            }
+            else if (first?.kind === "delim" &&
+                [0x7e, 0x7c, 0x5e, 0x24, 0x2a].includes(first.value) &&
+                isDelim(second, 0x3d)) {
+                matcher = `${String.fromCodePoint(first.value)}=`;
+                index += 2;
+            }
+            else {
+                this.#fail("invalid-attribute", "Expected an attribute matcher.", block.span);
+                return null;
+            }
+            const expectedToken = parts[index];
+            if (expectedToken?.kind !== "ident" &&
+                expectedToken?.kind !== "string") {
+                this.#fail("invalid-attribute", "Expected an identifier or string attribute value.", block.span);
+                return null;
+            }
+            expected = expectedToken.value;
+            index += 1;
+            const modifierToken = parts[index];
+            if (modifierToken?.kind === "ident") {
+                const candidate = lowerAscii(modifierToken.value);
+                if (candidate === "i" || candidate === "s") {
+                    modifier = candidate;
+                    index += 1;
+                }
+            }
+        }
+        if (index !== parts.length) {
+            this.#fail("invalid-attribute", "Unexpected content in attribute selector.", block.span);
+            return null;
+        }
+        this.guard.createNode(3);
+        return Object.freeze({
+            kind: "attribute",
+            namespace,
+            name,
+            matcher,
+            value: expected,
+            modifier,
+            span: block.span
+        });
+    }
+    #pseudo() {
+        const firstColon = this.#values[this.#index];
+        let kind = "class";
+        this.#index += 1;
+        if (this.#values[this.#index]?.kind === "colon") {
+            kind = "element";
+            this.#index += 1;
+        }
+        const nameValue = this.#values[this.#index];
+        if (nameValue?.kind !== "ident" && nameValue?.kind !== "function-block") {
+            this.#fail("invalid-pseudo", "Expected a pseudo selector name.", firstColon?.span ?? emptySpan());
+            return null;
+        }
+        this.#index += 1;
+        const name = lowerAscii(nameValue.kind === "ident" ? nameValue.value : nameValue.name);
+        if (kind === "class" && LEGACY_PSEUDO_ELEMENTS.has(name))
+            kind = "element";
+        const knownFunctional = kind === "class"
+            ? FUNCTIONAL_PSEUDO_CLASSES
+            : FUNCTIONAL_PSEUDO_ELEMENTS;
+        const knownNonFunctional = kind === "class"
+            ? NON_FUNCTIONAL_PSEUDO_CLASSES
+            : NON_FUNCTIONAL_PSEUDO_ELEMENTS;
+        if ((nameValue.kind === "ident" && !knownNonFunctional.has(name)) ||
+            (nameValue.kind === "function-block" && !knownFunctional.has(name))) {
+            this.#fail("invalid-pseudo", `Unknown pseudo-${kind}: ${name}.`, nameValue.span);
+            return null;
+        }
+        if (nameValue.kind === "ident" &&
+            knownFunctional.has(name)) {
+            this.#fail("invalid-pseudo", `:${kind === "element" ? ":" : ""}${name} requires arguments.`, nameValue.span);
+            return null;
+        }
+        const argument = nameValue.kind === "function-block"
+            ? this.pseudoArgument(nameValue, kind)
+            : Object.freeze({ kind: "none" });
+        if (argument === null) {
+            this.#failed = true;
+            return null;
+        }
+        const span = joinedSpan(firstColon?.span ?? nameValue.span, nameValue.span);
+        this.guard.createNode(3);
+        return kind === "class"
+            ? Object.freeze({
+                kind: "pseudo-class",
+                name,
+                argument,
+                span
+            })
+            : Object.freeze({
+                kind: "pseudo-element",
+                name,
+                argument,
+                span
+            });
+    }
+    #explicitCombinator() {
+        const value = this.#values[this.#index];
+        if (isDelim(value, 0x3e)) {
+            this.#index += 1;
+            return ">";
+        }
+        if (isDelim(value, 0x2b)) {
+            this.#index += 1;
+            return "+";
+        }
+        if (isDelim(value, 0x7e)) {
+            this.#index += 1;
+            return "~";
+        }
+        return null;
+    }
+    #skipWhitespace() {
+        const start = this.#index;
+        while (this.#values[this.#index]?.kind === "whitespace") {
+            this.guard.step();
+            this.#index += 1;
+        }
+        return this.#index !== start;
+    }
+    #nameOrStar(value) {
+        if (value?.kind === "ident")
+            return value.value;
+        if (isDelim(value, 0x2a))
+            return "*";
+        return null;
+    }
+    #currentSpan() {
+        return this.#values[this.#index]?.span ??
+            this.#values.at(-1)?.span ??
+            emptySpan();
+    }
+    #fail(code, message, span) {
+        this.#failed = true;
+        this.diagnostic(code, message, span);
+    }
+}
+function parseAnPlusB(source) {
+    const normalized = lowerAscii(source);
+    if (normalized === "odd")
+        return Object.freeze({ a: 2, b: 1 });
+    if (normalized === "even")
+        return Object.freeze({ a: 2, b: 0 });
+    if (/^[+-]?\d+$/u.test(normalized)) {
+        return Object.freeze({ a: 0, b: Number(normalized) });
+    }
+    const match = /^([+-]?\d*)n(?:([+-]\d+))?$/u.exec(normalized);
+    if (match === null)
+        return null;
+    const coefficient = match[1];
+    const a = coefficient === "" || coefficient === "+"
+        ? 1
+        : coefficient === "-"
+            ? -1
+            : Number(coefficient);
+    return Object.freeze({ a, b: Number(match[2] ?? 0) });
+}
+export function parseSelectorList(source, options = {}) {
+    const syntax = parseCssComponentValues(source, {
+        ...(options.limits === undefined ? {} : { limits: options.limits }),
+        ...(options.signal === undefined ? {} : { signal: options.signal })
+    });
+    if (!syntax.ok) {
+        return Object.freeze({
+            ok: false,
+            errors: syntax.errors,
+            usage: syntax.usage
+        });
+    }
+    const parser = new SelectorParser(syntax.value, options, syntax.usage);
+    return parser.parse(syntax.errors);
+}

package/dist/internal/selectors/specificity.d.ts

@@ -0,0 +1,3 @@
+import type { ComplexSelector, SelectorList, SelectorSpecificity, SelectorSpecificityOptions } from "./types.js";
+export declare function specificityOfComplexSelector(selector: ComplexSelector, options?: SelectorSpecificityOptions): SelectorSpecificity;
+export declare function specificitiesOfSelectorList(list: SelectorList, options?: SelectorSpecificityOptions): readonly SelectorSpecificity[];