parser-development

解析器开发

请将 crates/biome_parser/CONTRIBUTING.md 作为解析器指南的权威文档。根据当前任务涉及的语法、词法分析器、解析规则或错误恢复，阅读相应章节。

工作流

1. 检查语言语法和相邻的解析规则。
2. 更改错误恢复行为前，先添加或调整有针对性的 ok/ 和 error/ 测试样例。
3. 类型化语法树结构发生变化时，更新语法。
4. 更改 .ungram 后，重新生成语法和工厂相关产物。
5. 使用显式的存在性测试和有界错误恢复实现解析器逻辑。
6. 运行该语言解析器的针对性测试，并检查快照。

语法

xtask/codegen/ 下的语法文件定义了类型化语法节点和字段。遵循现有的语言命名规则：

• 节点名称以语言名为前缀；
• 联合类型名称使用 Any；
• 使用 Bogus 节点表示可恢复的无效语法；
• 列表节点名称以 List 结尾；
• 将列表表示为存在但可能为空的节点，而不是可选字段。

更改语法后，运行：

just gen-grammar <lang>

这会更新生成的语法节点、语法种类、工厂、宏和特定语言的映射。解析器规则仍由手动编写。

存在性约定

只有在未消耗任何词元时，解析函数才会返回 Absent。调用 start、bump、eat、expect 或其他可能前进的解析器之前，先检查用于区分语法的第一个词元。

使用：

• 对于缺失时应生成诊断的必需词元，使用 expect；
• 对于可选词元，使用 eat；
• 对于可选节点，使用 .ok()；
• 对于必需节点，使用 .or_add_diagnostic(...)；
• 对于应保留在 CST 中的格式错误节点，使用类型化错误恢复。

如果有界前瞻或更精确的存在性测试可以区分语法，就不要使用回溯。

错误恢复

错误恢复必须保留后续有效语法，并在相应位置生成语法允许的错误节点。

错误恢复集合通常应包含最近的相关：

• 列表分隔符；
• 列表或代码块终止符；
• 语句边界；
• 用于开始下一个有效结构的词元。

不要从无关的语法位置复制错误恢复集合。请确认调用方在解析失败后预期会遇到哪些词元。

列表

当解析器基础设施的列表 trait 符合语法约定时，应使用它们，而不是自行编写循环。

对于分隔列表，请确认：

• 解析器能识别外围终止符；
• 分隔符处理符合尾随分隔符语法；
• 格式错误的元素会促使解析前进或停止；
• 错误恢复不会消耗外围终止符；
• 空列表仍会生成必需的列表节点。

词法分析器和词元源

遵循 biome_parser 当前的 Lexer 和缓冲词元源 trait；不要照搬技能或问题中较旧的 trait 实现。

• 使用词法分析器基础设施提供的经过检查的字节和字符访问器。
• 当相同字节的含义取决于上下文时，明确保留词法分析上下文。
• 确保词法分析器的每条路径都会前进或返回 EOF。
• 使用 &str 词法分析器测试验证有效的多字节字符以及字符边界和索引行为。只有通过现有的面向字节的 API，才测试格式错误的字节序列。

测试

加载 testing-codegen，了解解析器快速测试和快照机制。

• 开发时使用 crate 的 quick_test 检查 CST。
• 在解析器 crate 当前的 ok/ 和 error/ 目录下添加持久化测试样例。
• 修复解析器错误时，需要添加修改前会失败的最小测试样例。
• 更改错误恢复时，需要在格式错误的输入后添加有效语法，以证明解析能够正确恢复。

审查清单

• Absent 路径不消耗输入。
• 必需节点和词元会生成有用的诊断。
• 错误恢复会生成符合语法的错误节点。
• 每个循环要么前进，要么退出。
• 列表错误恢复会在外围边界之前停止。
• CST 保留所有源文本，包括格式错误的输入。
• 语法更改包含生成的语法和工厂相关产物。
• 有效和格式错误的测试样例都覆盖了更改路径。

References

• Parser guide: crates/biome_parser/CONTRIBUTING.md
• Grammars: xtask/codegen/*.ungram
• Parser infrastructure: crates/biome_parser/src/
• Language implementations: crates/biome_*_parser/src/