@eslint/css-tree 3.2.0 → 3.3.0

package/dist/version.cjs

@@ -1 +1 @@
-module.exports = "3.2.0";
+module.exports = "3.3.0";

package/dist/version.js

@@ -1 +1 @@
-export const version = "3.2.0";
+export const version = "3.3.0";

package/lib/index.d.ts

@@ -996,6 +996,121 @@ export const tokenNames: ReadonlyArray<string>;
  */
 export type CssTokenizerCallback = (token: number, start: number, end: number) => void;
 
+/**
+ * Represents the API for iterating over tokens in a CSS source string.
+ */
+export interface TokenIterateAPI {
+    /**
+     * The name of the file being parsed.
+     */
+    filename: string;
+
+    /**
+     * The CSS source string being tokenized.
+     */
+    source: string;
+
+    /**
+     * The total number of tokens in the stream.
+     */
+    tokenCount: number;
+
+    /**
+     * Gets the type of the token at the specified index.
+     *
+     * @param index - The index of the token.
+     * @returns The numeric type of the token.
+     */
+    getTokenType(index: number): number;
+
+    /**
+     * Gets the name of the token type at the specified index.
+     *
+     * @param index - The index of the token.
+     * @returns The string name of the token type.
+     */
+    getTokenTypeName(index: number): string;
+
+    /**
+     * Gets the start position of the token at the specified index.
+     *
+     * @param index - The index of the token.
+     * @returns The starting character position of the token.
+     */
+    getTokenStart(index: number): number;
+
+    /**
+     * Gets the end position of the token at the specified index.
+     *
+     * @param index - The index of the token.
+     * @returns The ending character position of the token.
+     */
+    getTokenEnd(index: number): number;
+
+    /**
+     * Gets the value of the token at the specified index.
+     *
+     * @param index - The index of the token.
+     * @returns The string value of the token.
+     */
+    getTokenValue(index: number): string;
+
+    /**
+     * Gets a substring from the source string.
+     *
+     * @param start - The starting index.
+     * @param end - The ending index.
+     * @returns The substring from the source.
+     */
+    substring(start: number, end: number): string;
+
+    /**
+     * A Uint32Array containing balance information for tokens.
+     */
+    balance: Uint32Array;
+
+    /**
+     * Checks if a token type represents a block opener.
+     *
+     * @param type - The token type to check.
+     * @returns True if the token type is a block opener.
+     */
+    isBlockOpenerTokenType(type: number): boolean;
+
+    /**
+     * Checks if a token type represents a block closer.
+     *
+     * @param type - The token type to check.
+     * @returns True if the token type is a block closer.
+     */
+    isBlockCloserTokenType(type: number): boolean;
+
+    /**
+     * Gets the index of the matching pair token for a block token.
+     *
+     * @param index - The index of the block token.
+     * @returns The index of the matching pair token.
+     */
+    getBlockTokenPairIndex(index: number): number;
+
+    /**
+     * Gets the location information for a position in the source.
+     *
+     * @param offset - The character offset in the source.
+     * @returns The location information.
+     */
+    getLocation(offset: number): CssLocation;
+
+    /**
+     * Gets the location range information for a range in the source.
+     *
+     * @param start - The starting offset.
+     * @param end - The ending offset.
+     * @returns The location range information.
+     */
+    getRangeLocation(start: number, end: number): CssLocationRange;
+}
+
 /**
  * A function used to tokenize CSS source code.
  *
@@ -1306,6 +1421,16 @@ export type OnParseCommentCallback = (value: string, loc: CssLocationRange) => v
  */
 export type OnParseErrorCallback = (error: SyntaxParseError, fallbackNode: CssNode) => void;
 
+/**
+ * A callback function invoked for each token encountered during parsing.
+ *
+ * @param token - The numeric type of the token.
+ * @param start - The starting index of the token in the source string.
+ * @param end - The ending index (exclusive) of the token in the source string.
+ * @param index - The index of the token in the stream.
+ */
+export type OnTokenCallback = (this: TokenIterateAPI, token: number, start: number, end: number, index: number) => void;
+
 /**
  * Options for controlling the behavior of the CSS parser.
  */
