# 機能設計書 18-コードフラグメント

## 概要

本ドキュメントは、CoffeeScriptコンパイラにおけるコードフラグメント機能の設計を記述する。CodeFragmentクラスは、生成されたJavaScriptコードの断片を位置情報と共に管理する機能を提供する。

### 本機能の処理概要

コードフラグメント機能は、CoffeeScriptからJavaScriptへのコード生成時に、ソースマップ生成のための位置情報を保持しながらコード断片を管理するための機能である。

**業務上の目的・背景**：CoffeeScriptコンパイラは、ソースマップ生成をサポートしている。ソースマップは、生成されたJavaScriptコードの各部分が、元のCoffeeScriptソースコードのどの位置に対応するかを記録したファイルである。これにより、ブラウザのデバッガでJavaScriptを実行しながら、CoffeeScriptのソースコードを参照してデバッグできる。CodeFragmentクラスは、この位置情報をコード生成時に保持し、最終的なソースマップ生成を可能にする。また、コメントの適切な位置への配置もサポートする。

**機能の利用シーン**：
- ノードのcompileNodeメソッド実行時：makeCodeでフラグメントを生成
- コード出力時：fragmentsToTextでフラグメントを結合
- ソースマップ生成時：各フラグメントの位置情報を使用
- コメント出力時：フラグメントにコメント情報を付加

**主要な処理内容**：
1. CodeFragmentインスタンスの生成：code、type、locationData、commentsを保持
2. makeCodeメソッド：親ノードからCodeFragmentを生成
3. fragmentsToText関数：フラグメント配列をJavaScript文字列に結合
4. コメントフラグメントの管理：precedingComments、followingComments
5. ソースマップ生成への位置情報提供

**関連システム・外部連携**：
- nodes.coffee：各ノードのcompileNodeがCodeFragmentを生成
- sourcemap.litcoffee：CodeFragmentの位置情報を使用してソースマップを生成

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 11 | Annotated Source - Nodes | 補助機能 | CodeFragmentクラスの解説を含む |
| 26 | Annotated Source - Nodes | 補助機能 | CodeFragmentクラスの解説を含む（v2） |

## 機能種別

コード生成 / 位置情報管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| parent | Base | No | このフラグメントを生成したノード | Baseインスタンスまたはnull |
| code | String | Yes | 生成されたJavaScriptコード断片 | 任意の文字列 |

### 入力データソース

各ノードクラスのcompileNodeメソッドから生成される。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| code | String | JavaScriptコード断片 |
| type | String | 生成元ノードのクラス名 |
| locationData | Object | ソース位置情報（first_line, first_column等） |
| comments | Array | 付随するコメント |

### 出力先

fragmentsToTextで結合され、最終的なJavaScript出力となる。

## 処理フロー

### 処理シーケンス

```
1. ノードのコンパイル
   └─ compileNode内でmakeCodeを呼び出し

2. CodeFragmentの生成
   ├─ codeを文字列として保存
   ├─ typeに親ノードのクラス名を設定
   ├─ locationDataに親ノードの位置情報を設定
   └─ commentsに親ノードのコメントを設定

3. フラグメント配列の構築
   └─ 複数のCodeFragmentを配列として返す

4. コメントの付加（compileCommentFragments）
   ├─ precedingCommentsとして前方に付加
   └─ followingCommentsとして後方に付加

5. フラグメントの結合
   └─ fragmentsToTextで各フラグメントのcodeを結合

6. ソースマップ生成（オプション）
   └─ 各フラグメントのlocationDataを使用
```

### フローチャート

```mermaid
flowchart TD
    A[compileNode呼び出し] --> B[makeCode実行]
    B --> C[CodeFragment生成]
    C --> D[code, type, locationData設定]
    D --> E[フラグメント配列に追加]
    E --> F{コメントあり?}
    F -->|Yes| G[コメントフラグメント付加]
    F -->|No| H[フラグメント配列を返す]
    G --> H
    H --> I[fragmentsToText]
    I --> J[JavaScript文字列]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-18-01 | 位置情報保持 | 各フラグメントは生成元の位置情報を保持 | フラグメント生成時 |
| BR-18-02 | コメント前方付加 | precedingCommentsは次の有効トークンの前に出力 | コメント配置時 |
| BR-18-03 | コメント後方付加 | followingCommentsは前のコードの後に出力 | コメント配置時 |
| BR-18-04 | 型情報保持 | typeは生成元ノードのクラス名を保持 | フラグメント生成時 |
| BR-18-05 | コード結合順序 | フラグメントは配列順に結合される | fragmentsToText時 |

### 計算ロジック

CodeFragmentコンストラクタ:
```coffeescript
constructor: (parent, code) ->
  @code = "#{code}"
  @type = parent?.constructor?.name or 'unknown'
  @locationData = parent?.locationData
  @comments = parent?.comments
