【免费下载链接】tools
Unified developer tools for JavaScript, TypeScript, and the web
本篇技术指南围绕 xtask/README.md 展开,系统讲解 Rome(Rome Tools)中 xtask 目录下的 Rust 脚本工具链:它覆盖了**代码生成(codegen)、覆盖率/一致性测试(coverage)、基准测试(benchmark)**三大开发场景。读完本文,你将掌握 cargo codegen、cargo bench_parser、cargo lintdoc 等命令的完整用法、.ungram 语法文件驱动的 AST 生成约定,以及它们如何与 rome_js_syntax、rome_js_parser、rome_service 等核心 crate 协同工作,从而能够在本地复现 Rome 自身的开发与性能验证流程。
一、xtask 是什么:一个目录,三种开发工具
xtask 是 Rust 生态中一种常见的「用代码替代 shell 脚本」的开发模式:把项目维护者需要反复执行的代码生成、测试增强、基准对比等工作,写成一个或多个可执行的 Rust crate,而不是一堆难以跨平台的 bash/python 脚本。
在 Rome 仓库中,xtask/README.md 明确说明:
This directory contains Rust scripts for code generation, running coverage tests and benchmark etc. Please checkout their respective READMEs for usage instructions.
也就是说,xtask 目录本身是一个公共工具 crate,为其他脚本提供通用能力;具体的脚本则分散在各自的子 crate 中,各自带有 README。从目录结构(见 xtask)可以看到当前仓库包含以下成员:
| 子 crate | 作用 |
|---|---|
xtask(根 crate) | 公共工具库:rustfmt 调用、项目根目录定位、生成文件头注释、跨平台 shell 胶水 |
xtask_codegen | 代码生成命令,对应 cargo codegen 系列子命令 |
xtask_bench | 基准测试,对应 cargo bench_parser / cargo bench_formatter 等 |
xtask_coverage | 覆盖率/一致性测试(README 中提及的 coverage tests) |
xtask_lintdoc | 从 lint 规则源码自动生成网站文档页,对应 cargo lintdoc |
xtask_contributors | 抓取 GitHub 贡献者数据,生成网站 Contributors 组件 |
这种「一个 crate 对应一类命令」的组织方式,让每个脚本都可以独立编译、独立调试,同时通过依赖 xtask 根 crate 复用公共逻辑。
二、xtask 根 crate:公共工具与跨平台胶水
xtask/src/lib.rs 提供了所有脚本共用的基础设施,理解它是读懂其他脚本的前提。
2.1 定位项目根目录
project_root() 通过 CARGO_MANIFEST_DIR 环境变量向上回溯两级,得到仓库根目录:
pub fn project_root() -> PathBuf {
Path::new(&env::var("CARGO_MANIFEST_DIR")
.unwrap_or_else(|_| env!("CARGO_MANIFEST_DIR").to_owned()))
.ancestors().nth(2).unwrap().to_path_buf()
}
因为 xtask 位于 xtask/Cargo.toml,向上两级恰好是仓库根。所有脚本在 main 中都会先执行 pushd(project_root()),保证无论从哪里调用,文件读写都落在仓库根目录下。
2.2 两个工作模式:Overwrite 与 Verify
pub enum Mode {
Overwrite, // 直接覆盖生成
Verify, // 只检查是否与预期一致(CI 用)
}
这是代码生成工具最常见的双模式设计:本地开发用 Overwrite 直接刷新生成文件;CI 中用 Verify 检查生成文件是否过期,防止开发者提交未重新生成的代码。
2.3 rustfmt 与生成文件头
run_rustfmt(mode) 会强制使用 stable 工具链执行 cargo fmt(或 cargo fmt -- --check),并在 ensure_rustfmt() 中校验 rustfmt 确实来自 stable 工具链。而 reformat() / reformat_with_command() / prepend_generated_preamble() 三个函数负责在生成代码前先格式化,并自动加上「Generated file, do not edit」的声明。例如:
pub const PREAMBLE: &str = "Generated file, do not edit by hand, see `xtask/codegen`";
这些生成文件头在仓库里随处可见,例如 lint 文档页会写入 <!-- this file is auto generated, usecargo lintdocto update it -->。
2.4 跨平台胶水:glue.rs
xtask/src/glue.rs 自嘲为 "A shell but bad, some cross platform glue code",实现了 shell 的核心能力:
run!宏:解析并执行命令,支持 stdin 输入(<stdin语法),失败时返回带上下文的错误;pushd/pushenv:通过 RAII 在作用域结束时自动恢复目录与环境变量(内部用 thread_local 的栈维护);fs2模块:封装read_dir、read_to_string、write、copy、remove_file、remove_dir_all、create_dir_all等文件操作,统一带上错误上下文;rm_rf:递归删除目录或文件(先检查路径存在性);shelx:简易的 shell 分词器,处理单引号包裹的带空格参数。
正是这一层胶水,让后续所有脚本可以在 Windows 与 Unix 上以同一套代码运行外部进程。
三、cargo codegen:基于 ungrammar 的代码生成
3.1 命令总览
cargo codegen 别名定义在仓库根目录的 .cargo/config.toml:
codegen = "run -p xtask_codegen --"
codegen-bindings = "run -p xtask_codegen --features schema -- bindings"
codegen-configuration = "run -p xtask_codegen --features configuration -- configuration"
codegen-schema = "run -p xtask_codegen --features schema -- schema"
codegen-website = "run -p xtask_codegen --features website -- website"
入口是 xtask/codegen/src/main.rs,其内置帮助文本列出全部子命令:aria(生成 lint 规则的 aria 绑定)、analyzer、configuration、schema(Rome 配置文件 JSON Schema)、bindings(Workspace API 的 TypeScript 定义)、grammar(ungram 转 AST)、formatter(生成各语言 formatter)、test(解析器内联注释测试抽取)、unicode(词法器 unicode 表)、newlintrule、all(依次运行所有生成器)。
3.2 cargo codegen grammar:ungrammar 驱动 AST
这是整个生成体系的核心。grammar 子命令读取 .ungram 语法文件(JS 使用 xtask/codegen/js.ungram,另有 css.ungram 与 json.ungram),将它们转换为 rome_js_syntax 等语法 crate。
Rome 采用 ungrammar)。
3.3 语法书写约定(Conventions to create syntax)
原文档给出了三条必须遵守的内部约定,直接决定了生成代码的质量:
约定一:manual__ 前缀标记手工实现的方法
MyDeclaration = manual__decl:Body
这样写表示代码中会有一个手写的 impl:
impl MyDeclaration {
fn decl(self) -> Option<Body> {
// custom logic goes here
}
}
生成器看到 manual__ 前缀后会跳过该方法,让开发者用自定义逻辑填充。
约定二:token 联合必须有标签
BinExpr = left: Expr op: ('+' | '-' | '*') right: Expr
给联合加上 op: 标签后,生成器才能正确处理并产出更高质量的 AST——它会生成一个在 T![+]、T![-]、T![*] 中查找 token 的方法:
impl BinExpr {
fn op(self) -> Option<SyntaxToken> {
// custom logic goes here
support::find_token(
&self.syntax,
&[
T![+],
T![-],
T![*],
],
)
}
}
约定三:跟踪损坏代码的节点必须包含 Bogus 字样
// 例如 MyBogusNode = ...
名字中必须包含 Bogus(大小写敏感)。这会触发生成器生成不同类型的代码,用于处理 Rome 解析出错代码的场景,是错误恢复机制的一部分。
3.4 cargo codegen test:抽取解析器内联测试
test 子命令把 rome_js_parser 中的内联注释测试抽取到 rome_js_parser/test_data/ 目录。标准工作流:
# (先在解析器里修改内联注释测试)
cargo codegen test
cargo test parser # 检查失败的测试
UPDATE_EXPECT=1 cargo test parser # 提交更新后的快照
这与 rome_js_parser/test_data/inline/ 下存放 .rast、.js 等测试数据的目录结构完全吻合。
3.5 cargo codegen unicode:同步 Unicode 数据
unicode 子命令从 unicode.org 下载最新的 Unicode 数据,写入 crates/rome_js_lexer/src/tables.rs。当项目的 Unicode 支持需要升级时(例如新增字符类别、ID 起始字符规则变化),就应运行此命令。当前仓库中对应文件为 crates/rome_js_unicode_table/src/tables.rs。
3.6 进阶命令:newlintrule 与 promoterule
xtask_codegen 还提供两个非常实用的规则开发辅助命令(同样定义在 justfile 中):
# 生成一个空白 lint 规则的模板
cargo run -p xtask_codegen -- newlintrule --path=<路径> --name=<规则名>
# 将规则从 nursery 提升到正式组
cargo run -p xtask_codegen -- promoterule --rule=<规则名> --group=<目标组>
promoterule 的实现位于 xtask/codegen/src/promote_rule.rs,体现了「nursery 规则稳定后晋升」的规则治理流程。
四、cargo bench:解析器与格式化器基准测试
4.1 命令映射
xtask/bench/README.md 说明该 crate 基于 Criterion 生成基准结果。别名同样在 .cargo/config.toml 中:
bench_parser = "run -p xtask_bench --release -- --feature parser"
bench_formatter = "run -p xtask_bench --release -- --feature formatter"
bench_analyzer = "run -p xtask_bench --release -- --feature analyzer"
4.2 分支对比工作流
要对比 main 分支与 PR 分支的性能,官方流程如下:
# (在 pr 分支上提交代码后执行)
git checkout main
cargo bench_parser --save-baseline main
git checkout -
cargo bench_parser --save-baseline pr
critcmp main pr # (cargo install critcmp)
critcmp 是 Criterion 基线对比工具,输出形如下表(来自 xtask/bench/README.md):
group main pr
----- ---- --
parser/compiler.js 1.05 98.1±26.02ms 10.7 MB/sec 1.00 93.4±7.47ms 11.2 MB/sec
parser/d3.min.js 1.09 57.7±10.50ms 4.5 MB/sec 1.00 52.9±1.59ms 5.0 MB/sec
parser/jquery.min.js 1.16 20.5±4.63ms 4.0 MB/sec 1.00 17.6±0.55ms 4.7 MB/sec
parser/react.production.min.js 1.05 1096.7±295.86µs 5.6 MB/sec 1.00 1049.1±237.49µs 5.9 MB/sec
parser/three.min.js 1.00 81.6±11.86ms 7.2 MB/sec 1.10 90.2±19.85ms 6.5 MB/sec
parser/vue.global.prod.js 1.09 28.7±6.39ms 4.2 MB/sec 1.00 26.3±0.88ms 4.6 MB/sec
其中 1.xx 列是百分比差异,数值越大表示越慢。例如表中 jquery 在 main 上慢 16%,整体上 pr 分支表现更优。测试语料来自真实世界的大型 JS/TS 库(compiler.js、d3.min.js、jquery.min.js、three.min.js、vue.global.prod.js 等),语料清单存放在 xtask/bench/src/libs-js.txt 等文件中。
4.3 可用的运行参数
从 xtask/bench/src/main.rs 的帮助文本可看到完整参数:
| 参数 | 说明 |
|---|---|
--save-baseline | 为本次运行保存基线,供后续对比 |
--feature | 必填,取值 parser / formatter |
--criterion=[true/false] | 是否运行统计检验以判断本次运行比上次快还是慢 |
--suites=<IDS> | 指定运行哪些套件,逗号分隔;* 全部、js 仅 JS 库、ts 仅 TS 库,默认 * |
--filter=<file> | 过滤不匹配查询的测试 |
格式化器基准的命令与解析器完全同构:
git checkout main
cargo bench_formatter --save-baseline main
git checkout -
cargo bench_formatter --save-baseline pr
critcmp main pr
另外,基准进程的全局分配器按平台做了优化:Windows 使用 mimalloc,其他平台使用 tikv-jemallocator(见 xtask/bench/Cargo.toml),这保证了测量结果接近生产环境。
4.4 dhat 堆分析
当需要分析解析/格式化过程中的内存分配时,使用 dhat 特性:
cargo run -p xtask_bench --features dhat-heap --release-with-debug
该特性在 xtask/bench/Cargo.toml 中定义为 dhat-heap = ["dhat", "humansize"],配合 [global_allocator] 注入 dhat::Alloc,可以在 main.rs 中启用 dhat::Profiler::new_heap() 进行堆剖析。
五、cargo lintdoc:从规则源码生成网站文档
xtask/lintdoc/src/main.rs 是一个很有代表性的「文档即测试」工具:它读取每个 lint 规则的 Markdown 文档片段,把其中的代码块当作可执行的测试用例。
流程大致为:
- 通过
RegistryVisitor遍历rome_js_analyze与rome_json_analyze的规则注册表(crates/rome_js_analyze/registry.rs),按组(a11y、complexity、correctness、nursery、performance、security、style、suspicious)收集所有规则及其元数据; - 解析文档中的 fenced code block,识别
expect_diagnostic、ignore、js/ts/tsx/json等属性(解析逻辑见CodeBlockTest::from_str); - 对每个代码块调用真实的解析器与分析器,断言「期望出诊断的必须恰好出一个诊断,不期望的必须一个都不出」;
- 把验证通过的诊断输出为 HTML,连同索引页写入
website/src/pages/lint/rules/,并更新Groups.astro、NumberOfRules.astro等生成组件。
因此 cargo lintdoc 既是文档生成器,也是一套回归测试——规则文档中任何与实现不符的示例都会导致命令失败。
六、cargo contributors 与覆盖率测试
6.1 贡献者组件生成
xtask/contributors/src/main.rs 读取 GitHub API 的贡献者数据(需要带只读权限的 token,且仅拥有仓库读取权限的用户可运行),生成 website/src/components/Contributors.astro 组件。它对分页的 Link 响应头做了递归处理,并对登录名、头像 URL 做 HTML 转义,最终产物带有生成声明头。
6.2 覆盖率测试
README 中提到的 coverage tests 由 .cargo/config.toml 中的 coverage 别名承载:
coverage = "run -p xtask_coverage --profile=release-with-debug --"
该命令用于运行解析器/格式化器对标准测试套件(如 Test262、TypeScript 官方测试集)的一致性测试,是 Rome 验证「能解析多少标准用例」的关键工具。
七、从源码看整体调用关系
综合来看,xtask 脚本与核心 crate 的调用关系可以概括为:
xtask_codegen ──grammar──▶ rome_js_syntax / rome_json_syntax(.ungram → AST)
──test──────▶ rome_js_parser/test_data(内联测试抽取)
──unicode───▶ rome_js_unicode_table(tables.rs)
xtask_bench ──────────▶ rome_js_parser / rome_js_formatter / rome_json_parser ...
xtask_lintdoc ──────────▶ rome_js_analyze / rome_json_analyze / rome_service → website 文档
xtask_contributors ─────▶ GitHub API → website/src/components/Contributors.astro
xtask_codegen的grammar依赖ungrammarcrate 与quote/proc-macro2生成 Rust 源码,可选特性schema/configuration/website对应不同生成目标(见 xtask/codegen/Cargo.toml);xtask_bench通过 path 依赖直接引用rome_js_parser、rome_js_formatter、rome_js_syntax等核心 crate(见 xtask/bench/Cargo.toml),保证测的是仓库当前源码;- 所有脚本共用
xtask根 crate 的project_root、pushd、run!等基础设施。
八、常见问题与使用建议
- 生成文件被手动修改导致 CI 失败:代码生成产物都带「do not edit」声明,CI 使用
Mode::Verify校验。请通过cargo codegen重新生成,而非手工改动。 rustfmt工具链报错:ensure_rustfmt要求 stable 工具链的 rustfmt,提示rustup component add rustfmt --toolchain stable即可。- 基准对比注意基线漂移:
--save-baseline保存的是本地基线,换机器或换 commit 后应重新保存;对比时结合--criterion的统计检验判断差异是否显著。 - nursery 规则晋升:新规则先以
newlintrule模板落地到 nursery 组,稳定后通过promoterule晋升,这一过程与lintdoc的文档生成、codegen-configuration的配置生成保持同步。 - 添加新语言支持:参照
grammar子命令对 js/css/json 三种 ungram 文件的处理方式,为新语言添加.ungram文件并扩展生成器。
总结
Rome 的 xtask 目录是一个高度工程化的开发工具集:它以 xtask 根 crate 提供跨平台基础设施,以 xtask_codegen 完成「语法定义 → AST → 格式化器 → 配置/文档」的自动化生成,以 xtask_bench 支撑基于 Criterion 的分支性能对比,以 xtask_lintdoc 实现「文档即测试」的规则文档流水线。理解这套体系,不仅能让你顺畅地参与 Rome 的规则开发与性能优化,也能为自研编译工具链的工程化提供一份可复制的范本。
【免费下载链接】tools
Unified developer tools for JavaScript, TypeScript, and the web
创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考



