konsistent-config

konsistent 配置

创建或修改 konsistent.json 文件，以强制项目遵循结构约定。konsistent CLI 检查文件系统结构以及 TypeScript 导出/导入——它不是样式检查工具。

核心目标

**重要提醒：**不要编写会导致运行 konsistent 检查时零错误的 konsistent.json 文件。那样就违背了目的。目标是创建一个 konsistent.json 文件，用于识别代码库中使用的模式所遭到的违反情况，即使这些模式并未得到 100% 遵循。根据代码库中的主流模式添加约定，即使其他实例违反了这些模式。

将现有代码库视为推断约定的证据，而不是一份要求每条约定都必须适用的规范。不遵循主流模式的现有文件是预期会发现的问题，而不是证明该约定有误。

配置成功后，konsistent 可以因存在违规而退出。这些违规正是预期的审计结果。只有 konsistent validate 预期能在没有错误的情况下通过。

工作流程

1. 设置 konsistent CLI（仅在尚未设置时）

检查是否已安装 konsistent 包：

• 根目录 package.json 中有 konsistent
• node_modules/konsistent 目录存在
• package.json 中有 konsistent 脚本

如果尚未安装，则必须先安装 konsistent CLI。使用项目的包管理器。例如，使用 PNPM：

pnpm add konsistent --save-dev

然后，确保 package.json 中有一个调用 konsistent CLI 的 konsistent 脚本。至少应包含：

  "scripts": {
    "konsistent": "konsistent"
  }

如果以上条件都已满足，或满足后，请继续第 2 节。

2. 根据是否存在 konsistent.json 文件确定操作模式

1. 检查项目根目录下是否已存在 konsistent.json。
2. 阅读 node_modules/konsistent/konsistent.schema.json，确认权威的结构定义。
3. 在进行更改前，阅读 node_modules/konsistent/docs/ 中的相关文档（请参阅下文的参考资料）。
4. 如果存在 konsistent.json：阅读该文件，然后根据用户要求添加/删除/更新约定。
5. 如果不存在 konsistent.json：在项目根目录创建该文件。

3. 创建或编辑 konsistent.json 文件

探索用户的代码库，了解现有结构和命名模式。请参阅 node_modules/konsistent/docs/guides/exploring-codebases.md，了解需要关注的内容。

务必从整体上审查代码库中的结构约定。对于包含多个嵌套子目录的大型代码库，可考虑使用子 Agent 分别检查代码库的不同部分。向每个子 Agent 说明以下小节中列出的所有分析要求，并让子 Agent 收集原始证据，而不是做出最终的主流模式判断。

如果由多个子 Agent 分别探索不同部分，请确保能将它们的发现合并为完整且相关的样本集合。每个子 Agent 必须报告其检查范围、该范围内的实例总数、符合与不符合的数量、相互竞争的模式以及有代表性的示例。主 Agent 必须合并这些发现、还原每个完整的样本集合，并根据合并后的证据判断主流模式。在某个委派部分中占主导地位的模式，不一定在完整样本集合中也占主导地位。

还要考虑相关文件之间的约定，而不仅仅是单个文件内部的约定。使用 haveFiles 谓词，根据匹配的文件确保特定的其他文件存在；使用 for.files，根据匹配的文件在特定的其他相关文件中强制执行约定。

必需的模式证据

在记录每项候选约定的证据之前，不要编写配置。对于每项候选约定：

1. 确定完整的相关范围，例如所有同级软件包、适配器、路由或 barrel 文件。也要考虑相关文件之间的约定，而不只是单个文件内的约定。

• 例如，使用 haveFiles 谓词，根据匹配的文件确保存在特定的其他文件；使用 for.files，根据匹配的文件在特定的其他相关文件中强制执行约定。

2. 统计范围内的总数、符合约定的实例数，以及不符合约定的实例数。始终注明分母；仅举出少数几个匹配示例，无法证明该模式占主导。
3. 搜索反例时要和搜索支持性示例一样有意识。检查有代表性的符合与不符合实例。
4. 比较相互竞争的模式。默认情况下，只有某项候选约定至少出现 3 次，且占相关范围的至少三分之二时，才可视为占主导。
5. 遇到相互竞争的模式且没有明显占主导的“胜出者”时，请暂停并询问用户要强制执行哪种模式（或是否不强制执行任何一种）。
6. 对于每项已确定的约定（通过占主导的候选模式或用户决定），判断不符合的实例是违规，还是属于语义上确实不同的范围。仅凭现有差异，并不能证明例外合理。

探索时使用证据表：

候选约定	范围	符合	违反	相互竞争的模式	决定
每个软件包都有 src/index.ts	12 个软件包	10	2	无	强制执行
服务文件使用 -service 后缀	9 个服务文件	5	4	-service 与 -svc	存在歧义；询问用户

