Configs: Switch name verbosity of recommended and recommended-requiring-type-checking

[JoshuaKGoldberg]

Before You File a Proposal Please Confirm You Have Done The Following...

• I have searched for related issues and found none that match my proposal.
• I have read the FAQ and my problem is not listed.

Description

We recommend most small-to-medium-sized projects (defined as projects where the cost of the type checker on linting is not significant) use "recommended requiring type checking" (https://typescript-eslint.io/docs/linting/configs):

We recommend all TypeScript projects extend from this configuration, with the caveat that rules using type information take longer to run. See Linting with Type Information for more details.

But, in my experience, most projects haven't been enabling it - even with our new config docs. Users are accustomed to enabling exactly one "recommended" preset per plugin.

Proposal: let's breaking change switch the names so that "recommended" includes typed rules and "recommended without type checking does not?

<=5.x	>=6.0
recommended	recommended-without-type-checking
recommended-without-type-checking	recommended

Impacted Configurations

• plugin:@typescript-eslint/recommended
• plugin:@typescript-eslint/recommended-requiring-type-checking

Additional Info

If we do this, we'll need to hold users' hands through the migration. We'll want to at least:

• Write a migration guide covering what users will have to change and why:
  • For projects that can use typed rules: add parserOptions.project if it doesn't yet exist
  • For projects that cannot: rename recommended to recommended-without-type-checking
• Link to that guide on the top of https://typescript-eslint.io/docs/linting/configs
• Make the error message for using a typed rule without parserOptions.project more informative & link to that guide

[Josh-Cena]

I disagree—"linting with type-checking" is not easy to teach.

"recommended" is a universal config name across plugins. If it's the first time I start using some plugin, turning on "recommended" will be the very first thing I do when trying it out—even before I start reading documentation. Instantly running into errors about misconfigured projects is not good UX. (Some people don't even read documentation at all!)

On the other hand, I'm still convinced that type-aware linting is not universal practice, maybe not even the majority. "recommended-requiring-type-checking" is a next-level option, not a starter one.

[JoshuaKGoldberg]

very first thing I do when trying it out—even before I start reading documentation
Some people don't even read documentation at all!

That is bad behavior. You and they should not work that way. 🙂 . Please read docs?

Keeping typed rules out of the recommended ruleset seriously limits what this plugin is able to provide out-of-the-box. If people use the plugin only for the basic needs, they're missing out on the most powerful & useful rules.

IMO it's better for the plugin to give an informative error explaining how to fix a user's vague guesses at the right configuration. Then, the user is forced to read the docs and set up the tool properly.

On the other hand, I'm still convinced that type-aware linting is not universal practice, maybe not even the majority. "recommended-requiring-type-checking" is a next-level option, not a starter one.

This is bad (as in: I agree, that's how the world uses the plugin, and we should change that). The plugin should not be expected to run that way 🙂. Type-aware linting -especially once the main performance issues are mitigated- is the best way to run the plugin. That's why we recommend it.

[bradzacher]

I love this idea in theory - the issue is that it's going to be a major breaking change for most of our users - which is difficult to stomach because of how much effort it would take to fix. Either people need to update their config to change their recommended configs around, or they need to figure out how to configure type-aware linting.

Either way it would probably force a lot of people to stay on the old version for a long while.

---

I think people don't use type-aware linting for a few reasons:

1. •it's unknown to them* - they haven't read the docs / followed some blog that told them what to do
2. it's a pain to config - if you've got lots of tsconfigs in weird places then you can't use glob configs easily. if you've got weird structures then it's a pain to config. if you haven't read the docs then it's a pain to config 🤦.
3. performance - it's slow on large repos.
4. OOMs - even if you don't care for the perf - some repos are just big enough to completely OOM which causes (2) as you have to get crafty in setting up workarounds.

This issue specifically addresses (1), but I think before we do that ideally we need a solution for (2), (3) and (4).

(2) config pains

The painpoint of (2) is generally two things:

1. tsconfigRootDir - people don't read the docs and don't know about it.
2. pointing at all the projects in your repo.

We could actually fix both of these if we implement an automatic search algorithm for tsconfigs (#101). I believe VSCode (or is it the ts LSP?) has something like this already. In a nutshell: when you open a file, the system will walk up the tree to find the nearest tsconfig which includes the file and use that.

(3) performance

I don't know if there is anything we can really do here because we have an absolute lower-bound of the build time for the project.

Right now we rely upon a full build of the project before we start linting. I wonder if TS has a mechanism to let us do lazy builds (i.e. here's a file - just build its dep graph and absolutely no more). Maybe that sort of optimisation would require something like microsoft/TypeScript#47947?
This would require a lot of investigation.

Also we've never done any concerted performance profiling effort on the tooling to find hotspots / problems. It's possible that we waste time redoing things unnecessarily. For example a while ago Ben/James found we were wasting a lot of time due to our use of incremental build APIs.

If TS got faster, we would to... eg microsoft/TypeScript#30235 would help. Though we would need eslint/rfcs#87 to support that world. Or perhaps something like synckit would bridge that gap?

(4) OOMs

Sadly TS isn't really made for having multiple programs in the same thread simultaneously like we do. I think vscode gets away with it by either (a) one worker thread per tsconfig or (b) lazy type computation.

I documented this problem in depth here: #1192 (comment)

Side note that (3) and (4) would potentially be fixed by #4183. Or rather less fixed and more worked-around. (a) Isolate each tsconfig into a thread = no more OOMs (b) typecheck in parallel = faster perf.