conformetry-configure

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Configuring conformetry and writing templates

配置 conformetry 与编写模板

A generator pairs a name with a template — an ordinary folder of ordinary files — and the inputs needed to render it. The configuration declares generators; the template folder is the whole definition of what gets produced. The same template is then what instances are measured against, so a template is a standard as much as a starting point.

一个生成器将名称与模板（一个存放普通文件的普通文件夹）以及渲染所需的输入关联在一起。配置负责声明生成器；模板文件夹完整定义了最终生成的内容。实例随后也以同一个模板为基准接受度量，因此模板既是一个起点，也是一项标准。

The configuration

配置

The configuration file default-exports an array, one entry per generator. Only two fields are required:

Field	Required	Meaning
`name`	yes	How the generator is invoked
`templatePath`	yes	Template folder, relative to the workspace root
`inputs`	no	Values the template renders with, as JSON Schema fragments
`instances`	no	Where this generator's output already lives
`description`	no	Shown when generators are listed
`threshold`	no	Lowest conformance score this generator's instances may have, 0 to 1

Unknown keys are rejected, so a misspelled field — or

aliases

, which was removed outright — fails the load rather than quietly doing nothing. Check your entry took effect by listing the generators:

bash

conformetry templates

A generator with neither

inputs

nor

instances

is legal: it renders a fixed template that nothing validates afterwards.

配置文件默认导出一个数组，每个生成器对应一个条目。只有两个字段是必填的：

字段	是否必填	含义
`name`	是	调用生成器时使用的名称
`templatePath`	是	相对于工作区根目录的模板文件夹
`inputs`	否	模板渲染时使用的值，以 JSON Schema 片段表示
`instances`	否	此生成器现有输出的位置
`description`	否	列出生成器时显示的说明
`threshold`	否	此生成器的实例可具有的最低符合性得分，取值为 0 到 1

未知键会被拒绝，因此拼错的字段——或已彻底移除的

aliases

——都会导致加载失败，而不是悄无声息地不起作用。可以通过列出生成器来检查条目是否生效：

bash

conformetry templates

生成器既不声明

inputs

也不声明

instances

是合法的：它会渲染一个固定模板，之后没有任何内容对其进行验证。

Four collisions the configuration refuses to load with

配置文件拒绝加载的四种冲突

Two generators may not share a
name
. A host resolves the first match, leaving the other unreachable.
Two generators may not name the same
templatePath
. Validation could not tell which generator a matching instance belongs to.
A name may not be empty or contain a path separator. It becomes a filename in the emitted Nx plugin.
A name may not be
all
.
```
validate --templates all
```
already means every template, and a generator answering to that word would make the same token mean two things on one command line.

两个生成器不能使用相同的
name
。宿主会解析到第一个匹配项，另一个将无法被访问。
两个生成器不能指定相同的
templatePath
。验证时无法判断匹配的实例属于哪个生成器。
名称不能为空，也不能包含路径分隔符。 它会成为所生成的 Nx 插件中的文件名。
名称不能为
all
。
```
validate --templates all
```
已表示所有模板；如果某个生成器也以该词响应，同一个命令行标记就会产生两种含义。

Instance groups: where output already lives

实例组：现有输出的所在位置

instances

is a list of groups, each with optional

patterns

tags

substitutions

, and

threshold

. Groups exist so substitutions — and the conformance bar — can differ per set of paths.

Under the Nx plugin,

tags

is what changes a group's meaning:

A group with tags is a project selector. It applies to any project carrying one of those tags, and its
```
patterns
```
are read inside each selected project — so
```
src/modules/*
```
means the same thing in every project.
A group with no tags is a plain workspace glob, used verbatim.
A group with tags and no patterns selects without locating. That is how a generator scopes which projects it may target while validating nothing.

Directory patterns and file patterns behave differently, and the difference decides which template can win a match. See references/languages.md for what each language then compares.

instances

是组（groups）的列表，每组都可选择设置

