@ismail-elkorchi/css-parser 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ismail Elkorchi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# @ismail-elkorchi/css-parser
+
+Deterministic CSS parsing and selector evaluation for automation pipelines that need stable output across Node, Deno, Bun, and modern browsers.
+
+## Install
+
+```bash
+npm install @ismail-elkorchi/css-parser
+```
+
+```bash
+deno add jsr:@ismail-elkorchi/css-parser
+```
+
+```txt
+import { parse } from "jsr:@ismail-elkorchi/css-parser";
+```
+
+## Success Path
+
+```ts
+import {
+  compileSelectorList,
+  parse,
+  parseStream,
+  querySelectorAll,
+  serialize
+} from "@ismail-elkorchi/css-parser";
+
+const css = ".card { color: red; } #content .card { margin: 1px; }";
+const parsed = parse(css, {
+  budgets: { maxInputBytes: 4096, maxNodes: 256, maxDepth: 32 }
+});
+
+const stream = new ReadableStream({
+  start(controller) {
+    controller.enqueue(new TextEncoder().encode(".a{display:block}"));
+    controller.close();
+  }
+});
+
+const streamed = await parseStream(stream, {
+  budgets: { maxInputBytes: 4096, maxBufferedBytes: 256, maxNodes: 256 }
+});
+
+const selector = compileSelectorList("#content .card");
+const root = {
+  kind: "document",
+  children: [{ kind: "element", tagName: "main", attributes: [{ name: "id", value: "content" }], children: [] }]
+};
+
+console.log(querySelectorAll(selector, root).length);
+console.log(serialize(parsed));
+console.log(serialize(streamed));
+```
+
+Runnable examples:
+
+```bash
+npm run examples:run
+```
+
+## Options / API Reference
+
+- [Options and API reference](./docs/reference/options.md)
+
+## When To Use
+
+- You need deterministic CSS parse/serialize behavior for repeatable tooling.
+- You need parse budgets to bound runtime work and memory growth.
+- You need selector matching utilities in the same package as parsing.
+
+## When Not To Use
+
+- You need a browser layout engine.
+- You need CSS sanitization or policy enforcement beyond parsing.
+- You need runtime execution of scripts or DOM behavior.
+
+## Security Note
+
+Use explicit budgets for untrusted input and fail closed on `BudgetExceededError`. Parsing validates syntax structure, not trust or safety policy. See [SECURITY.md](./SECURITY.md).
+
+## Runtime Compatibility
+
+- Node.js (current LTS and current stable)
+- Deno (stable)
+- Bun (stable)
+- Modern evergreen browsers (smoke-tested)
+
+## No Runtime Dependencies
+
+No runtime dependencies are used by production parser code.
+
+## Docs Map
+
+- [Documentation index](./docs/index.md)
+
+## Release Trigger
+
+See [RELEASING.md](./RELEASING.md) for required secrets, trigger methods, and post-publish checks.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,19 @@
+# Third-party notices
+
+This repository vendors third-party sources and datasets for deterministic runtime behavior and conformance evaluation.
+
+## CSSTree
+- Source: https://github.com/csstree/csstree
+- Package/version: `css-tree@3.1.0`
+- Vendored files: `src/internal/vendor/csstree/csstree.esm.js`
+- License: MIT (`src/internal/vendor/csstree/LICENSE`)
+
+## CSSWG draft snapshots
+- Source: https://drafts.csswg.org/
+- Vendored files: `vendor/specs/csswg-drafts/*.html`
+- License: W3C/CSSWG publication terms per draft
+
+## Web Platform Tests (WPT)
+- Source: https://github.com/web-platform-tests/wpt
+- Vendored sparse checkout: `vendor/wpt`
+- License: upstream WPT repository license

package/dist/internal/csstree-runtime.d.ts

