Single run detection for type-aware linting

[bradzacher]

Type-aware linting has historically been a bit of a slow process. By-and-large - having to wait for TS to do a typecheck of your codebase before linting is where most of the runtime usually goes.

v4.27.0 (#3512) added a new feature which allows the parser to detect if it's running in the CLI.
When detected - it will switch to a different TypeScript API that is faster and more direct.

Our initial testing has shown about a 10% reduction in runtimes for CLI runs.
But we'd like some feedback about it.

Please give this a go and let us know how it works for you.
(If you're unsure if it's working, you can turn on debug logging (DEBUG=typescript-eslint:* yarn eslint) and look for the string Detected single-run/CLI usage.)

In the coming weeks we'll be looking to turn this feature on by default for all users - so feedback is valuable to help us catch edge-cases early!

Caveats:

• This new codepath is not compatible with the IDE usecase. It should not even be executed in the IDE. If you encounter IDE weirdness after opting-in, please file a bug.
• This new codepath is not compatible with custom scripts that use ESLint to check the same file(s) multiple times. If you encounter any weirdness after opting-in, please file a bug.
  • If your custom script just uses the ESLint API to lint each file once - then it is compatible, but automatic detection won't work. You can set the environment variable manually to force the codepath.

File a Bug

If the feature doesn't work quite as expected - please file an issue with in-depth information so that we can look into it and help tune this feature appropriately before turning it on as the default.

The more information you give - the easier it is for us to look into.

The best way to file an issue is with a repro repo so that we can immediately look into and reproduce the problem.

Opting-In

You can opt-in to this feature in one of two ways

parserOptions.allowAutomaticSingleRunInference = true

  module.exports = {
    parser: '@typescript-eslint/parser',
    parserOptions: {
+     allowAutomaticSingleRunInference: true,
      project: ['./tsconfig.json'],
    },
  };

This will turn on the inference logic which should allow the parser to auto-detect when you do an ESLint run from the CLI (eg yarn eslint src, or yarn lint when lint is an npm script pointing at eslint).

TSESTREE_SINGLE_RUN=true

You can use this environment variable will force the parser to use this new codepath.

$ TSESTREE_SINGLE_RUN=true npx eslint src
$ TSESTREE_SINGLE_RUN=true yarn lint

This does not turn on the inference logic, and instead just forces that your run is treated as a "single run".

---

Technical details

Our parser has to support both the "one-and-done" usecase of the CLI, as well as "persistent" usecases of tools like IDEs. The latter case introduces complexities due to having to continually update the TS data structure as the code changes.

Previously we had exactly one codepath in the parser, we would create a "watch program" for each parserOptions.project that you passed in, and we would assume every single run was a "persistent" run. This meant we ultimately did a lot of unnecessary work during CLI runs. On top of that - the "watch program" API carries with it overhead - even if you make no changes to the code.

Last week we added codepaths to allow us to use a more standard TS "program". This is where the real speedup is as the standard program does not have the same overhead that a "watch program" does.

The new options just do some basic inference to guess if you're doing a CLI run (right now basically: "is it a CI run?", "is the script node_modules/.bin/eslint?"), and if you are then use the new codepath.

[bradzacher]

If you have a question about this feature or how to turn it on - feel free to comment below.

If you have a BUG report, please file an issue.
If you report a bug in the comments, we'll just ask you to file an issue... so please save us all time.

[bobaaaaa]

Just to make sure: This works only with enabled parser option project? (https://github.com/typescript-eslint/typescript-eslint/tree/master/packages/parser#parseroptionsproject)

[bradzacher]

This works only with enabled parser option project

Correct!
This option does nothing without project. Without it - you don't need any perf improvement as you're not doing type-aware linting!

So yes - you still need to pass project in so that we know how to build the typescript program for your codebase.

I'll update the OP.