Merge remote-tracking branch 'origin/main' into fix-types--persistent…

…-puffin-26bee81a68

.github/bin/generate-docs/install.mjs

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { parallelBuildsNotice } from './parallel-builds-notice.mjs';
 
 const template = fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), './install-template.md'), 'utf8');
 const packageJSONInfo = JSON.parse(fs.readFileSync('./package.json', 'utf8'));
@@ -12,7 +13,7 @@ installDoc = installDoc.replaceAll('<packageName>', packageJSONInfo.name);
 installDoc = installDoc.replaceAll('<packagePath>', path.join(path.basename(path.dirname(process.cwd())), path.basename(process.cwd())));
 
 if (packageJSONInfo?.csstools?.assumesToProcessBundledCSS) {
-	installDoc = installDoc.replaceAll('<parallelBuildsNotice>', `⚠️ [${packageJSONInfo.csstools.humanReadableName}] assumes to process your complete CSS bundle.<br>If your build tool processes files individually or in parallel the output will be incorrect.<br>Using [\`@csstools/postcss-bundler\`](https://github.com/csstools/postcss-plugins/tree/main/plugin-packs/postcss-bundler) and \`@import\` statements is one way to make sure your CSS is bundled before it is processed by this plugin.\n`);
+	installDoc = installDoc.replaceAll('<parallelBuildsNotice>', parallelBuildsNotice(packageJSONInfo.csstools.humanReadableName));
 	installDoc = installDoc.replaceAll('<otherPluginsInWebpack>', `["@csstools/postcss-bundler"]`);
 	// <parallelBuildsNotice>
 } else {

.github/bin/generate-docs/parallel-builds-notice.mjs

@@ -0,0 +1,3 @@
+export function parallelBuildsNotice(label) {
+	return `> [!IMPORTANT]\n> [${label}] assumes to process your complete CSS bundle.<br>If your build tool processes files individually or processes files in parallel the output will be incorrect.<br>Using [\`@csstools/postcss-bundler\`](https://github.com/csstools/postcss-plugins/tree/main/plugin-packs/postcss-bundler) and \`@import\` statements is one way to make sure your CSS is bundled before it is processed by this plugin.\n`;
+}

.github/bin/generate-docs/readme.mjs

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { parallelBuildsNotice } from './parallel-builds-notice.mjs';
 
 const template = fs.readFileSync(path.join('docs', './README.md'), 'utf8');
 const corsTemplate = fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), './cors-template.md'), 'utf8');
@@ -33,6 +34,7 @@ readmeDoc = readmeDoc.replace(`<!-- Available Variables: -->
 <!-- <envSupport> -->
 <!-- <corsWarning> -->
 <!-- <linkList> -->
+<!-- <parallelBuildsNotice> -->
 <!-- to generate : npm run docs -->
 
 `, '');
@@ -110,6 +112,12 @@ readmeDoc = readmeDoc.replaceAll('<packageVersion>', packageJSONInfo.version);
 readmeDoc = readmeDoc.replaceAll('<packagePath>', path.join(path.basename(path.dirname(process.cwd())), path.basename(process.cwd())));
 readmeDoc = readmeDoc.replaceAll('<specUrl>', packageJSONInfo.csstools.specUrl);
 
+if (packageJSONInfo?.csstools?.assumesToProcessBundledCSS) {
+	readmeDoc = readmeDoc.replaceAll('<parallelBuildsNotice>', parallelBuildsNotice(packageJSONInfo.csstools.humanReadableName));
+} else {
+	readmeDoc = readmeDoc.replaceAll('<parallelBuildsNotice>', ``);
+}
+
 for (const exampleFilePath of exampleFilePaths) {
 	readmeDoc = readmeDoc.replaceAll(
 		`<${path.relative(path.join('test', 'examples'), exampleFilePath)}>`,

experimental/postcss-gradient-stop-increments/docs/README.md

@@ -12,6 +12,7 @@
 <!-- <envSupport> -->
 <!-- <corsWarning> -->
 <!-- <linkList> -->
+<!-- <parallelBuildsNotice> -->
 <!-- to generate : npm run docs -->
 
 <header>

packages/css-parser-algorithms/CHANGELOG.md

@@ -1,8 +1,11 @@
 # Changes to CSS Parser Algorithms
 
-### Unreleased (patch)
+### Unreleased (minor)
 
 - Fix 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/index.d.ts

@@ -28,29 +28,120 @@ export declare enum ComponentValueType {
 
 export declare type ContainerNode = FunctionNode | SimpleBlockNode;
 
-export declare class FunctionNode {
+export 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;
 }
 
@@ -85,11 +176,10 @@ export declare function parseListOfComponentValues(tokens: Array<CSSToken>, opti
 
 export declare function replaceComponentValues(componentValuesList: Array<Array<ComponentValue>>, replaceWith: (componentValue: ComponentValue) => ComponentValue | void): ComponentValue[][];
 
-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:
@@ -100,11 +190,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;
@@ -135,6 +220,18 @@ export declare class TokenNode {
     static isTokenNode(x: unknown): x is TokenNode;
 }
 
+/**
+ * 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;
+
 export declare class WhitespaceNode {
     type: ComponentValueType;
     value: Array<CSSToken>;