# 機能設計書 23-@babel/plugin-transform-parameters

## 概要

本ドキュメントは、`@babel/plugin-transform-parameters` プラグインの機能設計を記載したものである。このプラグインは、ES2015（ES6）のデフォルトパラメータとレストパラメータをES5互換のコードに変換するBabelプラグインである。

### 本機能の処理概要

**業務上の目的・背景**：ES2015で導入されたデフォルトパラメータ（`function fn(a = 1)`）とレストパラメータ（`function fn(...args)`）は、関数の引数をより柔軟に扱うための構文である。古いJavaScript環境ではこれらの構文がサポートされていないため、`arguments`オブジェクトを使用した従来の方法に変換する必要がある。

**機能の利用シーン**：このプラグインは以下のような場面で利用される。
- `function fn(a = 1, b = 2) {}` のようなデフォルトパラメータの変換
- `function fn(...args) {}` のようなレストパラメータの変換
- `function fn({ a } = {}) {}` のようなデストラクチャリングパラメータの変換
- アロー関数のパラメータ変換（通常の関数に変換して処理）

**主要な処理内容**：
1. アロー関数でレスト/デフォルトパラメータを使用している場合、通常の関数に変換
2. デフォルトパラメータを`arguments`オブジェクトを使用した条件分岐に変換
3. レストパラメータをforループによる配列構築に変換
4. パラメータ参照の最適化（インデックスアクセスやlength参照の最適化）
5. シャドウイングされたパラメータの処理（IIFEラッパーの生成）

**関連システム・外部連携**：
- `@babel/core`：Babelのコア機能との連携
- `@babel/helper-plugin-utils`：プラグインユーティリティの利用
- `@babel/types`：ASTノードの検証・構築
- `@babel/plugin-transform-destructuring`：デストラクチャリングパラメータとの連携

**権限による制御**：特になし。ビルド時に実行されるトランスパイル処理のため、権限による制御は不要。

## 関連画面

本プラグインはビルドツールとして動作するため、直接的な関連画面はない。

## 機能種別

コード変換処理（AST変換）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| loose | boolean | No | looseモードの有効化。`ignoreFunctionLength` assumptionを有効にする | - |

### 入力データソース

- JavaScriptソースコード（AST形式）
- Babelの設定ファイル（babel.config.js, .babelrc等）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| transformedAST | AST | 変換後のAST |

### 出力先

変換されたASTは@babel/generatorによってJavaScriptコードとして出力される。

## 処理フロー

### 処理シーケンス

```
1. プラグイン初期化
   └─ オプション（loose）の読み込み
   └─ assumption設定の解決（ignoreFunctionLength, noNewArrows）

2. AST走査開始
   └─ 各Function（関数）ノードに対してビジターを実行

3. アロー関数の前処理
   └─ レスト/デフォルトパラメータを含む場合
   └─ 通常の関数式に変換（arrowFunctionToExpression）

4. レストパラメータ処理（convertFunctionRest）
   └─ レストパラメータの検出
   └─ 参照の最適化判定
   └─ 最適化可能: インデックスアクセスやlength参照を直接arguments参照に変換
   └─ 最適化不可: forループによる配列構築コードを生成

5. デフォルトパラメータ処理（convertFunctionParams）
   └─ 単純なパラメータリストかどうかを判定
   └─ デフォルト値の展開
   └─ looseモード: 直接代入に変換
   └─ strictモード: arguments.length検査を含む変換

6. スコープ処理
   └─ シャドウイングの検出
   └─ 必要に応じてIIFEラッパーを生成
```

### フローチャート

```mermaid
flowchart TD
    A[Function検出] --> B{アロー関数?}
    B -->|Yes| C{レスト/デフォルト含む?}
    C -->|Yes| D[通常関数に変換]
    C -->|No| Z[処理完了]
    B -->|No| E[レストパラメータ処理]
    D --> E

    E --> F{レストパラメータ含む?}
    F -->|Yes| G[参照分析]
    G --> H{最適化可能?}
    H -->|Yes| I[直接参照に変換]
    H -->|No| J[forループ生成]
    F -->|No| K[デフォルトパラメータ処理]
    I --> K
    J --> K

    K --> L{デフォルト含む?}
    L -->|Yes| M{looseモード?}
    M -->|Yes| N[直接代入変換]
    M -->|No| O[arguments.length検査付き変換]
    L -->|No| P[スコープ処理]
    N --> P
    O --> P

    P --> Q{シャドウイング?}
    Q -->|Yes| R[IIFE生成]
    Q -->|No| Z
    R --> Z
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | アロー関数変換 | レスト/デフォルトパラメータを含むアロー関数は通常関数に変換 | アロー関数でargumentsアクセスが必要な場合 |
| BR-002 | レスト最適化 | 単純な参照パターンは直接argumentsアクセスに最適化 | 参照が限定的でdeopted状態でない場合 |
| BR-003 | looseモード | 関数のlengthプロパティを無視した簡潔な変換を行う | ignoreFunctionLength assumption有効時 |
| BR-004 | IIFE生成 | パラメータのシャドウイングや外部バインディング参照がある場合 | スコープ競合が検出された場合 |

### 計算ロジック

**デフォルトパラメータの変換例（strictモード）**：
```javascript
// 入力
function fn(a = 1) {}

