konsistent-fix-violations

konsistent — 修复违规项

运行 konsistent，找出问题并解决违规项。难点不在于机械地修复，而在于当一条规则导致许多违规时，判断是规则还是代码有问题，以及哪些非平凡违规值得尝试修复，哪些应暂缓处理。

规范的工作流和每项谓词的分类标准记录在 node_modules/konsistent/docs/guides/fixing-violations.md 中。对违规项进行分类前，请先阅读该文档。 本技能在该工作流之上增加了严格的门控、用户确认和 AskUserQuestion 交互。

工作流（严格按顺序执行）

1. 运行 CLI，并以 JSON 格式收集所有违规项。
2. 按规则分组违规项，并找出违规数量较多的规则。
3. 针对每条违规数量较多的规则，询问用户，是保留、更改还是移除该规则。
4. 如果需要更改规则，通过 konsistent-config 技能更新 konsistent.json。
5. 重新运行 CLI以刷新违规列表，然后暂停并在修改任何代码前征求明确确认。
6. 将剩余违规项分类，分为平凡和非平凡两类。
7. 向用户列出非平凡违规项，由用户决定如何处理每一项。
8. 修复已批准的违规项，并重新运行 CLI 进行验证。

不要跳过步骤，也不要合并步骤。步骤 3、5 和 7 中征求用户输入的要求不可妥协。

---

1. 运行 CLI

按以下顺序确定调用方式：

1. 如果 package.json 中有 konsistent 脚本 → 使用项目的包管理器：pnpm konsistent、npm run konsistent 或 yarn konsistent（根据锁文件 / packageManager 字段选择）。
2. 否则，如果 devDependencies 中包含 konsistent → 通过包运行器运行：pnpm exec konsistent、npx konsistent 等。
3. 否则，回退到 npx konsistent。

运行带有 JSON 输出的 check 命令，并设置较高的诊断上限，以免截断内容：

<runner> konsistent check --format=json --max-diagnostics=1000

注意：通过已封装 konsistent 的 npm / pnpm 脚本调用时，可能需要使用 -- 来传递标志：

pnpm konsistent check --format=json --max-diagnostics=1000
# OR if the script runs konsistent without args:
pnpm konsistent -- check --format=json --max-diagnostics=1000

JSON 输出是一个包含 { severity, conventionName, filePath, predicateName, message } 的数组。有错误时，退出代码非零，这是预期行为——无论如何都要读取 JSON。完整的输出架构请参阅 node_modules/konsistent/docs/reference/cli.md。

如果命令因违规以外的原因失败（未找到配置、配置无效、缺少依赖项），请停止并先解决根本问题。不要继续。

2. 按规则分组违规项

按 conventionName（也可按 predicateName）汇总违规项。计算每组的数量。简要向用户报告总数：

发现 N 项违规，涉及 M 条约定。规则 X 有 K 项违规；规则 Y 有 J 项违规；……

当一条规则有大约 5 项或更多违规，或者其匹配的违规文件超过该规则路径模式所匹配文件的一半时，该规则即为“违规数量较多”。请酌情判断——例如，某条规则有 4 项违规，分布在 4 个文件中，而其路径模式仅匹配 5 个文件，这也属于违规数量较多。

原因：1–2 项违规几乎总是意味着代码是特例。许多违规则往往意味着规则体现了一种代码库并未真正采用的约定——不先质疑规则就修复代码，会造成无谓改动，还可能覆盖团队实际采用的约定。

3. 询问用户：规则还是代码

对于每条数量较多的规则，都要明确询问用户如何选择。使用 AskUserQuestion 工具，并提供具体选项。不要自行推断——此决定由用户做出。

提问时说明：

• 规则的名称／描述／约束内容。
• 代码库分布情况——统计匹配文件中符合规则和违反规则的数量，并报告比例（例如：“25 个匹配的包中，12 个使用模式 A，13 个使用模式 B——代码库中的两种模式大致各占一半”）。这种说明能显著帮助用户做出决定。
• 简要总结违反规则的文件实际遵循的约定（阅读其中 2～3 个文件——它们遵循了什么共同的命名／结构模式？）。
• 每种模式各提供几个有代表性的示例（文件路径或符号名称）。