patterns

、

tags

、

substitutions

和

threshold

。设置组是为了让 substitutions 以及符合性门槛能够按不同路径集分别配置。

在 Nx 插件下，正是

tags

会改变一个组的含义：

带 tags 的组是项目选择器。 它适用于携带其中任一 tag 的任何项目，并且其
```
patterns
```
会在每个选定项目内部解析——因此
```
src/modules/*
```
在每个项目中的含义都相同。
不带 tags 的组是普通的工作区 glob，会逐字使用。
带 tags 但不带 patterns 的组只负责选择而不负责定位。 这样，生成器可以限定其验证时可能面向的项目，同时不验证任何内容。

目录模式与文件模式的行为有所不同，这一差异决定了哪个模板能够优先匹配。有关每种语言随后如何进行比较，请参阅 references/languages.md。

Inputs

输入

Each input is a JSON Schema fragment. These keys are honored; anything else is ignored:

Key	Effect
`description`	The prompt text
`enum`	Turns the prompt into a list, and restricts the value
`minLength` / `maxLength`	Length validation
`pattern`	Tested as a unicode regular expression

The two hosts disagree about whether inputs are required, and the configuration cannot change that. The Nx plugin marks every declared input required. The command-line host marks none required. Write templates so that a missing value is obvious in the output rather than assuming either behavior.

Four input names carry extra meaning under the Nx plugin and are worth using deliberately rather than by accident:

project

module

type

, and

directory

all steer where output lands. Declaring an input called

project

on a generator whose groups carry tags additionally turns it into a project picker.

config

help

instancePath

, and

template

are reserved and never treated as inputs —

--template

is how the command-line host selects which template to render.

name

is deliberately not reserved.

每个输入都是一段 JSON Schema。以下键会被识别，其他键则会被忽略：

键	作用
`description`	提示文本
`enum`	将提示转换为列表，并限制可选值
`minLength` / `maxLength`	长度验证
`pattern`	使用 Unicode 正则表达式进行测试

两个宿主对于输入是否必填存在分歧，而配置无法改变这一点。 Nx 插件会将每个已声明的输入标为必填，命令行宿主则不会将任何输入标为必填。编写模板时，应让缺失值在输出中清晰可见，而不要依赖任一宿主的行为。

以下四个输入名称在 Nx 插件下具有额外含义，应有意识地使用，而非偶然用到：

project

、

module

、

type

和

directory

都会决定输出的落点。在组带 tags 的生成器上声明名为

project

的输入，还会额外将其变成项目选择器。

config

、

help

、

instancePath

和

template

是保留名称，永远不会被当作输入——

--template

是命令行宿主选择要渲染的模板时使用的参数。

name

则刻意_没有_被保留。

Writing a template

编写模板

The folder is the definition. Nothing registers a template's files.

A template that should produce a folder contains that folder. Its instance path is then the folder's parent. A template that produces loose files holds them at its root. Get this wrong and output lands one level off.

文件夹就是定义。模板中的文件无需单独注册。

如果模板应生成一个文件夹，模板本身就必须包含该文件夹。 此时，其实例路径是模板文件夹的_父目录_。如果模板生成的是独立文件，则应将它们放在模板根目录。弄错这一点，输出位置就会整体偏差一级。

Placeholders

占位符

Rendering is mustache, with HTML escaping switched off — so write

{{field}}

and never

{{{field}}}

. Paths use the same braces as content: a file named

{{nameKebabCase}}.service.ts

renders to

orders.service.ts

Four naming-case variants are always available, derived from the name:

Placeholder	`search bar` becomes
`{{nameCamelCase}}`	`searchBar`
`{{nameKebabCase}}`	`search-bar`
`{{namePascalCase}}`	`SearchBar`
`{{nameSnakeCase}}`	`search_bar`

Explicit inputs and configured substitutions are applied last, so they always beat a derived variant of the same name.

