conformetry-generate

使用 conformetry 生成

Conformetry 生成器会将一个模板——一个由普通文件组成的普通文件夹——渲染为磁盘上的一个实例。同一个模板随后会作为衡量实例的标准，因此生成并非只是为了方便。手动编写的代码如果符合模板已有的形态，从一开始就无法通过一致性检查。

手动编写文件之前，先检查是否有生成器

猜测生成器名称会被拒绝，因此请查看注册表，而不是自行推断：

conformetry templates --config configuration/conformetry.config.ts

每条 conformetry 命令都必须指定 --config <path>；不会假定存在默认文件。在 Nx 工作区中，生成的插件也能回答同一个问题：

nx list conformetry

两者都会读取实时配置，因此对你当前所在的工作区而言都是准确的。无需把任何一方的输出缓存到笔记中——添加生成器后，输出就会改变。

生成会无条件覆盖

写入过程中没有任何存在性检查、跳过已存在文件、合并或冲突检测。模板中的每个文件都会被渲染，并覆盖已有内容。

切勿将生成器指向已经包含你想保留的工作的路径。 要更改现有实例，请直接编辑。仅当你打算丢弃现有内容，或者实例缺少模板要求的文件且你已阅读将被替换的内容时，才重新生成。

Nx 路径通过 Tree 写入，因此 --dry-run 会如实显示将写入的内容：

nx g conformetry:<generator> --name=<name> --project=<project> --dry-run

不确定输出会写到哪里时，先执行此操作。

两个入口对输入的要求不同

这是生成过程中最令人困惑的一点，而且并非错误：同一个生成器会根据调用方式表现不同。

	Nx 插件	命令行主机
调用方式	nx g conformetry:<name>	conformetry generate --config <path> --template <name>
输入	必须提供所有已声明的输入	无需提供任何输入
缺少输入	拒绝执行，或提示输入	模板插值时拒绝执行
默认目标位置	根据工作区解析	generated/<generator-name>

其余差异在于_何时_发现缺少值。Nx 路径要求预先提供所有已声明的输入，因此会在开始渲染之前拒绝执行。命令行主机不要求提供任何输入，而是在模板需要某个输入时才发现遗漏——此时会抛出 MissingSubstitutionError，指出占位符和模板文件。

因此，在命令行主机上可以省略模板从未插值的输入，但 Nx 路径上不行。模板实际插值的任何内容，两种方式都必须提供。

无论使用哪种方式，都要显式传入所有输入。 如果模板中的某项是“可选”的，应使用区段来表达——当 owner 缺失时，{{#owner}}…{{/owner}} 不会渲染任何内容——而不是依赖裸露的 {{owner}}。

两种方式都必须使用完整名称来指定生成器——没有简短的替代名称。名称错误时，两种主机都会列出实际名称。

标志是 --template，而不是 --generator。 它与配置中的 templatePath、templates 命令以及一致性报告使用的词一致。--generator 已被移除，不再作为别名保留；传入该标志会按名称拒绝。此命令接受未知标志，以便将模板输入作为标志传入；如果不拒绝该标志，过时脚本中的 --generator 就会被悄悄丢弃，看起来仍能正常运行。

在命令行中，--template 也是可选的。在终端中省略它会显示所有已配置模板的自动补全选项及其描述；Agent shell 不是终端，因此始终要传入该标志——在 Agent shell 中省略时，运行会被拒绝并列出可用名称，而不会停下来等待提示输入。

输出位置

在 Nx 路径中，目标位置按以下顺序解析，匹配到的第一项优先：

1. 显式指定 --directory。
2. 未提供 project 输入——视为新项目，根据其 type 输入，放在同类型项目旁边。
3. 提供了 module 输入——放在该现有模块中。指定不存在的模块会报错，而不会创建新模块。
4. 生成器自身的作用域目录，取自其实例组中的第一个带标签模式。
5. 现有实例数量最多的生成器所在目录。
6. 项目根目录。

第 4 和第 5 步正是生成器通常完全不需要指定目标位置的原因：它知道自己的实例存放在哪里。只有在刻意将内容放到约定位置之外时，才使用 --directory。

在命令行宿主中，只有 --directory 会生效；若未指定，目标位置就是 generated/<generator-name>——这是临时位置，不是源代码树。要写入工作区时，务必在此处传入 --directory。

无人值守运行

命令行宿主在 stdin 是终端时会提示输入，且没有关闭此行为的标志——是否连接终端是唯一条件，因此 Agent shell、钩子或 CI 作业都不会收到提示。

生成器声明的每个输入都是必填项，两个入口点都如此：生成器会替换它的每个占位符，而 mustache 会将缺失的占位符渲染为空字符串，而不是报错，因此可选输入会悄悄在生成的文件中留下空缺。没有终端时，任何未传入的输入都会导致硬错误，并指出要传入的标志——绝不会静默使用默认值，也绝不会在无人应答时显示菜单。请传入模板声明的所有输入，或在可以接受提问的环境中运行。

生成之后

两个步骤都很简单，也都能发现一整类错误：

1. 检查符合性，确认刚生成的内容。生成的实例按构造应当符合要求，因此如果有差异，说明目标位置不正确、输入为空，或覆盖了现有内容。参见 conformetry-validate 技能。
2. 在生成的文件中实现。 不要在旁边构建平行结构。模板中的章节注释和声明就是约定；始终可以在其中添加内容，删除它们才会造成问题。

尚无生成器时

添加生成器属于配置变更，而不是代码变更——参见 conformetry-configure 技能。之后有两件事会立即产生影响：必须通过 nx sync 重新生成已输出的 Nx 插件；在插件过期时，每条 conformetry 命令都会拒绝运行，而不是使用过时的定义。

与其阅读说明，不如亲自查看

conformetry-examples包含 12 个独立示例，每个示例都有自己的配置、模板、实例和命令。在为不熟悉的内容搭建脚手架前，值得先运行其中两个：

• hello-template——现有的最小生成器，通过两条命令完成生成和验证，让整个流程一目了然。
• case-variants——展示路径和内容中的所有派生大小写变体，以及显式输入如何覆盖它们。

每个示例的运行时间约为 1 秒，其指南引用了生成的输出，并由该包自身的测试套件进行断言。请参见其 AGENTS.md，了解每个示例对应解答的问题。