# 機能設計書 59-@babel/plugin-transform-optional-catch-binding

## 概要

本ドキュメントは、Babelプラグイン `@babel/plugin-transform-optional-catch-binding` の機能設計を記載したものである。本プラグインは、ES2019で導入されたオプショナルcatchバインディング（catch句でのパラメータ省略）をES5互換のコードに変換する。

### 本機能の処理概要

**業務上の目的・背景**：ES2019より前のJavaScriptでは、`try-catch` 文の `catch` 句には必ずパラメータ（通常 `e` や `error`）を指定する必要があった。ES2019からは、エラーオブジェクトを使用しない場合にパラメータを省略できるようになった（`catch { }` の形式）。しかし、レガシー環境ではこの構文がサポートされていないため、トランスパイルが必要となる。本プラグインは、パラメータなしの `catch` 句に自動的にダミーパラメータを追加する。

**機能の利用シーン**：
- エラーオブジェクトを使用せず、エラー発生時の処理のみが必要な場合
- try-catchを単純なエラー抑制として使用する場合
- 未使用変数の警告を避けたい場合

**主要な処理内容**：
1. `CatchClause` ノードを検出
2. `param` が `null` または `undefined` かどうかを判定
3. パラメータがない場合、一意の識別子（例: `_unused`）を生成
4. 生成した識別子をcatch句のパラメータとして設定

**関連システム・外部連携**：`@babel/helper-plugin-utils` の `declare` 関数を使用してプラグインを宣言。

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

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

### 入力データソース

- Babelコアから渡されるAST（抽象構文木）
- `CatchClause` ノードが処理対象

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 変換後AST | AST Node | パラメータが追加されたcatch句 |

### 出力先

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

## 処理フロー

### 処理シーケンス

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

2. CatchClause Visitor
   └─ path.node.param をチェック
   └─ param が null/undefined の場合:
      └─ scope.generateUidIdentifier("unused") で一意の識別子生成
      └─ paramPath.replaceWith(uid) でパラメータを設定
```

### フローチャート

```mermaid
flowchart TD
    A[CatchClause検出] --> B{param がない?}
    B -->|No| Z[スキップ]
    B -->|Yes| C[一意の識別子を生成]
    C --> D[paramPath.replaceWith]
    D --> E[変換完了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | パラメータ追加 | パラメータなしのcatch句にダミーパラメータを追加 | param === null |
| BR-02 | 一意識別子 | スコープ内で一意の識別子を生成 | パラメータ追加時 |

### 計算ロジック

`scope.generateUidIdentifier("unused")` により、スコープ内で一意な識別子（`_unused`、`_unused2` など）を生成。

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | SyntaxError | 不正なtry-catch構文 | Babelコアがエラー報告 |

### リトライ仕様

該当なし

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

該当なし（ステートレスな変換処理）

## パフォーマンス要件

- 非常に軽量な変換処理
- 追加のランタイムヘルパーは不要

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

- 特になし

## 備考

- ES2019をネイティブサポートする環境ではこのプラグインは不要
- `@babel/preset-env` 使用時は、ターゲット環境に応じて自動的に適用される
- 最もシンプルなBabelプラグインの一つ（19行）

---

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

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

### 推奨読解順序

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

プラグイン全体が非常にシンプルなため、1ファイルで完結している。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/babel-plugin-transform-optional-catch-binding/src/index.ts` | プラグイン全体（19行） |

**主要処理フロー**:
1. **1行目**: `@babel/helper-plugin-utils` から `declare` をインポート
2. **3行目**: プラグイン宣言
3. **4行目**: Babelバージョン検証
4. **6-18行目**: プラグイン本体（CatchClause Visitor）
5. **10-11行目**: パラメータなしのチェック
6. **12行目**: 一意識別子の生成
7. **13-14行目**: パラメータの置換

#### Step 2: Visitorロジックの詳細

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/babel-plugin-transform-optional-catch-binding/src/index.ts` | CatchClause Visitor（10-16行目） |

**コード詳細**:
```typescript
CatchClause(path) {
  if (!path.node.param) {                        // パラメータがない場合
    const uid = path.scope.generateUidIdentifier("unused");  // _unused を生成
    const paramPath = path.get("param");         // param パスを取得
    paramPath.replaceWith(uid);                  // パラメータを設定
  }
}
```

**読解のコツ**:
- `path.node.param` は CatchClause の `param` プロパティ（例: `catch (e) {}` の `e`）
- `null` または `undefined` の場合、オプショナルcatchバインディングを使用している

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

```
@babel/plugin-transform-optional-catch-binding
    │
    └─ visitor.CatchClause(path)
           │
           ├─ path.node.param チェック
           │
           ├─ path.scope.generateUidIdentifier("unused")
           │      └─ 一意識別子生成
           │
           └─ paramPath.replaceWith(uid)
                  └─ ASTノード置換
```

### データフロー図

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

try {                  AST解析  ───▶  CatchClause Visitor  ───▶  try {
  // code                                    │                     // code
} catch {                                    │                   } catch (_unused) {
  // handle               generateUidIdentifier                    // handle
}                              │                                 }
                         replaceWith
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-plugin-transform-optional-catch-binding/src/index.ts` | ソース | プラグインエントリーポイント（全19行） |
| package.json | `packages/babel-plugin-transform-optional-catch-binding/package.json` | 設定 | パッケージ定義、依存関係 |
