# 通知設計書 5-デバッグ情報出力

## 概要

本ドキュメントは、@babel/preset-envのdebugオプションが有効な場合に、ターゲット環境情報、モジュール変換設定、使用プラグイン一覧などのデバッグ情報をコンソールへ出力する機能について設計内容を記載する。

### 本通知の処理概要

この通知は、@babel/preset-envの設定で `debug: true` を指定した際に、プリセットの設定解析結果やプラグイン選択の詳細情報を開発者に知らせる機能である。

**業務上の目的・背景**：@babel/preset-envは、指定されたターゲットブラウザ/Node.jsバージョンに基づいて必要なBabelプラグインを自動的に選択する。この自動選択の結果がどのようになったかを確認したい場合がある。特に、特定のターゲット環境で予期しない変換が行われる場合や、バンドルサイズの最適化を検討する際に、どのプラグインが使用されているかを把握することは重要である。

**通知の送信タイミング**：@babel/preset-envが初期化される際、設定解析が完了した時点で送信される。つまり、Babelの変換処理が開始される前に出力される。

**通知の受信者**：コマンドを実行した開発者（標準出力を監視しているユーザー）

**通知内容の概要**：以下の情報が出力される：
- ターゲット環境の設定（JSON形式）
- モジュール変換設定
- 使用されるプラグイン一覧
- ポリフィル設定状況

**期待されるアクション**：開発者は、この情報を参考にして、preset-envの設定を調整したり、不要なプラグインを除外したり、ターゲット環境の設定を見直したりすることができる。

## 通知種別

コンソール出力（標準出力：stdout）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（console.log） |
| 優先度 | 低（デバッグ用） |
| リトライ | なし |

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

標準出力（stdout）に固定。特定の送信先決定ロジックはなく、プロセスの標準出力に直接出力される。

## 通知テンプレート

### コンソール通知の場合

| 項目 | 内容 |
|-----|------|
| 出力先 | 標準出力（stdout） |
| フォーマット | プレーンテキスト + JSON |

### 本文テンプレート

```
@babel/preset-env: `DEBUG` option

Using targets:
{targetsJSON}

Using modules transform: {modulesTransform}

Using plugins:
{pluginsList}

Using polyfills: {polyfillsMessage}
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| targetsJSON | ターゲット環境のJSON表現 | prettifyTargets(targets)をJSON.stringify | Yes |
| modulesTransform | モジュール変換設定 | optionsModules.toString() | Yes |
| pluginsList | 使用プラグイン一覧 | pluginNames配列をループ出力 | Yes |
| polyfillsMessage | ポリフィル設定メッセージ | useBuiltInsの設定による | No |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 設定読み込み | @babel/preset-env初期化 | `debug: true`オプションが指定されていること | プリセット初期化時に発火 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| `debug`オプション未指定またはfalse | デバッグモードでない場合は通知されない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[@babel/preset-env初期化] --> B[normalizeOptions実行]
    B --> C[ターゲット解析]
    C --> D[プラグイン選択]
    D --> E{debug: true?}
    E -->|Yes| F[console.log DEBUG header]
    E -->|No| G[デバッグ出力スキップ]
    F --> H[console.log Using targets]
    H --> I[console.log targets JSON]
    I --> J[console.log Using modules transform]
    J --> K[console.log Using plugins]
    K --> L[各プラグインをlogPlugin出力]
    L --> M{useBuiltIns設定?}
    M -->|false| N[console.log No polyfills]
    M -->|true| O[ポリフィル情報出力]
    N --> P[プリセット設定返却]
    O --> P
    G --> P
```

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

該当なし（データベースを使用しない）

## エラー処理

### エラーケース一覧

特にエラー処理は行われない。デバッグ情報の出力は設定解析が正常に完了した後に行われる。

### リトライ仕様

リトライなし

## 配信設定

### レート制限

該当なし（プリセット初期化時に1回のみ出力）

### 配信時間帯

制限なし

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

ターゲットブラウザのバージョン情報やプラグイン設定が出力される。機密性の高い情報は含まれないが、CI/CDログなどで外部に出力される場合は注意が必要。

