# 画面設計書 33-Annotated Source - Command

## 概要

本ドキュメントは、CoffeeScript v2のCLIコマンドモジュール（command.coffee）のソースコード解説ページ「Annotated Source - Command」の画面設計書です。Doccoツールによって生成された静的HTMLページとして、`coffee`コマンドラインツールの実装詳細を解説しています。

### 本画面の処理概要

本画面は、CoffeeScriptのコマンドラインインターフェース（coffee コマンド）を実装するcommand.coffeeのソースコードを、注釈付きで閲覧できるドキュメントページです。

**業務上の目的・背景**：CoffeeScriptのCLIツールの内部動作を理解したい開発者向けに、コマンドライン引数の解析、ファイルコンパイル、ファイル監視（--watch）、REPL起動、stdioコンパイルなどの実装詳細を提供します。CLIツールのカスタマイズや拡張、あるいはCoffeeScriptをビルドパイプラインに組み込む際の技術的理解を支援します。

**画面へのアクセス方法**：v2ドキュメントページ（docs/v2/index.html）からAnnotated Sourceセクションへ遷移し、「command.coffee」リンクをクリックしてアクセスします。または直接 docs/v2/annotated-source/command.html にアクセスします。

**主要な操作・処理内容**：
1. ソースコードセクション（右側）と注釈セクション（左側）の並列表示を閲覧
2. 「Jump To」メニューから他のソースファイル解説ページへ遷移
3. セクションアンカーリンク（#section-N）によるページ内ナビゲーション
4. ハイライトされたCoffeeScriptコードの閲覧

**画面遷移**：
- 遷移元：v2ドキュメントページ、Annotated Source - Index
- 遷移先：browser.html, cake.html, coffeescript.html, grammar.html, helpers.html, index.html, lexer.html, nodes.html, optparse.html, register.html, repl.html, rewriter.html, scope.html, sourcemap.html

**権限による表示制御**：特になし（静的HTMLページのため、すべてのユーザーが同一の内容を閲覧可能）

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 19 | coffeeコマンド | 主機能 | CLIコマンドcommand.coffeeのソースコード解説表示（v2） |
| 20 | --compile オプション | 補助機能 | コンパイルオプションの解説を含む（v2） |
| 21 | --watch オプション | 補助機能 | ファイル監視オプションの解説を含む（v2） |

## 画面種別

詳細（ソースコード解説ドキュメント表示）

## URL/ルーティング

`docs/v2/annotated-source/command.html`

## 入出力項目

本画面は静的HTMLページのため、ユーザー入力項目はありません。

| 項目名 | 入出力 | 型 | 説明 |
|--------|--------|-----|------|
| - | - | - | - |

## 表示項目

| 項目名 | 説明 | 表示位置 |
|--------|------|----------|
| タイトル | "command.coffee" | ヘッダー部 |
| Jump Toメニュー | 他ソースファイルへのリンク一覧 | 右上ドロップダウン |
| セクション一覧 | コード解説セクション | メインコンテンツ |
| 注釈部 | 各セクションの解説テキスト | 左カラム |
| コード部 | シンタックスハイライト付きソースコード | 右カラム |

### 主要セクション内容

| セクションNo | 解説内容 |
|-------------|---------|
| section-1 | モジュール概要：coffeeユーティリティの役割（コンパイル、REPL起動、ファイル監視等） |
| section-2 | 外部依存関係（fs, path, helpers, optparse, CoffeeScript, child_process, events） |
| section-3 | EventEmitterの拡張、printLine/printWarn/hidden関数 |
| section-4 | BANNERヘルプメッセージ |
| section-5 | SWITCHESオプション定義（--ast, --bare, --compile, --eval, --help等20個以上） |
| section-6 | グローバル変数（opts, sources, sourceCode, notSources, watchedDirs, optionParser） |
| section-7-10 | exports.run関数：オプション解析と分岐処理 |
| section-11 | compilePath関数：ファイル/ディレクトリのコンパイル |
| section-12 | compileScript関数：単一スクリプトのコンパイル |
| 以降 | watch, watchDir, writeJs, compileOptions, forkNode, usage, version関数等 |

## イベント仕様

### 1-Jump Toメニュークリック

「Jump To」リンクをクリックするとドロップダウンメニューが展開され、他のソースファイル解説ページへのリンクが表示されます。リンクをクリックすると対象ページへ遷移します。

### 2-セクションアンカーリンククリック

各セクションの「#」リンクをクリックすると、そのセクションへのパーマリンクがURLハッシュに設定されます。

## データベース更新仕様

本画面は静的HTMLページのため、データベース操作はありません。

## メッセージ仕様

本画面にはユーザー操作に対するメッセージ表示機能はありません。

