# 通知設計書 34-stdio map conflict

## 概要

本ドキュメントは、CoffeeScriptコンパイラで`--stdio`オプションと`--map`オプションが同時に指定された場合に発生するエラー通知「stdio map conflict」の設計仕様を記載する。

### 本通知の処理概要

CoffeeScriptのCLI（`coffee`コマンド）実行時に、標準入出力を使用するコンパイルモード（`--stdio`）とソースマップ生成モード（`--map`）が同時に指定された場合に、エラーメッセージを標準エラー出力に表示し、プロセスを終了コード1で終了する通知機能である。

**業務上の目的・背景**：`--stdio`モードは標準入力からソースコードを読み込み、コンパイル結果を標準出力に書き出す。一方、`--map`オプションはソースマップを別ファイル（`.js.map`）として書き出す。標準入出力モードではファイルパスが存在しないため、ソースマップファイルの出力先を決定できない。この互換性のない組み合わせをユーザーに通知し、適切なオプションの選択を促す必要がある。

**通知の送信タイミング**：`coffee --stdio --map`のようにオプションが指定された際、`compileStdio`関数の先頭で`opts.map`フラグをチェックし、trueの場合に即座に通知される。

**通知の受信者**：コマンドラインでCoffeeScriptコンパイラを実行している開発者またはビルドシステム。標準エラー出力（stderr）に出力されるため、ターミナルまたはログ収集システムが受信者となる。

**通知内容の概要**：「--stdio and --map cannot be used together」という固定メッセージでエラー内容を出力する。

**期待されるアクション**：ユーザーはエラーメッセージを確認し、以下のいずれかの対応を行うことが期待される：
1. `--map`オプションを削除して`--stdio`のみで実行
2. `--inline-map`オプションを使用してインラインソースマップを生成
3. ファイルベースのコンパイルに切り替えて`--map`を使用

## 通知種別

コンソール出力（標準エラー出力）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 高 |
| リトライ | 無し |

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

標準エラー出力（stderr）への直接出力のため、受信者決定ロジックは不要。コマンド実行元のターミナルまたはパイプ先に出力される。

## 通知テンプレート

### コンソール出力の場合

| 項目 | 内容 |
|-----|------|
| 出力先 | stderr（console.error） |
| 形式 | テキスト |

### 本文テンプレート

```
--stdio and --map cannot be used together
```

### 添付ファイル

なし

## テンプレート変数

なし（固定メッセージ）

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| CLI実行 | compileStdio関数呼び出し時 | opts.map === true | --mapと--stdioの同時指定 |

### 前提条件

| 条件 | 説明 |
|-----|------|
| opts.stdioがtrue | --stdioオプションが指定されている |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| opts.mapがfalse | --mapオプションが指定されていない場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[coffee --stdio --map 実行] --> B[exports.run関数]
    B --> C{opts.stdio?}
    C -->|Yes| D[compileStdio関数呼び出し]
    D --> E{opts.map?}
    E -->|Yes| F[console.error エラーメッセージ]
    F --> G[process.exit 1]
    E -->|No| H[正常処理継続]
    C -->|No| I[他の処理へ]
```

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

### 参照テーブル一覧

なし

### 更新テーブル一覧

なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| オプション競合 | --stdioと--mapの同時指定 | エラーメッセージを表示して終了 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

なし（コマンド実行ごとに発生）

### 配信時間帯

制限なし

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

- 固定メッセージのため、機密情報の漏洩リスクはない
- プロセス終了コード1により、シェルスクリプトやCI/CDパイプラインでエラー検知が可能

## 備考

- `--inline-map`（`-M`）オプションは`--stdio`と併用可能で、ソースマップをJavaScript出力内に埋め込む
- この制限は、ソースマップファイル（`.js.map`）の出力先パスを決定できないことに起因する
- 標準入力からの入力にはファイル名がないため、ソースマップのファイル参照も意味をなさない

---

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

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

### 推奨読解順序

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

オプションフラグの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | command.coffee | `src/command.coffee` | SWITCHES配列（43行目: -m, --map）を確認 |
| 1-2 | command.coffee | `src/command.coffee` | SWITCHES配列（51行目: -s, --stdio）を確認 |

**読解のコツ**: opts.mapとopts.stdioの両方がboolean型であることを理解しておく。

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

処理の起点となる関数を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | command.coffee | `src/command.coffee` | exports.run関数（72-139行目）でstdioモードへの分岐を確認 |
| 2-2 | command.coffee | `src/command.coffee` | 101行目で`compileStdio()`が呼び出される |

**主要処理フロー**:
1. **72行目**: `exports.run`関数の定義開始
2. **101行目**: `return compileStdio() if opts.stdio`でstdioモードへ分岐

#### Step 3: stdioコンパイル処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | command.coffee | `src/command.coffee` | compileStdio関数（250-259行目）でエラーチェックを確認 |

**主要処理フロー**:
- **250行目**: `compileStdio = ->`関数定義
- **251行目**: `if opts.map`でmapオプションチェック
- **252行目**: `console.error '--stdio and --map cannot be used together'`
- **253行目**: `process.exit 1`

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

```
exports.run (command.coffee:72)
    │
    └─ [opts.stdio === true]
           └─ compileStdio (command.coffee:250)
                  │
                  └─ [opts.map === true]
                         └─ console.error + process.exit(1)
```

### データフロー図

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

opts.stdio ───▶ compileStdio()
opts.map   ───▶      │
                     ▼
               opts.map チェック
                     │
         ┌───────────┴───────────┐
         │ true                  │ false
         ▼                       ▼
   console.error()          正常処理継続
         │                       │
         ▼                       ▼
   process.exit(1)          stdin → compile → stdout
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| command.coffee | `src/command.coffee` | ソース | CLIエントリーポイント、オプション競合チェック |
