@wordpress/eslint-plugin 24.0.1-next.ba3aee3a2.0 → 24.1.0

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

@@ -0,0 +1,101 @@
+const tokenListModule = require( '@wordpress/theme/design-tokens.js' );
+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.
+ *
+ * @param {string} value       - The CSS value string to search for variables.
+ * @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' }).
+ *
+ * @example
+ * extractCSSVariables(
+ *   'border: 1px solid var(--wpds-border-color, var(--wpds-border-fallback)); ' +
+ *   'color: var(--wpds-color-fg, black); ' +
+ *   'background: var(--unrelated-bg);',
+ *   'wpds'
+ * );
+ * // → Set { '--wpds-border-color', '--wpds-border-fallback', '--wpds-color-fg' }
+ */
+function extractCSSVariables( value, prefix = '' ) {
+	const regex = /--[\w-]+/g;
+	const variables = new Set();
+
+	let match;
+	while ( ( match = regex.exec( value ) ) !== null ) {
+		const variableName = match[ 0 ];
+		if ( variableName.startsWith( `--${ prefix }` ) ) {
+			variables.add( variableName );
+		}
+	}
+
+	return variables;
+}
+
+const knownTokens = new Set( tokenList );
+const wpdsTokensRegex = new RegExp( `[^\\w]--${ DS_TOKEN_PREFIX }`, 'i' );
+
+module.exports = /** @type {import('eslint').Rule.RuleModule} */ ( {
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Prevent use of non-existing --wpds-* variables',
+		},
+		schema: [],
+		messages: {
+			onlyKnownTokens:
+				'The following CSS variables are not valid Design System tokens: {{ tokenNames }}',
+		},
+	},
+	create( context ) {
+		const disallowedTokensAST = `JSXAttribute[name.name="style"] :matches(Literal[value=${ wpdsTokensRegex }], TemplateLiteral TemplateElement[value.raw=${ wpdsTokensRegex }])`;
+		return {
+			/** @param {import('estree').Literal | import('estree').TemplateElement} node */
+			[ disallowedTokensAST ]( node ) {
+				let computedValue;
+
+				if ( ! node.value ) {
+					return;
+				}
+
+				if ( typeof node.value === 'string' ) {
+					// Get the node's value when it's a "string"
+					computedValue = node.value;
+				} else if (
+					typeof node.value === 'object' &&
+					'raw' in node.value
+				) {
+					// Get the node's value when it's a `template literal`
+					computedValue = node.value.cooked ?? node.value.raw;
+				}
+
+				if ( ! computedValue ) {
+					return;
+				}
+
+				const usedTokens = extractCSSVariables(
+					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( ', ' ),
+						},
+					} );
+				}
+			},
+		};
+	},
+} );

package/utils/has-truthy-jsx-attribute.js

@@ -0,0 +1,50 @@
+/**
+ * Check if a JSX/React attribute exists and has a truthy value.
+ *
+ * This utility analyzes JSX attribute nodes from an ESLint AST to determine
+ * if a specific attribute is present with a truthy value.
+ *
+ * Handles the following patterns:
+ * - Boolean shorthand: `<Component prop />` → truthy
+ * - Explicit true: `<Component prop={true} />` → truthy
+ * - Explicit false: `<Component prop={false} />` → NOT truthy
+ * - String values: `<Component prop="value" />` → truthy (if non-empty)
+ * - Dynamic expressions: `<Component prop={someVar} />` → assumed truthy
+ *
+ * @param {Array}  attributes - Array of JSX attribute nodes from the ESLint AST
+ * @param {string} attrName   - The attribute name to check
+ * @return {boolean} Whether the attribute exists with a truthy value
+ */
+function hasTruthyJsxAttribute( attributes, attrName ) {
+	const attr = attributes.find(
+		( a ) => a.type === 'JSXAttribute' && a.name && a.name.name === attrName
+	);
+
+	if ( ! attr ) {
+		return false;
+	}
+
+	// Boolean attribute without value (e.g., `<Button disabled />`)
+	if ( attr.value === null ) {
+		return true;
+	}
+
+	// Expression like `prop={true}` or `prop={false}`
+	if (
+		attr.value.type === 'JSXExpressionContainer' &&
+		attr.value.expression.type === 'Literal'
+	) {
+		return attr.value.expression.value !== false;
+	}
+
+	// String value - truthy if not empty
+	if ( attr.value.type === 'Literal' ) {
+		return Boolean( attr.value.value );
+	}
+
+	// For any other expression (variables, function calls, etc.),
+	// assume it could be truthy since we can't statically analyze it
+	return true;
+}
+
+module.exports = { hasTruthyJsxAttribute };

package/utils/index.js

@@ -9,6 +9,7 @@ const {
 const { getTranslateFunctionArgs } = require( './get-translate-function-args' );
 const { getTextContentFromNode } = require( './get-text-content-from-node' );
 const { getTranslateFunctionName } = require( './get-translate-function-name' );
+const { hasTruthyJsxAttribute } = require( './has-truthy-jsx-attribute' );
 const isPackageInstalled = require( './is-package-installed' );
 
 module.exports = {
@@ -18,5 +19,6 @@ module.exports = {
 	getTranslateFunctionArgs,
 	getTextContentFromNode,
 	getTranslateFunctionName,
+	hasTruthyJsxAttribute,
 	isPackageInstalled,
 };