至少提供以下选项：

• 保留规则，修复代码——代码是特例；继续修复违规项。
• 修改规则以符合现有代码——违规模式才是真正的约定；更新 konsistent.json。
• 移除规则——这个约定不值得强制执行。
• 其他（自由文本，例如将 severity: warning 作为宽松处理、缩小路径模式范围、通过路径排除添加例外）。

当“修改规则”有不止一种具体形式时，应提供有意义的子选项，不要将它们合并。值得提供的子选项示例：

• 文件命名变体：${name}-options.ts 与 ${name}-model-options.ts。
• 按子模式拆分的混合规则（例如：“以 ai 结尾的单词型 provider 使用 flat-case；其他情况使用 camelCase”）——可通过 kebabToCamelMap／kebabToPascalMap 覆盖项或 placeholderSatisfies 约束来实现。
• 混合严重级别（必需项设为 error，建议项设为 warning）。

如果用户选择“修改”“移除”或“其他”，请记录第 4 步执行更改所需的具体信息。

对于数量较少的规则，跳过此步骤——假定代码有误，并在第 8 步修复。

4. 使用 konsistent-config 更新 konsistent.json

如果需要根据第 3 步的决定修改任何规则，实际编辑时应遵循 konsistent-config 技能。该技能了解谓词目录、路径占位符语法、大小写映射覆盖项、条件／迭代代码块，以及项目中 konsistent.json 的约定。不要在此处随意编辑 konsistent.json。

委派时，请提供：要修改的规则名称、用户的决定，以及具体更改（例如：“将 exportFunctions 名称模板从 ${name.toPascalCase()}Service 改为 create${name.toPascalCase()}Service”“添加 severity: warning”“为 packages/test-utils 添加路径排除”）。

配置更新后，请验证：

<runner> konsistent validate

继续之前，请修复任何配置错误。

5. 重新运行，并在修复前确认

配置更改后（如果无需更改，则在第 3 步之后），重新运行 CLI，获取反映新规则的最新违规列表：

<runner> konsistent check --format=json --max-diagnostics=1000

向用户报告更新后的数量。然后，停止并征求用户明确同意，之后才能更改任何代码：

“准备开始修复 N 个代码违规项。是否继续？”

使用 AskUserQuestion 清楚询问是或否。**用户确认之前，不得开始编辑代码。**此关卡是用户在批量更改前最后一次审查规则集的机会。

如果用户拒绝或希望进一步调整，请返回第 3 步或第 4 步。

6. 分类：简单问题与复杂问题

确认后，对其余违规项逐一分类。分类前，请阅读 node_modules/konsistent/docs/guides/fixing-violations.md，了解各谓词的分类标准和搜索启发式。

主要规则：

• 先搜索代码库。 konsistent 报告的“缺失”文件或导出，往往已经以不同名称、位于不同文件或采用不同大小写形式存在。这类问题仍属于简单问题——重命名、移动或重新导出即可。将问题标记为复杂问题前，请按确切名称、大小写变体、去除前后缀后的名称、独特词干和相邻位置进行搜索，并参照现有已成功匹配项。
• 拿不准时，归为复杂问题。 将误报归入简单问题，比归入复杂问题更糟——前者会导致未经用户确认就写出不合适的代码。但在搜索前不要将问题归为复杂问题：快速 grep 往往就能将问题判定为简单问题。

各谓词（haveType、haveFiles、export/exportConstants、exportTypes、exportFunctions、exportInterfaces、exportClasses、import/importTypes）的完整分类标准见 node_modules/konsistent/docs/guides/fixing-violations.md。

7. 列出复杂问题

将复杂问题整理成清晰的列表。每项包括：

• 文件路径和规则。
• 违规消息。
• 一句话说明为何属于复杂问题（例如，“代码库中不存在类型 FooConfig”，“需要拆分现有类”）。

向用户展示列表，并询问他们希望如何处理每个违规项或每组违规项：

