# 機能設計書 75-@babel/helper-compilation-targets

## 概要

本ドキュメントは、@babel/helper-compilation-targetsの機能設計について記載する。このパッケージは、Babelのコンパイルターゲット（対象ブラウザ/Node.js環境）の解決と処理を行うヘルパーモジュールである。

### 本機能の処理概要

**業務上の目的・背景**：現代のJavaScript開発では、サポート対象の環境（ブラウザ、Node.jsなど）に応じて適切な変換を行う必要がある。本パッケージは、browserslistクエリやターゲット設定を解析し、必要なBabelプラグインを決定するための互換性データ処理を提供する。@babel/preset-envの中核機能として、ターゲット環境に基づいた最適な変換プラグインの選定を実現する。

**機能の利用シーン**：@babel/preset-envや各種プラグインが、ユーザー指定のターゲット環境に基づいてプラグインの要否を判断する際に使用される。browserslistとの統合により、`.browserslistrc`や`package.json`のbrowserslistフィールドからターゲット設定を自動読み込みできる。ES Modulesサポート状況に基づく自動ターゲット設定も可能。

**主要な処理内容**：
1. ターゲット名の検証（chrome、firefox、node等の有効性チェック）
2. browserslistクエリの解析と最小バージョンの算出
3. ES Modulesサポートブラウザの自動検出
4. プラグイン要否の判定（isRequired関数）
5. ターゲット結果のキャッシュ（LRUキャッシュ）

**関連システム・外部連携**：browserslistライブラリ、@babel/compat-data、@babel/helper-validator-optionと連携する。

**権限による制御**：権限による実行制御は行わない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | @babel/preset-env等から内部利用 |

## 機能種別

ターゲット解決 / 互換性判定 / ユーティリティ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| inputTargets | InputTargets | No | ターゲット設定オブジェクト | 有効なターゲット名のみ |
| browsers | string \| string[] | No | browserslistクエリ | 有効なbrowserslistクエリ |
| esmodules | boolean | No | ESモジュールサポートブラウザのみ対象 | boolean型 |
| configPath | string | No | 設定ファイル検索開始パス | 有効なパス |
| configFile | string | No | browserslist設定ファイルパス | 有効なパス |
| browserslistEnv | string | No | browserslist環境名 | 文字列 |
| ignoreBrowserslistConfig | boolean | No | browserslist設定を無視 | boolean型 |

### 入力データソース

- Babel設定ファイル（babel.config.js等）
- browserslist設定ファイル（.browserslistrc、package.json）
- 環境変数（BROWSERSLIST、BROWSERSLIST_CONFIG）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Targets | object | 対象環境と最小バージョンのマップ |
| isRequired結果 | boolean | プラグインが必要かどうか |

### 出力先

呼び出し元に対してTargetsオブジェクトを返却

## 処理フロー

### 処理シーケンス

```
1. getTargets関数呼び出し
   ├─ browsersオプションの検証
   └─ inputTargetsからbrowsers/esmodulesを除外してtargetsを生成
2. browserslist設定の解決
   ├─ 明示的なbrowsersオプションがあればそれを使用
   ├─ なければ設定ファイルから検索
   └─ 見つからなければデフォルト（["defaults"]）を使用
3. esmodulesオプションの処理
   └─ ESM対応ブラウザの最小バージョンをマージ
4. browserslistクエリの解析
   ├─ resolveTargetsCachedでキャッシュ確認/解決
   └─ getLowestVersionsで最小バージョンを算出
5. ターゲットの解析と検証
   ├─ node: trueの場合は現在のNodeバージョンを使用
   ├─ 小数警告の出力
   └─ semverifyによるバージョン正規化
6. 結果の返却
```

### フローチャート

