linting-alignment

Linting 对齐

对齐时应优先遵循仓库策略：在当前上游行为允许的范围内尽量保持一致，同时保留仍能保护实际项目约束的本地规则。应将配置视为可执行的所有权关系图，而不是一串熟悉的软件包名称。

根据请求推断授权模式：

• 审查 — 检查并报告；保持工作树不变。
• 对齐 — 检查、进行有针对性的修改并验证。用户要求更新、修复、迁移或配置工具链时，默认采用此模式。
• 发布 — 先对齐，只有在用户明确要求时才提交、推送或发起评审。

1. 确认仓库权限

确定仓库根目录、当前分支、工作树状态，以及适用的根目录和作用域内 Agent 指令。阅读适用于受影响范围的代码风格、贡献、依赖、生成文件和验证指南。

运行工具前，先识别用户已有的更改。根据仓库证据而非惯例，确定包管理器、工作区布局、支持的运行时、基准分支和请求的发布边界。

完成标准： 已确认适用的策略、验证入口、分支边界，以及每个预先存在的脏文件。

2. 构建所有权关系图

通过追踪可执行关系，清点 lint 覆盖范围：

• 包清单、锁文件、工作区声明，以及根目录或包级脚本。
• 根目录和嵌套的 linter、formatter、analyzer、忽略规则、编辑器、钩子和 CI 配置。
• 导入、extends、展开语法、插件声明、CLI 调用、生成文件，以及包的 peer 或可选依赖。
• 一方源码中的内联禁用规则和 formatter 忽略规则。

为发现的每个节点记录其角色和所有者：编排器或预设、linter、formatter、原生插件、运行时加载的插件、独立 analyzer、类型感知配套工具、作用域配置或执行使用方。沿导入关系追踪到已安装的软件包或已发布源码，直到确认有效预设、插件成员和配置所有者。根据此关系图确定软件包集合；工具名称耳熟并不能证明某个软件包或规则处于启用状态。

区分以下四条执行路径：

1. 核心路径 — formatter 和 linter 命令。
2. 插件路径 — 由 linter 执行的原生或运行时加载规则。
3. Analyzer 路径 — 独立静态分析 CLI，其项目扫描范围超出插件覆盖范围。
4. 类型感知路径 — 语义规则、编译器诊断及其项目图依赖。

如果关系图中包含 Ultracite、Oxlint、Oxfmt 或其集成工具，在将任何配置归类为冗余之前，请完整阅读 references/ultracite-oxc-ownership.md。如果其中包含 React Doctor 或其集成工具，在比较其 analyzer 和插件路径之前，请完整阅读 references/react-doctor-ownership.md。

完成标准： 每条已配置命令都能通过其配置和导入追溯到已安装的所有者；每个嵌套作用域和执行路径都已纳入考量；重复或相互竞争的工具已与有意互补的路径区分开来。

3. 建立可比基线

在进行对齐编辑之前，运行仓库批准的最小只读命令，检验范围内的每条活跃通道。记录准确的命令、版本、退出码、诊断数量或类别，以及具有代表性的有效配置。若工具提供打印配置、规则列表、调试或文件列表命令，且能证明哪些配置和规则处于启用状态，请优先使用。

确保比较条件受控：前后使用相同的工作树、环境、目标和标志。如果工作树中已存在工具链变更，则在隔离的临时工作树中，基于固定的 Git 版本点构建变更前基线，或使用其他同等可比的产物。只有当现有 CI 的修订版本、命令和环境均匹配时，才可将其用作基线。将无法获取的基线标记为缺口；没有比较依据时，不要将诊断称为回归。

如果基线命令失败，应将该故障与请求的变更分开处理。基线是证据，不是修复无关源代码的许可。

**完成条件：**每条活跃通道都有可复现的变更前状态，或明确的比较缺口；且相同的探测命令已准备好用于变更后状态。

4. 验证所属层

对于当前版本的配置审查，请检查已安装的预设和软件包源代码。对于升级或迁移，还应检查每个变更图节点的主要发行说明、迁移指南、软件包清单和官方文档。若仓库规定了文档服务，请使用该服务。

核实可能影响本地行为的事实：预设包含的内容、规则默认值、捆绑或外部插件、对等依赖要求、配置合并和发现语义、忽略行为、修复器行为、类型感知要求、支持的文件类型以及稳定性保证。

根据证据，将每项上游变更分类为 纳入、无操作、暂缓、拆分或后续处理。即使是语义化版本兼容的发行版，也可能新增诊断或格式化输出，因此发行版分类不能替代基线。

**完成条件：**已证明当前生效行为，并为范围内的每项上游变更提供有证据支持的处理结论。

5. 判断本地调整的价值

将每个本地预设层、规则覆盖、插件、嵌套配置、忽略模式、抑制项、重复命令和非默认格式化选项分类为 保留、移除、缩小范围、修复源头、迁移 或 暂缓。

