Change Request: Support "cross-file" linting

[JoshuaKGoldberg]

Which packages would you like to change?

• @eslint/compat
• @eslint/config-array
• @eslint/config-helpers
• @eslint/core
• @eslint/mcp
• @eslint/migrate-config
• @eslint/object-schema
• @eslint/plugin-kit

What problem do you want to solve?

"Cross-file" or "multi-file" linting is an increasingly common need in many lint plugins. Two common user needs are from:

• Cross file types like typescript-eslint's typed linting.
• Import analysis in plugins like eslint-plugin-import and eslint-plugin-import-x

ESLint today does not have any native concepts of cross-file dependencies, stateful parsing, or type information. It does not provide APIs for them. As a result, userland plugins have needed to put cross-file parsing into parsers such as @typescript-eslint/parser. This is the only way to get it to work in ESLint right now, but is problematic:

• ESLint's parsers are intended to be isolated and stateless. Using them for contextually aware and/or stateful logic breaks that paradigm.
  • ESLint's --cache is fundamentally unreliable when users opt into any form of cross-file linting, as cache invalidation does not account for cross-file information.
• Parsers don't receive information like a full list of files, what form of session ESLint is being run in, etc. - which would be useful for optimizing cross-file things.
  • (From my anecdotal recollection) ESLint's --concurrency often ends up being slower on large codebases using typed linting, as each thread/worker instantiates TypeScript type services that end up significantly overlapping in functionality

What do you think is the correct solution?

I personally have been advocating for a two-step approach:

1. Since users are using plugins for cross-file linting now (and have been since at least typescript-eslint was introduced in 2019), adding in rudimentary stateful information to parsers.
2. In the big ESLint rewrite, add a more native concept of a stateful entity. Something that has setup and teardown phases, knows the full list of files, and can instantiate services such as a module dependency graph or a type-checker.

The feedback we've gotten from the TSC has been that only the latter is desirable.

Participation

• I am willing to submit a pull request for this change.

Additional comments

I asked about this internally and was suggested by @nzakas to post an issue. This is that issue! 🙂 Is there other information that would be useful for me to file that isn't in the major past discussions? For quick reference:

• Complete rewrite of ESLint eslint#16557: past discussion opening up this rewrite repo & touching on points such as making ESLint type-aware and/or project-aware
• Feedback Wanted: Project-aware ESLint eslint#16819: further discussion on these topics
• feat: parsing session objects rfcs#102: has a lot of links & text explaining needs around session information
• Typed linting optimizations blocked by ESLint core typescript-eslint/typescript-eslint#11677: further explains the typescript-eslint perspective & list of needs blocked on stateful services

Terminology aside: I've personally been calling this "cross-file" linting to convey that it uses an understanding of code built up across-files. "Multi-file" makes me think the linter is reporting on multiple files at once, or that lint rules are targeted to multiple files at a time. I'm not intending to suggest completely redesigning the core concept of "each rule looks at a file at a time". Just that the information they use on each file is more informed.

[nzakas]

Thanks for filing this. I think it's a good idea to start considering how to do this. I'd like to get async into the core first, which would give us more options, but ultimately we should head in this direction.

I'd like to make sure we differentiate between cross-file linting and project-aware linting, as these are two different things in my mind:

• Cross-file linting is the ability to follow imports in a file that is currently being linted. If a.js imports b.js, then we follow and parse b.js. (To what end? TBD.) The canonical example is we can tell that an imported binding doesn't exist in b.js.
• Project-aware linting is the understanding of the entire project when linting. The canonical example is finding unused exports in a project.

I don't see these as mutually exclusive, I think we can do both in the long-term. In the short-term, cross-file linting is more achievable and I think a significant portion of the work could be reused for project-aware linting in the future.

[JoshuaKGoldberg]

Well that's promising! For "async into the core", what is the status of that? What can be helped with? Are there issues/links we can look at?

[nzakas]

It's kind of an amorphous task at the moment because we don't really know what the final state is going to look like. I've been tinkering on my own, trying to refactor things in an effort to see where async processing can be fit in. This is the issue I opened for that:
eslint/eslint#18787

After we get v10 out the door, I'll be circling back to pick things up. The expected outcome of that work is an RFC describing a new low-level API that supports asynchronous operations.