# 機能設計書 77-@babel/helper-create-class-features-plugin

## 概要

本ドキュメントは、@babel/helper-create-class-features-pluginの機能設計について記載する。このパッケージは、クラス機能（プロパティ、プライベートメソッド、デコレータ等）の変換プラグインを作成するためのヘルパーモジュールである。

### 本機能の処理概要

**業務上の目的・背景**：ES6以降のクラス構文には、クラスフィールド、プライベートフィールド/メソッド、静的ブロック、デコレータなど多くの機能が追加されている。これらの機能を古い環境向けに変換するプラグインは複雑なロジックを共有する必要がある。本パッケージは、クラス機能変換の共通ロジックを提供し、@babel/plugin-transform-class-properties、@babel/plugin-transform-private-methods、@babel/plugin-proposal-decoratorsなどのプラグインで再利用される。

**機能の利用シーン**：クラスプロパティ、プライベートメソッド、静的ブロック、デコレータなどのクラス機能を変換するプラグインを開発/実行する際に使用される。これらのプラグインはすべてこのヘルパーを通じて一貫した変換ロジックを実装する。

**主要な処理内容**：
1. クラス機能フラグの管理（fields、privateMethods、decorators、privateIn、staticBlocks）
2. プライベート名のマップ構築と参照変換
3. フィールド初期化ノードの生成
4. コンストラクタへの初期化コード注入
5. 計算プロパティキーの抽出
6. デコレータ変換の委譲

**関連システム・外部連携**：@babel/core、@babel/types、semverと連携する。

**権限による制御**：権限による実行制御は行わない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | クラス機能変換プラグインから内部利用 |

## 機能種別

プラグインファクトリ / クラス変換 / AST操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | string | Yes | プラグイン名 | - |
| feature | number | Yes | 機能フラグ（FEATURES定数） | FEATURES値のいずれか |
| loose | boolean | No | ルーズモード | - |
| manipulateOptions | function | No | パーサーオプション操作 | - |
| api | PluginAPI | Yes | Babel API オブジェクト | - |
| inherits | PluginObject["inherits"] | No | 継承プラグイン | - |

### 入力データソース

各クラス機能変換プラグインからの呼び出し

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| PluginObject | object | Babelプラグインオブジェクト |

### 出力先

@babel/coreのプラグインシステムに対して返却

## 処理フロー

### 処理シーケンス

```
1. createClassFeaturePlugin呼び出し
   ├─ デコレータ機能の場合→createDecoratorTransformに委譲
   └─ その他の機能→通常フロー
2. assumption取得
   ├─ setPublicClassFields
   ├─ privateFieldsAsSymbols
   ├─ privateFieldsAsProperties
   ├─ noUninitializedPrivateFieldAccess
   └─ constantSuper
3. PluginObject生成
   ├─ pre: 機能フラグ有効化、バージョン設定
   └─ visitor: Class訪問者定義
4. Class訪問者実行
   ├─ shouldTransform判定
   ├─ プライベート名の重複チェック
   ├─ プライベート名マップ構築
   ├─ プライベート参照変換
   ├─ 計算キー抽出
   ├─ フィールド初期化ノード生成
   └─ コンストラクタへの注入
```

### フローチャート

```mermaid
flowchart TD
    A[createClassFeaturePlugin] --> B{feature=decorators?}
    B -->|Yes| C[createDecoratorTransform]
    B -->|No| D[assumption取得]
    D --> E[PluginObject生成]
    E --> F[pre: enableFeature]
    F --> G[visitor: Class]
    G --> H{shouldTransform?}
    H -->|No| I[スキップ]
    H -->|Yes| J[プライベート名重複チェック]
    J --> K[buildPrivateNamesMap]
    K --> L[buildPrivateNamesNodes]
    L --> M[transformPrivateNamesUsage]
    M --> N[extractComputedKeys]
    N --> O[buildFieldsInitNodes]
    O --> P[injectInitialization]
    P --> Q[wrapClass]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-77-01 | looseモード一貫性 | class-properties、private-methods、private-property-in-objectは同じloose設定が必要 | 複数プラグイン使用時 |
| BR-77-02 | プライベート名重複禁止 | 同名のプライベートフィールド/メソッドは禁止 | プライベートメンバー定義時 |
| BR-77-03 | バージョン管理 | 複数プラグイン使用時は最新バージョンのみ変換実行 | 常時 |
| BR-77-04 | デコレータ優先順序 | デコレータはclass-propertiesより前に指定必須（legacy） | デコレータ使用時 |
| BR-77-05 | TypeScript declare除外 | TypeScriptのdeclareプロパティは変換対象外 | TypeScript使用時 |

### 計算ロジック

**FEATURES定数**：
```
fields = 1 << 1 (2)
privateMethods = 1 << 2 (4)
decorators = 1 << 3 (8)
privateIn = 1 << 4 (16)
staticBlocks = 1 << 5 (32)
```

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

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

データベース操作なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | looseモード不一致 | 関連プラグインでloose設定が異なる | 統一した設定を使用 |
| - | プライベート重複 | 同名のプライベートメンバー | 名前を変更 |
| - | デコレータ未有効 | デコレータ構文があるがプラグイン未設定 | デコレータプラグイン追加 |
| - | プライベートメソッド未有効 | プライベートメソッドがあるがプラグイン未設定 | private-methodsプラグイン追加 |

### リトライ仕様

リトライ対象外

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

トランザクション処理なし

## パフォーマンス要件

- バージョンチェックで不要な変換をスキップ
- 同一ファイル内で最新バージョンのみ処理

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

特になし

## 備考

- privateFieldsAsSymbolsとprivateFieldsAsPropertiesは同時使用不可
- 2023-11デコレータはcreateDecoratorTransformに完全委譲
- BABEL_SHOW_CONFIG_FOR環境変数でデバッグ可能

---

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

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

### 推奨読解順序

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

まず、機能フラグとオプション型を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | features.ts | `packages/babel-helper-create-class-features-plugin/src/features.ts` | FEATURES定数の定義（5-12行目） |
| 1-2 | index.ts | `packages/babel-helper-create-class-features-plugin/src/index.ts` | Options型の定義（38-46行目） |

**読解のコツ**: FEATURESはビットフラグで、複数の機能を組み合わせられる。fields、privateMethods、decorators等の各ビット位置を理解する。

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

メインのcreateClassFeaturePlugin関数を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/babel-helper-create-class-features-plugin/src/index.ts` | createClassFeaturePlugin関数（48-288行目） |

