# アーキテクチャ設計書

## 概要

本ドキュメントは、Babel JavaScriptコンパイラプロジェクトのアーキテクチャ設計を記述するものである。Babelは次世代JavaScriptの構文を現行のJavaScript環境で動作可能なコードに変換（トランスパイル）するためのツールチェーンである。

## システム全体構成

### アーキテクチャ概要図

詳細なアーキテクチャ構成図は[アーキテクチャ構成図.md](./アーキテクチャ構成図.md)を参照。

### システム境界と外部連携

| 外部システム | 連携方式 | 用途 |
| --- | --- | --- |
| Node.js | ネイティブモジュール | ランタイム実行環境 |
| npm/Yarn | パッケージマネージャ | パッケージ配布・依存関係管理 |
| browserslist | 設定ファイル参照 | ターゲット環境の解決 |
| caniuse-lite | データ参照 | ブラウザ互換性データ |
| core-js | ポリフィル連携 | ランタイムポリフィル提供 |
| ESLint | プラグイン連携 | Babel構文を含むコードのリンティング |

## レイヤー構成

### アーキテクチャスタイル

**パイプライン・アーキテクチャ（Compiler Pipeline）** + **プラグインアーキテクチャ**

Babelは古典的なコンパイラパイプラインアーキテクチャを採用しており、以下の3段階処理で構成される：
1. **Parse（構文解析）**: ソースコード → AST
2. **Transform（変換）**: AST → AST（プラグインによる変換）
3. **Generate（コード生成）**: AST → ソースコード

### レイヤー定義

| レイヤー | 責務 | 主なコンポーネント |
| --- | --- | --- |
| CLI/API Layer | ユーザーインターフェース提供、オプション解析 | `@babel/cli`, `@babel/core` API |
| Configuration Layer | 設定ファイル解決、プリセット/プラグイン読み込み | `@babel/core/config` |
| Parser Layer | ソースコードからAST生成 | `@babel/parser` |
| Transform Layer | AST変換、プラグイン実行 | `@babel/traverse`, plugins, presets |
| Generator Layer | ASTからソースコード生成 | `@babel/generator` |
| Type Layer | AST型定義、ノード操作ユーティリティ | `@babel/types` |
| Helper Layer | 共通ヘルパー関数、コード生成支援 | `@babel/helpers`, `@babel/template` |

### レイヤー間の依存関係ルール

```
依存の方向性:
CLI/API Layer
    ↓
Configuration Layer
    ↓
Parser Layer ← Transform Layer → Generator Layer
                    ↓
                Type Layer
                    ↓
                Helper Layer
```

**許可される参照:**
- 上位レイヤーから下位レイヤーへの参照
- Transform Layerから Parser Layer, Generator Layer, Type Layerへの参照
- 全レイヤーから Helper Layerへの参照

**禁止される参照:**
- 下位レイヤーから上位レイヤーへの参照
- Parser LayerとGenerator Layer間の直接参照（Type Layerを介して間接的に連携）

## モジュール構成

### ドメイン分割

| ドメイン | 責務 | 関連モジュール |
| --- | --- | --- |
| Core | コンパイラコア機能、設定管理、変換オーケストレーション | `babel-core` |
| Parser | ECMAScript/TypeScript/Flow/JSX構文解析 | `babel-parser` |
| Transform | AST走査・変換基盤 | `babel-traverse` |
| CodeGen | ソースコード生成、ソースマップ生成 | `babel-generator` |
| Types | AST型システム、ノードビルダー・バリデータ | `babel-types` |
| Plugins | ES機能変換プラグイン群 | `babel-plugin-transform-*` |
| Presets | プラグインセット管理 | `babel-preset-env`, `babel-preset-react`, etc. |
| Helpers | ランタイムヘルパー、コードテンプレート | `babel-helpers`, `babel-template`, `babel-runtime` |
| Tools | CLI、レジスタ、スタンドアロン版 | `babel-cli`, `babel-node`, `babel-register`, `babel-standalone` |
| ESLint | ESLint連携 | `babel-eslint-parser`, `babel-eslint-plugin` |

### パッケージ構造