```

fragmentsToText関数:
```coffeescript
fragmentsToText = (fragments) ->
  (fragment.code for fragment in fragments).join('')
```

## データベース操作仕様

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

データベースは使用しない。

### テーブル別操作詳細

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | CodeFragment自体はエラーを発生させない | - |

### リトライ仕様

該当なし。

## トランザクション仕様

トランザクションは使用しない。

## パフォーマンス要件

特に定められていない。

## セキュリティ考慮事項

特になし。

## 備考

- CodeFragmentはデバッグ時にtoStringで位置情報付きの文字列を出力可能
- HoistTarget.expandでホイストされたフラグメントを展開

---

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

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

### 推奨読解順序

#### Step 1: CodeFragmentクラスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | nodes.coffee | `src/nodes.coffee` | 27-46行目のCodeFragmentクラス定義を理解する |

**読解のコツ**: CodeFragmentは非常にシンプルなデータ保持クラス。code、type、locationData、commentsの4プロパティを持つ。

**主要処理フロー**:
- **33-38行目**: コンストラクタでcode、type、locationData、commentsを初期化
- **40-42行目**: toStringメソッドでデバッグ用文字列を生成
- **45-46行目**: fragmentsToText関数でフラグメント配列を結合

#### Step 2: makeCodeメソッドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | nodes.coffee | `src/nodes.coffee` | 450-451行目のmakeCodeメソッドを理解する |

**主要処理フロー**:
- **450-451行目**: `makeCode: (code) -> new CodeFragment this, code`
- thisを親として、codeを持つCodeFragmentを生成

#### Step 3: コメントフラグメントの処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | nodes.coffee | `src/nodes.coffee` | 142-189行目のcompileCommentFragmentsメソッドを理解する |

**主要処理フロー**:
- **164-188行目**: コメントをフラグメントに付加するロジック
- **183-185行目**: precedingCommentsとして前方に付加
- **186-188行目**: followingCommentsとして後方に付加

#### Step 4: フラグメントの結合処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | nodes.coffee | `src/nodes.coffee` | 723-834行目のBlock.compileCommentsを理解する |

**主要処理フロー**:
- **727-767行目**: precedingCommentsの挿入位置を決定
- **772-832行目**: followingCommentsの挿入位置を決定

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

```
Base.compile() (nodes.coffee:61)
    │
    └─ compileToFragments() (nodes.coffee:98)
           │
           ├─ compileNode() (各クラス)
           │      │
           │      └─ makeCode() (nodes.coffee:450)
           │             │
           │             └─ new CodeFragment(this, code)
           │
           ├─ compileCommentFragments() (nodes.coffee:142)
           │      │
           │      ├─ precedingComments付加
           │      └─ followingComments付加
           │
           └─ fragmentsToText() (nodes.coffee:45)
                  │
                  └─ fragment.code を結合
```

### データフロー図

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

ノード                   CodeFragment生成                JavaScript
    │                        │                              │
parent ─────────▶  ├─ code: 生成コード              "var x = 1;"
├─ locationData     ├─ type: "Assign"          ───▶
└─ comments         ├─ locationData: {line:1}
                    └─ comments: [...]

[ソースマップ]
    │
sourcemap.litcoffee ◀─── locationData
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| nodes.coffee | `src/nodes.coffee` | ソース | CodeFragmentクラス定義、makeCode、compileCommentFragments |
| sourcemap.litcoffee | `src/sourcemap.litcoffee` | ソース | CodeFragmentの位置情報を使用してソースマップ生成 |
| coffeescript.coffee | `src/coffeescript.coffee` | ソース | コンパイルパイプライン |
