Configuration: simplification of include/ignore overriding

[Conaclos]

Summary

Biome provides several ways to tune the behavior of tools for a given set of files. We can now use .gitignore files, global include/ignore, by-tool include/ignore, and granular overrides. The resulting configuration schema is pretty complex and can be confusing when these features are used together.

This RFC proposes to get rid of some of these features to improve configuration composability and simplify the overall configuration.

Proposal

Users have repeatedly asked for a way to control which files are ignored or included when formatting and linting. We initially only provided a global files.{include,ignore} properties to specify which files got formatted and linted and a way to override the selected for a given tool ({linter,formatter,organizeImports}.{include,ignore}). Note that we can also pass a set of files via command line arguments.

In response to user requests, we later added support for .gitignore files (vcs.useIgnoreFile). We also added support for extending another configuration extends and we adopted the granular configuration proposal that allows to override the formatter configuration for a given language ({javascript,json}.formatter) and to apply custom configurations to set of files (overrides).

The resulting configuration provides multiple ways to achieve the same thing and led to numerous bugs around overriding behaviors. Also, if the user uses both {files,formatter,linter}.{include,ignore} and overrides, this can lead to pretty complex configurations.

To reduce this complexity and improve composability, I suggest getting rid of {files,formatter,linter,organizeImports}.{include,ignore}.

  type BiomeConfig = {
    $schema: string,
    extends: string,
    files: {
-     include: string[],
-     ignore: string[],
      ignoreUnknown: boolean,
      maxSize: number,
    },
+   formatter: FormatterOptions,
-   formatter: {
-     ignore: string[],
-     include: string[],
-     ...FormatterOptions,
-   },
+   linter: LinterOptions,
-   linter: {
-      ignore: string[],
-      include: string[],
-     ...LinterOptions,
-   },
+   organizeImports: OrganizeImportsOptions,
-   organizeImports: {
-     ignore: string[],
-     include: stringo[],
-     ...OrganizeImportsOptions,
-   },
    javascript: JavaScriptOptions,
    json: JsonOptions,
    overrides: Array<{
      ignore: string[],
      include: string[],
      formatter: FormatterOptions,
      linter: LinterOptions,
      organizeImports: OrganizeImportsOptions,
      javascript: JavaScriptOptions,
      json: JsonOptions,
    }>
    vcs: {
      enabled: boolean,
      clientKind: string,
      useIgnoreFile: boolean,
      root: boolean,
    },
  }

  type JavaScriptOptions = {
    parser: {
      unsafeParameterDecoratorsEnabled: boolean,
    },
    formatter: {
      ...FormatterOptions,
      quoteSTyle: "single" | "double",
      jsxQuoteStyle: "single" | "double",
      quoteProperties: "asNeeded" | "preserve",
      trailingComma: "all" | "es5" | "non",
      semicolons: "always" | "asNeededa",
      arrowParentheses: "always" | "asNeededa",
    },
    globals: string[],
  }

  type LinterOptions = {
    enabled: bbolean
    rules: { ... }
  }

  type FormatterOptions = {
    enabled: bbolean
    indentStyle: "tab" | "space",
    indentWidth: number,
    lineEndind: "lf" | "crlf" | "cr",
    lineWidth: number,
    bracketSameLine: boolean,
    bracketSpacing: boolean,
  }

  type OrganizeImportsOptions = {
    enabled: boolean,
  }

  type JsonOptions = {
    parser: {
      allowComments: boolean,
      allowTrailingCommas: boolean,
    },
    formatter: FormatterOptions,
  }

Alternative proposal

Alternatively we could get rid of {formatter,linter,organizeImports}.{include,ignore}, and move {files}.{include,ignore} to the top.

  type BiomeConfig = {
    $schema: string,
    extends: string,
    files: {
-     include: string[],
-     ignore: string[],
      ignoreUnknown: boolean,
      maxSize: number,
    },
+   include: string[],
+   ignore: string[],
    +   formatter: FormatterOptions,
-   formatter: {
-     ignore: string[],
-     include: string[],
-     ...FormatterOptions,
-   },
+   linter: LinterOptions,
-   linter: {
-      ignore: string[],
-      include: string[],
-     ...LinterOptions,
-   },
+   organizeImports: OrganizeImportsOptions,
-   organizeImports: {
-     ignore: string[],
-     include: stringo[],
-     ...OrganizeImportsOptions,
-   },
    javascript: JavaScriptOptions,
    json: JsonOptions,
    overrides: Array<{
      ignore: string[],
      include: string[],
      formatter: FormatterOptions,
      linter: LinterOptions,
      organizeImports: OrganizeImportsOptions,
      javascript: JavaScriptOptions,
      json: JsonOptions,
    }>
    vcs: {
      enabled: boolean,
      clientKind: string,
      useIgnoreFile: boolean,
      root: boolean,
    },

Migration plan

Before getting rid of {files,formatter,linter,organizeImports}.{include,ignore} properties, we should first deprecate them and provide an automatic migration via biome migrate.

For instance, let's assume that the user have this configuration:

{
  formatter: {
    include: ["*.js"],
    ignore: ["*.gen.js"],
    ...
  },
  linter: {
    include: ["*.js"],
    ignore: ["*.test.js"],
    ...
  },
}

The migration tool could convert the configuration to:

{
  overrides: [
    {
      include: ["*.js"],
      ignore: ["*.gen.js"],
      formatter: { ... },
    },
    {
      include: ["*.js"],
      ignore: ["*.test.js"],
      linter: { ... },
  },
}

One difficulty could be the presence of both files.{include,ignore}} and {formatter,linter}.{include,ignore}. In this case we have to merge the selectors.

For instance, let's assume that the user have this configuration:

{
  files: {
    ignore: ["*.js", "*.ts"],
  },
  formatter: {
    include: ["*.ts"],
    ...
  },
}

Should certainly generate something like:

{
  overrides: [
    {
      include: ["*.ts"],
      formatter: { ... },
    },
}

[ematipico]

There's one important thing that this RFC doesn't address. overrides.ignore and {files, formatter,linter}.ignore, like overrides.include and files, formatter,linter}.include have semantically two different meanings.

• {files, formatter,linter}.ignore/files, formatter,linter}.include: the globs here mean "do or do not handle this folder/file". This has repercussions for the walker of the file system. For example, with files.ignore: ["dist"], the dist folder is completely ignored and the files inside aren't read at all
• overrides.ignore/overrides.include: the globs here mean "apply or not apply this configuratino to this folder/file", but the files/folders are always read, regardless of the globs.

It's an important distinction, so we can't remove ignore/include all at once. So we are required to have a replacement somehow

[Conaclos]

In this case we could keep files.{include,ignore} or adopt the alternative approach that suggests moving files.{include,ignore} to the root object.

Why {formatter,linter,organizeImports}.{include,ignore} have not the same semantic that overrides.{include,ignore}? Do we have a dedicated file crawler for every tool?

[ematipico]

Why {formatter,linter,organizeImports}.{include,ignore} have not the same semantic that overrides.{include,ignore}?

Because that's how overrides work in other tools 🤷