coinagerie-triage

失敗した coinagerie チェックへの対処

失敗には5種類あり、それぞれ異なる対応が必要です。設定ファイルに手を付ける前に、どの種類の失敗が発生したか確認してください。

ログの表示	種類
Found a glossary out of step with the code	不足している単語と古くなった単語
Refused a glossary it cannot parse	解析できない形式の書き込み先
Rejected the configuration	設定の不備
Rejected the command line	実行時に使用できないフラグ
Found no glossary destination to check	outputsも書き込み先フラグも指定されていない

最後の3つには、それぞれ修正方法が1つあります。設定を修正する（coinagerie-configure スキル）、競合するフラグを削除する（--checkと--writeは併用できず、--formatにはjsonまたはmarkdownを指定します）、または書き込み先を追加してください。

不足している単語

コードで使われている単語が用語集にありません。名前が挙がった単語を1つずつ判断してください。

その単語が……	対応
コードベースの実際の用語である	--writeで単語だけを追加し、その後定義します（coinagerie-define）
どこでも同じ意味を持つ言語のキーワードや定型文である	その理由とともにexclude.wordsエントリーに追加します
誰も書いていない見出し語である（settingsからのsetなど）	意図する単語に対応付けるfoldエントリーを追加します
偶発的なもの、つまりタイプミスや一時的な名前である	コード内で名前を変更します
コードベース本来の単語ではないファイルに由来する	生成ファイルまたはベンダー提供ファイル用のexclude.pathsグロブを追加します

コード内で単語とその語形を検索して、見出し語がどこから来ているかを確認してください。複数形、-ing形と-ed形、そしてcamelCase名の各要素も検索します。foldを使うと、見出し語がそのままの形で現れない場合があります。

空の箇条書きは、チェックでいつまでも解消されない負債です。意味を持つ単語は、追加する変更と同時にそれぞれ定義してください。

古くなった単語

用語集にある単語がコードで使われなくなると、--writeはその単語を定義とともに削除します。書き込む前に、なぜ古くなったのか確認してください。

• 名前が変更された。 定義は新しい単語に対応します。名前変更は手書きのテキストが失われるケースです。書き込みを実行する前に、古い箇条書きの太字の見出し語を手作業で新しい単語に変更してください。定義はそのまま残り、チェックは書き込みなしで通ります。すでに書き込みで削除されている場合は、用語集ファイルのバージョン管理履歴からテキストを復元してください。
• 意図的に削除された。 書き込みを実行してください。コードを追跡することが設計上の方針です。
• 単語またはパスのエントリーによって新たに除外された。 書き込みを実行してください。削除は意図どおりです。
• コードではなくスキャン対象が変わった。 include、exclude.paths、チェックアウト、またはビルド手順の欠落を変更したあとに何十もの単語が古くなった場合は、スキャン対象が縮小しています。スキャンを復元してから再度チェックしてください。この状態で書き込むと、縮小したスキャンで検出されなくなった定義がすべて削除されます。

書き込みの前に、毎回古くなった単語の一覧を確認してください。書き込み後に--checkを実行し、チェックが通ることを確認してください。

解析できない用語集

エラーにはファイル名と、Markdownの不備の場合は行番号が表示され、何も書き込まれていません。原因には、ブロック内に箇条書きでもインデントされた続きでもない行がある、単語が重複している、コロンの直後にスペースを入れずテキストを置いている、アンカーがない・重複している・逆向きになっている、JSONが無効である、または値が文字列ではない、などがあります。該当する行を手作業で修正すれば、その前後にある定義はすべて残ります。

エラーを回避するためにブロックやファイルを削除すると、次の書き込みではすべての定義が空の状態からやり直しになります。

マシン間で結果が一致しないチェック

• ローカルでは成功するが、CI では失敗する。 スキャン対象のセットが異なっています。原因として考えられるのは、ローカルには存在するが CI では無視される生成フォルダーやビルドフォルダー、またはその逆、コミットされていない用語集や設定、作業ディレクトリの違いです。両方で引数なしの coinagerie --format json を実行して比較してください。
• 編集後もキャッシュされた成功結果が残る。 タスクランナーのキャッシュを使用している場合、親用語集など、設定が別の場所から読み込むファイルをチェックの入力として宣言する必要があります。
• 親用語集を変更した後、単語が再び不足として表示される。 親の単語リストを読み込む exclude.words を持つ子は、親が除外するすべての単語を列挙します。意図的に定義を子へ移すか、親の項目を復元してください。

衝動を判断に変える

衝動	代わりに
チェックを通すため、不足している単語をすべて除外する	上の表を参考に単語ごとに判断してください。除外した単語は定義を失います
不足がなくなるまで exclude.paths を広げる	コードベース自体の単語ではないファイルだけを除外してください
--write を実行して先へ進む	古いリストを見て改名を確認し、改名した各見出し語を先に編集してください
ブロックを削除して再生成する	エラーに表示された行を修正してください
チェックに成功したら完了とみなす	チェックが成功しても、空の定義が許容されるだけです。追加した内容を定義してください