# 通知設計書 14-includeオプション互換性警告

## 概要

本ドキュメントは、`@babel/preset-env`において、動的インポート（Dynamic Import）の変換に関する互換性警告の仕様を定義する。

### 本通知の処理概要

この通知は、開発者が`@babel/preset-env`のモジュール変換オプションと動的インポートの変換を組み合わせて使用しようとした際、互換性のない設定の場合に警告を出力する機能である。

**業務上の目的・背景**：動的インポート（`import()`）は、AMD、CommonJS、SystemJSのモジュールシステムに変換可能だが、UMD形式への変換はサポートされていない。また、モジュール変換が無効（`modules: false`）の場合も動的インポートの変換は行われない。この警告は、開発者に動的インポート変換の制限事項を通知し、適切なモジュール設定への見直しを促すために存在する。

**通知の送信タイミング**：`getSpecialModulesPluginNames`関数内で、`shouldTransformDynamicImport`がtrueかつ、モジュール形式が未設定（false）またはUMDの場合に送信される。

**通知の受信者**：Babelを使用してJavaScript/TypeScriptコードをトランスパイルする開発者。コンソール出力を通じて通知される。

**通知内容の概要**：動的インポートはAMD、CommonJS、SystemJSへの変換時のみ変換可能であることを説明する警告メッセージ。

**期待されるアクション**：開発者はモジュール変換設定を`"amd"`、`"commonjs"`、または`"systemjs"`に変更するか、動的インポートの変換を諦めてネイティブの動的インポートをそのまま使用することが推奨される。

## 通知種別

コンソール出力（console.warn）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 中 |
| リトライ | なし（コンソール出力のため） |

### 送信先決定ロジック

標準エラー出力（stderr）経由でコンソールに出力される。Babelを実行している開発者に対して直接表示される。

## 通知テンプレート

### コンソール出力の場合

| 項目 | 内容 |
|-----|------|
| 出力先 | console.warn |
| 形式 | テキスト |

### 本文テンプレート

```
Dynamic import can only be transformed when transforming ES modules to AMD, CommonJS or SystemJS.
```

### 添付ファイル

該当なし

## テンプレート変数

該当なし（固定メッセージ）

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| API呼び出し | getSpecialModulesPluginNames関数の実行 | `shouldTransformDynamicImport === true` かつ `(!modules || modules === "umd")` | 動的インポート変換が必要だがモジュール設定が非対応の場合 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| shouldTransformDynamicImport が false | 動的インポートの変換が不要な場合 |
| modules が "amd", "commonjs", "systemjs" のいずれか | サポートされているモジュール形式の場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[getSpecialModulesPluginNames呼び出し] --> B{shouldTransformDynamicImport<br>がtrue?}
    B -->|No| C[modulesPluginNames返却]
    B -->|Yes| D{modulesがtruthy<br>かつumd以外?}
    D -->|Yes| E[transform-dynamic-importを追加]
    D -->|No| F[console.warn出力]
    E --> C
    F --> C
```

## データベース参照・更新仕様

### 参照テーブル一覧

該当なし（コンパイラプリセットのため、データベースアクセスは行わない）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| なし | - | この警告自体はエラーではなく、処理を中断しない |

### リトライ仕様

該当なし（一度の警告出力のみ）

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 制限なし | プリセット初期化時に一度だけ出力 |

### 配信時間帯

制限なし（Babelコンパイル実行時）

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

- 設定オプション名のみを出力し、ソースコードや機密情報は含まない
- ローカル環境のコンソールへの出力のため、情報漏洩リスクは低い

## 備考

- 動的インポート（`import()`）はES2020で標準化された機能
- UMD形式は複数のモジュールシステムに対応するユニバーサル形式だが、動的インポートの変換は技術的に困難
- `modules: false`の場合、ESモジュールをそのまま出力するため、動的インポートも変換されない

---

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

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

### 推奨読解順序

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

まず、ModuleOptionの型定義とモジュール変換の選択肢を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types.ts | `packages/babel-preset-env/src/types.ts` | ModuleOption型の定義 |
| 1-2 | options.ts | `packages/babel-preset-env/src/options.ts` | ModulesOption列挙型 |

**読解のコツ**: `ModuleOption`は`"amd" | "umd" | "systemjs" | "commonjs" | "auto" | false`の値を取る。

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

処理の起点となる`getSpecialModulesPluginNames`関数を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/babel-preset-env/src/index.ts` | getSpecialModulesPluginNames関数の開始（101行目） |

**主要処理フロー**:
1. **105-108行目**: modulesが有効な場合、対応する変換プラグインを追加
2. **110-118行目**: shouldTransformDynamicImportの処理と警告出力

#### Step 3: 警告出力処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts | `packages/babel-preset-env/src/index.ts` | 動的インポート警告（114-117行目） |

**主要処理フロー**:
- **110行目**: `shouldTransformDynamicImport`のチェック
- **111-112行目**: modules && modules !== "umd"の条件
- **114-117行目**: 条件を満たさない場合のconsole.warn出力

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

```
declarePreset (index.ts:195)
    │
    ├─ normalizeOptions (221行目)
    │
    ├─ getLocalTargets (237-244行目)
    │
    └─ getSpecialModulesPluginNames (283行目)
           │
           ├─ moduleTransformations[modules] (107行目)
           │      └─ モジュール変換プラグイン名取得
           │
           └─ console.warn (114-117行目)
                  └─ 条件: shouldTransformDynamicImport && (!modules || modules === "umd")
```

### データフロー図

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

Options {                 declarePreset
  modules: "umd",    ───▶ ├─ normalizeOptions
}                         ├─ getSpecialModulesPluginNames
                          │      ├─ モジュール形式チェック   ───▶ console.warn
caller {                  │      └─ 動的インポート変換判定        (条件付き)
  supportsDynamicImport   └─ プラグインリスト構築
}
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-preset-env/src/index.ts` | ソース | プリセットのエントリーポイントと警告出力 |
| types.ts | `packages/babel-preset-env/src/types.ts` | ソース | 型定義（ModuleOption等） |
| options.ts | `packages/babel-preset-env/src/options.ts` | ソース | ModulesOption列挙型の定義 |
| module-transformations.ts | `packages/babel-preset-env/src/module-transformations.ts` | ソース | モジュール形式とプラグイン名のマッピング |
