# 機能設計書 44-@babel/plugin-transform-typescript

## 概要

本ドキュメントは、BabelプラグインであるTypeScriptコードのJavaScriptへの変換機能について記述する。

### 本機能の処理概要

**業務上の目的・背景**：
TypeScriptは静的型付けを提供するJavaScriptのスーパーセットであり、大規模アプリケーション開発で広く採用されている。しかし、ブラウザやNode.jsは直接TypeScriptを実行できないため、JavaScriptへのトランスパイルが必要となる。本プラグインは、TypeScriptの型アノテーションを削除し、TypeScript固有の構文（enum、namespace、parameterプロパティ等）をJavaScriptに変換することで、実行可能なコードを生成する。

**機能の利用シーン**：
- TypeScriptプロジェクトでのBabelベースのビルドパイプライン構築
- 型チェックをtsc（TypeScriptコンパイラ）に任せ、トランスパイルをBabelで行う分離アーキテクチャ
- @babel/preset-typescriptを通じた利用
- Reactプロジェクト等でのTSX（TypeScript + JSX）サポート

**主要な処理内容**：
1. 型アノテーション（type annotations）の削除
2. インターフェース定義（interface）の削除
3. 型エイリアス（type alias）の削除
4. 列挙型（enum）のJavaScript関数への変換
5. 名前空間（namespace）のIIFEへの変換
6. パラメータプロパティの初期化コード生成
7. const enum の最適化（optimizeConstEnums オプション）
8. 型のみのインポート/エクスポートの削除

**関連システム・外部連携**：
@babel/plugin-syntax-typescriptで構文解析を継承。@babel/helper-create-class-features-pluginでクラスメンバー初期化を処理。

**権限による制御**：
プラグインオプションによる動作制御（allowNamespaces、jsxPragma、onlyRemoveTypeImports、optimizeConstEnums等）。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本機能はCLI/APIから利用されるプラグインのため、直接の画面関連なし |

## 機能種別

データ変換（AST変換）/ 型削除

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| allowNamespaces | boolean | No | 名前空間の変換を許可（デフォルト: true） | - |
| jsxPragma | string | No | JSX変換関数（デフォルト: "React.createElement"） | - |
| jsxPragmaFrag | string | No | JSXフラグメント変換関数（デフォルト: "React.Fragment"） | - |
| onlyRemoveTypeImports | boolean | No | 型のみのインポートだけを削除 | - |
| optimizeConstEnums | boolean | No | const enumをインライン化 | - |
| allowDeclareFields | boolean | No | declareフィールドの許可 | - |

### 入力データソース

TypeScript/TSXソースコード（AST形式）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| transformedAST | t.Program | JavaScript形式に変換されたAST |

### 出力先

変換されたAST（@babel/coreに返却）

## 処理フロー

### 処理シーケンス

```
1. Program.enterビジター
   └─ GLOBAL_TYPESの初期化
   └─ JSXプラグマコメントの解析
   └─ 型のみインポートの削除
   └─ グローバル型の登録
2. 各種型ノードビジター
   └─ TSInterfaceDeclaration: 削除
   └─ TSTypeAliasDeclaration: 削除
   └─ TSDeclareFunction: 削除
   └─ TSIndexSignature: 削除
3. Classビジター
   └─ typeParameters削除
   └─ implements削除
   └─ パラメータプロパティの処理
4. Functionビジター
   └─ typeParameters削除
   └─ returnType削除
   └─ thisパラメータ削除
5. TSEnumDeclaration
   └─ enumをJavaScript関数に変換
6. TSModuleDeclaration
   └─ namespaceをIIFEに変換
7. Program.exit
   └─ 空エクスポートの追加（ESM維持用）
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Program.enter]
    B --> C[GLOBAL_TYPES初期化]
    C --> D[JSXプラグマ解析]
    D --> E[型のみインポート削除]
    E --> F{各ノードタイプ}
    F -->|Interface| G[削除]
    F -->|TypeAlias| H[削除]
    F -->|Enum| I{const enum?}
    I -->|Yes & optimize| J[インライン化]
    I -->|No| K[IIFE変換]
    F -->|Namespace| L[IIFE変換]
    F -->|Class| M[型情報削除]
    M --> N[パラメータプロパティ処理]
    F -->|Function| O[型情報削除]
    G --> P[Program.exit]
    H --> P
    J --> P
    K --> P
    L --> P
    N --> P
    O --> P
    P --> Q{ESMマーク必要?}
    Q -->|Yes| R[空エクスポート追加]
    Q -->|No| S[終了]
    R --> S
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-44-01 | 型アノテーション削除 | すべての型アノテーションを削除 | 常時 |
| BR-44-02 | インターフェース削除 | interface宣言を完全に削除 | interface検出時 |
| BR-44-03 | enum変換 | enumをIIFE形式のJavaScriptに変換 | enum検出時 |
| BR-44-04 | const enum最適化 | const enumを使用箇所でインライン化 | optimizeConstEnums=true時 |
| BR-44-05 | namespace変換 | namespaceをIIFE形式に変換 | allowNamespaces=true時 |
| BR-44-06 | パラメータプロパティ | constructorのパラメータプロパティをthis代入に変換 | TSParameterProperty検出時 |
| BR-44-07 | 型インポート削除 | 型のみのインポートを削除 | import type検出時 |
| BR-44-08 | ESM維持 | 値のエクスポートがない場合、空のエクスポートを追加 | sourceType="module"時 |

### 計算ロジック

enum変換ロジック:
```javascript
// 入力: enum Direction { Up, Down }
// 出力:
var Direction;
(function(Direction) {
  Direction[Direction["Up"] = 0] = "Up";
  Direction[Direction["Down"] = 1] = "Down";
})(Direction || (Direction = {}));
```

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

該当なし（ファイルシステム操作のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| CJS_TRANSFORM_REQUIRED | 設定エラー | import = require使用時にCommonJS変換未設定 | @babel/plugin-transform-modules-commonjsを追加 |
| DESTRUCTURING_PARAM_PROPERTY | 構文エラー | パラメータプロパティで分割代入使用 | パラメータ構文を修正 |
| DECLARE_FIELD_INITIALIZER | 構文エラー | declareフィールドに初期値設定 | 初期値を削除またはコンストラクタに移動 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

特定のパフォーマンス要件なし（変換処理は同期的に実行）

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

- 型情報は実行時には削除されるため、型による実行時チェックは行われない
- enum値の初期化式内のコードは保持されるため、副作用に注意

## 備考

- 本プラグインは型チェックを行わない（型チェックはtscに委譲）
- JSX対応にはjsxPragma/jsxPragmaFragオプションまたは@jsxプラグマコメントを使用
- TypeScript 3.8以降の型のみインポート（import type）をネイティブサポート

---

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

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

### 推奨読解順序

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

まず、プラグインのオプション型定義と内部状態を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/babel-plugin-transform-typescript/src/index.ts` | Options型（80-90行目） |
| 1-2 | global-types.ts | `packages/babel-plugin-transform-typescript/src/global-types.ts` | GLOBAL_TYPESの管理 |

