# 機能設計書 27 --inline-map オプション

## 概要

本ドキュメントは、CoffeeScript CLIツールの `--inline-map` (`-M`) オプションの機能設計を記述する。このオプションは、ソースマップをJavaScriptファイル内にBase64エンコードで埋め込む機能を提供する。

### 本機能の処理概要

`--inline-map` オプションは、Source Map V3形式のソースマップをBase64エンコードしてJavaScriptファイルの末尾にData URIとして埋め込む機能を提供する。外部の`.js.map`ファイルを生成せず、単一のJavaScriptファイルにソースマップ情報が含まれるため、ファイル配布が簡単になる。

**業務上の目的・背景**：外部ソースマップファイルを使用する場合、JavaScriptファイルと一緒にソースマップファイルも配布・デプロイする必要がある。インラインソースマップを使用することで、単一のJavaScriptファイルのみでデバッグ情報を含めることができ、ファイル管理が簡単になる。特に開発環境や、単一ファイルとして配布したいライブラリに有用である。

**機能の利用シーン**：
- 開発環境でデバッグ情報を手軽に含めたい場合
- 単一ファイルとして配布したいライブラリを作成する場合
- ソースマップファイルの管理を避けたい場合
- ビルドパイプラインを簡素化したい場合

**主要な処理内容**：
1. CoffeeScript.compile() でインラインマップオプションを有効にしてコンパイル
2. ソースマップをJSON文字列化してBase64エンコード
3. Data URI形式（`data:application/json;base64,...`）に変換
4. `//# sourceMappingURL=` コメントとしてJS末尾に追加
5. `//# sourceURL=` コメントも追加してファイル名を明示

**関連システム・外部連携**：ブラウザ開発者ツール、Node.jsデバッガー

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

## 関連画面

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

## 機能種別

コード埋め込み / デバッグ支援

## 入力仕様

### 入力パラメータ

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

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| JavaScript with inline map | string | ソースマップが埋め込まれたJavaScriptコード |

### 出力先

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

### インラインソースマップ形式

```javascript
// コンパイルされたJavaScriptコード
//# sourceMappingURL=data:application/json;base64,BASE64_ENCODED_SOURCEMAP
//# sourceURL=filename.coffee
```

## 処理フロー

### 処理シーケンス

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

2. compileOptions でインラインマップオプションを設定
   └─ inlineMap: true を設定

3. CoffeeScript.compile() でコンパイル
   └─ ソースマップ生成も同時に実行

4. インラインマップの埋め込み（coffeescript.coffeeで実行）
   └─ v3SourceMap を JSON.stringify
   └─ Base64エンコード
   └─ Data URI形式のコメントを生成
   └─ sourceURLコメントを追加

5. 結果の出力
   └─ インラインマップ付きのJSを出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始: coffee -M source.coffee] --> B[引数パース]
    B --> C{--inline-map 指定?}
    C -->|No| D[通常コンパイル]
    C -->|Yes| E[compileOptions: inlineMap=true]
    E --> F[CoffeeScript.compile]
    F --> G[v3SourceMap生成]
    G --> H[JSON.stringify]
    H --> I[Base64エンコード]
    I --> J[Data URI生成]
    J --> K[sourceMappingURLコメント追加]
    K --> L[sourceURLコメント追加]
    L --> M[JSに結合]
    M --> N{出力先}
    N -->|--compile| O[ファイル出力]
    N -->|--print| P[標準出力]
    O --> Q[終了]
    P --> Q
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-27-01 | Data URI形式 | ソースマップは `data:application/json;base64,` で始まるData URIとして埋め込む | --inline-map指定時 |
| BR-27-02 | sourceURL追加 | `//# sourceURL=filename` コメントを追加してソースファイル名を明示 | --inline-map指定時 |
| BR-27-03 | Base64エンコード | ソースマップJSONをBase64でエンコード | --inline-map指定時 |
| BR-27-04 | UTF-8対応 | 拡張文字を含む場合もencodeURIComponentで正しくエンコード | ソースに非ASCII文字がある場合 |

### 計算ロジック