不要编造条件，让所有相互竞争的变体都变得有效。如果证据存在歧义，请暂停并询问用户要强制执行哪种约定，或是否不强制执行任何约定。

对抗性审查

将候选约定写入配置前，先尝试推翻它：

• 搜索整个范围，不要找到几个支持性示例后就停止。
• 留意是否存在更有力的竞争约定，或会改变范围的语义边界。
• 检查是否已有其他工具强制执行该行为。
• 优先选择能揭示真正离群项的规则，而不是能解释所有现有文件的规则。

审查的目的是淘汰薄弱或臆造的模式，而不是消除强模式下的违规。

修改现有配置时：

• 保留与用户请求无关的所有约定。
• 除非用户要求修改，否则保留现有的 name、description 和 severity 值。
• 添加约定时，将其追加到 conventions 数组。
• 用户报告违规时，阅读现有配置和违规文件，以判断应修复配置还是建议修复代码。

禁止的优化

绝不能为了实现以下任何结果而优化配置：

• 不报告任何违规。
• 让所有现有文件都有效。
• 迁就观察到的所有差异。
• 运行 CLI 后减少违规数量。
• 仅为了让 CLI 以退出代码 0 通过，就将约定的 severity 标记为 "warning"。

不得仅因为现有代码违反某项约定，就弱化、缩小、限定或排除该约定。

验证

通过 package.json 脚本运行 konsistent validate，验证生成的配置（例如 pnpm konsistent validate）。

验证成功后，冻结基于证据的配置，并通过不带参数运行 package.json 脚本中的 konsistent，审计实际代码库。将报告的违规项视为审计发现，而不是配置失败。

只有满足以下任一条件时，才允许在审计后更改配置：

• 配置未编码证据表中记录的模式。
• 路径模式意外包含了一个独立的语义类别。
• 配置错误使用了 konsistent 架构或谓词 API。
• 新发现的代码对已记录证据的影响足够大，导致候选模式不再占主导。

“现有文件不符合此规则”绝不是更改配置的充分理由。对于每项审计后的更改，都要说明适用的允许理由，并在相关时更新已记录的证据。

参考资料

所有权威文档都位于 node_modules/konsistent/docs/（随软件包发布）。编写配置前请先阅读：

• node_modules/konsistent/docs/reference/configuration.md — 顶层 konsistent.json 结构（version、conventions、severity、excludeFiles）。
• node_modules/konsistent/docs/reference/predicates.md — 所有 must 谓词（haveType、haveFiles、export、exportTypes、exportConstants、exportFunctions、exportInterfaces、exportClasses、import、importTypes）。
• node_modules/konsistent/docs/reference/path-patterns.md — glob、占位符、大小写转换（toPascalCase、toCamelCase、toFlatCase、toNthSegment、extract，等等）、否定。
• node_modules/konsistent/docs/reference/constraints.md — 用于内联路径约束的 matches、segments，以及 if.placeholderSatisfies。
• node_modules/konsistent/docs/reference/conditional-rules.md — 当 must 是数组时使用的 if / for / excludeFiles 块。
• node_modules/konsistent/docs/reference/case-maps.md — 用于缩写和特殊大小写的 kebabToPascalMap、kebabToCamelMap。
• node_modules/konsistent/docs/guides/examples.md — 可直接复制粘贴的常见模式（provider 软件包、工厂、适配器、条件规则，等等）。
• node_modules/konsistent/docs/guides/exploring-codebases.md — 编写规则前的模式识别方法。

配置语法建议

• 在 conventions 上使用 name，为其设置可识别的 ID（必须采用 kebab-case）。
• 如果 convention 名称本身不够清晰，请使用 description。
• 优先使用带大小写转换的模板，而非硬编码名称——这是 konsistent 的核心优势。
• 当相关谓词适用于相同路径时，将它们归入同一个 convention。
• 当相同路径需要不同严重级别时，使用单独的 conventions。
• 使用路径否定排除已知例外，但仅限于不属于该 convention 预期类别的语义类别，例如生成文件、测试夹具、供应商代码，或有明确依据的不同软件包类别。

配置语法注意事项

• 不要尝试在声明名称或导出名称中使用 *。这些通配符仅允许用于路径段。

完成报告

交付配置时，请报告：

• 每项推断出的 convention 及其证据比例，例如 12 个实例中有 10 个符合。
• 有代表性的符合示例。
• 审计发现的有代表性的违规项，或明确说明未发现违规项。
• 有意跳过的模糊候选模式。
• 每项排除项及其不属于该 convention 预期类别的语义原因。

不要将成功描述为“konsistent 通过”。应区分架构验证成功与代码库审计发现。