# 機能設計書 29 --transpile オプション

## 概要

本ドキュメントは、CoffeeScript CLIツールの `--transpile` (`-t`) オプションの機能設計を記述する。このオプションは、CoffeeScriptからコンパイルされたJavaScriptをさらにBabelでトランスパイルし、古いブラウザやNode.jsバージョン向けに変換する機能を提供する。

### 本機能の処理概要

`--transpile` オプションは、CoffeeScriptコンパイル後のJavaScriptコードをBabelトランスパイラに渡し、ES5など古い環境でも動作するコードに変換する機能を提供する。CoffeeScriptはES6+の機能（クラス、アロー関数、テンプレートリテラルなど）を使用したJavaScriptを生成するため、古い実行環境のサポートが必要な場合にBabelとの連携が有用である。

**業務上の目的・背景**：CoffeeScript 2.xはモダンなES6+ JavaScriptを生成する。しかし、IE11などの古いブラウザや、古いバージョンのNode.jsではES6+の機能がサポートされていない。`--transpile` オプションにより、Babelを使用してES5互換のコードに変換でき、幅広い環境での動作を保証できる。

**機能の利用シーン**：
- IE11など古いブラウザをサポートする必要がある場合
- 古いNode.jsバージョンでスクリプトを実行する必要がある場合
- 特定のBabelプラグイン（デコレータ、プロポーザルなど）を適用したい場合
- ポリフィルと組み合わせて古い環境での互換性を確保したい場合

**主要な処理内容**：
1. @babel/core または babel-core モジュールをロード
2. CoffeeScriptコンパイル後のJavaScriptコードを取得
3. Babel.transform() でトランスパイルを実行
4. ソースマップが有効な場合、Babelのソースマップを統合
5. トランスパイル後のコードを出力

**関連システム・外部連携**：@babel/core、babel-core、.babelrc設定ファイル

**権限による制御**：なし

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | CLIオプションのため関連画面なし |

## 機能種別

トランスパイル / 後処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --transpile / -t | boolean | No | Babelトランスパイルを有効にする | オプションの有無で判定 |
| source | string | Yes | コンパイル対象のCoffeeScriptファイルまたはコード | ファイルが存在するか、有効なコードであること |

### 入力データソース

- ファイルシステム（CoffeeScriptソースファイル）
- コマンドライン引数（`--eval` 併用時）
- 標準入力（`--stdio` 併用時）

### Babel設定

Babelの設定は以下の場所から自動的に読み込まれる:
- `.babelrc` ファイル
- `.babelrc.js` ファイル
- `babel.config.js` ファイル
- `package.json` の `babel` キー

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| transpiled JS | string | Babelでトランスパイルされた JavaScript コード |
| source map | object | ソースマップ（--mapまたは--inline-map併用時） |

### 出力先

- ファイルシステム（`.js` ファイル、`--compile` 併用時）
- 標準出力（`--print` 併用時）

## 処理フロー

### 処理シーケンス

