konsistent-config

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

konsistent Configuration

konsistent配置

Create or modify a

konsistent.json

file that enforces structural conventions for the project. The

konsistent

CLI checks filesystem structure and TypeScript exports/imports — it is not a style linter.

创建或修改

konsistent.json

文件，为项目强制执行结构规范。

konsistent

CLI检查文件系统结构和TypeScript导出/导入——它不是代码风格检查器。

Prerequisites

前提条件

Check if the

konsistent

package is already installed:

```
konsistent
```
available in root
```
package.json
```
```
node_modules/konsistent
```
directory exists
a
```
konsistent
```
script exists in
```
package.json
```

If not, the

konsistent

CLI must be installed first. Use the project's package manager. For example, with PNPM:

bash

pnpm add konsistent --save-dev

Then, ensure

package.json

has a

konsistent

script which invokes the

konsistent

CLI. At a minimum:

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

Once the package has been successfully installed, proceed to the primary workflow.

检查是否已安装

konsistent

包：

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

如果未安装，必须先安装

konsistent

CLI。使用项目的包管理器，例如使用PNPM：

bash

pnpm add konsistent --save-dev

然后，确保

package.json

中有一个调用

konsistent

CLI的

konsistent

脚本。至少需要：

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

成功安装包后，进入主工作流程。

Workflow

工作流程

Check if
```
konsistent.json
```
already exists at the project root.

Read

node_modules/konsistent/konsistent.schema.json

to confirm the authoritative shape.

Read the relevant docs in
```
node_modules/konsistent/docs/
```
(see References below) before making changes.
If
```
konsistent.json
```
exists: read it, then add/remove/update conventions as requested by the user.
If
```
konsistent.json
```
does not exist: create it at the project root.

Before creating a new config, or if the user has not provided any specific requests for editing an existing config, you must:

Explore the user's codebase to understand existing structure and naming patterns.

Refer to

node_modules/konsistent/docs/guides/exploring-codebases.md

for what to look out for.

When modifying an existing config:

Preserve all conventions not related to the user's request.
Preserve existing
```
name
```
,
```
description
```
, and
```
severity
```
values unless asked to change them.
When adding conventions, append to the
```
conventions
```
array.
When the user reports violations, read the existing config and the violating files to determine whether to fix the config or advise fixing the code.

检查项目根目录是否已存在
```
konsistent.json
```
。

读取

node_modules/konsistent/konsistent.schema.json

以确认权威结构。

在进行更改前，阅读
```
node_modules/konsistent/docs/
```
中的相关文档（见下文参考资料）。
如果
```
konsistent.json
```
已存在：读取该文件，然后根据用户请求添加/删除/更新规范。
如果
```
konsistent.json
```
不存在：在项目根目录创建该文件。

在创建新配置，或用户未提供编辑现有配置的具体请求时，必须：

探索用户的代码库，了解现有结构和命名模式。

参考

node_modules/konsistent/docs/guides/exploring-codebases.md

，明确需要关注的内容。

修改现有配置时：

保留所有与用户请求无关的规范。
保留现有的
```
name
```
、
```
description
```
和
```
severity
```
值，除非用户要求更改。
添加规范时，追加到
```
conventions
```
数组中。
当用户报告违规时，读取现有配置和违规文件，以确定是修复配置还是建议修复代码。

References

参考资料

All canonical documentation lives in

node_modules/konsistent/docs/

(published with the package). Read these before authoring config:

node_modules/konsistent/docs/reference/configuration.md

— top-level

konsistent.json

shape (version, conventions, severity, excludeFiles).

node_modules/konsistent/docs/reference/predicates.md

— every

must

