# 画面設計書 31-Annotated Source - CoffeeScript

## 概要

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

### 本画面の処理概要

本画面は、CoffeeScriptコンパイラの中核となるメインモジュール（coffeescript.coffee）のソースコードを、注釈付きで閲覧できるドキュメントページです。

**業務上の目的・背景**：CoffeeScriptコンパイラの内部動作を理解したい開発者向けに、ソースコードと解説を並列表示することで、コンパイル処理の流れを視覚的に把握できるようにしています。compile関数、tokens関数、nodes関数などのコアAPI、およびソースマップ生成、Babelトランスパイル連携、スタックトレース変換などの高度な機能の実装詳細を学習できます。

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

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

**画面遷移**：
- 遷移元：v2ドキュメントページ、Annotated Source - Index
- 遷移先：browser.html, cake.html, command.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 | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | CoffeeScript コンパイル | 主機能 | メインモジュールcoffeescript.coffeeのソースコード解説表示（v2） |
| 3 | トークン化 | 補助機能 | tokens関数の解説を含む（v2） |
| 4 | 構文解析 | 補助機能 | nodes関数の解説を含む（v2） |

## 画面種別

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

## URL/ルーティング

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

## 入出力項目

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

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

## 表示項目

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

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

| セクションNo | 解説内容 |
|-------------|---------|
| section-1 | モジュール概要：CoffeeScriptのサーバー/ブラウザ両対応、トークン化・パース・コンパイルの主要エントリ関数 |
| section-2 | package.jsonの読み込み |
| section-3 | VERSIONとFILE_EXTENSIONS定数 |
| section-4 | helpers公開とSourceMap関数取得 |
| section-5 | registerCompiled関数のエクスポート |
| section-6-7 | base64encode関数（Node/ブラウザ両対応） |
| section-8 | withPrettyErrors関数（SyntaxErrorへのファイル情報追加） |
| section-9 | compile関数の概要とオプション説明 |
| section-10-19 | compile関数の実装詳細（トークン化、パース、フラグメント生成、ソースマップ生成、Babel連携） |
| section-20 | tokens関数 |
| section-21 | nodes関数 |
| section-22 | run/eval/registerスタブ関数 |
| section-23-24 | Lexerインスタンス化とparser.lexerラッパー |
| section-25-27 | parser.yy設定とparseError関数 |
| section-28-31 | patchStackTrace関数（スタックトレースのソースマップ変換） |
| section-32 | checkShebangLine関数 |

## イベント仕様

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

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

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

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

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

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

## メッセージ仕様

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

## 例外処理

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

## 備考

- Doccoツール（https://github.com/jashkenas/docco）によって自動生成されたドキュメント
- CSSファイル（docco.css）によりスタイリングされている
- シンタックスハイライトはhighlight.jsを使用
- v1版（docs/v1/annotated-source/coffee-script.html）とファイル名が異なることに注意（v2はcoffeescript.html）

---

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

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

### 推奨読解順序

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

CoffeeScriptコンパイラの中核となるデータ構造（トークン、AST、ソースマップ）を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | coffeescript.coffee | `src/coffeescript.coffee` | exports.VERSION, FILE_EXTENSIONSの定義を確認 |
| 1-2 | helpers.coffee | `src/helpers.coffee` | ユーティリティ関数群の理解 |

**読解のコツ**: CoffeeScriptの`require`文でモジュール依存関係を把握し、`exports`で公開APIを確認する。

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

compile関数がコンパイル処理の主要エントリーポイントです。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | coffeescript.coffee | `src/coffeescript.coffee` | compile関数（62行目）の構造を把握 |

**主要処理フロー**:
1. **62-64行**: オプションのクローンと初期化
2. **66-71行**: ソースマップ生成条件の判定とLexerによるトークン化
3. **73-78行**: referencedVarsの収集（変数名重複防止用）
4. **81-86行**: import/export検出時のbareモード強制
5. **88行**: parser.parseによるAST生成
6. **94-107行**: ASTモード時の処理（ESTreeフォーマット出力）
7. **109-133行**: フラグメントからJavaScriptコード生成とソースマップ更新
8. **142-163行**: Babelトランスパイル連携
9. **165-177行**: インラインソースマップ生成と結果返却

#### Step 3: トークン化処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | coffeescript.coffee | `src/coffeescript.coffee` | tokens関数（183-184行）を確認 |
| 3-2 | lexer.coffee | `src/lexer.coffee` | Lexer.tokenize関数の実装 |

**主要処理フロー**:
- **183-184行**: lexer.tokenize呼び出しでソースコードをトークン配列に変換

#### Step 4: 構文解析処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | coffeescript.coffee | `src/coffeescript.coffee` | nodes関数（189-191行）を確認 |
| 4-2 | parser.js | `lib/coffeescript/parser.js` | Jisonパーサーの構造（自動生成ファイル） |

**主要処理フロー**:
- **189-191行**: 文字列の場合はトークン化後、parser.parseでAST生成

#### Step 5: スタックトレース変換を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | coffeescript.coffee | `src/coffeescript.coffee` | patchStackTrace関数（253-323行）を確認 |
| 5-2 | sourcemap.litcoffee | `src/sourcemap.litcoffee` | SourceMapクラスの実装 |

**主要処理フロー**:
- **253-323行**: Error.prepareStackTraceをモンキーパッチしてソースマップによる行番号変換を実現

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

```
exports.compile (coffeescript.coffee:62)
    |
    +-- lexer.tokenize (lexer.coffee)
    |       |
    |       +-- トークン配列生成
    |
    +-- parser.parse (parser.js)
    |       |
    |       +-- AST生成 (nodes.coffee)
    |
    +-- nodes.compileToFragments (nodes.coffee)
    |       |
    |       +-- CodeFragment配列生成
    |
    +-- SourceMap.add / generate (sourcemap.litcoffee)
    |       |
    |       +-- v3SourceMap生成
    |
    +-- transpiler (Babel) [optional]
            |
            +-- ES5/ES6変換
```

### データフロー図

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

CoffeeScriptソース -----> lexer.tokenize -----> トークン配列
                              |
                              v
                         parser.parse -----> ASTノード
                              |
                              v
                    compileToFragments -----> フラグメント配列
                              |
                              v
                      フラグメント結合 -----> JavaScriptコード
                              |
                              v
                   SourceMap.generate -----> v3SourceMap (JSON)
                              |
                              v
                      [transpile?] -----> Babel変換済みJS
                              |
                              v
                     registerCompiled -----> キャッシュ登録
                              |
                              v
                        return -----> {js, sourceMap, v3SourceMap} or js
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| coffeescript.coffee | `src/coffeescript.coffee` | ソース | メインモジュール（コンパイルAPI） |
| coffeescript.html | `docs/v2/annotated-source/coffeescript.html` | テンプレート | 本画面のHTMLファイル |
| lexer.coffee | `src/lexer.coffee` | ソース | 字句解析器 |
| parser.js | `lib/coffeescript/parser.js` | 生成ファイル | Jisonパーサー |
| nodes.coffee | `src/nodes.coffee` | ソース | ASTノード定義 |
| helpers.coffee | `src/helpers.coffee` | ソース | ユーティリティ関数 |
| sourcemap.litcoffee | `src/sourcemap.litcoffee` | ソース | ソースマップ生成 |
| docco.css | `docs/v2/annotated-source/docco.css` | 設定 | スタイルシート |
