@wordpress/eslint-plugin 25.0.0 → 25.1.0

package/rules/use-import-as.js

@@ -0,0 +1,310 @@
+/** @type {import('eslint').Rule.RuleModule} */
+const rule = {
+	meta: {
+		type: 'suggestion',
+		hasSuggestions: true,
+		docs: {
+			description:
+				'Enforce configured `as` names for specific named imports and unlocked private APIs.',
+			url: 'https://github.com/WordPress/gutenberg/blob/HEAD/packages/eslint-plugin/docs/rules/use-import-as.md',
+		},
+		schema: [
+			{
+				type: 'object',
+				additionalProperties: {
+					type: 'object',
+					minProperties: 1,
+					additionalProperties: {
+						type: 'string',
+					},
+				},
+			},
+		],
+		messages: {
+			mustUseImportAs:
+				'`{{ importedName }}` from `{{ source }}` must be imported as `{{ localName }}`.',
+			useImportAsSuggestion: 'Import as `{{ localName }}`.',
+			useUnlockAsSuggestion: 'Destructure as `{{ localName }}`.',
+		},
+	},
+	create( context ) {
+		const importAsMap =
+			context.options.length > 0 &&
+			context.options[ 0 ] &&
+			typeof context.options[ 0 ] === 'object'
+				? context.options[ 0 ]
+				: {};
+		const privateApisSources = new Map();
+		const trackedUnlockImports = new Set();
+
+		return {
+			/** @param {import('estree').ImportDeclaration} node */
+			ImportDeclaration( node ) {
+				if ( typeof node.source.value !== 'string' ) {
+					return;
+				}
+
+				const source = node.source.value;
+				const sourceMap = importAsMap[ source ];
+
+				node.specifiers.forEach( ( specifier ) => {
+					if ( specifier.type !== 'ImportSpecifier' ) {
+						return;
+					}
+
+					const importedName = getImportedName( specifier );
+					if ( importedName === 'unlock' ) {
+						trackedUnlockImports.add( specifier.local.name );
+					}
+
+					if ( ! sourceMap ) {
+						return;
+					}
+
+					if ( importedName === 'privateApis' ) {
+						privateApisSources.set( specifier.local.name, source );
+					}
+					const localName = sourceMap[ importedName ];
+
+					if ( ! localName || specifier.local.name === localName ) {
+						return;
+					}
+
+					context.report( {
+						node: specifier.local,
+						messageId: 'mustUseImportAs',
+						data: {
+							importedName,
+							source,
+							localName,
+						},
+						suggest: [
+							{
+								messageId: 'useImportAsSuggestion',
+								data: {
+									localName,
+								},
+								fix( fixer ) {
+									return fixer.replaceText(
+										specifier,
+										getImportSpecifierSuggestionText(
+											specifier,
+											context.sourceCode,
+											localName
+										)
+									);
+								},
+							},
+						],
+					} );
+				} );
+			},
+			/** @param {import('estree').VariableDeclarator} node */
+			VariableDeclarator( node ) {
+				if (
+					node.parent.type !== 'VariableDeclaration' ||
+					node.parent.kind !== 'const' ||
+					node.id.type !== 'ObjectPattern' ||
+					! isUnlockCall(
+						node.init,
+						context.sourceCode,
+						trackedUnlockImports
+					)
+				) {
+					return;
+				}
+
+				const privateApisIdentifier = node.init.arguments[ 0 ];
+				if ( privateApisIdentifier.type !== 'Identifier' ) {
+					return;
+				}
+
+				const source = privateApisSources.get(
+					privateApisIdentifier.name
+				);
+				if ( ! source ) {
+					return;
+				}
+
+				const sourceMap = importAsMap[ source ];
+				if ( ! sourceMap ) {
+					return;
+				}
+
+				node.id.properties.forEach( ( property ) => {
+					if ( property.type !== 'Property' || property.computed ) {
+						return;
+					}
+
+					const importedName = getPropertyName( property.key );
+					if ( ! importedName ) {
+						return;
+					}
+
+					const localName = sourceMap[ importedName ];
+					if ( ! localName ) {
+						return;
+					}
+
+					const propertyLocalName = getPropertyLocalName(
+						property.value
+					);
+					if (
+						! propertyLocalName ||
+						propertyLocalName === localName
+					) {
+						return;
+					}
+
+					context.report( {
+						node: getReportNode( property.value ),
+						messageId: 'mustUseImportAs',
+						data: {
+							importedName,
+							source,
+							localName,
+						},
+						suggest: [
+							{
+								messageId: 'useUnlockAsSuggestion',
+								data: {
+									localName,
+								},
+								fix( fixer ) {
+									return fixer.replaceText(
+										property,
+										getPropertySuggestionText(
+											property,
+											context.sourceCode,
+											localName
+										)
+									);
+								},
+							},
+						],
+					} );
+				} );
+			},
+		};
+	},
+};
+
+/**
+ * @param {import('estree').ImportSpecifier} specifier
+ * @return {string} Imported name.
+ */
+function getImportedName( specifier ) {
+	return specifier.imported.type === 'Identifier'
+		? specifier.imported.name
+		: String( specifier.imported.value );
+}
+
+/**
+ * @param {import('estree').ImportSpecifier} specifier
+ * @param {import('eslint').SourceCode}      sourceCode
+ * @param {string}                           localName
+ * @return {string} Suggested replacement text for an import specifier.
+ */
+function getImportSpecifierSuggestionText( specifier, sourceCode, localName ) {
+	return `${ sourceCode.getText( specifier.imported ) } as ${ localName }`;
+}
+
+/**
+ * @param {import('estree').CallExpression|import('estree').Expression|null} node
+ * @param {import('eslint').SourceCode}                                      sourceCode
+ * @param {ReadonlySet<string>}                                              trackedUnlockImports
+ * @return {node is import('estree').CallExpression} Whether this is an `unlock()` call with one argument.
+ */
+function isUnlockCall( node, sourceCode, trackedUnlockImports ) {
+	if (
+		node &&
+		node.type === 'CallExpression' &&
+		node.callee.type === 'Identifier' &&
+		node.arguments.length === 1
+	) {
+		if ( ! trackedUnlockImports.has( node.callee.name ) ) {
+			return false;
+		}
+
+		const { references } = sourceCode.getScope( node.callee );
+		const reference = references.find(
+			( currentReference ) => currentReference.identifier === node.callee
+		);
+
+		return !! reference?.resolved?.defs.some(
+			( definition ) => definition.type === 'ImportBinding'
+		);
+	}
+
+	return false;
+}
+
+/**
+ * @param {import('estree').Expression|import('estree').PrivateIdentifier} key
+ * @return {string|null} Property name.
+ */
+function getPropertyName( key ) {
+	if ( key.type === 'Identifier' ) {
+		return key.name;
+	}
+
+	if ( key.type === 'Literal' ) {
+		return String( key.value );
+	}
+
+	return null;
+}
+
+/**
+ * @param {import('estree').Property}   property
+ * @param {import('eslint').SourceCode} sourceCode
+ * @param {string}                      localName
+ * @return {string} Suggested replacement text for a destructuring property.
+ */
+function getPropertySuggestionText( property, sourceCode, localName ) {
+	const keyText = sourceCode.getText( property.key );
+
+	if ( property.value.type === 'AssignmentPattern' ) {
+		return `${ keyText }: ${ localName } = ${ sourceCode.getText(
+			property.value.right
+		) }`;
+	}
+
+	return `${ keyText }: ${ localName }`;
+}
+
+/**
+ * @param {import('estree').Pattern} value
+ * @return {string|null} Local variable name.
+ */
+function getPropertyLocalName( value ) {
+	if ( value.type === 'Identifier' ) {
+		return value.name;
+	}
+
+	if (
+		value.type === 'AssignmentPattern' &&
+		value.left.type === 'Identifier'
+	) {
+		return value.left.name;
+	}
+
+	return null;
+}
+
+/**
+ * @param {import('estree').Pattern} value
+ * @return {import('estree').Node} Node to report on.
+ */
+function getReportNode( value ) {
+	if (
+		value.type === 'AssignmentPattern' &&
+		value.left.type === 'Identifier'
+	) {
+		return value.left;
+	}
+
+	return value;
+}
+
+module.exports = rule;

