# バッチ設計書 14-external-parser-tests

## 概要

本ドキュメントは、サードパーティのパーサーテストスイート（Test262、Flow、TypeScript）を使用してBabelパーサーの互換性を検証するCI/CDバッチ「external-parser-tests」の設計を定義するものである。

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

external-parser-testsバッチは、ECMAScript標準テストスイート（Test262）およびFlow、TypeScriptの公式テストケースを使用して、Babelパーサー（@babel/parser）の構文解析能力を検証するCI/CDジョブである。

**業務上の目的・背景**：Babelパーサーは最新のJavaScript/TypeScript構文を正確に解析する必要がある。自社のテストだけでなく、業界標準のテストスイートを使用することで、パーサーの互換性と信頼性を客観的に検証できる。Test262はECMAScript仕様の公式テストスイートであり、FlowとTypeScriptは広く使用される型付きJavaScriptの拡張である。これらとの互換性を維持することで、ユーザーのコードベースでの安定動作を保証する。

**バッチの実行タイミング**：GitHub Actions上でpushおよびpull_requestイベント発生時に自動実行される。buildジョブの完了後に実行される依存関係がある。

**主要な処理内容**：
1. リポジトリのチェックアウト
2. Node.js最新版のセットアップと依存関係のインストール
3. ビルドアーティファクトのダウンロード
4. 外部テストスイート（Test262、Flow、TypeScript）のダウンロード
5. Test262パーサーテストの実行
6. Flowパーサーテストの実行
7. TypeScriptパーサーテストの実行

**前後の処理との関連**：本バッチはbuildジョブの成果物（babel-artifact）を入力として使用する。テスト結果に基づき、パーサーの許可リスト（allowlist）の更新が必要な場合がある。

**影響範囲**：本バッチはテスト実行のみを行い、ソースコードやデータの変更は行わない。テスト失敗時はCI全体が失敗となり、PRのマージがブロックされる。

## バッチ種別

テスト実行 / 外部互換性検証

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動（随時） |
| 実行時刻 | N/A |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | GitHub Actions（push/pull_request） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| build完了 | Babelのビルドアーティファクトが生成済みであること |
| babel-artifact存在 | ビルド成果物がダウンロード可能であること |
| ネットワーク接続 | 外部テストスイートをダウンロードするためのネットワーク接続 |

### 実行可否判定

buildジョブが成功した場合のみ実行される（needs: build）。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| FLOW_COMMIT | string | No | Makefile定義 | Flowテストのコミットハッシュ |
| TYPESCRIPT_COMMIT | string | No | Makefile定義 | TypeScriptテストのコミットハッシュ |
| TEST262_COMMIT | string | No | Makefile定義 | Test262のコミットハッシュ |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| babel-artifact | GitHub Actions Artifact | Babelビルド成果物 |
| tc39/test262 | Git Repository | ECMAScript標準テストスイート |
| facebook/flow | Git Repository | Flowパーサーテストケース |
| microsoft/TypeScript | Git Repository | TypeScriptパーサーテストケース |
| allowlist.txt | テキスト | 既知の失敗テストの許可リスト |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | テスト結果・エラー詳細 |
| GitHub Actions Log | ログ | ジョブ実行ログ |

### 出力ファイル仕様

本バッチはファイル出力を行わない（--update-allowlistオプション使用時を除く）。

## 処理フロー

### 処理シーケンス

```
1. リポジトリチェックアウト
   └─ actions/checkout@v4を使用
2. Node.js環境セットアップ
   └─ Node.js 25.6.1をセットアップ、Yarnキャッシュを有効化
3. 依存関係インストール
   └─ yarn installを実行
4. ビルドアーティファクトダウンロード
   └─ babel-artifactをダウンロードして展開
5. 外部テストスイートダウンロード
   └─ make bootstrap-flow bootstrap-typescript bootstrap-test262を実行
6. Test262テスト実行
   └─ make test-test262を実行
7. Flowテスト実行
   └─ make test-flowを実行
8. TypeScriptテスト実行
   └─ make test-typescriptを実行
9. 結果報告
   └─ 成功/失敗ステータスをGitHub Actionsに報告
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[リポジトリチェックアウト]
    B --> C[Node.js環境セットアップ]
    C --> D[yarn install]
    D --> E[babel-artifact ダウンロード]
    E --> F[外部テストスイート ダウンロード]
    F --> G[Test262 テスト実行]
    G --> H{Test262 成功?}
    H -->|成功| I[Flow テスト実行]
    H -->|失敗| N[失敗終了]
    I --> J{Flow 成功?}
    J -->|成功| K[TypeScript テスト実行]
    J -->|失敗| N
    K --> L{TypeScript 成功?}
    L -->|成功| M[成功終了]
    L -->|失敗| N
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| PARSER_ERROR | パーサーエラー | 構文解析の失敗 | パーサー実装を修正またはallowlistに追加 |
| DOWNLOAD_FAILURE | ダウンロードエラー | 外部リポジトリ接続失敗 | ネットワークを確認、リトライ |
| ARTIFACT_NOT_FOUND | 入力エラー | babel-artifactが見つからない | buildジョブを確認 |
| ALLOWLIST_MISMATCH | 許可リスト不整合 | 期待と実際の失敗テストの差異 | allowlistを更新 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（自動リトライなし） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

1. GitHub Actionsのログを確認し、失敗したテストスイートとテストケースを特定する
2. ローカル環境で該当のテストを実行して再現確認する
3. パーサーの問題であれば修正、既知の非互換であればallowlistを更新する
4. `make test-test262-update-allowlist`等で許可リストを更新可能

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | Test262: 約45,000件、Flow: 約5,000件、TypeScript: 約20,000件 |
| 目標処理時間 | 30分以内 |
| メモリ使用量上限 | 4GB（GitHub Actionsランナーのデフォルト） |

## 排他制御

同一ブランチに対する同時実行は、GitHub Actionsのconcurrencyグループ設定により制御される。新しい実行が開始されると、進行中の古い実行はキャンセルされる。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | バッチ開始時 | ジョブ名、Node.jsバージョン |
| ダウンロードログ | テストスイートダウンロード時 | リポジトリ名、コミットハッシュ |
| 進捗ログ | テスト実行中 | テストスイート名、進捗状況 |
| 終了ログ | バッチ終了時 | 成功/失敗テスト数サマリー |
| エラーログ | エラー発生時 | 失敗テスト名、パーサーエラー詳細 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理時間 | 45分超過 | GitHub Actions UI |
| 新規失敗テスト | 1件以上 | GitHub Actions UI |

## 備考

- Test262、Flow、TypeScriptの各テストスイートは特定のコミットハッシュで固定されている（Makefileで定義）
- 許可リスト（allowlist.txt）には、Babelが意図的にサポートしない構文や既知の非互換が記載されている
- `--update-allowlist`オプションを使用すると、現在の失敗テストで許可リストを更新できる
- テストスイートのバージョン更新は定期実行バッチ（update-parser-tests）で行われる
- Test262テストは正規のECMAScript仕様準拠を検証し、FlowとTypeScriptテストは拡張構文の互換性を検証する
