# 画面設計書 24-Annotated Source - Index (v2)

## 概要

本ドキュメントは、CoffeeScript v2のソースコード解説インデックスページ(index.coffee)の設計仕様を定義する。

### 本画面の処理概要

この画面は、CoffeeScript v2コンパイラの`index.coffee`モジュールのソースコード解説を表示するドキュメント画面である。Doccoツールによって自動生成された形式で、ソースコードと解説文を2カラムで並べて表示する。index.coffeeはNode.js環境でのCoffeeScript APIエントリーポイントを提供する。

**業務上の目的・背景**：CoffeeScript v2コンパイラの内部実装を理解したい開発者向けに、Node.js環境でのメインAPIエントリーポイントの仕組みを解説する。index.coffeeはCoffeeScript.compile、CoffeeScript.run、CoffeeScript.eval、CoffeeScript.registerなどの主要APIを提供し、Babelトランスパイル統合も担当する重要なモジュールである。

**画面へのアクセス方法**：v2 Annotated Sourceのルートから「index.coffee」リンクをクリック、またはURLを直接指定してアクセスする。

**主要な操作・処理内容**：
1. ソースコードの各セクションと対応する解説文の閲覧
2. 「Jump To」メニューから他のソースコード解説ページへの遷移
3. セクションアンカーリンクによる特定セクションへの直接アクセス
4. CoffeeScript.compile、run、eval、transpile関数の実装理解

**画面遷移**：
- 遷移元：v2ドキュメントトップ、他のAnnotated Sourceページ
- 遷移先：browser.coffee、cake.coffee、coffeescript.coffee、command.coffee、grammar.coffee、helpers.coffee、lexer.coffee、nodes.coffee、optparse.coffee、register.coffee、repl.coffee、rewriter.coffee、scope.litcoffee、sourcemap.litcoffee

**権限による表示制御**：なし（静的ドキュメントのため全ユーザーがアクセス可能）

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 7 | Lexer | 遷移先機能 | Lexerソースコード解説ページへの遷移リンク（v2） |
| 14 | Grammar | 遷移先機能 | Grammarソースコード解説ページへの遷移リンク（v2） |
| 16 | Nodes | 遷移先機能 | Nodesソースコード解説ページへの遷移リンク（v2） |

## 画面種別

詳細（ソースコード解説ドキュメント / インデックス）

## URL/ルーティング

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

## 入出力項目

本画面は静的HTMLドキュメントのため、ユーザー入力項目はない。

## 表示項目

| 項目名 | 説明 | 表示形式 |
|--------|------|----------|
| タイトル | index.coffee | h1テキスト |
| Jump Toメニュー | 他ソースファイルへの遷移リンク一覧 | ドロップダウンリスト |
| セクションリスト | ソースコード解説セクション（全18セクション） | 2カラムレイアウト |
| 解説テキスト | 各セクションの解説文 | HTML段落 |
| ソースコード | 対応するCoffeeScriptコード | シンタックスハイライト付きpre |

### 解説セクション一覧

| セクション番号 | 内容 | 対応する主要関数/処理 |
|----------------|------|----------------------|
| 1 | Node.js実装概要 | モジュールインポート |
| 2 | Babelトランスパイル | CoffeeScript.transpile |
| 3 | compile関数（共有） | universalCompile |
| 4 | compile関数（Node API） | CoffeeScript.compile |
| 5 | transpileオプション処理 | transpile.transpile設定 |
| 6 | run関数 | CoffeeScript.run |
| 7 | filenameの設定 | mainModule.filename |
| 8 | モジュールキャッシュクリア | moduleCache |
| 9 | node_modulesパス設定 | mainModule.paths |
| 10 | コンパイルオプション設定 | options.inlineMap |
| 11 | コンパイル実行 | CoffeeScript.compile |
| 12 | eval関数 | CoffeeScript.eval |
| 13 | sandbox/module定義 | createContext |
| 14 | REPLハック | _require設定 |
| 15 | require.extensions警告 | 廃止警告 |
| 16 | _compileRawFileContent | BOM除去・コンパイル |
| 17 | _compileFile | ファイル読み込み・コンパイル |
| 18 | module.exports | 名前付きエクスポート |

## イベント仕様

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

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

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

各セクションの段落記号をクリックすると、そのセクションへのアンカーリンクがURLに設定され、ブックマークや共有に使用可能となる。

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

本画面は静的HTMLドキュメントであり、データベース操作は発生しない。

## メッセージ仕様

