This is a good question, thanks for prompting on the docs. cc @bradzacher as chief tsconfigRootDir advocate - I'm under the impression it is still needed, to make sure we don't accidentally resolve one higher than the project root.

tsconfigRootDir is how we orient ourselves in disk for all of our type-aware linting. Without it there are only two absolute paths that we know - the CWD and the file being linted (and in some cases the latter isn't even absolute!!).

For project: string | string[] we use it to resolve relative paths.

For project: true and projectService: true we use it as a stopping point to cut off traversals when finding tsconfigs. Mostly this just prevents the "not covered by a tsconfig" case from ballooning out to an unbounded number of disk lookups though.

Why isn't CWD enough? Well because you can CD around the project - so CWD is dynamic! ./tsconfig.json is meaningless if CWD is dynamic.

@bradzacher thank you for explaining! That's very insightful.

@JoshuaKGoldberg @bradzacher follow-up question: How can one set tsconfigRootDir in a shareable config? Because if one sets it to __dirname, then it will resolve to the path inside node_modules when invoking ESLint in the consumer.

@MariaSolOs

We have more or less the same question 😂 #10507 (comment)

But I think bottom line the advice for now would be that the end user is expected to configure typed linting, including tsconfigRootDir. You may want to watch the progress of #10507 to see where we land on providing this as a utility ourselves.

Yeah it's not possible to do it from a shared config -- which has always been one of the problems, sadly.
With flat configs technically you could just make your config a function and then the user calls it like myConfig(__dirname) if you really want -- but it's also just as easy to document that you should set it in you config.

NOTE that if the user doesn't set tsconfigRootDir then for project: string | string[] it defaults to process.cwd() -- which "often" works just fine. The time that will break is if you're in a "JS monorepo" structure and someone does like cd packages/eslint-plugin && yarn eslint -- then the CWD is wrong and things break. But if everyone just runs commands from the repo root then process.cwd() === __dirname and it all "just works".

With projectService: true and project: true no value === no restriction and we'll just traverse the folder tree all the way to the disk root -- so again not the "end of the world" but it can waste some time for each file if you're not careful. Again it should "just work" though cos if you've configured type-aware linting correctly then every file has a corresponding tsconfig.json and so we'd stop traversing at that level so yeah "magically just works"