# 機能設計書 1-@babel/core

## 概要

本ドキュメントは、Babelコンパイラのコア機能である`@babel/core`パッケージの設計仕様を記述する。このパッケージは、JavaScriptコードの変換処理を統括するエントリーポイントとして機能し、`babel.transform`メソッドを公開してコード変換を実行する。

### 本機能の処理概要

**業務上の目的・背景**：モダンJavaScript（ES2015+）やTypeScript、JSX等の構文を使用して開発されたコードを、ターゲット環境（古いブラウザやNode.js）で実行可能な形式に変換する必要がある。@babel/coreは、この変換プロセスの中核を担い、プラグインやプリセットを通じて柔軟なコード変換を実現する。開発者は最新の言語機能を使用しながら、幅広い環境への互換性を維持できる。

**機能の利用シーン**：ビルドプロセス中にWebpackやRollup等のバンドラーから呼び出される場合、CLI経由でファイルやディレクトリを変換する場合、またはプログラマティックにコード変換を行う場合に利用される。CI/CDパイプライン、開発サーバー、テスト環境など、あらゆる開発フェーズで活用される。

**主要な処理内容**：
1. 設定ファイル（babel.config.js、.babelrc等）の読み込みと解析
2. プラグイン・プリセットの解決と初期化
3. 入力コードの抽象構文木（AST）への変換（@babel/parserを使用）
4. プラグインによるASTの走査と変換（@babel/traverseを使用）
5. 変換後のASTからJavaScriptコードの生成（@babel/generatorを使用）
6. ソースマップの生成と管理

**関連システム・外部連携**：@babel/parser（構文解析）、@babel/traverse（AST走査）、@babel/generator（コード生成）、各種プラグイン・プリセットと連携する。また、Webpack babel-loader、Rollup @rollup/plugin-babel、Jest babel-jest等のツールから呼び出される。

**権限による制御**：特になし。ファイルシステムへのアクセス権限はNode.js実行環境に依存する。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | Babelトランスフォームデモ | API連携 | Babel.transformメソッドを通じてコード変換を実行 |
| 2 | インラインスクリプトタグデモ | API連携 | transformScriptTags経由でBabel.transformを呼び出しコード変換 |
| 3 | 外部スクリプトタグデモ | API連携 | transformScriptTags経由でBabel.transformを呼び出しコード変換 |
| 4 | カスタムスクリプトタグデモ | API連携 | transformScriptTags経由でBabel.transformを呼び出しコード変換 |

## 機能種別

コード変換処理（トランスパイラ）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| code | string | Yes | 変換対象のJavaScriptソースコード | 空文字列も許容 |
| opts | InputOptions | No | 変換オプション | オブジェクト形式 |
| opts.filename | string | No | ソースファイル名（エラー表示・ソースマップ用） | - |
| opts.presets | PluginItem[] | No | 使用するプリセットの配列 | 有効なプリセット名/パス |
| opts.plugins | PluginItem[] | No | 使用するプラグインの配列 | 有効なプラグイン名/パス |
| opts.sourceMaps | boolean \| "inline" \| "both" | No | ソースマップ生成の有無と形式 | 指定値のみ |
| opts.sourceType | "script" \| "module" \| "unambiguous" | No | ソースコードの種別 | 指定値のみ |
| opts.configFile | string \| boolean | No | 設定ファイルのパス | 有効なパス |
| opts.babelrc | boolean | No | .babelrcファイルの検索有無 | boolean |
| opts.envName | string | No | 使用する環境名 | - |
| opts.caller | CallerMetadata | No | 呼び出し元の情報 | オブジェクト形式 |
| opts.targets | string \| object | No | ターゲット環境の指定 | browserslistクエリまたはオブジェクト |

### 入力データソース

- 画面入力（ブラウザ環境でのリアルタイム変換）
- ファイルシステム（CLIやビルドツール経由）
- 標準入力（パイプライン処理）
- プログラム内の文字列データ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| code | string \| null | 変換後のJavaScriptコード |
| map | object \| null | ソースマップオブジェクト |
| ast | t.File \| null | 変換後のAST（opts.ast=trueの場合） |
| metadata | object | プラグインから出力されたメタデータ |
| options | object | 使用された変換オプション |
| sourceType | "script" \| "module" | 検出されたソースタイプ |
| externalDependencies | Set<string> | 外部依存ファイルのセット |

### 出力先

- 変数への代入（プログラマティック利用）
- ファイルシステムへの書き込み（CLI経由）
- 標準出力（パイプライン処理）
- ビルドツールへの返却（バンドラー連携）

