tagguard

tagguard

リリースにタグを付けようとしています。整合している必要がある3つの項目、つまり Git タグ、パッケージのバージョン、変更履歴のエントリーは、本当に一致していますか？ tagguard は、5つの明示的なチェックでこの問いに答えるリリース前ゲートです。いずれかのチェックに失敗すると、リリースをブロックします。

1. SEMVER_VALID — パッケージのバージョンが SemVer の文法に一致すること（数値コンポーネントの先頭のゼロは拒否され、プレリリースおよびビルドメタデータのサフィックスは SemVer の規則に従います）
2. TAG_MATCHES_VERSION — 先頭に数字が続く場合に限り、先頭の v または V を1つ取り除いて正規化したタグが、パッケージのバージョンと完全に一致すること
3. PRERELEASE_ALLOWED — プレリリース部分（+ より前にある -）を含むバージョンは、プレリリースが許可されていない限り失敗します
4. CHANGELOG_ENTRY — 変更履歴にこのバージョンの ## 見出しがあること：## 0.2.0、## [0.2.0]、## v0.2.0 (2026-01-01)、## [0.2.0] - 2026-01-01 はすべて該当します
5. CHANGELOG_ENTRY_NONEMPTY — その見出しの下に内容があること：次の ## 見出しまでに、見出し以外の空でない行が少なくとも1行あること

各チェックは、合否にかかわらず、この順序ですべて報告されます。ゲートは途中で処理を打ち切らないため、リリースがブロックされた場合、問題がすべて一度に表示されます。ローカルでの純粋な計算のみです。Git コマンドも、ネットワークも、設定も使用しません。

CLI

npx @reneturcios/tagguard check --tag v0.2.0 --version 0.2.0 --changelog CHANGELOG.md
npx @reneturcios/tagguard --version

--allow-prerelease を追加すると、1.0.0-beta.1 のようなプレリリースバージョンを許可できます。

コマンドはゲートのレポートを JSON として出力します。

{
  "ok": true,
  "normalized_tag": "0.2.0",
  "checks": [
    { "code": "SEMVER_VALID", "ok": true, "message": "..." }
  ]
}

終了コード：ゲートを通過した場合は 0、ゲートがリリースをブロックした場合（JSON レポートは引き続き出力されます）または実行時エラーが発生した場合は 1（変更履歴ファイルを読み取れない場合は、エラー行が出力され、JSON は出力されません）、使用方法に誤りがある場合は 2 です。

MCP サーバー

npx -y @reneturcios/tagguard mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "tagguard": {
      "command": "npx",
      "args": ["-y", "@reneturcios/tagguard", "mcp"]
    }
  }
}

ツール

• check_release_tag — 提案されたリリース1件に対してリリース前ゲートを実行し、5つすべてのチェックを報告します。
  • tag（文字列、必須）— 提案する Git タグ。例："v0.2.0"
  • package_version（文字列、必須）— package.json 内のバージョン
  • changelog（文字列、必須）— CHANGELOG.md のテキスト
  • allow_prerelease（ブール値、任意、デフォルトは false）— プレリリースのバージョン部分を許可します

tag、package_version、changelog が指定されていないか空の場合は、引数名を示すエラーになります。package_version が SemVer に準拠していないことはエラーではありません。チェック1が失敗するだけであり、それがゲートの役割です。

Docker

docker run -i ghcr.io/cloudcorprecords/tagguard
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/tagguard check --tag v0.2.0 --version 0.2.0 --changelog /w/CHANGELOG.md

開発

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

ライセンス

MIT — Copyright (c) 2026 Rene Turcios