diagnostics-development

诊断开发

将 crates/biome_diagnostics/CONTRIBUTING.md 作为权威的 API 和设计指南。在选择建议类型或派生形式前，先检查同一子系统中的现有诊断。

选择诊断 API

对 lint 和 assist 规则使用 RuleDiagnostic。当解析器、服务、CLI、配置或基础设施边界需要自己的结构化诊断时，使用独立类型并派生 Diagnostic。

不要仅为包装一条 lint 消息而引入独立类型。如果复杂诊断包含位置、子诊断或条件建议，不要强行用 RuleDiagnostic 链来表示；使用自有类型可以更清晰地表达其约定。

三个问题

完整的诊断应回答：

1. 发现了什么情况？
2. 这为什么重要？
3. 用户可以怎么做？

将这些职责分开：

• 主消息指出具体情况；
• 注释或详情解释后果或原因；
• 操作、差异、命令或最终建议给出下一步。

不要用含糊的文字将原因和补救措施混为一谈。如果存在自动化操作，通常应由其标签表达补救措施，而不是在注释中重复说明。

消息和标记

• 指出实际问题，而不只是语法结构。
• 高亮最有助于用户理解问题的最小源码范围。
• 直接在 markup! 中插入值；不要先用 format! 分配字符串。
• 在有助于快速浏览时，使用强调标记标出源码术语或配置值。
• 保持主消息简短；将解释放在建议中。
• 不要声称实现无法证实的后果。

选择建议

根据用户需要的信息选择建议：

需求	机制
解释或下一步	注释或日志建议
指向相关源码范围	详情或代码框建议
显示精确的文本更改	差异建议或代码操作
显示要运行的命令	命令建议
额外的可选上下文	详细建议

优先提供源码证据，而不是用一段话描述问题所在。避免添加多条注释，用不同措辞重复同一事实。

独立诊断

对于 #[derive(Diagnostic)]，请核对当前指南和派生实现所支持的属性。通常需要关注：

• 严重级别和类别；
• 主消息和纯文本描述；
• 位置路径、源码和范围；
• 建议和详细建议；
• 可修复、不必要、已弃用或内部等标签。

诊断类型负责保存报告边界所需的稳定数据。如果一个范围和结构化值就足够，不要保留大型源码缓冲区或分配渲染后的字符串。

类别

不要手动编辑生成的诊断类别注册表。使用负责该类别的规则脚手架或生成器，然后核对生成的条目和文档 URL。

对于非规则诊断，在做出更改前检查相邻类别和当前的代码生成源；不要根据生成文件推断工作流。

严重级别

遵循子系统既定策略。严重级别用于表达实际影响，而非作者对消息的重视程度。引入不同的严重级别或标签前，请检查相邻诊断和当前贡献指南。

验证

• 添加范围尽可能小、能够渲染该诊断的测试或 fixture。
• 检查快照中的消息、建议顺序、标记、路径和高亮范围。
• 测试条件建议的每个分支。
• 手动计算偏移量时，使用包含周边空白和多字节文本的源码范围进行测试。
• 对于 lint 诊断，请加载 lint-rule-development 和 testing-codegen，以获取规则专用的 fixture。

审查清单

• 主要消息说明了问题所在。
• 建议解释了原因，并给出具体的下一步操作。
• 高亮范围最小且正确。
• 结构化标记避免分配预格式化字符串。
• 所选 API 与诊断复杂度相匹配。
• 类别变更使用受支持的源或生成器。
• 快照覆盖了每条条件消息或建议路径。

参考资料

• 诊断指南：crates/biome_diagnostics/CONTRIBUTING.md
• 诊断 trait：crates/biome_diagnostics/src/diagnostic.rs
• 建议 API：crates/biome_diagnostics/src/advice.rs
• 现有派生示例：搜索 #[derive(Diagnostic)]