# 画面設計書 36-Annotated Source - Register

## 概要

本ドキュメントは、CoffeeScript v2のNode.js登録処理モジュール（register.coffee）のソースコード解説ページ「Annotated Source - Register」の画面設計書です。Doccoツールによって生成された静的HTMLページとして、Node.jsでCoffeeScriptファイルを直接requireするための実装詳細を解説しています。

### 本画面の処理概要

本画面は、CoffeeScriptファイルをNode.jsで直接require可能にするregister.coffeeのソースコードを、注釈付きで閲覧できるドキュメントページです。

**業務上の目的・背景**：Node.js環境でCoffeeScriptファイルを直接実行・インポートする仕組みを理解したい開発者向けに、require.extensionsへの拡張子登録、Module.prototype.load のパッチ、child_process.forkのパッチなどの実装詳細を提供します。Node.jsモジュールシステムの拡張方法の学習や、類似の言語拡張実装の参考になります。

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

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

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

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 46 | require フック | 主機能 | Node.js登録処理register.coffeeのソースコード解説表示（v2） |
| 50 | child_process.fork対応 | 補助機能 | forkパッチの解説を含む（v2） |

## 画面種別

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

## URL/ルーティング

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

## 入出力項目

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

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

## 表示項目

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

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

| セクションNo | 解説内容 |
|-------------|---------|
| 冒頭 | 外部依存関係（CoffeeScript, child_process, helpers, path） |
| 冒頭 | patchStackTrace関数の取得と条件付き実行 |
| 中盤 | loadFile関数：CoffeeScriptファイルのコンパイルとモジュール読み込み |
| 中盤 | require.extensionsへのCoffeeScript拡張子登録 |
| 中盤 | Module.prototype.loadのオーバーライド（マルチドット拡張子対応） |
| 終盤 | child_process.forkのパッチ（CoffeeScriptファイルの直接fork対応） |
| 終盤 | getRootModule関数：トップモジュールのオプション取得 |

## イベント仕様

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

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

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

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

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

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

## メッセージ仕様

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

## 例外処理

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

## 備考

- Doccoツールによって自動生成されたドキュメント
- CSSファイル（docco.css）によりスタイリングされている
- シンタックスハイライトはhighlight.jsを使用
- CoffeeScript.register()を呼び出すことで本モジュールの機能が有効化される

---

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

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

### 推奨読解順序

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

モジュールオプションとソースマップキャッシュの構造を把握します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | register.coffee | `src/register.coffee` | module.optionsの構造と役割を確認 |

**読解のコツ**: モジュールはoptionsプロパティを持つことがあり、これはトランスパイル設定などを含む。getRootModule関数でルートモジュールのオプションを取得。

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

require.extensionsへの登録がエントリーポイントです。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | register.coffee | `src/register.coffee` | require.extensions登録部分（32-34行） |

**主要処理フロー**:
1. **9-12行**: Node.jsのソースマップサポート確認
2. **14-16行**: Error.prepareStackTraceがなければpatchStackTrace実行
3. **32-34行**: FILE_EXTENSIONS（.coffee, .litcoffee, .coffee.md）をrequire.extensionsに登録

#### Step 3: ファイル読み込み処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | register.coffee | `src/register.coffee` | loadFile関数（19-28行） |

**主要処理フロー**:
- **19-20行**: モジュールのoptionsを取得（自身またはルートモジュールから）
- **24-25行**: ソースマップ有効時にinlineMapオプション設定
- **26行**: CoffeeScript._compileFile呼び出し
- **28行**: module._compile でJavaScript実行

#### Step 4: マルチドット拡張子対応を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | register.coffee | `src/register.coffee` | Module.prototype.loadオーバーライド（38-55行） |

**主要処理フロー**:
- **40-48行**: findExtension関数 - ファイル名から拡張子を検出（.coffee.mdなどマルチドット対応）
- **50-55行**: Module.prototype.load置き換え - 適切な拡張子でModule._extensionsを呼び出し

#### Step 5: child_process.forkパッチを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | register.coffee | `src/register.coffee` | child_process.fork置き換え（59-69行） |

**主要処理フロー**:
- **60-61行**: 元のfork関数とcoffeeバイナリパス取得
- **62-69行**: fork関数置き換え - CoffeeScriptファイルの場合はcoffeeバイナリ経由で起動

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

```
require('coffeescript/register')
    |
    +-- patchStackTrace() [条件付き]
    |
    +-- require.extensions['.coffee'] = loadFile
    |       |
    |       +-- loadFile(module, filename)
    |               |
    |               +-- getRootModule(module)
    |               +-- CoffeeScript._compileFile(filename, options)
    |               +-- module._compile(js, filename)
    |
    +-- Module.prototype.load = function(filename) {...}
    |       |
    |       +-- findExtension(filename)
    |       +-- Module._extensions[extension](this, filename)
    |
    +-- child_process.fork = function(path, args, options) {...}
            |
            +-- helpers.isCoffee(path)
            +-- originalFork(binary, [path, ...args], options)
```

### データフロー図

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

require('file.coffee') -> loadFile(module, filename) -> module._compile
                              |
                              v
                         CoffeeScript._compileFile
                              |
                              v
                         JavaScriptコード生成
                              |
                              v
                         module.exports設定
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| register.coffee | `src/register.coffee` | ソース | Node.js登録処理モジュール（74行） |
| register.html | `docs/v2/annotated-source/register.html` | テンプレート | 本画面のHTMLファイル |
| coffeescript.coffee | `src/coffeescript.coffee` | ソース | _compileFile関数提供 |
| helpers.coffee | `src/helpers.coffee` | ソース | isCoffee関数提供 |
| bin/coffee | `bin/coffee` | 実行ファイル | forkパッチで使用 |
| docco.css | `docs/v2/annotated-source/docco.css` | 設定 | スタイルシート |
