タグ監査
フロントマターのすべてのタグをプロジェクトのボキャブラリと照合する——unknown、ニアデュプリケート、オーファン。
監査が報告する内容
pnpm tags:auditはパッケージ所有の監査 CLI を実行します。src/のデフォルトTagCliConfigエクスポートで宣言されたコンテンツディレクトリを走査し、各ページのフロントマターからtags:配列を収集して、同じモジュールの名前付きtagVocabularyエクスポートと照合した3種類の指摘を報告します。
Unknown tags — 正規 id と完全一致しない文字列です。ボキャブラリエントリを追加するか、意図した id に置き換えるか、ページから削除してください。
tagGovernance: "strict"では unknown はビルドを失敗させます。Near-duplicates — 互いに変種のように見える2つの別個のタグ(文字列類似度が高い、または同じ単数形を持つ)。正規 id を1つ選び、もう一方を使うコンテンツを更新します。
Orphan vocabulary entries — どのページからも参照されていない正規 id。参照をすべて更新または削除してからエントリを削除します。
クリーンな実行では✓ No tag issues foundと表示されます。
CLI 設定と package script
scaffold は明示的な設定モジュールをpackage.jsonで指定します。
{
"scripts": {
"tags:audit": "tags-audit --config src/config/tag-vocabulary.ts"
}
}設定パスはプロジェクトルートから解決されます。--configがない、読み込めない、または有効なTagCliConfigをデフォルトエクスポートしていない場合、CLI は明確なエラーで終了します。名前付きtagVocabularyエクスポートも維持してください。生成されたzfb.config.tsが同じモジュールを参照するため、ランタイムのガバナンスと CLI 監査が単一の情報源を共有します。
package manager の--を使えば、pnpm と npm のどちらでもオプションを一貫して転送できます。
レポートの読み方
デフォルトの出力はカテゴリ別にグループ化された色付きテキストです。機械処理には--jsonを渡します。
pnpm tags:audit -- --json > audit.jsonJSON のペイロードはAuditReportで、unknowns、nearDuplicates、orphans、filesScanned、そして正確な id をキーとするfrequencyマップを含みます。CI ダッシュボードはこれを利用できます。
b4push経由での CI 連携
プロジェクトのプリプッシュ検証スクリプト(pnpm b4push)は--ci付きで監査を実行します。
pnpm tags:audit -- --ci--ciはtagGovernanceの設定値に関わらず、ハード指摘(unknown)があれば非ゼロ終了を強制します。つまり:
tagGovernance: "warn"では——unknown があってもpnpm buildは通過しますが(マイグレーション中に移行を止めないため意図的)、pnpm b4pushはプッシュを拒否します。tagGovernance: "strict"では——ビルドはすでに unknown で落ちます。--ciは将来的に enforcement を緩めても b4push が厳しさを保つための安全網です。
この「ビルドは寛容、push は厳格」という2層構造は、複数著者のドキュメントベースの最適解です。ドラフトは Zod と戦わずローカルで試行錯誤できつつ、壊れたタグがmainに入ることはありません。