# 機能設計書 51-ブラウザコンパイラ

## 概要

本ドキュメントは、CoffeeScriptのブラウザコンパイラ機能の設計を記述する。ブラウザ環境でCoffeeScriptコードをJavaScriptにコンパイルし、実行するための機能を提供する。

### 本機能の処理概要

ブラウザコンパイラは、Webブラウザ環境でCoffeeScriptコードを直接コンパイルし、実行可能にする機能である。Node.js環境ではなくブラウザ内で動作するため、特別な考慮が必要となる。

**業務上の目的・背景**：従来、CoffeeScriptのコンパイルはNode.js環境で行われ、事前にJavaScriptファイルを生成する必要があった。しかし、開発時のプロトタイピングや学習目的、ブラウザベースのエディタ・IDE、オンラインドキュメントのインタラクティブなコード例などでは、ブラウザ内で直接コンパイルを行う需要がある。本機能はそのニーズに応え、ブラウザ環境でCoffeeScriptを手軽に試すことを可能にする。

**機能の利用シーン**：
- CoffeeScript公式サイトの「Try CoffeeScript」ページでのインタラクティブなコード実行
- オンラインドキュメント内でのコード例のリアルタイムコンパイル
- ブラウザベースの開発環境でのCoffeeScriptサポート
- 教育目的でのCoffeeScript学習ツール

**主要な処理内容**：
1. CoffeeScriptコアモジュールのブラウザ向け拡張
2. `CoffeeScript.eval()` によるコードの評価と実行
3. `CoffeeScript.run()` による即時実行
4. ソースマップのインライン生成（btoa/JSON対応環境の場合）
5. グローバルスコープでの安全なコード実行

**関連システム・外部連携**：
- CoffeeScriptコアコンパイラ（`src/coffeescript.coffee`）
- ブラウザのグローバルオブジェクト（`window` / `global`）
- Base64エンコーディング（`btoa`）
- JSON API

**権限による制御**：特になし。ブラウザ環境で利用可能なすべてのユーザーが本機能を利用できる。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | トップページ | 主画面 | ブラウザ上でCoffeeScriptコードをJavaScriptにコンパイルするコア機能 |
| 2 | Try CoffeeScript | 主画面 | ブラウザ環境でのコンパイル機能を提供 |
| 3 | テストスイート | 主画面 | テストコードをブラウザ上でコンパイルして実行 |
| 4 | v1ドキュメント | 主画面 | ブラウザ上でのコード例のコンパイル表示 |
| 5 | v1テストスイート | 主画面 | v1コンパイラでテストコードをブラウザ上で実行 |
| 6 | v2ドキュメント | 主画面 | ブラウザ上でのコード例のコンパイル表示 |
| 7 | v2テストスイート | 主画面 | v2コンパイラでテストコードをブラウザ上で実行 |
| 8 | CoffeeScript 2発表ページ | 補助画面 | ブラウザ上でのコード例のコンパイル機能 |
| 22 | Annotated Source - Browser | 主画面 | ブラウザサポートbrowser.coffeeのソースコード解説表示 |
| 37 | Annotated Source - Browser | 主画面 | ブラウザサポートbrowser.coffeeのソースコード解説表示（v2） |

## 機能種別

実行処理 / コンパイル処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| code | String | Yes | コンパイル対象のCoffeeScriptソースコード | 空文字列でないこと |
| options | Object | No | コンパイルオプション | - |
| options.bare | Boolean | No | トップレベル関数ラッパーを除去するか（デフォルト：`eval`ではtrue） | - |
| options.shiftLine | Boolean | No | 行番号をシフトするか（`run`ではtrue） | - |
| options.inlineMap | Boolean | No | インラインソースマップを生成するか | - |

### 入力データソース

- ユーザー入力（Webフォーム、scriptタグ内容）
- XHRによるリモートファイル取得
- HTMLドキュメント内の`text/coffeescript`スクリプトタグ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| compiledCode | String | コンパイルされたJavaScriptコード |
| result | Any | `eval`または`run`による実行結果 |

### 出力先

- ブラウザのJavaScript実行環境
- グローバルスコープでの実行結果

## 処理フロー

### 処理シーケンス

