# バッチ設計書 4-License Report Update

## 概要

本ドキュメントは、License Report Updateバッチ（license-report-update.yml）の設計仕様を記載したものである。このバッチは、license_finder CLIを使用してプロジェクトの依存ライブラリのライセンスレポートを生成し、変更がある場合に自動的にPull Requestを作成するバッチである。

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

**業務上の目的・背景**：オープンソースプロジェクトでは、使用している依存ライブラリのライセンスを適切に管理することが法的義務として重要である。本バッチは、license_finderを使用して依存関係のライセンス情報を定期的に収集し、Markdownレポートとして出力する。これにより、ライセンスコンプライアンスの維持と透明性の確保が可能となる。

**バッチの実行タイミング**：現在はスケジュール実行がコメントアウトされており、手動実行（workflow_dispatch）のみ可能である。元々は毎週月曜日9:00 JST（UTC 00:00）に実行される設計であった。

**主要な処理内容**：
1. GitHub App Tokenを生成
2. コードをチェックアウトし、pnpm環境をセットアップ
3. license_finder gemをインストール
4. license_finderでMarkdown形式のレポートを生成
5. タイムスタンプ行を削除（差分の誤検知防止）
6. 変更がある場合、新しいブランチを作成しPRを自動作成

**前後の処理との関連**：本バッチで作成されたPRは、License Compliance（license.yml）ワークフローによってライセンスチェックが実行される。

**影響範囲**：`docs/packages-license.md`ファイル、GitHubリポジトリのブランチとPR

## バッチ種別

レポート生成 / 自動PR作成

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 手動のみ（週次設定がコメントアウト済み） |
| 実行時刻 | -（元設計: 9:00 JST） |
| 実行曜日 | -（元設計: 月曜日） |
| 実行日 | - |
| トリガー | 手動（workflow_dispatch）のみ |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| LICENSE_CI_TRIGGER_APP_ID | GitHub App IDがvarsに設定されていること |
| LICENSE_CI_TRIGGER_APP_PRIVATE_KEY | GitHub App秘密鍵がSecretsに設定されていること |
| Node.js/pnpm | フロントエンド依存関係の解析に必要 |
| Ruby/gem | license_finderのインストールに必要 |

### 実行可否判定

- 手動トリガー時のみ実行
- 依存関係に変更がない場合、PRは作成されない（git diffで判定）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| - | - | - | - | 入力パラメータなし |

### 入力データソース

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

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| docs/packages-license.md | Markdown | ライセンスレポート |
| GitHub Branch | Git | license-report-update-{timestamp}ブランチ |
| GitHub PR | API | ライセンスレポート更新PR |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | docs/packages-license.md |
| 出力先 | リポジトリルート/docs/ |
| 文字コード | UTF-8 |
| フォーマット | Markdown（license_finder出力） |

## 処理フロー

### 処理シーケンス

```
1. GitHub App Token生成
   └─ actions/create-github-app-token@v2.1.4
   └─ contents:write, pull-requests:write権限
2. コードチェックアウト
   └─ actions/checkout@v4.3.0
   └─ App Tokenを使用
3. pnpm環境セットアップ
   └─ .github/actions/pnpm-setup
4. license_finderインストール
   └─ sudo gem install -N license_finder
5. ライセンスレポート生成
   └─ license_finder report --format=markdown
   └─ 先頭行をスキップ（tail -n +2）
   └─ タイムスタンプ行削除（sed -e '/^As of /d'）
6. 変更有無判定
   └─ git diff --quiet
   └─ 変更なし → 終了
7. ブランチ作成・コミット
   └─ git checkout -b license-report-update-{timestamp}
   └─ git add, git commit
8. プッシュ・PR作成
   └─ git push origin {branch}
   └─ gh pr create
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[GitHub App Token生成]
    B --> C[コードチェックアウト]
    C --> D[pnpm環境セットアップ]
    D --> E[license_finderインストール]
    E --> F[ライセンスレポート生成]
    F --> G[タイムスタンプ行削除]
    G --> H{変更あり?}
    H -->|いいえ| I[変更なしで終了]
    H -->|はい| J[Gitユーザー設定]
    J --> K[新ブランチ作成]
    K --> L[コミット]
    L --> M[リモートプッシュ]
    M --> N[PR作成]
    N --> O[バッチ終了]
    I --> O
```

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

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

データベース操作なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | gem install失敗 | ネットワークエラー/権限不足 | 再実行 |
| - | license_finder失敗 | 依存関係解析エラー | ログ確認、依存関係修正 |
| - | PR作成失敗 | 権限不足/API制限 | Token権限確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

- ワークフロー失敗時：GitHub Actionsの実行ログを確認し、原因特定後に手動で再実行
- 部分的失敗（レポート生成後）：手動でPRを作成

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | なし |
| コミットタイミング | git commit実行時 |
| ロールバック条件 | PR作成失敗時はブランチ削除を検討 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1回/実行 |
| 目標処理時間 | 10分以内（timeout-minutes: 10） |
| メモリ使用量上限 | GitHub Actions標準ランナー制限内 |

## 排他制御

- concurrencyグループ: `${{ github.workflow }}-${{ github.ref }}`
- 同時実行時は後続ジョブが待機

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | 各ステップ開始時 | ステップ名 |
| 進捗ログ | 処理中 | license_finder出力、git操作結果 |
| 終了ログ | バッチ終了時 | PR作成結果または「No changes to commit」 |
| エラーログ | エラー発生時 | エラー詳細 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理時間 | 10分 | GitHub Actionsタイムアウト |
| エラー発生 | - | GitHub Actionsログ |

## 備考

- cronスケジュールは現在コメントアウトされており、手動実行のみ可能
- タイムスタンプ行（"As of ..."）を削除することで、ライセンスに変更がない場合の誤差分を防止
- PRタイトル形式：「[yyyy/mm/dd] License Report Update」
- PRボディ：「This pull request automatically updates the license report.」
- GitHub Appを使用してCIトリガーを有効化
