# 機能設計書 49-@babel/plugin-transform-runtime

## 概要

本ドキュメントは、Babelプラグインであるヘルパー関数の@babel/runtimeからの参照変換機能について記述する。

### 本機能の処理概要

**業務上の目的・背景**：
Babelは変換時にヘルパー関数を生成するが、これらは各ファイルにインラインで挿入されるため、コードの重複が発生する。本プラグインは、ヘルパー関数を@babel/runtimeパッケージからのインポートに置き換えることで、出力コードサイズを削減し、共有ヘルパーによる効率的なバンドルを実現する。

**機能の利用シーン**：
- ライブラリ開発時のバンドルサイズ最適化
- 複数ファイルでヘルパーを共有したい場合
- グローバルスコープの汚染を避けたい場合
- @babel/preset-envと組み合わせた利用

**主要な処理内容**：
1. Babelヘルパー関数のインライン挿入をインポート文に置き換え
2. @babel/runtime/helpers/からの named import 生成
3. CommonJS/ESM環境に応じた適切なインポート形式の選択
4. ヘルパーのバージョン互換性チェック

**関連システム・外部連携**：
@babel/runtimeパッケージが必要。@babel/helper-module-importsでインポート文を生成。

**権限による制御**：
プラグインオプション（absoluteRuntime、version、moduleName）による動作制御が可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本機能はCLI/APIから利用されるプラグインのため、直接の画面関連なし |

## 機能種別

コード最適化（AST変換）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| absoluteRuntime | boolean/string | No | ランタイムへの絶対パスを使用 | boolean/string |
| version | string | No | @babel/runtimeのバージョン（デフォルト: "8.0.0-beta.0"） | セマンティックバージョン |
| moduleName | string | No | カスタムランタイムモジュール名（デフォルト: null→@babel/runtime） | - |

### 入力データソース

Babelヘルパー関数を使用するJavaScriptソースコード（AST形式）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| transformedAST | t.Program | ヘルパーインポートが追加されたAST |
| helperImports | t.ImportDeclaration | @babel/runtime/helpers/からのインポート文 |

### 出力先

変換されたAST（@babel/coreに返却）

## 処理フロー

### 処理シーケンス

```
1. pre()フック
   └─ helperGenerator関数を設定
2. helperGenerator呼び出し（各ヘルパー要求時）
   └─ modulePathを計算
   └─ availableHelper()でバージョン互換性チェック
   └─ HEADER_HELPERSの場合blockHoist=4を設定
   └─ addDefaultImportでインポート文生成
   └─ キャッシュに保存
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[pre()フック]
    B --> C[helperGenerator設定]
    C --> D{ヘルパー要求?}
    D -->|Yes| E[modulePath計算]
    E --> F{absoluteRuntime?}
    F -->|Yes| G[絶対パス解決]
    F -->|No| H[相対パス使用]
    G --> I[availableHelper確認]
    H --> I
    I --> J{バージョン互換?}
    J -->|No| K[インラインヘルパー使用]
    J -->|Yes| L{キャッシュあり?}
    L -->|Yes| M[キャッシュから取得]
    L -->|No| N[addDefaultImport]
    N --> O[キャッシュに保存]
    M --> P[識別子返却]
    O --> P
    D -->|No| Q[終了]
    K --> Q
    P --> Q
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-49-01 | ヘルパー置換 | インラインヘルパーをインポートに置換 | ヘルパー使用時 |
| BR-49-02 | バージョン互換性 | runtimeVersionで利用可能なヘルパーのみ置換 | availableHelper()で判定 |
| BR-49-03 | interopヘルパー優先 | interopRequireWildcard/Defaultはblock hoist=4 | 非ESM環境時 |
| BR-49-04 | キャッシュ | 同一ヘルパーは一度だけインポート | 重複防止 |
| BR-49-05 | 絶対パス | absoluteRuntime時はファイルシステムパスを使用 | absoluteRuntime=true/string時 |

### 計算ロジック

ヘルパーパス計算:
```javascript
// 基本形
`${moduleName}/helpers/${helperName}`
// → "@babel/runtime/helpers/classCallCheck"