An interpolated placeholder nobody supplied raises
MissingSubstitutionError
, naming the placeholder and the template file, on generation and validation alike. So a typo in a placeholder name fails loudly rather than leaving a silent hole in content or an empty segment in a path.

Two things are still permissive, and are how a template asks for something optional:

Section tags.
```
{{#owner}}Owner: {{owner}}{{/owner}}
```
and
```
{{^owner}}Unowned.{{/owner}}
```
are conditionals, so an absent
```
owner
```
renders nothing rather than raising. Interpolate inside the section, never outside it.
A supplied empty value.
```
substitutions: { owner: "" }
```
is an answer. Only an absent key is a hole.

Adding a placeholder to a template is therefore a breaking change for every instance group that does not supply it. Add the substitution in the same change.

渲染使用 mustache，并关闭了 HTML 转义——因此应写

{{field}}

，绝不要写

{{{field}}}

。路径与内容使用相同的大括号：名为

{{nameKebabCase}}.service.ts

的文件会渲染为

orders.service.ts

。

始终可以根据名称使用四种命名大小写变体：

占位符	`search bar` 变为
`{{nameCamelCase}}`	`searchBar`
`{{nameKebabCase}}`	`search-bar`
`{{namePascalCase}}`	`SearchBar`
`{{nameSnakeCase}}`	`search_bar`

显式输入和已配置的 substitutions 最后应用，因此始终优先于同名的派生变体。

任何未提供替换值的插值占位符都会引发
MissingSubstitutionError
；在生成和验证时，错误都会指出占位符和模板文件的名称。因此，占位符名称拼写错误会明确失败，而不会在内容中留下隐性缺口，或在路径中留下空段。

仍有两项机制采用宽松处理，模板可借此表达可选内容：

Section 标签。
```
{{#owner}}Owner: {{owner}}{{/owner}}
```
和
```
{{^owner}}Unowned.{{/owner}}
```
是条件标签，因此缺少
```
owner
```
时会渲染为空，而不会引发错误。只在 section 标签内部插值，不要在其外部插值。
提供了空值。
```
substitutions: { owner: "" }
```
本身就是一个有效回答。只有键不存在才会形成缺口。

因此，为模板添加占位符时，对每个未提供该值的实例组来说都是破坏性变更。必须在同一次变更中补充对应的 substitution。

There is no conditional-file mechanism

不存在条件文件机制

No per-file predicate, no extension filtering, no skip list. Every file in the tree is rendered and written. Mustache sections work inside content, but a path rendered from an empty placeholder yields an empty segment rather than a skipped file. Do not go looking for a way to make a file optional; there isn't one.

没有按文件判断的谓词，没有扩展名过滤，也没有跳过列表。目录树中的每个文件都会被渲染并写入。Mustache section 可以在_内容_中使用，但由空占位符渲染出的路径会产生空路径段，而不是跳过该文件。不要试图寻找让文件变为可选的方法，因为这种机制并不存在。

Marking a value as free

将值标记为可自由填写

A comment containing

TODO

is a placeholder: any comment in the instance satisfies it. Use it for prose that legitimately varies per instance.

There is no equivalent for string literals. A string in a template is required verbatim, so a placeholder description or message becomes a permanent requirement for every instance. Prefer leaving such a value out of the template to pinning wording nobody wants.

包含

TODO

的注释是一个占位符：实例中的任意注释都可以满足它。可将其用于确实需要因实例而异的说明文字。

字符串字面量没有对应的机制。模板中的字符串必须逐字保留，因此模板中的占位符描述或消息会成为每个实例的永久要求。最好将这类值从模板中省略，而不是固定所有人都不想要的措辞。

Thresholds

阈值

Conformance is scored rather than merely passed, and a threshold is the lowest score an instance may have. It resolves narrowest-first: an instance group's

threshold

, then the generator's, then a run-level

--threshold

, then

Leave it unset unless you are migrating. The default of

