# 機能設計書 42-@babel/plugin-transform-modules-umd

## 概要

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

### 本機能の処理概要

**業務上の目的・背景**：
UMD（Universal Module Definition）は、AMD、CommonJS、およびグローバル変数の3つの異なるモジュールシステムで動作する汎用的なモジュール形式である。ライブラリ開発者がnpm、RequireJS、およびブラウザの`<script>`タグすべてで動作するコードを配布する際に必要とされる。本プラグインは、ES2015モジュール構文をUMD形式に変換することで、あらゆる環境での利用を可能にする。

**機能の利用シーン**：
- 複数の環境（Node.js、ブラウザ、RequireJS）で動作するライブラリの開発
- CDN経由でのスクリプト配布（グローバル変数として公開）
- レガシーシステムとの互換性が必要なプロジェクト
- npmパッケージとしてもブラウザ直接読み込みとしても使用したいケース

**主要な処理内容**：
1. ES2015のimport/export文をUMD形式のIIFE（即時実行関数）に変換
2. AMD（define）、CommonJS（require/exports）、グローバル変数の3パターンを検出・分岐
3. ブラウザ用グローバル変数の自動生成と設定
4. モジュール間の相互運用性（interop）処理

**関連システム・外部連携**：
@babel/helper-module-transformsと連携してモジュール変換処理を実行。Node.jsのpath APIを使用してモジュール名からグローバル変数名を算出。

**権限による制御**：
プラグインオプションによる動作制御（globals、exactGlobals、strict等）が可能。

## 関連画面

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

## 機能種別

データ変換（AST変換）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| allowTopLevelThis | boolean | No | トップレベルのthisをundefinedに変換しない | - |
| exactGlobals | boolean | No | グローバル変数名を厳密に指定 | - |
| globals | Record<string, string> | No | モジュール名からグローバル変数名へのマッピング | - |
| 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 | UMD形式に変換されたAST |
| umdWrapper | t.ExpressionStatement | UMDラッパーIIFE |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. Program.exitビジター
   └─ ESモジュールかどうかを判定
2. モジュールヘッダー準備
   └─ rewriteModuleStatementsAndPrepareHeader呼び出し
3. AMD/CommonJS/ブラウザ引数構築
   └─ 各環境用の引数配列を生成
4. ブラウザ初期化コード生成
   └─ buildBrowserInit関数でグローバル変数設定
5. UMDラッパー注入
   └─ buildWrapperテンプレートでIIFE生成
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{ESモジュールか?}
    B -->|No| C[処理終了]
    B -->|Yes| D[モジュールヘッダー準備]
    D --> E[AMD引数配列構築]
    E --> F[CommonJS引数配列構築]
    F --> G[ブラウザ引数配列構築]
    G --> H[interopラッパー適用]
    H --> I[ブラウザ初期化コード生成]
    I --> J[UMDラッパーIIFE生成]
    J --> K[終了]
    C --> K
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-42-01 | UMD形式変換 | import/exportをUMD形式IIFEに変換 | ESモジュール構文検出時 |
| BR-42-02 | 環境検出 | define/exports/globalを判定して適切な形式を選択 | 実行時 |
| BR-42-03 | グローバル変数設定 | ファイル名またはglobalsオプションからグローバル名を決定 | ブラウザ環境時 |
| BR-42-04 | exactGlobalsモード | globalsマッピングを厳密に適用 | exactGlobals=true時 |

### 計算ロジック

グローバル変数名の算出:
- exactGlobals=false: `basename(source, extname(source))`をtoIdentifierで変換
- exactGlobals=true: globalsマッピングを直接使用

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

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

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

- UMD形式はグローバル変数を使用するため、名前衝突に注意
- strictモードオプションにより、安全なコード生成を保証

## 備考

- UMDはライブラリ配布に最適な形式
- グローバル変数名はファイル名から自動生成されるため、意図した名前にするにはglobalsオプションを使用

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/babel-plugin-transform-modules-umd/src/index.ts` | Options型（43-52行目）を確認。globals、exactGlobalsが特有 |

**読解のコツ**: AMDプラグインとの違いはglobals/exactGlobalsオプションの存在。これによりブラウザ環境でのグローバル変数名を制御できる。

#### Step 2: UMDテンプレートを理解する

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

**主要処理フロー**:
- **23-41行目**: UMDラッパーテンプレート（AMD/CommonJS/グローバルの3分岐）
- **36-38行目**: globalThisまたはselfまたはthisをglobalとして使用
- **17-19行目**: buildPrerequisiteAssignmentでネストしたグローバル変数を初期化

#### Step 3: ブラウザ用初期化処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts | `packages/babel-plugin-transform-modules-umd/src/index.ts` | buildBrowserInit関数（75-122行目） |

**主要処理フロー**:
- **75-122行目**: ブラウザ環境でのグローバル変数初期化文を生成
- **81-83行目**: モジュール名またはファイル名からグローバル変数名を決定
- **90-108行目**: exactGlobalsモードでドット区切りの階層的グローバル変数を設定

#### Step 4: Program.exitビジターを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | index.ts | `packages/babel-plugin-transform-modules-umd/src/index.ts` | Program.exit（164-272行目） |

**主要処理フロー**:
- **166行目**: ESモジュールでなければ処理スキップ
- **174-186行目**: rewriteModuleStatementsAndPrepareHeader呼び出し
- **188-200行目**: AMD、CommonJS、ブラウザ用引数配列の初期化
- **249-266行目**: buildWrapperでUMDラッパー生成

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

```
@babel/plugin-transform-modules-umd/src/index.ts
    │
    ├─ @babel/helper-plugin-utils/declare()
    │      └─ プラグイン定義の標準化
    │
    ├─ @babel/helper-module-transforms
    │      ├─ rewriteModuleStatementsAndPrepareHeader()
    │      ├─ getModuleName()
    │      ├─ wrapInterop()
    │      └─ buildNamespaceInitStatements()
    │
    ├─ node:path
    │      ├─ basename()
    │      └─ extname()
    │
    └─ @babel/core/template
           └─ buildWrapper / buildPrerequisiteAssignment
```

### データフロー図

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

ESModuleソースコード  ──▶  Parser (AST生成)
                              │
                              ▼
                      rewriteModuleStatements
                              │
                     ┌────────┼────────┐
                     ▼        ▼        ▼
               AMD引数   CJS引数   Browser引数
                     │        │        │
                     └────────┼────────┘
                              │
                              ▼
                      buildWrapper (IIFE)
                              │
                              ▼
                       UMDモジュールAST ──▶ Generator ──▶ UMD形式コード
```

### 関連ファイル一覧

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