mcpField
L
lint-rule-development

lint-rule-development

github.com/biomejs开发26.0k103 次安装今天更新
代码仓库

关于 lint-rule-development

这项开发技能指导如何在 Biome 中编写 lint 和 assist 规则，涵盖查询设计、诊断、代码操作、选项、文档、测试夹具及代码生成。

主要功能

  1. 01选择分析器查询与状态
  2. 02生成规则脚手架
  3. 03编写诊断和代码操作
  4. 04配置选项与文档
  5. 05添加测试夹具并运行定向测试
  6. 06重新生成规则产物

适用场景

  1. 01添加 JavaScript lint 规则
  2. 02为某种语言创建 assist 规则
  3. 03测试诊断和自动修复
  4. 04更新 Biome 生成的规则配置

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/biomejs/biome --skill lint-rule-development

安装后在 Claude Code 中输入/lint-rule-development确认已加载。

详细介绍

Lint 规则开发

遵循 crates/biome_analyze/CONTRIBUTING.md 中当前的分析器架构。只阅读与规则相关的章节，不要默认加载整份指南。

工作流

  1. 在相同语言和分组中，查找两到三个查询方式或操作相似的现有规则。
  2. 添加分析器行为时，生成相应的 lint 规则或 assist 脚手架。
  3. 实现范围最窄的查询和状态，以判断是否应发出信号。
  4. 添加诊断，并在安全时添加操作。
  5. 添加有针对性的有效和无效 fixture，然后检查快照。
  6. 运行所需的分析器代码生成和范围最窄的测试。

脚手架命令：

just new-js-lintrule useMyRule
just new-css-lintrule useMyRule
just new-json-lintrule useMyRule
just new-graphql-lintrule useMyRule

新的 lint 规则从 nursery 开始。它们是针对 main 的补丁变更，因为 nursery 规则不遵循常规的功能版本管理策略。加载 changeset 以创建发布条目。

对于新的 assist，请使用该语言的 new-*-assistrule 配方，例如：

just new-js-assistrule useMyAction
just new-json-assistrule useMyAction

生成器会将 assists 放在 src/assist/source/ 下；它们不使用 lint 分组或 nursery 策略。新的 assist 是面向用户的功能，通常需要针对 next 的次要版本 changeset。现有 assist 的错误修复遵循常规错误修复策略。查看 justfile，了解哪些语言支持 assist 脚手架。

查询与状态

选择能够回答规则需求且成本最低的查询：

  • 用于语法局部检查的 Ast<Node>；
  • 当需要绑定、引用、作用域或全局变量时使用 Semantic<Node>；
  • 仅当事实归属于某项服务时才使用服务查询；
  • 仅当语法和语义模型都无法回答问题时，才使用类型推断。

大多数规则只需要其中一种。只有需要在整个遍历过程中保留状态的规则，才应使用带有自定义 Visitor 的 Queryable。

分析器指南中有关查询和服务的章节，是可用 API 的权威说明。

run() 应决定是否发出信号。将仅用于操作的工作放在 action() 中，避免对每个候选节点都执行。

优先在 State 中使用范围、语法节点、令牌和紧凑枚举。从语法文本构建 String、Box<str> 或集合，通常意味着存在可避免的分配；在持有源文本前加载 syntax-text-handling。

在 run() 中遍历子树或扫描令牌之前，以及编写自定义 Visitor（必须实现 visited_kinds）之前，都要加载 syntax-text-handling。

对于匹配全局标识符的规则，必须证明引用解析到的是全局标识符，而不是局部遮蔽项。覆盖节点联合类型和框架特定语法族中的所有相关成员。

诊断

每条诊断都要回答三个不同的问题：

  1. 发现了什么情况？
  2. 为什么这是个问题？
  3. 用户应该怎么做？

消息回答第一个问题。建议回答第二个问题；当没有操作时，也回答第三个问题。存在自动修复时，代码操作及其标签通常会回答第三个问题。

加载 diagnostics-development，了解消息结构、标记、详情、建议、类别和独立的 Diagnostic 类型。不要在规则实现中重复其中的指南内容。

操作

在 action() 中构建变更。只有在任何可达输入都不会改变行为时，才设置 FixKind::Safe。如果安全性取决于规则无法证明的假设，则使用 Unsafe。

测试应用操作后是否：

  • 生成有效语法；
  • 保留注释和 trivia；
  • 不会再次触发同一规则；
  • 对安全修复保留语义；
  • 能处理 run() 接受的每一种语法变体。

使用具有相同变更形式的现有规则作为 API 示例。

选项

仅为真正的语义模式或已有的冲突偏好添加选项。不要添加推测性的灵活选项。

以规则在 crates/biome_rule_options/src/ 下生成的文件或已有文件作为唯一准则。请遵循分析器指南中的 Rule Options、Merge 和 Documenting Options 部分，了解当前的派生项、合并行为、配置示例和 rustdoc 要求。

检查以下集成点：

  • 规则的 type Options；
  • 未设置选项时，默认值应保留原有行为；
  • 扩展配置应按照选项类型的约定进行合并；
  • 为每种行为准备包含 options.json 的 fixture 目录；
  • 规则 rustdoc 应说明每个选项的默认值，并展示其用法；
  • just gen-rules 和 just gen-configuration 应更新注册信息和配置。

如果源 ESLint 规则包含 biome migrate eslint 应保留的选项，请加载 eslint-migrate-options。

规则文档

declare_lint_rule! 和 declare_assist_rule! 内的 rustdoc 面向终端用户，是网站内容，而非内部 API 文档。

  • 用一句单行摘要说明行为。
  • 解释被报告的模式为何有问题。
  • 将 ### Invalid 示例放在 ### Valid 示例之前。
  • 根据当前的 rules-check 语法标记示例。
  • 对于每个选项，都应说明默认值、展示配置，并提供应用后的示例。
  • 不要仅仅为了规避验证而使用 ignore。

编写示例前，请查看相邻规则的文档和分析器指南。

测试与生成

加载 testing-codegen，了解 fixture 命名、预期注释、.jsonc 用例、快照审查和清理规则。

常见的定向命令：

just test-lintrule useMyRule
just gen-rules
just gen-configuration

根据 AGENTS.md 的要求运行 just f 和 just l。

审查清单

  • 查询范围不超过所需范围。
  • 通过语义模型处理全局变量和变量遮蔽。
  • State 避免不必要地持有源代码文本。
  • 仅限操作的工作应延后到 action() 中执行。
  • 安全修复应保留语义。
  • 默认值应保留现有行为。
  • 有效、无效、选项、抑制和修复用例应覆盖变更涉及的分支。
  • 包含所需的生成产物。
  • 面向用户的诊断信息和 rustdoc 应解释行为，而不是实现细节。

参考资料

  • 分析器指南：crates/biome_analyze/CONTRIBUTING.md
  • 规则实现：crates/biome_*_analyze/src/lint/
  • 规则选项：crates/biome_rule_options/src/
  • 测试 fixture：crates/biome_*_analyze/tests/specs/

评论

支持 Markdown