package/rules/use-recommended-components.js

@@ -8,7 +8,17 @@
  */
 const ALLOWLIST = {
 	'@wordpress/ui': {
-		allowed: [ 'Badge', 'Stack', 'Text' ],
+		allowed: [
+			'Badge',
+			'Card',
+			'Collapsible',
+			'CollapsibleCard',
+			'EmptyState',
+			'Link',
+			'Stack',
+			'Text',
+			'VisuallyHidden',
+		],
 		message:
 			'`{{ name }}` from `{{ source }}` is not yet recommended for use in a WordPress environment.',
 	},
@@ -24,8 +34,22 @@ const ALLOWLIST = {
  */
 const DENYLIST = {
 	'@wordpress/components': {
+		ExternalLink:
+			'Use `Link` from `@wordpress/ui` with the `openInNewTab` prop instead.',
+		__experimentalHeading: 'Use `Text` from `@wordpress/ui` instead.',
+		__experimentalHStack: 'Use `Stack` from `@wordpress/ui` instead.',
+		__experimentalText: 'Use `Text` from `@wordpress/ui` instead.',
+		__experimentalVStack: 'Use `Stack` from `@wordpress/ui` instead.',
 		__experimentalZStack:
 			'{{ name }} is planned for deprecation. Write your own CSS instead.',
+		Card: 'Use `Card.Root` from `@wordpress/ui` instead.',
+		CardBody: 'Use `Card.Content` from `@wordpress/ui` instead.',
+		CardDivider: 'A divider is no longer a standard pattern for cards.',
+		CardFooter: 'A footer is no longer a standard pattern for cards.',
+		CardHeader:
+			'Use `Card.Header` (and optionally `Card.Title`) from `@wordpress/ui` instead.',
+		CardMedia: 'Use `Card.FullBleed` from `@wordpress/ui` instead.',
+		VisuallyHidden: 'Use `{{ name }}` from `@wordpress/ui` instead.',
 	},
 };
 

package/utils/ds-token-utils.js

@@ -0,0 +1,58 @@
+const DS_TOKEN_PREFIX = 'wpds-';
+const wpdsTokensRegex = new RegExp( `(?:^|[^\\w])--${ DS_TOKEN_PREFIX }`, 'i' );
+
+/**
+ * Single-pass extraction that finds all `--prefix-*` tokens in a CSS value
+ * string, classifying each occurrence as `var()`-wrapped or bare, and whether
+ * it appears in a declaration position (i.e. followed by `:`).
+ *
+ * @param {string} value       - The CSS value string to search.
+ * @param {string} [prefix=''] - Optional prefix to filter variables (e.g., 'wpds-').
+ */
+function collectTokenOccurrences( value, prefix = '' ) {
+	const regex = new RegExp(
+		`(?:^|[^\\w])(var\\(\\s*)?(--${ prefix }[\\w-]+)`,
+		'g'
+	);
+	const occurrences = [];
+
+	let match;
+	while ( ( match = regex.exec( value ) ) !== null ) {
+		occurrences.push( {
+			token: match[ 2 ],
+			bare: ! match[ 1 ],
+			declaration: /^\s*:/.test( value.slice( regex.lastIndex ) ),
+		} );
+	}
+
+	return occurrences;
+}
+
+/**
+ * Returns the static string value for a literal-like node, or `undefined`
+ * when the node does not contain one.
+ *
+ * @param {import('estree').Literal | import('estree').TemplateElement} node
+ * @return {string | undefined} The static string value, or `undefined`
+ *                              when the node does not contain one.
+ */
+function getStaticNodeValue( node ) {
+	if ( ! node.value ) {
+		return;
+	}
+
+	if ( typeof node.value === 'string' ) {
+		return node.value;
+	}
+
+	if ( typeof node.value === 'object' && 'raw' in node.value ) {
+		return node.value.cooked ?? node.value.raw;
+	}
+}
+
+module.exports = {
+	DS_TOKEN_PREFIX,
+	collectTokenOccurrences,
+	getStaticNodeValue,
+	wpdsTokensRegex,
+};