Change Request: Improved debugging tools for flat configs

[bradzacher]

ESLint version

v8.x

What problem do you want to solve?

I've been working on migrating a reasonably complex legacy config to a flat config.
I found that the migration path is fraught with danger due to changes in the files changes.

In our config we had the following two patterns in our matches:

1. *.js - i.e. "match all JS files"
2. some/path/**/*.*t* - i.e. "match all cts, mts, ts, tsx` files

(1) breaks in flat configs - it would only match files in the directory alongside the config file. The correct form is **/*.js.

(2) breaks in flat configs - it can cause matching on files like .DS_Store. The fix I used for this was to instead explicitly use .{ts,tsx,cts,mts}.

These problems are, of course, user config problems - migration problems. However it was really hard to debug this. Currently there are only one tool to debug flat configs - --print-config. However from what I found - this isn't much good for debugging.

For example - if I ran eslint --print-config some/path/.DS_Store - it'll just print out a config - which tells me nothing - I already know that file is matching the config because it's crashing my lint run!
Similarly if I ran eslint --print-config some/path/foo.js - again it'll just print a config and it won't tell me anything useful for debugging.

Fixing my config was a lot of manual effort in which I manually imported and logged my config from a node process to confirm its contents (lots of spreads of shared configs), followed by trial and error - deleting sections and seeing what happened. It was manual and painful!

What do you think is the correct solution?

With flat configs being so much about composing configs together in an array with lots of files - IMO the really important thing for me now is understanding exactly which elements in that array matched a given file.

For example if there was a command like eslint --debug-config <path>:

// config = [ eslint.recommended, { files: ["some/path/**/*.*t*", "some/other_path/**/*.*t*"], ... }, { files: ["*.js"], ... } ]
$ eslint --debug-config some/path/.DS_Store
[
  0 - matches all files as it has no files
  1 - file matched pattern "some/path/**/*.*t*"
  2 - file did not match any patterns
]

$ eslint --debug-config some/path/foo.js
[
  0 - matches all files as it has no files
  1 - file did not match any patterns
  2 - file did not match any patterns
]

Such a tool would have made debugging the patterns dead simple and it would have helped me understand how ESLint was matching things to resolve the final config for the file.

Participation

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

Additional comments

No response

[github-actions]

Oops! It looks like we lost track of this issue. What do we want to do here? This issue will auto-close in 7 days without an update.

[fasttime]

@kecrily are you still triaging this?

[kecrily]

You mean on this issue? no

[fasttime]

Okay, thanks for letting us know.

[nzakas]

If I'm understanding this correctly, the ask here is for a way to pass a file on the command line and have it indicate which objects in the config array it matches?

The first step is to define what is meant by "matches," as the config array matches in a bunch of different ways:

• Explicit matching - when a file path matches a pattern in files
• Excluded matching - when a config object has ignores plus some other keys, if the file path is not ignored then it matches by exclusion.
• Implicit matching - when a config object has no files or ignores, it is merged in whenever the file path is explicitly matched by at least one other config object.

@bradzacher are you looking to get all of this information or just a subset?

[bradzacher]

At the most basic form of this request I would want to get an array of booleans which tell me whether or not a "match" occurred. By that I mean true if the object passed one of your defined conditions and was used in the final config merge, false otherwise.

With such a debug feature one could do like eslint --debug-config path then node -e 'console.log(require("eslint.config.js"))' to print the config array and out and one can manually correlate the two to find the problem.

---

A more advanced form would be if eslint explicitly told you which of the 3 conditions it matched, if any. Eg instead of a boolean it printed "explicit match of pattern X" or "excluded match" or "implicit match due to no ignores/files".

This form would (probably) save you from manually logging out the config to correlate things. You may still need to print it out if you've got a whole bunch of spreads or shared configs but it would be less required.

[nzakas]

I think we may have a better solution in the works: https://github.com/eslint/config-inspector

😄

[nzakas]

@bradzacher have you tried the config inspector? (--inspect-config on the command line)

Does that solve your use case?

[bradzacher]

I have and I have been recommending it to users whenever they ask questions about flat configs in our discord - and a lot of people have found it has helped them self-service - which as been really good!

I'd love it if it could show the final calculated config for the file as well - I believe right now it just shows the calculated rules. For @typescript-eslint the final calculated language options are very important in helping users understand their setup.

[bradzacher]

For all intents and purposes - we can probably consider this closed and instead hop over to the config inspector repo for any further enhancements.