@@ -0,0 +1,20 @@
+export type CssTreeParseContext = "stylesheet" | "atrule" | "atrulePrelude" | "mediaQueryList" | "mediaQuery" | "condition" | "rule" | "selectorList" | "selector" | "block" | "declarationList" | "declaration" | "value";
+export interface CssTreeParseError {
+    readonly message: string;
+    readonly formattedMessage?: string;
+    readonly offset?: number;
+    readonly line?: number;
+    readonly column?: number;
+}
+export interface CssTreeParseOptions {
+    readonly context?: CssTreeParseContext;
+    readonly positions?: boolean;
+    readonly onParseError?: (error: CssTreeParseError) => void;
+}
+export declare function parse(source: string, options?: CssTreeParseOptions): unknown;
+export declare function generate(ast: unknown): string;
+export declare function tokenize(source: string, callback: (type: number, start: number, end: number) => void): void;
+export declare function toPlainObject(ast: unknown): unknown;
+export declare function fromPlainObject(ast: Record<string, unknown>): unknown;
+export declare const tokenNames: readonly string[];
+export declare const CSSTREE_VERSION: string;

package/dist/internal/csstree-runtime.js

@@ -0,0 +1,21 @@
+// Vendored CSSTree runtime entrypoint.
+// @ts-expect-error Vendored JS module does not include local .d.ts in this repository.
+import * as runtime from "./vendor/csstree/csstree.esm.js";
+const csstree = runtime;
+export function parse(source, options) {
+    return csstree.parse(source, options);
+}
+export function generate(ast) {
+    return csstree.generate(ast);
+}
+export function tokenize(source, callback) {
+    csstree.tokenize(source, callback);
+}
+export function toPlainObject(ast) {
+    return csstree.toPlainObject(ast);
+}
+export function fromPlainObject(ast) {
+    return csstree.fromPlainObject(ast);
+}
+export const tokenNames = csstree.tokenNames;
+export const CSSTREE_VERSION = csstree.version;

package/dist/internal/encoding/mod.d.ts

@@ -0,0 +1 @@
+export { decodeCssBytes, sniffCssEncoding, type EncodingSniffOptions, type EncodingSniffResult } from "./sniff.js";

package/dist/internal/encoding/mod.js

@@ -0,0 +1 @@
+export { decodeCssBytes, sniffCssEncoding } from "./sniff.js";

package/dist/internal/encoding/sniff.d.ts

@@ -0,0 +1,14 @@
+export interface EncodingSniffOptions {
+    readonly transportEncodingLabel?: string;
+    readonly maxPrescanBytes?: number;
+    readonly defaultEncoding?: string;
+}
+export interface EncodingSniffResult {
+    readonly encoding: string;
+    readonly source: "bom" | "transport" | "charset" | "default";
+}
+export declare function sniffCssEncoding(bytes: Uint8Array, options?: EncodingSniffOptions): EncodingSniffResult;
+export declare function decodeCssBytes(bytes: Uint8Array, options?: EncodingSniffOptions): {
+    text: string;
+    sniff: EncodingSniffResult;
+};

package/dist/internal/encoding/sniff.js