```
1. コマンドライン引数をパース
   └─ --transpile オプションが指定されているか確認

2. Babelモジュールのロード
   └─ @babel/core を試行、失敗したら babel-core を試行

3. compileOptions でtranspileオプションを設定
   └─ transpile オブジェクトに Babel への参照を設定

4. CoffeeScript.compile() でコンパイル
   └─ 通常のコンパイル処理

5. Babel.transform() でトランスパイル
   └─ ソースマップがある場合は inputSourceMap として渡す

6. 結果の統合
   └─ トランスパイル後のコードとソースマップを統合

7. 出力
   └─ トランスパイル後のJSを出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始: coffee -t source.coffee] --> B[引数パース]
    B --> C{--transpile 指定?}
    C -->|No| D[通常コンパイル]
    C -->|Yes| E[@babel/core ロード試行]
    E --> F{成功?}
    F -->|Yes| G[Babel参照保持]
    F -->|No| H[babel-core ロード試行]
    H --> I{成功?}
    I -->|Yes| G
    I -->|No| J[エラー表示して終了]
    G --> K[CoffeeScript.compile]
    K --> L[JavaScript取得]
    L --> M{v3SourceMap あり?}
    M -->|Yes| N[inputSourceMap設定]
    M -->|No| O[transpilerOptions設定]
    N --> O
    O --> P[Babel.transform]
    P --> Q[トランスパイル後コード取得]
    Q --> R{ソースマップ更新?}
    R -->|Yes| S[v3SourceMap更新]
    R -->|No| T[出力]
    S --> T
    T --> U[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-29-01 | Babel必須 | --transpile使用時は @babel/core または babel-core がインストールされている必要がある | --transpile指定時 |
| BR-29-02 | 設定ファイル検索 | Babelはコンパイル対象ファイルの位置から設定ファイルを検索する | --transpile指定時 |
| BR-29-03 | ソースマップ統合 | CoffeeScriptのソースマップがある場合、Babelの inputSourceMap として渡される | --map または --inline-map 併用時 |
| BR-29-04 | オブジェクト渡し | transpileオプションはオブジェクトで渡す必要がある（Node API使用時） | Node API使用時 |
| BR-29-05 | ファイル名渡し | Babelのfilename オプションが設定されていない場合、自動で設定される | --transpile指定時 |

### 計算ロジック

特になし

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| Babel Not Found | 依存関係エラー | @babel/core も babel-core もインストールされていない | npm install @babel/core でインストール |
| Babel Config Error | 設定エラー | Babel設定ファイルが不正 | .babelrc等の設定を確認 |
| Transpile Error | トランスパイルエラー | Babelトランスパイル中のエラー | エラーメッセージを確認して修正 |

### リトライ仕様

本機能はリトライ処理を行わない。

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

本機能はトランザクション処理を使用しない。

## パフォーマンス要件

- トランスパイルにより追加の処理時間が発生
- 大規模プロジェクトではビルドキャッシュの使用を推奨

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

- 信頼できるBabelプラグインのみを使用する
- サードパーティプラグインのセキュリティを確認

## 備考

- ローカルインストールの場合: `npm install --save-dev @babel/core`
- グローバルインストールの場合: `npm install --global @babel/core`
- 典型的な .babelrc 設定: `{ "presets": ["@babel/preset-env"] }`

---

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

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

### 推奨読解順序

#### Step 1: オプション定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | command.coffee | `src/command.coffee` | SWITCHESの `--transpile` 定義（52行目）を確認 |

**読解のコツ**: `['-t', '--transpile', 'pipe generated JavaScript through Babel']` の形式で定義されている。

#### Step 2: Babelロード処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | command.coffee | `src/command.coffee` | compileOptions関数内のBabelロード（453-482行目） |

**主要処理フロー**:
- **453行目**: `if opts.transpile`
- **460-461行目**: `require '@babel/core'` 試行
- **463-464行目**: `require 'babel-core'` フォールバック
- **466-481行目**: エラーメッセージ（ローカル/グローバル判定）

#### Step 3: transpileオプション設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | command.coffee | `src/command.coffee` | transpileオブジェクトの設定（484-497行目） |

**主要処理フロー**:
- **484行目**: `opts.transpile = {} unless typeof opts.transpile is 'object'`
- **490行目**: `opts.transpile.transpile = CoffeeScript.transpile`
- **496-497行目**: filename設定

#### Step 4: トランスパイル実行を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | coffeescript.coffee | `src/coffeescript.coffee` | compile関数内のtranspile処理（142-163行目） |

**主要処理フロー**:
- **142行目**: `if options.transpile`
- **150行目**: `transpiler = options.transpile.transpile`
- **158-159行目**: inputSourceMap設定
- **160行目**: `transpilerOutput = transpiler js, transpilerOptions`
- **161行目**: `js = transpilerOutput.code`
- **162-163行目**: ソースマップ更新

#### Step 5: CoffeeScript.transpile関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | index.coffee | `src/index.coffee` | transpile関数（9-19行目） |

**主要処理フロー**:
- **9行目**: `CoffeeScript.transpile = (js, options) ->`
- **11行目**: `babel = require '@babel/core'`
- **19行目**: `babel.transform js, options`

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

```
exports.run (72行目)
    │
    └─ compileScript (202行目)
           │
           ├─ compileOptions (203行目)
           │      │
           │      ├─ [Babelロード] (460-464行目)
           │      │      ├─ require '@babel/core'
           │      │      └─ require 'babel-core' (フォールバック)
           │      │
           │      └─ opts.transpile.transpile = CoffeeScript.transpile (490行目)
           │
           └─ CoffeeScript.compile (223行目)
                  │
                  └─ coffeescript.coffee: compile (62行目)
                         │
                         ├─ 通常コンパイル処理
                         │
                         └─ [transpile処理] (142-163行目)
                                │
                                ├─ transpiler = options.transpile.transpile
                                │
                                └─ transpilerOutput = transpiler(js, options)
                                       │
                                       └─ index.coffee: transpile (9行目)
                                              └─ babel.transform(js, options)
```

### データフロー図

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

CoffeeScriptソース ───▶ CoffeeScript.compile
                              │
                              ▼
                        ES6+ JavaScript
                              │
                              ▼
                        [transpile処理] (142-163行目)
                              │
                              ▼
                        CoffeeScript.transpile (9行目)
                              │
                              ▼
                        babel.transform
                              │
                              ├─ inputSourceMap (ソースマップ統合)
                              │
                              ▼
                        transpilerOutput
                              │
                              ├─ .code → トランスパイル後JS
                              │
                              └─ .map → 更新されたソースマップ
                                      │
                                      ▼
                              最終出力（ES5互換JS）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| command.coffee | `src/command.coffee` | ソース | CLIメイン処理、Babelロード、--transpile分岐処理 |
| coffeescript.coffee | `src/coffeescript.coffee` | ソース | compile関数内のtranspile処理統合 |
| index.coffee | `src/index.coffee` | ソース | CoffeeScript.transpile関数の実装 |
| optparse.coffee | `src/optparse.coffee` | ソース | コマンドライン引数パーサー |
| .babelrc | プロジェクトルート | 設定 | Babel設定ファイル（ユーザー作成） |
