# バッチ設計書 39-Coverage（coverage.yml）

## 概要

本ドキュメントは、mrubyプロジェクトにおけるGitHub Actionsワークフロー `Coverage`（coverage.yml）のバッチ設計書である。push時にclang-18でカバレッジ付きビルド・テストを実行し、gcovrでカバレッジレポートを生成するCI/CDパイプラインについて記述する。

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

`Coverage` ワークフローは、GitHub Actionsで定義されたCI/CDパイプラインであり、コードのpush時に自動的にトリガーされ、カバレッジ計測付きでmrubyのビルドとテストを実行し、コードカバレッジレポートを生成してアーティファクトとしてアップロードする。

**業務上の目的・背景**：コードカバレッジを継続的に計測することで、テストが網羅していないコード領域を特定し、テスト品質の向上を図る。push毎にカバレッジレポートが生成されるため、コード変更によるカバレッジの推移を追跡できる。

**バッチの実行タイミング**：GitHubリポジトリへのpush時に自動実行される。pull_requestイベントでは実行されない。

**主要な処理内容**：
1. コードチェックアウト
2. clang-18を使用し、`--coverage` フラグ付きでmrubyをビルド・テスト実行（`rake test`）
3. gcovrのインストール
4. gcovr（llvm-cov-18 gcov使用）でカバレッジレポートを生成（HTMLフォーマット）
5. カバレッジレポートをGitHub Actionsアーティファクトとしてアップロード（保持期間3日）

**前後の処理との関連**：No.38 Build & Test（build.yml）が同時にトリガーされるが、互いに独立して実行される。本ワークフローはpushイベントのみで実行される点がBuild & Testと異なる。

**影響範囲**：GitHub Actions上でのCI/CD実行のみ。カバレッジレポートはアーティファクトとして保存される。リポジトリのコードには影響しない。

## バッチ種別

CI/CDパイプライン（カバレッジ計測）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動（push時のみ） |
| 実行時刻 | イベント発生時 |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | push |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| GitHub Actions | GitHubリポジトリでActionsが有効であること |
| ランナー | ubuntu-24.04のランナーが利用可能であること |
| clang-18 | ランナーにclang-18がプリインストールされていること |
| pip | Python pipが利用可能であること |

### 実行可否判定

pushイベントが発生した場合に自動実行される。pull_requestイベントでは実行されない。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| MRUBY_CONFIG | 環境変数 | Yes | ci/gcc-clang | mrubyビルド設定ファイルパス |
| CC | 環境変数 | Yes | clang-18 | Cコンパイラ |
| CXX | 環境変数 | Yes | clang++-18 | C++コンパイラ |
| LD | 環境変数 | Yes | clang-18 | リンカ |
| CFLAGS | 環境変数 | Yes | -O0 -g --coverage | Cコンパイルフラグ（最適化なし、デバッグ情報、カバレッジ） |
| CXXFLAGS | 環境変数 | Yes | -O0 -g --coverage | C++コンパイルフラグ |
| LDFLAGS | 環境変数 | Yes | --coverage | リンクフラグ（カバレッジ） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| .github/workflows/coverage.yml | YAML | ワークフロー定義 |
| mrubyソースコード一式 | C/Ruby | ビルド・テスト対象 |
| ci/gcc-clang | Ruby | ビルド設定 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| GitHub Actions ログ | テキスト | ビルド・テスト実行ログ |
| GitHub Step Summary | Markdown | カバレッジサマリー |
| GitHub Actions アーティファクト | HTML | カバレッジ詳細レポート |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | coverage-{github.sha} |
| 出力先 | GitHub Actionsアーティファクト |
| 文字コード | UTF-8 |
| 区切り文字 | N/A（HTMLフォーマット） |
| 保持期間 | 3日間（retention-days: 3） |

## 処理フロー

### 処理シーケンス

```
1. トリガー検知
   └─ pushイベントの検知
2. コードチェックアウト
   └─ actions/checkout@v6でリポジトリをクローン
3. Rubyバージョン確認
   └─ ruby -v を実行
4. コンパイラバージョン確認
   └─ clang-18 --version を実行
5. ビルドとテスト実行
   └─ rake test を --coverage フラグ付きで実行
6. gcovrインストール
   └─ pip install gcovr を実行
7. カバレッジレポート生成
   └─ gcovr --gcov-executable "llvm-cov-18 gcov" でHTML形式のレポートを生成
   └─ GITHUB_STEP_SUMMARYにサマリーを出力
8. アーティファクトアップロード
   └─ actions/upload-artifact@v6でcoverage/ディレクトリをアップロード
```

### フローチャート

```mermaid
flowchart TD
    A[push イベント] --> B[コードチェックアウト]
    B --> C[Ruby/コンパイラバージョン確認]
    C --> D[rake test 実行 --coverage付き]
    D --> E{テスト結果}
    E -->|成功| F[pip install gcovr]
    E -->|失敗| G[ジョブ失敗]
    F --> H[gcovr でカバレッジレポート生成]
    H --> I[GITHUB_STEP_SUMMARYにサマリー出力]
    I --> J[coverage/をアーティファクトとしてアップロード]
    J --> K[正常終了]
    G --> L[バッチ終了]
    K --> L
```

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

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

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

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

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ジョブ失敗 | ビルドエラー | コンパイルエラー | ソースコードを修正してpush |
| ジョブ失敗 | テスト失敗 | テストケース失敗 | テスト結果を確認し修正 |
| ジョブ失敗 | gcovr失敗 | カバレッジデータ生成エラー | gcovrの設定やコンパイルフラグを確認 |
| ジョブ失敗 | アップロード失敗 | アーティファクトのアップロードエラー | GitHub Actionsのストレージ状況を確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（GitHub Actions標準動作、手動で再実行可能） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

ジョブ失敗時はGitHub Actionsのログを確認し、失敗したステップを特定する。GitHub UIから手動で再実行が可能。

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | mruby全ソース・テスト |
| 目標処理時間 | 特に定めなし（タイムアウト設定なし） |
| メモリ使用量上限 | GitHub Actionsランナーのデフォルト値 |

## 排他制御

同一コミットに対する複数のCoverageワークフロー実行は、アーティファクト名にgithub.shaが含まれるため競合しない。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ジョブ開始時 | チェックアウト情報、Ruby/コンパイラバージョン |
| 進捗ログ | ビルド・テスト中 | コンパイル進捗、テスト実行状況 |
| 終了ログ | カバレッジ生成完了時 | カバレッジサマリー（GITHUB_STEP_SUMMARY） |
| エラーログ | エラー発生時 | エラー詳細 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ジョブ実行時間 | 特に定めなし（タイムアウト設定なし） | GitHub Actions UI |
| ジョブ失敗 | 1件以上 | GitHub通知 |

## 備考

- pushイベントのみでトリガーされる（pull_requestでは実行されない）
- clang-18を使用し、`-O0 -g --coverage` フラグでカバレッジ計測を有効化
- gcovrの `--gcov-executable "llvm-cov-18 gcov"` オプションでLLVM互換のgcovツールを指定
- テストファイル（`*_test.c`、`*/test/*`）はカバレッジ計測から除外される（`-e` オプション）
- `--html-details` オプションで詳細なHTML形式のカバレッジレポートを生成
- `-s` オプションでサマリーを標準出力にも表示
- アーティファクトの保持期間は3日間（`retention-days: 3`）
- アーティファクト名はコミットSHAを含む: `coverage-{github.sha}`
- build/ディレクトリを対象としてカバレッジデータを収集
