# バッチ設計書 42-pre-commit（pre-commit.yml）

## 概要

本ドキュメントは、GitHub Actionsワークフロー「pre-commit」（pre-commit.yml）のバッチ設計書である。Pull Request作成・更新時にprek（pre-commitフック実行ツール）を使用して、コードベース全体に対してpre-commitフックを自動実行するワークフローについて記載する。

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

本ワークフローは、Pull Request時にprekを使用してpre-commitフックをリポジトリ全ファイルに対して実行し、コーディング規約違反やフォーマットの不整合を検出する。

**業務上の目的・背景**：mrubyプロジェクトではpre-commitフックを使用してコード品質を維持している。ローカル環境でのフック実行が漏れた場合でも、CI上でPull Request時に必ずフックを実行することで、品質基準を満たさないコードがマージされることを防止する。j178/prekツールを使用することで、高速かつ信頼性の高いフック実行を実現している。

**バッチの実行タイミング**：Pull Request作成時および更新時に自動実行される。

**主要な処理内容**：
1. リポジトリのソースコードをチェックアウトする
2. prek-actionを使用してpre-commitフックを全ファイルに対して実行する
3. manualステージのpre-commitフックを追加で全ファイルに実行する

**前後の処理との関連**：本ワークフローはPull Requestの品質ゲートとして機能し、Super-Linter（No.43）やls-lint（No.44）等の他のLintワークフローと並行して実行される。ローカル環境では`rake check`（No.27）が同等の機能を提供する。

**影響範囲**：Pull Requestのマージ可否判定。pre-commitフックの検証結果がPull Requestのステータスチェックとして表示される。

## バッチ種別

品質管理 / コードLint / CI（継続的インテグレーション）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（イベント駆動） |
| 実行時刻 | 該当なし（イベントトリガー） |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | Pull Request作成・更新時 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| GitHubリポジトリ | mrubyリポジトリがGitHub上に存在すること |
| pre-commit設定 | .pre-commit-config.yamlがリポジトリに存在すること |
| Pull Request | Pull Requestイベントが発生していること |

### 実行可否判定

GitHub Actionsのpull_requestイベントトリガーにより自動判定される。全てのPull Requestに対して実行され、ブランチのフィルタリングは行われない。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| extra-args | string | No | --all-files | prek-actionに渡す追加引数 |
| hook-stage | string | No | manual | 手動フック実行時のステージ指定 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| リポジトリソースコード | ファイルシステム | チェックアウトされたソースコード全体 |
| .pre-commit-config.yaml | YAML | pre-commitフックの設定ファイル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| Pull Requestステータス | GitHub Check | ワークフローの成功/失敗ステータス |
| GitHub Actionsログ | テキスト | フック実行結果の詳細ログ |

### 出力ファイル仕様

本ワークフローはファイル出力を行わない。結果はGitHub Actionsのログおよびチェックステータスとして出力される。

| 項目 | 内容 |
|-----|------|
| ファイル名 | 該当なし |
| 出力先 | GitHub Actionsログ |
| 文字コード | 該当なし |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. リポジトリチェックアウト
   └─ actions/checkout@v6でソースコードを取得（ref: github.ref, sha: github.sha）
2. pre-commitフック実行（自動ステージ）
   └─ j178/prek-action@v1を使用して--all-filesオプションで全ファイルに対してフックを実行
3. pre-commitフック実行（manualステージ）
   └─ prek run --color=always --all-files --hook-stage manualで手動ステージのフックを追加実行
```

### フローチャート

```mermaid
flowchart TD
    A[ワークフロー開始<br>Pull Request] --> B[リポジトリチェックアウト<br>actions/checkout@v6]
    B --> C[prek-action実行<br>--all-files]
    C --> D{自動フック結果}
    D -->|成功| E[manualステージフック実行<br>prek run --hook-stage manual]
    D -->|失敗| F[ワークフロー失敗]
    E --> G{manualフック結果}
    G -->|成功| H[ワークフロー成功]
    G -->|失敗| F
```

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

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

本ワークフローはデータベース操作を行わない。

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 該当なし | 該当なし | 該当なし | 該当なし |

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | フック違反 | pre-commitフックがコード違反を検出した場合 | 該当するコードを修正してPRを更新する |
| - | prekインストールエラー | prek-actionのセットアップに失敗した場合 | GitHub Actionsのランナー状態を確認し再実行する |
| - | manualフック失敗 | manualステージのフック実行に失敗した場合 | manualステージのフック定義を確認し修正する |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 手動で再実行（GitHub Actions UIまたはPR更新） |
| リトライ間隔 | 該当なし（手動） |
| リトライ対象エラー | 一時的なインフラエラー |

### 障害時対応

フック違反による失敗の場合は、ログから違反箇所を特定し、コードを修正してPull Requestを更新する。インフラ起因の場合はGitHub Actions UIからワークフローを再実行する。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし（CI/CDパイプライン） |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | リポジトリ全ファイル |
| 目標処理時間 | 明示的な規定なし |
| メモリ使用量上限 | ubuntu-latestランナーのデフォルト（7GB RAM） |

## 排他制御

GitHub Actionsの標準動作により、同一PRに対する複数のワークフロー実行が発生する可能性がある。concurrencyの設定は定義されていないため、同時実行が許可されている。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ワークフロー開始時 | GitHub Actionsの標準ログ（PRイベント情報） |
| 進捗ログ | フック実行中 | 各フックの実行結果（パス/フェイル）、--color=alwaysでカラー出力 |
| 終了ログ | ワークフロー終了時 | フック実行結果サマリー |
| エラーログ | フック違反時 | 違反ファイル名、行番号、違反内容 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ワークフロー失敗 | 1回 | GitHubリポジトリの通知設定に従う |
| フック違反検出 | 1件以上 | Pull Requestのステータスチェック |

## 備考

- j178/prek-action@v1を使用している（prekはpre-commitの高速な代替ツール）
- 自動ステージとmanualステージの2段階でフック実行を行う
- `--all-files`オプションにより、変更ファイルだけでなくリポジトリ全体を検証する
- 権限設定は`contents: read`のみで、コードの読み取りのみを行う
- ローカル環境では`rake check`（No.27）が同等の処理を提供する
