# 機能設計書 62-@babel/plugin-proposal-do-expressions

## 概要

本ドキュメントは、Babelのdo式（do expressions）を変換する提案プラグイン `@babel/plugin-proposal-do-expressions` の機能設計を定義する。

### 本機能の処理概要

本プラグインは、TC39で提案されているdo式をES5互換のコードに変換する機能を提供する。do式はブロック文を式として評価可能にし、ブロック内の最後の式の値を返す。これにより、if文やswitch文などの文を式コンテキストで使用できるようになる。

**業務上の目的・背景**：JavaScriptでは文（statement）と式（expression）の区別があり、if文やswitch文などは式として使用できない。do式を使うことで、これらの制御構造を式として扱い、変数への代入やJSXの中で使用することが可能になる。例えば `const x = do { if (cond) { 1 } else { 2 } }` のような記述が可能になる。

**機能の利用シーン**：JSXの中で条件分岐を行う際、三項演算子では複雑になりすぎる場合にdo式が有用。また、変数の初期化時に複雑なロジックを適用する際にも利用される。

**主要な処理内容**：
1. DoExpressionノードを検出し、exit時に変換処理を実行
2. 制御フロー文（return、break、continue）を含む場合は特別な変換を適用
3. ブロック内の完了記録（completion records）を収集し、一時変数への代入に変換
4. IIFEパターンまたはステートメントの展開によりdo式を除去

**関連システム・外部連携**：async do式は `proposal-async-do-expressions` で別途処理される。`@babel/core`のAST変換機能を利用する。

**権限による制御**：特にロールや権限による制御はない。Babel設定ファイルでのプラグイン有効化により機能する。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本機能はCLIツールまたはビルドプロセスで使用され、GUI画面との関連はない |

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| - | - | - | 本プラグインにはオプションパラメータはない | - |

### 入力データソース

- ソースコードからのASTノード（DoExpressionノード）
- assumption設定（noDocumentAll）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| transformedAST | AST Node | 変換後のAST（展開されたステートメントまたはIIFE） |

### 出力先

- 変換後のJavaScriptコード（Babelのパイプライン出力）

## 処理フロー

### 処理シーケンス

```
1. DoExpression exit時に変換開始
   └─ async do式は処理をスキップ
2. 制御フロー文の収集
   └─ collectControlFlowStatements で return/break/continue を検出
3. 制御フロー文がある場合
   └─ transformDoExpressionWithControlFlowStatements を実行
   └─ 親ステートメントを平坦化
4. 制御フロー文がない場合
   └─ replaceExpressionWithStatements でブロック本体を展開
   └─ 空の場合は undefined に置換
5. 完了記録の処理
   └─ getCompletionRecords で完了式を取得
   └─ 一時変数への代入に変換
```

### フローチャート

