タグ監査
フロントマターのすべてのタグをプロジェクトのボキャブラリと照合する——unknown、deprecated、エイリアス、ニアデュプリケート、オーファン。
監査が報告する内容
pnpm tags:auditはsrc/と設定済みのすべてのロケールディレクトリを走査し、各ページのフロントマターからtags:配列を収集して、src/と照合した5種類の指摘を報告します。
- Unknown tags — 正規 id でもエイリアスでもない文字列です。ボキャブラリエントリを追加するか、ページからタグを削除してください。<code>tagGovernance: "strict"</code>では unknown はビルドを失敗させます。
- Deprecated tags — 解決先のエントリが
deprecatedマークされています。エントリにredirectがあれば読者のトラフィックは代替タグに解決されますが、コンテンツは更新しておくべきです。 - Alias usage — 文字列は既知のエイリアスであり、正規 id ではありません。ページは正しくレンダリングされますが、正規形から離れていきます。
--fixでその場で修正できます。 - Near-duplicates — 互いに変種のように見える2つの別個の正規タグ(文字列類似度が高い、または同じ単数形を持つ)。通常はボキャブラリ側の問題で、どちらかを選び、もう一方をエイリアスに回します。
- Orphan vocabulary entries — どのページからも参照されていないボキャブラリ id。
deprecated: trueで廃止することを検討してください。
クリーンな実行では✓ No tag issues foundと表示されます。
レポートの読み方
デフォルトの出力はカテゴリ別にグループ化された色付きテキストです。機械処理には--jsonを渡します。
pnpm tags:audit --json > audit.jsonJSON のペイロードはAuditReportで、unknowns、deprecated、aliases、nearDuplicates、orphans、filesScanned、そして正規 id をキーとするfrequencyマップを含みます。CI ダッシュボードや自動修正ツールはこれを消費するべきです。
--fix: バイト安定なエイリアス書き換え
pnpm tags:audit --fixは、エイリアスタグをフロントマター内で正規 id に直接書き換えます(1ファイルずつ)。
pnpm tags:audit --fix知っておくべき挙動:
- 書き換わるのはエイリアスのみ。 unknown・deprecated・ニアデュプリケートは一切触りません——これらは単純な置換ではなく編集判断が必要です。
- タグブロックの外はバイト安定。 インデントスタイル、クォート、改行コード(LF と CRLF の両方)を含めて他のバイトはすべて保持されます。
- 両方の YAML シーケンススタイルに対応。 フロー形式(
tags: [foo, bar])とブロック形式(tags:\n - foo)の両方。
--fixは作業ツリーがクリーンな状態で実行し、diff を確認してからコミットしてください。
b4push経由での CI 連携
プロジェクトのプリプッシュ検証スクリプト(<code>pnpm b4push</code>)は--ci付きで監査を実行します。
pnpm tags:audit --ci--ciはtagGovernanceの設定値に関わらず、ハード指摘(unknown または deprecated)があれば非ゼロ終了を強制します。つまり:
tagGovernance: "warn"では——unknown があってもpnpm buildは通過しますが(マイグレーション中に移行を止めないため意図的)、pnpm b4pushはプッシュを拒否します。tagGovernance: "strict"では——ビルドはすでに unknown で落ちます。--ciは将来的に enforcement を緩めても b4push が厳しさを保つための安全網です。
この「ビルドは寛容、push は厳格」という2層構造は、複数著者のドキュメントベースの最適解です。ドラフトは Zod と戦わずローカルで試行錯誤できつつ、壊れたタグがmainに入ることはありません。