タグ監査
フロントマターのすべてのタグをプロジェクトのボキャブラリと照合する——unknown、deprecated、エイリアス、ニアデュプリケート、オーファン。
監査が報告する内容
pnpm tags:auditはsrc/と設定済みのすべてのロケールディレクトリを走査し、各ページのフロントマターからtags:配列を収集して、src/と照合した5種類の指摘を報告します。
Unknown tags — 正規 id でもエイリアスでもない文字列です。ボキャブラリエントリを追加するか、ページからタグを削除してください。
tagGovernance: "strict"では 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 連携
プロジェクトのプリプッシュ検証スクリプト(pnpm b4push)は--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に入ることはありません。