@wordpress/eslint-plugin 24.6.1-next.v.202604091042.0 → 25.0.0

package/README.md

@@ -14,15 +14,47 @@ npm install @wordpress/eslint-plugin --save-dev
 
 ## Usage
 
-To opt-in to the default configuration, extend your own project's `.eslintrc` file:
+### Flat config (ESLint v10+, recommended)
 
-```json
-{
-	"extends": [ "plugin:@wordpress/eslint-plugin/recommended" ]
-}
+Create an `eslint.config.mjs` file in your project root:
+
+```js
+import wordpress from '@wordpress/eslint-plugin';
+
+export default [ ...wordpress.configs.recommended ];
 ```
 
-Refer to the [ESLint documentation on Shareable Configs](https://eslint.org/docs/latest/extend/shareable-configs) for more information.
+You can add your own overrides after the spread:
+
+```js
+import wordpress from '@wordpress/eslint-plugin';
+
+export default [
+	...wordpress.configs.recommended,
+	{
+		rules: {
+			// your custom rule overrides
+		},
+	},
+];
+```
+
+Refer to the [ESLint flat config documentation](https://eslint.org/docs/latest/use/configure/configuration-files) for more information.
+
+### Legacy eslintrc (ESLint v9, deprecated)
+
+If you are still using ESLint v9 with the legacy `.eslintrc.*` format, a compatibility wrapper is available:
+
+```js
+// .eslintrc.js
+const wordpress = require( '@wordpress/eslint-plugin/eslintrc' );
+
+module.exports = wordpress.configs.recommended;
+```
+
+> **Note:** The eslintrc wrapper is deprecated and will be removed in a future major version. Please migrate to flat config.
+
+### About the recommended preset
 
 The `recommended` preset will include rules governing an ES2015+ environment, and includes rules from the [`eslint-plugin-jsdoc`](https://github.com/gajus/eslint-plugin-jsdoc), [`eslint-plugin-jsx-a11y`](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y), [`eslint-plugin-react`](https://github.com/yannickcr/eslint-plugin-react), and other similar plugins.
 
@@ -55,15 +87,16 @@ Alternatively, you can opt-in to only the more granular rulesets offered by the
 -   `test-unit`– rules for unit tests written in Jest.
 -   `test-playwright` – rules for end-to-end tests written in Playwright.
 
-For example, if your project does not use React, you could consider extending including only the ESNext rules in your project using the following `extends` definition:
+For example, if your project does not use React, you could use only the ESNext rules:
 
-```json
-{
-	"extends": [ "plugin:@wordpress/eslint-plugin/esnext" ]
-}
+```js
+// eslint.config.mjs
+import wordpress from '@wordpress/eslint-plugin';
+
+export default [ ...wordpress.configs.esnext ];
 ```
 
-These rules can be used additively, so you could extend both `esnext` and `custom` rulesets, but omit the `react` and `jsx-a11y` configurations.
+These rules can be used additively, so you could spread both `esnext` and `custom` rulesets, but omit the `react` and `jsx-a11y` configurations.
 
 The granular rulesets will not define any environment globals. As such, if they are required for your project, you will need to define them yourself.
 
