# 画面設計書 15-Annotated Source - SourceMap

## 概要

本ドキュメントは、CoffeeScript v1のソースコード解説ページ「Annotated Source - SourceMap」の画面設計書である。Doccoを使用して自動生成されたドキュメントページで、sourcemap.litcoffeeのソースコードとその解説を並列表示する。

### 本画面の処理概要

この画面は、CoffeeScriptコンパイラのソースマップ生成機能を実装するsourcemap.litcoffeeのソースコードを、Literate CoffeeScript形式のマークダウンテキストと実装コードを並列表示する形式で解説するドキュメントページである。SourceMapクラスは、コンパイル済みJavaScriptから元のCoffeeScriptソースコードへのマッピング情報を生成する。

**業務上の目的・背景**：デバッグ時にコンパイル済みJavaScriptのエラー位置を元のCoffeeScriptコードの位置に変換するソースマップ機能を理解するために必要な画面である。現代のJavaScript開発ではソースマップは必須の機能であり、その内部実装を理解することで、デバッグの問題解決やカスタムビルドツールの開発に役立つ知識を得られる。

**画面へのアクセス方法**：v1ドキュメントページ（docs/v1/index.html）のAnnotated Sourceセクション、またはAnnotated Source - Index（docs/v1/annotated-source/index.html）から「sourcemap.litcoffee」リンクをクリックしてアクセスする。直接URL（docs/v1/annotated-source/sourcemap.html）でもアクセス可能である。

**主要な操作・処理内容**：
1. ソースコードとコメントの並列表示を閲覧する
2. 「Jump To...」メニューから他のソースファイル解説ページへ遷移する
3. セクション番号リンク（pilcrow）をクリックして特定のコードセクションへの直接リンクを取得する
4. LineMapクラス、SourceMapクラス、V3ソースマップ生成の解説を確認する

**画面遷移**：
- 遷移元: v1ドキュメント（docs/v1/index.html）、Annotated Source - Index（docs/v1/annotated-source/index.html）、他のAnnotated Sourceページ
- 遷移先: Jump Toメニューから他のすべてのAnnotated Sourceページ

**権限による表示制御**：本画面は静的HTMLファイルであり、認証・認可の仕組みは存在しない。すべてのユーザーが同一の内容を閲覧できる。

## 関連機能

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

## 画面種別

詳細（ドキュメント閲覧画面）

## URL/ルーティング

- URL: `/docs/v1/annotated-source/sourcemap.html`
- 静的HTMLファイルとして配置

## 入出力項目

本画面は静的HTMLであり、ユーザー入力項目は存在しない。

| 項目名 | 入出力 | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| - | - | - | - | 入力項目なし |

## 表示項目

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| ページタイトル | テキスト | "sourcemap.litcoffee" |
| ソースコード | HTML（ハイライト済み） | sourcemap.litcoffeeの全ソースコード |
| コメント/解説 | HTML | Literate形式のマークダウンテキスト |
| Jump Toメニュー | リンクリスト | 他のソースファイルへのナビゲーション |
| セクションリンク | アンカーリンク | 各セクションへの直接リンク（#section-N形式） |

## イベント仕様

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

Jump Toリンクをクリックすると、対応するソースコード解説ページへ遷移する。

- イベントタイプ: クリック
- 対象要素: `#jump_to a.source`
- 処理内容: 指定されたHTMLファイルへのページ遷移

### 2-セクションリンククリック

各セクションの段落記号（pilcrow: &#182;）をクリックすると、そのセクションへの直接リンクがブラウザのURLバーに表示される。

- イベントタイプ: クリック
- 対象要素: `a.pilcrow`
- 処理内容: URLハッシュの変更（#section-N）

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

### 操作別データベース影響一覧

本画面は静的HTMLファイルであり、データベース操作は発生しない。

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| - | - | - | データベース操作なし |

## メッセージ仕様

本画面は静的HTMLであり、動的なメッセージ表示機能は存在しない。

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| - | - | - | - |

## 例外処理

