Upgrade ESLint to v9

[shvlv]

What?

Upgrade ESLint to v9.

Why?

Fixes #64782
Fixes #62496.

ESLint was moving to the new flat config and new API — https://eslint.org/docs/latest/use/migrate-to-9.0.0. The community made great progress supporting v9 — eslint/eslint#18391.

How?

The following parts were updated:

• shared configs from eslint-plugin to support the flat format
• custom WordPress rules to support new APi
• lint-js command to support the v9 CLI
• root ESLint config to support flat format
• root package.json to upgrade ESLint plugins

Several plugins are incompatible with ESLint v9 and were fixed with eslint/compat helper:

• ✔️ eslint-plugin-import . The issue and PR exist. We expect it to be released soon. Note that the forked plugin https://github.com/un-ts/eslint-plugin-import-x supports v9. Was released with v2.31.0
• ✔️ eslint-plugin-react-hooks supports v9 only in [RC version ] (eslint-plugin-react-hooks & "Flat Config" (ESLint 9) facebook/react#28313). We hope it will be released soon. Released with v.5.0.0.
• ✔️ eslint-plugin-testing-library supports flat config but not support updated API. Released with v7.0.0.
• ✔️ eslint-plugin-storybook supports v9 in canary version. But it might be problems with a glob expression. The overall issue - Suport ESLint v9 storybookjs/eslint-plugin-storybook#157. Released with 0.10.0.
• eslint-plugin-ssr-friendly doesn't support flat config and new API. The plugin looks unmaintained; we can consider moving these rules to @wordpress/eslint-plugin. The issue - [Breaking Changes] Support ESLint 9 kopiro/eslint-plugin-ssr-friendly#30.

eslint-plugin-eslint-comments was replaced by @eslint-community/eslint-plugin-eslint-comments - https://github.com/eslint-community/eslint-plugin-eslint-comments (see mysticatea/eslint-plugin-eslint-comments#79 (comment)).

Testing Instructions

Run npm run lint:js.

Current status

1766 problems (1424 errors, 342 warnings)
  33 errors and 109 warnings potentially fixable with the `--fix` option.

With upgrading plugins, new rules were introduced that have to be handled on the root config. Also, maybe the new configuration still does not completely reflect the previous one (while I strived for that goal). Some issues are repeated many times, so they can be easily addressed (like @typescript-eslint/no-explicit-any or no-undef in react-navite-editor).

Also, documentation for eslint-plugin, script, and inside /docs should be double-checked.

[gziolo]

Awesome work @shvlv starting this PR. Thank you so much. The number of breaking changes is overwhelming. It won't be an easy upgrade for the folks using wp-scripts lint. If they were using a custom config, an ignores file, or have some rules disabled as comments in the code, it will require a lot of manual intervention. It is what it is, and we can't do much about it other than document the migration path to make the transition easy. Let's see if we can collectively help to get it to the finish line. I invited a few more core contributors to help with review 😄

[sirreal]

Are there automated migration tools that can help with migration? Were they used in this PR?

It would be helpful for folks dealing with this breaking change to document how they can migrate and what tooling is available.

[shvlv]

Are there automated migration tools that can help with migration? Were they used in this PR?

Yes, tools exist.

@eslint/migrate-config

To migrate config, https://eslint.org/docs/latest/use/configure/migration-guide#migrate-your-config-file could be used. However, as the documentation says, it's appropriate chiefly for static configuration files (yml and json), but our config file has pretty complex logic, so I didn't try it. But maybe it will be a good start for wp-scripts users because I can imagine many of them have no configs or have pretty simple configs.

In projects I participated in, we often used the following approach:

const defaultConfig = require( '@wordpress/scripts/config/.eslintrc.js' );

module.exports = {
	...defaultConfig,
	settings: {
		'import/resolver': {
			typescript: {},
		},
	},
};

But yes, it will not work now for several reasons, and I'm not sure the migration tool could help either.

In general, migration to v9 is pretty complicated for several reasons:

• you should update all ESLint plugins
• you should find the shared config in flat format. Plugins support legacy and new formats but do it in a different way. For some plugins you can use plugin.configs.recommended, but for others it will be plugin.configs['flat/recommended'] .
• you should understand the plugin exposes the object or the array (to be descructed)
• in the case of an array you should iterate over array times to add custom files/ignores properties

But it's complex for the Gutenberg giant monorepo and should be easier for consuming projects.

eslint-transforms

It can be used to migrate custom rules to the new API (https://www.npmjs.com/package/eslint-transforms and https://eslint.org/blog/2023/09/preparing-custom-rules-eslint-v9/). I tried it for @wordpress/eslint-plugin; however, it shows no issues while I get errors in runtime. Hopefully, we will have a small number of custom rules, and only four must be updated.

@eslint/config-inspector

It's the new tool to make debugging easier (https://eslint.org/docs/latest/use/configure/debug#use-the-config-inspector and https://github.com/eslint/config-inspector). It doesn't work if you have config errors. But now it works like the following:

We can consider adding the name property to our configs to make debugging easier. I assume the tool is not so important for Gutenberg package users, but it might be helpful for internal development.

It would be helpful for folks dealing with this breaking change to document how they can migrate and what tooling is available.

Yes, we should mention these tools in the documentation (or a blog post). However, I think documentation with examples of how-to is even more important.

[shvlv]

Last update:

• fixed typescript/eslint config to eslint-recommended as it was originally
• suppress cauthErrors for eslint/no-unused-vars rule - see https://eslint.org/docs/latest/rules/no-unused-vars#caughterrors-none
• exclude *.d.ts files explicitly (I don't know honestly why all ts files were parsed by eslint)
• merged package configs into the parent one (see Using flat config in monorepo: one config file or multiple? eslint/eslint#16960).

Regarding the last one, ESLint v9 doesn't support multiple configurations as it used to. I.e., it stops after finding the parent configuration. I see the pros and cons of this decision. Pros: we have everything in a single place; it's transparent; we can merge duplicated rules. Cons: we already have 700+ lines in the config file. We can keep it as is and consider refactoring in the future. Refactoring can be done in the two directions:

• split big configuration files into several configs splitter logically (for instance, general, package-specific, tests, etc)
• still use the configuration on the package level, but this way, we should update our scripts to run wp-script lint:js several times: globally and additionally for specific packages (not ideal solution, perhaps)

Current status:

✖ 750 problems (407 errors, 343 warnings)
  13 errors and 110 warnings potentially fixable with the `--fix` option.

[marekdedic]

Hi, maybe I understand things incorrectly, but it seems to me that it's still possible to have multiple config files, you just have a different mechanism for using them - importing. So each package can have its own config, which imports some shared general config much like you import and use configs from third-party plugins.

[swissspidy]

This is gonna be a very painful change for the ecosystem. Is there any way we could reduce the burden for users of these packages? For example by simultaneously supporting v8 and v9 or so?

[shvlv]

Hi, maybe I understand things incorrectly, but it seems to me that it's still possible to have multiple config files, you just have a different mechanism for using them - importing. So each package can have its own config, which imports some shared general config much like you import and use configs from third-party plugins.

@marekdedic, I think we are talking about different things. We have the following structure:

.eslintrc.js
package/
  react-native-editor/
    .eslintrc.js

When we run ESLint V8 from the root directory, and ESLint starts to lint files inside react-native-editor, it uses package/react-native-editor/.eslintrc.js because it's the closest file to the current working directory.https://eslint.org/docs/v8.x/use/configure/configuration-files#cascading-and-hierarchy. Even more:

ESLint then searches up the directory structure, merging any .eslintrc files it finds along the way until reaching either an .eslintrc file with root: true or the root directory.

But it does not work in this way now - https://eslint.org/docs/latest/use/configure/configuration-files#configuration-file-resolution:

When ESLint is run on the command line, it first checks the current working directory for eslint.config.js. If that file is found, then the search stops...

That means if you run eslint from the root directory and it contains the configuration file, the inner package/react-native-editor/.eslintrc.js file is ignored completely. (Also root option is not supported anymore).

[shvlv]

This is gonna be a very painful change for the ecosystem. Is there any way we could reduce the burden for users of these packages? For example by simultaneously supporting v8 and v9 or so?

@swissspidy, the problem is @wordpress/eslint-plugin has a few custom rules but mostly configures third-party rules from other plugins https://github.com/WordPress/gutenberg/pull/65648/files#diff-691525462f8b4cac47c3c2e0e2668606f539ed0b3f62f8f6b79dffe7ef38bd9d. The most significant issue is typescript-eslint. To support legacy config, we should install different packages https://typescript-eslint.io/getting-started/legacy-eslint-setup, so I don't see a way to make it work 🤷‍♂️

Other issues are resolvable:

• support legacy and new API in our custom rules
• retain the current configs and add new ones under the flat subdirectory
• find legacy file formats in lint-js scripts command and generate legacy or new config based on that

[marekdedic]

@shvlv You are right, we are misunderstanding each other. :)
If you want to use a different eslint config for different packages, you either have to have one monster-config in the root, or you need to run eslint separately for each package (then either run it in the package folder or pass the config as a --config argument). I was talking about the second case, in which you can create a shared "base" config and extend it on a per-package basis.

[shvlv]

Last updates:

• eslint-plugin-import:2.3.0 doesn't detect node built-in modules correctly. The latest version 2.30.0 triggers "parserPath or languageOptions.parser is required!". So I had to update it to 2.10.0. I hope it's temporary before the new release with [Fix] ExportMap / flat config: include languageOptions in context import-js/eslint-plugin-import#3052 is created).
• packages/block-serialization-spec-parser/shared-tests.js errors suppressed explicitly
• enabled lining for *.d.ts files. It resolves more errors than introduces, so it makes sense while we can discuss it.

[marekdedic]

Hi @shvlv - check out eslint 9.12, I think they may have added exactly what we were talking about last week - see eslint/eslint#18742

[shvlv]

Last updates:

• update eslint-plugin-import to v2.31.0
• remove unnecessary suppressions
• suppress react/no-deprecated in element package
• suppress react-hooks/rules-of-hooks for experimental components (see [eslint-plugin-react-hooks] only allow capitalized component names facebook/react#25162). It's forbidden to prefix components with __.
• replace eslint-comments/ with @eslint-community/eslint-comments/ rule prefix

We are almost there:

✖ 354 problems (13 errors, 341 warnings)
  5 errors and 108 warnings potentially fixable with the `--fix` option.

@marekdedic I didn't test the last ESLint release, but from the description, I see it's exactly what we talked about. But when I'm thinking about root .eslint.config.js... There are a lot of package-specific configs. So maybe what we have now with a single root config is even better. But we should agree on the decision with someone from the maintainers.

[shvlv]

Hi @gziolo, technically, we are close to finishing. We have to additionally test the scripts package as the standalone project dependency. Documentation should be double-checked and updated. eslint-plugin-import and eslint-plugin-react-hooks (used in the eslint-plugin package) were released with stable versions and support ESLint v9. Rest plugins are not stable, but it's only part of the root Gutenberg config where we have the lock file, so it's possible to move forward as is.

The main question is whether we are going to introduce this breaking change. You can check my consideration here: #65648 (comment). I think the eslint-plugin can't support v8 and v9 simultaneously.

[manzoorwanijk]

Any progress on this?

[shvlv]

Any progress on this?

We are trying different options to make the upgrade smoother for end users. But there is no clear and robust solution. Maybe we can make @wordpress/scripts support eslint: ^8 || ^9 with peer or regular dependencies. But I'm still not sure it will work (and I didn't complete the testing locally).

[shvlv]

I've checked the compatibility issue once more. The important notes:

• ESLint started to support flat configs in version 8.21 (https://eslint.org/blog/2022/08/eslint-v8.21.0-released). It's possible to enable flat system with the ESLINT_USE_FLAT_CONFIG environment variable (https://eslint.org/docs/v8.x/use/configure/configuration-files-new) set to true.
• ESLint v9 still supports legacy (eslintrc) configs. The ESLINT_USE_FLAT_CONFIG should be false. The support will be dropped in version 10 (https://eslint.org/blog/2023/10/flat-config-rollout-plans/).
• CLI can work in flat mode or eslintrc mode depending on ESLINT_USE_FLAT_CONFIG variable and root config format
• typescript-eslintsupports "eslint": "^8.57.0 || ^9.0.0" (https://github.com/typescript-eslint/typescript-eslint/blob/4dbf48b8eec0321babb4293a1be71b54dd00c018/packages/typescript-eslint/package.json#L60)
• rules API deprecations affected WordPress ESLint Plugin were introduced in ESLint v8.38-8.49 (https://eslint.org/blog/2023/09/preparing-custom-rules-eslint-v9/)

This means we can support the same range as typescript-eslint. I changed peer dependencies for ESLint plugin peer dependency to ^8.57.0 || ^9.0.0 and Scripts dependency to ^8.57.0 || ^9.11.0. Also, the deprecation notice were added (it's visible regardless ESLint v8 or v9 is used):

Deprecated eslintrc configuration file detected. The support will be finished soon. See #65648 for details.

Sure, the text should be updated to refer to the updated documentation with a migration guide.

Additionally ESLint v9 emits ESLintRCWarning:

ESLintRCWarning: You are using an eslintrc configuration file, which is deprecated and support will be removed in v10.0.0. Please migrate to an eslint.config.js file. See https://eslint.org/docs/latest/use/configure/migration-guide for details. An eslintrc configuration file is used because you have the ESLINT_USE_FLAT_CONFIG environment variable set to false. If you want to use an eslint.config.js file, remove the environment variable. If you want to find the location of the eslintrc configuration file, use the --debug flag.

I've tested the following combinations (linting works as expected, both configurations are supported):

ESLint	Config	Result
v8	.eslintrc	WordPressScriptsWarning
v8	eslint.config.js	no warnings
v9	.eslintrc	ESLintRCWarning, WordPressScriptsWarning
v9	eslint.config.js	no warnings

Also, I've rebased onto trunk. The new version of rules-of-hooks rule forbids hooks started from underscore. I've suppressed entries with inline comments, but it conflicts with react-compiler. That's why I suppressed those files with gutenberg/rules-of-hooks-suppression in the main config. The issue should be addressed later.

[gziolo]

@shvlv, excellent progress on backward compatibility support for ESLint 8 in existing projects. Overall, it's a lot of changes so it might require a larger group of folks from @WordPress/gutenberg-core to chime in to get it to the finish line.

Also, I've rebased onto trunk. The new version of rules-of-hooks rule forbids hooks started from underscore. I've suppressed entries with inline comments, but it conflicts with react-compiler. That's why I suppressed those files with gutenberg/rules-of-hooks-suppression in the main config. The issue should be addressed later.

@Mamaduka and @tyxla, can you check these changes based on your experience on the work with React compiler?

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @ghostintranslation.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Unlinked contributors: ghostintranslation.

Co-authored-by: shvlv <[email protected]>
Co-authored-by: gziolo <[email protected]>
Co-authored-by: sirreal <[email protected]>
Co-authored-by: marekdedic <[email protected]>
Co-authored-by: swissspidy <[email protected]>
Co-authored-by: manzoorwanijk <[email protected]>
Co-authored-by: tyxla <[email protected]>
Co-authored-by: stein2nd <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[tyxla]

@shvlv, excellent progress on backward compatibility support for ESLint 8 in existing projects. Overall, it's a lot of changes so it might require a larger group of folks from @WordPress/gutenberg-core to chime in to get it to the finish line.

Also, I've rebased onto trunk. The new version of rules-of-hooks rule forbids hooks started from underscore. I've suppressed entries with inline comments, but it conflicts with react-compiler. That's why I suppressed those files with gutenberg/rules-of-hooks-suppression in the main config. The issue should be addressed later.

@Mamaduka and @tyxla, can you check these changes based on your experience on the work with React compiler?

There's no way around it, unfortunately. React Compiler needs the rules of hooks to be followed in order to work for the files in question. Prefixing a hook with an underscore, passing a hook around as a prop, or conditionally executing a hook are all violations that are not allowed. As a temporary fix, disabling the rules of hooks for those files (which was done here) is one way to go - although we should make sure that it's only temporary. Alternatively, we've used the 'use no memo'; directive (see #66361) to instruct the React Compiler to skip optimizing a particular file.