# バッチ設計書 11-Dependency Review

## 概要

本ドキュメントは、GitHub Actions ワークフロー「Dependency Review」の設計を定義するものである。依存関係のセキュリティレビューを自動化し、脆弱性のある依存パッケージの導入を防止するバッチ処理について記載する。

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

**業務上の目的・背景**：ソフトウェア開発において、サードパーティライブラリの脆弱性はセキュリティリスクの主要因の一つである。本バッチは、Pull RequestやMerge Group時に自動的に依存関係をスキャンし、既知の脆弱性を含むパッケージの導入を事前に検知・阻止することで、プロダクトのセキュリティ品質を維持する。route06/actionsの共通ワークフローを活用することで、組織全体で統一されたセキュリティ基準を適用できる。

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

**主要な処理内容**：
1. GitHubのDependency Review機能を呼び出し、PRで追加・変更される依存パッケージを特定
2. 各依存パッケージに対して、脆弱性データベース（GitHub Advisory Database）との照合を実施
3. 脆弱性が検出された場合、PR上にコメントとして警告を出力
4. 重大な脆弱性が含まれる場合、CIステータスを失敗に設定してマージをブロック

**前後の処理との関連**：本バッチは独立して動作するが、License Compliance（No.10）と同様にPR/merge_group時に並列実行される。他のCI/CDバッチ（Frontend CI、Database CI等）と連携してPRの品質ゲートを構成する。

**影響範囲**：Pull Request全体、依存関係の変更を含むpackage.json、pnpm-lock.yaml等のファイル

## バッチ種別

セキュリティスキャン / 依存関係レビュー

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動（随時） |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | Pull Request / Merge Group |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| リポジトリ設定 | GitHub Dependency Graphが有効化されていること |
| 権限 | contents: read、pull-requests: write が付与されていること |
| route06/actions | 共有ワークフローへのアクセス権があること |

### 実行可否判定

Pull RequestまたはMerge Groupイベントが発生した場合に自動実行される。特定のファイルパターンによるフィルタリングは行わず、全てのPRに対して実行される。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| - | - | - | - | 共有ワークフローにより自動設定される |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| package.json | JSON | プロジェクトの依存関係定義 |
| pnpm-lock.yaml | YAML | 依存関係のロックファイル |
| GitHub Advisory Database | API | 脆弱性データベース |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| Pull Requestコメント | Markdown | 脆弱性検出結果のレポート |
| GitHub Checks | Status | CI実行結果（成功/失敗） |

### 出力ファイル仕様

ファイル出力は行わない。結果はGitHub PR上に直接コメントとして出力される。

## 処理フロー

### 処理シーケンス

```
1. イベント検知
   └─ Pull RequestまたはMerge Groupイベントを受信

2. route06/actions共有ワークフロー呼び出し
   └─ dependency_review.ymlを実行

3. 依存関係変更の検出
   └─ PR差分から依存関係の追加・更新・削除を特定

4. 脆弱性スキャン
   └─ GitHub Advisory Databaseと照合

5. 結果レポート出力
   └─ PRにコメントとして検出結果を投稿

6. ステータス設定
   └─ 脆弱性有無に応じてチェックステータスを設定
```

### フローチャート

```mermaid
flowchart TD
    A[PR/Merge Group イベント発生] --> B[route06/actions ワークフロー呼び出し]
    B --> C[依存関係変更検出]
    C --> D{脆弱性検出?}
    D -->|あり| E[PRにコメント出力]
    E --> F{重大な脆弱性?}
    F -->|あり| G[ステータス: 失敗]
    F -->|なし| H[ステータス: 警告付き成功]
    D -->|なし| I[ステータス: 成功]
    G --> J[バッチ終了]
    H --> J
    I --> J
```

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

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

データベース操作は行わない。

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| NETWORK_ERROR | ネットワークエラー | GitHub APIへの接続失敗 | 自動リトライ後、手動再実行 |
| AUTH_ERROR | 認証エラー | トークン無効・期限切れ | シークレット設定を確認 |
| RATE_LIMIT | レート制限 | API呼び出し上限超過 | 一定時間待機後に再実行 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | route06/actionsの設定に準拠 |
| リトライ間隔 | route06/actionsの設定に準拠 |
| リトライ対象エラー | 一時的なネットワークエラー |

### 障害時対応

1. ワークフロー実行ログを確認し、エラー原因を特定
2. route06/actionsのバージョン互換性を確認
3. 必要に応じてPRを再プッシュまたはワークフローを手動再実行

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1 PR（依存関係数百件程度） |
| 目標処理時間 | 5分以内 |
| メモリ使用量上限 | GitHubランナー標準（7GB） |

## 排他制御

同一PRに対する同時実行は許可される。ワークフローレベルでの排他制御は設定されていない。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ワークフロー開始時 | イベント種別、PR番号 |
| 進捗ログ | スキャン中 | スキャン対象パッケージ数 |
| 終了ログ | ワークフロー終了時 | 検出結果サマリー |
| エラーログ | エラー発生時 | エラー詳細、スタックトレース |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 実行失敗 | 1回 | GitHub Checks UI |
| 脆弱性検出 | 1件以上 | PR コメント |

## 備考

- route06/actions v2.7.0（コミット: 3bcea5bf834ff2e0e6c912c1167fcc1fe05e49c2）を使用
- GitHub Dependency Review Actionの詳細設定は共有ワークフロー側で管理
