# 通知設計書 1-reserved_word

## 概要

本ドキュメントは、CoffeeScriptコンパイラが予約語を識別子として使用しようとした際に発生する構文エラー「reserved word」の通知仕様を定義する。

### 本通知の処理概要

CoffeeScriptコンパイラのレキサー（字句解析器）において、JavaScriptの予約語（case、function、var、void、with、const、let、enum、native、implements、interface、package、private、protected、public、static）がソースコード内で識別子として使用された場合に、構文エラーとして通知を行う処理である。

**業務上の目的・背景**：CoffeeScriptはJavaScriptにコンパイルされる言語であり、JavaScriptの予約語をCoffeeScriptの識別子として使用すると、生成されるJavaScriptコードがランタイムエラーを引き起こす可能性がある。この通知により、開発者はコンパイル時点で問題を発見・修正でき、実行時エラーを未然に防止できる。

**通知の送信タイミング**：レキサーが識別子トークン（IDENTIFIER）を解析している最中に、その識別子がRESERVED配列に含まれる予約語であることを検出した時点で即座に発生する。JSXタグ内の場合は例外的に許可される。

**通知の受信者**：CoffeeScriptソースコードをコンパイルしている開発者。コマンドラインインターフェース、Node.js API、またはブラウザコンパイラを通じてエラーメッセージを受け取る。

**通知内容の概要**：エラーメッセージとして「reserved word '{identifier}'」という形式で、問題となった予約語を特定できるようにしている。また、エラー発生位置（行番号・列番号）も併せて通知される。

**期待されるアクション**：開発者は該当する予約語を別の識別子名に変更するか、またはプロパティとしてアクセスする形式（例：obj.case）に書き換えることで問題を解決する。

## 通知種別

コンパイラ出力（標準エラー出力 / SyntaxError例外）

## 送信仕様

### 基本情報

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

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

CoffeeScriptコンパイラを呼び出しているコンテキストに依存する：
- CLI実行時：標準エラー出力に出力
- Node.js API使用時：SyntaxError例外をスロー
- ブラウザコンパイラ使用時：SyntaxError例外をスロー

## 通知テンプレート

### エラーメッセージ形式

| 項目 | 内容 |
|-----|------|
| 形式 | テキスト |

### 本文テンプレート

```
[filename]:[line]:[column]: error: reserved word '{identifier}'
[source_code_line]
[marker]
```

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| identifier | 使用された予約語 | レキサーで検出された識別子 | Yes |
| filename | ソースファイル名 | コンパイルオプションまたは標準入力 | No |
| line | エラー発生行番号 | locationData.first_line | Yes |
| column | エラー発生列番号 | locationData.first_column | Yes |
| source_code_line | エラーが発生した行のソースコード | 入力ソースコード | Yes |
| marker | エラー位置を示すマーカー（^記号） | 計算により生成 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| コンパイル処理 | identifierToken()メソッド実行中 | 識別子がRESERVED配列に含まれ、かつJSXタグ内でない場合 | レキサーが識別子を解析している際に予約語を検出 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| JSXタグ内での使用 | JSXタグ内では予約語を属性名として使用可能なため抑止 |
| プロパティアクセス | obj.case のようにプロパティとしてアクセスする場合は許可 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[identifierToken開始] --> B[識別子を抽出]
    B --> C{PROPERTYタグか?}
    C -->|Yes| D[エラーなし:継続]
    C -->|No| E{RESERVED配列に含まれるか?}
    E -->|No| D
    E -->|Yes| F{JSXタグ内か?}
    F -->|Yes| D
    F -->|No| G[error関数を呼び出し]
    G --> H[throwSyntaxError実行]
    H --> I[SyntaxError例外発生]
    I --> J[コンパイル中断]
```

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

### 参照テーブル一覧

該当なし（メモリ内の配列参照のみ）

### 内部データ構造

| 構造名 | 用途 | 備考 |
|--------|------|------|
| RESERVED配列 | 予約語リスト | lexer.coffeeで定義 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| SyntaxError | 予約語が識別子として使用された | 開発者が識別子名を変更 |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 制限なし |
| 1日あたり上限 | 制限なし |

### 配信時間帯

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

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

- エラーメッセージにはソースコードの一部が含まれるため、ログ出力時はソースコードの機密性を考慮する必要がある
- ファイルパスが出力されるため、環境によってはパス情報の露出に注意が必要

## 備考

- RESERVED配列の内容：'case', 'function', 'var', 'void', 'with', 'const', 'let', 'enum', 'native', 'implements', 'interface', 'package', 'private', 'protected', 'public', 'static'
- これらはJavaScriptの予約語であり、CoffeeScriptでは使用できない

---

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

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

### 推奨読解順序

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

まず、予約語を定義している配列を確認することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | lexer.coffee | `src/lexer.coffee` | RESERVED配列の定義（1258-1262行目） |

**読解のコツ**: RESERVED配列はJavaScriptの予約語を格納しており、これらがCoffeeScriptで識別子として使用されると構文エラーとなる。

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

処理の起点となる関数を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | lexer.coffee | `src/lexer.coffee` | identifierToken()メソッド（125-260行目） |

**主要処理フロー**:
1. **125-128行目**: 識別子トークンのマッチング開始
2. **231-232行目**: 識別子がRESERVED配列に含まれるかチェックし、含まれていればエラーを発生

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

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

**主要処理フロー**:
- **1178-1185行目**: errorメソッドがlocationDataを構築してthrowSyntaxErrorを呼び出す
- **213-223行目**: SyntaxError例外を生成し、カスタムtoStringメソッドを設定してスロー

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

```
Lexer.tokenize()
    |
    +-- identifierToken()
           |
           +-- RESERVED配列チェック (231-232行目)
           |       |
           |       +-- [予約語検出時] error()
           |                |
           |                +-- throwSyntaxError() [helpers.coffee]
           |                        |
           |                        +-- SyntaxError例外発生
           |
           +-- [正常時] token()
```

### データフロー図

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

ソースコード  -----> identifierToken()  -----> トークンストリーム
    |                     |
    |                     v
    |               RESERVED配列と比較
    |                     |
    |              [予約語の場合]
    |                     |
    |                     v
    +------------> error() + throwSyntaxError()
                          |
                          v
                   SyntaxError例外
                          |
                          v
                   エラーメッセージ出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| lexer.coffee | `src/lexer.coffee` | ソース | 字句解析器。識別子トークンの解析と予約語チェックを行う |
| helpers.coffee | `src/helpers.coffee` | ソース | ヘルパー関数群。throwSyntaxErrorでエラー生成 |
| error_messages.coffee | `test/error_messages.coffee` | テスト | エラーメッセージのフォーマットテスト |