本画面は静的ドキュメントのため、動的メッセージは表示されない。

## 例外処理

静的HTMLファイルのため、以下のHTTPエラーのみ発生しうる：
- 404 Not Found: ファイルが見つからない場合
- 500 Internal Server Error: サーバー側の問題

## 備考

- Doccoツール（http://ashkenas.com/docco/）で自動生成されたドキュメント
- CoffeeScript 2.x系のソースコードを対象としている
- v1のcoffee-script.coffeeから名前がcoffeescript.coffeeに変更されている
- Babelトランスパイル統合がv2の特徴

---

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

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

### 推奨読解順序

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

index.coffeeが操作する主要なデータ構造は、CoffeeScriptオブジェクト（API関数群）、Node.jsのmodule/require、vmモジュールである。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.coffee | `src/index.coffee` | 1-5行目のモジュールインポート |

**読解のコツ**: CoffeeScriptオブジェクトがcoffeescript.coffeeからインポートされ、そこにNode.js固有のメソッドが追加されるパターンを理解する。

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

index.coffeeはrequire('coffeescript')で読み込まれ、CoffeeScriptオブジェクトをエクスポートする。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.coffee | `src/index.coffee` | 1行目でcoffeescriptモジュールをインポート |
| 2-2 | index.coffee | `src/index.coffee` | 末尾でmodule.exportsを設定 |

**主要処理フロー**:
1. **1-5行目**: CoffeeScript、fs、vm、path、helpersのインポート
2. **7-15行目**: CoffeeScript.transpile関数の定義（Babel統合）
3. **18行目**: universalCompile変数に基本compile関数を保存
4. **21-24行目**: Node.js用compile関数の定義（transpileオプション対応）
5. **28-47行目**: CoffeeScript.run関数の定義
6. **51-80行目**: CoffeeScript.eval関数の定義
7. **82行目**: CoffeeScript.register関数の定義
8. **末尾**: 名前付きエクスポート

#### Step 3: CoffeeScript.run関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.coffee | `src/index.coffee` | 28-47行目：run関数 |

**主要処理フロー**:
- **28行目**: run関数の定義開始
- **29行目**: require.mainをmainModuleとして取得
- **32-34行目**: filenameの設定
- **37行目**: moduleキャッシュのクリア
- **40-44行目**: node_modulesパスの設定
- **46行目**: オプション保存
- **48-49行目**: inlineMapを有効化してコンパイル
- **50行目**: mainModule._compileで実行

#### Step 4: Babelトランスパイル統合を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | index.coffee | `src/index.coffee` | 7-15行目：transpile関数 |

**主要処理フロー**:
- **8-9行目**: @babel/coreのロード試行
- **10-11行目**: babel-coreのフォールバック
- **13行目**: Babelが見つからない場合のエラー
- **14行目**: babel.transformの呼び出し

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

```
require('coffeescript')
    |
    +-- CoffeeScript (from './coffeescript')
    |
    +-- CoffeeScript.compile(code, options)
    |       |
    |       +-- [transpile?] transpile.transpile()
    |       +-- universalCompile()
    |
    +-- CoffeeScript.run(code, options)
    |       |
    |       +-- require.main設定
    |       +-- CoffeeScript.compile()
    |       +-- mainModule._compile()
    |
    +-- CoffeeScript.eval(code, options)
    |       |
    |       +-- vm.createContext()
    |       +-- CoffeeScript.compile()
    |       +-- vm.runInContext()
    |
    +-- CoffeeScript.register()
            |
            +-- require('./register')
```

### データフロー図

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

CoffeeScriptコード    CoffeeScript.compile()            JavaScriptコード
(文字列)           --------->                       --------->
                              |
                              v
               [transpile?] babel.transform()
                              |
                              v
                    coffeescript.compile()


.coffeeファイル      CoffeeScript.run()                 実行結果
(パス)            --------->                       --------->
                              |
                              v
                    fs.readFileSync()
                              |
                              v
                    compile() + module._compile()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.coffee | `src/index.coffee` | ソース | Node.js APIエントリーポイント |
| index.html | `docs/v2/annotated-source/index.html` | テンプレート | Docco生成HTML |
| coffeescript.coffee | `src/coffeescript.coffee` | ソース | コアコンパイラ |
| register.coffee | `src/register.coffee` | ソース | require拡張 |
| helpers.coffee | `src/helpers.coffee` | ソース | ヘルパー関数 |
| docco.css | `docs/v2/annotated-source/docco.css` | スタイル | ドキュメントスタイル |
