# 機能設計書 41-@babel/plugin-transform-modules-amd

## 概要

本ドキュメントは、BabelプラグインであるES2015モジュールからAMD（Asynchronous Module Definition）形式への変換機能について記述する。

### 本機能の処理概要

**業務上の目的・背景**：
ES2015（ES6）で導入されたモジュール構文（import/export）は、すべてのJavaScript実行環境でネイティブにサポートされているわけではない。特にRequireJSなどのモジュールローダーを使用するレガシー環境では、AMD形式のモジュールが必要とされる。本プラグインは、ES2015モジュール構文をAMD形式に変換することで、これらの環境との互換性を確保する重要な役割を担う。

**機能の利用シーン**：
- RequireJSを使用したモジュール管理を行うプロジェクトでの利用
- ブラウザ環境でネイティブESモジュールがサポートされていない場合の代替手段
- 非同期モジュールローディングが必要なアプリケーション開発時

**主要な処理内容**：
1. ES2015のimport/export文をAMDのdefine関数呼び出しに変換
2. 動的インポート（dynamic import）をAMD互換のPromiseベース非同期ロードに変換
3. モジュール間の相互運用性（interop）を処理するためのラッパー関数生成
4. 名前空間インポートやデフォルトエクスポートの適切な処理

**関連システム・外部連携**：
@babel/helper-module-transformsと連携してモジュール変換処理を実行。@babel/coreのテンプレート機能を使用してAMDラッパーコードを生成する。

**権限による制御**：
プラグインオプションによる動作制御が可能（strict、loose、noInteropなど）。

## 関連画面

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

## 機能種別

データ変換（AST変換）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| allowTopLevelThis | boolean | No | トップレベルのthisをundefinedに変換しない | - |
| importInterop | string/function | No | インポートの相互運用モードを指定 | 'babel'/'node'/関数 |
| loose | boolean | No | 緩やかな変換モードを有効化 | - |
| noInterop | boolean | No | 相互運用ヘルパーを無効化 | - |
| strict | boolean | No | strictモードを強制 | - |
| strictMode | boolean | No | 'use strict'を挿入 | - |

### 入力データソース

ES2015モジュール構文を含むJavaScriptソースコード（AST形式）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| transformedAST | t.Program | AMD形式に変換されたAST |
| define | t.CallExpression | AMDのdefine関数呼び出し |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. プラグイン初期化（pre）
   └─ ファイルメタデータにモジュールタイプ'amd'を設定
2. CallExpression/ImportExpressionビジター
   └─ 動的インポートをPromiseベースのrequire呼び出しに変換
3. Program.exitビジター
   └─ ESモジュールかどうかを判定
   └─ モジュールヘッダーを準備
   └─ AMD依存関係配列を構築
   └─ define関数ラッパーを注入
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{ESモジュールか?}
    B -->|No| C{動的importあり?}
    C -->|Yes| D[匿名AMDラッパー注入]
    C -->|No| E[処理終了]
    B -->|Yes| F[モジュールヘッダー準備]
    F --> G[AMD引数配列構築]
    G --> H[インポート処理]
    H --> I[エクスポート処理]
    I --> J[interopラッパー適用]
    J --> K[define関数でラップ]
    K --> L[終了]
    D --> L
    E --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-41-01 | AMD形式変換 | import/exportをdefine関数に変換 | ESモジュール構文検出時 |
| BR-41-02 | 動的インポート変換 | import()をPromiseベースrequireに変換 | 動的import検出時 |
| BR-41-03 | 相互運用処理 | CommonJS/AMDモジュールとの互換性確保 | noInterop=false時 |

### 計算ロジック

特になし（構文変換のみ）

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| INVALID_VERSION | バージョンエラー | Babel 7未満で使用 | Babelバージョンを更新 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

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

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

- strictモードオプションにより、安全なコード生成を保証
- interop処理により、外部モジュールとの安全な連携を実現

## 備考

- 本プラグインは@babel/preset-envから自動的に利用される場合がある
- RequireJS環境でのデバッグ時にはソースマップの利用を推奨

---

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

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

### 推奨読解順序

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

まず、プラグインのオプション型定義とステート型を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/babel-plugin-transform-modules-amd/src/index.ts` | Options型（48-55行目）とState型（57-61行目）を確認 |

**読解のコツ**: `PluginOptions`型は@babel/helper-module-transformsから継承されており、モジュール変換プラグイン共通のオプションを含む。

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

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

**主要処理フロー**:
1. **63-73行目**: プラグイン初期化、オプション取得
2. **74-79行目**: プラグイン名設定とpre処理
3. **81-124行目**: CallExpression/ImportExpressionビジター（動的import処理）
4. **125-215行目**: Program.exitビジター（メイン変換処理）

#### Step 3: AMDラッパー生成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts | `packages/babel-plugin-transform-modules-amd/src/index.ts` | buildWrapperテンプレート（18-26行目） |

**主要処理フロー**:
- **18-21行目**: 名前付きモジュール用テンプレート
- **23-26行目**: 匿名モジュール用テンプレート（動的import専用）
- **28-46行目**: injectWrapper関数でラッパーを挿入

#### Step 4: モジュール変換ヘルパーを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | helper-module-transforms | `packages/babel-helper-module-transforms/src/index.ts` | rewriteModuleStatementsAndPrepareHeader関数 |

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

```
@babel/plugin-transform-modules-amd/src/index.ts
    │
    ├─ @babel/helper-plugin-utils/declare()
    │      └─ プラグイン定義の標準化
    │
    ├─ @babel/helper-module-transforms
    │      ├─ rewriteModuleStatementsAndPrepareHeader()
    │      ├─ buildDynamicImport()
    │      ├─ wrapInterop()
    │      └─ buildNamespaceInitStatements()
    │
    └─ @babel/core/template
           └─ buildWrapper / buildAnonymousWrapper
```

### データフロー図

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

ESModuleソースコード  ──▶  Parser (AST生成)
                              │
                              ▼
                      rewriteModuleStatements
                              │
                              ▼
                      buildAMDArguments
                              │
                              ▼
                      injectWrapper (define)
                              │
                              ▼
                       AMDモジュールAST ──▶ Generator ──▶ AMD形式コード
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-plugin-transform-modules-amd/src/index.ts` | ソース | メインプラグイン実装 |
| package.json | `packages/babel-plugin-transform-modules-amd/package.json` | 設定 | 依存関係・メタデータ |
| helper-module-transforms | `packages/babel-helper-module-transforms/src/` | ソース | モジュール変換共通ヘルパー |
| helper-plugin-utils | `packages/babel-helper-plugin-utils/src/` | ソース | プラグイン開発ユーティリティ |
