# 機能設計書 10-@babel/helpers

## 概要

本ドキュメントは、Babelのランタイムヘルパー関数集である`@babel/helpers`パッケージの設計仕様を記述する。このパッケージは、変換後のコードで使用される共通のユーティリティ関数をASTとして提供する。

### 本機能の処理概要

**業務上の目的・背景**：Babelがコードを変換する際、特定のJavaScript機能（クラス、スプレッド演算子、async/await等）をエミュレートするためのヘルパー関数が必要となる。@babel/helpersは、これらのヘルパー関数をAST形式で提供し、変換プラグインが出力コードに必要なランタイムサポートを注入できるようにする。

**機能の利用シーン**：@babel/plugin-transform-classesでクラス変換時、@babel/plugin-transform-spread でスプレッド演算子変換時、その他の変換プラグインでヘルパーが必要な場合に利用される。

**主要な処理内容**：
1. ヘルパー関数ASTの提供
2. ヘルパー間の依存関係管理
3. バインディング名の動的変更
4. ローカル変数との競合回避
5. 最小バージョン情報の提供

**関連システム・外部連携**：@babel/core（ヘルパー注入）、@babel/types（AST操作）、各種変換プラグインと連携する。

**権限による制御**：特になし。純粋なAST生成のみ。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | プログラマティックなAPIとして動作 |

## 機能種別

ヘルパー関数ライブラリ

## 入力仕様

### 入力パラメータ

#### get(name, getDependency?, bindingName?, localBindings?, adjustAst?)
| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|-----|------|
| name | string | Yes | ヘルパー名 |
| getDependency | Function | No | 依存ヘルパーの取得関数 |
| bindingName | string | No | バインディング名 |
| localBindings | string[] | No | 競合を避けるローカル変数名 |
| adjustAst | Function | No | AST調整関数 |

#### minVersion(name)
| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|-----|------|
| name | string | Yes | ヘルパー名 |

#### getDependencies(name)
| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|-----|------|
| name | string | Yes | ヘルパー名 |

### 入力データソース

- @babel/coreからの呼び出し
- 変換プラグインからの直接呼び出し

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| nodes | t.Statement[] | ヘルパー関数のAST |
| globals | string[] | 使用するグローバル変数 |
| minVersion | string | 必要な最小@babel/runtimeバージョン |
| dependencies | string[] | 依存するヘルパー名 |

### 出力先

- 呼び出し元への直接返却

## 処理フロー

### 処理シーケンス

```
1. get関数の呼び出し
   └─ ヘルパー名を受け取る
2. loadHelper実行
   └─ ヘルパーデータをロードまたはキャッシュから取得
3. permuteHelperAST実行
   └─ バインディング名の変更
   └─ 依存関係の解決
   └─ ローカル変数との競合回避
4. 結果オブジェクトの構築
   └─ nodes、globalsを返却
```

### フローチャート

```mermaid
flowchart TD
    A[get呼び出し] --> B[loadHelper]
    B --> C{キャッシュあり?}
    C -->|Yes| D[キャッシュから取得]
    C -->|No| E[helpers-generated.tsからロード]
    E --> F[helperDataを構築]
    F --> G[キャッシュに保存]
    D --> H[build実行]
    G --> H
    H --> I[helper.ast呼び出し]
    I --> J[permuteHelperAST]
    J --> K[ローカル変数名の変更]
    K --> L[依存関係の解決]
    L --> M[結果を返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 名前衝突回避 | ローカル変数名と競合する場合、アンダースコアを付加 | localBindings指定時 |
| BR-02 | 依存解決 | getDependency関数でヘルパー間の依存を解決 | 依存ヘルパー参照時 |
| BR-03 | 内部ヘルパー | internalフラグのヘルパーは直接使用不可 | isInternal確認時 |
| BR-04 | 遅延ロード | ヘルパーデータは初回アクセス時にロード | 常時 |
| BR-05 | listエクスポート | 利用可能なヘルパー名一覧を提供 | list参照時 |

### 計算ロジック

特になし

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| BABEL_HELPER_UNKNOWN | ReferenceError | 不明なヘルパー名 | 有効なヘルパー名を使用 |

### リトライ仕様

リトライ機能なし

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

該当なし

## パフォーマンス要件

- ヘルパーデータはキャッシュされ、再利用時は高速
- 事前生成されたhelpers-generated.tsからロード

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

- AST生成のみでコード実行は発生しない

## 備考

- アンダースコア付きのヘルパー名（例: _classCallCheck）は内部用
- @babel/runtimeと組み合わせて使用することで、ヘルパーの重複を避けられる

---

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

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

### 推奨読解順序

#### Step 1: エントリーポイントを理解する

処理の起点となるファイルを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/babel-helpers/src/index.ts` | 公開API（get, minVersion, getDependencies, list）（1-162行目） |

**主要処理フロー**:
1. **95-130行目**: loadHelper関数 - ヘルパーデータのロード
2. **132-145行目**: get関数 - ヘルパーASTの取得
3. **147-149行目**: minVersion関数 - 最小バージョンの取得
4. **151-153行目**: getDependencies関数 - 依存関係の取得
5. **155-157行目**: isInternal関数 - 内部ヘルパー判定
6. **159行目**: list定数 - 利用可能なヘルパー一覧

#### Step 2: AST変換処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/babel-helpers/src/index.ts` | permuteHelperAST関数（38-78行目） |

**主要処理フロー**:
- **46-64行目**: ローカル変数名の変更処理
- **66-73行目**: 依存関係の解決処理
- **75-77行目**: AST調整処理

#### Step 3: ヘルパーデータ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts | `packages/babel-helpers/src/index.ts` | HelperData型（80-92行目）、helperDataキャッシュ（94行目） |

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

```
@babel/helpers (index.ts)
    │
    ├─ get(name, ...)
    │      └─ loadHelper(name)
    │             ├─ helpers[name] (helpers-generated.ts)
    │             └─ helperData[name] = { build, minVersion, getDependencies }
    │                    │
    │                    └─ build(getDependency, bindingName, localBindings, adjustAst)
    │                           ├─ helper.ast()
    │                           └─ permuteHelperAST(ast, metadata, ...)
    │                                  ├─ locals処理（変数名変更）
    │                                  └─ dependencies処理（依存解決）
    │
    ├─ minVersion(name)
    │      └─ loadHelper(name).minVersion
    │
    ├─ getDependencies(name)
    │      └─ loadHelper(name).getDependencies()
    │
    ├─ isInternal(name)
    │      └─ helpers[name].metadata.internal
    │
    └─ list
           └─ Object.keys(helpers)
```

### データフロー図

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

ヘルパー名 ───────▶ loadHelper ───────▶ HelperData
"classCallCheck"                        (キャッシュ)

getDependency ───────▶ permuteHelperAST ───────▶ 調整済みAST
bindingName                                      (nodes, globals)
localBindings

helpers-generated.ts ───────▶ helper.ast() ───────▶ 元AST
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-helpers/src/index.ts` | ソース | 公開APIのエントリーポイント |
| helpers-generated.ts | `packages/babel-helpers/src/helpers-generated.ts` | 生成 | 自動生成されたヘルパー定義 |
| helpers/ | `packages/babel-helpers/src/helpers/` | ソース | 個別ヘルパーの実装 |