```
babel/
├── packages/               # コアパッケージ群
│   ├── babel-core/        # コンパイラコア
│   │   └── src/
│   │       ├── config/    # 設定システム
│   │       ├── transformation/  # 変換オーケストレーション
│   │       └── parser/    # パーサー連携
│   ├── babel-parser/      # JavaScriptパーサー
│   │   └── src/
│   │       ├── parser/    # パーサー実装
│   │       ├── tokenizer/ # トークナイザー
│   │       └── plugins/   # 構文プラグイン（typescript, flow, jsx）
│   ├── babel-traverse/    # AST走査
│   │   └── src/
│   │       ├── path/      # NodePath API
│   │       └── scope/     # スコープ解析
│   ├── babel-generator/   # コード生成
│   │   └── src/
│   │       ├── generators/  # ノードタイプ別ジェネレータ
│   │       └── printer.ts   # コード出力
│   ├── babel-types/       # AST型定義
│   │   └── src/
│   │       ├── builders/   # ノードビルダー
│   │       ├── validators/ # バリデーション
│   │       └── definitions/ # ノード定義
│   ├── babel-template/    # コードテンプレート
│   ├── babel-helpers/     # ランタイムヘルパー
│   ├── babel-runtime/     # ランタイムライブラリ
│   ├── babel-cli/         # CLIツール
│   ├── babel-node/        # Node.js統合
│   ├── babel-register/    # require hook
│   ├── babel-standalone/  # ブラウザバンドル
│   ├── babel-preset-env/  # 環境ベースプリセット
│   ├── babel-preset-react/      # React プリセット
│   ├── babel-preset-typescript/ # TypeScript プリセット
│   ├── babel-preset-flow/       # Flow プリセット
│   ├── babel-plugin-transform-*/  # 変換プラグイン群（70+）
│   ├── babel-plugin-proposal-*/   # Stage プラグイン群
│   ├── babel-plugin-syntax-*/     # 構文プラグイン群
│   ├── babel-helper-*/            # ヘルパーパッケージ群
│   └── babel-compat-data/         # 互換性データ
├── eslint/                # ESLint連携パッケージ
│   ├── babel-eslint-parser/
│   └── babel-eslint-plugin/
├── codemods/              # コードmod変換
├── scripts/               # ビルド・開発スクリプト
├── test/                  # 統合テスト
└── benchmark/             # パフォーマンスベンチマーク
```

### コンポーネント依存関係

**コアパッケージ依存関係:**

```
@babel/cli
    └── @babel/core
            ├── @babel/parser
            ├── @babel/traverse
            │       └── @babel/types
            ├── @babel/generator
            │       └── @babel/types
            ├── @babel/template
            │       ├── @babel/parser
            │       └── @babel/types
            └── @babel/types

@babel/preset-env
    ├── @babel/core
    ├── @babel/helper-compilation-targets
    ├── @babel/compat-data
    └── @babel/plugin-transform-* (多数)
```

## ミドルウェア構成

### データベース

| 種類 | ミドルウェア | バージョン | 用途 |
| --- | --- | --- | --- |
| 該当なし | - | - | Babelはステートレスなコンパイラであり、データベースは使用しない |

### キャッシュ

| ミドルウェア | バージョン | 用途 | TTL |
| --- | --- | --- | --- |
| ファイルシステムキャッシュ | - | 変換結果キャッシュ（@babel/register使用時） | 設定変更まで |
| インメモリキャッシュ | - | パーサークラスキャッシュ、設定解決キャッシュ | プロセスライフタイム |

### メッセージキュー

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| 該当なし | - | Babelはリアルタイム処理のため、メッセージキューは使用しない |

### 検索エンジン

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| 該当なし | - | - |

### その他ミドルウェア

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| gensync | 最新 | 同期/非同期API統一 |
| semver | ^7.7.3 | バージョン比較 |
| browserslist | 4.28.1 | ターゲット環境解決 |

## データフロー

### リクエスト処理の流れ

**同期変換フロー（transformSync）:**

1. `@babel/core.transformSync(code, options)` 呼び出し
2. 設定解決（`config/index.ts`）
   - babel.config.js, .babelrc 等の読み込み
   - プリセット・プラグインの解決と読み込み
3. ファイル正規化（`transformation/normalize-file.ts`）
   - ソースコードのパース
   - `@babel/parser.parse(code)` → AST生成
