# 機能設計書 58-@babel/plugin-transform-class-static-block

## 概要

本ドキュメントは、Babelプラグイン `@babel/plugin-transform-class-static-block` の機能設計を記載したものである。本プラグインは、ES2022で導入されたクラス静的初期化ブロック（`static { }` 構文）を、従来のJavaScriptコードに変換する。

### 本機能の処理概要

**業務上の目的・背景**：クラス静的初期化ブロック（Class Static Block）は、クラスの静的メンバーの初期化時に複雑なロジックを実行するための構文である。`static { /* 初期化コード */ }` の形式で、クラス定義内に静的な初期化コードを記述できる。この構文はES2022で標準化されたが、レガシー環境でも利用するためにトランスパイルが必要となる。

**機能の利用シーン**：
- 静的プロパティの複雑な初期化（条件分岐、ループなど）
- 静的プロパティ間の依存関係がある初期化
- プライベート静的フィールドへのアクセスが必要な初期化
- 静的フィールドの初期化時に副作用が必要な場合

**主要な処理内容**：
1. `ClassBody` 内の `StaticBlock` ノードを検出
2. 静的ブロックを静的プロパティの初期化式に変換
3. 後続の静的プロパティがない場合は、プライベートプロパティを追加してそこに初期化式を配置
4. クラス式の場合は、クラス定義後に初期化関数を呼び出す
5. 匿名クラスの場合は、`setFunctionName` ヘルパーで名前を設定

**関連システム・外部連携**：`@babel/helper-create-class-features-plugin` を使用してクラス機能の変換を支援。静的ブロックの有効化と名前付き評価を担当。

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

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

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 変換後AST | AST Node | 静的ブロックが静的プロパティ初期化式に変換されたクラス |

### 出力先

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

## 処理フロー

### 処理シーケンス

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

2. pre フック
   └─ staticBlocks 機能を有効化（@babel/helper-create-class-features-plugin）

3. ClassBody Visitor
   └─ 匿名クラス式の名前付け処理
   └─ 静的ブロックの収集

4. 静的ブロック処理
   └─ 静的ブロックを式に変換
   └─ 後続の静的プロパティがある場合：初期化式に追加
   └─ ない場合：プライベートプロパティを追加、クラス後に呼び出し

5. クラス式のシーケンス処理
   └─ クラス定義後に初期化関数を呼び出す
```

### フローチャート

```mermaid
flowchart TD
    A[ClassBody検出] --> B[静的ブロックを収集]
    B --> C{後続の静的プロパティ?}
    C -->|Yes| D[初期化式に追加]
    C -->|No| E[プライベートプロパティ追加]
    D --> F[次の静的ブロックへ]
    E --> G{クラス式?}
    G -->|Yes| H[シーケンス式で呼び出し]
    G -->|No| I[クラス後に式ステートメント挿入]
    H --> J[変換完了]
    I --> J
    F --> C
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 静的ブロック変換 | static {}を式に変換 | 静的ブロック存在時 |
| BR-02 | 単一式最適化 | 単一のExpressionStatementはIIFEなしで変換 | 本体が単一式の場合 |
| BR-03 | プライベートプロパティ生成 | 後続静的プロパティがない場合、一意なプライベートプロパティを生成 | 静的ブロックが末尾 |
| BR-04 | クラス式処理 | クラス式の場合、シーケンス式で初期化関数呼び出し | クラス式 |
| BR-05 | 名前設定 | 匿名クラスに名前を設定 | 静的ブロックがある匿名クラス |

### 計算ロジック

静的ブロックの変換方法：
- 単一のExpressionStatement: そのまま式として使用
- 複数の文または非Expression: `(() => { ... })()` でラップ

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

該当なし

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

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

## パフォーマンス要件

- 単一式の場合はIIFEを避けて最適化
- 静的プロパティの初期化順序を維持

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

- 特になし

## 備考

- ES2022をネイティブサポートする環境ではこのプラグインは不要
- `@babel/preset-env` 使用時は、ターゲット環境に応じて自動的に適用される
- `@babel/helper-create-class-features-plugin` と連携して、プライベートフィールド変換との互換性を確保

---

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

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

### 推奨読解順序

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

クラス機能プラグインで使用される機能フラグを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/babel-plugin-transform-class-static-block/src/index.ts` | enableFeature, FEATURES のインポート（4-8行目） |

**読解のコツ**: `FEATURES.staticBlocks` フラグを有効化することで、`@babel/helper-create-class-features-plugin` との連携が可能になる。

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

プラグインの初期化と各ヘルパー関数を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/babel-plugin-transform-class-static-block/src/index.ts` | プラグイン全体構造（34-241行目） |

**主要処理フロー**:
1. **17-27行目**: generateUid関数（一意なプライベートプロパティ名生成）
2. **29-32行目**: mapLast関数（配列の最後の要素を変換）
3. **34-35行目**: プラグイン宣言、Babelバージョン検証
4. **37-66行目**: rawNamedEvaluationVisitor（匿名クラスの名前設定）
5. **72-80行目**: maybeSequenceExpression（式の配列をシーケンス式に）
6. **82-97行目**: blocksToExpressions（静的ブロックを式に変換）
7. **99-108行目**: prependToInitializer（初期化式に式を追加）

#### Step 3: ClassBody Visitorを理解する

静的ブロックの検出と変換処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts | `packages/babel-plugin-transform-class-static-block/src/index.ts` | ClassBody Visitor（123-239行目） |

**主要処理フロー**:
- **113-117行目**: pre フックでstaticBlocks機能を有効化
- **127-140行目**: 匿名クラス式の名前付け処理
- **142-146行目**: pendingStaticBlocks配列の初期化
- **148-169行目**: 静的ブロックと静的プロパティの走査
- **171-220行目**: 残りの静的ブロックの処理
- **222-237行目**: クラス式/宣言に応じた呼び出し挿入

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

```
@babel/plugin-transform-class-static-block
    │
    ├─ pre()
    │      └─ enableFeature(file, FEATURES.staticBlocks, false)
    │
    └─ visitor.ClassBody()
           │
           ├─ namedEvaluationVisitor
           │      └─ 匿名クラスの名前設定
           │
           ├─ StaticBlock検出
           │      └─ pendingStaticBlocks に収集
           │
           ├─ 静的プロパティ検出
           │      └─ prependToInitializer()
           │             └─ blocksToExpressions()
           │
           └─ 残りの静的ブロック処理
                  │
                  ├─ プライベートプロパティ生成
                  │      └─ generateUid()
                  │
                  └─ 呼び出し挿入
                         ├─ クラス式: sequenceExpression
                         └─ クラス宣言: insertAfter
```

### データフロー図

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

class C {              AST解析  ───▶  ClassBody Visitor  ───▶  class C {
  static x = 1;                              │                    static x = 1;
  static {                                   │                    static #_ =
    console.log();          blocksToExpressions                     (() => console.log())();
  }                                          │                  }
}                                      prependToInitializer
                                       または
                                       insertAfter
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-plugin-transform-class-static-block/src/index.ts` | ソース | プラグインエントリーポイント |
| package.json | `packages/babel-plugin-transform-class-static-block/package.json` | 設定 | パッケージ定義、依存関係 |
| index.ts | `packages/babel-helper-create-class-features-plugin/src/index.ts` | ソース | クラス機能プラグインヘルパー |
