用途:该技能面向在 Biome 仓库内实现或调试格式化器行为的场景,涉及 IR 组合、节点规则、布局选择、源注释处理、verbatim 输出与抑制注释(suppression)等。
主要能力与工作流:以 crates/biome_formatter/CONTRIBUTING.md 和对应语言格式化器指南作为架构参考,先选择 IR 原语前查看相邻节点实现。流程为:用聚焦的内部 formatter spec 或 quick_test 复现行为;检查节点字段、注释和邻近规则;用 formatter IR 实现最小布局改动;运行聚焦测试并检查快照;在兼容性相关时与 Prettier 对比;提交前格式化与 lint。
打印纪律:格式化输出是对源树的结构化重写,而非全新 pretty-printer。范围内的每个源 token 必须恰好消费一次,可通过格式化、format_removed、format_replaced 或语言专用 helper 完成;每个源节点每次都必须被处理,优先 node.format() 或 with_options。父格式化器不得内联子节点字段来获取便利布局。绕过节点规则的架构专用格式化器必须检查 f.context().comments().is_suppressed(node.syntax()),被抑制时写语言对应的 format_suppressed_node(...)。源 token 须经类型化访问器打印,token("...") 仅用于格式化器插入的新语法;移除用 format_removed,替换用 format_replaced。自定义格式化须由实现 Format<Context> 的小结构体承载,不用自由函数或存储闭包。
节点与 token 规则:生成的节点规则实现 FormatNodeRule,在 fmt_fields 中显式解构 Fields,经类型化访问器格式化 token,谨慎使用 ;保留每个 token 与注释,除非契约有意移除或替换。format_verbatim 保留源文本,仅在测试覆盖有效、畸形与带注释形式后改为结构化格式化。
IR 组合与注释:用语义 IR(space()、软/硬换行、group、缩进原语、条件内容);多路布局用一次选定的枚举表示。头尾注释通常由基础设施处理,节点拥有无处附加注释的位置时显式处理 dangling 注释,并在结构边界测试注释。
测试与生成验证:关注幂等性,测试基础设施会在调用中重新格式化无误的非范围输出,二次结果不同即失败。行为变更即使外部快照变化也应补内部 spec。与 Prettier 对比可用:bun packages/prettier-compare/bin/prettier-compare.js --rebuild -l js 'const value={a:1}' 或 -f path/to/file.js;--rebuild 会重建 WASM 产物。提交前运行 just f 和 just l。
限制:该技能高度依赖仓库内文档与测试设施,具体命令与路径来自资料;未提供独立 CLI 或非仓库环境用法,缺失细节暂未提供。