Base64エンコード:
- Node.js環境: `Buffer.from(src).toString('base64')`
- ブラウザ環境: `btoa(encodeURIComponent(src).replace(...))`

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| SyntaxError | 構文エラー | CoffeeScriptの文法エラー | エラーメッセージを表示して終了コード1 |
| Base64 Error | エンコードエラー | Base64エンコードに失敗 | エラーメッセージを表示して終了コード1 |

### リトライ仕様

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

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

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

## パフォーマンス要件

- インラインマップはBase64エンコードにより約33%サイズが増加
- 大きなファイルではファイルサイズに影響

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

- インラインソースマップには元のソースコードが含まれる
- 公開されるJavaScriptファイルにソースコードが露出する点に注意

## 備考

- `--map` オプションとは排他的ではないが、通常はどちらか一方を使用する
- 開発環境では便利だが、プロダクション環境ではファイルサイズ増加に注意

---

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

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

### 推奨読解順序

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

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

**読解のコツ**: `['-M', '--inline-map', 'generate source map and include it directly in output']` の形式で定義されている。

#### Step 2: インラインマップオプション設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | command.coffee | `src/command.coffee` | compileOptions関数（508行目） |

**主要処理フロー**:
- **508行目**: `inlineMap: opts['inline-map']` でインラインマップオプション設定

#### Step 3: Base64エンコードを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | coffeescript.coffee | `src/coffeescript.coffee` | base64encode関数（29-40行目） |

**主要処理フロー**:
- **29行目**: `base64encode = (src) -> switch`
- **30-31行目**: Node.js環境では`Buffer.from(src).toString('base64')`
- **32-38行目**: ブラウザ環境では`btoa`を使用

#### Step 4: インラインマップ埋め込み処理を理解する

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

**主要処理フロー**:
- **165行目**: `if options.inlineMap`
- **166行目**: `encoded = base64encode JSON.stringify v3SourceMap`
- **167行目**: `sourceMapDataURI = "//# sourceMappingURL=data:application/json;base64,#{encoded}"`
- **168行目**: `sourceURL = "//# sourceURL=#{filename}"`
- **169行目**: `js = "#{js}\n#{sourceMapDataURI}\n#{sourceURL}"`

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

```
exports.run (72行目)
    │
    └─ compileScript (202行目)
           │
           ├─ compileOptions (203行目)
           │      └─ inlineMap: opts['inline-map'] (508行目)
           │
           └─ CoffeeScript.compile (223行目)
                  │
                  └─ coffeescript.coffee: compile (62行目)
                         │
                         ├─ SourceMap.generate (140行目)
                         │      └─ v3SourceMap生成
                         │
                         └─ [inlineMap処理] (165-169行目)
                                │
                                ├─ base64encode (29行目)
                                │      └─ Buffer.from().toString('base64')
                                │
                                ├─ sourceMapDataURI生成
                                │
                                └─ sourceURL追加
```

### データフロー図

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

CoffeeScriptソース ───▶ CoffeeScript.compile
                              │
                              ├─ tokens → nodes → fragments
                              │
                              └─ SourceMap.generate
                                      │
                                      ▼
                              v3SourceMap (JSON)
                                      │
                                      ▼
                              JSON.stringify
                                      │
                                      ▼
                              base64encode (29行目)
                                      │
                                      ▼
                              Base64文字列
                                      │
                                      ▼
                        "data:application/json;base64,..."
                                      │
                                      ▼
                        "//# sourceMappingURL=..." + "//# sourceURL=..."
                                      │
                                      ▼
                              JSコード + インラインマップ ───▶ 出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| command.coffee | `src/command.coffee` | ソース | CLIメイン処理、--inline-map分岐処理 |
| coffeescript.coffee | `src/coffeescript.coffee` | ソース | compile関数、base64encode関数、インラインマップ埋め込み |
| sourcemap.litcoffee | `src/sourcemap.litcoffee` | ソース | SourceMapクラス、V3生成 |
| optparse.coffee | `src/optparse.coffee` | ソース | コマンドライン引数パーサー |
