This RFC is a long-term one since it would be a breaking change. Biome 2 is just out, and we don't intend to do a Biome 3 anytime soon yet. But I think it's a discussion that requires careful deliberation, so it's best to start it early.

Proposal

In a future version of Biome, files.includes should be treated as additive to an auto-detected set of included files, instead of authorative as it is today.

Auto-detected inclusion would be based on the concept of entry files: https://knip.dev/explanations/entry-files

In short, entry files are all those files from which configured tools start to include code or configuration relevant to a project. For example, if you have an src/index.ts file, that's probably an entry point for your configured bundler. But for Biome, your biome.json is also an entry point. And a script that you invoke from the package.json "scripts" section is another entry point. Knip's FAQ also has more information on this: https://knip.dev/reference/faq#where-does-knip-look-for-entry-files

With this suggestion, every entry file that gets detected, as well as all their dependencies, are automatically included by Biome. This leaves files.includes for configuring additional files that weren't automatically detected, as well as for ignoring things that were included that you wish to exclude.

Motivation

The motivation for this change is two-fold:

• Because Biome can auto-detect entry files, and their dependencies, users should rarely need to configure files.includes manually anymore. The exceptions would be for adding entry files that didn't get detected, or to ignore files that get included accidentally.
  • Do note that accidental inclusion would be far less likely than with our current default, which is too include everything.
• We would be able to make rules such as noUnusedExports more reliable, and a rule such as noUnusedFiles would even become feasible as well. Both of those are functionality that Knip currently handles well, but which are hard to do for us given our current configuration.
  • Implementing noUnusedExports wouldn't be very hard today (although it does require a bit of special handling -- see the linked discussion), but it would be less reliable because we wouldn't be able to detect whether exports are imported by live code or by another file that happens to contain dead code itself.

Implications

• The main implication is that in order to do this well, we need to have extensive support for detecting entry files for various tools. Knip itself has an ecosystem of plugins to handle this, we may need to consider whether we can become compatible with their plugins -- although that requires compatibility with JS plugins in general first.
• Another implication is around user expectations. Today, users expect pretty much all supported files to be handled by Biome, except those that they explicitly ignore in files.includes. After all, our current default is to include everything, and when configuring files.includes, many users will start by including **. But this default will change, and starting files.includes with ** would become a bit of an anti-pattern, since it's not advised if you want detection of dead code to work properly. Users can still include everything they want, but it's probably a bit of a change in mindset.

Migration

The format for files.includes wouldn't change, but its semantics do. But the nice thing is: projects that have already configured files.includes would continue working... except they might specify more files than desired for rules such as noUnusedFiles and noUnusedExports. For Biome to function correctly, the migration is seamless, but for users to get the most value out of such rules, they would need to trim their configuration.