**主要処理フロー**:
1. **56-58行目**: デコレータ機能の場合はcreateDecoratorTransformに委譲
2. **60-66行目**: assumptionの取得（setPublicClassFields等）
3. **68-73行目**: privateFieldsAsSymbolsとprivateFieldsAsPropertiesの排他チェック
4. **106-119行目**: pre関数でenableFeatureを呼び出し
5. **121-285行目**: visitor.Classでクラス変換を実行

#### Step 3: 機能管理を理解する

機能フラグの有効化と判定ロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | features.ts | `packages/babel-helper-create-class-features-plugin/src/features.ts` | enableFeature関数（30-61行目） |
| 3-2 | features.ts | `packages/babel-helper-create-class-features-plugin/src/features.ts` | shouldTransform関数（90-184行目） |

**主要処理フロー**:
- **30-61行目**: enableFeature - 機能フラグをファイルに設定、looseモード一貫性チェック
- **90-184行目**: shouldTransform - クラスに変換が必要かどうかを判定

#### Step 4: フィールド変換を理解する

フィールド初期化とプライベート名処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | fields.ts | `packages/babel-helper-create-class-features-plugin/src/fields.ts` | buildPrivateNamesMap、buildFieldsInitNodes関数 |
| 4-2 | misc.ts | `packages/babel-helper-create-class-features-plugin/src/misc.ts` | injectInitialization関数 |

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

```
@babel/helper-create-class-features-plugin/src/index.ts
    │
    ├─ createClassFeaturePlugin()
    │      │
    │      ├─ (decorators) → createDecoratorTransform()
    │      │
    │      └─ (other features)
    │             ├─ pre()
    │             │      └─ enableFeature()
    │             │
    │             └─ visitor.Class()
    │                    ├─ shouldTransform()
    │                    ├─ buildPrivateNamesMap()
    │                    ├─ buildPrivateNamesNodes()
    │                    ├─ transformPrivateNamesUsage()
    │                    ├─ extractComputedKeys()
    │                    ├─ buildFieldsInitNodes()
    │                    ├─ injectInitialization()
    │                    └─ wrapClass()
    │
    └─ エクスポート
           ├─ FEATURES
           ├─ enableFeature
           ├─ injectInitialization
           └─ buildCheckInRHS
```

### データフロー図

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

Options ───▶ createClassFeaturePlugin()
  - name                         │
  - feature                      ├─ デコレータ分岐
  - loose                        │
  - api                          ▼
                           PluginObject生成
                                 │
                                 ▼
                           Class訪問者
                                 │
      ┌──────────────────────────┼──────────────────────────┐
      ▼                          ▼                          ▼
shouldTransform          buildPrivateNamesMap      buildFieldsInitNodes
      │                          │                          │
      └──────────────────────────┼──────────────────────────┘
                                 ▼
                          injectInitialization
                                 │
                                 ▼
                          変換済みAST
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-helper-create-class-features-plugin/src/index.ts` | ソース | メインエントリーポイント |
| features.ts | `packages/babel-helper-create-class-features-plugin/src/features.ts` | ソース | 機能フラグ管理 |
| fields.ts | `packages/babel-helper-create-class-features-plugin/src/fields.ts` | ソース | フィールド変換ロジック |
| decorators.ts | `packages/babel-helper-create-class-features-plugin/src/decorators.ts` | ソース | デコレータ変換 |
| misc.ts | `packages/babel-helper-create-class-features-plugin/src/misc.ts` | ソース | 共通ユーティリティ |
| typescript.ts | `packages/babel-helper-create-class-features-plugin/src/typescript.ts` | ソース | TypeScript対応 |
