@wordpress/eslint-plugin 24.3.1-next.v.202602271551.0 → 24.4.0

package/rules/data-no-store-string-literals.js

@@ -31,7 +31,7 @@ function arrayLast( array ) {
 function getReferences( context, specifiers ) {
 	const variables = specifiers.reduce(
 		( acc, specifier ) =>
-			acc.concat( context.getDeclaredVariables( specifier ) ),
+			acc.concat( context.sourceCode.getDeclaredVariables( specifier ) ),
 		[]
 	);
 	const references = variables.reduce(
@@ -58,7 +58,9 @@ function collectAllNodesFromCallbackFunctions( context, node ) {
 		( acc, { identifier: { parent } } ) =>
 			parent && parent.arguments && parent.arguments.length > 0
 				? acc.concat(
-						context.getDeclaredVariables( parent.arguments[ 0 ] )
+						context.sourceCode.getDeclaredVariables(
+							parent.arguments[ 0 ]
+						)
 				  )
 				: acc,
 		[]
@@ -153,9 +155,10 @@ function getFixes( fixer, context, callNode ) {
 		fixer.replaceText( callNode.arguments[ 0 ], variableName ),
 	];
 
-	const imports = context
-		.getAncestors()[ 0 ]
-		.body.filter( ( node ) => node.type === 'ImportDeclaration' );
+	const ancestors = context.sourceCode.getAncestors( callNode );
+	const imports = ancestors[ 0 ].body.filter(
+		( node ) => node.type === 'ImportDeclaration'
+	);
 	const packageImports = imports.filter(
 		( node ) => node.source.value === importName
 	);

package/rules/dependency-group.js

@@ -22,7 +22,8 @@ module.exports = {
 	},
 	create( context ) {
 		const mode = context.options[ 0 ] || 'always';
-		const comments = context.getSourceCode().getAllComments();
+		const sourceCode = context.sourceCode;
+		const comments = sourceCode.getAllComments();
 
 		/**
 		 * Locality classification of an import, one of "External",
@@ -194,9 +195,7 @@ module.exports = {
 										return null;
 									}
 
-									const text = context
-										.getSourceCode()
-										.getText();
+									const text = sourceCode.getText();
 
 									// Trim preceding and trailing newlines.
 									let [ start, end ] = comment.range;

package/rules/i18n-translator-comments.js

@@ -61,6 +61,7 @@ function extractTranslatorKeys( commentText ) {
 module.exports = {
 	meta: {
 		type: 'problem',
+		schema: [],
 		messages: {
 			missing:
 				'Translation function with placeholders is missing preceding translator comment',
@@ -71,6 +72,7 @@ module.exports = {
 		},
 	},
 	create( context ) {
+		const sourceCode = context.sourceCode;
 		return {
 			CallExpression( node ) {
 				const {
@@ -107,7 +109,7 @@ module.exports = {
 					return;
 				}
 
-				const comments = context.getCommentsBefore( node ).slice();
+				const comments = sourceCode.getCommentsBefore( node ).slice();
 
 				let parentNode = parent;
 
@@ -123,7 +125,9 @@ module.exports = {
 					parentNode.type !== 'Program' &&
 					Math.abs( parentNode.loc.start.line - currentLine ) <= 1
 				) {
-					comments.push( ...context.getCommentsBefore( parentNode ) );
+					comments.push(
+						...sourceCode.getCommentsBefore( parentNode )
+					);
 					parentNode = parentNode.parent;
 				}
 

package/rules/no-dom-globals-in-constructor.js

@@ -0,0 +1,17 @@
+/**
+ * Internal dependencies
+ */
+const { createDOMGlobalRule } = require( '../utils/dom-globals' );
+
+module.exports = createDOMGlobalRule( {
+	description: 'Disallow use of DOM globals in class constructors',
+	message:
+		"Use of DOM global '{{name}}' is forbidden in class constructors, consider moving this to componentDidMount() or equivalent for non React components",
+	test( scope ) {
+		if ( scope.block?.parent ) {
+			const { type, kind } = scope.block.parent;
+			return type === 'MethodDefinition' && kind === 'constructor';
+		}
+		return false;
+	},
+} );

package/rules/no-dom-globals-in-module-scope.js

@@ -0,0 +1,12 @@
+/**
+ * Internal dependencies
+ */
+const { createDOMGlobalRule } = require( '../utils/dom-globals' );
+
+module.exports = createDOMGlobalRule( {
+	description: 'Disallow use of DOM globals in module scope',
+	message: "Use of DOM global '{{name}}' is forbidden in module scope",
+	test( scope ) {
+		return scope.type === 'module' || scope.type === 'global';
+	},
+} );

package/rules/no-dom-globals-in-react-cc-render.js

@@ -0,0 +1,26 @@
+/**
+ * Internal dependencies
+ */
+const {
+	createDOMGlobalRule,
+	isReturnValueJSX,
+} = require( '../utils/dom-globals' );
+
+module.exports = createDOMGlobalRule( {
+	description:
+		'Disallow use of DOM globals in render() method of a React class component',
+	message:
+		"Use of DOM global '{{name}}' is forbidden in render(), consider moving this to componentDidMount()",
+	test( scope ) {
+		if ( scope.block?.parent ) {
+			const { type, kind, key } = scope.block.parent;
+			return (
+				type === 'MethodDefinition' &&
+				kind === 'method' &&
+				key.name === 'render' &&
+				isReturnValueJSX( scope )
+			);
+		}
+		return false;
+	},
+} );

package/rules/no-dom-globals-in-react-fc.js

@@ -0,0 +1,17 @@
+/**
+ * Internal dependencies
+ */
+const {
+	createDOMGlobalRule,
+	isReturnValueJSX,
+} = require( '../utils/dom-globals' );
+
+module.exports = createDOMGlobalRule( {
+	description:
+		'Disallow use of DOM globals in the render cycle of a React function component',
+	message:
+		"Use of DOM global '{{name}}' is forbidden in the render-cycle of a React FC, consider moving this inside useEffect()",
+	test( scope ) {
+		return isReturnValueJSX( scope );
+	},
+} );

package/rules/no-i18n-in-save.js

@@ -22,7 +22,7 @@ module.exports = {
 	},
 	create( context ) {
 		let saveFunctionDepth = 0;
-		const filename = context.getFilename();
+		const filename = context.filename;
 
 		// Skip deprecated files as they preserve old behavior including translation functions
 		const normalizedFilename = filename.replace( /\\/g, '/' );

package/rules/no-setting-ds-tokens.js

@@ -3,7 +3,7 @@ module.exports = /** @type {import('eslint').Rule.RuleModule} */ ( {
 		type: 'problem',
 		docs: {
 			description:
-				'Disallow setting any CSS custom property beginning with --wpds- in inline styles',
+				'Disallow setting any CSS custom property beginning with --wpds-',
 		},
 		schema: [],
 		messages: {
@@ -14,9 +14,7 @@ module.exports = /** @type {import('eslint').Rule.RuleModule} */ ( {
 	create( context ) {
 		return {
 			/** @param {import('estree').Property} node */
-			'JSXAttribute[name.name="style"] ObjectExpression > Property[key.value=/^--wpds-/]'(
-				node
-			) {
+			'ObjectExpression > Property[key.value=/^--wpds-/]'( node ) {
 				context.report( {
 					node: node.key,
 					messageId: 'disallowedSet',

package/rules/no-unknown-ds-tokens.js

@@ -4,35 +4,41 @@ const tokenList = tokenListModule.default || tokenListModule;
 const DS_TOKEN_PREFIX = 'wpds-';
 
 /**
- * Extracts all unique CSS custom properties (variables) from a given CSS value string,
- * including those in fallback positions, optionally filtering by a specific prefix.
+ * Single-pass extraction that finds all `--prefix-*` tokens in a CSS value
+ * string and classifies each occurrence as `var()`-wrapped or bare.
  *
- * @param {string} value       - The CSS value string to search for variables.
+ * @param {string} value       - The CSS value string to search.
  * @param {string} [prefix=''] - Optional prefix to filter variables (e.g., 'wpds-').
- * @return {Set<string>} A Set of unique matched CSS variable names (e.g., Set { '--wpds-token' }).
+ * @return {{ tokens: Set<string>, bare: Set<string> }}
+ *   `tokens` — every unique matched token;
+ *   `bare`   — the subset that appeared at least once without a `var()` wrapper.
  *
  * @example
- * extractCSSVariables(
- *   'border: 1px solid var(--wpds-border-color, var(--wpds-border-fallback)); ' +
- *   'color: var(--wpds-color-fg, black); ' +
- *   'background: var(--unrelated-bg);',
- *   'wpds'
+ * classifyTokens(
+ *   'var(--wpds-color-fg) --wpds-color-bg',
+ *   'wpds-'
  * );
- * // → Set { '--wpds-border-color', '--wpds-border-fallback', '--wpds-color-fg' }
+ * // → { tokens: Set {'--wpds-color-fg','--wpds-color-bg'},
+ * //     bare:   Set {'--wpds-color-bg'} }
  */
-function extractCSSVariables( value, prefix = '' ) {
-	const regex = /--[\w-]+/g;
-	const variables = new Set();
+function classifyTokens( value, prefix = '' ) {
+	const regex = new RegExp(
+		`(?:^|[^\\w])(var\\(\\s*)?(--${ prefix }[\\w-]+)`,
+		'g'
+	);
+	const tokens = new Set();
+	const bare = new Set();
 
 	let match;
 	while ( ( match = regex.exec( value ) ) !== null ) {
-		const variableName = match[ 0 ];
-		if ( variableName.startsWith( `--${ prefix }` ) ) {
-			variables.add( variableName );
+		const token = match[ 2 ];
+		tokens.add( token );
+		if ( ! match[ 1 ] ) {
+			bare.add( token );
 		}
 	}
 
-	return variables;
+	return { tokens, bare };
 }
 
 const knownTokens = new Set( tokenList );
@@ -50,6 +56,8 @@ module.exports = /** @type {import('eslint').Rule.RuleModule} */ ( {
 				'The following CSS variables are not valid Design System tokens: {{ tokenNames }}',
 			dynamicToken:
 				'Design System tokens must not be dynamically constructed, as they cannot be statically verified for correctness or processed automatically to inject fallbacks.',
+			bareToken:
+				'Design System tokens must be wrapped in `var()` for build-time fallback injection to work: {{ tokenNames }}',
 		},
 	},
 	create( context ) {
@@ -71,6 +79,7 @@ module.exports = /** @type {import('eslint').Rule.RuleModule} */ ( {
 			[ dynamicTemplateLiteralAST ]( node ) {
 				let hasDynamic = false;
 				const unknownTokens = [];
+				const bareTokens = [];
 
 				for ( const quasi of node.quasis ) {
 					const raw = quasi.value.raw;
@@ -84,7 +93,7 @@ module.exports = /** @type {import('eslint').Rule.RuleModule} */ ( {
 						hasDynamic = true;
 					}
 
-					const tokens = extractCSSVariables(
+					const { tokens, bare } = classifyTokens(
 						value,
 						DS_TOKEN_PREFIX
 					);
@@ -95,12 +104,15 @@ module.exports = /** @type {import('eslint').Rule.RuleModule} */ ( {
 						const endMatch = value.match( /(--([\w-]+))$/ );
 						if ( endMatch ) {
 							tokens.delete( endMatch[ 1 ] );
+							bare.delete( endMatch[ 1 ] );
 						}
 					}
 
 					for ( const token of tokens ) {
 						if ( ! knownTokens.has( token ) ) {
 							unknownTokens.push( token );
+						} else if ( bare.has( token ) ) {
+							bareTokens.push( token );
 						}
 					}
 				}
@@ -123,6 +135,18 @@ module.exports = /** @type {import('eslint').Rule.RuleModule} */ ( {
 						},
 					} );
 				}
+
+				if ( bareTokens.length > 0 ) {
+					context.report( {
+						node,
+						messageId: 'bareToken',
+						data: {
+							tokenNames: bareTokens
+								.map( ( token ) => `'${ token }'` )
+								.join( ', ' ),
+						},
+					} );
+				}
 			},
 			/** @param {import('estree').Literal | import('estree').TemplateElement} node */
 			[ staticTokensAST ]( node ) {
@@ -145,7 +169,7 @@ module.exports = /** @type {import('eslint').Rule.RuleModule} */ ( {
 					return;
 				}
 
-				const usedTokens = extractCSSVariables(
+				const { tokens: usedTokens, bare } = classifyTokens(
 					computedValue,
 					DS_TOKEN_PREFIX
 				);
@@ -164,6 +188,31 @@ module.exports = /** @type {import('eslint').Rule.RuleModule} */ ( {
 						},
 					} );
 				}
+
+				// Skip bare-token check for property keys
+				// (e.g. `{ '--wpds-token': value }` declaring a custom property).
+				const isPropertyKey =
+					node.parent?.type === 'Property' &&
+					node.parent.key === node;
+
+				if ( ! isPropertyKey ) {
+					const bareTokens = [ ...usedTokens ].filter(
+						( token ) =>
+							knownTokens.has( token ) && bare.has( token )
+					);
+
+					if ( bareTokens.length > 0 ) {
+						context.report( {
+							node,
+							messageId: 'bareToken',
+							data: {
+								tokenNames: bareTokens
+									.map( ( token ) => `'${ token }'` )
+									.join( ', ' ),
+							},
+						} );
+					}
+				}
 			},
 		};
 	},

package/rules/no-unused-vars-before-return.js

@@ -11,15 +11,16 @@
 const FUNCTION_SCOPE_JSX_IDENTIFIERS = new WeakMap();
 
 /**
- * Returns the closest function scope for the current ESLint context object, or
- * undefined if it cannot be determined.
+ * Returns the closest function scope for the given node, or undefined if it
+ * cannot be determined.
  *
  * @param {ESLintRuleContext} context ESLint context object.
+ * @param {ESTreeNode}        node    Current AST node.
  *
  * @return {ESLintScope|undefined} Function scope, if known.
  */
-function getClosestFunctionScope( context ) {
-	let functionScope = context.getScope();
+function getClosestFunctionScope( context, node ) {
+	let functionScope = context.sourceCode.getScope( node );
 	while ( functionScope.type !== 'function' && functionScope.upper ) {
 		functionScope = functionScope.upper;
 	}
@@ -73,7 +74,7 @@ module.exports = /** @type {import('eslint').Rule} */ ( {
 				// identifiers. Account for this by visiting JSX identifiers
 				// first, and tracking them in a map per function scope, which
 				// is later merged with the known variable references.
-				const functionScope = getClosestFunctionScope( context );
+				const functionScope = getClosestFunctionScope( context, node );
 				if ( ! functionScope ) {
 					return;
 				}
@@ -88,7 +89,7 @@ module.exports = /** @type {import('eslint').Rule} */ ( {
 				FUNCTION_SCOPE_JSX_IDENTIFIERS.get( functionScope ).add( node );
 			},
 			'ReturnStatement:exit'( node ) {
-				const functionScope = getClosestFunctionScope( context );
+				const functionScope = getClosestFunctionScope( context, node );
 				if ( ! functionScope ) {
 					return;
 				}

package/rules/react-no-unsafe-timeout.js

@@ -71,7 +71,7 @@ module.exports = {
 				// Consider whether `setTimeout` is a reference to the global
 				// by checking references to see if `setTimeout` resolves to a
 				// variable in scope.
-				const { references } = context.getScope();
+				const { references } = context.sourceCode.getScope( node );
 				const hasResolvedReference = references.some(
 					( reference ) =>
 						reference.identifier.name === 'setTimeout' &&

package/rules/use-recommended-components.js

@@ -0,0 +1,114 @@
+/**
+ * Allowlist: only the listed components are permitted from these packages.
+ * Any other named import will be flagged with the package's message.
+ *
+ * `message` supports `{{ name }}` and `{{ source }}` placeholders.
+ *
+ * @type {Record<string, { allowed: string[], message?: string }>}
+ */
+const ALLOWLIST = {
+	'@wordpress/ui': {
+		allowed: [ 'Badge', 'Stack' ],
+		message:
+			'`{{ name }}` from `{{ source }}` is not yet recommended for use in a WordPress environment.',
+	},
+};
+
+/**
+ * Denylist: the listed components are flagged with a message pointing
+ * to a recommended alternative.
+ *
+ * Messages support `{{ name }}` and `{{ source }}` placeholders.
+ *
+ * @type {Record<string, Record<string, string>>}
+ */
+const DENYLIST = {
+	'@wordpress/components': {
+		__experimentalZStack:
+			'{{ name }} is planned for deprecation. Write your own CSS instead.',
+	},
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description:
+				'Encourage the use of recommended UI components in a WordPress environment.',
+			url: 'https://github.com/WordPress/gutenberg/blob/HEAD/packages/eslint-plugin/docs/rules/use-recommended-components.md',
+		},
+		schema: [],
+	},
+	create( context ) {
+		return {
+			/** @param {import('estree').ImportDeclaration} node */
+			ImportDeclaration( node ) {
+				if ( typeof node.source.value !== 'string' ) {
+					return;
+				}
+
+				const source = node.source.value;
+
+				const allowlistEntry = ALLOWLIST[ source ];
+				const denylistEntry = DENYLIST[ source ];
+
+				if ( ! allowlistEntry && ! denylistEntry ) {
+					return;
+				}
+
+				node.specifiers.forEach( ( specifier ) => {
+					if ( specifier.type !== 'ImportSpecifier' ) {
+						return;
+					}
+
+					const name = specifier.imported.name;
+
+					if (
+						allowlistEntry &&
+						! allowlistEntry.allowed.includes( name )
+					) {
+						context.report( {
+							node: specifier,
+							message: resolveMessage(
+								allowlistEntry.message,
+								name,
+								source
+							),
+						} );
+					}
+
+					if ( denylistEntry?.hasOwnProperty( name ) ) {
+						context.report( {
+							node: specifier,
+							message: resolveMessage(
+								denylistEntry[ name ],
+								name,
+								source
+							),
+						} );
+					}
+				} );
+			},
+		};
+	},
+};
+
+/**
+ * @param {string|undefined} template
+ * @param {string}           name
+ * @param {string}           source
+ * @return {string} Resolved message string.
+ */
+function resolveMessage( template, name, source ) {
+	if ( ! template ) {
+		return `\`${ name }\` from \`${ source }\` is not recommended.`;
+	}
+	return template
+		.replace( /\{\{\s*name\s*\}\}/g, name )
+		.replace( /\{\{\s*source\s*\}\}/g, source );
+}
+
+module.exports = rule;
+module.exports.ALLOWLIST = ALLOWLIST;
+module.exports.DENYLIST = DENYLIST;

package/utils/dom-globals.js

@@ -0,0 +1,156 @@
+/**
+ * Shared utilities for SSR-safety rules that prevent DOM global usage in
+ * unsafe contexts.
+ *
+ * These rules replace the unmaintained `eslint-plugin-ssr-friendly` package.
+ */
+
+const { browser: browserGlobals, node: nodeGlobals } = require( 'globals' );
+
+/**
+ * Returns true if the given name is a browser-only DOM global (exists in
+ * browser globals but not in node globals).
+ *
+ * @param {string} name Identifier name to check.
+ * @return {boolean} Whether the name is a DOM-only global.
+ */
+function isDOMGlobal( name ) {
+	return name in browserGlobals && ! ( name in nodeGlobals );
+}
+
+/**
+ * Returns true if the given scope's block returns JSX (heuristic for
+ * detecting React render functions).
+ *
+ * @param {import('eslint').Scope.Scope} scope Scope to check.
+ * @return {boolean} Whether the scope returns JSX.
+ */
+function isReturnValueJSX( scope ) {
+	if ( scope.type !== 'function' ) {
+		return false;
+	}
+
+	const { block } = scope;
+
+	// Concise arrow function: const C = () => <div />
+	if (
+		block.type === 'ArrowFunctionExpression' &&
+		block.body.type !== 'BlockStatement'
+	) {
+		return (
+			block.body.type === 'JSXElement' ||
+			block.body.type === 'JSXFragment'
+		);
+	}
+
+	const body = block?.body?.body;
+	if ( ! body || typeof body.find !== 'function' ) {
+		return false;
+	}
+
+	return body.some(
+		( statement ) =>
+			statement?.type === 'ReturnStatement' &&
+			statement.argument &&
+			( statement.argument.type === 'JSXElement' ||
+				statement.argument.type === 'JSXFragment' )
+	);
+}
+
+/**
+ * Returns true if the reference's identifier should be skipped from
+ * reporting. Allows `typeof <global>` checks and TypeScript type references.
+ *
+ * @param {import('eslint').Scope.Reference} reference Variable reference.
+ * @return {boolean} Whether the reference should be skipped.
+ */
+function shouldSkipReference( reference ) {
+	const { parent } = reference.identifier;
+	return (
+		( parent.type === 'UnaryExpression' && parent.operator === 'typeof' ) ||
+		parent.type === 'TSTypeReference' ||
+		parent.type === 'TSInterfaceHeritage' ||
+		parent.type === 'TSTypeQuery'
+	);
+}
+
+/**
+ * Creates an ESLint rule that reports DOM global usage based on a scope
+ * predicate.
+ *
+ * @param {Object}                                           options             Rule options.
+ * @param {string}                                           options.description Rule description.
+ * @param {string}                                           options.message     Error message template (use {{name}} for the global name).
+ * @param {(scope: import('eslint').Scope.Scope) => boolean} options.test        Predicate that receives the reference's scope and
+ *                                                                               returns true if usage should be reported.
+ * @return {import('eslint').Rule.RuleModule} ESLint rule module.
+ */
+function createDOMGlobalRule( { description, message, test } ) {
+	return {
+		meta: {
+			type: 'problem',
+			schema: [],
+			docs: {
+				description,
+			},
+			messages: {
+				defaultMessage: message,
+			},
+		},
+		create( context ) {
+			return {
+				Program( node ) {
+					const scope = context.sourceCode.getScope( node );
+
+					// Report variables declared elsewhere (e.g. variables
+					// defined as "global" by eslint).
+					for ( const variable of scope.variables ) {
+						if (
+							variable.defs.length === 0 &&
+							isDOMGlobal( variable.name )
+						) {
+							for ( const reference of variable.references ) {
+								if (
+									! shouldSkipReference( reference ) &&
+									test( reference.from )
+								) {
+									context.report( {
+										node: reference.identifier,
+										messageId: 'defaultMessage',
+										data: {
+											name: reference.identifier.name,
+										},
+									} );
+								}
+							}
+						}
+					}
+
+					// Report variables not declared at all.
+					for ( const reference of scope.through ) {
+						if (
+							isDOMGlobal( reference.identifier.name ) &&
+							! shouldSkipReference( reference ) &&
+							test( reference.from )
+						) {
+							context.report( {
+								node: reference.identifier,
+								messageId: 'defaultMessage',
+								data: {
+									name: reference.identifier.name,
+								},
+							} );
+						}
+					}
+				},
+			};
+		},
+	};
+}
+
+module.exports = {
+	isDOMGlobal,
+	isReturnValueJSX,
+	shouldSkipReference,
+	createDOMGlobalRule,
+};