# バッチ設計書 39-repl

## 概要

本ドキュメントは、Pull RequestにREPLコメントを作成/更新するバッチ「repl」の設計仕様を定義するものである。

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

本バッチは、Pull Requestがオープンされた際に、CircleCIでビルドされたBabel standaloneを使用してオンラインREPLでテストできるリンクをPRコメントとして自動投稿する。

**業務上の目的・背景**：Babelへのコントリビューターやレビュアーが、Pull Requestの変更をローカル環境でビルドすることなく、ブラウザ上のBabel REPLで即座にテストできるようにする。これにより、レビュープロセスが効率化され、変更の動作確認が容易になる。

**バッチの実行タイミング**：pull_request_targetイベントで実行される。これにより、フォークからのPRでもワークフローが実行可能になる。

**主要な処理内容**：
1. リポジトリをチェックアウト
2. scripts/actions/repl.tsスクリプトを実行
3. CircleCI APIを使用してPRに対応するジョブIDを取得
4. ジョブが完了するまで最大10分間待機
5. PRに既存のREPLコメントがあれば更新、なければ新規作成
6. コメントにはbabeljs.io/repl/build/{jobId}形式のREPLリンクを含む

**前後の処理との関連**：CircleCIで実行されるbabel-standaloneビルドジョブの完了を待つ必要がある。ワークフローは最初に60秒のスリープを実行してCircleCIトリガーを待つ。

**影響範囲**：Pull Requestのコメントセクションにのみ影響する。REPLリンクを通じてBabel standaloneのテストが可能になる。

## バッチ種別

自動化 / PR支援

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動 |
| 実行時刻 | 該当なし（イベント発生時） |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | pull_request_target |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Pull Request作成/更新 | pull_request_targetイベントが発生すること |
| CircleCIビルド | 対応するCircleCIパイプラインが実行されていること |
| BOT_TOKEN | PRコメント作成/更新に必要なトークン |

### 実行可否判定

pull_request_targetイベントで自動的に実行される。concurrency設定により、同一head_refでの並行実行はキャンセルされる。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| pull_number（内部） | number | Yes | - | context.issue.numberから取得 |
| head_ref（内部） | string | Yes | - | PRのheadブランチ名 |
| fork（内部） | boolean | Yes | - | フォークからのPRかどうか |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| GitHub context | Object | PRイベント情報 |
| CircleCI API | REST API | パイプライン・ワークフロー・ジョブ情報 |
| 既存PRコメント | GitHub API | 既存のREPLコメントの有無 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| PRコメント | Markdown | REPLリンクを含むコメント |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | なし（PRコメント） |
| 出力先 | Pull Request コメントセクション |
| 文字コード | UTF-8 |
| 区切り文字 | Markdown形式 |

## 処理フロー

### 処理シーケンス

```
1. リポジトリチェックアウト
   └─ actions/checkout@v4
2. repl.tsスクリプト実行
   └─ actions/github-script@v8
3. 60秒スリープ
   └─ CircleCIトリガーを待機
4. CircleCIパイプラインID取得
   └─ /api/v2/project/github/babel/babel/pipeline?branch={branch}
5. ワークフローID取得
   └─ /api/v2/pipeline/{pipelineId}/workflow
6. ジョブ完了待機（最大10分）
   └─ /api/v2/workflow/{workflowId}/job を10秒間隔でポーリング
7. 既存REPLコメント検索
   └─ issues.listComments APIでCOMMENT_PREFIXを検索
8. コメント作成/更新
   └─ issues.createComment または issues.updateComment
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[リポジトリチェックアウト]
    B --> C[60秒スリープ]
    C --> D[CircleCIパイプラインID取得]
    D --> E[ワークフローID取得]
    E --> F[ジョブステータス確認]
    F --> G{ジョブ完了?}
    G -->|No| H{10分経過?}
    H -->|No| I[10秒待機]
    I --> F
    H -->|Yes| J[エラー終了]
    G -->|Yes| K{成功?}
    K -->|No| J
    K -->|Yes| L[既存コメント検索]
    L --> M{コメント存在?}
    M -->|Yes| N[コメント更新]
    M -->|No| O[コメント作成]
    N --> P[バッチ終了]
    O --> P
    J --> P
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | CircleCIジョブ失敗 | ビルドジョブが失敗またはタイムアウト | CircleCIログを確認 |
| 1 | CircleCI API失敗 | ネットワークエラーまたはAPI制限 | ネットワーク接続を確認 |
| 1 | GitHub API失敗 | コメント作成/更新失敗 | BOT_TOKEN権限を確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 60回（ジョブ完了待機） |
| リトライ間隔 | 10秒 |
| リトライ対象エラー | CircleCIジョブのrunning状態 |

### 障害時対応

1. GitHub Actionsログでエラー内容を確認
2. CircleCIダッシュボードでジョブ状態を確認
3. ワークフローを再実行（PRの再pushまたはclose/reopen）

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1PRあたり1回 |
| 目標処理時間 | 12分以内（60秒スリープ + 最大10分待機 + 処理時間） |
| メモリ使用量上限 | 該当なし（CI環境依存） |

## 排他制御

- concurrency設定により、同一head_refでの並行実行を防止
- cancel-in-progress: trueにより、新しい実行が古い実行をキャンセル

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | スクリプト開始時 | PR番号 |
| 進捗ログ | ポーリング時 | ジョブステータス |
| 終了ログ | コメント作成/更新時 | REPLリンクURL |
| エラーログ | エラー発生時 | エラー詳細 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ジョブ失敗 | 1回 | GitHub Actions UI |
| 実行時間 | 15分 | GitHub Actions UI |

## 備考

- pull_request_targetイベントを使用することで、フォークからのPRでもワークフローシークレット（BOT_TOKEN）にアクセス可能
- COMMENT_PREFIX = "Build successful! You can test your changes in the REPL here: " で既存コメントを識別
- フォークの場合は "pull/{pull_number}" ブランチ名、それ以外は GITHUB_HEAD_REF を使用してCircleCIを検索
- CircleCIジョブが "running" 以外で "success" でない場合、エラーとして扱う
- REPLリンク形式: https://babeljs.io/repl/build/{job_number}
