# 通知設計書 13-browserslistオプション警告

## 概要

本ドキュメントは、`@babel/preset-env`において、`corejs`オプションが`useBuiltIns`オプションなしで設定された場合に出力される警告通知の仕様を定義する。

### 本通知の処理概要

この通知は、開発者が`@babel/preset-env`で`corejs`オプションを設定しているが、`useBuiltIns`オプションが`false`（デフォルト値）のままになっている場合に警告を出力する機能である。

**業務上の目的・背景**：`@babel/preset-env`では、ポリフィルの注入を制御するために`useBuiltIns`オプションと`corejs`オプションを組み合わせて使用する。`corejs`オプションは使用するcore-jsのバージョンを指定するが、`useBuiltIns`が`false`の場合はポリフィルが注入されないため、`corejs`の設定は効果を持たない。この警告は、設定の意図しない状態を開発者に通知し、設定の見直しを促すために存在する。

**通知の送信タイミング**：`normalizeCoreJSOption`関数内で、`corejs`オプションが有効なバージョンとして解析され、かつ`useBuiltIns`が`false`の場合に送信される。

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

**通知内容の概要**：`corejs`オプションは`useBuiltIns`オプションが`false`でない場合にのみ効果があることを説明する警告メッセージ。

**期待されるアクション**：開発者は`useBuiltIns`オプションを`"entry"`または`"usage"`に設定するか、不要であれば`corejs`オプションを削除することが推奨される。

## 通知種別

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

## 送信仕様

### 基本情報

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

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

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

## 通知テンプレート

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

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

### 本文テンプレート

```
WARNING (@babel/preset-env): The `corejs` option only has an effect when the `useBuiltIns` option is not `false`
```

### 添付ファイル

該当なし

## テンプレート変数

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

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| API呼び出し | normalizeCoreJSOption関数の実行 | `version`が有効（truthy）かつ`!useBuiltIns`がtrue | corejsバージョンが指定されているがuseBuiltInsがfalseの場合 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| version が falsy | corejsオプションが未指定または無効な場合 |
| useBuiltIns が truthy | useBuiltInsが"entry"または"usage"に設定されている場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[normalizeCoreJSOption呼び出し] --> B{corejsオプションが<br>オブジェクト形式?}
    B -->|Yes| C[version = corejs.version<br>proposals = corejs.proposals]
    B -->|No| D[rawVersion = corejs]
    C --> E[semver.coerceでバージョン解析]
    D --> E
    E --> F{versionが有効?}
    F -->|No| G[警告なし]
    F -->|Yes| H{useBuiltInsが有効?}
    H -->|Yes| I[バージョン検証処理へ]
    H -->|No| J[console.warn出力]
    J --> K[戻り値を返す]
    G --> K
    I --> K
```

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

### 参照テーブル一覧

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

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

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

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

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

## 備考

- `useBuiltIns`のデフォルト値は`false`であり、明示的に設定しないとポリフィルは注入されない
- `corejs`オプションはcore-jsのバージョンを指定し、現在はcore-js@3のみがサポートされている
- この警告は設定ミスの早期発見を助けることを目的としている

---

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

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

### 推奨読解順序

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

まず、CorejsOptionとBuiltInsOptionの型定義を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types.ts | `packages/babel-preset-env/src/types.ts` | CorejsOption型の定義 |
| 1-2 | normalize-options.ts | `packages/babel-preset-env/src/normalize-options.ts` | NormalizedCorejsOption型（151-154行目） |

**読解のコツ**: `CorejsOption`はバージョン文字列/数値またはオブジェクト形式（`{version, proposals}`）を受け付ける。

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

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

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

**主要処理フロー**:
1. **160-161行目**: 変数の初期化
2. **163-173行目**: corejsオプションの解析（オブジェクト形式 vs プリミティブ形式）
3. **175行目**: semver.coerceでバージョン解析
4. **177-196行目**: バージョン検証と警告出力

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | normalize-options.ts | `packages/babel-preset-env/src/normalize-options.ts` | useBuiltInsチェックと警告（191-195行目） |

**主要処理フロー**:
- **191行目**: `!useBuiltIns`の条件チェック
- **192-194行目**: console.warn出力

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

```
normalizeOptions (normalize-options.ts:201)
    │
    └─ normalizeCoreJSOption (156行目)
           │
           ├─ semver.coerce (175行目)
           │      └─ バージョン文字列の正規化
           │
           └─ console.warn (192-194行目)
                  └─ 条件: version && !useBuiltIns
```

### データフロー図

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

Options {                 normalizeOptions
  corejs: "3.33",    ───▶ ├─ normalizeCoreJSOption  ───▶ console.warn
  useBuiltIns: false      │      ├─ semver.coerce        (条件付き)
}                         │      └─ 条件チェック
                          └─ 他のオプション処理
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| normalize-options.ts | `packages/babel-preset-env/src/normalize-options.ts` | ソース | オプション正規化とwarning出力のメイン実装 |
| types.ts | `packages/babel-preset-env/src/types.ts` | ソース | 型定義（CorejsOption, BuiltInsOption等） |
| options.ts | `packages/babel-preset-env/src/options.ts` | ソース | UseBuiltInsOption列挙型の定義 |
| index.ts | `packages/babel-preset-env/src/index.ts` | ソース | プリセットのエントリーポイント |