```mermaid
flowchart TD
    A[DoExpression検出] --> B{async do式?}
    B -->|Yes| Z[処理スキップ]
    B -->|No| C[制御フロー文収集]
    C --> D{return/break/continue あり?}
    D -->|Yes| E[transformDoExpressionWithControlFlowStatements]
    E --> F[親ステートメント検索]
    F --> G[flattenStatement実行]
    D -->|No| H{ブロック本体が空?}
    H -->|Yes| I[undefined に置換]
    H -->|No| J[replaceExpressionWithStatements]
    G --> K[終了]
    I --> K
    J --> K
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | async do式スキップ | async do式は別プラグインで処理するためスキップ | node.async === true |
| BR-02 | 空ブロック処理 | 空のdo式はundefinedに置換 | body.length === 0 |
| BR-03 | 制御フロー変換 | return/break/continueを含む場合は特別な変換 | 制御フロー文検出時 |
| BR-04 | 完了記録処理 | ブロックの最後の式を一時変数に代入 | 制御フローなし |
| BR-05 | オプショナルチェイン対応 | OptionalMemberExpression/CallExpressionの特別処理 | computed プロパティあり |

### 計算ロジック

- 単純なdo式: `do { expr }` → `expr`
- 複数文のdo式: `do { stmt1; expr }` → IIFE化またはステートメント展開
- 制御フローあり: `do { if (c) return x; y }` → 親関数の変換を含む複雑な処理

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベース操作なし |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | サポート外パターン | 複雑な代入演算子内のdo式 | エラーメッセージを表示 |
| - | for-in初期化エラー | for-in文の変数初期化内のdo式 | 手動でコードを書き換える |
| - | 制御フローエスケープ | サポート外の制御フローパターン | IIFEでラップするか手動変換 |

### リトライ仕様

リトライ処理は不要（コンパイル時のエラーはリトライ対象外）

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

トランザクション管理は不要（ファイル変換処理のため）

## パフォーマンス要件

- 大規模コードベースでも数秒以内で変換完了すること
- 一時変数の生成を最小限に抑える

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

- ソースコード変換のため、実行時のセキュリティリスクは限定的
- 生成されるコードはオリジナルと同等のセキュリティ特性を持つ

## 備考

- TC39 Stage 1 提案
- async do式は別プラグイン（proposal-async-do-expressions）で処理
- 制御フロー文の処理は複雑で多くのエッジケースがある

---

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

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

### 推奨読解順序

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

do式の変換では、DoExpressionノードと制御フロー状態（ControlFlowVisitorState）が主要なデータ構造となる。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | utils.ts | `packages/babel-plugin-proposal-do-expressions/src/utils.ts` | ControlFlowVisitorState型定義、制御フロー収集関数 |

**読解のコツ**: `ControlFlowVisitorState`の`break`、`continue`、`returnPath`フィールドが制御フロー追跡の鍵。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/babel-plugin-proposal-do-expressions/src/index.ts` | DoExpressionのexitハンドラ |

**主要処理フロー**:
1. **18-23行目**: async do式のスキップ判定
2. **24-29行目**: 制御フロー文の収集と分岐
3. **32-37行目**: 通常ケースの変換（replaceExpressionWithStatements）

#### Step 3: 制御フロー変換処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts | `packages/babel-plugin-proposal-do-expressions/src/index.ts` | transformDoExpressionWithControlFlowStatements関数 |

**主要処理フロー**:
- **51-122行目**: 親要素を辿りながら変換対象を特定
- **124-278行目**: flattenStatement関数によるステートメント種別ごとの変換
- **280-425行目**: flattenExpression関数による式の変換

#### Step 4: ユーティリティ関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | utils.ts | `packages/babel-plugin-proposal-do-expressions/src/utils.ts` | collectControlFlowStatements、wrapDoExpressionInIIFE |

**主要処理フロー**:
- **47-55行目**: 制御フロー文を収集
- **57-82行目**: IIFEラップによるフォールバック処理

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

```
@babel/core (transform)
    │
    └─ @babel/plugin-proposal-do-expressions/src/index.ts
           │
           ├─ DoExpression.exit (visitor)
           │      │
           │      ├─ collectControlFlowStatements (utils.ts)
           │      │
           │      ├─ transformDoExpressionWithControlFlowStatements
           │      │      │
           │      │      ├─ flattenStatement
           │      │      │      └─ flattenExpression
           │      │      │             └─ flattenByTraverse
           │      │      │
           │      │      └─ flattenLVal
           │      │
           │      └─ replaceExpressionWithStatements (直接変換)
           │
           └─ wrapDoExpressionInIIFE (utils.ts) - フォールバック
```

### データフロー図

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

DoExpression              制御フロー分析                    変換後AST
do {                      ───▶
  if (cond) {                 flattenStatement              ステートメント展開
    return x;                 flattenExpression             または
  }                           完了記録処理                  IIFE
  y;
}
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-plugin-proposal-do-expressions/src/index.ts` | ソース | プラグインエントリーポイント、主要変換ロジック |
| utils.ts | `packages/babel-plugin-proposal-do-expressions/src/utils.ts` | ソース | 制御フロー収集、IIFEラップ |
| package.json | `packages/babel-plugin-proposal-do-expressions/package.json` | 設定 | パッケージ定義・依存関係 |
