# 機能設計書 55-構文エラー処理

## 概要

本ドキュメントは、CoffeeScriptコンパイラの構文エラー処理機能の設計を記述する。構文エラーの生成、ソース位置情報の付加、エラーメッセージのフォーマット表示を行う。

### 本機能の処理概要

構文エラー処理機能は、CoffeeScriptコードのコンパイル時に発生する構文エラーを検出し、開発者が問題を特定しやすい形式でエラー情報を提供する。エラー発生箇所の行番号・列番号、該当行のコード、エラー箇所を示すマーカーなどを含む詳細なエラーメッセージを生成する。

**業務上の目的・背景**：コンパイル時のエラーメッセージは、開発者が問題を迅速に特定・修正するための重要な情報源である。不明瞭なエラーメッセージは開発効率を低下させるため、エラー発生位置と内容を明確に示す必要がある。本機能は、標準的なエラーメッセージ形式（`<filename>:<line>:<col>: error: <message>`）を提供し、ソースコードの該当箇所を視覚的に示すことで、デバッグ効率を向上させる。

**機能の利用シーン**：
- CoffeeScriptコードのコンパイル時に構文エラーが発生した場合
- REPLでの入力エラー表示
- IDEやエディタのエラーハイライト情報提供
- ビルドツールでのエラー出力

**主要な処理内容**：
1. SyntaxErrorオブジェクトの生成と位置情報の付加
2. エラーメッセージのフォーマット（ファイル名:行番号:列番号）
3. 該当行のコードスニペット表示
4. エラー箇所を示すキャレットマーカー（^）の生成
5. カラー出力対応（TTY環境の場合）

**関連システム・外部連携**：
- Node.js process.stdout（カラー出力判定）
- Lexer、Parser、Nodes（エラー発生元）

**権限による制御**：該当なし

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 17 | Annotated Source - Helpers | 補助画面 | throwSyntaxErrorの解説を含む |
| 32 | Annotated Source - Helpers | 補助画面 | throwSyntaxErrorの解説を含む（v2） |

## 機能種別

エラー処理 / メッセージフォーマット

## 入力仕様

### 入力パラメータ

#### throwSyntaxError関数
| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| message | String | Yes | エラーメッセージ | - |
| location | Object | Yes | エラー発生位置情報 | first_line, first_column, last_line, last_columnを含む |

#### updateSyntaxError関数
| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| error | SyntaxError | Yes | 更新対象のエラーオブジェクト | - |
| code | String | No | ソースコード | - |
| filename | String | No | ファイル名 | - |

### 入力データソース

- Lexer、Parser、Nodesからのエラー情報
- ソースコード文字列
- ファイル名情報

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| error | SyntaxError | 位置情報とフォーマット済みスタックを持つエラーオブジェクト |
| error.location | Object | エラー発生位置（first_line, first_column, last_line, last_column） |
| error.stack | String | フォーマット済みエラーメッセージ |

### 出力先

- 例外としてthrow
- error.stackプロパティ

## 処理フロー

### 処理シーケンス

```
1. throwSyntaxError呼び出し
   └─ message: エラーメッセージ
   └─ location: 位置情報オブジェクト

2. SyntaxErrorオブジェクト生成
   └─ new SyntaxError(message)
   └─ error.location = location

3. toStringメソッドの設定
   └─ syntaxErrorToString関数を代入

4. スタックトレースの設定
   └─ error.stack = error.toString()
   └─ コンパイラ内部スタックを隠蔽

5. エラーをthrow
```

### フローチャート