@@ -1335,6 +1460,11 @@ export interface ParseOptions {
      */
     onParseError?: OnParseErrorCallback;
 
+    /**
+     * A callback function invoked for each token encountered during parsing.
+     */
+    onToken?: OnTokenCallback;
+
     /**
      * The name of the file being parsed, used for error reporting.
      */
@@ -1378,12 +1508,28 @@ export interface ParseOptions {
 
 /**
  * A function that parses a CSS string into an abstract syntax tree (AST).
- *
- * @param source - The CSS source string to parse.
- * @param options - Optional configuration for the parser.
- * @returns The parsed CSS as a `CssNode`.
  */
-export type ParseFunction = (source: string, options?: ParseOptions) => CssNode;
+export interface ParseFunction {
+
+    /**
+     * Parses a CSS source string into an abstract syntax tree (AST).
+     * @param source - The CSS source string to parse.
+     * @param options - Optional configuration for the parser.
+     * @returns The parsed CSS as a `CssNode`.
+     * @throws {CSSSyntaxError} If a parsing error occurs, this error will be thrown.
+     */
+    (source: string, options?: ParseOptions): CssNode;
+
+    /**
+     * The error class used for parsing errors.
+     */
+    SyntaxError: typeof CSSSyntaxError;
+
+    /**
+     * The configuration used by the parser.
+     */
+    config: ParseConfig;
+}
 
 /**
  * Parses a CSS string into an abstract syntax tree (AST).
@@ -2120,6 +2266,59 @@ export const url: {
 // https://github.com/csstree/csstree/blob/master/lib/lexer/Lexer.js
 // ----------------------------------------------------------
 
+/**
+ * Represents a syntax error while parsing CSS code. In the actual code,
+ * this is called `SyntaxError`, but that clashes with the global `SyntaxError` class.
+ * This isn't exported separately but rather as a member of the `parse` function.
+ */
+declare class CSSSyntaxError extends SyntaxError {
+
+    /**
+     * Creates a new instance
+     * @param message The error message describing the syntax error.
+     * @param source The source code where the error occurred.
+     * @param offset The character offset in the source code where the error occurred.
+     * @param line The line number (1-indexed) in the source code where the error occurred.
+     * @param column The column number (1-indexed) in the source code where the error occurred.
+     * @param baseLine The base line number (1-indexed) for the error, used for relative positioning.
+     * @param baseColumn The base column number (1-indexed) for the error, used for relative positioning.
+     */
+    constructor(message: string, source: string, offset: number, line: number, column: number, baseLine?: number, baseColumn?: number);
+
+    /**
+     * The source code where the error occurred.
+     */
+    source: string;
+
+    /**
+     * The character offset in the source code where the error occurred.
+     */
+    offset: number;
+
+    /**
+     * The line number (1-indexed) in the source code where the error occurred.
+     */
+    line: number;
+
+    /**
+     * The column number (1-indexed) in the source code where the error occurred.
+     */
+    column: number;
+
+    /**
+     * The source code fragment around the error, including a specified number of extra lines.
+     * @param extraLines The number of extra lines to include in the fragment.
+     * @return A string containing the source code fragment around the error.
+     * This fragment includes the error line and the specified number of lines before and after it.
+     */
+    sourceFragment(extraLines: number): string;
+
+    /**
+     * The error message formatted with the source fragment.
+     */
+    readonly formattedMessage: string;
+}
+
 /**
  * Represents an error that occurs during the syntax matching process.
  * Extends the standard `SyntaxError` with additional properties specific to CSS parsing.

package/lib/lexer/Lexer.js

@@ -63,6 +63,16 @@ function syntaxHasTopLevelCommaMultiplier(syntax) {
     );
 }
 
+function valueHasEnv(tokens) {
+    for (let i = 0; i < tokens.length; i++) {
+        if (tokens[i].value.toLowerCase() === 'env(') {
+            return true;
+        }
+    }
+
+    return false;
+}
+
 function buildMatchResult(matched, error, iterations) {
     return {
         matched,
@@ -80,6 +90,10 @@ function matchSyntax(lexer, syntax, value, useCssWideKeywords) {
         return buildMatchResult(null, new Error('Matching for a tree with var() is not supported'));
     }
 
+    if (valueHasEnv(tokens)) {
+        return buildMatchResult(null, new Error('Matching for a tree with env() is not supported'));
+    }
+
     if (useCssWideKeywords) {
         result = matchAsTree(tokens, lexer.cssWideKeywordsSyntax, lexer);
     }
@@ -356,8 +370,10 @@ export class Lexer {
         return this.matchProperty(node.property, node.value);
     }
     matchProperty(propertyName, value) {
-        // don't match syntax for a custom property at the moment
-        if (names.property(propertyName).custom) {
+        if (
+            !this.getProperty(propertyName) &&
+            names.property(propertyName).custom
+        ) {
             return buildMatchResult(null, new Error('Lexer matching doesn\'t applicable for custom properties'));
         }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eslint/css-tree",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "A tool set for CSS: fast detailed parser (CSS → AST), walker (AST traversal), generator (AST → CSS) and lexer (validation and matching) based on specs and browser implementations",
   "author": "Roman Dvornov <rdvornov@gmail.com> (https://github.com/lahmatiy)",
   "license": "MIT",