• 暂缓——留待以后处理。提供以下两项后续帮助：
  • 起草 GitHub issue 的标题和正文，概述待处理工作（由用户创建）。
  • 通过 konsistent-config 技能，在 konsistent.json 中为暂缓处理的文件添加路径排除规则，确保 CI 保持通过，同时规则仍适用于其他所有匹配文件。待暂缓工作完成后，移除该排除规则。
• 尝试——让 Agent 尝试处理；询问用户是否能提供有帮助的背景信息（预期类型、可参考的示例、类似代码的参考资料）。
• 跳过——明确标记为不处理（例如，将放宽规则；请记下这一点，并在需要时返回第 4 步）。

使用 AskUserQuestion 征求决定。对于“尝试”，请主动询问背景信息——不要在未征求用户意见的情况下默默开始复杂改动。

8. 修复已批准的违规项

编辑任何公共 API 前，请决定重命名导出的向后兼容策略。 这是本步骤开始时最重要的决定——先确定一次，然后在整个处理过程中统一执行。

8a. 询问：项目是否处于允许破坏性变更的阶段？

使用 AskUserQuestion。问题应表述为：“重命名会影响包边界导出。是否可以进行破坏性变更，还是需要通过弃用别名保持向后兼容？”

• 可以进行破坏性变更（例如，即将升级主版本、处于 beta 阶段、版本低于 1.0，或仅供内部使用的项目）——统一直接重命名。不添加别名。跳过 8b。
• 需要保持向后兼容——继续执行 8b，确认哪些重命名会跨越包边界；仅为这些重命名添加别名。

8b. 如果需要保持向后兼容，请对每个重命名进行分类

只有跨越包边界导出的符号才需要考虑向后兼容。包内的重命名只是需要添加别名的噪声。

• 包边界导出（公共 API） — 可通过包的入口点从包外部访问该符号。检查 package.json 中的 exports / main / module / types 字段，并追踪每个入口点重新导出的内容（通常是 src/index.ts），以确定是否可以访问。如果可通过任何入口点访问 → 必须添加别名。
• 仅供内部使用的导出 — 在同一个包的文件之间使用了 export 关键字，但无法通过任何入口点访问该符号。无需添加别名。 可自由重命名，并更新包内调用位置。

对于 monorepo，请对每个包分别重复此检查——在 packages/foo/src/utils.ts 中进行的重命名，对 foo 来说可能是内部重命名，即使 foo 的入口点导出了许多其他符号。

对于每个包边界重命名，请在入口点中保留一个已弃用的别名，并同时添加新名称：

export { newName } from "./impl";
/** @deprecated Use `newName` instead. */
export { newName as oldName } from "./impl";

更新包内调用方，使其使用新名称。如果项目维护变更日志，请在其中记录这些重命名。

关于包边界区分的原因，请参阅 node_modules/konsistent/docs/guides/fixing-violations.md。

按以下顺序修复：

1. 修复第 6 步中的所有简单违规项。
2. 结合用户提供的上下文，尝试修复第 7 步中的非简单违规项。

尽可能按文件分组修复，以尽量减少改动。不要在每项修复之间重新运行 konsistent——请批量编辑。

完成后，重新运行 CLI：

<runner> konsistent check --format=json --max-diagnostics=1000

报告：

• 已解决的违规项。
• 仍存在的违规项（已延期的违规项以及新增的任何违规项）。
• 如果出现了新的违规项，请先进行调查，再宣布完成。

运行项目的检查，确保代码编辑没有导致其他问题（读取 package.json，确认实际使用的脚本）：

pnpm typecheck
pnpm test
pnpm check

---

重要注意事项

• 绝不要在第 4 步之后编辑 konsistent.json 来消除违规项，除非先回到第 3 步。规则与代码之间的选择应经过审慎决定。
• 绝不要跳过第 5 步的确认环节。即使没有高计数规则且配置没有变化，也要在批量修改代码之前征求确认。
• 绝不要仅仅因为提示信息看起来简短，就将违规项归类为简单项。请先阅读文件，并确认目标符号、类型或文件确实存在。
• 修复重命名时，请搜索代码库中的所有引用并更新它们——不要留下失效的导入。
• 如果运行 konsistent 后发现没有违规项，请报告这一点并停止。无需进行任何修复。