# バッチ設計書 11-validate_version

## 概要

本ドキュメントは、serve-dプロジェクトにおけるリリース時のバージョン整合性検証スクリプト `ci/validate_version.d` のバッチ設計書である。GitHubリリースタグとserve-dバイナリの報告するバージョン番号が一致することを自動的に検証する。

### 本バッチの処理概要

本バッチは、serve-dのリリースプロセスにおいてバージョン番号の整合性を自動検証するためのD言語スクリプトである。

**業務上の目的・背景**：リリースビルドにおいて、GitHubのリリースタグ名とserve-dバイナリが自己申告するバージョン番号が一致していることを保証する。バージョン番号の不整合はユーザーの混乱やデバッグの困難化を引き起こすため、リリースパイプラインの自動チェックとしてこのスクリプトが組み込まれている。

**バッチの実行タイミング**：GitHubリリース公開時（`release: published`イベント）に、CI/CDワークフロー `releases.yml` 内でビルド完了後に呼び出される。各プラットフォーム（Linux/macOS/Windows）のビルドステップにおいて `rdmd ci/validate_version.d` として実行される。

**主要な処理内容**：
1. クロスコンパイル環境かどうかを `CROSS` 環境変数で判定し、クロスコンパイル時はバージョン検証をスキップする
2. ビルド済みのserve-dバイナリを `--version` オプション付きで実行し、出力からバージョン番号を抽出する
3. `GITHUB_EVENT_PATH` 環境変数が指すJSONファイルからGitHubリリースイベント情報を読み込み、`tag_name` フィールドからリリースタグ名を取得する
4. バイナリのバージョン番号とリリースタグ名を比較し、不一致の場合はエラーで処理を中断する

**前後の処理との関連**：本バッチは `ci/build.sh` または `ci/build.bat` によるリリースビルド完了後に実行される。本バッチが成功した場合のみ、後続のアセットアップロード（`WebFreak001/upload-asset`）ステップに進む。

**影響範囲**：リリースCI/CDパイプライン全体に影響する。本バッチが失敗するとリリースアセットのアップロードが行われず、リリースが不完全な状態となる。

## バッチ種別

バージョン検証 / リリース整合性チェック

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（リリース公開時） |
| 実行時刻 | 指定なし |
| 実行曜日 | 指定なし |
| 実行日 | 指定なし |
| トリガー | GitHubリリース公開イベント（`release: published`） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| serve-dバイナリのビルド完了 | `ci/build.sh` または `ci/build.bat` によるリリースビルドが正常に完了し、カレントディレクトリに `serve-d`（Linux/macOS）または `serve-d.exe`（Windows）が存在すること |
| GITHUB_EVENT_PATH環境変数 | GitHub Actionsによって自動設定されるリリースイベント情報JSONファイルのパス |
| rdmdの利用可能性 | D言語のスクリプト実行環境 `rdmd` がPATH上に存在すること（`dlang-community/setup-dlang` アクションによりインストール済み） |

### 実行可否判定

- 環境変数 `CROSS` が設定されている（長さ > 0）場合は、クロスコンパイル環境と判定し、バージョン検証をスキップして正常終了する
- `CROSS` が未設定または空の場合、バージョン検証を実行する

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| CROSS | 環境変数（文字列） | No | 空文字列 | クロスコンパイルフラグ。設定されている場合はバージョン検証をスキップ |
| GITHUB_EVENT_PATH | 環境変数（文字列） | Yes | なし | GitHubリリースイベント情報を格納したJSONファイルのパス |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| serve-d / serve-d.exe | バイナリ実行ファイル | `--version` オプションで実行し、バージョン文字列を取得する |
| $GITHUB_EVENT_PATH | JSON | GitHubリリースイベントのペイロード。`release.tag_name` フィールドを参照 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | 検証結果メッセージ（例: `serve-d version is 0.7.4, same as released.`） |
| 標準エラー出力 | テキスト | クロスコンパイル時のスキップメッセージ |

### 出力ファイル仕様

本バッチはファイル出力を行わない。検証結果は標準出力/標準エラー出力およびプロセスの終了コードで伝達する。

| 項目 | 内容 |
|-----|------|
| ファイル名 | なし |
| 出力先 | 標準出力 / 標準エラー出力 |
| 文字コード | UTF-8 |
| 区切り文字 | なし |

## 処理フロー

### 処理シーケンス

