@ismail-elkorchi/css-parser 0.1.0 → 0.1.1

package/README.md

@@ -1,6 +1,20 @@
 # @ismail-elkorchi/css-parser
 
-Deterministic CSS parsing and selector evaluation for automation pipelines that need stable output across Node, Deno, Bun, and modern browsers.
+Deterministic CSS parsing and selector utilities for automation across Node, Deno, Bun, and modern browsers.
+
+No runtime dependencies: this package ships with zero runtime dependencies.
+
+## When To Use
+
+- You need deterministic CSS parse/serialize output.
+- You need selector querying without browser-engine side effects.
+- You need explicit resource budgets for untrusted stylesheets.
+
+## When Not To Use
+
+- You need browser layout/cascade computation.
+- You need stylesheet sanitization and policy enforcement in one step.
+- You need script or DOM runtime semantics.
 
 ## Install
 
@@ -12,25 +26,31 @@ npm install @ismail-elkorchi/css-parser
 deno add jsr:@ismail-elkorchi/css-parser
 ```
 
+## Import
+
+```ts
+import { parse } from "@ismail-elkorchi/css-parser";
+```
+
 ```txt
 import { parse } from "jsr:@ismail-elkorchi/css-parser";
 ```
 
-## Success Path
+## Copy/Paste Examples
+
+### Example 1: Parse CSS
 
 ```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 }
-});
+import { parse } from "@ismail-elkorchi/css-parser";
+
+const tree = parse(".card { color: red; }");
+console.log(tree.kind);
+```
+
+### Example 2: Parse streaming input
+
+```ts
+import { parseStream } from "@ismail-elkorchi/css-parser";
 
 const stream = new ReadableStream({
   start(controller) {
@@ -39,62 +59,54 @@ const stream = new ReadableStream({
   }
 });
 
-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));
+const tree = await parseStream(stream, { budgets: { maxInputBytes: 4096, maxBufferedBytes: 512 } });
+console.log(tree.kind);
 ```
 
-Runnable examples:
-
-```bash
-npm run examples:run
-```
-
-## Options / API Reference
-
-- [Options and API reference](./docs/reference/options.md)
+### Example 3: Query selectors
 
-## When To Use
+```ts
+import { compileSelectorList, querySelectorAll } from "@ismail-elkorchi/css-parser";
 
-- 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.
+const selector = compileSelectorList(".card");
+console.log(selector.supported, querySelectorAll(selector, { kind: "document", children: [] }).length);
+```
 
-## When Not To Use
+### Example 4: Extract render signals
 
-- You need a browser layout engine.
-- You need CSS sanitization or policy enforcement beyond parsing.
-- You need runtime execution of scripts or DOM behavior.
+```ts
+import { extractRenderSignals, parse } from "@ismail-elkorchi/css-parser";
 