## 例外処理

本画面は静的HTMLページのため、アプリケーションレベルの例外処理はありません。HTTPレベルでの404エラー（ファイルが見つからない場合）はWebサーバーが処理します。

## 備考

- Doccoツールによって自動生成されたドキュメント
- CSSファイル（docco.css）によりスタイリングされている
- シンタックスハイライトはhighlight.jsを使用
- coffeeコマンドの実際の使用方法はメインドキュメント（#usage）を参照

---

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

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

### 推奨読解順序

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

CLIで使用されるオプションとグローバル状態の構造を把握します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | command.coffee | `src/command.coffee` | SWITCHES配列でCLIオプション定義を確認（34-56行） |
| 1-2 | command.coffee | `src/command.coffee` | グローバル変数（opts, sources等）の役割を確認（58-64行） |

**読解のコツ**: SWITCHESは[short-flag, long-flag, description]の3要素配列で、optparse.coffeeによって解析される。

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

exports.run関数がCLI起動時のエントリーポイントです。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | command.coffee | `src/command.coffee` | exports.run関数（72-139行）の構造を把握 |

**主要処理フロー**:
1. **72-77行**: OptionParserの構築とオプション解析
2. **79-88行**: 後方互換性のための'--'引数処理
3. **93-106行**: オプションに応じた分岐（help, version, interactive, stdio, eval等）
4. **108-119行**: --outputオプションの解析（ファイル名/パス判定）
5. **121-136行**: --joinオプション（非推奨警告）と引数ファイルのコンパイル開始
6. **137-139行**: 各ソースファイルに対してcompilePath呼び出し

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | command.coffee | `src/command.coffee` | compilePath関数（151-187行） |
| 3-2 | command.coffee | `src/command.coffee` | compileScript関数（202-246行） |

**主要処理フロー**:
- **151-187行**: compilePath - ファイル/ディレクトリの判定と再帰処理
- **202-246行**: compileScript - 単一ファイルのコンパイル（トークン出力、AST出力、実行、ファイル保存の分岐）

#### Step 4: ファイル監視処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | command.coffee | `src/command.coffee` | watch関数（274-317行） |
| 4-2 | command.coffee | `src/command.coffee` | watchDir関数（320-348行） |

**主要処理フロー**:
- **274-317行**: watch - fs.watchを使用した単一ファイル監視
- **320-348行**: watchDir - ディレクトリ監視と新規ファイル検出

#### Step 5: コンパイルオプション構築を理解する

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

**主要処理フロー**:
- **452-499行**: Babel連携設定（--transpileオプション時）
- **501-527行**: コンパイルオプションオブジェクトの構築

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

```
exports.run (command.coffee:72)
    |
    +-- buildCSOptionParser (command.coffee:66)
    |       |
    |       +-- new optparse.OptionParser
    |
    +-- parseOptions (command.coffee:445)
    |       |
    |       +-- optionParser.parse
    |
    +-- [分岐]
            |
            +-- forkNode() [--nodejs]
            |
            +-- usage() [--help]
            |
            +-- version() [--version]
            |
            +-- require('./repl').start() [--interactive]
            |
            +-- compileStdio() [--stdio]
            |
            +-- compileScript() [--eval]
            |
            +-- compilePath() [デフォルト]
                    |
                    +-- watch() [--watch]
                    |
                    +-- compileScript()
                            |
                            +-- CoffeeScript.compile()
                            |
                            +-- writeJs()
```

### データフロー図

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

process.argv -----------> parseOptions -------> optsオブジェクト
                              |
                              v
ファイルパス -----------> compilePath ---------> ソースコード読込
                              |
                              v
ソースコード -----------> compileScript ------> CoffeeScript.compile
                              |
                              v
                         [オプション分岐]
                         /     |     \
                        v      v      v
               printTokens  printLine  writeJs
               (--tokens)   (--print)  (--compile)
                                           |
                                           v
                                      .jsファイル出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| command.coffee | `src/command.coffee` | ソース | CLIコマンド実装（552行） |
| command.html | `docs/v2/annotated-source/command.html` | テンプレート | 本画面のHTMLファイル |
| optparse.coffee | `src/optparse.coffee` | ソース | オプション解析 |
| coffeescript.coffee | `src/coffeescript.coffee` | ソース | コンパイルAPI |
| helpers.coffee | `src/helpers.coffee` | ソース | ユーティリティ関数 |
| repl.coffee | `src/repl.coffee` | ソース | REPL実装 |
| bin/coffee | `bin/coffee` | 実行ファイル | CLI起動スクリプト |
| docco.css | `docs/v2/annotated-source/docco.css` | 設定 | スタイルシート |
