# 機能設計書 56-@babel/plugin-transform-explicit-resource-management

## 概要

本ドキュメントは、Babelプラグイン `@babel/plugin-transform-explicit-resource-management` の機能設計を記載したものである。本プラグインは、TC39提案の明示的リソース管理（Explicit Resource Management）構文である `using` および `await using` 宣言をES2015互換のコードに変換する。

### 本機能の処理概要

**業務上の目的・背景**：明示的リソース管理（`using` 宣言）は、ファイルハンドル、データベース接続、ロックなどのリソースを確実にクリーンアップするための構文である。`using` で宣言されたリソースは、スコープを抜ける際に自動的に `[Symbol.dispose]()` メソッドが呼び出される。`await using` は非同期リソース用で、`[Symbol.asyncDispose]()` メソッドを呼び出す。この構文はTC39 Stage 3提案であり、レガシー環境でも利用するためにトランスパイルが必要となる。

**機能の利用シーン**：
- ファイルハンドルやストリームの自動クローズ
- データベース接続やトランザクションの自動解放
- ロックやセマフォの自動解放
- テンポラリリソースの確実なクリーンアップ

**主要な処理内容**：
1. `using` / `await using` 宣言を含むブロックを検出
2. for-of文内の `using` 宣言を処理（ループ変数を一時変数に置換）
3. ブロック内の `using` 宣言を `const` 宣言に変換
4. リソースを `usingCtx` ヘルパーでラップ
5. ブロック全体を try-catch-finally 構文で囲む
6. finally でリソースの dispose を呼び出す
7. モジュールレベルの `using` 宣言を処理（インポート/エクスポートのホイスト）

**関連システム・外部連携**：`@babel/plugin-transform-destructuring` の `unshiftForXStatementBody` 関数を使用。`@babel/helpers` の `usingCtx` ヘルパーを使用してリソース管理を行う。

**権限による制御**：本プラグインに権限制御の概念は存在しない。

## 関連画面

該当なし（CLIツール/ビルドツールとして動作）

## 機能種別

データ変換処理（ASTトランスフォーム）

## 入力仕様

### 入力パラメータ

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

### 入力データソース

- Babelコアから渡されるAST（抽象構文木）
- `VariableDeclaration`（kind: "using" または "await using"）ノードが処理対象

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 変換後AST | AST Node | try-catch-finally構文でラップされたブロック |

### 出力先

変換されたASTはBabelコアに返され、最終的にJavaScriptコードとして出力される

## 処理フロー

### 処理シーケンス

```
1. プラグイン初期化
   └─ Babelバージョン検証（^7.23.9 || ^8.0.0）

2. Program Visitor（モジュールレベル処理）
   └─ sourceType === "module" の場合のみ
   └─ using / await using 宣言を検出
   └─ インポート/エクスポートをホイスト
   └─ モジュール本体をブロックでラップ

3. Function Visitor（非同期関数処理）
   └─ async 関数内の await using を先に処理
   └─ async-to-generator 変換前に処理

4. ForOfStatement Visitor
   └─ for-of の変数が using の場合
   └─ ループ変数を一時変数に置換
   └─ ループ本体の先頭に using 宣言を挿入

5. BlockStatement / StaticBlock Visitor
   └─ using 宣言を検出
   └─ usingCtx ヘルパーを生成
   └─ 各 using 変数を ctx.u() / ctx.a() でラップ
   └─ ブロックを try-catch-finally でラップ
   └─ finally で ctx.d() を呼び出し
```

### フローチャート

