企业官网建设流程全解析

Rome CLI 交互式审查模式（rome check --review）实战指南：逐条审阅 lint 诊断并快速添加 suppression 注释

【免费下载链接】toolsUnified developer tools for JavaScript, TypeScript, and the web项目地址: https://gitcode.com/gh_mirrors/to/tools

rome check --review是 Rome（统一 JavaScript / TypeScript / Web 开发者工具链）提供的一种交互式诊断审查模式：它不像普通rome check那样一次性输出全部诊断后直接退出，而是逐个展示每条 lint 诊断，并提示你为每一条选择处理方式。本文基于仓库官方 CLI 截图 lint-review.md 还原该模式的完整界面与操作流程，并结合useAltText规则源码、suppression 注释生成实现与 CLI 参数文档，讲清楚"如何进入审查模式、如何解读界面、四个选项各做什么、底层如何工作、如何结合自动修复使用"。读完本文，你将能够在真实项目中熟练使用 Rome 的交互式审查工作流。

一、--review是什么：从官方截图还原交互界面

在仓库目录 website/src/components/cli-screenshots/ 下，官方为 CLI 主页准备了六张"终端截图"素材（check.md、init.md、lint-review.md、lint-suggestions.md、noUnreachable-example.md、recover-list.md）。其中 lint-review.md 完整记录了一次rome check --review的真实终端渲染结果，是我们还原该功能的第一手证据。

1.1 命令形态与进度指示

截图顶部是命令本身：

$ rome check --review

执行后进入交互界面，顶部出现一个带背景色的标题条：

Reviewing diagnostics (3/3)

这个(3/3)是进度指示器，表示"正在审查第 3 条（共 3 条）诊断"。可以推断：--review模式会遍历本次检查产出的全部诊断，逐条等待用户裁决，而不是一次刷屏全部输出。它天然适合"诊断条数不多、需要逐一人工决策"的场景（例如提交前清理、code review 前的自查）。

1.2 诊断展示区：位置、规则名与代码上下文

紧随标题条的是当前这条诊断的完整信息：

src/App.jsx:8:3 lint/jsx-a11y/altText ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✖ Provide alt text when using img, area, input type='image', and object elements. 6 │ return <div className="App"> 7 │ <header className="App-header"> > 8 │ <img src={logo2} className="App-logo" /> │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 9 │ <p>

关键信息从左到右依次是：

• 位置：src/App.jsx:8:3—— 文件路径 + 行号 + 列号；
• 规则名：lint/jsx-a11y/altText—— 完整规则标识（category/rule 两级命名）；
• 错误摘要：红色✖前缀的规则错误信息；
• 代码上下文：带行号的源文件片段，>标记当前行，^波浪号精确覆盖出问题的语法范围（这里是第 8 行整行<img>元素）；
• 补充说明：蓝色ℹ前缀的 note，解释"为依赖屏幕阅读器的用户提供有意义替代文本"的无障碍背景。

这种"位置 → 规则 → 摘要 → 代码上下文 → 补充说明"的结构，与rome check非交互模式下的诊断渲染完全一致，区别只在于多出了下文的交互选项区。

二、截图中的规则：lint/jsx-a11y/altText源码级解析

截图中的示例诊断来自altText规则（正式注册名为useAltText）。这条规则是理解整个审查流程的最佳实例，因为它在仓库中有完整的源码、文档与测试。

2.1 规则声明与定位

规则实现在 crates/rome_js_analyze/src/analyzers/a11y/use_alt_text.rs，通过declare_rule!宏声明：

