coinagerie-collect

运行 Coinagerie

Coinagerie 会列出代码库中使用的词，每个词条对应一个词头，并让词汇表与代码保持同步。它只读取名称，不读取散文：标识符（包括对象键、枚举成员、带引号的键，以及 JSON 或 YAML 键），还有不带扩展名的文件夹和文件名。注释、字符串字面量、模板文本和正则表达式均不计入。

一次扫描一个文件夹

一次运行会扫描其配置文件所在的文件夹。--config <path> 用于指定文件，路径相对于工作目录。未指定该选项时，会在工作目录（绝不搜索父目录）中依次查找 coinagerie.config.ts、.mts、.cts、.js、.mjs、.cjs，并采用第一个匹配项。若未找到文件，则使用默认值：扫描工作目录，不写入任何内容。

cd packages/widgets && coinagerie --check
coinagerie --config packages/widgets/coinagerie.config.ts --check

三种模式

调用	写入内容	在以下情况下以状态码 1 退出
coinagerie	不写入任何内容；将词汇表打印到 stdout	配置或命令行参数遭拒
coinagerie --check	不写入任何内容	某个目标中有缺失或过时的词、无法解析词汇表，或配置或命令行参数遭拒
coinagerie --write	内容发生变化的每个目标	无法解析词汇表，或配置遭拒

• 同时使用 --check 和 --write 会被拒绝。
• 每次运行都需要一个目标，即配置中的 outputs 条目，或 --output-json 或 --output-markdown 标志。若没有目标，运行会失败并指出 "no glossary destination"。
• 直接运行会打印代码中的词，且每个定义都为空。它不会读取目标文件，因此无法显示任何人编写的定义。默认以 Markdown 格式打印；--format json 会打印扁平对象。与 --check 或 --write 一起使用时，--format 会被忽略，但无效值仍会被拒绝。

哪些内容算作词

• 标识符会按大小写变化、_、- 和 . 拆分。首字母缩写会合理拆分（HTTPServer 会得到 http 和 server）。包含数字的词会保持完整（utf8）。词会转换为小写；纯数字和单字母词会被丢弃。
• 复数会归并为单数，屈折变化会归并为词元，因此 aspects 会并入 aspect，configured 会并入 configure。派生词族会分别保留：configuration 和 configure 是两个词。
• 词形还原器有时会得出比任何人写下的词都更奇怪的词头（settings 会变成 set）。因此，词汇表中的词头按拼写可能不会出现在代码中。
• TypeScript 和 JavaScript 会从语法树读取，并容忍语法错误。Python、SQL、shell、CSS、HCL、TOML、JSON 和 YAML 会由词法扫描器读取。其他语言的文件仍会贡献其路径中的词。
• .gitignore 始终生效。运行写入的文件绝不会被扫描。
• 配置文件会像其他文件一样被扫描：它自身的键（exclude、fold、outputs）也会作为词出现，除非配置将它们排除。

如何阅读打印的内容

Markdown 目标：位于 和 之间的区块，标题为 ## 🪙 Coinagerie，可带描述，随后每个词占一个项目符号，并按词排序。

- **orbit**: The path a body follows around another.
- **phase**:
- **tolerance**:
  Continues on an indented line.

仅有 - **phase**: 表示未定义。定义从缩进行开始的项目符号表示已定义。JSON 目标：按词排序的扁平对象，未定义的词对应 ""。

列出某个文件中的缺失项：

grep -A1 -E '^- \*\*[^*]+\*\*:$' glossary.md   # a bare bullet whose next line is indented is defined
jq -r 'to_entries[] | select(.value == "") | .key' glossary.json

检查和写入

• missing：代码使用了目标词表中没有的词。stale：目标词表列出了代码已不再使用的词。每个目标词表单独判断，定义绝不会在目标词表之间复制。
• --check 遇到任何缺失或过时的词都会失败，定义为空时则会通过。检查通过表示词已列出，并不表示词已有定义。
• --write 会将每个缺失的词添加为空项目符号，原样保留所有现有定义，并连同定义一起删除每个过时的词。代码未变时，再次运行 --write 不会有任何更改。尚无锚点的文件会在末尾追加该区块，因此首次写入无需手动放置标记。
• 如果词汇表无法完整解析，程序会在写入任何目标文件前停止：遇到无法识别的行、重复词、无效 JSON 或非字符串值时都会如此。磁盘上的内容不会改变。
• 诊断信息会输出到 stderr，打印运行的 stdout 仅包含词汇表。检查失败时，每个不同步的目标文件会记录一行（此处已略去部分内容）：

ERROR: 🪙 Found a glossary out of step with the code {"missing":["gate"],"path":"/repo/README.md","stale":["ephemeris"]}

使用 coinagerie-triage 技能处理失败。

标志

每个标志会替换其指定字段；没有对应标志的字段则保留配置文件中的值。

标志	替换内容
--config <path>	要读取的配置文件
--include <glob>	include；可重复指定多个
--exclude-paths <glob>	exclude.paths；可重复指定多个
--output-json <path>	整个 outputs 列表，替换为一个 JSON 目标
--output-markdown <path>	整个 outputs 列表，替换为一个 Markdown 目标（同时使用两个标志则会有两个目标）
--description <text>	每个 Markdown 目标的描述
--format json|markdown	无参数运行时打印的格式

目标路径相对于工作目录，glob 相对于扫描的文件夹。没有用于 exclude.words 或 fold 的标志：两者都是代码，因此应写在配置中。coinagerie-configure 技能涵盖所有字段。

接入

• CI 或提交钩子：从存放配置文件的文件夹运行 coinagerie --check，并用退出码控制流程。在本地使用 --write 写入，提交词汇表，并在 CI 中运行检查。
• Nx（可选）：@coinagerie/nx 插件会推断出一个可缓存的 coinagerie-check 目标，为每个项目运行 coinagerie --check。该命令会在项目文件夹中运行；项目旁边的 project.json 或命名的 package.json 中只要有配置文件，该项目就会纳入处理。配置文件和项目自身的文件是其输入。配置读取的其他位置中的文件（例如父级词汇表）应添加到插件的 inputs 选项中，否则缓存的通过结果在该文件被编辑后仍会继续有效。coinagerie 不在路径中时，command 选项用于指定如何运行该二进制文件。