@@ -0,0 +1,95 @@
+const WINDOWS_1252_ALIASES = new Set([
+    "iso-8859-1",
+    "iso8859-1",
+    "latin1",
+    "latin-1",
+    "us-ascii"
+]);
+function detectBom(bytes) {
+    if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) {
+        return "utf-8";
+    }
+    if (bytes.length >= 2 && bytes[0] === 0xfe && bytes[1] === 0xff) {
+        return "utf-16be";
+    }
+    if (bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xfe) {
+        return "utf-16le";
+    }
+    return null;
+}
+function stripQuotes(value) {
+    const trimmed = value.trim();
+    if ((trimmed.startsWith("\"") && trimmed.endsWith("\"")) ||
+        (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+        return trimmed.slice(1, -1).trim();
+    }
+    return trimmed;
+}
+function canonicalizeLabel(label) {
+    const normalized = stripQuotes(label).toLowerCase();
+    if (normalized.length === 0) {
+        return null;
+    }
+    if (WINDOWS_1252_ALIASES.has(normalized)) {
+        return "windows-1252";
+    }
+    try {
+        const resolved = new TextDecoder(normalized).encoding.toLowerCase();
+        if (resolved === "iso-8859-1") {
+            return "windows-1252";
+        }
+        return resolved;
+    }
+    catch {
+        return null;
+    }
+}
+function decodeLatin1(bytes) {
+    let out = "";
+    for (let index = 0; index < bytes.length; index += 1) {
+        const value = bytes[index];
+        if (value !== undefined) {
+            out += String.fromCharCode(value);
+        }
+    }
+    return out;
+}
+function sniffCharsetRule(bytes, maxPrescanBytes) {
+    const scanSize = Math.min(bytes.length, maxPrescanBytes);
+    let scan = decodeLatin1(bytes.subarray(0, scanSize));
+    if (scan.charCodeAt(0) === 0xfeff) {
+        scan = scan.slice(1);
+    }
+    const match = scan.match(/^\s*@charset\s+("([^"]+)"|'([^']+)')\s*;/i);
+    if (!match) {
+        return null;
+    }
+    const label = match[2] ?? match[3] ?? "";
+    return canonicalizeLabel(label);
+}
+export function sniffCssEncoding(bytes, options = {}) {
+    const defaultEncoding = canonicalizeLabel(options.defaultEncoding ?? "utf-8") ?? "utf-8";
+    const bom = detectBom(bytes);
+    if (bom) {
+        return { encoding: bom, source: "bom" };
+    }
+    if (options.transportEncodingLabel) {
+        const transport = canonicalizeLabel(options.transportEncodingLabel);
+        if (transport) {
+            return { encoding: transport, source: "transport" };
+        }
+    }
+    const charset = sniffCharsetRule(bytes, options.maxPrescanBytes ?? 1024);
+    if (charset) {
+        return { encoding: charset, source: "charset" };
+    }
+    return { encoding: defaultEncoding, source: "default" };
+}
+export function decodeCssBytes(bytes, options = {}) {
+    const sniff = sniffCssEncoding(bytes, options);
+    const decoder = new TextDecoder(sniff.encoding);
+    return {
+        text: decoder.decode(bytes),
+        sniff
+    };
+}

package/dist/internal/serializer/mod.d.ts

@@ -0,0 +1 @@
+export { sanitizeCssNode, serializeTreeNode } from "./serialize.js";

package/dist/internal/serializer/mod.js

@@ -0,0 +1 @@
+export { sanitizeCssNode, serializeTreeNode } from "./serialize.js";

package/dist/internal/serializer/serialize.d.ts

@@ -0,0 +1,3 @@
+import type { CssAstNode } from "../tree/types.js";
+export declare function sanitizeCssNode(node: unknown): Record<string, unknown>;
+export declare function serializeTreeNode(node: CssAstNode | Record<string, unknown>): string;

package/dist/internal/serializer/serialize.js

@@ -0,0 +1,89 @@
+import { fromPlainObject, generate } from "../csstree-runtime.js";
+const METADATA_KEYS = new Set(["id", "span", "spanProvenance"]);
+function isRecord(value) {
+    return value !== null && typeof value === "object";
+}
+function hasLeadingWhitespace(value) {
+    if (value.length === 0) {
+        return false;
+    }
+    const first = value.charCodeAt(0);
+    return first === 0x20 || first === 0x09 || first === 0x0a || first === 0x0d || first === 0x0c;
+}
+function normalizeCustomPropertyValue(valueNode) {
+    const valueType = valueNode["type"];
+    if (valueType === "Raw") {
+        const rawValue = valueNode["value"];
+        if (typeof rawValue !== "string" || rawValue.length === 0 || hasLeadingWhitespace(rawValue)) {
+            return;
+        }
+        valueNode["value"] = ` ${rawValue}`;
+        return;
+    }
+    if (valueType !== "Value") {
+        return;
+    }
+    const children = valueNode["children"];
+    if (!Array.isArray(children) || children.length === 0) {
+        return;
+    }
+    const [first] = children;
+    if (isRecord(first) && first["type"] === "WhiteSpace") {
+        return;
+    }
+    children.unshift({
+        type: "WhiteSpace",
+        loc: null,
+        value: " "
+    });
+}
+function normalizeCustomPropertySpacing(node) {
+    if (Array.isArray(node)) {
+        for (const entry of node) {
+            normalizeCustomPropertySpacing(entry);
+        }
+        return;
+    }
+    if (!isRecord(node)) {
+        return;
+    }
+    if (node["type"] === "Declaration") {
+        const property = node["property"];
+        const value = node["value"];
+        if (typeof property === "string" && property.startsWith("--") && isRecord(value)) {
+            normalizeCustomPropertyValue(value);
+        }
+    }
+    for (const entry of Object.values(node)) {
+        normalizeCustomPropertySpacing(entry);
+    }
+}
+function sanitizeForRuntime(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => sanitizeForRuntime(entry));
+    }
+    if (!isRecord(value)) {
+        return value;
+    }
+    const next = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (METADATA_KEYS.has(key)) {
+            continue;
+        }
+        next[key] = sanitizeForRuntime(entry);
+    }
+    return next;
+}
+export function sanitizeCssNode(node) {
+    const sanitized = sanitizeForRuntime(node);
+    if (!isRecord(sanitized)) {
+        throw new Error("CSS node must be an object");
+    }
+    return sanitized;
+}
+export function serializeTreeNode(node) {
+    const sanitized = sanitizeCssNode(node);
+    normalizeCustomPropertySpacing(sanitized);
+    const runtimeNode = fromPlainObject(sanitized);
+    return generate(runtimeNode);
+}