predicate (

haveType

haveFiles

export

exportTypes

exportConstants

exportFunctions

exportInterfaces

exportClasses

import

importTypes

node_modules/konsistent/docs/reference/path-patterns.md

— globs, placeholders, case transformations (

toPascalCase

toCamelCase

toFlatCase

toNthSegment

extract

, …), negation.

node_modules/konsistent/docs/reference/constraints.md

—

matches

segments

for inline path constraints and

if.placeholderSatisfies

node_modules/konsistent/docs/reference/conditional-rules.md

—

if

for

excludeFiles

blocks when

must

is an array.

node_modules/konsistent/docs/reference/case-maps.md

—

kebabToPascalMap

kebabToCamelMap

for acronyms and special casing.

```
node_modules/konsistent/docs/guides/examples.md
```
— copy-pasteable common patterns (provider packages, factories, adapters, conditional rules, …).

node_modules/konsistent/docs/guides/exploring-codebases.md

— pattern-identification approach before writing rules.

node_modules/konsistent/docs/

is not present (e.g. the project doesn't have

konsistent

installed yet), fall back to the published docs at https://github.com/vercel-labs/konsistent/tree/main/docs.

所有标准文档都位于

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

—— 通配符、占位符、大小写转换（

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
```
—— 可直接复制的常见模式（提供者包、工厂、适配器、条件规则等）。

node_modules/konsistent/docs/guides/exploring-codebases.md

—— 编写规则前的模式识别方法。

如果

node_modules/konsistent/docs/

不存在（例如项目尚未安装

konsistent

），请使用GitHub上发布的文档：https://github.com/vercel-labs/konsistent/tree/main/docs。

Guidelines

指南

Explore the user's project first — understand actual directory structure, naming conventions, and patterns before writing rules.
Use
```
severity: "warning"
```
for conventions that are recommended but not mandatory.
Use
```
name
```
on conventions to give them identifiable IDs (must be kebab-case).
Use
```
description
```
when the convention name alone isn't self-explanatory.
Prefer templates with case transformations over hardcoded names — this is konsistent's key strength.
Group related predicates in one convention when they apply to the same path.
Use separate conventions for the same path when different severities are needed.
Use path negation to exclude known exceptions rather than listing all included paths.
Consider conventions between related files as well, not only within a single file. Use the
```
haveFiles
```
predicate to ensure a specific other file exists based on the matched file, and use
```
for.files
```
to enforce conventions within specific other related files based on the matched file.
Validate the generated config by running
```
konsistent validate
```
via the
```
package.json
```
script (e.g.
```
pnpm konsistent validate
```
).
Test the config against the actual codebase by running
```
konsistent
```
via the
```
package.json
```
script (with no arguments).

Important reminder: The objective is NOT to write a

konsistent.json

file that leads to zero errors when running the CLI. That would defeat the purpose. The objective is to create a konsistent.json file that identifies violations to patterns used in the codebase, even if they are not being 100% adhered to.

首先探索用户的项目——在编写规则前，了解实际的目录结构、命名规范和模式。
对于建议性而非强制性的规范，使用
```
severity: "warning"
```
。
在规范上使用
```
name
```
属性，为其分配可识别的ID（必须为kebab-case格式）。
当规范名称本身无法清晰说明时，使用
```
description
```
。
优先使用带大小写转换的模板，而非硬编码名称——这是konsistent的核心优势。
将适用于同一路径的相关断言分组到一个规范中。
当需要不同的严重级别时，为同一路径使用单独的规范。
使用路径取反来排除已知例外，而非列出所有包含的路径。
考虑相关文件之间的规范，而不仅仅是单个文件内的规范。使用
```
haveFiles
```
断言确保匹配的文件对应的特定其他文件存在，并使用
```
for.files
```
在匹配文件对应的特定相关文件内强制执行规范。
通过
```
package.json
```
脚本运行
```
konsistent validate
```
来验证生成的配置（例如
```
pnpm konsistent validate
```
）。
通过
```
package.json
```
脚本运行
```
konsistent
```
（不带参数），在实际代码库中测试配置。

重要提醒： 目标不是编写一个运行CLI时零错误的

konsistent.json

文件，这会违背其初衷。目标是创建一个konsistent.json文件，能够识别代码库中使用的模式的违规情况，即使这些模式并未被100%遵守。