What's up with the two parserOptions?

[Jutanium]

I'm new to ESLint. There appear to be two parserOptions, one of which is often redundant.

If I set tsconfigRootDir to a directory, ESLint knows where to find my project. Why should I set project?

As a side note, project is an ambiguous name - what kind of project? What kind of value? (The possible true value makes this even more confusing.)

[JoshuaKGoldberg]

Some context: @Jutanium and I paired on Twitch to set up a new Astro+Solid+TypeScript project with linting. The typescript-eslint setup steps were mostly smooth until Typed Linting (#6826, #6828). This was another issue we had that I asked Dan to start as a discussion here: the two config values weren't intuitive in our pair, and I think it'd be good to discuss if we can make it simpler and/or more obvious what things do.

For example, if the user specifies tsconfigRootDir, maybe we could default project to true?

[bradzacher]

project is explained deeply in the parser docs.

tsconfigRootDir is explained in the parser docs.

Both of these options are described in the getting started guide and the above docs sections are linked as well (though the links are at different points in the guide)

the two config values weren't intuitive in our pair

What would be the preferred way to document them aside from what's already in the guide?

[JoshuaKGoldberg]

@bradzacher I think the direction here is more: just reading a config, they're not very intuitive. So no matter how much we document them, it's not ideal. A goal beyond documenting them could be ideating a way to set up the options that makes more sense on the surface.

[bradzacher]

I guess my question would be "why does it matter if a config option is meaningless without the docs?" - config is an inherently complex thing - so it's kind of expected that either "you know what you're doing" or that you're referencing the docs.

As an example - TS project references are configured via the references config property. What does that mean? What does referencing a project mean? What will setting this do to by typecheck?

Not saying we can't improve at all! I'm just trying to gauge the scope and thinking.

[bradzacher]

Why are there two?

Well until a month or so ago you had no option but to tell us the explicit paths to your tsconfig(s).
However if you set project: './tsconfig.json' - what is that path relative to? Well as a user it's obvious "this path is relative to my .eslintrc.js file". However for our parser it's not that simple!

Unfortunately ESLint doesn't tell the parser the path to the config file for various reasons [1] so the only paths we explicitly know about are (1) the CWD and (2) the path to the file currently being linted. (2) is obviously useless as a marker to resolve a relative path against so we have to leverage (1) the CWD.

The problem you run into is that the CWD is dynamic! It's not uncommon to cd into a subfolder and run the lint. If a user does that then the path we resolve against has changed and now we can't find the project!
By setting tsconfigRootDir: __dirname it gives us that constant marker to resolve against so you can run your lint anywhere within your project without it breaking.

Why do we allow relative paths at all?

A few reasons reasons:

1. For most lint runs tsconfigRootDir doesn't actually matter - people mostly just run the lint from the project root - so the difference between relative or absolute doesn't matter.
   • Monorepo setups make it more common to do yarn lint from a subdir, but most of the time people still do yarn lint ./package/foo instead of cd package/foo && yarn lint because the latter requires scripts in the package directory.
2. It's much nicer to define

   {
     project: ['./one/tsconfig', './two/tsconfig', /* ... */],
     tsconfigRootDir: __dirname,
   }

   As opposed to like

   {
     project: ['./one/tsconfig', './two/tsconfig', /* ... */]
       .map(p => path.resolve(__dirname, p)),
     // or
     project: [`${__dirname}/one/tsconfig', '${__dirname}/two/tsconfig', /* ... */],
   }

3. In some setups it can actually desirable to have relative paths resolved to the CWD. For example in a monorepo you could cd package/foo && yarn lint and have ./tsconfig.json resolve to package/foo/tsconfig.json instead of the project root as a kind of automatic project resolution! (note - some people actually do rely on this behaviour!!!)

---

With the new project: true config, tsconfigRootDir instead acts as a marker for where our algorithm should stop traversing when looking for a tsconfig that contains the linted file. It's a small perf optimisation but ultimately wouldn't change the result of the parser (i.e. it's not strictly necessary).

---

Worth noting that you may not realise it but there's actually THREE parser options for type-aware linting - the third being projectFolderIgnoreList. This option was added not long after we added support for globs in parserOptions.project - it was added because some users noted that using globs would match ./node_modules/package_that_ships_a_tsconfig_for_no_reason/tsconfig.json - which slowed down linting as our parser would create a useless ts.Program for that config.

I don't think there's many (if any) people that change this from its default of "ignore node_modules" - but it's there as an option!

---

[1] reasons ESLint doesn't tell the parser about the config file path:

• You can have n different multiple config files which "cascade" merge into a single ESLint config.
  • ESLint keeps cascading until it (a) reaches a config with root: true or (b) reaches the disk root. So technically a config outside the "project dir" could influence the project's config!
  • In the past you could even have a global, "personal" config file in your home folder which would cascade into the project config. This has since been deprecated and removed in ESLint v8.
• You can specify any config option via cli arguments - you could specify your entire config via cli arguments! CLI arguments explicitly override any config specified in any config file.

The cascading and overriding means that ultimately ESLint does not keep track of where the final value for each property came from - it just knows the final value. So knowing one of the possible config paths is technically meaningless in the world of ESLint!

[bradzacher]

Some fun facts on the history of the names - you can trace the names project and tsconfigRootDir all the way back to their original implementation almost 5 years ago!

parserOptions.project

project might sound ambiguous until you consider it in the context of TypeScript. TypeScript's CLI accepts a --project argument to specify the path to a tsconfig.json to build. TypeScript also allows you to specify "project references" which are similarly paths to tsconfig.jsons.

At some point we probably should have renamed it to parserOptions.projects given most cases will pass an array of paths or globs, but TBH it never seemed worth the user-land churn/overhead of forcing people to add a single character to their config "just because it's technically correct".

parserOptions.tsconfigRootDir

tsconfigRootDir is kinda poorly named and always has been given that project was named at the same time - it probably should have been projectRootDir. TBH I've never actually thought about renaming it - the disjoint naming never even occurred to me heh.

parserOptions.projectFolderIgnoreList

Probably should have been called projectGlobIgnoreList to better describe when specifically it is applied, but it's probably "good enough"

[bradzacher]

In regards to the best path forwards...

For example, if the user specifies tsconfigRootDir, maybe we could default project to true?

Personally I don't think we should make such a change - I think people should always provide project to explicitly opt-in to type-aware linting. If we start implicitly setting it then that's a really large breaking change that might impact users more than we think - for example if a shared config sets tsconfigRootDir for whatever reason then that implicitly opts the lint run in and hugely impacts the lint run duration.

We do have project: null to allow people to opt-out of type-aware linting, but it would be kind of sucky if you added shared config and it just implicitly opted you in by accident!

---

If I had to specify a "north star" - I would probably want to introduce a state like this to group the config:

type Path = RelativePath | AbsolutePath | GlobPath;
interface ExplicitProjectConfig {
  /** Paths to the tsconfigs to explicitly load for type information */
  tsconfigPaths: Path[];
  /** Paths to ignore when resolving globs from `tsconfigPaths` */
  globIgnoreList?: Path[];
  /** Absolute path to the project root to use when resolving relative paths */
  relativeRootDir?: AbsolutePath;
}

interface AutomaticProjectConfig {
  /** Explicitly opt-in to the automatic resolution and also a disjoin union field??? */
  automatic: true;
  /** Absolute path to the project root to stop traversing at when looking for tsconfigs */
  traversalRootDir: AbsolutePath;
}

interface ParserOptions {
  /**
   * `null` allows people to explicitly opt folders out of type-aware linting
   * for specific paths. It allows users to write configs as "type-aware-first" and
   * have non-type-aware linting being the edge case applied via `overrides` by
   * the config `plugin:@typescript-eslint/disable-type-checked`
   */
  project: ExplicitProjectConfig | AutomaticProjectConfig | null;
}