package/dist/internal/tokenizer/mod.d.ts

@@ -0,0 +1,2 @@
+export { tokenize } from "./tokenize.js";
+export type { CssTokenInternal, TokenizeOptions, TokenizeResult, TokenizerBudgets, TokenizerParseError } from "./tokens.js";

package/dist/internal/tokenizer/mod.js

@@ -0,0 +1 @@
+export { tokenize } from "./tokenize.js";

package/dist/internal/tokenizer/tokenize.d.ts

@@ -0,0 +1,2 @@
+import type { TokenizeOptions, TokenizeResult } from "./tokens.js";
+export declare function tokenize(input: string, options?: TokenizeOptions): TokenizeResult;

package/dist/internal/tokenizer/tokenize.js

@@ -0,0 +1,39 @@
+import { tokenNames, tokenize as tokenizeWithCssTree } from "../csstree-runtime.js";
+function normalizeTokenKind(rawKind) {
+    return rawKind.endsWith("-token") ? rawKind.slice(0, -6) : rawKind;
+}
+export function tokenize(input, options = {}) {
+    const startedAt = Date.now();
+    const tokens = [];
+    const errors = [];
+    tokenizeWithCssTree(input, (type, start, end) => {
+        const rawKind = tokenNames[type] ?? `token-${String(type)}`;
+        const kind = normalizeTokenKind(rawKind);
+        tokens.push({
+            type,
+            kind,
+            rawKind,
+            value: input.slice(start, end),
+            start,
+            end
+        });
+    });
+    const maxTokens = options.budgets?.maxTokens;
+    if (maxTokens !== undefined && tokens.length > maxTokens) {
+        errors.push({
+            code: "max-tokens-exceeded",
+            index: tokens[maxTokens]?.start ?? input.length
+        });
+    }
+    const maxTimeMs = options.budgets?.maxTimeMs;
+    if (maxTimeMs !== undefined && Date.now() - startedAt > maxTimeMs) {
+        errors.push({
+            code: "soft-time-budget-exceeded",
+            index: input.length
+        });
+    }
+    return {
+        tokens: Object.freeze(tokens),
+        errors: Object.freeze(errors)
+    };
+}

package/dist/internal/tokenizer/tokens.d.ts

@@ -0,0 +1,23 @@
+export interface CssTokenInternal {
+    readonly type: number;
+    readonly kind: string;
+    readonly rawKind: string;
+    readonly value: string;
+    readonly start: number;
+    readonly end: number;
+}
+export interface TokenizerParseError {
+    readonly code: string;
+    readonly index: number;
+}
+export interface TokenizerBudgets {
+    readonly maxTokens?: number;
+    readonly maxTimeMs?: number;
+}
+export interface TokenizeOptions {
+    readonly budgets?: TokenizerBudgets;
+}
+export interface TokenizeResult {
+    readonly tokens: readonly CssTokenInternal[];
+    readonly errors: readonly TokenizerParseError[];
+}

package/dist/internal/tokenizer/tokens.js

@@ -0,0 +1 @@
+export {};

package/dist/internal/tree/build.d.ts

