# 画面設計書 30-Annotated Source - SourceMap (v2)

## 概要

本ドキュメントは、CoffeeScript v2のソースマップ生成(sourcemap.litcoffee)のソースコード解説画面の設計仕様を定義する。

### 本画面の処理概要

この画面は、CoffeeScriptコンパイラの`sourcemap.litcoffee`モジュールのソースコードを解説形式で表示するドキュメント画面である。Doccoツールによって自動生成された形式で、ソースコードと解説文を2カラムで並べて表示する。sourcemap.litcoffeeはLiterate CoffeeScript形式で書かれており、ソースマップの生成を担当する。

**業務上の目的・背景**：CoffeeScriptコンパイラの内部実装を理解したい開発者向けに、ソースマップ生成の仕組みを解説する。ソースマップはJavaScriptランタイムがコンパイル済みJavaScriptを元のCoffeeScriptソースに対応付けるためのファイルで、デバッグ時のスタックトレースや開発者ツールでのソースコード表示に使用される。

**画面へのアクセス方法**：v2 Annotated Sourceのインデックスページ(docs/v2/annotated-source/index.html)から「sourcemap.litcoffee」リンクをクリック、またはURLを直接指定してアクセスする。

**主要な操作・処理内容**：
1. ソースコードの各セクションと対応する解説文の閲覧
2. 「Jump To」メニューから他のソースコード解説ページへの遷移
3. SourceMapクラスとLineMapクラスの実装理解
4. V3ソースマップ形式とVLQエンコーディングの理解

**画面遷移**：
- 遷移元：v2 Annotated Source Index、他のAnnotated Sourceページ
- 遷移先：browser.coffee、cake.coffee、coffeescript.coffee、command.coffee、grammar.coffee、helpers.coffee、index.coffee、lexer.coffee、nodes.coffee、optparse.coffee、register.coffee、repl.coffee、rewriter.coffee、scope.litcoffee

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | ソースマップ生成 | 主機能 | ソースマップ生成sourcemap.litcoffeeのソースコード解説表示（v2） |

## 画面種別

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

## URL/ルーティング

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

## 入出力項目

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

## 表示項目

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

### 主要クラス・メソッド

| クラス/メソッド名 | 説明 | 処理内容 |
|------------------|------|---------|
| LineMap | 行マッピング | 1行分の列マッピングを管理 |
| LineMap.add | マッピング追加 | 列位置にソース位置を登録 |
| LineMap.sourceLocation | ソース位置取得 | 列からソース位置を逆引き |
| SourceMap | ソースマップ本体 | 全行のマッピングを管理 |
| SourceMap.add | マッピング追加 | 行・列にソース位置を登録 |
| SourceMap.sourceLocation | ソース位置取得 | 生成コード位置からソース位置 |
| SourceMap.generate | V3生成 | V3形式JSONを生成 |
| encodeVlq | VLQエンコード | 数値をVLQ形式に変換 |
| encodeBase64 | Base64エンコード | 1文字Base64変換 |

### V3ソースマップ形式

| フィールド | 説明 |
|-----------|------|
| version | バージョン（常に3） |
| file | 生成ファイル名 |
| sourceRoot | ソースルートパス |
| sources | ソースファイル配列 |
| names | 名前配列（未使用） |
| mappings | VLQエンコードされたマッピング |
| sourcesContent | ソースコード内容（オプション） |

## イベント仕様

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

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

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

各セクションの段落記号をクリックすると、そのセクションへのアンカーリンクがURLに設定される。

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

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

## メッセージ仕様

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

## 例外処理

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

## 備考

- Doccoツールで自動生成されたドキュメント
- CoffeeScript 2.x系のソースコードを対象
- Literate CoffeeScript形式（.litcoffee）で記述
- V3ソースマップ形式はGoogle提案の標準仕様
- VLQはVariable Length Quantity（可変長数値）エンコーディング

---

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

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

### 推奨読解順序

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

SourceMapとLineMapクラスの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | sourcemap.litcoffee | `src/sourcemap.litcoffee` | LineMapクラスの構造 |
| 1-2 | sourcemap.litcoffee | `src/sourcemap.litcoffee` | SourceMapクラスの構造 |

**読解のコツ**: LineMapは1行分、SourceMapはLineMap配列で全体を管理。マッピングは[sourceLine, sourceColumn]形式。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | sourcemap.litcoffee | `src/sourcemap.litcoffee` | SourceMap.add がマッピング追加 |
| 2-2 | sourcemap.litcoffee | `src/sourcemap.litcoffee` | SourceMap.generate がV3生成 |

**主要処理フロー**:
1. **コンパイル中**: SourceMap.addでマッピング蓄積
2. **コンパイル後**: SourceMap.generateでV3形式出力
3. **VLQエンコード**: 相対位置を効率的にエンコード

#### Step 3: VLQエンコーディングを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | sourcemap.litcoffee | `src/sourcemap.litcoffee` | encodeVlqメソッド |
| 3-2 | sourcemap.litcoffee | `src/sourcemap.litcoffee` | Base64エンコード |

**主要処理フロー**:
- **符号ビット**: 最下位ビットが符号（0:正, 1:負）
- **継続ビット**: 最上位ビットで継続を示す
- **Base64**: 6ビット単位でA-Za-z0-9+/に変換

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

```
CoffeeScript.compile(code, {sourceMap: true})
    |
    +-- Root.compile()
            |
            +-- SourceMap()  # インスタンス生成
            |
            +-- 各ノード.compileNode()
            |       |
            |       +-- SourceMap.add(sourceLocation, generatedLocation)
            |               |
            |               +-- LineMap.add(column, sourceLocation)
            |
            +-- SourceMap.generate(options)
                    |
                    +-- VLQエンコード
                    +-- V3 JSON生成
```

### データフロー図

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

CoffeeScript          コンパイル + マッピング収集        JavaScript
ソースコード       --------->                         --------->
(位置情報)                     |                        + SourceMap
                              v
               SourceMap.add(src, gen)
                              |
                              v
               SourceMap.generate()
                              |
                              v
               VLQ + Base64エンコード
                              |
                              v
               V3 SourceMap JSON  -----> .map ファイル
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| sourcemap.litcoffee | `src/sourcemap.litcoffee` | ソース | ソースマップ生成 |
| sourcemap.html | `docs/v2/annotated-source/sourcemap.html` | テンプレート | Docco生成HTML |
| coffeescript.coffee | `src/coffeescript.coffee` | ソース | SourceMap使用 |
| nodes.coffee | `src/nodes.coffee` | ソース | 位置情報付きコード生成 |
| docco.css | `docs/v2/annotated-source/docco.css` | スタイル | ドキュメントスタイル |