declare_rule! { /// Enforce that all elements that require alternative text have meaningful information to relay back to the end user. /// /// This is a critical component of accessibility for screen reader users... pub(crate) UseAltText { version: "10.0.0", name: "useAltText", recommended: true, } }

要点：

• name: "useAltText"对应诊断中的altText短名与lint/jsx-a11y/altText完整标识；
• recommended: true表示它属于 Rome 默认推荐规则集，开箱即用，无需显式在配置中启用；
• 规则文档同步维护在 website/src/pages/lint/rules/useAltText.md，其中包含与截图同源的错误示例与合法示例。

2.2 检查逻辑：四条判定分支

规则的run方法以Ast<AnyJsxElement>为查询类型，对每个 JSX 元素执行检查（use_alt_text.rs#L75-L128）：

细节上，has_valid_alt_text/has_valid_label两个辅助函数还会剔除空字符串（is_not_string_constant("")）、null/undefined值以及尾部 spread 属性等"假有效"情况（use_alt_text.rs#L153-L179）。也就是说，<img src="x" alt="" />同样会被判定为不合规——这解释了为什么审查模式里"Add suppression comment"（而不是"直接修好"）往往是面对此类诊断时的首选动作。

2.3 测试佐证

仓库为规则准备了专用测试用例：crates/rome_js_analyze/tests/specs/a11y/useAltText/，包含input.jsx（基础非法样例）与area.jsx（<area>场景）及其.snap快照。运行cargo test即可复现规则行为，是验证你对该规则理解是否正确的最可靠途径。

三、审查交互区：四个选项与快捷键

截图下半部分是审查模式的核心——交互决策区：

❯ How do you want to resolve this? ℹ Use arrow keys and then enter to select an option ◉ Add suppression comment (shortcut s) ◯ Do nothing (shortcut n) ◯ Exit (shortcut escape) ◯ More options... (shortcut m)

逐项解读：

操作方式为：方向键上下移动高亮项，enter确认选择；也可直接按快捷键跳过移动。每处理完一条，进度指示器推进，直至(n/n)全部完成。

3.1 默认选中的 "Add suppression comment"

默认项是Add suppression comment，这并非偶然：Rome 对 a11y 类规则不提供自动修复（因为补什么 alt 文本需要人工语义判断），而"记录本次审查决策"最自然的方式就是把抑制注释写进代码。选择该项后，Rome 会在诊断位置生成类似如下的注释：

// rome-ignore lint/jsx-a11y/altText: <explanation>

仓库中的 suppression 测试快照确认了这一格式：crates/rome_js_analyze/tests/suppression/a11y/useKeyWithClickEvents/invalid.jsx.snap 中可以看到：

{/* rome-ignore lint/a11y/useKeyWithClickEvents: <explanation> */}

以及 TypeScript/JS 普通注释形态// rome-ignore lint/correctness/noUndeclaredVariables: <explanation>（见 noUndeclaredVariables.ts.snap）。注释由三部分组成：rome-ignore关键字 + 完整规则标识 +: <explanation>理由说明，其中理由部分建议填写为什么这条代码可以豁免该规则。

四、底层原理：suppression 注释是如何被"写"进去的

"Add suppression comment"不是简单的字符串插入，Rome 需要把注释精确落在诊断对应的语法 token 上。实现位于 crates/rome_js_analyze/src/suppression_action.rs 的apply_suppression_comment函数：

pub(crate) fn apply_suppression_comment(payload: SuppressionCommentEmitterPayload<JsLanguage>) { // 1. 根据诊断文本范围找到最左侧、最合适的 token let original_token = get_token_from_offset(token_offset, diagnostic_text_range); // 2. suppression 系统按"行"工作，向前找到第一个带换行的前导 trivia let apply_suppression = original_token .as_ref() .map(|original_token| find_token_to_apply_suppression(original_token.clone())); ... }

从注释与代码可以提炼出三条设计要点：

1. 按行定位：Rome 的 suppression 是"行级"的，插入前会从诊断覆盖的 token 出发，寻找最近一个带换行（newline）的 leading trivia，把注释放在该行之前；
2. JSX 边界处理：JSX 元素内容中可能自带换行，函数会判断目标 token 是否位于JsxOpeningElement/JsxSelfClosingElement/JsxText内，以决定注释插入形态（JSX 中用{/* ... */}包裹）；
3. 模板字符串例外：JS 模板字符串内的表达式可能包含诊断，实现以${作为边界 token，把抑制注释放到${之后，避免破坏模板语义。

这段逻辑直接决定了你在审查界面按下s后看到的注释位置与格式，也解释了为什么面对src/App.jsx:8:3这样的 JSX 诊断时，生成的会是{/* rome-ignore ... */}而非// rome-ignore ...。

五、结合rome check全家桶使用：自动修复与审查的配合

审查模式解决的是"人肉决策"环节，而rome check本身还提供了自动修复能力，两者应配合使用。根据官方 CLI 参考 website/src/pages/cli.md，rome check的完整形态为：

rome check [--apply] [--apply-unsafe] [PATH]...

常用参数速查（与审查/修复工作流强相关）：

在 crates/rome_cli/src/execute/process_file/lint.rs 中可以看到，文件级修复通过 workspace 的fix_file能力执行，rome check --apply时遍历会携带fix_file_mode并批量落地修复；而--review走的是另一条"逐条人审"路径。推荐的工程化工作流是：

1. 先用rome check --apply自动处理所有 safe fixes；
2. 对剩余无法自动修复（如useAltText、noUndeclaredVariables等无 fix 或 unsafe 规则）的诊断，用rome check --review逐条审查；
3. 确认为"设计如此"的，按s写入带理由的 suppression 注释；需要稍后处理的，按n跳过；批量场景优先m查看更多选项。

此外，rome.json 位于仓库根目录，是所有命令（含check、lint、format）的配置入口，review模式同样遵循其中的 linter 规则启停与 files 忽略配置。

六、验证与深入学习路径

如果你想在本地复现截图中的效果并深入验证：

1. 运行规则测试：cargo test -p rome_js_analyze，重点查看 crates/rome_js_analyze/tests/specs/a11y/useAltText/ 下的input.jsx与快照，理解诊断输出格式；
2. 验证 suppression 生成：crates/rome_js_analyze/tests/suppression/目录下的快照展示了各种语言形态（JSX、TS）下rome-ignore注释的精确落点，可与 suppression_action.rs 的实现互相印证；
3. 对照 CLI 参数：website/src/pages/cli.md 是官方生成的 CLI 参考，rome check与rome lint两节完整列出了与--review搭配使用的全部选项；
4. 查阅规则文档：website/src/pages/lint/rules/useAltText.md 提供了该规则的合法/非法示例与 WCAG 1.1.1 无障碍指引出处。

总结

rome check --review把 Rome 的 lint 从"一次性的诊断列表"升级为"逐条可决策的交互流程"：顶部的(n/n)进度条让你掌握全局，统一的信息区（位置 / 规则 / 摘要 / 代码上下文 / note）降低理解成本，四个选项（Add suppression comment / Do nothing / Exit / More options）配合s、n、escape、m快捷键实现键盘流操作。底层上，它复用了 Rome 完整的诊断渲染管线与行级 suppression 注释引擎，确保每一笔"人工决策"都能以可追踪、可解释的形式沉淀进代码仓库。

【免费下载链接】toolsUnified developer tools for JavaScript, TypeScript, and the web项目地址: https://gitcode.com/gh_mirrors/to/tools