# 機能設計書 13-@babel/compat-data

## 概要

本ドキュメントは、Babelの@babel/compat-dataパッケージの機能設計を記述する。@babel/compat-dataは、各ブラウザ・ランタイム環境におけるJavaScript機能のサポート状況を示す互換性データを提供する。

### 本機能の処理概要

@babel/compat-dataは、ECMAScript機能とBabelプラグインの対応関係を示すデータを提供し、@babel/preset-envが最適なプラグインセットを決定するための基盤となる。

**業務上の目的・背景**：モダンJavaScriptの各機能は、ブラウザやNode.jsのバージョンによってサポート状況が異なる。開発者がターゲット環境を指定した際、どの構文変換プラグインが必要かを自動判定するためには、正確な互換性データが不可欠である。@babel/compat-dataは、ECMAScript提案の各機能について、どのブラウザバージョンからネイティブサポートされているかを網羅的にまとめたデータベースである。

**機能の利用シーン**：@babel/preset-envがtargetsオプションに基づいて必要なプラグインを選定する際に参照される。また、@babel/helper-compilation-targetsから直接参照され、カスタムプラグイン開発でも利用可能。

**主要な処理内容**：
1. プラグインと環境サポートバージョンのマッピングデータ提供（plugins.json）
2. ネイティブESモジュールサポートデータ提供（native-modules.json）
3. バグ修正プラグインのターゲットデータ提供（plugin-bugfixes.json）
4. 重複プラグインの関係データ提供（overlapping-plugins.json）

**関連システム・外部連携**：@babel/preset-env、@babel/helper-compilation-targets、browserslistと連携する。データソースはkangax/compat-table、MDN browser-compat-data、electron-to-chromiumなど。

**権限による制御**：本機能に権限制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | なし | - | データライブラリとして利用 |

## 機能種別

データ提供 / 互換性データベース

## 入力仕様

### 入力パラメータ

本パッケージはJSONデータを提供するのみで、関数としての入力パラメータは存在しない。

| データファイル | 説明 |
|---------------|------|
| plugins.json | 各変換プラグインのサポートバージョン |
| native-modules.json | ESモジュールのサポートバージョン |
| plugin-bugfixes.json | バグ修正プラグインのターゲット |
| overlapping-plugins.json | 重複するプラグインの関係 |

### 入力データソース

- kangax/compat-table: ECMAScript互換性テーブル
- @mdn/browser-compat-data: MDNブラウザ互換性データ
- electron-to-chromium: ElectronとChromiumのバージョン対応
- core-js-compat: core-jsのポリフィル対応データ

## 出力仕様

### 出力データ

**plugins.json形式**:
```json
{
  "transform-arrow-functions": {
    "chrome": "47",
    "opera": "34",
    "edge": "13",
    "firefox": "43",
    "safari": "10",
    "node": "6",
    "ios": "10"
  }
}
```

| 項目名 | 型 | 説明 |
|--------|-----|------|
| プラグイン名 | object | 各プラグインのサポート情報 |
| ブラウザ名 | string | 最小サポートバージョン |

### 出力先

JSON形式でエクスポートされ、他のBabelパッケージから参照される。

## 処理フロー

### 処理シーケンス

```
1. データ生成（ビルド時）
   └─ scripts/build-data.mjs を実行
       └─ compat-tableからデータを抽出
       └─ MDN browser-compat-dataを参照
       └─ electron-to-chromiumでElectronバージョンを変換
       └─ JSONファイルを生成

2. データ利用（実行時）
   └─ @babel/preset-env がtargetsを受け取る
   └─ @babel/compat-data/plugins をimport
   └─ filterItemsでプラグインリストを決定
```

### フローチャート

```mermaid
flowchart TD
    A[compat-table更新] --> B[build-data.mjs実行]
    B --> C[plugins.json生成]
    B --> D[native-modules.json生成]
    B --> E[plugin-bugfixes.json生成]
    C --> F[@babel/preset-env]
    D --> F
    E --> F
    F --> G{targets指定}
    G --> H[filterItems呼び出し]
    H --> I[必要なプラグインリスト]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | バージョン形式 | メジャー.マイナー形式（例: "47", "10.3"） | 常時 |
| BR-02 | 環境識別子 | chrome, firefox, safari, edge, node, ios等 | 常時 |
| BR-03 | 提案機能の扱い | Stage 4になった機能のみデータに含める | 常時 |
| BR-04 | バグ修正プラグイン | 特定ブラウザのバグ対応プラグインは別データ | plugin-bugfixes.json |

### 計算ロジック

プラグイン必要性の判定:
```
必要 = ターゲットバージョン < サポート開始バージョン