```
1. CROSS環境変数チェック
   └─ CROSS環境変数が設定されている場合、スキップメッセージを出力して終了
2. serve-dバイナリのバージョン取得
   └─ serve-d --version を実行し、終了コード0を確認
3. バージョン文字列の解析
   └─ 出力が "serve-d standalone v" で始まることを確認し、バージョン番号部分を抽出
4. GitHubリリースタグの取得
   └─ GITHUB_EVENT_PATHのJSONから release.tag_name を取得し、先頭の "v" を除去
5. バージョン比較
   └─ バイナリのバージョンとリリースタグを比較し、不一致の場合はエラーを発生
6. 検証成功メッセージの出力
   └─ "serve-d version is X.Y.Z, same as released." を出力
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B{CROSS環境変数が設定されているか}
    B -->|あり| C[スキップメッセージ出力]
    C --> D[正常終了]
    B -->|なし| E[serve-d --version 実行]
    E --> F{終了コード == 0 か}
    F -->|No| G[エラー: ステータス異常]
    F -->|Yes| H{出力が serve-d standalone v で始まるか}
    H -->|No| I[エラー: 出力形式異常]
    H -->|Yes| J[バージョン番号を抽出]
    J --> K[GITHUB_EVENT_PATH から JSON読み込み]
    K --> L{release オブジェクト が存在するか}
    L -->|No| M[エラー: リリースイベントではない]
    L -->|Yes| N[tag_name を取得し先頭の v を除去]
    N --> O{バイナリバージョン == タグ名か}
    O -->|No| P[エラー: バージョン不一致]
    O -->|Yes| Q[成功メッセージ出力]
    Q --> D
```

## データベース操作仕様

### 操作別データベース影響一覧

本バッチはデータベース操作を行わない。

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| なし | なし | なし | データベース操作なし |

### テーブル別操作詳細

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 非0終了 | 実行エラー | `serve-d --version` がステータス0以外を返した場合 | serve-dバイナリのビルド状態を確認する |
| enforce失敗 | 出力形式エラー | `--version` 出力が `serve-d standalone v` で始まらない場合 | バイナリのバージョン出力形式の変更有無を確認する |
| enforce失敗 | イベント形式エラー | `GITHUB_EVENT_PATH` のJSONに `release` オブジェクトが存在しない場合 | ワークフローのトリガー設定を確認する |
| enforce失敗 | バージョン不一致 | バイナリバージョンとタグ名が一致しない場合 | ソースコード内のバージョン定義とリリースタグ名を確認する |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0回（リトライなし） |
| リトライ間隔 | なし |
| リトライ対象エラー | なし（バージョン不一致は本質的なエラーであり、リトライでは解決しない） |

### 障害時対応

- バージョン不一致エラーが発生した場合は、ソースコード内のバージョン定義（ビルド設定やバージョンファイル）を確認し、リリースタグ名と一致するよう修正してから再リリースを行う
- `GITHUB_EVENT_PATH` 関連のエラーが発生した場合は、GitHub Actionsワークフローのトリガー設定を確認する

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | なし（データベース操作なし） |
| コミットタイミング | なし |
| ロールバック条件 | なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1件（1回のバージョン比較） |
| 目標処理時間 | 数秒以内 |
| メモリ使用量上限 | 特になし（軽量な文字列比較処理のみ） |

## 排他制御

排他制御は不要。本バッチは読み取り専用の検証処理であり、外部リソースへの書き込みを行わない。ただし、CI/CDパイプライン内で各プラットフォームのビルドジョブごとに独立して実行されるため、並行実行しても問題ない。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| スキップログ | CROSS環境変数検出時 | `Not checking if serve-d version is up-to-date because it's cross-compiled!` |
| 成功ログ | バージョン検証成功時 | `serve-d version is X.Y.Z, same as released.` |
| エラーログ | enforce失敗時 | 各種enforceのエラーメッセージ（例: `Tag was named X but serve-d reported version Y`） |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 終了コード | 非0 | GitHub Actionsの実行結果としてワークフロー失敗が通知される |
| ワークフロー全体の結果 | 失敗 | GitHubリポジトリの通知設定に準ずる |

## 備考

- 本スクリプトは `rdmd` コマンドにより直接実行される（`#!/usr/bin/env rdmd` シェバン付き）
- `releases.yml` ワークフローでは、ビルドスクリプトと `&&` で連結されて実行される（例: `./ci/build.sh && rdmd ci/validate_version.d`）
- Windows環境では `serve-d.exe`、Linux/macOS環境では `./serve-d` がバイナリパスとして使用される
- リリースタグの先頭に `v` プレフィックスが付いている場合は自動的に除去されて比較される