只有当前证据直接支持的变更才有充分理由：已验证的上游覆盖、现存诊断、失效的解析边、执行冲突、过时依赖、无效范围或明确的仓库策略变更。保留仍体现领域安全、框架行为、生成代码边界、兼容性、性能或有意迁移基线的偏离项。

规则正确且源头修复比例外更精简时，优先修复源头。代码有意采用不同做法时，优先使用范围最小的有效例外。若独立分析器的 CLI 能覆盖插件通道无法处理的工作，则予以保留；只有在其运行时和项目图要求均得到满足时，才保留类型感知检查。

统计每项源头修复（已选或候选）涉及的文件数，记录修复由格式化程序、自动修复、代码迁移工具还是手动编辑完成，以及它新暴露出的其他规则问题。纯样式默认项（其目的是保持一致性，而非捕获错误）若修复涉及的文件超过基线中该工具所检查文件数的十分之一，则应 暂缓，除非请求明确指定了该默认项；泛指上游默认设置的请求不指定任何特定默认项。

如果对于所有调用（包括钩子和编辑器显式传入的文件列表），都有其他机制排除某个忽略模式所涵盖的路径；或者这些路径中的文件（包括工具之后会写入的文件）都能通过检查，则该忽略模式应 移除。探测时零文件变更只能证明当前树的状态；Changesets、发布工具和代码生成器会在探测之后写入文件。

完成标准： 范围内每项已变更或保留的非默认选项都有证据、负责人、通道和记录的处置结果；范围内每条与上游默认值不同的规则或格式化选项，都记录了其文件数以及修复会在其他规则中暴露的问题。

6. 先探测，再应用

每次只探测一条所有权边或一组规则，然后重新运行对应的基线命令。迁移和生成器实验应在临时 worktree 或一次性副本中进行，并使用各自独立安装的依赖，因为与用户的依赖安装共享目录或使用符号链接的探测可能会改写该安装。不要让被否决的探测留在用户的 worktree 中。

在 Review 模式下，所有探测都必须只读，不得更改 worktree；继续进行比较和报告，不应用任何处置结果。

除非当前源码或经过审查的试运行证明设置和初始化命令会保留自定义配置，否则应将它们视为生成器。如果重新生成会替换仓库自有策略，则直接编辑精简的入口配置，或有选择地应用生成器经过审查的差异。

简化配置前，先验证其合并和发现行为。若预设不继承忽略设置，则保留显式的忽略传播。若最近的嵌套配置会替代根配置，则保留或添加显式的父级扩展。考虑会禁用嵌套发现的标志，以及相对于声明配置的路径解析方式。

在 Align 或 Publish 模式下，只应用第 5 步中的处置结果。仅在策略发生变更时更新策略文档；发布说明的记录工作留在审查或变更记录中。

完成标准： worktree 中只有已选定的变更；所有修改后的图边都能解析；不存在被否决的实验和附带的格式化改动。

7. 比较并验证

使用相同范围和环境，重新运行完全相同的基线探测。逐项比较生效配置、退出状态、诊断信息、格式化输出和相关运行成本。说明每项差异是由请求的更改还是已验证的上游更改造成的。

在 Review 模式下，只使用仓库批准的只读检查，并将具备修改能力的门禁记录为已跳过。在 Align 或 Publish 模式下，运行仓库要求的格式化、lint、类型、测试和聚合验证门禁。若存在 Git，随后运行 git diff --check。审查最终差异，并确认：

• 每项依赖都由一个有效的图边所需。
• 每项配置和忽略规则都作用于预期范围。
• 插件、分析器和类型感知通道没有被误当作彼此的替代品。
• 现有基线失败与对齐工作保持隔离。

修复、暂缓或拆分由对齐导致的回归。记录确切阻碍，不要将更改范围扩大到无关的清理工作。

**完成条件：**前后状态可比较，所有差异都有说明，必需的门禁均已通过或有确切阻碍，且最终差异符合授权范围。

8. 在要求的边界内报告

开头先说明结果。概述所有权关系图、直接有据可依的更改、基线比较、验证结果、暂缓或延期的工作，以及任何来源或比较方面的缺口。列出所有保留的上游默认值偏差及其原因；对于规则或格式化器选项，还要列出涉及的文件数量，以及修复后会在其他规则中暴露的任何问题。将每项延期采用的默认值明确标记为待用户决定。

在 Review 模式下，确认工作树未发生变化。在 Align 模式下，停在发布之前。在 Publish 模式下，遵循仓库指南，仅通过明确要求的边界发布已验证的对齐文件，并在审查说明中列出偏差；将尚待托管平台检查的项目与失败项分开报告。

**完成条件：**用户能够了解工具链的所有权归属、每项本地偏差为何改变或保留、哪些延期采用的默认值仍待用户决定、对齐后的状态与基线相比如何，以及确切的发布状态。