例：targets: { chrome: "45" }
    transform-arrow-functions.chrome = "47"
    → 45 < 47 なので変換が必要
```

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | インポートエラー | JSONファイルが見つからない | パッケージの再インストール |

### リトライ仕様

本機能にリトライ処理は存在しない。

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

本機能はトランザクション処理を行わない。

## パフォーマンス要件

- JSONデータは起動時に一度だけロード
- プラグイン判定はO(1)のルックアップ

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

- 静的JSONデータのみを提供
- 外部からの入力は受け付けない

## 備考

- Node.js v20.19.0以上またはv22.12.0以上が必要
- データ更新はBabelリリースに合わせて行われる
- 50以上のプラグインと20以上の環境の組み合わせを管理

---

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

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

### 推奨読解順序

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

まず、提供されるデータの構造を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | plugins.json | `packages/babel-compat-data/data/plugins.json` | 各プラグインのサポートバージョン定義 |
| 1-2 | native-modules.json | `packages/babel-compat-data/data/native-modules.json` | ESMサポート情報 |
| 1-3 | plugin-bugfixes.json | `packages/babel-compat-data/data/plugin-bugfixes.json` | バグ修正プラグイン情報 |
| 1-4 | overlapping-plugins.json | `packages/babel-compat-data/data/overlapping-plugins.json` | 重複プラグイン関係 |

**読解のコツ**:
- **plugins.json**: キーがプラグイン名（transform-接頭辞付き）、値が環境別サポートバージョン
- **1-8行目**: transform-explicit-resource-managementの例。chrome 141、firefox 141、node 25でサポート
- **363-376行目**: transform-arrow-functions。chrome 47、node 6など多くの環境でサポート済み

#### Step 2: パッケージ設定を理解する

エクスポート設定とデータファイルの関係を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | package.json | `packages/babel-compat-data/package.json` | exportsフィールドの定義 |

**主要処理フロー**:
- **15-20行目**: exportsフィールドで4つのJSONファイルを公開
- **21-23行目**: データ生成スクリプトの定義

#### Step 3: データ生成プロセスを理解する

データがどのように生成されるかを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | build-data.mjs | `packages/babel-compat-data/scripts/build-data.mjs` | メインのデータ生成スクリプト |
| 3-2 | build-modules-support.mjs | `packages/babel-compat-data/scripts/build-modules-support.mjs` | ESMサポートデータ生成 |
| 3-3 | build-bugfixes-targets.mjs | `packages/babel-compat-data/scripts/build-bugfixes-targets.mjs` | バグ修正データ生成 |

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

```
データ生成（ビルド時）
    │
    ├─ download-compat-table.sh
    │      └─ kangax/compat-table をダウンロード
    │
    └─ build-data.mjs
           ├─ compat-tableのデータを解析
           ├─ @mdn/browser-compat-data を参照
           ├─ electron-to-chromium を参照
           └─ plugins.json を出力

データ利用（実行時）
    │
    └─ @babel/preset-env
           └─ import plugins from "@babel/compat-data/plugins"
                  └─ filterItems(plugins, include, exclude, targets)
                         └─ 必要なプラグインを決定
```

### データフロー図

```
[外部データソース]                 [処理]                    [出力]

kangax/compat-table ─────┐
                         │
@mdn/browser-compat-data ├───> build-data.mjs ───────> plugins.json
                         │
electron-to-chromium ────┘

core-js-compat ──────────────> build-modules-support.mjs ──> native-modules.json

compat-table ────────────────> build-bugfixes-targets.mjs ──> plugin-bugfixes.json
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| package.json | `packages/babel-compat-data/package.json` | 設定 | パッケージ設定、exports定義 |
| plugins.json | `packages/babel-compat-data/data/plugins.json` | データ | プラグイン別サポートバージョン |
| native-modules.json | `packages/babel-compat-data/data/native-modules.json` | データ | ESMサポートバージョン |
| plugin-bugfixes.json | `packages/babel-compat-data/data/plugin-bugfixes.json` | データ | バグ修正プラグインターゲット |
| overlapping-plugins.json | `packages/babel-compat-data/data/overlapping-plugins.json` | データ | 重複プラグイン関係 |
| build-data.mjs | `packages/babel-compat-data/scripts/build-data.mjs` | スクリプト | メインデータ生成 |
| build-modules-support.mjs | `packages/babel-compat-data/scripts/build-modules-support.mjs` | スクリプト | モジュールサポート生成 |
| build-bugfixes-targets.mjs | `packages/babel-compat-data/scripts/build-bugfixes-targets.mjs` | スクリプト | バグ修正データ生成 |
| download-compat-table.sh | `packages/babel-compat-data/scripts/download-compat-table.sh` | スクリプト | 外部データ取得 |