-## Security Note
+const tree = parse(".card { color: red; }");
+console.log(extractRenderSignals(tree).length >= 0);
+```
 
-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).
+Run packaged examples:
 
-## Runtime Compatibility
+```bash
+npm run examples:run
+```
 
-- Node.js (current LTS and current stable)
-- Deno (stable)
-- Bun (stable)
-- Modern evergreen browsers (smoke-tested)
+## Compatibility
 
-## No Runtime Dependencies
+Runtime compatibility matrix:
 
-No runtime dependencies are used by production parser code.
+| Runtime | Status |
+| --- | --- |
+| Node.js | Supported |
+| Deno | Supported |
+| Bun | Supported |
+| Browser (evergreen) | Supported |
 
-## Docs Map
+## Security and Safety Notes
 
-- [Documentation index](./docs/index.md)
+Parsing is not sanitization. For untrusted input:
+- configure strict budgets,
+- handle `BudgetExceededError` explicitly,
+- apply separate policy checks before execution or rendering.
 
-## Release Trigger
+## Documentation
 
-See [RELEASING.md](./RELEASING.md) for required secrets, trigger methods, and post-publish checks.
+- [Docs index](./docs/index.md)
+- [First parse success tutorial](./docs/tutorial/first-parse.md)
+- [Options reference](./docs/reference/options.md)

package/dist/public/mod.d.ts

@@ -3,33 +3,67 @@ export type { BudgetExceededPayload, BudgetOptions, CompiledSelector, CompiledSe
 export declare class BudgetExceededError extends Error {
     readonly payload: BudgetExceededPayload;
     constructor(payload: BudgetExceededPayload);
-}
+} /**
+ * Represents a structured public error for `PatchPlanningError` failure cases.
+ */
 export declare class PatchPlanningError extends Error {
     readonly payload: PatchPlanningErrorPayload;
     constructor(payload: PatchPlanningErrorPayload);
 }
-export declare function parse(css: string, options?: ParseOptions): StyleSheetTree;
-export declare function parseFragment(css: string, contextTagName: string, options?: ParseOptions): FragmentTree;
-export declare function parseRuleList(css: string, options?: ParseOptions): FragmentTree;
-export declare function parseDeclarationList(css: string, options?: ParseOptions): FragmentTree;
+export declare function parse(css: string, options?: ParseOptions): StyleSheetTree; /**
+ * Parses input deterministically for the `parseFragment` public API.
+ */
+export declare function parseFragment(css: string, contextTagName: string, options?: ParseOptions): FragmentTree; /**
+ * Parses input deterministically for the `parseRuleList` public API.
+ */
+export declare function parseRuleList(css: string, options?: ParseOptions): FragmentTree; /**
+ * Parses input deterministically for the `parseDeclarationList` public API.
+ */
+export declare function parseDeclarationList(css: string, options?: ParseOptions): FragmentTree; /**
+ * Returns deterministic public metadata for `getParseErrorSpecRef`.
+ */
 export declare function getParseErrorSpecRef(parseErrorId: string): string;
-export declare function tokenize(css: string, options?: TokenizeOptions): readonly Token[];
-export declare function tokenizeStream(stream: ReadableStream<Uint8Array>, options?: TokenizeOptions): AsyncIterable<Token>;
-export declare function parseBytes(bytes: Uint8Array, options?: ParseOptions): StyleSheetTree;
+export declare function tokenize(css: string, options?: TokenizeOptions): readonly Token[]; /**
+ * Tokenizes input deterministically for the `tokenizeStream` public API.
+ */
+export declare function tokenizeStream(stream: ReadableStream<Uint8Array>, options?: TokenizeOptions): AsyncIterable<Token>; /**
+ * Parses input deterministically for the `parseBytes` public API.
+ */
+export declare function parseBytes(bytes: Uint8Array, options?: ParseOptions): StyleSheetTree; /**
+ * Parses input deterministically for the `parseStream` public API.
+ */
 export declare function parseStream(stream: ReadableStream<Uint8Array>, options?: ParseOptions): Promise<StyleSheetTree>;
 export declare function serialize(treeOrNode: StyleSheetTree | FragmentTree | CssNode): string;
-export declare function walk(tree: StyleSheetTree | FragmentTree, visitor: NodeVisitor): void;
-export declare function walkByType(tree: StyleSheetTree | FragmentTree, type: string, visitor: NodeVisitor): void;
-export declare function findById(tree: StyleSheetTree | FragmentTree, id: NodeId): CssNode | null;
-export declare function findAllByType(tree: StyleSheetTree | FragmentTree, type: string): IterableIterator<CssNode>;
+export declare function walk(tree: StyleSheetTree | FragmentTree, visitor: NodeVisitor): void; /**
+ * Traverses parsed data deterministically for the `walkByType` public API.
+ */
+export declare function walkByType(tree: StyleSheetTree | FragmentTree, type: string, visitor: NodeVisitor): void; /**
+ * Traverses parsed data deterministically for the `findById` public API.
+ */
+export declare function findById(tree: StyleSheetTree | FragmentTree, id: NodeId): CssNode | null; /**
+ * Traverses parsed data deterministically for the `findAllByType` public API.
+ */
+export declare function findAllByType(tree: StyleSheetTree | FragmentTree, type: string): IterableIterator<CssNode>; /**
+ * Provides deterministic public behavior for `outline`.
+ */
 export declare function outline(tree: StyleSheetTree | FragmentTree): Outline;
 export declare function chunk(tree: StyleSheetTree | FragmentTree, options?: ChunkOptions): Chunk[];
-export declare function applyPatchPlan(originalCss: string, plan: PatchPlan): string;
+export declare function applyPatchPlan(originalCss: string, plan: PatchPlan): string; /**
+ * Computes deterministic public output for `computePatch`.
+ */
 export declare function computePatch(originalCss: string, edits: readonly Edit[]): PatchPlan;
 export declare function compileSelectorList(selectorText: string): CompiledSelectorList;
-export declare function extractStyleRuleSignals(cssOrTree: string | StyleSheetTree, options?: StyleSignalOptions): readonly StyleRuleSignal[];
-export declare function extractInlineStyleSignals(styleText: string): readonly StyleDeclarationSignal[];
-export declare function extractRenderSignals(cssOrTree: string | StyleSheetTree, options?: RenderSignalOptions): readonly RenderSignal[];
+export declare function extractStyleRuleSignals(cssOrTree: string | StyleSheetTree, options?: StyleSignalOptions): readonly StyleRuleSignal[]; /**
+ * Extracts deterministic public data for `extractInlineStyleSignals`.
+ */
+export declare function extractInlineStyleSignals(styleText: string): readonly StyleDeclarationSignal[]; /**
+ * Extracts deterministic public data for `extractRenderSignals`.
+ */
+export declare function extractRenderSignals(cssOrTree: string | StyleSheetTree, options?: RenderSignalOptions): readonly RenderSignal[]; /**
+ * Extracts deterministic public data for `extractInlineRenderSignals`.
+ */
 export declare function extractInlineRenderSignals(styleText: string, options?: RenderSignalOptions): readonly RenderSignal[];
-export declare function matchesSelector<TNode extends SelectorNodeLike>(selector: string | CompiledSelectorList, node: TNode, root: TNode, options?: SelectorQueryOptions): boolean;
+export declare function matchesSelector<TNode extends SelectorNodeLike>(selector: string | CompiledSelectorList, node: TNode, root: TNode, options?: SelectorQueryOptions): boolean; /**
+ * Traverses parsed data deterministically for the `querySelectorAll` public API.
+ */
 export declare function querySelectorAll<TNode extends SelectorNodeLike>(selector: string | CompiledSelectorList, root: TNode, options?: SelectorQueryOptions): readonly TNode[];

package/dist/public/mod.js

@@ -18,7 +18,9 @@ const SUPPORTED_PARSE_CONTEXTS = new Set([
     "declarationList",
     "declaration",
     "value"
-]);
+]); /**
+ * Represents a structured public error for `BudgetExceededError` failure cases.
+ */
 export class BudgetExceededError extends Error {
     payload;
     constructor(payload) {
@@ -26,7 +28,9 @@ export class BudgetExceededError extends Error {
         this.name = "BudgetExceededError";
         this.payload = payload;
     }
-}
+} /**
+ * Represents a structured public error for `PatchPlanningError` failure cases.
+ */
 export class PatchPlanningError extends Error {
     payload;
     constructor(payload) {
@@ -418,7 +422,9 @@ function parseInternal(css, context, options = {}) {
         errors: publicErrors,
         ...(trace ? { trace } : {})
     };
-}
+} /**
+ * Parses input deterministically for the `parse` public API.
+ */
 export function parse(css, options = {}) {
     if (options.context !== undefined && options.context !== "stylesheet") {
         throw new Error("parse() only supports context \"stylesheet\"; use parseFragment() for other contexts");
@@ -433,7 +439,9 @@ export function parse(css, options = {}) {
         errors: parsed.errors,
         ...(parsed.trace ? { trace: parsed.trace } : {})
     };
-}
+} /**
+ * Parses input deterministically for the `parseFragment` public API.
+ */
 export function parseFragment(css, contextTagName, options = {}) {
     const context = normalizeFragmentContext(contextTagName);
     if (!SUPPORTED_PARSE_CONTEXTS.has(context)) {
@@ -449,13 +457,19 @@ export function parseFragment(css, contextTagName, options = {}) {
         errors: parsed.errors,
         ...(parsed.trace ? { trace: parsed.trace } : {})
     };
-}
+} /**
+ * Parses input deterministically for the `parseRuleList` public API.
+ */
 export function parseRuleList(css, options = {}) {
     return parseFragment(css, "rule", options);
-}
+} /**
+ * Parses input deterministically for the `parseDeclarationList` public API.
+ */
 export function parseDeclarationList(css, options = {}) {
     return parseFragment(css, "declarationList", options);
-}
+} /**
+ * Returns deterministic public metadata for `getParseErrorSpecRef`.
+ */
 export function getParseErrorSpecRef(parseErrorId) {
     void parseErrorId;
     return CSS_PARSE_ERRORS_SECTION_URL;
@@ -568,7 +582,9 @@ async function decodeStreamToText(stream, options) {
         totalBytes: total,
         maxBufferedObserved
     };
-}
+} /**
+ * Tokenizes input deterministically for the `tokenize` public API.
+ */
 export function tokenize(css, options = {}) {
     enforceBudget("maxInputBytes", options.budgets?.maxInputBytes, css.length);
     const tokenized = tokenizeInternal(css, {
@@ -579,14 +595,18 @@ export function tokenize(css, options = {}) {
     });
     enforceBudget("maxTokens", options.budgets?.maxTokens, tokenized.tokens.length);
     return tokenized.tokens.map((token) => toPublicToken(token));
-}
+} /**
+ * Tokenizes input deterministically for the `tokenizeStream` public API.
+ */
 export async function* tokenizeStream(stream, options = {}) {
     const decoded = await decodeStreamToText(stream, options);
     const tokens = tokenize(decoded.text, options);
     for (const token of tokens) {
         yield token;
     }
-}
+} /**
+ * Parses input deterministically for the `parseBytes` public API.
+ */
 export function parseBytes(bytes, options = {}) {
     enforceBudget("maxInputBytes", options.budgets?.maxInputBytes, bytes.byteLength);
     const decoded = decodeCssBytes(bytes, {
@@ -609,7 +629,9 @@ export function parseBytes(bytes, options = {}) {
         ...parsed,
         trace: withDecodeTrace
     };
-}
+} /**
+ * Parses input deterministically for the `parseStream` public API.
+ */
 export async function parseStream(stream, options = {}) {
     const budgets = options.budgets;
     const decoded = await decodeStreamToText(stream, options);
@@ -645,7 +667,9 @@ function nodeFromTree(treeOrNode) {
         return treeOrNode.root;
     }
     return treeOrNode;
-}
+} /**
+ * Serializes data deterministically for the `serialize` public API.
+ */
 export function serialize(treeOrNode) {
     const node = nodeFromTree(treeOrNode);
     const sanitized = sanitizeCssNode(node);
@@ -656,10 +680,14 @@ function walkNode(node, depth, visitor) {
     for (const child of childNodes(node)) {
         walkNode(child, depth + 1, visitor);
     }
-}
+} /**
+ * Traverses parsed data deterministically for the `walk` public API.
+ */
 export function walk(tree, visitor) {
     walkNode(tree.root, 0, visitor);
-}
+} /**
+ * Traverses parsed data deterministically for the `walkByType` public API.
+ */
 export function walkByType(tree, type, visitor) {
     const normalizedType = type.toLowerCase();
     walk(tree, (node, depth) => {
@@ -667,7 +695,9 @@ export function walkByType(tree, type, visitor) {
             visitor(node, depth);
         }
     });
-}
+} /**
+ * Traverses parsed data deterministically for the `findById` public API.
+ */
 export function findById(tree, id) {
     let matched = null;
     walk(tree, (node) => {
@@ -676,7 +706,9 @@ export function findById(tree, id) {
         }
     });
     return matched;
-}
+} /**
+ * Traverses parsed data deterministically for the `findAllByType` public API.
+ */
 export function* findAllByType(tree, type) {
     const normalizedType = type.toLowerCase();
     const found = [];
@@ -688,7 +720,9 @@ export function* findAllByType(tree, type) {
     for (const node of found) {
         yield node;
     }
-}
+} /**
+ * Provides deterministic public behavior for `outline`.
+ */
 export function outline(tree) {
     const entries = [];
     walk(tree, (node, depth) => {
@@ -717,7 +751,9 @@ function countNodes(node) {
 }
 function topLevelNodes(tree) {
     return tree.children.length > 0 ? tree.children : [tree.root];
-}
+} /**
+ * Provides deterministic public behavior for `chunk`.
+ */
 export function chunk(tree, options = {}) {
     const maxChars = options.maxChars ?? 8192;
     const maxNodes = options.maxNodes ?? 256;
@@ -845,7 +881,9 @@ function buildReplacement(spanByNode, nodeById, edit, sourceIndex) {
         end: span.end,
         replacementCss: edit.css
     };
-}
+} /**
+ * Provides deterministic public behavior for `applyPatchPlan`.
+ */
 export function applyPatchPlan(originalCss, plan) {
     let cursor = 0;
     let output = "";
@@ -864,7 +902,9 @@ export function applyPatchPlan(originalCss, plan) {
         output += step.text;
     }
     return output;
-}
+} /**
+ * Computes deterministic public output for `computePatch`.
+ */
 export function computePatch(originalCss, edits) {
     if (edits.length === 0) {
         const steps = [
@@ -1400,7 +1440,9 @@ function compileSingleSelector(selectorNode, selectorIndex) {
         supported: unsupported.length === 0,
         unsupportedParts: unsupported
     };
-}
+} /**
+ * Provides deterministic public behavior for `compileSelectorList`.
+ */
 export function compileSelectorList(selectorText) {
     const parsed = parseFragment(selectorText, "selectorList");
     const selectorNodes = Array.isArray(parsed.root.children)
@@ -1536,7 +1578,9 @@ function classifyRenderSignalClass(declaration, options) {
         }
     }
     return null;
-}
+} /**
+ * Extracts deterministic public data for `extractStyleRuleSignals`.
+ */
 export function extractStyleRuleSignals(cssOrTree, options = {}) {
     const includeUnsupportedSelectors = options.includeUnsupportedSelectors === true;
     const strictSelectors = options.strictSelectors === true;
@@ -1580,7 +1624,9 @@ export function extractStyleRuleSignals(cssOrTree, options = {}) {
         });
     });
     return signals;
-}
+} /**
+ * Extracts deterministic public data for `extractInlineStyleSignals`.
+ */
 export function extractInlineStyleSignals(styleText) {
     const fragment = parseDeclarationList(styleText);
     const signals = [];
@@ -1594,7 +1640,9 @@ export function extractInlineStyleSignals(styleText) {
         declarationOrder += 1;
     }
     return signals;
-}
+} /**
+ * Extracts deterministic public data for `extractRenderSignals`.
+ */
 export function extractRenderSignals(cssOrTree, options = {}) {
     const ruleSignals = extractStyleRuleSignals(cssOrTree, options);
     const renderSignals = [];
@@ -1619,7 +1667,9 @@ export function extractRenderSignals(cssOrTree, options = {}) {
         }
     }
     return renderSignals;
-}
+} /**
+ * Extracts deterministic public data for `extractInlineRenderSignals`.
+ */
 export function extractInlineRenderSignals(styleText, options = {}) {
     const declarations = extractInlineStyleSignals(styleText);
     const renderSignals = [];
@@ -1664,7 +1714,9 @@ function resolveCompiledSelectorList(selector) {
         }
     }
     return compiled;
-}
+} /**
+ * Provides deterministic public behavior for `matchesSelector`.
+ */
 export function matchesSelector(selector, node, root, options = {}) {
     const compiled = resolveCompiledSelectorList(selector);
     assertSelectorStrict(compiled, options.strict === true);
@@ -1681,7 +1733,9 @@ export function matchesSelector(selector, node, root, options = {}) {
         }
     }
     return false;
-}
+} /**
+ * Traverses parsed data deterministically for the `querySelectorAll` public API.
+ */
 export function querySelectorAll(selector, root, options = {}) {
     const compiled = resolveCompiledSelectorList(selector);
     assertSelectorStrict(compiled, options.strict === true);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ismail-elkorchi/css-parser",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Deterministic CSS parser for automation workflows across Node, Deno, Bun, and modern browsers.",
   "license": "MIT",
   "repository": {
@@ -48,7 +48,7 @@
     "test:bench": "npm run build && node --expose-gc scripts/bench/run-bench.mjs",
     "test:bench:stability": "npm run build && node --expose-gc scripts/bench/run-bench-stability.mjs",
     "examples:run": "npm run build && node examples/run-all.mjs",
-    "check:fast": "npm run lint && npm run typecheck && npm run test:control && npm run examples:run",
+    "check:fast": "npm run lint && npm run typecheck && npm run test:control && npm run docs:required && npm run examples:run",
     "docs:lint:jsr": "deno doc --lint --sloppy-imports jsr/mod.ts",
     "docs:test:jsr": "deno test --doc --no-check --sloppy-imports jsr/mod.ts",
     "smoke:node": "npm run build && node scripts/smoke/control.mjs --runtime=node --report=reports/smoke-node.json",
@@ -65,10 +65,13 @@
     "realworld:bench:selectors:stability": "npm run build && node scripts/bench/run-selector-bench-stability.mjs",
     "realworld:check": "node scripts/realworld/check-realworld-targets.mjs",
     "eval:realworld": "npm run realworld:bench && npm run realworld:signals && npm run realworld:bench:selectors && npm run realworld:bench:selectors:stability && npm run realworld:check && node scripts/realworld/eval-realworld.mjs",
-    "mutation:pilot": "npm run build && node scripts/mutation/run-pilot.mjs --config=scripts/mutation/pilot-config.json --out=docs/reference/mutation-pilot-report.json",
+    "mutation:pilot": "npm run build && node scripts/mutation/run-pilot.mjs --config=scripts/mutation/pilot-config.json --out=docs/maintainers/mutation-pilot-report.json",
     "eval:ci": "node scripts/eval/run-eval.mjs --profile=ci",
     "eval:release": "node scripts/eval/run-eval.mjs --profile=release",
-    "eval:hard-gate": "node scripts/eval/run-eval.mjs --profile=hard-gate"
+    "eval:hard-gate": "node scripts/eval/run-eval.mjs --profile=hard-gate",
+    "docs:required": "node scripts/quality/doc-required.mjs",
+    "release:notes:dry-run": "node scripts/release/render-notes.mjs --dry-run",
+    "changelog:update:dry-run": "node scripts/release/update-changelog.mjs --dry-run"
   },
   "dependencies": {},
   "overrides": {