4. 変換実行（`transformation/index.ts`）
   - プラグインチェーンの構築
   - `@babel/traverse` によるAST走査
   - 各プラグインのvisitorによるAST変換
5. コード生成（`@babel/generator`）
   - AST → ソースコード変換
   - ソースマップ生成（オプション）
6. 結果返却 `{ code, map, ast }`

### 非同期処理の流れ

**非同期変換フロー（transformAsync）:**

1. `@babel/core.transformAsync(code, options)` 呼び出し
2. gensyncによる非同期実行ラッパー
3. 設定解決（非同期対応）
   - 非同期プリセット/プラグインローダーのサポート
4. 変換実行（同期と同様）
5. Promise返却

**CLIバッチ処理:**

1. `babel src --out-dir lib` コマンド実行
2. ソースディレクトリの走査
3. ファイル単位での並列変換（jest-worker使用）
4. 出力ディレクトリへの書き出し

### データ永続化の流れ

**キャッシュ永続化（@babel/register）:**

1. require()フック発火
2. キャッシュファイル存在確認
3. キャッシュヒット → 変換スキップ
4. キャッシュミス → 変換実行 → キャッシュ保存

## 横断的関心事

### 認証・認可

| 方式 | 実装箇所 | 対象 |
| --- | --- | --- |
| 該当なし | - | Babelはローカル実行のコンパイラであり、認証・認可機構は不要 |

### ロギング・監査

| 種類 | 実装方式 | 保存先 |
| --- | --- | --- |
| デバッグログ | `debug`オプション（preset-env） | stdout |
| ビルドログ | CLIオプション（`--verbose`） | stdout |
| エラーレポート | code-frame形式 | stderr |

### エラーハンドリング

| エラー種別 | ハンドリング方式 | レスポンス |
| --- | --- | --- |
| 構文エラー | `@babel/parser` ParseError | code-frame付きエラーメッセージ |
| 設定エラー | ConfigError | スタックトレース付きエラー |
| プラグインエラー | プラグイン内部エラー | code-frame付きエラーメッセージ |
| 変換エラー | NodePath.buildCodeFrameError | ソースコード位置付きエラー |

### トランザクション管理

| 範囲 | 管理方式 | 分離レベル |
| --- | --- | --- |
| AST変換 | 単一ファイル単位 | ファイル間の分離 |
| プラグイン実行 | 順序保証（pre → normal → post） | プラグイン間は共有状態 |

## 設計原則・コーディング規約

### 適用している設計原則

| 原則 | 適用箇所 | 実装例 |
| --- | --- | --- |
| Visitor Pattern | AST走査 | `@babel/traverse` のvisitor API |
| Plugin Architecture | 変換処理 | transform/proposal/syntax plugins |
| Factory Pattern | ASTノード生成 | `@babel/types` builders |
| Chain of Responsibility | プラグイン実行 | pre → normal → post plugin chain |
| Immutability | AST操作 | `cloneNode()` による安全な操作 |
| Dependency Injection | 設定システム | プリセット・プラグインの動的読み込み |

### コーディング規約

- **言語**: TypeScript（ESM）
- **フォーマッタ**: Prettier
- **リンター**: ESLint（TypeScript ESLint）
- **テストフレームワーク**: Jest
- **パッケージ管理**: Yarn Workspaces（モノレポ）
- **ビルドシステム**: Gulp + Rollup
- **TypeScript設定**:
  - `strict: true`
  - ESM出力（`type: "module"`）
  - Node.js 20.19+ 対応

## 備考

### バージョン情報
- 本ドキュメントはBabel 8.0.0-rc.2をベースに作成
- Babel 9対応のフラグ（`process.env.BABEL_9_BREAKING`）が存在

### モノレポ構成
- 150以上のパッケージを単一リポジトリで管理
- Yarn Workspacesによる依存関係管理
- 独自のリリースツール（`yarn-plugin-babel-release-tool`）を使用

### パフォーマンス最適化
- パーサークラスのキャッシュ（プラグイン組み合わせ別）
- gensyncによる同期/非同期APIの統一
- babel-plugin-transform-charcodesによる文字コード最適化
