# 通知設計書 22-キャッシュAPI警告

## 概要

本ドキュメントは、`@babel/core`の設定APIにおける、バージョンチェック機能が環境変数によって無効化された場合に出力されるキャッシュAPI警告の設計について記載する。

### 本通知の処理概要

この通知は、Babelプラグインやプリセットが`api.assertVersion()`を呼び出してBabelバージョンの互換性をチェックする際に、バージョンが互換性がないにもかかわらず環境変数`BABEL_7_TO_8_DANGEROUSLY_DISABLE_VERSION_CHECK`によってチェックが無効化されている場合に警告を出力する機能を提供する。

**業務上の目的・背景**：Babel 7からBabel 8への移行期間中、一部のプラグインやプリセットがまだ新しいバージョンに対応していない場合がある。しかし、開発者がリスクを理解した上で強制的に動作させたい場合に、環境変数でバージョンチェックを無効化できる。この警告は、チェックが無効化されていることを開発者に通知し、潜在的な問題を認識させる。

**通知の送信タイミング**：`assertVersion`関数が呼び出され、要求されたバージョン範囲と現在のBabelバージョンが互換性がなく、かつ環境変数`BABEL_7_TO_8_DANGEROUSLY_DISABLE_VERSION_CHECK`が設定されている場合に警告が出力される。

**通知の受信者**：コンソールを監視している開発者、特にBabel設定を行っている開発者やCI/CDシステムの管理者が対象。

**通知内容の概要**：警告メッセージには、要求されたBabelバージョン範囲、現在読み込まれているBabelバージョン、および問題の原因を特定するためのスタックトレース確認の案内が含まれる。

**期待されるアクション**：開発者は、警告の内容を確認し、プラグイン・プリセットのバージョンを更新するか、Babelのバージョンを変更するか、またはリスクを受け入れてそのまま続行するかを判断することが期待される。

## 通知種別

コンソール警告（console.warn）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 高 |
| リトライ | 無 |

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

標準エラー出力（stderr）に対してconsole.warnで出力される。Babelの設定読み込み処理を実行しているプロセスのコンソールに表示される。

## 通知テンプレート

### コンソール出力

| 項目 | 内容 |
|-----|------|
| 出力先 | stderr（console.warn経由） |
| 形式 | プレーンテキスト |

### 本文テンプレート

```
Requires Babel "${range}", but was loaded with "${coreVersion}". If you are sure you have a compatible version of @babel/core, it is likely that something in your build process is loading the wrong version. Inspect the stack trace of this error to look for the first entry that doesn't mention "@babel/core" or "babel-core" to see what is calling Babel.
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| なし | - | - | 添付ファイルなし |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| range | 要求されたBabelバージョン範囲 | assertVersion関数のパラメータ | Yes |
| coreVersion | 現在読み込まれているBabelのバージョン | @babel/coreのversion | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| API呼び出し | assertVersion関数の呼び出し | バージョン非互換かつ環境変数が設定されている | プラグイン・プリセットの初期化時 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| バージョンが互換性がある | semver.satisfiesがtrueを返す場合 |
| rangeが"*" | すべてのバージョンを許容する場合 |
| 環境変数が設定されていない | BABEL_7_TO_8_DANGEROUSLY_DISABLE_VERSION_CHECKが未設定の場合はエラーをスロー |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[assertVersion呼び出し] --> B{rangeの型チェック}
    B -->|数値| C[^N.0.0-0形式に変換]
    B -->|文字列| D[そのまま使用]
    C --> E{range === "*"?}
    D --> E
    E -->|Yes| F[正常終了]
    E -->|No| G{semver.satisfies?}
    G -->|Yes| F
    G -->|No| H{環境変数設定あり?}
    H -->|Yes| I[console.warnで警告出力]
    H -->|No| J[Errorをスロー]
    I --> K[正常終了]
    F --> L[終了]
    K --> L
    J --> L
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| なし | - | データベースは使用しない |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| なし | - | データベースは使用しない |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 型エラー | rangeが文字列でも数値でもない場合 | "Expected string or integer value."エラーをスロー |
| バージョン非互換エラー | 環境変数が設定されていない場合のバージョン非互換 | BABEL_VERSION_UNSUPPORTEDエラーをスロー |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | なし |
| 1日あたり上限 | なし |

### 配信時間帯

制限なし（設定読み込み時に同期的に出力）

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

- バージョン情報のみが出力され、機密情報は含まれない
- 環境変数の使用により、意図的にセキュリティチェックを無効化しているため、使用には注意が必要

## 備考

- 環境変数名の"DANGEROUSLY"は、この機能の使用にはリスクが伴うことを示している
- Babel 7から8への移行期間中の一時的な措置として設計されている
- スタックトレースの制限値を25に引き上げて、問題の原因特定を容易にしている

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | config-api.ts | `packages/babel-core/src/config/helpers/config-api.ts` | ConfigAPI型の定義（39-46行目） |

**読解のコツ**: `assertVersion`が`ConfigAPI`型のメンバーとして定義されていることを確認する。

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

警告を出力するassertVersion関数の実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | config-api.ts | `packages/babel-core/src/config/helpers/config-api.ts` | assertVersion関数の実装（123-174行目） |

**主要処理フロー**:
1. **行124-128**: 数値の場合、`^N.0.0-0`形式の文字列に変換
2. **行130-132**: 文字列でない場合はエラーをスロー
3. **行137**: `*`またはsemver.satisfiesで互換性チェック
4. **行139-145**: エラーメッセージの構築
5. **行147-152**: 環境変数が設定されている場合はconsole.warnで警告
6. **行155-173**: 環境変数が設定されていない場合はエラーをスロー

#### Step 3: API公開部分を理解する

Config APIがどのように公開されているかを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config-api.ts | `packages/babel-core/src/config/helpers/config-api.ts` | makeConfigAPI関数（57-93行目） |

**主要処理フロー**:
- **行91**: assertVersionがConfigAPIオブジェクトに含まれる

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

```
プラグイン/プリセット
    │
    └─ api.assertVersion(range)
           │
           ├─ 型チェック（数値→文字列変換）
           │
           ├─ semver.satisfies(coreVersion, range)
           │
           └─ バージョン非互換時
                  │
                  ├─ 環境変数あり → console.warn(message) ← 警告出力
                  │
                  └─ 環境変数なし → throw Error
```

### データフロー図

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

バージョン範囲 ───▶ assertVersion関数 ───▶ void または Error
                              │
                              ▼
                        semver.satisfies確認
                              │
                              ▼ (非互換)
                        環境変数確認 ───▶ console.warn（警告メッセージ）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| config-api.ts | `packages/babel-core/src/config/helpers/config-api.ts` | ソース | Config APIの実装とassertVersion関数 |
| index.ts | `packages/babel-core/src/index.ts` | ソース | coreVersionのエクスポート |
| caching.ts | `packages/babel-core/src/config/caching.ts` | ソース | キャッシュ設定の実装 |