```
1. CoffeeScriptモジュールの読み込み
   └─ require './coffeescript' でコアコンパイラを取得

2. eval関数の定義
   └─ options.bareをデフォルトでonに設定
   └─ グローバルスコープ（window/global）でevalを実行

3. run関数の定義
   └─ options.bare = on, options.shiftLine = on を設定
   └─ Functionコンストラクタでコンパイル済みコードを実行

4. ブラウザ環境チェック
   └─ window?がfalseの場合は終了

5. インラインソースマップ対応
   └─ btoa と JSON が利用可能な場合、compileをオーバーライド
   └─ options.inlineMap = true を設定

6. モジュールエクスポート
   └─ ブラウザ向けに制限されたCoffeeScriptオブジェクトをエクスポート
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[CoffeeScriptコアモジュール読み込み]
    B --> C[eval関数定義]
    C --> D[run関数定義]
    D --> E{window存在?}
    E -->|No| F[モジュールエクスポートして終了]
    E -->|Yes| G{btoa/JSON利用可能?}
    G -->|Yes| H[compile関数をオーバーライド<br/>inlineMap有効化]
    G -->|No| I[標準compile使用]
    H --> J[load関数定義]
    I --> J
    J --> K[runScripts関数定義]
    K --> L[DOMContentLoaded<br/>イベントハンドラ登録]
    L --> F
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-51-01 | グローバルスコープ実行 | evalはグローバルスコープで実行される | CoffeeScript.eval呼び出し時 |
| BR-51-02 | bareオプションデフォルト | eval時はbareオプションがデフォルトでon | CoffeeScript.eval呼び出し時 |
| BR-51-03 | インラインソースマップ | btoa/JSON対応環境では自動的にインラインソースマップを生成 | ブラウザ環境でのコンパイル時 |
| BR-51-04 | ESモジュール副作用回避 | this === windowの場合のみDOMContentLoadedイベントを登録 | モジュールロード時 |

### 計算ロジック

該当なし

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

### 操作別データベース影響一覧

該当なし（ブラウザ環境のため、データベース操作は行わない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| SyntaxError | 構文エラー | 不正なCoffeeScriptコード | ユーザーにエラーメッセージを表示 |
| ReferenceError | 参照エラー | 未定義変数の参照 | ユーザーにエラーメッセージを表示 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- コンパイル処理は同期的に実行される
- 大規模なコードのコンパイルはブラウザUIをブロックする可能性がある
- ソースマップ生成時は追加のメモリ消費がある

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

- `eval`関数を使用するため、信頼できないコードの実行には注意が必要
- グローバルスコープで実行されるため、既存の変数を上書きする可能性がある
- XSSなどのセキュリティリスクに注意

## 備考

- ESモジュール版ではDOMContentLoadedイベントハンドラは自動登録されない（副作用回避のため）
- IE互換のため、`attachEvent`にもフォールバック対応

---

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

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

### 推奨読解順序

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

ブラウザコンパイラは比較的シンプルな構造で、主にコンパイルオプションオブジェクトを扱う。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | coffeescript.coffee | `src/coffeescript.coffee` | コアコンパイラのcompile関数のオプション構造を理解 |

**読解のコツ**: optionsオブジェクトは `{bare, inlineMap, shiftLine, sourceFiles}` などのプロパティを持つ。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | browser.coffee | `src/browser.coffee` | ブラウザ向け拡張機能のメインモジュール |

**主要処理フロー**:
1. **6-7行目**: CoffeeScriptコアモジュールの読み込みとcompile関数の取得
2. **13-16行目**: `CoffeeScript.eval`関数の定義 - グローバルスコープでのeval実行
3. **19-22行目**: `CoffeeScript.run`関数の定義 - Functionコンストラクタによる実行
4. **29行目**: ブラウザ環境チェック（window?）
5. **34-37行目**: インラインソースマップ対応のためのcompileオーバーライド

#### Step 3: 主要API関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | browser.coffee | `src/browser.coffee` | eval, run, load, runScripts関数の実装 |

**主要処理フロー**:
- **13-16行目**: `eval`関数 - `window.eval`または`global.eval`を使用してグローバルスコープで実行
- **19-22行目**: `run`関数 - Functionコンストラクタでラップして実行
- **40-56行目**: `load`関数 - XHRでリモートファイルを読み込み
- **61-96行目**: `runScripts`関数 - scriptタグの自動コンパイル・実行

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

```
browser.coffee
    │
    ├─ CoffeeScript.eval(code, options)
    │      └─ compile(code, options)
    │             └─ globalRoot.eval(compiledCode)
    │
    ├─ CoffeeScript.run(code, options)
    │      └─ compile(code, options)
    │             └─ Function(compiledCode)()
    │
    ├─ CoffeeScript.load(url, callback, options, hold)
    │      └─ XMLHttpRequest.open/send
    │             └─ CoffeeScript.run(responseText, options)
    │
    └─ CoffeeScript.runScripts()
           ├─ getElementsByTagName('script')
           ├─ CoffeeScript.load() [srcあり]
           └─ CoffeeScript.run() [インライン]
```

### データフロー図

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

CoffeeScript     ───▶  CoffeeScript.compile()  ───▶  JavaScript
ソースコード              │                            コード
                         │
                         ▼
                    window.eval() または
                    Function()()
                         │
                         ▼
                    実行結果
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| browser.coffee | `src/browser.coffee` | ソース | ブラウザコンパイラのメインモジュール |
| coffeescript.coffee | `src/coffeescript.coffee` | ソース | コアコンパイラ（compile関数） |
| index.coffee | `src/index.coffee` | ソース | Node.js向けエントリーポイント（参考） |
