@wordpress/eslint-plugin 25.0.1-next.v.202604201441.0 → 25.1.0

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

@@ -1,3 +1,19 @@
+const {
+	DS_TOKEN_PREFIX,
+	collectTokenOccurrences,
+	getStaticNodeValue,
+	wpdsTokensRegex,
+} = require( '../utils/ds-token-utils' );
+
+const wpdsDeclarationRegex = new RegExp(
+	`(?:^|[^\\w])--${ DS_TOKEN_PREFIX }[\\w-]+\\s*:`,
+	'i'
+);
+const dynamicDeclarationStartRegex = new RegExp(
+	`--${ DS_TOKEN_PREFIX }[\\w-]*$`
+);
+const dynamicDeclarationEndRegex = /^[\w-]*\s*:/;
+
 module.exports = /** @type {import('eslint').Rule.RuleModule} */ ( {
 	meta: {
 		type: 'problem',
@@ -12,6 +28,9 @@ module.exports = /** @type {import('eslint').Rule.RuleModule} */ ( {
 		},
 	},
 	create( context ) {
+		const staticDeclarationAST = `:matches(Literal[value=${ wpdsDeclarationRegex }], TemplateLiteral[expressions.length=0] TemplateElement[value.raw=${ wpdsDeclarationRegex }])`;
+		const dynamicTemplateLiteralAST = `TemplateLiteral[expressions.length>0]:has(TemplateElement[value.raw=${ wpdsTokensRegex }])`;
+
 		return {
 			/** @param {import('estree').Property} node */
 			'ObjectExpression > Property[key.value=/^--wpds-/]'( node ) {
@@ -20,6 +39,44 @@ module.exports = /** @type {import('eslint').Rule.RuleModule} */ ( {
 					messageId: 'disallowedSet',
 				} );
 			},
+			/** @param {import('estree').Literal | import('estree').TemplateElement} node */
+			[ staticDeclarationAST ]( node ) {
+				context.report( {
+					node,
+					messageId: 'disallowedSet',
+				} );
+			},
+			/** @param {import('estree').TemplateLiteral} node */
+			[ dynamicTemplateLiteralAST ]( node ) {
+				for ( let index = 0; index < node.quasis.length; index++ ) {
+					const quasi = node.quasis[ index ];
+					const value = getStaticNodeValue( quasi );
+					const nextValue = node.quasis[ index + 1 ]
+						? getStaticNodeValue( node.quasis[ index + 1 ] )
+						: undefined;
+
+					if ( ! value ) {
+						continue;
+					}
+					const hasStaticDeclaration = collectTokenOccurrences(
+						value,
+						DS_TOKEN_PREFIX
+					).some( ( { declaration } ) => declaration );
+					const hasSplitDeclaration =
+						! quasi.tail &&
+						dynamicDeclarationStartRegex.test( value ) &&
+						nextValue &&
+						dynamicDeclarationEndRegex.test( nextValue );
+
+					if ( hasStaticDeclaration || hasSplitDeclaration ) {
+						context.report( {
+							node,
+							messageId: 'disallowedSet',
+						} );
+						return;
+					}
+				}
+			},
 		};
 	},
 } );

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

@@ -1,48 +1,69 @@
 const tokenListModule = require( '@wordpress/theme/design-tokens.js' );
 const tokenList = tokenListModule.default || tokenListModule;
 
-const DS_TOKEN_PREFIX = 'wpds-';
+const {
+	DS_TOKEN_PREFIX,
+	collectTokenOccurrences,
+	getStaticNodeValue,
+	wpdsTokensRegex,
+} = require( '../utils/ds-token-utils' );
+
+const knownTokens = new Set( tokenList );
 
 /**
- * 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.
- * @param {string} [prefix=''] - Optional prefix to filter variables (e.g., 'wpds-').
- * @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
- * classifyTokens(
- *   'var(--wpds-color-fg) --wpds-color-bg',
- *   'wpds-'
- * );
- * // → { tokens: Set {'--wpds-color-fg','--wpds-color-bg'},
- * //     bare:   Set {'--wpds-color-bg'} }
+ * @param {Array<{ token: string, bare: boolean, declaration: boolean }>} occurrences
+ * @param {{ includeBareTokens?: boolean }}                               [options]
  */
-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 token = match[ 2 ];
-		tokens.add( token );
-		if ( ! match[ 1 ] ) {
-			bare.add( token );
+function getInvalidTokenNames(
+	occurrences,
+	{ includeBareTokens = true } = {}
+) {
+	const unknownTokens = new Set();
+	const bareTokens = new Set();
+
+	for ( const { token, bare, declaration } of occurrences ) {
+		if ( ! knownTokens.has( token ) ) {
+			unknownTokens.add( token );
+			continue;
+		}
+
+		if ( includeBareTokens && bare && ! declaration ) {
+			bareTokens.add( token );
 		}
 	}
 
-	return { tokens, bare };
+	return {
+		unknownTokens: [ ...unknownTokens ],
+		bareTokens: [ ...bareTokens ],
+	};
 }
 
-const knownTokens = new Set( tokenList );
-const wpdsTokensRegex = new RegExp( `(?:^|[^\\w])--${ DS_TOKEN_PREFIX }`, 'i' );
+/**
+ * @param {string[]} tokenNames
+ */
+function formatTokenNames( tokenNames ) {
+	return tokenNames.map( ( token ) => `'${ token }'` ).join( ', ' );
+}
+
+/**
+ * @param {import('eslint').Rule.RuleContext} context
+ * @param {import('estree').Node}             node
+ * @param {'onlyKnownTokens' | 'bareToken'}   messageId
+ * @param {string[]}                          tokenNames
+ */
+function reportTokenNames( context, node, messageId, tokenNames ) {
+	if ( tokenNames.length === 0 ) {
+		return;
+	}
+
+	context.report( {
+		node,
+		messageId,
+		data: {
+			tokenNames: formatTokenNames( tokenNames ),
+		},
+	} );
+}
 
 module.exports = /** @type {import('eslint').Rule.RuleModule} */ ( {
 	meta: {
@@ -78,8 +99,7 @@ module.exports = /** @type {import('eslint').Rule.RuleModule} */ ( {
 			 */
 			[ dynamicTemplateLiteralAST ]( node ) {
 				let hasDynamic = false;
-				const unknownTokens = [];
-				const bareTokens = [];
+				const occurrences = [];
 
 				for ( const quasi of node.quasis ) {
 					const raw = quasi.value.raw;
@@ -93,30 +113,26 @@ module.exports = /** @type {import('eslint').Rule.RuleModule} */ ( {
 						hasDynamic = true;
 					}
 
-					const { tokens, bare } = classifyTokens(
+					let quasiOccurrences = collectTokenOccurrences(
 						value,
 						DS_TOKEN_PREFIX
 					);
 
-					// Remove the trailing incomplete token — it's the one
-					// being dynamically constructed by the next expression.
 					if ( isFollowedByExpression ) {
 						const endMatch = value.match( /(--([\w-]+))$/ );
 						if ( endMatch ) {
-							tokens.delete( endMatch[ 1 ] );
-							bare.delete( endMatch[ 1 ] );
+							quasiOccurrences = quasiOccurrences.filter(
+								( { token } ) => token !== endMatch[ 1 ]
+							);
 						}
 					}
 
-					for ( const token of tokens ) {
-						if ( ! knownTokens.has( token ) ) {
-							unknownTokens.push( token );
-						} else if ( bare.has( token ) ) {
-							bareTokens.push( token );
-						}
-					}
+					occurrences.push( ...quasiOccurrences );
 				}
 
+				const { unknownTokens, bareTokens } =
+					getInvalidTokenNames( occurrences );
+
 				if ( hasDynamic ) {
 					context.report( {
 						node,
@@ -124,95 +140,45 @@ module.exports = /** @type {import('eslint').Rule.RuleModule} */ ( {
 					} );
 				}
 
-				if ( unknownTokens.length > 0 ) {
-					context.report( {
-						node,
-						messageId: 'onlyKnownTokens',
-						data: {
-							tokenNames: unknownTokens
-								.map( ( token ) => `'${ token }'` )
-								.join( ', ' ),
-						},
-					} );
-				}
-
-				if ( bareTokens.length > 0 ) {
-					context.report( {
-						node,
-						messageId: 'bareToken',
-						data: {
-							tokenNames: bareTokens
-								.map( ( token ) => `'${ token }'` )
-								.join( ', ' ),
-						},
-					} );
-				}
+				reportTokenNames(
+					context,
+					node,
+					'onlyKnownTokens',
+					unknownTokens
+				);
+				reportTokenNames( context, node, 'bareToken', bareTokens );
 			},
 			/** @param {import('estree').Literal | import('estree').TemplateElement} node */
 			[ staticTokensAST ]( node ) {
-				let computedValue;
-
-				if ( ! node.value ) {
-					return;
-				}
-
-				if ( typeof node.value === 'string' ) {
-					computedValue = node.value;
-				} else if (
-					typeof node.value === 'object' &&
-					'raw' in node.value
-				) {
-					computedValue = node.value.cooked ?? node.value.raw;
-				}
+				const computedValue = getStaticNodeValue( node );
 
 				if ( ! computedValue ) {
 					return;
 				}
 
-				const { tokens: usedTokens, bare } = classifyTokens(
+				const occurrences = collectTokenOccurrences(
 					computedValue,
 					DS_TOKEN_PREFIX
 				);
-				const unknownTokens = [ ...usedTokens ].filter(
-					( token ) => ! knownTokens.has( token )
-				);
-
-				if ( unknownTokens.length > 0 ) {
-					context.report( {
-						node,
-						messageId: 'onlyKnownTokens',
-						data: {
-							tokenNames: unknownTokens
-								.map( ( token ) => `'${ token }'` )
-								.join( ', ' ),
-						},
-					} );
-				}
-
 				// 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( ', ' ),
-							},
-						} );
+				const { unknownTokens, bareTokens } = getInvalidTokenNames(
+					occurrences,
+					{
+						includeBareTokens: ! isPropertyKey,
 					}
-				}
+				);
+
+				reportTokenNames(
+					context,
+					node,
+					'onlyKnownTokens',
+					unknownTokens
+				);
+				reportTokenNames( context, node, 'bareToken', bareTokens );
 			},
 		};
 	},

package/rules/no-unsafe-render-order.js

@@ -0,0 +1,158 @@
+/**
+ * Components tracked by this rule.
+ *
+ * @type {Set<string>}
+ */
+const TRACKED_COMPONENTS = new Set( [ 'Link', 'Text', 'VisuallyHidden' ] );
+
+/**
+ * @type {import('eslint').Rule.RuleModule}
+ */
+module.exports = {
+	meta: {
+		type: 'problem',
+		docs: {
+			description:
+				'Prevent render-prop composition orders that silently remove semantics.',
+			url: 'https://github.com/WordPress/gutenberg/blob/HEAD/packages/eslint-plugin/docs/rules/no-unsafe-render-order.md',
+		},
+		schema: [
+			{
+				type: 'object',
+				properties: {
+					checkLocalImports: {
+						type: 'boolean',
+						description:
+							'When true, also checks tracked components imported from relative paths.',
+					},
+				},
+				additionalProperties: false,
+			},
+		],
+		messages: {
+			visuallyHiddenOrder:
+				'Do not pass `VisuallyHidden` via `render`. Make `VisuallyHidden` the outer component instead.',
+			linkTextOrder:
+				'Use `Text` as the outer component and pass `Link` via `render` so the resulting element stays an `<a>`.',
+		},
+	},
+
+	create( context ) {
+		const checkLocalImports =
+			context.options[ 0 ]?.checkLocalImports ?? false;
+		const trackedImports = new Map();
+
+		/**
+		 * @param {string} source
+		 * @return {boolean} Whether the import should be tracked.
+		 */
+		function shouldTrackImportSource( source ) {
+			if ( source === '@wordpress/ui' ) {
+				return true;
+			}
+
+			if ( checkLocalImports ) {
+				return source.startsWith( '.' ) || source.startsWith( '/' );
+			}
+
+			return false;
+		}
+
+		/**
+		 * @param {import('estree-jsx').JSXIdentifier|import('estree-jsx').JSXMemberExpression} node
+		 * @return {string|null} Tracked component name or null.
+		 */
+		function resolveTrackedJsxName( node ) {
+			if ( node.type !== 'JSXIdentifier' ) {
+				return null;
+			}
+
+			return trackedImports.get( node.name ) ?? null;
+		}
+
+		/**
+		 * @param {Array}  attributes    JSX attributes to inspect.
+		 * @param {string} attributeName Attribute name to match.
+		 * @return {import('estree-jsx').JSXAttribute|undefined} Matching attribute.
+		 */
+		function getJsxAttribute( attributes, attributeName ) {
+			return attributes.find(
+				( attribute ) =>
+					attribute.type === 'JSXAttribute' &&
+					attribute.name?.name === attributeName
+			);
+		}
+
+		/**
+		 * @param {Array} attributes
+		 * @return {string|null} Resolved JSX name inside `render={ <... /> }`.
+		 */
+		function getRenderedComponentName( attributes ) {
+			const renderAttribute = getJsxAttribute( attributes, 'render' );
+
+			if (
+				! renderAttribute?.value ||
+				renderAttribute.value.type !== 'JSXExpressionContainer' ||
+				renderAttribute.value.expression.type !== 'JSXElement'
+			) {
+				return null;
+			}
+
+			return resolveTrackedJsxName(
+				renderAttribute.value.expression.openingElement.name
+			);
+		}
+
+		return {
+			ImportDeclaration( node ) {
+				const source = node.source.value;
+
+				if (
+					typeof source !== 'string' ||
+					! shouldTrackImportSource( source )
+				) {
+					return;
+				}
+
+				node.specifiers.forEach( ( specifier ) => {
+					if ( specifier.type === 'ImportSpecifier' ) {
+						const importedName = specifier.imported.name;
+
+						if ( TRACKED_COMPONENTS.has( importedName ) ) {
+							trackedImports.set(
+								specifier.local.name,
+								importedName
+							);
+						}
+					}
+				} );
+			},
+
+			JSXOpeningElement( node ) {
+				const renderedComponentName = getRenderedComponentName(
+					node.attributes
+				);
+
+				if ( renderedComponentName === 'VisuallyHidden' ) {
+					context.report( {
+						node,
+						messageId: 'visuallyHiddenOrder',
+					} );
+					return;
+				}
+
+				const elementName = resolveTrackedJsxName( node.name );
+
+				if (
+					elementName === 'Link' &&
+					renderedComponentName === 'Text'
+				) {
+					context.report( {
+						node,
+						messageId: 'linkTextOrder',
+					} );
+				}
+			},
+		};
+	},
+};

package/rules/no-unsafe-wp-apis.js

@@ -1,7 +1,7 @@
 /** @type {import('eslint').Rule.RuleModule} */
 module.exports = {
-	type: 'problem',
 	meta: {
+		type: 'problem',
 		schema: [
 			{
 				type: 'object',