@wordpress/eslint-plugin 24.4.1-next.v.202603161435.0 → 24.5.0

package/rules/no-unmerged-classname.js

@@ -0,0 +1,107 @@
+/** @type {import('eslint').Rule.RuleModule} */
+module.exports = {
+	meta: {
+		type: 'problem',
+		schema: [],
+		messages: {
+			noUnmergedClassname:
+				'The `className` prop should be destructured from props and merged into the `className` attribute to ensure it is forwarded to the underlying element.',
+		},
+	},
+	create( context ) {
+		return {
+			JSXOpeningElement( node ) {
+				const classNameAttr = node.attributes.find(
+					( attr ) =>
+						attr.type === 'JSXAttribute' &&
+						attr.name?.name === 'className'
+				);
+
+				if ( ! classNameAttr ) {
+					return;
+				}
+
+				const hasSpread = node.attributes.some(
+					( attr ) => attr.type === 'JSXSpreadAttribute'
+				);
+
+				if ( ! hasSpread ) {
+					return;
+				}
+
+				const func = getEnclosingFunction( node );
+				if ( ! func ) {
+					return;
+				}
+
+				const propsParam = func.params[ 0 ];
+				if ( ! propsParam ) {
+					return;
+				}
+
+				// Props passed as a plain identifier (e.g. `function Foo( props )`)
+				// and spread directly — className can never be merged.
+				if ( propsParam.type === 'Identifier' ) {
+					const spreadMatchesParam = node.attributes.some(
+						( attr ) =>
+							attr.type === 'JSXSpreadAttribute' &&
+							attr.argument.type === 'Identifier' &&
+							attr.argument.name === propsParam.name
+					);
+					if ( spreadMatchesParam ) {
+						context.report( {
+							node: classNameAttr,
+							messageId: 'noUnmergedClassname',
+						} );
+					}
+					return;
+				}
+
+				if ( propsParam.type !== 'ObjectPattern' ) {
+					return;
+				}
+
+				const hasRestElement = propsParam.properties.some(
+					( prop ) => prop.type === 'RestElement'
+				);
+				if ( ! hasRestElement ) {
+					return;
+				}
+
+				const classNameDestructured = propsParam.properties.some(
+					( prop ) =>
+						prop.type === 'Property' &&
+						prop.key?.name === 'className'
+				);
+
+				if ( ! classNameDestructured ) {
+					context.report( {
+						node: classNameAttr,
+						messageId: 'noUnmergedClassname',
+					} );
+				}
+			},
+		};
+	},
+};
+
+/**
+ * Walk up the AST to find the enclosing function node.
+ *
+ * @param {import('estree').Node} node
+ * @return {import('estree').Function | null} The enclosing function, or null.
+ */
+function getEnclosingFunction( node ) {
+	let current = node;
+	while ( current.parent ) {
+		current = current.parent;
+		if (
+			current.type === 'FunctionDeclaration' ||
+			current.type === 'FunctionExpression' ||
+			current.type === 'ArrowFunctionExpression'
+		) {
+			return current;
+		}
+	}
+	return null;
+}

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/utils/dom-globals.js

@@ -0,0 +1,157 @@
+/**
+ * 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' ||
+		parent.type === 'TSQualifiedName'
+	);
+}
+
+/**
+ * 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,
+};