Change Request: expose shouldUseFlatConfig (or a wrapper API that selects between the two formats automatically)

[cprussin]

ESLint version

v8.38.0

What problem do you want to solve?

Currently, neither findFlatConfigFile nor shouldUseFlatConfig are exported. This makes it impossible for tools that use the API directly such as jest-runner-eslint to support both config formats without manually reproducing the behavior in those functions.

What do you think is the correct solution?

Ideally, it would be great if there were an API exposed (probably in unsupported-apis.js) that would wrap the FlatESLint and ESLint apis and select the right one automatically, behaving the same as the CLI.

Short of that, exposing shouldUseFlatConfig or findFlatConfigFile is enough to prevent tools having to manually roll their own logic here.

Participation

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

Additional comments

I'm happy to submit the fix for this, I'll just need guidance by those who would approve it on which, if either, approach would be acceptable.

[nzakas]

I'm not clear on the ask here: are you asking for a way to determine if flat config should be used? Or are you asking for a way to find the flat config file?

There is already an open issue for adding a method to FlatESLint to find the config file:
#17046

[cprussin]

@nzakas not exactly the same, we don't need to find the flat config file, we need to know which config format is being used so that we can call the correct APIs (and remove options that aren't supported by the FlatESLint API but are supported by the ESLint api). See https://github.com/jest-community/jest-runner-eslint/pull/176/files#diff-f5651cdb0e581e985fe919453f1a58dfba958912e3c5e7ddfb4f31057483eb17R106-R166 for the specific use case.

I think the ideal ask is to expose an API that behaves exactly as the CLI does -- meaning it would determine which config format is being used and would call ESLint or FlatESLint as needed transparently. Short of that, the ask is to expose shouldUseFlatConfig so that at least that function doesn't have to be copy-pasted if a tool wants to support both config formats simultaneously, as the ESLint CLI does.

[nzakas]

I think the ideal ask is to expose an API that behaves exactly as the CLI does

I don't think we can do this and have it make sense. The CLI operates on a couple of different signals. If eslint.config.js is present, then it uses flat config, but also if the ESLINT_USE_FLAT_CONFIG environment variable is set to true (see the docs). Eventually, all of this will go away, so I'm also not sure we want to have this written in stone in some API.

With the new FlatESLint#findConfigFile() method, you can determine if a eslint.config.js file is present, would that be enough?

let eslint = new FlatESLint(options);
if (!(await eslint.findConfigFile())) {
   eslint = new ESLint(options);
}

[cprussin]

It's an improvement, and it's probably good enough. But it's still not perfect, as ideally tooling like jest-runner-eslint that effectively behave as a drop-in replacement for the CLI would behave more or less identically to the CLI when it comes to choosing between flat & legacy config formats (i.e. matching support for the ESLINT_USE_FLAT_CONFIG env variable would be nice).

Would you be opposed to exposing this kind of a wrapper API in unsupported-api.js? That way, it's treated as exactly as stable as FlatESLint itself, and is explicitly not set in stone.

If that's not feasible I'm sure it's fine to use findConfigFile as a reasonable enough proxy :)

[cprussin]

@nzakas might be easier to have some code to be more concrete about what I'm proposing, this is super quick & dirty and almost certainly not correct, and obviously I haven't done any of the tests or anything, but this is roughly what I had in mind: 5560fca. Thoughts?

[ljharb]

@nzakas tbh if the logic is likely to change in the future that's a strong argument for exposing this API - that way, userland doesn't have to care what it's doing, only that it gives them a boolean. Currently, changing the rules will break tools that are attempting to mimic the rules - but with this API, changing the rules would Just Work for those tools.

[fasttime]

I think the idea is to remove the current ESLint class and rename FlatESLint to ESLint in the next major version. At that point, shouldUseFlatConfig would start resolving to true all the time.

[ljharb]

sure, but it would still be convenient to have the implementation be return true and let consumers not have to care about it.

[nzakas]

as ideally tooling like jest-runner-eslint that effectively behave as a drop-in replacement for the CLI would behave more or less identically to the CLI when it comes to choosing between flat & legacy config formats (i.e. matching support for the ESLINT_USE_FLAT_CONFIG env variable would be nice).

@cprussin ah okay, this was the bit I really didn't quite understand. I don't use Jest, so I wasn't aware that this was how jest-runner-eslint would work. Given that, I think we can look at including such a shouldUseFlatConfig() function in the unsupported API and just flip it to always return true in the future.

@mdjermanovic what do you think?

[cprussin]

that sounds good @nzakas

[cprussin]

Just to clarify, would you all prefer a shouldUseFlatConfig over something like getESLintEngine? The reason I ask is that I expect that the main (or possibly only) use case for shouldUseFlatConfig would be to build a function that looks exactly like getESLintEngine anyways...

[mdjermanovic]

I support shouldUseFlatConfig(). Since we have a consensus on it, marking accepted and PR is welcome.

would you all prefer a shouldUseFlatConfig over something like getESLintEngine?

getESLintEngine doesn't seem like a good idea to me because ESLint and FlatESLint constructors have different options.

[cprussin]

@mdjermanovic makes sense, fair enough.

Done in #17169.

Thanks folks!