# 通知設計書 21-unicode code point error

## 概要

本ドキュメントは、CoffeeScriptコンパイラにおけるUnicodeコードポイントエスケープエラー（unicode code point error）の通知仕様を記述する。

### 本通知の処理概要

本通知は、CoffeeScriptソースコード内で使用されるUnicodeコードポイントエスケープ（`\u{xxxxxx}`形式）が無効な範囲を指定した場合に発生するエラーメッセージである。

**業務上の目的・背景**：Unicodeコードポイントエスケープは、ES2015で導入された機能であり、CoffeeScript 1.12.6以降でサポートされている。Unicodeの有効なコードポイント範囲はU+0000からU+10FFFFまでであり、この範囲を超える値は無効である。開発者がこの範囲を超えた値を指定した場合、早期にエラーを通知することで、コンパイル後の予期しない動作を防止する。

**通知の送信タイミング**：コンパイル時、具体的には文字列リテラルまたは正規表現リテラル内のUnicodeコードポイントエスケープを処理する際に、`replaceUnicodeCodePointEscapes`関数内でコードポイントの値を検証するタイミングで発生する。

**通知の受信者**：CoffeeScriptコンパイラを実行している開発者。コンソール出力またはエラーオブジェクトとして通知される。

**通知内容の概要**：エラーメッセージ「unicode code point escapes greater than \u{10ffff} are not allowed」とともに、エラーが発生したソースコード内の位置情報（行番号・列番号）が提供される。

**期待されるアクション**：開発者は、指定されたコードポイント値をU+10FFFF以下の有効な値に修正する必要がある。

## 通知種別

コンソールエラー出力 / SyntaxError例外

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（コンパイル処理中に即時発生） |
| 優先度 | 高（コンパイルエラー） |
| リトライ | なし（即時エラー終了） |

### 送信先決定ロジック

コンパイラを実行しているプロセスの標準エラー出力、またはAPIとして呼び出された場合はSyntaxError例外として呼び出し元に返される。

## 通知テンプレート

### コンソール出力の場合

| 項目 | 内容 |
|-----|------|
| 出力先 | stderr |
| 形式 | テキスト |

### 本文テンプレート

```
[ファイル名]:[行番号]:[列番号]: error: unicode code point escapes greater than \u{10ffff} are not allowed
[該当行のソースコード]
[エラー位置を示すキャレット]
```

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| filename | ソースファイル名 | コンパイルオプション | Yes |
| line | エラー発生行番号 | Lexer位置情報 | Yes |
| column | エラー発生列番号 | offset計算結果 | Yes |
| codePointHex | 指定されたコードポイント値（16進） | 正規表現マッチ結果 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| コンパイル処理 | Unicodeコードポイントエスケープの解析 | codePointDecimal > 0x10ffff | 16進数を10進数に変換した値が0x10ffff（1,114,111）を超える場合 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| 有効範囲内の値 | 0x0000〜0x10ffffの範囲内であればエラーは発生しない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[文字列/正規表現リテラル解析] --> B[replaceUnicodeCodePointEscapes呼び出し]
    B --> C{コードポイント値の検証}
    C -->|> 0x10ffff| D[error関数呼び出し]
    C -->|<= 0x10ffff| E[正常処理継続]
    D --> F[SyntaxError生成]
    F --> G[エラーメッセージ出力]
    G --> H[コンパイル中断]
    E --> I[Unicode変換処理]
    I --> J[処理完了]
```

## データベース参照・更新仕様

### 参照テーブル一覧

該当なし（ファイルベースのコンパイル処理）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| SyntaxError | コードポイント > 0x10ffff | ソースコードの該当箇所を有効な値に修正 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 制限 | なし（コンパイル時エラー） |

### 配信時間帯

制限なし（コンパイル実行時に即時通知）

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

- エラーメッセージにはソースコードの断片が含まれる可能性があるため、ログ出力先の管理に注意
- 機密情報を含む可能性のある文字列リテラル内のエラーは、ログに残る可能性がある

## 備考

- 本エラーはCoffeeScript 1.12.6でUnicodeコードポイントエスケープがサポートされた際に導入された
- ES2015仕様に準拠したUnicodeコードポイントの有効範囲チェック

---

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

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

### 推奨読解順序

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

Unicodeコードポイントエスケープの正規表現パターンと、エラー情報の構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | helpers.coffee | `src/helpers.coffee` | UNICODE_CODE_POINT_ESCAPE正規表現（321-325行目）の構造を理解 |

**読解のコツ**: CoffeeScriptのヒアドキュメント風正規表現（`///`）は複数行に分割されており、コメントも含められる。

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

エラーが発生する`replaceUnicodeCodePointEscapes`関数を理解する。

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

**主要処理フロー**:
1. **307行目**: 関数定義、flags/error/delimiterオプションを受け取る
2. **309行目**: UNICODE_CODE_POINT_ESCAPEパターンでマッチングを実行
3. **312行目**: マッチした16進数値を10進数に変換
4. **313-316行目**: 0x10ffffを超える場合、error関数を呼び出してエラー通知

#### Step 3: エラー出力処理を理解する

error関数がどのように呼び出され、SyntaxErrorが生成されるかを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | helpers.coffee | `src/helpers.coffee` | throwSyntaxError関数 |
| 3-2 | lexer.coffee | `src/lexer.coffee` | error メソッド（1178行目以降） |

**主要処理フロー**:
- **314行目**: errorコールバックにメッセージとoffset/length情報を渡す
- errorコールバックは通常Lexerのerrorメソッドであり、throwSyntaxErrorを呼び出す

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

```
CoffeeScript.compile()
    │
    ├─ Lexer.tokenize()
    │      ├─ stringToken() / regexToken()
    │      │      └─ validateUnicodeCodePointEscapes()
    │      │             └─ replaceUnicodeCodePointEscapes()
    │      │                    └─ > 0x10ffff → error()
    │      │                           └─ throwSyntaxError()
    │      └─ matchWithInterpolations()
    │             └─ validateUnicodeCodePointEscapes()
    │
    └─ エラー時: SyntaxError例外をスロー
```

### データフロー図

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

ソースコード           replaceUnicodeCodePointEscapes      エラーメッセージ
"\u{110000}"  ───▶     parseInt("110000", 16)     ───▶    "unicode code point
                              │                            escapes greater than
                              ▼                            \u{10ffff} are not
                       1114112 > 1114111                   allowed"
                              │
                              ▼
                       error()呼び出し
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| helpers.coffee | `src/helpers.coffee` | ソース | Unicodeエスケープ処理、エラー関数定義 |
| lexer.coffee | `src/lexer.coffee` | ソース | 文字列・正規表現のトークン化、エラーハンドリング |
| coffeescript.coffee | `src/coffeescript.coffee` | ソース | コンパイルエントリーポイント |
| error_messages.coffee | `test/error_messages.coffee` | テスト | エラーメッセージのテストケース（1546-1603行目） |