**読解のコツ**: `NEEDS_EXPLICIT_ESM`WeakMapは、ESMとして認識されるべきファイルを追跡するために使用される。

#### Step 2: メインプラグイン構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/babel-plugin-transform-typescript/src/index.ts` | declare関数によるプラグイン定義（100行目〜） |

**主要処理フロー**:
- **100-115行目**: オプション取得とデフォルト値設定
- **117-204行目**: classMemberVisitors定義（フィールド、メソッド、コンストラクタ）
- **206-678行目**: メインビジター定義

#### Step 3: クラスメンバー処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts | `packages/babel-plugin-transform-typescript/src/index.ts` | classMemberVisitors（117-204行目） |

**主要処理フロー**:
- **118-153行目**: field処理（declare、abstract、accessibility等の削除）
- **154-161行目**: method処理（accessibility、abstract等の削除）
- **162-203行目**: constructor処理（TSParameterPropertyの変換）

#### Step 4: enum変換を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | enum.ts | `packages/babel-plugin-transform-typescript/src/enum.ts` | transpileEnum関数 |
| 4-2 | const-enum.ts | `packages/babel-plugin-transform-typescript/src/const-enum.ts` | transpileConstEnum関数 |

#### Step 5: namespace変換を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | namespace.ts | `packages/babel-plugin-transform-typescript/src/namespace.ts` | transpileNamespace関数 |

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

```
@babel/plugin-transform-typescript/src/index.ts
    │
    ├─ @babel/plugin-syntax-typescript (inherits)
    │      └─ TypeScript構文解析の有効化
    │
    ├─ @babel/helper-create-class-features-plugin
    │      └─ injectInitialization()
    │
    ├─ ./enum.ts
    │      └─ transpileEnum()
    │
    ├─ ./const-enum.ts
    │      └─ transpileConstEnum()
    │
    ├─ ./namespace.ts
    │      └─ transpileNamespace()
    │
    └─ ./global-types.ts
           ├─ GLOBAL_TYPES
           ├─ isGlobalType()
           └─ registerGlobalType()
```

### データフロー図

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

TypeScriptソース  ──▶  Parser (TS AST生成)
                              │
                     ┌────────┼────────┐
                     ▼        ▼        ▼
               型削除    enum変換   namespace変換
                     │        │        │
                     └────────┼────────┘
                              │
                              ▼
                    パラメータプロパティ変換
                              │
                              ▼
                       JavaScriptAST ──▶ Generator ──▶ JSコード
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-plugin-transform-typescript/src/index.ts` | ソース | メインプラグイン実装（735行） |
| enum.ts | `packages/babel-plugin-transform-typescript/src/enum.ts` | ソース | enum変換処理 |
| const-enum.ts | `packages/babel-plugin-transform-typescript/src/const-enum.ts` | ソース | const enum最適化 |
| namespace.ts | `packages/babel-plugin-transform-typescript/src/namespace.ts` | ソース | namespace変換処理 |
| global-types.ts | `packages/babel-plugin-transform-typescript/src/global-types.ts` | ソース | グローバル型管理 |
| package.json | `packages/babel-plugin-transform-typescript/package.json` | 設定 | 依存関係・メタデータ |
