Support ESLint v9

[MikeMcC399]

Request

This is a request for the eslint-doc-generator to support usage in an ESLint v9 environment.

Installing should produce no warnings.

Why it's needed

ESLint v9 is the current version. eslint-doc-generator assists in generating standardized documentation sections independently of plugin authors. This is possible on ESLint v8 and earlier versions.

It would be beneficial to users of plugins working under ESLint v9 to have support for this version. This would enable a continued high standard of plugin documentation information available.

Edit: Since Oct 5, 2024 ESLint v9 is the lowest supported version of ESLint - see https://eslint.org/version-support/.

Related issues

• Support ESLint flat config #376
• Peer dependency warnings on ESLint v9 #525
• ESLint v9 Support typescript-eslint/typescript-eslint#8211
• feat: update templates for eslint v9 eslint/generator-eslint#179

[bmish]

I would like to make sure we work with ESLint v9. However, I'm not actually sure of any ESLint v9 specific issues.

The peer dependency issue in #525 is not really specific to ESLint v9.

Besides that, is there any actual problem using it with ESLint v9?

[ljharb]

since eslint 9 defaults to flat config, i assume #376 is a blocker

[bmish]

I haven't really identified a specific blocker with flat configs. That issue was more intended to investigate whether flat configs will need additional work to support. As long as flat configs are exported from plugins using the existing configs object, we should be able to identify them. The problem is, many plugins are exporting flat configs only via string exports (const recommended = require('eslint-plugin-foo/configs/recommended');), and that isn't detectable really. Discussed more in eslint/eslint#18095.

[MikeMcC399]

@bmish

Are you going to pick this up some time? I see that https://typescript-eslint.io/blog/announcing-typescript-eslint-v8 brings in ESLint v9 support and that was one of the blockers.

[MikeMcC399]

Installing eslint-doc-generator produces several deprecation warnings including

npm warn deprecated [email protected]: This version is no longer supported. Please see https://eslint.org/version-support for other options.

Subsequent npm ci shows:

$ npm ci
npm warn ERESOLVE overriding peer dependency
npm warn While resolving: @typescript-eslint/[email protected]
npm warn Found: [email protected]
npm warn node_modules/eslint
npm warn   dev eslint@"^9.12.0" from the root project
npm warn   8 more (@eslint-community/eslint-utils, eslint-compat-utils, ...)
npm warn
npm warn Could not resolve dependency:
npm warn peer eslint@"^6.0.0 || ^7.0.0 || ^8.0.0" from @typescript-eslint/[email protected]
npm warn node_modules/eslint-doc-generator/node_modules/@typescript-eslint/utils
npm warn   @typescript-eslint/utils@"^5.38.1" from [email protected]
npm warn   node_modules/eslint-doc-generator
npm warn
npm warn Conflicting peer dependency: [email protected]
npm warn node_modules/eslint
npm warn   peer eslint@"^6.0.0 || ^7.0.0 || ^8.0.0" from @typescript-eslint/[email protected]
npm warn   node_modules/eslint-doc-generator/node_modules/@typescript-eslint/utils
npm warn     @typescript-eslint/utils@"^5.38.1" from [email protected]
npm warn     node_modules/eslint-doc-generator

[MikeMcC399]

@bmish

• Are you open to contributions to move the repo forward? It looks like you have been the major contributor all along.

• As you know, eslint-doc-generator has been used (on your advice Automate docs with eslint-doc-generator cypress-io/eslint-plugin-cypress#115) to generate documentation for eslint-plugin-cypress and it's referred to in the eslint-plugin-cypress/CONTRIBUTING.md. So I'd like to help to ensure that eslint-doc-generator continues to be applicable by being reasonably up-to-date.

[bmish]

@MikeMcC399 yes I am open to contributions so please continue filing issues/PRs with any suggestions. I am busy traveling recently but would like to get things updated/modernized in this repository in the coming months, and any help is welcome.

[MikeMcC399]

@bmish

Thanks very much for your positive reply! I'll make a start by highlighting some suggestions and I'll submit PRs as far as I am able to do.

[MikeMcC399]

@bmish

• First PR in chore(deps): update eslint to 8.57.1 #530 for your review

[MikeMcC399]

• I submitted a set of dependency updates in Oct 2024, which have been merged and have moved the repo forward. I'm not able to tackle all open issues though (for example Migrate @typescript-eslint/* linting to 7.* #545), so hopefully @bmish (or others) will be able to devote time to the open issues.

[bmish]

@MikeMcC399 really appreciate all the issues and PRs you filed.

I believe I have addressed everything related to updating the dev environment (Node, ESLint, TypeScript, and all other dependencies) for this repository. Please let me know if I have missed anything.

I do apologize for the delay, as there were a LOT of issues to untangle, and I was traveling and had other commitments the past few months.

This should enable much easier development going forward.

I'd like to release a major release soon to clear the pipeline with the breaking change of dropping all the old Node versions:

• Require Node 18, 20, 22+ #575

Are there any other breaking changes you had in mind that we should consider for inclusion with that? We don't necessarily need to include anything else, as nothing else is ready now, and we can perform additional major releases later when other things are ready. Just let me know what you plan to work on next or what you had in mind.

[MikeMcC399]

@bmish

really appreciate all the issues and PRs you filed.

I'm glad to have been able to assist!

I believe I have addressed everything related to updating the dev environment (Node, ESLint, TypeScript, and all other dependencies) for this repository. Please let me know if I have missed anything.

• I would support Drop support below ESLint v8 #582 which bumps to "eslint": ">= 8.57.1". This is equivalent to eslint@maintenance. Users who need support for earlier (now unsupported) versions could just stay with the existing [email protected] release.

I do apologize for the delay, as there were a LOT of issues to untangle, and I was traveling and had other commitments the past few months.

I understand that the migration needed a lot of changes. I already came to that conclusion when I evaluated whether I could do it or not!

This should enable much easier development going forward.

I'd like to release a major release soon to clear the pipeline with the breaking change of dropping all the old Node versions:

• Require Node 18, 20, 22+ #575

Are there any other breaking changes you had in mind that we should consider for inclusion with that? We don't necessarily need to include anything else, as nothing else is ready now, and we can perform additional major releases later when other things are ready. Just let me know what you plan to work on next or what you had in mind.

I suggest you go ahead with the (breaking) release. I wasn't planning on any other contributions.

Good luck and thanks for the changes 🙂