Rome CLI 交互式审查模式rome check --review实战指南逐条审阅 lint 诊断并快速添加 suppression 注释【免费下载链接】toolsUnified developer tools for JavaScript, TypeScript, and the web项目地址: https://gitcode.com/gh_mirrors/to/toolsrome 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 typeimage, and object elements. 6 │ return div classNameApp 7 │ header classNameApp-header 8 │ img src{logo2} classNameApp-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方法以AstAnyJsxElement为查询类型对每个 JSX 元素执行检查use_alt_text.rs#L75-L128元素判定条件通过标准img无alt且无aria-label且无aria-labelledby→ 报错三者至少其一area同上三者至少其一input typeimage仅当type静态值等于image时检查三者至少其一object无title且无aria-label且无aria-labelledby且无可访问子内容 → 报错使用title或 ARIA 标签细节上has_valid_alt_text/has_valid_label两个辅助函数还会剔除空字符串is_not_string_constant()、null/undefined值以及尾部 spread 属性等假有效情况use_alt_text.rs#L153-L179。也就是说img srcx alt /同样会被判定为不合规——这解释了为什么审查模式里Add suppression comment而不是直接修好往往是面对此类诊断时的首选动作。2.3 测试佐证仓库为规则准备了专用测试用例crates/rome_js_analyze/tests/specs/a11y/useAltText/包含input.jsx基础非法样例与area.jsxarea场景及其.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)逐项解读选项快捷键行为Add suppression comments在当前诊断位置插入一条rome-ignore抑制注释将这条规则对该行/元素的报告静默是默认高亮项◉Do nothingn跳过当前诊断不做任何改动继续下一条Exitescape退出整个审查流程中止后续诊断More options...m展开更多处理方式截图中未展开从代码结构看通常可包含应用 safe fix 等后续动作操作方式为方向键上下移动高亮项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: SuppressionCommentEmitterPayloadJsLanguage) { // 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())); ... }从注释与代码可以提炼出三条设计要点按行定位Rome 的 suppression 是行级的插入前会从诊断覆盖的 token 出发寻找最近一个带换行newline的 leading trivia把注释放在该行之前JSX 边界处理JSX 元素内容中可能自带换行函数会判断目标 token 是否位于JsxOpeningElement/JsxSelfClosingElement/JsxText内以决定注释插入形态JSX 中用{/* ... */}包裹模板字符串例外JS 模板字符串内的表达式可能包含诊断实现以${作为边界 token把抑制注释放到${之后避免破坏模板语义。这段逻辑直接决定了你在审查界面按下s后看到的注释位置与格式也解释了为什么面对src/App.jsx:8:3这样的 JSX 诊断时生成的会是{/* rome-ignore ... */}而非// rome-ignore ...。五、结合rome check全家桶使用自动修复与审查的配合审查模式解决的是人肉决策环节而rome check本身还提供了自动修复能力两者应配合使用。根据官方 CLI 参考 website/src/pages/cli.mdrome check的完整形态为rome check [--apply] [--apply-unsafe] [PATH]...常用参数速查与审查/修复工作流强相关参数作用--apply应用安全修复safe fixes并格式化执行路径对应FixFileMode::SafeFixes--apply-unsafe应用安全 不安全修复并做格式化与 import 排序对应FixFileMode::SafeAndUnsafeFixes--linter-enabledtrue\|false单独开关 linter 检查--formatter-enabledtrue\|false单独开关格式化检查--max-diagnosticsNUMBER限制单次输出的诊断条数默认 20--json以 JSON 格式输出报告--stdin-file-pathPATH从标准输入读取代码并按指定文件名/扩展名处理在 crates/rome_cli/src/execute/process_file/lint.rs 中可以看到文件级修复通过 workspace 的fix_file能力执行rome check --apply时遍历会携带fix_file_mode并批量落地修复而--review走的是另一条逐条人审路径。推荐的工程化工作流是先用rome check --apply自动处理所有 safe fixes对剩余无法自动修复如useAltText、noUndeclaredVariables等无 fix 或 unsafe 规则的诊断用rome check --review逐条审查确认为设计如此的按s写入带理由的 suppression 注释需要稍后处理的按n跳过批量场景优先m查看更多选项。此外rome.json 位于仓库根目录是所有命令含check、lint、format的配置入口review模式同样遵循其中的 linter 规则启停与 files 忽略配置。六、验证与深入学习路径如果你想在本地复现截图中的效果并深入验证运行规则测试cargo test -p rome_js_analyze重点查看 crates/rome_js_analyze/tests/specs/a11y/useAltText/ 下的input.jsx与快照理解诊断输出格式验证 suppression 生成crates/rome_js_analyze/tests/suppression/目录下的快照展示了各种语言形态JSX、TS下rome-ignore注释的精确落点可与 suppression_action.rs 的实现互相印证对照 CLI 参数website/src/pages/cli.md 是官方生成的 CLI 参考rome check与rome lint两节完整列出了与--review搭配使用的全部选项查阅规则文档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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考