# バッチ設計書 49-gulp generate-runtime-helpers

## 概要

本ドキュメントは、Babelプロジェクトにおけるランタイムヘルパー生成バッチ `gulp generate-runtime-helpers` の設計について記載する。このバッチは@babel/helpersパッケージのヘルパー関数定義を自動生成する。

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

**業務上の目的・背景**：@babel/helpersパッケージには、トランスパイル時に挿入されるランタイムヘルパー関数が含まれている。これらのヘルパーは個別のソースファイルとして管理されており、ビルド時に単一のhelpers-generated.tsファイルに統合される。この自動生成により、ヘルパーの追加・変更が容易になり、コードの圧縮やメタデータの抽出も自動化される。

**バッチの実行タイミング**：`gulp build` および `gulp build-dev` の一部として実行される。また、`gulp watch` でhelpersディレクトリの変更時に自動実行される。

**主要な処理内容**：
1. packages/babel-helpers/src/helpers/ディレクトリ内の全ヘルパーファイルを読み込み
2. 各ヘルパーの@minVersionコメントからバージョン情報を抽出
3. TypeScriptからJavaScriptへのトランスパイル
4. Terserによるコード圧縮（関数名の維持オプションあり）
5. ヘルパーのメタデータ（依存関係、グローバル変数等）を抽出
6. helpers-generated.tsファイルの生成

**前後の処理との関連**：`gulp build` 内では、最初のビルドフェーズ後に実行され、生成されたhelpers-generated.tsを含む@babel/helpersが再度ビルドされる。

**影響範囲**：packages/babel-helpers/src/helpers-generated.tsが生成・更新される。このファイルはBabelのトランスパイル結果に直接影響する重要なファイルである。

## バッチ種別

コード生成処理

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | gulp build時、helpersディレクトリ変更時 |
| 実行時刻 | N/A |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | gulp generate-runtime-helpers / gulp build / gulp watch |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Node.js環境 | Node.js 20以上が必要 |
| 依存関係インストール済み | `yarn install` によりnode_modulesが構築済み |
| Terser | コード圧縮用パッケージがインストール済み |
| @babel/preset-typescript | TypeScriptトランスパイル用 |

### 実行可否判定

packages/babel-helpers/src/helpers/ディレクトリ内にヘルパーファイルが存在すればビルド可能。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| BABEL_9_BREAKING | 環境変数 | No | false | trueで@onlyBabel8ヘルパーを除外 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| packages/babel-helpers/src/helpers/*.ts | TypeScript | ヘルパーソースファイル |
| packages/babel-helpers/src/helpers/*.js | JavaScript | ヘルパーソースファイル（一部） |
| packages/babel-helpers/scripts/generate-helpers.js | JavaScript | 生成スクリプト |
| packages/babel-helpers/scripts/build-helper-metadata.js | JavaScript | メタデータ抽出 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| packages/babel-helpers/src/helpers-generated.ts | TypeScript | 生成されたヘルパー定義 |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | helpers-generated.ts |
| 出力先 | packages/babel-helpers/src/ |
| 文字コード | UTF-8 |
| ヘッダーコメント | 自動生成警告、再生成コマンド |

## 処理フロー

### 処理シーケンス

```
1. ヘルパーファイル列挙
   └─ helpers/ディレクトリ内のファイルをソート順で読み込み

2. 各ヘルパーファイルの処理
   ├─ ファイル内容読み込み
   ├─ @minVersionコメント抽出
   ├─ @internal/@onlyBabel8/@mangleFnsフラグ確認
   ├─ TypeScript → JavaScript変換（@babel/preset-typescript）
   ├─ 相対インポートパス書き換え（./xxx.ts → xxx）
   ├─ @no-mangle関数名の収集
   ├─ Terser圧縮（関数名維持オプション付き）
   └─ メタデータ抽出（getHelperMetadata）

3. 出力ファイル生成
   ├─ ヘッダーコメント生成
   ├─ HelperインターフェースとHelperMetadata型定義
   ├─ helper関数定義
   ├─ 各ヘルパーのエントリ生成（サイズ・gzipサイズコメント付き）
   └─ formatCodeでPrettier整形
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[helpers/ディレクトリ読込]
    B --> C[ファイルをソート]
    C --> D[各ファイル処理ループ]
    D --> E{.ts or .js?}
    E -->|.ts| F[TypeScript変換]
    E -->|.js| G[直接処理]
    F --> H[@minVersion抽出]
    G --> H
    H --> I[相対インポート書換]
    I --> J[@mangleFns確認]
    J --> K[Terser圧縮]
    K --> L[メタデータ抽出]
    L --> M{@onlyBabel8 & BABEL_9?}
    M -->|Yes| N[スキップ]
    M -->|No| O[エントリ追加]
    N --> P{次ファイル?}
    O --> P
    P -->|Yes| D
    P -->|No| Q[出力ファイル生成]
    Q --> R[Prettier整形]
    R --> S[ファイル書込]
    S --> T[バッチ終了]
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | @minVersion未定義 | バージョンコメントがない場合 | ヘルパーファイルに@minVersionを追加 |
| - | 圧縮エラー | 構文エラーがある場合 | ヘルパーソースの構文を確認 |
| - | TypeScriptエラー | 型エラーがある場合 | ヘルパーの型定義を修正 |

### リトライ仕様

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

### 障害時対応

生成エラー時は、該当するヘルパーファイルの構文と@minVersionコメントの存在を確認する。

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

本バッチはデータベーストランザクションを使用しない。

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 約50〜100ヘルパーファイル |
| 目標処理時間 | 10秒〜1分 |
| メモリ使用量上限 | 500MB |

## 排他制御

単一の出力ファイルを生成するため、同時実行時は競合の可能性がある。通常はgulpタスク内で順次実行されるため問題にならない。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | タスク開始時 | Generating @babel/helpers runtime helpers |
| 完了ログ | 生成完了時 | Generated @babel/helpers |
| 警告ログ | 無視ファイル時 | ignoring xxx |
| エラーログ | エラー発生時 | エラーメッセージ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 生成失敗 | 1回 | CI/CDシステム通知 |

## 備考

- 出力ファイルには各ヘルパーのサイズとgzip圧縮サイズがコメントで記載される
- @mangleFnsが指定されたヘルパーは関数名を圧縮するが、@no-mangleコメント付きの関数は除外
- @internalフラグはメタデータのinternal属性として記録される
- @onlyBabel8フラグはBABEL_9_BREAKING環境変数と組み合わせて使用
- Terser圧縮オプション: ecma=5、passes=10、directives保持（_typeofヘルパー用）
- package.jsonとtsconfig.jsonはIGNORED_FILESとして除外される
- 相対インポート（./xxx.ts）はヘルパー名のみに書き換えられる