means a perfect match, which is what makes a template a standard rather than a suggestion. Lower it deliberately when bringing existing instances onto a new template gradually, and raise it back as they catch up — a permanently lowered threshold is a template that no longer describes its instances.

A lowered threshold does not suppress reporting: differences still print for an instance that cleared its bar.

符合性采用评分机制，而不只是判断通过或不通过；threshold 是实例可以具有的最低得分。它按从最具体到最宽泛的顺序解析：实例组的

threshold

、生成器的

threshold

、运行级别的

--threshold

，最后是

。

除非正处于迁移阶段，否则不要设置它。 默认值

表示完全匹配，这正是模板作为标准而非建议的原因。逐步将现有实例迁移到新模板时，可以有意降低该值，并随着实例逐渐符合要求而将其调高——永久降低的 threshold 意味着模板已无法准确描述其实例。

降低 threshold 并不会抑制报告：对于已经达到门槛的实例，差异仍会输出。

After changing the configuration

修改配置后

The Nx generator namespace is emitted from the configuration, and every conformetry command refuses to run while it is out of date rather than working from stale definitions:

bash

nx sync

Two failures come from this area and both name their own fix:

A file being out of date with the configuration — run
```
nx sync
```
.
A generator naming a template folder that does not exist — fix
```
templatePath
```
, or create the folder.

A dependency install only warns rather than failing when emission does not work, so a mid-edit configuration never breaks everyone's install. That also means a warning there is real and worth reading.

Nx 的生成器命名空间会根据配置生成；只要它处于过期状态，所有 conformetry 命令都会拒绝运行，而不会使用陈旧的定义：

bash

nx sync

这一区域有两种失败情况，错误信息都会指出各自的修复方法：

某个文件与配置不同步——运行
```
nx sync
```
。
某个生成器指定了不存在的模板文件夹——修复
```
templatePath
```
，或者创建该文件夹。

当生成过程无法完成时，依赖安装只会发出警告而不会失败，因此编辑到一半的配置不会破坏所有人的依赖安装。这也意味着这里的警告确实值得认真查看。

Checking your work

检查工作结果

Generate an instance, then check it conforms. A freshly generated instance conforms by construction, so any difference means the template and the configuration disagree — see the

conformetry-validate

skill for reading the result, and

conformetry-generate

for the generation step itself.

生成一个实例，然后检查它是否符合要求。新生成的实例天然符合要求，因此任何差异都意味着模板与配置不一致——有关如何解读结果，请参阅

conformetry-validate

skill；生成步骤本身则参阅

conformetry-generate

。

Seeing it rather than reading about it

直接查看示例，而不只是阅读说明

conformetry-examples

is eleven self-contained examples, each a complete configuration small enough to read in one sitting. The ones that answer configuration questions:

hello-template
— the minimum fields, and where a template is laid down.
case-variants
— the derived variants, and overriding one.
scoring-thresholds
— two instance groups at two thresholds, and which of the three levels wins.
ambiguous-attribution
— what two templates claiming one path reports, and why declaring the same glob twice is a mistake.
nx-host
— tag-scoped instance groups, and what a host without a project graph does with them.
failure-modes
— a placeholder nobody supplied, rendered as an empty string on both sides of the loop rather than as an error.

See its AGENTS.md for the full index.

conformetry-examples

包含十一个自包含的示例，每个都是一份小到一次就能读完的完整配置。以下示例可以回答配置相关问题：

hello-template
——最少需要哪些字段，以及模板应放置在何处。
case-variants
——派生变体，以及如何覆盖其中一个变体。
scoring-thresholds
——具有两个阈值的两个实例组，以及三个层级中哪一个优先。
ambiguous-attribution
——两个模板同时声称匹配一个路径时会报告什么，以及为什么重复声明同一个 glob 是一个错误。
nx-host
——按 tag 划分的实例组，以及没有项目图的宿主会如何处理它们。
failure-modes
——未提供替换值的占位符如何在循环两端都渲染为空字符串，而不是报错。

完整索引见 AGENTS.md。