## 処理フロー

### 処理シーケンス

```
1. transform関数の呼び出し
   └─ 入力コードとオプションを受け取る
2. 設定の読み込み (loadConfig)
   └─ babel.config.js、.babelrc等から設定を解決
   └─ プリセット・プラグインを初期化
3. コード正規化 (normalizeFile)
   └─ 入力コードをAST形式に変換
   └─ @babel/parserを使用してパース
4. AST変換 (transformFile)
   └─ プラグインのpre hookを実行
   └─ visitorをマージしてASTを走査
   └─ @babel/traverseでノードを変換
   └─ プラグインのpost hookを実行
5. コード生成 (generateCode)
   └─ @babel/generatorでASTをコードに変換
   └─ ソースマップを生成
6. 結果オブジェクトの構築
   └─ code, map, ast, metadata等を返却
```

### フローチャート

```mermaid
flowchart TD
    A[transform呼び出し] --> B[loadConfig: 設定読み込み]
    B --> C{設定が有効?}
    C -->|No| D[null を返却]
    C -->|Yes| E[normalizeFile: AST生成]
    E --> F[transformFile: プラグイン適用]
    F --> G{opts.code !== false?}
    G -->|Yes| H[generateCode: コード生成]
    G -->|No| I[コード生成をスキップ]
    H --> J[FileResult構築]
    I --> J
    J --> K[結果を返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 設定マージ | 複数の設定ファイルは優先度に従ってマージされる | 複数設定が存在する場合 |
| BR-02 | プリセット展開 | プリセットは逆順で適用される（最初に書かれたものが最後に適用） | プリセット指定時 |
| BR-03 | プラグイン順序 | プラグインは記述順で適用される | プラグイン指定時 |
| BR-04 | sourceType判定 | unambiguous指定時はESM構文の有無で自動判定 | sourceType: "unambiguous" |
| BR-05 | キャッシュ | 設定とプラグインの解決結果はキャッシュされる | 同一設定での複数回呼び出し |

### 計算ロジック

特になし

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

該当なし（メモリ内処理のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| BABEL_TRANSFORM_ERROR | 変換エラー | プラグイン実行中のエラー | エラーメッセージにファイル名を付加して再throw |
| BABEL_GENERATE_ERROR | 生成エラー | コード生成中のエラー | エラーメッセージにファイル名を付加して再throw |
| BABEL_PARSE_ERROR | パースエラー | 構文エラー | 行番号・列番号付きのエラーメッセージを表示 |
| BABEL_HELPER_UNKNOWN | ヘルパーエラー | 不明なヘルパー参照 | ヘルパー名をエラーメッセージに含める |

### リトライ仕様

リトライ機能なし（同期処理のため）

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

該当なし（ステートレスな変換処理）

## パフォーマンス要件

- 大規模ファイル（500KB超）では自動的にcompactモードが有効化される
- 設定解決結果はキャッシュされ、同一設定での再実行は高速化される
- gensyncを使用した同期/非同期両対応の実装により、呼び出し元の要件に柔軟に対応

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

- 入力コードはそのまま処理され、サニタイズは行われない（信頼できるソースからの入力を前提）
- プラグインは任意のNode.jsコードを実行可能なため、信頼できるプラグインのみを使用すること
- ファイルシステムアクセスは設定ファイル読み込みとプラグイン解決に限定

## 備考

- Babel 8.0.0以降では、transform関数にコールバックが必須となる（同期実行にはtransformSyncを使用）
- DEFAULT_EXTENSIONS定数として推奨拡張子（.js, .jsx, .es6, .es, .mjs, .cjs）が提供される

---

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

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

### 推奨読解順序

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

まず、入出力のデータ構造を把握することで、処理全体の流れを理解しやすくなる。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | options.ts | `packages/babel-core/src/config/validation/options.ts` | InputOptions、ResolvedOptionsの型定義を確認 |
| 1-2 | index.ts (transformation) | `packages/babel-core/src/transformation/index.ts` | FileResult型（26-34行目）の構造を理解 |

**読解のコツ**: TypeScriptの型定義を最初に確認することで、関数の入出力が明確になる。

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

処理の起点となるファイル・関数を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/babel-core/src/index.ts` | 公開APIの一覧とre-exportの構造を把握 |
| 2-2 | transform.ts | `packages/babel-core/src/transform.ts` | transform関数の実装を確認 |