## 備考

- デバッグ出力はプリセットの初期化時に行われるため、複数ファイルを処理する場合でも1回のみ出力される
- logPlugin関数を使用して、各プラグインがどのターゲット環境で必要とされているかの詳細情報が出力される
- ポリフィル設定がない場合は専用のメッセージが表示される

---

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

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

### 推奨読解順序

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

この通知に関わるデータ構造は、preset-envの設定オプションとターゲット情報である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/babel-preset-env/src/index.ts` | Options型とTargets型の使用を確認 |
| 1-2 | types.d.ts | `packages/babel-preset-env/src/types.d.ts` | Options型の定義を確認 |

**読解のコツ**: `Options`型にはdebugプロパティが含まれており、boolean型である。

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

デバッグ情報出力の処理フローを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/babel-preset-env/src/index.ts` | declarePreset関数内のdefault export（195-337行目） |

**主要処理フロー**:
1. **208-221行目**: normalizeOptionsで設定を正規化
2. **223-244行目**: ターゲット環境の解析
3. **278-292行目**: プラグイン選択処理
4. **319-334行目**: debugモード時のconsole.log出力

#### Step 3: デバッグ出力の詳細を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts | `packages/babel-preset-env/src/index.ts` | debug条件ブロック（319-334行目） |

**主要処理フロー**:
- **320行目**: `console.log("@babel/preset-env: \`DEBUG\` option")` でヘッダー出力
- **321行目**: `console.log("\nUsing targets:")` でターゲットセクション
- **322行目**: `console.log(JSON.stringify(prettifyTargets(targets), null, 2))` でターゲットJSON
- **323行目**: モジュール変換設定の出力
- **324行目**: `console.log("\nUsing plugins:")` でプラグインセクション
- **325-327行目**: `pluginNames.forEach`で各プラグインをlogPluginで出力
- **329-333行目**: ポリフィル設定メッセージの出力

#### Step 4: logPlugin関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | debug.ts | `packages/babel-preset-env/src/debug.ts` | logPlugin関数の実装 |

**主要処理フロー**:
- 各プラグインがどのターゲット環境で必要とされているかを出力

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

```
babel.transform() / babel.transformFile()
    │
    └─ @babel/preset-env 初期化
           │
           ├─ normalizeOptions()
           │      └─ オプション正規化
           │
           ├─ getTargets() / getLocalTargets()
           │      └─ ターゲット環境解析
           │
           ├─ filterItems()
           │      └─ プラグイン選択
           │
           └─ [debug: true]
                  │
                  ├─ console.log("@babel/preset-env: `DEBUG` option")
                  │
                  ├─ console.log(prettifyTargets(targets))
                  │
                  ├─ console.log(modulesTransform)
                  │
                  ├─ pluginNames.forEach(logPlugin)
                  │
                  └─ console.log(polyfillsMessage)
```

### データフロー図

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

babel.config.js ───────────▶ normalizeOptions()
    │                              │
    ├─ targets                     ▼
    ├─ debug: true         getTargets() / getLocalTargets()
    ├─ useBuiltIns                 │
    └─ modules                     ▼
                           filterItems()
                                   │
                                   ▼
                           [debug: true]
                                   │
                                   ├─▶ stdout: "@babel/preset-env: `DEBUG` option"
                                   ├─▶ stdout: "Using targets: {...}"
                                   ├─▶ stdout: "Using modules transform: ..."
                                   ├─▶ stdout: "Using plugins: ..."
                                   └─▶ stdout: "Using polyfills: ..."
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-preset-env/src/index.ts` | ソース | preset-envのメインロジックとデバッグ出力 |
| debug.ts | `packages/babel-preset-env/src/debug.ts` | ソース | logPlugin関数の実装 |
| normalize-options.ts | `packages/babel-preset-env/src/normalize-options.ts` | ソース | オプション正規化処理 |
| types.d.ts | `packages/babel-preset-env/src/types.d.ts` | 型定義 | Options型の定義 |