@@ -0,0 +1,2 @@
+import type { TreeBuildOptions, TreeBuildResult } from "./types.js";
+export declare function buildTreeFromCss(input: string, options?: TreeBuildOptions): TreeBuildResult;

package/dist/internal/tree/build.js

@@ -0,0 +1,85 @@
+import { parse as parseCssTree, toPlainObject } from "../csstree-runtime.js";
+const SUPPORTED_CONTEXTS = new Set([
+    "stylesheet",
+    "atrule",
+    "atrulePrelude",
+    "mediaQueryList",
+    "mediaQuery",
+    "condition",
+    "rule",
+    "selectorList",
+    "selector",
+    "block",
+    "declarationList",
+    "declaration",
+    "value"
+]);
+function isRecord(value) {
+    return value !== null && typeof value === "object";
+}
+function toTreeError(error) {
+    return {
+        message: error.message,
+        ...(typeof error.formattedMessage === "string" ? { formattedMessage: error.formattedMessage } : {}),
+        ...(typeof error.offset === "number" ? { offset: error.offset } : {}),
+        ...(typeof error.line === "number" ? { line: error.line } : {}),
+        ...(typeof error.column === "number" ? { column: error.column } : {})
+    };
+}
+function fallbackRoot(context, input) {
+    if (context === "stylesheet") {
+        return {
+            type: "StyleSheet",
+            loc: null,
+            children: [
+                {
+                    type: "Raw",
+                    loc: null,
+                    value: input
+                }
+            ]
+        };
+    }
+    return {
+        type: "Raw",
+        loc: null,
+        value: input
+    };
+}
+export function buildTreeFromCss(input, options = {}) {
+    const context = options.context ?? "stylesheet";
+    if (!SUPPORTED_CONTEXTS.has(context)) {
+        throw new Error(`Unsupported parse context: ${context}`);
+    }
+    const errors = [];
+    try {
+        const parsed = parseCssTree(input, {
+            context,
+            positions: options.captureSpans ?? false,
+            onParseError(error) {
+                const next = toTreeError(error);
+                errors.push(next);
+                options.onParseError?.(next);
+            }
+        });
+        const plain = toPlainObject(parsed);
+        if (!isRecord(plain) || typeof plain["type"] !== "string") {
+            throw new Error("CSSTree parse result was not a valid AST node");
+        }
+        return {
+            root: plain,
+            errors
+        };
+    }
+    catch (error) {
+        const fallbackError = {
+            message: error instanceof Error ? error.message : String(error)
+        };
+        errors.push(fallbackError);
+        options.onParseError?.(fallbackError);
+        return {
+            root: fallbackRoot(context, input),
+            errors
+        };
+    }
+}

package/dist/internal/tree/mod.d.ts

@@ -0,0 +1,2 @@
+export { buildTreeFromCss } from "./build.js";
+export type { CssAstNode, TreeBuildOptions, TreeBuildResult, TreeBuilderError, TreeSpan } from "./types.js";

package/dist/internal/tree/mod.js

@@ -0,0 +1 @@
+export { buildTreeFromCss } from "./build.js";

package/dist/internal/tree/types.d.ts

@@ -0,0 +1,25 @@
+import type { CssTreeParseContext } from "../csstree-runtime.js";
+export interface TreeSpan {
+    readonly start: number;
+    readonly end: number;
+}
+export interface CssAstNode {
+    readonly type: string;
+    readonly [key: string]: unknown;
+}
+export interface TreeBuilderError {
+    readonly message: string;
+    readonly formattedMessage?: string;
+    readonly offset?: number;
+    readonly line?: number;
+    readonly column?: number;
+}
+export interface TreeBuildOptions {
+    readonly context?: CssTreeParseContext;
+    readonly captureSpans?: boolean;
+    readonly onParseError?: (error: TreeBuilderError) => void;
+}
+export interface TreeBuildResult {
+    readonly root: CssAstNode;
+    readonly errors: readonly TreeBuilderError[];
+}

package/dist/internal/tree/types.js

@@ -0,0 +1 @@
+export {};

package/dist/internal/vendor/csstree/LICENSE

@@ -0,0 +1,19 @@
+Copyright (C) 2016-2024 by Roman Dvornov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.