用途:这是 Biome 项目中一份面向贡献者的技能指南,用于在实现 lint 规则的可配置选项时提供规范流程。适用前提是规则已实现完成,且选项应保持最小化,只在确实需要时才添加。
主要能力:覆盖定义规则选项类型、JSON 反序列化、配置合并以及在测试中验证选项行为。选项类型放在 biome_rule_options crate 中,运行 just gen-analyzer 后会为规则生成对应文件。
主要用法要点:选项结构体所有字段用 Option<_> 包裹以便正确合并;数组用 Box<[Box<str>]> 而非 Vec<String>;serde 使用 rename_all = "camelCase"、deny_unknown_fields 与 default;通过 #[cfg_attr(feature = "schema", derive(schemars::JsonSchema))] 支持 schema 生成。合并通过实现 biome_deserialize::Merge 的 merge_with 完成,简单值使用 merge_with()(用户值优先),集合通常重置为用户值而非合并,简单场景可派生 Merge。规则中通过 ctx.options() 读取选项,上下文自动处理配置文件位置、extends 继承与按文件覆盖。用户在 biome.json 的 linter.rules 下按规则名配置 level 与 options。测试时在测试目录放置 options.json,其选项作用于该目录下所有测试文件。文档需在 declare_lint_rule! 的 rustdoc 中说明每个选项。实现完成后运行 just gen-analyzer 更新 JSON schema、TypeScript 绑定与文档导出。
限制与注意:选项命名应语义清晰;文档建议只在社区风格冲突、规则存在多种合理解释或不同环境需要不同行为时添加选项,而非为“更灵活”或回避做决定而添加。提供的示例代码与命令应保持原样使用。