@@ -99,15 +132,27 @@ The granular rulesets will not define any environment globals. As such, if they
 | [valid-sprintf](https://github.com/WordPress/gutenberg/tree/HEAD/packages/eslint-plugin/docs/rules/valid-sprintf.md)                                                 | Enforce valid sprintf usage.                                                                    | ✓           |
 | [wp-global-usage](https://github.com/WordPress/gutenberg/tree/HEAD/packages/eslint-plugin/docs/rules/wp-global-usage.md)                                             | Enforce correct usage of WordPress globals like `globalThis.SCRIPT_DEBUG`.                      |             |
 
-### Legacy
+### Migrating from eslintrc to flat config
 
-If you are using WordPress' `.jshintrc` JSHint configuration and you would like to take the first step to migrate to an ESLint equivalent it is also possible to define your own project's `.eslintrc` file as:
+If you are upgrading from a previous version that used `.eslintrc.*` files:
 
-```json
-{
-	"extends": [ "plugin:@wordpress/eslint-plugin/jshint" ]
-}
-```
+1. Replace your `.eslintrc.*` file with an `eslint.config.mjs` file.
+2. Change `extends` arrays to import + spread:
+    ```js
+    // Old (.eslintrc.js)
+    module.exports = {
+    	extends: [ 'plugin:@wordpress/eslint-plugin/recommended' ],
+    };
+
+    // New (eslint.config.mjs)
+    import wordpress from '@wordpress/eslint-plugin';
+    export default [ ...wordpress.configs.recommended ];
+    ```
+3. Convert `overrides` to separate config objects with `files` patterns.
+4. Replace `env` with `languageOptions.globals` using the [`globals`](https://www.npmjs.com/package/globals) package.
+5. Delete your `.eslintignore` file and move patterns into an `ignores` config object.
+
+See the [ESLint migration guide](https://eslint.org/docs/latest/use/configure/migration-guide) for full details.
 
 ## Contributing to this package
 

package/configs/babel-parser-compat.js

@@ -0,0 +1,69 @@
+/* eslint-disable jsdoc/check-tag-names -- Package names containing @ are not JSDoc tags */
+/**
+ * Wrapper around @babel/eslint-parser that ensures compatibility with
+ * ESLint v10+. ESLint v10 expects `scopeManager.addGlobals()` which is
+ * available in eslint-scope v9 bundled with ESLint v10, but
+ * @babel/eslint-parser v7 uses an older eslint-scope that does not have
+ * this method. This wrapper patches the scope manager when needed.
+ *
+ * TODO: Remove this wrapper when upgrading to @babel/eslint-parser v8+,
+ * which adds native ESLint v10 support (requires @babel/core v8).
+ * See https://github.com/babel/babel/issues/17791
+ */
+/* eslint-enable jsdoc/check-tag-names */
+const babelParser = require( '@babel/eslint-parser' );
+
+module.exports = {
+	meta: {
+		...babelParser.meta,
+		name: '@wordpress/babel-eslint-parser-compat',
+	},
+
+	parse( code, options ) {
+		return babelParser.parse( code, options );
+	},
+
+	parseForESLint( code, options ) {
+		const result = babelParser.parseForESLint( code, options );
+
+		// Patch scopeManager if addGlobals is missing (ESLint v10 compat).
+		if (
+			result.scopeManager &&
+			typeof result.scopeManager.addGlobals !== 'function'
+		) {
+			result.scopeManager.addGlobals = function addGlobals( names ) {
+				const globalScope = this.scopes[ 0 ];
+				if ( ! globalScope ) {
+					return;
+				}
+				for ( const name of names ) {
+					globalScope.__defineGeneric(
+						name,
+						globalScope.set,
+						globalScope.variables,
+						null,
+						null
+					);
+				}
+
+				// Resolve through references that match the new globals.
+				const namesSet = new Set( names );
+				globalScope.through = globalScope.through.filter(
+					( reference ) => {
+						if ( namesSet.has( reference.identifier.name ) ) {
+							const variable = globalScope.set.get(
+								reference.identifier.name
+							);
+							reference.resolved = variable;
+							variable.references.push( reference );
+							return false;
+						}
+						return true;
+					}
+				);
+			};
+		}
+
+		return result;
+	},
+};

package/configs/custom.js

@@ -1,31 +1,40 @@
-module.exports = {
-	plugins: [ '@wordpress' ],
-	rules: {
-		'@wordpress/no-unused-vars-before-return': 'error',
-		'@wordpress/no-base-control-with-label-without-id': 'error',
-		'@wordpress/no-unguarded-get-range-at': 'error',
-		'@wordpress/no-global-active-element': 'error',
-		'@wordpress/no-global-get-selection': 'error',
-		'@wordpress/no-setting-ds-tokens': 'error',
-		'@wordpress/no-unknown-ds-tokens': 'error',
-		'@wordpress/no-unsafe-wp-apis': 'error',
-		'@wordpress/no-wp-process-env': 'error',
+/**
+ * Internal dependencies
+ */
+const wpRules = require( '../rules' );
+
+const wpPlugin = { rules: wpRules };
+
+module.exports = [
+	{
+		plugins: {
+			'@wordpress': wpPlugin,
+		},
+		rules: {
+			'@wordpress/no-unused-vars-before-return': 'error',
+			'@wordpress/no-base-control-with-label-without-id': 'error',
+			'@wordpress/no-unguarded-get-range-at': 'error',
+			'@wordpress/no-global-active-element': 'error',
+			'@wordpress/no-global-get-selection': 'error',
+			'@wordpress/no-setting-ds-tokens': 'error',
+			'@wordpress/no-unknown-ds-tokens': 'error',
+			'@wordpress/no-unsafe-wp-apis': 'error',
+			'@wordpress/no-wp-process-env': 'error',
+		},
 	},
-	overrides: [
-		{
-			files: [ '*.native.js' ],
-			rules: {
-				'@wordpress/no-base-control-with-label-without-id': 'off',
-				'@wordpress/i18n-no-flanking-whitespace': 'error',
-				'@wordpress/i18n-hyphenated-range': 'error',
-			},
+	{
+		files: [ '**/*.native.js' ],
+		rules: {
+			'@wordpress/no-base-control-with-label-without-id': 'off',
+			'@wordpress/i18n-no-flanking-whitespace': 'error',
+			'@wordpress/i18n-hyphenated-range': 'error',
 		},
-		{
-			files: [ '*.test.js', '**/test/*.js' ],
-			rules: {
-				'@wordpress/no-global-active-element': 'off',
-				'@wordpress/no-global-get-selection': 'off',
-			},
+	},
+	{
+		files: [ '**/*.test.js', '**/test/*.js' ],
+		rules: {
+			'@wordpress/no-global-active-element': 'off',
+			'@wordpress/no-global-get-selection': 'off',
 		},
-	],
-};
+	},
+];

package/configs/es5.js

@@ -1,95 +1,102 @@
-module.exports = {
-	extends: [ require.resolve( './jsdoc.js' ) ],
-	rules: {
-		'array-bracket-spacing': [ 'error', 'always' ],
-		'array-callback-return': 'error',
-		'brace-style': [ 'error', '1tbs' ],
-		camelcase: [
-			'error',
-			{
-				properties: 'never',
-			},
-		],
-		'comma-dangle': [ 'error', 'always-multiline' ],
-		'comma-spacing': 'error',
-		'comma-style': [ 'error', 'last' ],
-		curly: [ 'error', 'all' ],
-		'dot-notation': 'error',
-		'eol-last': 'error',
-		eqeqeq: 'error',
-		'func-call-spacing': 'error',
-		indent: [ 'error', 'tab', { SwitchCase: 1 } ],
-		'key-spacing': 'error',
-		'keyword-spacing': 'error',
-		'linebreak-style': [ 'error', 'unix' ],
-		'no-alert': 'error',
-		'no-bitwise': 'error',
-		'no-caller': 'error',
-		'no-cond-assign': [ 'error', 'except-parens' ],
-		'no-console': 'error',
-		'no-debugger': 'error',
-		'no-dupe-args': 'error',
-		'no-dupe-keys': 'error',
-		'no-duplicate-case': 'error',
-		'no-else-return': 'error',
-		'no-eval': 'error',
-		'no-extra-semi': 'error',
-		'no-fallthrough': 'error',
-		'no-irregular-whitespace': 'error',
-		'no-lonely-if': 'error',
-		'no-multi-str': 'error',
-		'no-mixed-operators': 'error',
-		'no-mixed-spaces-and-tabs': 'error',
-		'no-multiple-empty-lines': [ 'error', { max: 1 } ],
-		'no-multi-spaces': 'error',
-		'no-nested-ternary': 'error',
-		'no-redeclare': 'error',
-		'no-shadow': 'error',
-		'no-trailing-spaces': 'error',
-		'no-undef': 'error',
-		'no-undef-init': 'error',
-		'no-unreachable': 'error',
-		'no-unsafe-negation': 'error',
-		'no-unused-expressions': 'error',
-		'no-unused-vars': [ 'error', { ignoreRestSiblings: true } ],
-		'no-useless-return': 'error',
-		'no-whitespace-before-property': 'error',
-		'no-with': 'error',
-		'object-curly-spacing': [ 'error', 'always' ],
-		'one-var-declaration-per-line': [ 'error', 'initializations' ],
-		'operator-linebreak': 'error',
-		'padded-blocks': [ 'error', 'never' ],
-		'quote-props': [ 'error', 'as-needed' ],
-		quotes: [ 'error', 'single', { avoidEscape: true } ],
-		semi: 'error',
-		'semi-spacing': 'error',
-		'space-before-blocks': [ 'error', 'always' ],
-		'space-before-function-paren': [
-			'error',
-			{
-				anonymous: 'never',
-				named: 'never',
-				asyncArrow: 'always',
-			},
-		],
-		'space-in-parens': [
-			'error',
-			'always',
-			{
-				exceptions: [ 'empty' ],
-			},
-		],
-		'space-infix-ops': 'error',
-		'space-unary-ops': [
-			'error',
-			{
-				overrides: {
-					'!': true,
+/**
+ * Internal dependencies
+ */
+const jsdocConfig = require( './jsdoc' );
+
+module.exports = [
+	...jsdocConfig,
+	{
+		rules: {
+			'array-bracket-spacing': [ 'error', 'always' ],
+			'array-callback-return': 'error',
+			'brace-style': [ 'error', '1tbs' ],
+			camelcase: [
+				'error',
+				{
+					properties: 'never',
 				},
-			},
-		],
-		'valid-typeof': 'error',
-		'vars-on-top': 'error',
-		'wrap-iife': 'error',
+			],
+			'comma-dangle': [ 'error', 'always-multiline' ],
+			'comma-spacing': 'error',
+			'comma-style': [ 'error', 'last' ],
+			curly: [ 'error', 'all' ],
+			'dot-notation': 'error',
+			'eol-last': 'error',
+			eqeqeq: 'error',
+			'func-call-spacing': 'error',
+			indent: [ 'error', 'tab', { SwitchCase: 1 } ],
+			'key-spacing': 'error',
+			'keyword-spacing': 'error',
+			'linebreak-style': [ 'error', 'unix' ],
+			'no-alert': 'error',
+			'no-bitwise': 'error',
+			'no-caller': 'error',
+			'no-cond-assign': [ 'error', 'except-parens' ],
+			'no-console': 'error',
+			'no-debugger': 'error',
+			'no-dupe-args': 'error',
+			'no-dupe-keys': 'error',
+			'no-duplicate-case': 'error',
+			'no-else-return': 'error',
+			'no-eval': 'error',
+			'no-extra-semi': 'error',
+			'no-fallthrough': 'error',
+			'no-irregular-whitespace': 'error',
+			'no-lonely-if': 'error',
+			'no-multi-str': 'error',
+			'no-mixed-operators': 'error',
+			'no-mixed-spaces-and-tabs': 'error',
+			'no-multiple-empty-lines': [ 'error', { max: 1 } ],
+			'no-multi-spaces': 'error',
+			'no-nested-ternary': 'error',
+			'no-redeclare': 'error',
+			'no-shadow': 'error',
+			'no-trailing-spaces': 'error',
+			'no-undef': 'error',
+			'no-undef-init': 'error',
+			'no-unreachable': 'error',
+			'no-unsafe-negation': 'error',
+			'no-unused-expressions': 'error',
+			'no-unused-vars': [ 'error', { ignoreRestSiblings: true } ],
+			'no-useless-return': 'error',
+			'no-whitespace-before-property': 'error',
+			'no-with': 'error',
+			'object-curly-spacing': [ 'error', 'always' ],
+			'one-var-declaration-per-line': [ 'error', 'initializations' ],
+			'operator-linebreak': 'error',
+			'padded-blocks': [ 'error', 'never' ],
+			'quote-props': [ 'error', 'as-needed' ],
+			quotes: [ 'error', 'single', { avoidEscape: true } ],
+			semi: 'error',
+			'semi-spacing': 'error',
+			'space-before-blocks': [ 'error', 'always' ],
+			'space-before-function-paren': [
+				'error',
+				{
+					anonymous: 'never',
+					named: 'never',
+					asyncArrow: 'always',
+				},
+			],
+			'space-in-parens': [
+				'error',
+				'always',
+				{
+					exceptions: [ 'empty' ],
+				},
+			],
+			'space-infix-ops': 'error',
+			'space-unary-ops': [
+				'error',
+				{
+					overrides: {
+						'!': true,
+					},
+				},
+			],
+			'valid-typeof': 'error',
+			'vars-on-top': 'error',
+			'wrap-iife': 'error',
+		},
 	},
-};
+];

package/configs/esnext.js

@@ -2,67 +2,75 @@
  * External dependencies
  */
 const { cosmiconfigSync } = require( 'cosmiconfig' );
+const babelParser = require( './babel-parser-compat' );
+const globals = require( 'globals' );
 
-const config = {
-	parser: '@babel/eslint-parser',
-	parserOptions: {
-		sourceType: 'module',
-	},
-	env: {
-		es6: true,
-	},
-	extends: [ require.resolve( './es5.js' ) ],
-	rules: {
-		// Disable ES5-specific (extended from ES5)
-		'vars-on-top': 'off',
+/**
+ * Internal dependencies
+ */
+const es5Config = require( './es5' );
 
-		// Enable ESNext-specific.
-		'arrow-parens': [ 'error', 'always' ],
-		'arrow-spacing': 'error',
-		'computed-property-spacing': [ 'error', 'always' ],
-		'constructor-super': 'error',
-		'no-const-assign': 'error',
-		'no-dupe-class-members': 'error',
-		'no-duplicate-imports': 'error',
-		'no-useless-computed-key': 'error',
-		'no-useless-constructor': 'error',
-		'no-var': 'error',
-		'object-shorthand': 'error',
-		'prefer-const': [
-			'error',
-			{
-				destructuring: 'all',
-			},
-		],
-		quotes: [
-			'error',
-			'single',
-			{ allowTemplateLiterals: true, avoidEscape: true },
-		],
-		'space-unary-ops': [
-			'error',
-			{
-				overrides: {
-					'!': true,
-					yield: true,
-				},
-			},
-		],
-		'template-curly-spacing': [ 'error', 'always' ],
-	},
+const parserOptions = {
+	sourceType: 'module',
 };
 
 // It won't recognize the `babel.config.json` file used in the project until the upstream bug in `cosmiconfig` is fixed:
 // https://github.com/davidtheclark/cosmiconfig/issues/246.
 const result = cosmiconfigSync( 'babel' ).search();
 if ( ! result || ! result.filepath ) {
-	config.parserOptions = {
-		...config.parserOptions,
-		requireConfigFile: false,
-		babelOptions: {
-			presets: [ require.resolve( '@wordpress/babel-preset-default' ) ],
-		},
+	parserOptions.requireConfigFile = false;
+	parserOptions.babelOptions = {
+		presets: [ require.resolve( '@wordpress/babel-preset-default' ) ],
 	};
 }
 
-module.exports = config;
+module.exports = [
+	...es5Config,
+	{
+		languageOptions: {
+			parser: babelParser,
+			parserOptions,
+			globals: {
+				...globals.es2015,
+			},
+		},
+		rules: {
+			// Disable ES5-specific (extended from ES5)
+			'vars-on-top': 'off',
+
+			// Enable ESNext-specific.
+			'arrow-parens': [ 'error', 'always' ],
+			'arrow-spacing': 'error',
+			'computed-property-spacing': [ 'error', 'always' ],
+			'constructor-super': 'error',
+			'no-const-assign': 'error',
+			'no-dupe-class-members': 'error',
+			'no-duplicate-imports': 'error',
+			'no-useless-computed-key': 'error',
+			'no-useless-constructor': 'error',
+			'no-var': 'error',
+			'object-shorthand': 'error',
+			'prefer-const': [
+				'error',
+				{
+					destructuring: 'all',
+				},
+			],
+			quotes: [
+				'error',
+				'single',
+				{ allowTemplateLiterals: true, avoidEscape: true },
+			],
+			'space-unary-ops': [
+				'error',
+				{
+					overrides: {
+						'!': true,
+						yield: true,
+					},
+				},
+			],
+			'template-curly-spacing': [ 'error', 'always' ],
+		},
+	},
+];

package/configs/i18n.js

@@ -1,14 +1,25 @@
-module.exports = {
-	plugins: [ '@wordpress' ],
-	rules: {
-		'@wordpress/valid-sprintf': 'error',
-		'@wordpress/i18n-translator-comments': 'error',
-		'@wordpress/i18n-text-domain': 'error',
-		'@wordpress/i18n-no-collapsible-whitespace': 'error',
-		'@wordpress/i18n-no-placeholders-only': 'error',
-		'@wordpress/i18n-no-variables': 'error',
-		'@wordpress/i18n-ellipsis': 'error',
-		'@wordpress/i18n-no-flanking-whitespace': 'error',
-		'@wordpress/i18n-hyphenated-range': 'error',
+/**
+ * Internal dependencies
+ */
+const wpRules = require( '../rules' );
+
+const wpPlugin = { rules: wpRules };
+
+module.exports = [
+	{
+		plugins: {
+			'@wordpress': wpPlugin,
+		},
+		rules: {
+			'@wordpress/valid-sprintf': 'error',
+			'@wordpress/i18n-translator-comments': 'error',
+			'@wordpress/i18n-text-domain': 'error',
+			'@wordpress/i18n-no-collapsible-whitespace': 'error',
+			'@wordpress/i18n-no-placeholders-only': 'error',
+			'@wordpress/i18n-no-variables': 'error',
+			'@wordpress/i18n-ellipsis': 'error',
+			'@wordpress/i18n-no-flanking-whitespace': 'error',
+			'@wordpress/i18n-hyphenated-range': 'error',
+		},
 	},
-};
+];

package/configs/index.js

@@ -1 +1,15 @@
-module.exports = require( 'requireindex' )( __dirname );
+module.exports = {
+	custom: require( './custom' ),
+	es5: require( './es5' ),
+	esnext: require( './esnext' ),
+	i18n: require( './i18n' ),
+	jsdoc: require( './jsdoc' ),
+	jshint: require( './jshint' ),
+	'jsx-a11y': require( './jsx-a11y' ),
+	react: require( './react' ),
+	recommended: require( './recommended' ),
+	'recommended-with-formatting': require( './recommended-with-formatting' ),
+	'test-e2e': require( './test-e2e' ),
+	'test-playwright': require( './test-playwright' ),
+	'test-unit': require( './test-unit' ),
+};