parsers : do not walk sub trees of removed nodes and make mutations during AST walks safe

packages/css-parser-algorithms/CHANGELOG.md

@@ -1,8 +1,11 @@
 # Changes to CSS Parser Algorithms
 
-### Unreleased (patch)
+### Unreleased (minor)
 
 - Small fixes in type definitions
+- Only `walk` child nodes if they are still part of the current AST tree [#1202](https://github.com/csstools/postcss-plugins/issues/1202)
+- Make `walk` methods safe for mutations [#1204](https://github.com/csstools/postcss-plugins/issues/1204)
+- Add a `forEach` method to `FunctionNode` and `SimpleBlockNode`
 
 ### 2.3.2
 

packages/css-parser-algorithms/dist/consume/consume-component-block-function.d.ts

@@ -7,40 +7,129 @@ export declare function consumeComponentValue(ctx: Context, tokens: Array<CSSTok
     advance: number;
     node: ComponentValue;
 };
-export declare class FunctionNode {
+declare abstract class ContainerNodeBaseClass {
+    /**
+     * The contents of the `Function` or `Simple Block`.
+     * This is a list of component values.
+     */
+    value: Array<ComponentValue>;
+    /**
+     * Retrieve the index of the given item in the current node.
+     * For most node types this will be trivially implemented as `this.value.indexOf(item)`.
+     */
+    indexOf(item: ComponentValue): number | string;
+    /**
+     * Retrieve the item at the given index in the current node.
+     * For most node types this will be trivially implemented as `this.value[index]`.
+     */
+    at(index: number | string): ComponentValue | undefined;
+    /**
+     * Iterates over each item in the `value` array of the current node.
+     *
+     * @param cb - The callback function to execute for each item.
+     * The function receives an object containing the current node (`node`), its parent (`parent`),
+     * and an optional `state` object.
+     * A second parameter is the index of the current node.
+     * The function can return `false` to stop the iteration.
+     *
+     * @param state - An optional state object that can be used to pass additional information to the callback function.
+     * The state object is cloned for each iteration. This means that changes to the state object are not reflected in the next iteration.
+     *
+     * @returns `false` if the iteration was halted, `undefined` otherwise.
+     *
+     * @template T - The type of the `state` object.
+     * @template U - The type of the current node.
+     */
+    forEach<T extends Record<string, unknown>, U extends ContainerNode>(this: U, cb: (entry: {
+        node: ComponentValue;
+        parent: ContainerNode;
+        state?: T;
+    }, index: number | string) => boolean | void, state?: T): false | undefined;
+    /**
+     * Walks the current node and all its children.
+     *
+     * @param cb - The callback function to execute for each item.
+     * The function receives an object containing the current node (`node`), its parent (`parent`),
+     * and an optional `state` object.
+     * A second parameter is the index of the current node.
+     * The function can return `false` to stop the iteration.
+     *
+     * @param state - An optional state object that can be used to pass additional information to the callback function.
+     * The state object is cloned for each iteration. This means that changes to the state object are not reflected in the next iteration.
+     * However changes are passed down to child node iterations.
+     *
+     * @returns `false` if the iteration was halted, `undefined` otherwise.
+     *
+     * @template T - The type of the `state` object.
+     * @template U - The type of the current node.
+     */
+    walk<T extends Record<string, unknown>, U extends ContainerNode>(this: U, cb: (entry: {
+        node: ComponentValue;
+        parent: ContainerNode;
+        state?: T;
+    }, index: number | string) => boolean | void, state?: T): false | undefined;
+}
+export declare class FunctionNode extends ContainerNodeBaseClass {
+    /**
+     * The node type
+     * Always `ComponentValueType.Function`
+     */
     type: ComponentValueType;
+    /**
+     * The token for the name of the function.
+     */
     name: TokenFunction;
+    /**
+     * The token for the closing parenthesis of the function.
+     * If the function is unclosed, this will be an EOF token.
+     */
     endToken: CSSToken;
-    value: Array<ComponentValue>;
     constructor(name: TokenFunction, endToken: CSSToken, value: Array<ComponentValue>);
+    /**
+     * Retrieve the name of the current Function.
+     * This is the parsed and unescaped name of the function.
+     */
     getName(): string;
     /**
      * Normalize the current Function:
      * - if the "endToken" is EOF, replace with a ")-token"
      */
     normalize(): void;
+    /**
+     * Retrieve the tokens for the current Function.
+     * This is the inverse of parsing from a list of tokens.
+     */
     tokens(): Array<CSSToken>;
+    /**
+     * Convert the current Function to a string.
+     * This is not a true serialization.
+     * It is purely a concatenation of the string representation of the tokens.
+     */
     toString(): string;
-    indexOf(item: ComponentValue): number | string;
-    at(index: number | string): ComponentValue | undefined;
-    walk<T extends Record<string, unknown>>(cb: (entry: {
-        node: ComponentValue;
-        parent: ContainerNode;
-        state?: T;
-    }, index: number | string) => boolean | void, state?: T): false | undefined;
+    /**
+     * A debug helper to convert the current object to a JSON representation.
+     * This is useful in asserts and to store large ASTs in files.
+     */
     toJSON(): unknown;
+    /**
+     * Check if the current object is a FunctionNode.
+     * This is a type guard to help with type narrowing.
+     */
     isFunctionNode(): this is FunctionNode;
+    /**
+     * Check if the given object is a FunctionNode.
+     * This is a type guard to help with type narrowing.
+     */
     static isFunctionNode(x: unknown): x is FunctionNode;
 }
 export declare function consumeFunction(ctx: Context, tokens: Array<CSSToken>): {
     advance: number;
     node: FunctionNode;
 };
-export declare class SimpleBlockNode {
+export declare class SimpleBlockNode extends ContainerNodeBaseClass {
     type: ComponentValueType;
     startToken: CSSToken;
     endToken: CSSToken;
-    value: Array<ComponentValue>;
     constructor(startToken: CSSToken, endToken: CSSToken, value: Array<ComponentValue>);
     /**
      * Normalize the current Simple Block:
@@ -51,11 +140,6 @@ export declare class SimpleBlockNode {
     toString(): string;
     indexOf(item: ComponentValue): number | string;
     at(index: number | string): ComponentValue | undefined;
-    walk<T extends Record<string, unknown>>(cb: (entry: {
-        node: ComponentValue;
-        parent: ContainerNode;
-        state?: T;
-    }, index: number | string) => boolean | void, state?: T): false | undefined;
     toJSON(): unknown;
     isSimpleBlockNode(): this is SimpleBlockNode;
     static isSimpleBlockNode(x: unknown): x is SimpleBlockNode;
@@ -116,3 +200,4 @@ export declare class TokenNode {
     isTokenNode(): this is TokenNode;
     static isTokenNode(x: unknown): x is TokenNode;
 }
+export {};

packages/css-parser-algorithms/dist/index.d.ts

@@ -5,6 +5,7 @@ export { parseCommaSeparatedListOfComponentValues } from './parse/parse-comma-se
 export { gatherNodeAncestry } from './util/node-ancestry';
 export { replaceComponentValues } from './util/replace-component-values';
 export { stringify } from './util/stringify';
+export { walkerIndexGenerator } from './util/walker-index-generator';
 export { ComponentValueType } from './util/component-value-type';
 export { isCommentNode, isFunctionNode, isSimpleBlockNode, isTokenNode, isWhitespaceNode, } from './util/type-predicates';
 export { sourceIndices } from './util/source-indices';

packages/css-parser-algorithms/dist/util/walker-index-generator.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Generate a function that finds the next element that should be visited when walking an AST.
+ * Rules :
+ * - the previous iteration is used as a reference, so any checks are relative to the start of the current iteration.
+ * - the next element always appears after the current index.
+ * - the next element always exists in the list.
+ * - replacing an element does not cause the replaced element to be visited.
+ * - removing an element does not cause elements to be skipped.
+ * - an element added later in the list will be visited.
+ */
+export declare function walkerIndexGenerator<T>(initialList: Array<T>): (list: Array<T>, child: T, index: number) => number;