Linter 插件

Biome Linter 插件的使用概览。

Biome Linter 支持 GritQL 插件。插件可以匹配特定的代码模式、报告自定义的诊断信息，并建议可修复的重写。

下面是一个插件示例，它会报告所有对 Object.assign() 的使用：

`$fn($args)` where {
    $fn <: `Object.assign`,
    register_diagnostic(
        span = $fn,
        message = "Prefer object spread instead of `Object.assign()`"
    )
}

你可以把 GritQL 片段放进项目里任意位置的文件中，但要注意使用 .grit 扩展名。然后，你只需通过以下配置将其作为插件启用：

{
    "plugins": ["./path-to-plugin.grit"]
}

现在，该插件会在 Linter 运行的所有受支持文件上启用。你可以在运行 biome lint 或 biome check 时看到它的结果。例如：

$ biome lint

/packages/tailwindcss-config-analyzer/src/introspect.ts:12:17 plugin ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ✖ Prefer object spread instead of `Object.assign()`

    10 │ function createContextFromConfig(config: Partial<Config>) {
    11 │        return createContext(
  > 12 │                resolveConfig(Object.assign({}, DEFAULT_CONFIG, config)),
       │                              ^^^^^^^^^^^^^
    13 │        );
    14 │ }

你可以用 lint/plugin 抑制注释来抑制插件的诊断信息。详情见插件抑制。

插件也可以使用 => 运算符建议代码重写：

`console.log($msg)` as $call where {
    register_diagnostic(
        span = $call,
        message = "Use console.info instead of console.log.",
        severity = "warn",
        fix_kind = "safe"
    ),
    $call => `console.info($msg)`
}

重写行为：

不使用 --write 时，重写会作为建议显示，但不会应用。
使用 --write 时，Biome 会应用标记为 fix_kind = "safe" 的插件重写。
使用 --write --unsafe 时，Biome 也会应用不安全的插件重写。
如果省略 fix_kind，该重写默认会被视为不安全。

将插件限制到特定文件

默认情况下，插件会在 Biome 处理的每个文件上运行。不过，你可以使用 includes 选项来限制插件可以或不可以运行的文件和目录。

在以下示例中，第一个插件只在 src/components/ 内的文件上运行。第二个插件在 src/ 目录下所有扩展名为 .ts 的文件上运行，但排除了 src/ 目录下以 .test.ts 结尾的文件：

{
    "plugins": [
        {
            "path": "./react-plugin.grit",
            "includes": ["src/components/**"]
        },
        {
            "path": "./ts-only-plugin.grit",
            "includes": ["src/**/*.ts", "!src/**/*.test.ts"]
        }
    ]
}

设置了 includes 时，插件只会在至少匹配一个正向模式、且没有被取反模式排除的文件上运行。模式遵循glob 语法参考。

目标语言

GritQL 片段始终尝试与给定的_目标语言_进行匹配。如果没有指定目标语言，则默认为 JavaScript 或其某种上层语言。

如果你想使用其他目标语言，必须显式指定。例如，下面是一个 CSS 插件，它会报告在允许的 .color-* 类之外设置颜色的任何选择器：

language css;

`$selector { $props }` where {
    $props <: contains `color: $color` as $rule,
    not $selector <: r"\.color-.*",
    register_diagnostic(
        span = $rule,
        message = "Don't set explicit colors. Use `.color-*` classes instead."
    )
}

Biome 目前支持 JavaScript、CSS 和 JSON 目标语言。

插件 API

除了 Grit 的内置函数之外，Biome 目前还支持一个额外的函数：

`register_diagnostic()`

注册一条诊断信息，在模式匹配时报告。

支持四个参数：

span（必填）：要附加诊断信息的语法节点。这通常是你在代码片段中匹配到的一个变量。
message（必填）：随诊断信息一起显示的消息。
severity：诊断信息的严重性等级。允许的值为：hint、info、warn 和 error。默认使用 error。
fix_kind：相关重写修复的安全性（safe 或 unsafe）。仅当模式也使用重写运算符（=>）时才相关。默认情况下，修复被视为不安全。