Docs: undocumented (and surprising) behavior of files accepting nested arrays of string

[andreww2012]

Docs page(s)

https://eslint.org/docs/latest/use/configure/configuration-files

What documentation issue do you want to solve?

Hello!

Recently I discovered seemingly undocumented and quite unintuitive behavior or files config parameter. As per types, files are accepting a nested array of strings:

eslint/lib/types/index.d.ts

Line 1260 in cb69ab3

files?: Array<string | string[]>;

And without any doubt I assumed the files array will be flattened into string[] and thus the reason for such a type is developer convenience.

But I proved to be wrong. If another array of strings is passed to the top level array, only files matched all the patterns from that array will be matched, i.e. intersection operation is taking place.

Here is a small repo demonstrating that behavior: https://stackblitz.com/edit/vitejs-vite-ujdzec
Run pnpm test to lint. I've left a note in the eslint config file what should be changed to confirm this behavior.

What do you think is the correct solution?

I would like to see this documented in the main documentation on the site and ideally in JSDoc for files property. Sorry if I've missed it.

Participation

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

Additional comments

No response

[nzakas]

Yeah, this was something we thought we needed early on but it turned out it was necessary. We didn't document it because we didn't want people using it until we were sure, and then we just forgot to remove it. I honestly didn't realize it had made it into the types in @types/eslint.

So, I think we should do the opposite: remove it from the types and then remove the functionality in v10.

@eslint/eslint-tsc thoughts?

[mdjermanovic]

So, I think we should do the opposite: remove it from the types and then remove the functionality in v10.

I agree.

[fasttime]

So, I think we should do the opposite: remove it from the types and then remove the functionality in v10.

I also agree. Technically, it should not be a breaking change to remove the nested array functionality for files and ignores, because it was never documented. This change was previously suggested in #18118.

[mdjermanovic]

Looks like we have a consensus. I prepared a PR to update types (#18971) and added this issue to the v10.0.0 board to remove this functionality from the core in v10.0.0.

[mdjermanovic]

So, I think we should do the opposite: remove it from the types and then remove the functionality in v10.

Since removing it from types can break builds of other projects, as #18971 shows, shall we make that change in v10 as well instead of now (v9)?

[mdjermanovic]

Just to note that we might eventually decide to keep this functionality as it seems useful for eslint/rfcs#126.