```mermaid
flowchart TD
    A[getTargets呼び出し] --> B[inputTargets検証]
    B --> C{browsersオプション?}
    C -->|あり| D[browserslist解析]
    C -->|なし| E{設定ファイル検索?}
    E -->|有効| F[設定ファイル読み込み]
    E -->|無効/見つからず| G[デフォルト使用]
    F --> H{esmodules?}
    G --> H
    D --> H
    H -->|true| I[ESMサポートでフィルタ]
    H -->|false| J[resolveTargetsCached]
    I --> J
    J --> K[getLowestVersions]
    K --> L[各ターゲットパース]
    L --> M[Targets返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-75-01 | ターゲット名検証 | chrome、firefox、node等の定義済みターゲットのみ許可 | ターゲット指定時 |
| BR-75-02 | 小数バージョン警告 | 6.10等の小数バージョンは6.1と解釈される可能性を警告 | 小数バージョン指定時 |
| BR-75-03 | node: true解釈 | trueの場合は現在のNode.jsバージョンを使用 | node: true指定時 |
| BR-75-04 | デフォルトbrowsers | 設定がない場合は["defaults"]を使用 | 設定なし時 |
| BR-75-05 | キャッシュ | browserslist解析結果を最大64件キャッシュ | 常時 |

### 計算ロジック

**最小バージョン算出**：
```
複数バージョンがある場合 → semverで最小を選択
未リリース版（tp等） → 文字列のまま保持
バージョン範囲（10.0-10.2） → 範囲の開始値を使用
```

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

### 操作別データベース影響一覧

データベース操作なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 検証エラー | 無効なターゲット名 | 有効なターゲット名を使用（提案表示あり） |
| - | 検証エラー | 無効なbrowserslistクエリ | 有効なクエリに修正 |
| - | バージョンエラー | 無効なバージョン形式 | semver形式（major.minor.patch）を使用 |

### リトライ仕様

リトライ対象外

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

トランザクション処理なし

## パフォーマンス要件

- LRUキャッシュ（max: 64）によるbrowserslist解析結果のキャッシュ
- 同一クエリの再解析を回避

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

特になし

## 備考

- @babel/preset-envの中核依存パッケージ
- browserslistの環境変数（BROWSERSLIST）もサポート
- mobileToDesktop: trueでモバイルブラウザをデスクトップ版として扱う

---

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

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

### 推奨読解順序

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

まず、型定義とターゲットの定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | targets.ts | `packages/babel-helper-compilation-targets/src/targets.ts` | browserNameMapの定義（6-22行目） |
| 1-2 | options.ts | `packages/babel-helper-compilation-targets/src/options.ts` | TargetNamesの定義 |

**読解のコツ**: browserNameMapはbrowserslistの出力をBabel内部のターゲット名にマッピングする。and_chr→chrome、ios_saf→iosなどの変換ルールを理解する。

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

メインのgetTargets関数を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/babel-helper-compilation-targets/src/index.ts` | getTargets関数の定義（204-316行目） |

**主要処理フロー**:
1. **208行目**: inputTargetsからbrowsers、esmodulesを取得
2. **210行目**: validateBrowsersでbrowsersの検証
3. **213行目**: generateTargetsでtargetsオブジェクト生成
4. **221-242行目**: browserslist設定の解決（環境変数、設定ファイル、デフォルト）
5. **246-255行目**: esmodules時のESM対応ブラウザ設定
6. **260-289行目**: browserslist解析とesmodules適用
7. **291-313行目**: 各ターゲットのパースと警告出力

#### Step 3: フィルタリング処理を理解する

プラグイン要否判定のロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | filter-items.ts | `packages/babel-helper-compilation-targets/src/filter-items.ts` | isRequired関数（60-76行目） |
| 3-2 | filter-items.ts | `packages/babel-helper-compilation-targets/src/filter-items.ts` | filterItems関数（78-106行目） |

**主要処理フロー**:
- **60-76行目**: isRequired - excludesチェック、includesチェック、targetsSupported判定
- **78-106行目**: filterItems - プラグインリストをフィルタリング

#### Step 4: ユーティリティ関数を理解する

バージョン処理のユーティリティを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | utils.ts | `packages/babel-helper-compilation-targets/src/utils.ts` | semverify、semverMin、isUnreleasedVersion関数 |

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

```
@babel/helper-compilation-targets/src/index.ts
    │
    ├─ getTargets()
    │      ├─ validateBrowsers()
    │      ├─ validateTargetNames()
    │      ├─ generateTargets()
    │      ├─ resolveTargetsCached()
    │      │      └─ resolveTargets()
    │      │             └─ browserslist()
    │      │                    └─ getLowestVersions()
    │      ├─ nodeTargetParser()
    │      └─ defaultTargetParser()
    │
    ├─ filterItems()
    │      └─ isRequired()
    │             └─ targetsSupported()
    │
    └─ prettifyTargets() / getInclusionReasons()
```

### データフロー図

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

InputTargets ───▶ getTargets() ───▶ Targets
  - browsers                │
  - esmodules               │
  - targets                 ▼
         ┌──────────────────┼──────────────────┐
         ▼                  ▼                  ▼
   validateTargetNames  browserslist()    esmodules処理
         │                  │                  │
         └──────────────────┼──────────────────┘
                            ▼
                   getLowestVersions()
                            │
                            ▼
                     Targets返却
                            │
                            ▼
                   filterItems() / isRequired()
                            │
                            ▼
                   プラグイン要否
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-helper-compilation-targets/src/index.ts` | ソース | メインエントリーポイント |
| targets.ts | `packages/babel-helper-compilation-targets/src/targets.ts` | ソース | ターゲット名マッピング |
| options.ts | `packages/babel-helper-compilation-targets/src/options.ts` | ソース | ターゲット名定義 |
| filter-items.ts | `packages/babel-helper-compilation-targets/src/filter-items.ts` | ソース | プラグインフィルタリング |
| utils.ts | `packages/babel-helper-compilation-targets/src/utils.ts` | ソース | バージョン処理ユーティリティ |
| pretty.ts | `packages/babel-helper-compilation-targets/src/pretty.ts` | ソース | ターゲット表示整形 |
| debug.ts | `packages/babel-helper-compilation-targets/src/debug.ts` | ソース | デバッグ情報出力 |
| types.d.ts | `packages/babel-helper-compilation-targets/src/types.d.ts` | 型定義 | 型定義ファイル |
