coinagerie-collect

Coinagerie の実行

Coinagerie は、コードベースで使われている単語を見出し語ごとに列挙し、コードに合わせて用語集を保ちます。読むのは名前であり、文章ではありません。識別子（オブジェクトのキー、列挙型のメンバー、引用符で囲まれたキー、JSON や YAML のキーを含む）に加え、拡張子を除いたフォルダー名とファイル名を読み取ります。コメント、文字列リテラル、テンプレートテキスト、正規表現は対象になりません。

一度に 1 つのフォルダー

実行時には、設定ファイルが置かれているフォルダーをスキャンします。--config <path> では、作業ディレクトリからの相対パスでファイルを指定します。このフラグがない場合は、作業ディレクトリ（親ディレクトリは検索しません）で coinagerie.config.ts を検索し、続いて .mts、.cts、.js、.mjs、.cjs の順に検索します。最初に見つかったファイルが使われます。ファイルが見つからない場合は、デフォルトが適用されます。作業ディレクトリをスキャンし、何も書き込みません。

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

3 つのモード

実行方法	書き込み内容	次の場合に終了コード 1 を返す
coinagerie	何も書き込まず、用語集を標準出力に表示します	設定またはコマンドラインが拒否された場合
coinagerie --check	何も書き込みません	出力先に単語の不足または古い単語がある場合、用語集を解析できない場合、または設定やコマンドラインが拒否された場合
coinagerie --write	内容が変更された出力先のみ	用語集を解析できない場合、または設定が拒否された場合

• --check と --write を同時に指定すると拒否されます。
• どちらも出力先が必要です。出力先は設定の outputs エントリ、または --output-json か --output-markdown フラグで指定します。指定がない場合、実行は "no glossary destination" と表示して失敗します。
• フラグを付けずに実行すると、コードにある単語がすべて定義空欄で表示されます。出力先は読み込まないため、誰かが記述した定義を表示することはできません。表示形式のデフォルトは Markdown です。--format json を指定するとフラットなオブジェクトが表示されます。--check または --write と併用した場合、--format は無視されますが、無効な値は引き続き拒否されます。

単語の判定基準

• 識別子は、大文字・小文字の変化、_、-、. で分割されます。頭字語の連続も適切に分割されます（HTTPServer は http と server になります）。数字を含む単語はそのまま保持されます（utf8）。単語は小文字に変換され、数字のみの単語と 1 文字の単語は除外されます。
• 複数形は単数形に、活用形は原形にまとめられるため、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 は、missing または stale の単語があると失敗し、定義が空の場合は成功します。チェックが成功しても、単語が記載されていることを示すだけで、定義されていることを示すわけではありません。
• --write は、missing の単語を空の箇条書きとして追加し、既存の定義はすべてそのまま保持し、stale の単語とその定義を削除します。コードに変更がなければ、2 回目の --write では何も変わりません。まだアンカーがないファイルでは、ブロックが末尾に追加されるため、最初の書き込みに手動でマーカーを配置する必要はありません。
• 用語集を完全に解析できない場合、出力先への書き込みを始める前に実行が停止します。認識できない行、重複した単語、無効な JSON、文字列以外の値が該当します。ディスク上のファイルは一切変更されません。
• 診断メッセージは stderr に出力され、印字実行時の stdout には用語集だけが出力されます。チェックに失敗すると、手順から外れている出力先ごとに 1 行がログに記録されます（ここでは省略しています）。

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 出力先を指定します（両方のフラグで 2 つ指定）
--description <text>	すべての Markdown 出力先の説明
--format json|markdown	引数なしで実行したときに出力する形式

出力先のパスは作業ディレクトリを基準とし、glob はスキャン対象のフォルダーを基準とします。exclude.words と fold のフラグはありません。どちらもコードであるため、設定に記述します。すべてのフィールドについては、coinagerie-configure スキルを参照してください。

組み込む

• CI またはコミットフック：設定ファイルがあるフォルダーで coinagerie --check を実行し、終了コードで処理を制御します。ローカルでは --write で書き込み、用語集をコミットして、CI でチェックします。
• Nx（任意）：@coinagerie/nx プラグインは、設定ファイルが project.json または名前付きの package.json と同じ場所にあるすべてのプロジェクトについて、プロジェクトのフォルダーで coinagerie --check を実行するキャッシュ可能な coinagerie-check ターゲットを推論します。設定ファイルとプロジェクト独自のファイルが入力になります。親用語集など、設定ファイルが別の場所から読み込むファイルは、プラグインの inputs オプションに含めてください。そうしないと、そのファイルを編集してもキャッシュ済みの成功結果が残ります。coinagerie がパス上にない場合は、command オプションでバイナリの実行方法を指定します。