# 機能設計書 6-Babelトランスパイル

## 概要

本ドキュメントは、生成されたJavaScriptをBabelでトランスパイルし、古いブラウザ/Node.js向けに変換する機能について、その処理内容、入出力仕様、およびコードリーディングガイドを記載したものである。

### 本機能の処理概要

Babelトランスパイル機能は、CoffeeScriptからコンパイルされたES6+のJavaScriptコードを、Babelを使用してES5互換コードに変換する機能である。

**業務上の目的・背景**：CoffeeScript 2.xはES6+のJavaScriptを出力するが、古いブラウザ（IE11等）やNode.jsの古いバージョンでは、アロー関数、クラス構文、テンプレートリテラルなどのES6+機能をサポートしていない。Babelトランスパイルにより、これらの環境でも動作するコードを生成できる。

**機能の利用シーン**：IE11などの古いブラウザをサポートする必要がある場合、古いNode.jsバージョン（v6以前等）で動作させる場合、特定のBabelプリセット/プラグインを適用したい場合に利用される。

**主要な処理内容**：
1. Babelモジュールの動的ロード
2. コンパイル済みJavaScriptの受け取り
3. ソースマップの連携（inputSourceMap）
4. Babelトランスパイルの実行
5. 変換後コードとソースマップの取得

**関連システム・外部連携**：`@babel/core`または`babel-core`モジュール

**権限による制御**：特になし（すべてのユーザーが利用可能）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLI | 主機能 | `coffee --transpile`コマンドでBabelトランスパイル |

## 機能種別

計算処理 / コード変換

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| options.transpile | object | Yes | Babelオプション | オブジェクトであること |
| options.transpile.presets | array | No | Babelプリセット配列 | - |
| options.transpile.plugins | array | No | Babelプラグイン配列 | - |
| inputSourceMap | object | No | 入力ソースマップ（自動設定） | V3形式 |

### 入力データソース

- CoffeeScriptコンパイル結果のJavaScriptコード
- CoffeeScriptコンパイル時に生成されたソースマップ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| code | string | トランスパイル後のJavaScriptコード |
| map | object | 更新されたソースマップ |

### 出力先

- compile関数の戻り値（js, v3SourceMap）に統合

## 処理フロー

### 処理シーケンス

```
1. transpileオプション検証
   └─ オブジェクトでなければエラー

2. Babelモジュール取得
   └─ options.transpile.transpileから取得

3. オプション準備
   └─ transpileオプションをコピー

4. ソースマップ連携
   └─ v3SourceMapをinputSourceMapとして設定

5. Babelトランスパイル実行
   └─ transpiler(js, transpilerOptions)

6. 結果取得
   └─ code（変換コード）とmap（更新ソースマップ）

7. 出力変数更新
   └─ js = transpilerOutput.code
   └─ v3SourceMap = transpilerOutput.map
```

### フローチャート

```mermaid
flowchart TD
    A[開始: transpileオプションあり] --> B{transpileがオブジェクト?}
    B -->|No| C[Error: オブジェクト必須]
    B -->|Yes| D[transpiler取得]
    D --> E[transpileオプションからtranspile削除]
    E --> F[オプションコピー]
    F --> G{v3SourceMapあり?}
    G -->|Yes| H[inputSourceMap設定]
    G -->|No| I[Babelトランスパイル実行]
    H --> I
    I --> J[transpilerOutput取得]
    J --> K[js = transpilerOutput.code]
    K --> L{v3SourceMap & transpilerOutput.map?}
    L -->|Yes| M[v3SourceMap更新]
    L -->|No| N[続行]
    M --> N
    N --> O[終了]
    C --> P[エラースロー]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | オブジェクト必須 | transpileオプションはオブジェクトでなければならない | transpileオプション指定時 |
| BR-02 | ソースマップ継続 | CoffeeScriptのソースマップをBabelに渡して連鎖 | v3SourceMap生成時 |
| BR-03 | Babel自動検出 | @babel/coreを優先、なければbabel-coreを使用 | Node.js API使用時 |

### 計算ロジック

特になし（Babelに委譲）

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| Error | transpileオプションエラー | transpileがオブジェクトでない | オブジェクト形式で指定 |
| Error | Babelモジュール未インストール | @babel/core/babel-coreがない | npm install @babel/core |
| BabelError | トランスパイルエラー | Babel処理中のエラー | Babelエラーメッセージを確認 |

### リトライ仕様

リトライは行わない

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

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

## パフォーマンス要件

- Babelトランスパイルの時間はコードサイズとプラグイン数に依存
- 大規模プロジェクトではビルドキャッシュの活用を推奨

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

- Babelプラグインは信頼できるソースからインストールすること

## 備考

- `@babel/core` v7.x を推奨
- babel-coreは非推奨（レガシーサポート用）

---

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

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

### 推奨読解順序

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

まず、transpileオプションの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | coffeescript.coffee | `src/coffeescript.coffee` | 142-163行目でtranspileオプションの処理フローを確認 |

**読解のコツ**: transpileオプションはBabelのオプションをそのまま渡す形式。presets, plugins等を含むことができる。

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

Node.js環境でのBabel連携を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.coffee | `src/index.coffee` | `transpile`関数（9-19行目）でBabelモジュール読み込み |
| 2-2 | index.coffee | `src/index.coffee` | `compile`関数（24-31行目）でtranspile参照設定 |

**主要処理フロー**:
1. **9-18行目**: @babel/coreまたはbabel-coreをrequire
2. **19行目**: babel.transformでトランスパイル実行
3. **29-30行目**: transpile.transpileにtranspile関数参照を設定

#### Step 3: コンパイル内での呼び出しを理解する

compile関数内でのBabel連携処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | coffeescript.coffee | `src/coffeescript.coffee` | 142-163行目のtranspile処理 |

**主要処理フロー**:
- **142-143行目**: transpileオプションの型チェック
- **150-151行目**: transpiler関数の取得と削除
- **153行目**: オプションのコピー
- **158-159行目**: inputSourceMapの設定
- **160行目**: トランスパイル実行
- **161-163行目**: 結果の取得と更新

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

```
CoffeeScript.compile (coffeescript.coffee:62)
    │
    └─ [transpileオプションあり時]
           │
           ├─ オプション検証 (coffeescript.coffee:142-146)
           │
           ├─ transpiler取得 (coffeescript.coffee:150)
           │      │
           │      └─ CoffeeScript.transpile (index.coffee:9)
           │             ├─ require '@babel/core'
           │             └─ babel.transform
           │
           ├─ inputSourceMap設定 (coffeescript.coffee:158-159)
           │
           └─ transpiler実行 (coffeescript.coffee:160)
                  └─ babel.transform(js, options)
```

### データフロー図

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

JavaScript        ──▶  CoffeeScript.transpile   ──▶  babel.transform
(ES6+)                  │
                       ▼
                  @babel/core              ──▶  トランスパイル済みJS
                  または babel-core             (ES5互換)
                       │
                       ▼
V3 SourceMap      ──▶  inputSourceMap設定   ──▶  更新されたSourceMap
(CoffeeScript)                                   (CoffeeScript→ES5の
                                                 連鎖マッピング)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.coffee | `src/index.coffee` | ソース | transpile関数定義、Node.js向けcompile |
| coffeescript.coffee | `src/coffeescript.coffee` | ソース | transpileオプション処理 |
| @babel/core | `node_modules/@babel/core` | 外部モジュール | Babelトランスパイラ本体 |
