# 機能設計書 28 --bare オプション

## 概要

本ドキュメントは、CoffeeScript CLIツールの `--bare` (`-b`) オプションの機能設計を記述する。このオプションは、コンパイル時にトップレベルの関数ラッパー（IIFE: Immediately Invoked Function Expression）を生成せずにJavaScriptを出力する機能を提供する。

### 本機能の処理概要

`--bare` オプションは、CoffeeScriptからJavaScriptへのコンパイル時に、通常生成されるトップレベルの即時実行関数（IIFE）ラッパーを省略する機能を提供する。通常、CoffeeScriptは変数のスコープ汚染を防ぐためにコード全体を `(function() { ... }).call(this);` でラップするが、このオプションを使用するとラップなしでコンパイルされる。

**業務上の目的・背景**：CoffeeScriptのデフォルトのコンパイル動作では、グローバルスコープの汚染を防ぐためにコード全体がIIFEでラップされる。しかし、ES6モジュール（import/export）を使用する場合や、特定のビルドツールと連携する場合、または複数ファイルを結合する場合には、このラッパーが不要または邪魔になることがある。`--bare` オプションにより、ラッパーなしのシンプルなJavaScriptを生成できる。

**機能の利用シーン**：
- ES6モジュール（import/export）を使用する場合
- 複数のCoffeeScriptファイルを結合してコンパイルする場合
- ビルドツール（Webpack、Rollup等）と連携する場合
- グローバル変数を意図的に定義したい場合
- 生成されるJavaScriptをシンプルに保ちたい場合

**主要な処理内容**：
1. compileOptionsでbare: trueを設定
2. CoffeeScript.compile()でbare オプションを渡す
3. コード生成フェーズでIIFEラッパーを省略
4. import/exportが含まれる場合は自動的にbareモードになる

**関連システム・外部連携**：ES6モジュールシステム、各種ビルドツール

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

## 関連画面

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

## 機能種別

コンパイルオプション / 出力形式制御

## 入力仕様

### 入力パラメータ

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

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| JavaScript (bare) | string | IIFEラッパーなしのJavaScriptコード |

### 出力先

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

### 出力形式の比較

**通常コンパイル（bare: false）:**
```javascript
(function() {
  var x;
  x = 1;
  console.log(x);
}).call(this);
```

**bareモード（bare: true）:**
```javascript
var x;
x = 1;
console.log(x);
```

## 処理フロー

### 処理シーケンス

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

2. compileOptions でbareオプションを設定
   └─ bare: opts.bare を設定

3. import/exportチェック（自動bare検出）
   └─ ソースにIMPORT/EXPORTトークンがあればbare: trueに強制

4. CoffeeScript.compile() でコンパイル
   └─ bare オプションに基づきIIFE生成を制御

5. 結果の出力
   └─ ラッパーなしのJSを出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始: coffee -b source.coffee] --> B[引数パース]
    B --> C[compileOptions: bare=opts.bare]
    C --> D[トークン化]
    D --> E{IMPORT/EXPORT含む?}
    E -->|Yes| F[bare: true に強制]
    E -->|No| G{--bare 指定?}
    G -->|Yes| F
    G -->|No| H[bare: false]
    F --> I[CoffeeScript.compile]
    H --> I
    I --> J{bare?}
    J -->|Yes| K[IIFEラッパーなしで生成]
    J -->|No| L[IIFEラッパーありで生成]
    K --> M[出力]
    L --> M
    M --> N[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-28-01 | IIFE省略 | bare: trueの場合、`(function() { ... }).call(this);`ラッパーを生成しない | --bare指定時 |
| BR-28-02 | 自動bare | import/export構文が含まれる場合、自動的にbare: trueになる | IMPORT/EXPORTトークン検出時 |
| BR-28-03 | 変数宣言位置 | bareモードでもvar宣言は先頭にまとめられる | bareモードコンパイル時 |
| BR-28-04 | eval連携 | CoffeeScript.eval()では常にbare: trueが設定される | eval実行時 |

### 計算ロジック

特になし

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

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

## パフォーマンス要件

- bareモードでは若干出力サイズが小さくなる（ラッパー分）

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

- bareモードでは変数がグローバルスコープに漏れる可能性がある
- 意図しないグローバル変数の上書きに注意

## 備考

- ES6モジュールを使用する場合は--bareオプションが自動的に有効になる
- REPLモードでは評価結果を取得するために常にbareモードが使用される

---

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

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

### 推奨読解順序

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

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

**読解のコツ**: `['-b', '--bare', 'compile without a top-level function wrapper']` の形式で定義されている。

#### Step 2: bareオプション設定を理解する

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

**主要処理フロー**:
- **504行目**: `bare: opts.bare` でbareオプション設定

#### Step 3: 自動bare検出を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | coffeescript.coffee | `src/coffeescript.coffee` | compile関数内の自動bare処理（81-86行目） |

**主要処理フロー**:
- **81-82行目**: `unless options.bare? and options.bare is yes`
- **83-86行目**: IMPORT/EXPORTトークンがあればbare: trueに設定

#### Step 4: コード生成でのbare処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | nodes.coffee | `src/nodes.coffee` | Blockクラスのコンパイル処理 |

**読解のコツ**: Blockクラスのcompile()でbareオプションに応じてIIFEラッパーの有無を制御する。

#### Step 5: evalでのbare使用を理解する

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

**主要処理フロー**:
- **98行目**: `o.bare = on # ensure return value`

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

```
exports.run (72行目)
    │
    └─ compileScript (202行目)
           │
           ├─ compileOptions (203行目)
           │      └─ bare: opts.bare (504行目)
           │
           └─ CoffeeScript.compile (223行目)
                  │
                  └─ coffeescript.coffee: compile (62行目)
                         │
                         ├─ [自動bare検出] (81-86行目)
                         │      └─ IMPORT/EXPORTトークンチェック
                         │
                         └─ nodes.compileToFragments
                                │
                                └─ Block.compile
                                       │
                                       └─ [bare分岐]
                                              ├─ true: ラッパーなし
                                              └─ false: IIFEでラップ
```

### データフロー図

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

CoffeeScriptソース ───▶ lexer.tokenize
                              │
                              ▼
                        トークン列
                              │
                              ▼
                        [IMPORT/EXPORTチェック] (81-86行目)
                              │
                              ▼
                        bare オプション決定
                              │
                              ▼
                        nodes.compileToFragments
                              │
                              ▼
                    ┌─────────┴─────────┐
                    ▼                   ▼
              [bare: true]        [bare: false]
                    │                   │
                    ▼                   ▼
              ラッパーなし        IIFEでラップ
              JavaScript         JavaScript
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| command.coffee | `src/command.coffee` | ソース | CLIメイン処理、--bare分岐処理 |
| coffeescript.coffee | `src/coffeescript.coffee` | ソース | compile関数、自動bare検出 |
| nodes.coffee | `src/nodes.coffee` | ソース | Blockクラス、IIFE生成制御 |
| index.coffee | `src/index.coffee` | ソース | eval関数でのbare設定 |
| optparse.coffee | `src/optparse.coffee` | ソース | コマンドライン引数パーサー |