本画面は静的HTMLであり、アプリケーションレベルの例外処理は存在しない。
- HTTPレベル: 404 Not Found（ファイルが存在しない場合）
- HTTPレベル: 500 Internal Server Error（サーバー設定エラー等）

## 備考

- 本画面はDoccoツールによって自動生成されたHTMLファイルである
- ソースコードはsrc/sourcemap.litcoffeeから生成される
- Literate CoffeeScript形式：マークダウンテキストとコードが混在
- V3形式のソースマップ（Source Map Revision 3）を生成
- VLQ（Variable-Length Quantity）エンコーディングを使用
- スタイルシートはdocco.cssを使用
- v2系にも同様のページ（docs/v2/annotated-source/sourcemap.html）が存在する

---

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

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

### 推奨読解順序

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

ソースマップの概念と基本的なデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | sourcemap.litcoffee | `src/sourcemap.litcoffee` | 行1-11: ソースマップの概要説明 |
| 1-2 | sourcemap.litcoffee | `src/sourcemap.litcoffee` | 行20-30: LineMapクラス - 1行分のマッピング管理 |
| 1-3 | sourcemap.litcoffee | `src/sourcemap.litcoffee` | 行43-55: SourceMapクラス - 全体のマッピング管理 |

**読解のコツ**: ソースマップは「生成されたJS行列」→「元のCoffeeScript行列」のマッピングである。LineMapが1行分、SourceMapが全体を管理する。

#### Step 2: マッピング追加処理を理解する

マッピング情報の追加と検索処理を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | sourcemap.litcoffee | `src/sourcemap.litcoffee` | 行24-26: `LineMap.add` - 列位置マッピング追加 |
| 2-2 | sourcemap.litcoffee | `src/sourcemap.litcoffee` | 行52-55: `SourceMap.add` - 行・列マッピング追加 |
| 2-3 | sourcemap.litcoffee | `src/sourcemap.litcoffee` | 行60-62: `sourceLocation` - 元位置検索 |

**主要処理フロー**:
1. **add(sourceLocation, generatedLocation)**: マッピング情報を追加
2. **sourceLocation([line, column])**: 生成コード位置から元コード位置を検索

#### Step 3: V3ソースマップ生成を理解する

V3形式のJSON出力処理を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | sourcemap.litcoffee | `src/sourcemap.litcoffee` | 行89以降: `generate`メソッド - V3出力生成 |
| 3-2 | sourcemap.litcoffee | `src/sourcemap.litcoffee` | VLQエンコーディング処理 |

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

```
sourcemap.html (生成されたHTML)
    |
    +-- sourcemap.litcoffee (ソースファイル)
           |
           +-- LineMap クラス
           |      +-- add(column, [sourceLine, sourceColumn])
           |      +-- sourceLocation(column)
           |
           +-- SourceMap クラス
                  +-- add(sourceLocation, generatedLocation)
                  +-- sourceLocation([line, column])
                  +-- generate(options, code)
```

### データフロー図

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

コンパイル時の位置情報   --->   SourceMap.add()        --->   V3 SourceMap JSON
       |                              |
       |                              +-- LineMap配列に格納
       |                              +-- VLQエンコード
       |                              +-- JSON生成
       |
       +-- sourceLocation: [行, 列]
       +-- generatedLocation: [行, 列]

V3 SourceMap構造:
{
  "version": 3,
  "sources": ["input.coffee"],
  "names": [],
  "mappings": "AAAA;AACA;..."  // VLQエンコード済み
}
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| sourcemap.html | `docs/v1/annotated-source/sourcemap.html` | 生成HTML | 本画面のHTMLファイル |
| sourcemap.litcoffee | `src/sourcemap.litcoffee` | ソース | ソースマップ生成クラス |
| coffeescript.coffee | `src/coffeescript.coffee` | ソース | SourceMapの使用元 |
| nodes.coffee | `src/nodes.coffee` | ソース | 位置情報の生成元 |
| docco.css | `docs/v1/annotated-source/docco.css` | スタイル | ページスタイル定義 |