// 出力
function fn() {
  let a = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 1;
}
```

**デフォルトパラメータの変換例（looseモード）**：
```javascript
// 入力
function fn(a = 1) {}

// 出力
function fn(a) {
  if (a === void 0) {
    a = 1;
  }
}
```

**レストパラメータの変換例**：
```javascript
// 入力
function fn(a, ...rest) {}

// 出力
function fn(a) {
  for (var _len = arguments.length, rest = new Array(_len > 1 ? _len - 1 : 0), _key = 1; _key < _len; _key++) {
    rest[_key - 1] = arguments[_key];
  }
}
```

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

本プラグインはデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | BuildCodeFrameError | 無効なパラメータパターン | ソースコードの修正 |

### リトライ仕様

ビルドプロセスのため、リトライは不要。エラー発生時はビルドが中断される。

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

該当なし。ビルドプロセスはトランザクション管理を行わない。

## パフォーマンス要件

- AST走査は1パスで完了すること
- 最適化により生成コードのサイズを最小化すること

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

- ソースコードの変換のみを行い、外部リソースへのアクセスは行わない
- 生成されるコードは入力コードと同等のセキュリティ特性を維持する

## 備考

- ES2015のデフォルトパラメータとレストパラメータはTC39によって標準化されている
- looseモードを使用すると、関数のlengthプロパティが正しく設定されない可能性がある

---

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

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

### 推奨読解順序

#### Step 1: データ構造を理解する

まず、プラグインのオプションと型定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/babel-plugin-transform-parameters/src/index.ts` | Options型定義（6-8行目）とassumption設定（13-16行目） |

**読解のコツ**: `noNewArrows`はBabel 8でのデフォルト変更が予定されている。コメントを参照。

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

処理の起点となるビジターパターンを特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/babel-plugin-transform-parameters/src/index.ts` | visitorオブジェクト（21-51行目）で関数処理のエントリを確認 |

**主要処理フロー**:
1. **22-38行目**: アロー関数の前処理（通常関数への変換）
2. **40行目**: convertFunctionRest呼び出し
3. **41-44行目**: convertFunctionParams呼び出し
4. **46-48行目**: スコープの再クロール

#### Step 3: デフォルトパラメータ処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | params.ts | `packages/babel-plugin-transform-parameters/src/params.ts` | convertFunctionParams関数（32-193行目） |

**主要処理フロー**:
- **44-45行目**: 単純なパラメータリストの判定
- **80-110行目**: デフォルト値処理（loose/strictモード分岐）
- **158-190行目**: IIFE生成とasync/generator処理

#### Step 4: レストパラメータ処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | rest.ts | `packages/babel-plugin-transform-parameters/src/rest.ts` | convertFunctionRest関数（294-439行目） |

**主要処理フロー**:
- **296行目**: hasRest判定
- **358行目**: memberExpressionOptimisationVisitorによる参照分析
- **361-375行目**: 最適化可能な場合の処理
- **407-415行目**: forループによる配列構築

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

```
index.ts (エントリーポイント)
    │
    └─ visitor.Function
           │
           ├─ arrowFunctionToExpression（アロー関数の場合）
           │
           ├─ convertFunctionRest (rest.ts)
           │      ├─ hasRest: レストパラメータ存在確認
           │      ├─ collectShadowedParamsNames: シャドウイング検出
           │      ├─ memberExpressionOptimisationVisitor: 参照分析
           │      ├─ optimiseIndexGetter: インデックス最適化
           │      ├─ optimiseLengthGetter: length最適化
           │      └─ buildRest: forループ生成
           │
           └─ convertFunctionParams (params.ts)
                  ├─ collectShadowedParamsNames: シャドウイング検出
                  ├─ iifeVisitor: IIFE必要性判定
                  ├─ buildDefaultParam: デフォルト値展開
                  ├─ buildLooseDefaultParam: looseモード変換
                  └─ buildScopeIIFE: IIFE生成
```

### データフロー図

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

JavaScriptソース ───▶ @babel/parser ───▶ AST
                                           │
                                           ▼
                              ┌─────────────────────────┐
                              │  transform-parameters    │
                              │  ビジター               │
                              │    │                    │
                              │    ├─ アロー関数変換    │
                              │    │                    │
                              │    ├─ convertFunctionRest│
                              │    │    ├─ 参照分析     │
                              │    │    └─ 最適化/forループ│
                              │    │                    │
                              │    └─ convertFunctionParams│
                              │         ├─ シャドウ検出  │
                              │         └─ IIFE生成     │
                              └─────────────────────────┘
                                           │
                                           ▼
                              変換後AST ───▶ @babel/generator ───▶ ES5コード
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-plugin-transform-parameters/src/index.ts` | ソース | プラグインエントリーポイント |
| params.ts | `packages/babel-plugin-transform-parameters/src/params.ts` | ソース | デフォルトパラメータ変換 |
| rest.ts | `packages/babel-plugin-transform-parameters/src/rest.ts` | ソース | レストパラメータ変換 |
| shadow-utils.ts | `packages/babel-plugin-transform-parameters/src/shadow-utils.ts` | ソース | シャドウイング・IIFE ユーティリティ |
| package.json | `packages/babel-plugin-transform-parameters/package.json` | 設定 | パッケージ定義、依存関係 |
| test/fixtures/ | `packages/babel-plugin-transform-parameters/test/fixtures/` | テスト | テストフィクスチャ |