**主要処理フロー**:
1. **21-29行目**: transformRunner - gensyncでラップされたメイン処理
2. **25行目**: loadConfigで設定を読み込み
3. **28行目**: runで変換を実行
4. **31-54行目**: transform関数 - コールバック形式のAPI

#### Step 3: 設定読み込み処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config/index.ts | `packages/babel-core/src/config/index.ts` | loadFullConfig、loadPartialConfigの流れ |
| 3-2 | full.ts | `packages/babel-core/src/config/full.ts` | プラグイン・プリセットの完全解決 |
| 3-3 | partial.ts | `packages/babel-core/src/config/partial.ts` | 部分的な設定読み込み |

**主要処理フロー**:
- **73-79行目** (index.ts): loadOptionsImplで設定を読み込みオプションを返却

#### Step 4: 変換処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | transformation/index.ts | `packages/babel-core/src/transformation/index.ts` | run関数とtransformFile関数 |
| 4-2 | normalize-file.ts | `packages/babel-core/src/transformation/normalize-file.ts` | ソースコードのAST化 |
| 4-3 | file/generate.ts | `packages/babel-core/src/transformation/file/generate.ts` | ASTからコード生成 |

**主要処理フロー**:
- **36-81行目**: run関数 - 変換の全体フロー
- **41-46行目**: normalizeFileでAST生成
- **50行目**: transformFileでプラグイン適用
- **62行目**: generateCodeでコード生成
- **83-133行目**: transformFile関数 - プラグインのvisitor実行

#### Step 5: パーサー連携を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | parser/index.ts | `packages/babel-core/src/parser/index.ts` | @babel/parserの呼び出し方法 |
| 5-2 | parse.ts | `packages/babel-core/src/parse.ts` | parse API の実装 |

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

```
@babel/core (index.ts)
    │
    ├─ transform / transformSync / transformAsync
    │      │
    │      ├─ loadConfig (config/index.ts → full.ts)
    │      │      ├─ loadPartialConfig (partial.ts)
    │      │      └─ プラグイン/プリセット解決 (files/plugins.ts)
    │      │
    │      └─ run (transformation/index.ts)
    │             ├─ normalizeFile → @babel/parser
    │             ├─ transformFile
    │             │      ├─ plugin.pre hooks
    │             │      ├─ traverse.visitors.merge
    │             │      ├─ @babel/traverse
    │             │      └─ plugin.post hooks
    │             └─ generateCode → @babel/generator
    │
    ├─ parse / parseSync / parseAsync
    │      └─ parser (parser/index.ts) → @babel/parser
    │
    └─ transformFile / transformFromAst
           └─ (上記transformと同様の流れ)
```

### データフロー図

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

ソースコード ───────▶ @babel/parser ───────▶ AST
(string)               (parse)

     オプション ───────▶ loadConfig ───────▶ ResolvedConfig
     (InputOptions)      (config)           (plugins, presets)

               AST + Config ───────▶ transformFile ───────▶ 変換済みAST
                                      (@babel/traverse)

               変換済みAST ───────▶ generateCode ───────▶ FileResult
                                   (@babel/generator)    (code, map, ast)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-core/src/index.ts` | ソース | 公開APIのエントリーポイント |
| transform.ts | `packages/babel-core/src/transform.ts` | ソース | transform系関数の実装 |
| transform-ast.ts | `packages/babel-core/src/transform-ast.ts` | ソース | transformFromAst系関数の実装 |
| transform-file.ts | `packages/babel-core/src/transform-file.ts` | ソース | transformFile系関数の実装 |
| parse.ts | `packages/babel-core/src/parse.ts` | ソース | parse系関数の実装 |
| config/index.ts | `packages/babel-core/src/config/index.ts` | ソース | 設定読み込みの公開API |
| config/full.ts | `packages/babel-core/src/config/full.ts` | ソース | 完全な設定解決 |
| config/partial.ts | `packages/babel-core/src/config/partial.ts` | ソース | 部分的な設定解決 |
| transformation/index.ts | `packages/babel-core/src/transformation/index.ts` | ソース | 変換処理のメインロジック |
| transformation/normalize-file.ts | `packages/babel-core/src/transformation/normalize-file.ts` | ソース | ファイル正規化・AST生成 |
| transformation/file/generate.ts | `packages/babel-core/src/transformation/file/generate.ts` | ソース | コード生成処理 |
| transformation/plugin-pass.ts | `packages/babel-core/src/transformation/plugin-pass.ts` | ソース | プラグイン実行コンテキスト |
| parser/index.ts | `packages/babel-core/src/parser/index.ts` | ソース | パーサー呼び出し |
