# 通知設計書 26-transpile option error

## 概要

本ドキュメントは、CoffeeScriptコンパイラにおけるトランスパイルオプションの形式エラー（transpile option error）の通知仕様を記述する。

### 本通知の処理概要

本通知は、CoffeeScriptコンパイラの`transpile`オプションが不正な形式で指定された場合に発生するエラーメッセージである。

**業務上の目的・背景**：CoffeeScript 2.0以降、BabelによるJavaScriptトランスパイル機能が統合されている。`transpile`オプションを使用することで、CoffeeScriptからコンパイルされたJavaScriptをさらにBabelで処理できる。このオプションには、Babelに渡すオプションオブジェクトを指定する必要があり、オブジェクト以外の値（true、文字列など）が指定された場合はエラーとなる。

**通知の送信タイミング**：コンパイル時、`CoffeeScript.compile()`関数内で`transpile`オプションの型チェックを行うタイミングで発生する。

**通知の受信者**：CoffeeScriptコンパイラをNode.js API経由で呼び出している開発者。エラーオブジェクトとして通知される。

**通知内容の概要**：エラーメッセージ「The transpile option must be given an object with options to pass to Babel」が提供される。

**期待されるアクション**：開発者は、`transpile`オプションにBabelオプションを含むオブジェクトを指定する必要がある（例：`{ presets: ['@babel/preset-env'] }`）。

## 通知種別

Error例外（SyntaxErrorではなく標準のError）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（コンパイル処理中に即時発生） |
| 優先度 | 高（コンパイルエラー） |
| リトライ | なし（即時エラー終了） |

### 送信先決定ロジック

Node.js APIとして呼び出された場合、Error例外として呼び出し元にスローされる。CLIから呼び出された場合は、標準エラー出力にエラーメッセージが出力される。

## 通知テンプレート

### API呼び出しの場合

| 項目 | 内容 |
|-----|------|
| 例外タイプ | Error |
| 形式 | 例外オブジェクト |

### 本文テンプレート

```
Error: The transpile option must be given an object with options to pass to Babel
```

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| なし | 固定メッセージ | - | - |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| コンパイル処理 | transpileオプションの検証 | typeof options.transpile isnt 'object' | transpileオプションがオブジェクト型でない場合 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| オブジェクト型 | transpileオプションがオブジェクト型の場合 |
| オプション未指定 | transpileオプションが指定されていない場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[CoffeeScript.compile呼び出し] --> B{options.transpile存在?}
    B -->|No| C[通常コンパイル処理]
    B -->|Yes| D{typeof transpile === 'object'?}
    D -->|No| E[new Error生成]
    D -->|Yes| F[Babelトランスパイル設定]
    E --> G[throw Error]
    G --> H[コンパイル中断]
    F --> I[トランスパイル実行]
    I --> J[処理完了]
    C --> J
```

## データベース参照・更新仕様

### 参照テーブル一覧

該当なし（ファイルベースのコンパイル処理）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| Error | transpileがオブジェクト以外 | オブジェクト形式でBabelオプションを指定 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 制限 | なし（コンパイル時エラー） |

### 配信時間帯

制限なし（コンパイル実行時に即時通知）

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

- エラーメッセージには機密情報は含まれない
- Babelオプションの内容はエラーメッセージに含まれない

## 備考

- このエラーはNode.js APIまたはブラウザAPIで`transpile`オプションを使用した場合にのみ発生
- CLIで`--transpile`オプションを使用する場合、追加のオプションは`.babelrc`や`babel.config.json`で指定するため、このエラーは発生しにくい
- `transpile: true`のような指定は不正とみなされる

---

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

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

### 推奨読解順序

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

コンパイルオプションの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | coffeescript.coffee | `src/coffeescript.coffee` | compileオプションの構造（transpile含む） |

**読解のコツ**: `options.transpile`はBabelに渡すオプションオブジェクトを期待する。

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

transpileオプション検証処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | coffeescript.coffee | `src/coffeescript.coffee` | 142-146行目 - transpileオプション検証 |

**主要処理フロー**:
1. **142行目**: `if options.transpile`でtranspileオプションの存在をチェック
2. **143行目**: `typeof options.transpile isnt 'object'`で型チェック
3. **146行目**: オブジェクト以外の場合、`throw new Error`でエラーをスロー

#### Step 3: Babelトランスパイル処理を理解する

正常なケースでのBabelトランスパイル処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | coffeescript.coffee | `src/coffeescript.coffee` | 148-159行目 - Babelトランスパイル設定 |

**主要処理フロー**:
- **150行目**: `transpiler = options.transpile.transpile`でトランスパイラ関数を取得
- **151行目**: `delete options.transpile.transpile`でtranspileプロパティを削除
- **153行目**: `transpilerOptions = Object.assign {}, options.transpile`でオプションをコピー

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

```
CoffeeScript.compile(code, options)
    │
    ├─ Lexer.tokenize()
    │
    ├─ Parser.parse()
    │
    ├─ nodes.compile()
    │
    └─ options.transpile チェック
           ├─ typeof !== 'object'
           │      └─ throw new Error(...)
           │
           └─ typeof === 'object'
                  ├─ transpiler取得
                  ├─ transpilerOptions設定
                  └─ transpiler(js, transpilerOptions)
```

### データフロー図

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

options = {             typeof transpile             エラーメッセージ
  transpile: true       !== 'object'                 "The transpile option
}                            │                        must be given an object
      │                      ▼                        with options to pass
      │               typeof true === 'boolean'       to Babel"
      │               'boolean' !== 'object'
      │                      │
      │                      ▼
      └─────────────▶ throw new Error(...)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| coffeescript.coffee | `src/coffeescript.coffee` | ソース | transpileオプション検証、Babelトランスパイル |
| command.coffee | `src/command.coffee` | ソース | CLI経由のtranspileオプション処理 |
| compilation.coffee | `test/compilation.coffee` | テスト | エラーメッセージのテストケース（164行目） |