// absoluteRuntime=true
`/absolute/path/to/@babel/runtime/helpers/${helperName}`
```

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

該当なし（ファイルシステム操作のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| INVALID_ABSOLUTE_RUNTIME | 設定エラー | absoluteRuntimeがboolean/string以外 | 正しい型を指定 |
| INVALID_VERSION | 設定エラー | versionがstringでない | バージョン文字列を指定 |
| INVALID_MODULE_NAME | 設定エラー | moduleNameがnull/string以外 | 正しい型を指定 |
| DEPRECATED_USE_BUILT_INS | 設定エラー | useBuiltInsオプション使用 | オプションを削除 |
| DEPRECATED_POLYFILL | 設定エラー | polyfillオプション使用 | corejsオプションを使用 |
| DEPRECATED_REGENERATOR | 設定エラー | regeneratorオプション使用 | オプションを削除 |
| DEPRECATED_USE_ES_MODULES | 設定エラー | useESModulesオプション使用 | オプションを削除 |
| DEPRECATED_HELPERS | 設定エラー | helpersオプション使用 | プラグインを削除 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

特定のパフォーマンス要件なし（変換処理は同期的に実行）

## セキュリティ考慮事項

- @babel/runtimeは信頼できるソースからインストールすること
- absoluteRuntimeを使用する場合、パスの検証に注意

## 備考

- Babel 8では多くのオプションが削除/簡素化された
- regeneratorオプションは不要になり、ヘルパーとして自動的に処理される
- useESModulesオプションはpackage.json#exportsで自動判定
- helpersオプションは削除（無効化するならプラグイン自体を削除）

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: オプション型を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/babel-plugin-transform-runtime/src/index.ts` | Options型（8-14行目） |

**読解のコツ**: Babel 8では多くのオプションが廃止されており、version/absoluteRuntime/moduleNameが中心。

#### Step 2: オプション検証を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/babel-plugin-transform-runtime/src/index.ts` | オプション検証（25-94行目） |

**主要処理フロー**:
- **25-32行目**: absoluteRuntimeの型検証
- **34-36行目**: versionの型検証
- **38-40行目**: moduleNameの型検証
- **42-94行目**: 廃止オプションのエラー処理

#### Step 3: helperGeneratorを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts | `packages/babel-plugin-transform-runtime/src/index.ts` | pre()フックとhelperGenerator（101-163行目） |

**主要処理フロー**:
- **105行目**: file.set("helperGenerator", ...)でジェネレータを設定
- **108-115行目**: modulePathの計算
- **121行目**: availableHelper()でバージョン互換性チェック
- **126-127行目**: HEADER_HELPERSのblockHoist設定
- **132行目**: addDefaultImportでインポート生成

#### Step 4: addDefaultImport関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | index.ts | `packages/babel-plugin-transform-runtime/src/index.ts` | addDefaultImport関数（137-162行目） |

**主要処理フロー**:
- **146-147行目**: キャッシュキーの生成（ESM判定を含む）
- **149-151行目**: キャッシュヒット時のクローン返却
- **153-158行目**: addDefaultでインポート生成

### プログラム呼び出し階層図

```
@babel/plugin-transform-runtime/src/index.ts
    │
    ├─ @babel/helper-plugin-utils
    │      └─ declare()
    │
    ├─ @babel/helper-module-imports
    │      ├─ addDefault()
    │      └─ isModule()
    │
    └─ ./get-runtime-path/
           ├─ getRuntimePath()
           └─ resolveFSPath()
```

### データフロー図

```
[入力]                    [処理]                         [出力]

Babelヘルパー要求  ──▶  helperGenerator
                              │
                              ▼
                     modulePath計算
                              │
                              ▼
                     availableHelper確認
                              │
                     ┌────────┼────────┐
                     ▼                 ▼
              互換あり           互換なし
                     │                 │
                     ▼                 ▼
              addDefaultImport   インラインヘルパー
                     │
                     ▼
                import文追加
                     │
                     ▼
                変換済みAST
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-plugin-transform-runtime/src/index.ts` | ソース | メインプラグイン実装（166行） |
| get-runtime-path/ | `packages/babel-plugin-transform-runtime/src/get-runtime-path/` | ソース | ランタイムパス解決 |
| package.json | `packages/babel-plugin-transform-runtime/package.json` | 設定 | 依存関係・メタデータ |
| @babel/runtime | 外部パッケージ | ランタイム | ヘルパー関数を提供 |