```mermaid
flowchart TD
    A[AST検出] --> B{using/await using?}
    B -->|No| Z[スキップ]
    B -->|Yes| C{for-of内?}
    C -->|Yes| D[ループ変数を一時変数に]
    C -->|No| E{モジュールレベル?}
    D --> F[ループ本体にusing挿入]
    E -->|Yes| G[import/exportホイスト]
    E -->|No| H[ブロック処理]
    F --> H
    G --> H
    H --> I[usingCtx生成]
    I --> J[変数をctx.u/ctx.aでラップ]
    J --> K[try-catch-finallyでラップ]
    K --> L[変換完了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | using変換 | `using x = expr` を `const x = ctx.u(expr)` に変換 | using 宣言 |
| BR-02 | await using変換 | `await using x = expr` を `const x = ctx.a(expr)` に変換 | await using 宣言 |
| BR-03 | disposeラップ | ブロックを try-catch-finally でラップ | using 宣言を含むブロック |
| BR-04 | await dispose | await using の場合は `await ctx.d()` で解放 | await using 宣言 |
| BR-05 | 関数名設定 | 匿名関数/クラスに名前を設定 | 匿名関数定義をusingに代入 |
| BR-06 | for-ofサポート | for-of のループ変数をサポート | for (using x of ...) |

### 計算ロジック

`usingCtx` ヘルパーは以下のオブジェクトを返す：
- `u(value)`: 同期リソースを登録し、値をそのまま返す
- `a(value)`: 非同期リソースを登録し、値をそのまま返す
- `d()`: 登録されたすべてのリソースを逆順にdispose
- `e`: エラーを格納するプロパティ

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

該当なし（データベース操作は行わない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | SyntaxError | 不正な using 宣言 | Babelコアがエラー報告 |
| - | RuntimeError | リソースの dispose がエラー | finally 内でエラーをキャプチャ |

### リトライ仕様

該当なし

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

- finally ブロック内でリソースの dispose を呼び出し、確実にクリーンアップを行う
- エラー発生時も finally が実行される

## パフォーマンス要件

- 変換によるオーバーヘッドは最小限
- try-catch-finally の追加により若干のパフォーマンス影響

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

- dispose メソッドが確実に呼び出されることで、リソースリークを防止

## 備考

- TC39 Explicit Resource Management提案（Stage 3）をネイティブサポートする環境ではこのプラグインは不要
- Babel 7.23.9以降が必要（usingCtxヘルパーサポート）
- `@babel/plugin-transform-destructuring` と連携してfor-of内のusing宣言を処理

---

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

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

### 推奨読解順序

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

using宣言の種類を示す列挙型を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/babel-plugin-transform-explicit-resource-management/src/index.ts` | USING_KIND列挙型（NORMAL=0, AWAIT=1）を確認 |

**読解のコツ**: `TOP_LEVEL_USING` Mapはモジュールレベルのusing宣言を追跡するために使用される。

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

プラグインの初期化と各Visitorの役割を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/babel-plugin-transform-explicit-resource-management/src/index.ts` | プラグイン全体構造（35-255行目） |

**主要処理フロー**:
1. **35-37行目**: Babelバージョン検証
2. **39行目**: TOP_LEVEL_USING Mapの初期化
3. **41-48行目**: isUsingDeclaration ヘルパー関数
4. **50-145行目**: transformUsingDeclarationsVisitor（メイン変換ロジック）
5. **147-254行目**: 各Visitorの定義（Program, Function, ForOfStatement, BlockStatement）

#### Step 3: ブロック変換ロジックを理解する

using宣言を含むブロックの変換処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts | `packages/babel-plugin-transform-explicit-resource-management/src/index.ts` | BlockStatement/StaticBlock Visitor（67-134行目） |

**主要処理フロー**:
- **71-73行目**: usingCtx識別子の生成
- **78-80行目**: await using の判定
- **83-100行目**: using宣言をconst宣言に変換、ctx.u()/ctx.a()でラップ
- **104-107行目**: disposeCall の生成
- **109-118行目**: try-catch-finally テンプレートの生成
- **120-133行目**: 親要素に応じた置換処理

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

```
@babel/plugin-transform-explicit-resource-management
    │
    ├─ visitor.Program()
    │      └─ モジュールレベルusing処理
    │             └─ import/exportホイスト
    │             └─ ブロック生成
    │
    ├─ visitor.Function()
    │      └─ async関数内のawait using事前処理
    │
    ├─ transformUsingDeclarationsVisitor
    │      │
    │      ├─ ForOfStatement()
    │      │      └─ ループ変数の一時変数置換
    │      │      └─ unshiftForXStatementBody()
    │      │
    │      └─ BlockStatement/StaticBlock()
    │             └─ usingCtx生成
    │             └─ using → const + ctx.u/a() 変換
    │             └─ try-catch-finally ラップ
    │             └─ finally: ctx.d() 呼び出し
    │
    └─ helpers
           └─ usingCtx: リソース管理ヘルパー
           └─ setFunctionName: 匿名関数名設定
```

### データフロー図

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

using x = resource;   ───▶  AST解析  ───▶  Visitor  ───▶  try {
                                             │               var _usingCtx = _usingCtx();
                                             │               const x = _usingCtx.u(resource);
                                             │               // 元のコード
                                             │             } catch (_) {
                                             │               _usingCtx.e = _;
                                             │             } finally {
                                             │               _usingCtx.d();
                                             │             }
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-plugin-transform-explicit-resource-management/src/index.ts` | ソース | プラグインエントリーポイント、変換ロジック |
| package.json | `packages/babel-plugin-transform-explicit-resource-management/package.json` | 設定 | パッケージ定義、依存関係 |
| index.ts | `packages/babel-plugin-transform-destructuring/src/index.ts` | ソース | unshiftForXStatementBody関数を提供 |