```mermaid
flowchart TD
    A[throwSyntaxError呼び出し] --> B[SyntaxError生成]
    B --> C[location設定]
    C --> D[toString設定]
    D --> E[stack設定]
    E --> F[throw error]

    subgraph syntaxErrorToString
        G[code/locationあり?] -->|No| H[Error.toString]
        G -->|Yes| I[位置情報取得]
        I --> J[filename決定]
        J --> K[codeLine取得]
        K --> L[マーカー生成]
        L --> M{カラー対応?}
        M -->|Yes| N[カラー適用]
        M -->|No| O[プレーン]
        N --> P[フォーマット済み文字列]
        O --> P
    end
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-55-01 | 標準エラー形式 | `<filename>:<line>:<col>: error: <message>` の形式で出力 | 全エラー |
| BR-55-02 | 1-indexed表示 | 行番号・列番号は1から開始（内部は0-indexed） | 表示時 |
| BR-55-03 | 匿名ファイル名 | filenameが`<anonymous`で始まる場合は`[stdin]`と表示 | 匿名スクリプト |
| BR-55-04 | 複数行エラー | first_lineとlast_lineが異なる場合は最初の行のみ表示 | 複数行にまたがるエラー |
| BR-55-05 | カラー出力 | process.stdout.isTTYがtrueかつNODE_DISABLE_COLORSが未設定の場合 | TTY環境 |
| BR-55-06 | マーカー表示 | エラー箇所を`^`で示す。複数文字の場合は連続したキャレット | 全エラー |

### 計算ロジック

**マーカー生成ロジック**:
```
start = first_column
end = (first_line === last_line) ? last_column + 1 : codeLine.length
marker = ' '.repeat(start) + '^'.repeat(end - start)
```

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

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| SyntaxError | 構文エラー | 不正な構文 | エラー位置情報とメッセージを表示 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- エラーメッセージのフォーマット処理は同期的に実行
- パフォーマンスへの影響は軽微

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

- ソースコードがエラーメッセージに含まれるため、センシティブな情報がログに出力される可能性に注意

## 備考

- カラー出力は赤色（ANSI: `\x1B[1;31m`）を使用
- error.colorfulプロパティでカラー出力を強制的に有効/無効化可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | helpers.coffee | `src/helpers.coffee` | locationオブジェクトの構造（first_line, first_column等） |

**読解のコツ**: locationオブジェクトは以下のプロパティを持つ
- first_line, first_column: エラー開始位置（0-indexed）
- last_line, last_column: エラー終了位置（0-indexed）
- range: [開始オフセット, 終了オフセット]

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | helpers.coffee | `src/helpers.coffee` | throwSyntaxError関数（213-223行目） |

**主要処理フロー**:
1. **214行目**: `new SyntaxError message` でエラーオブジェクト生成
2. **215行目**: `error.location = location` で位置情報設定
3. **216行目**: `error.toString = syntaxErrorToString` でカスタムtoString設定
4. **221行目**: `error.stack = error.toString()` でスタック設定
5. **223行目**: `throw error` でエラーをスロー

#### Step 3: エラーメッセージフォーマットを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | helpers.coffee | `src/helpers.coffee` | syntaxErrorToString関数（235-266行目） |

**主要処理フロー**:
- **236行目**: code/locationが無い場合はError.toString()を呼び出し
- **238-240行目**: 位置情報の取得とデフォルト値設定
- **242-245行目**: ファイル名の決定（匿名の場合は[stdin]）
- **247行目**: エラー行のコード取得
- **248-250行目**: start/end位置の計算
- **251行目**: マーカー文字列の生成
- **254-260行目**: カラー出力の判定と適用
- **262-266行目**: 最終的なフォーマット済み文字列の構築

#### Step 4: updateSyntaxError関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | helpers.coffee | `src/helpers.coffee` | updateSyntaxError関数（227-233行目） |

**主要処理フロー**:
- **229行目**: toStringがsyntaxErrorToStringの場合のみ更新
- **230-231行目**: codeとfilenameのデフォルト値設定
- **232行目**: stackの再生成

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

```
[エラー発生元]
    │
    ├─ Lexer
    ├─ Parser
    └─ Nodes
           │
           ▼
    throwSyntaxError(message, location)
           │
           ├─ new SyntaxError(message)
           │
           ├─ error.location = location
           │
           ├─ error.toString = syntaxErrorToString
           │
           └─ throw error
                  │
                  ▼
           syntaxErrorToString()
                  │
                  ├─ 位置情報解析
                  ├─ コード行取得
                  ├─ マーカー生成
                  ├─ カラー判定
                  └─ フォーマット出力
```

### データフロー図

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

message        ───▶  throwSyntaxError()  ───▶  SyntaxError
location       ───▶                            │
                                               ▼
code           ───▶  syntaxErrorToString()
filename       ───▶         │
                            ▼
                     フォーマット済み
                     エラーメッセージ
                            │
                            ▼
                     filename:line:col: error: message
                     codeLine
                     ^^^^^^^ (マーカー)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| helpers.coffee | `src/helpers.coffee` | ソース | 構文エラー処理の実装 |
| lexer.coffee | `src/lexer.coffee` | ソース | 字句解析エラーの発生元 |
| grammar.coffee | `src/grammar.coffee` | ソース | 構文解析エラーの発生元 |
| nodes.coffee | `src/nodes.coffee` | ソース | ノード処理エラーの発生元 |
