# 通知設計書 4-コンパイラエラー・警告

## 概要

本ドキュメントは、Vue.jsテンプレートコンパイラ（`@vue/compiler-core`）におけるエラー・警告通知機構の設計仕様を記述する。`packages/compiler-core/src/errors.ts`に実装されており、テンプレートのパース・変換時にエラーや警告を検出した場合に`onError`（デフォルトでthrow）と`onWarn`（デフォルトで`console.warn`）のコールバックを通じて伝達する。約40種類のパース/変換エラーコードが`ErrorCodes` enumとして定義されている。

### 本通知の処理概要

この通知は、Vueテンプレートのコンパイル時（パース・変換フェーズ）にエラーや警告を検出した場合に通知する機構である。エラーは`CompilerError`型として構造化され、ソースコード上の位置情報（`SourceLocation`）を含む。

**業務上の目的・背景**：Vueテンプレートコンパイラは、テンプレート文字列をレンダリング関数に変換するプロセスで動作する。HTMLパースエラー（不正なタグ構文、属性の重複など）やVue固有の変換エラー（v-ifの式欠落、v-modelの不正使用など）を構造化されたエラーオブジェクトとして開発者に通知する。エラーコードにより機械的な判別が可能であり、IDE統合やリンター等のツール連携にも対応できる設計になっている。

**通知の送信タイミング**：テンプレートのパースフェーズ（HTML構文解析）および変換フェーズ（ディレクティブ処理等）で問題が検出された時点で即座に発火する。`onError`コールバックはデフォルトでthrowするため、最初のエラーでコンパイル処理が停止する。

**通知の受信者**：テンプレートコンパイラの呼び出し元（ビルドツール、SFCコンパイラ、ブラウザ内ランタイムコンパイラ）。最終的には開発者がエラーメッセージを確認する。

**通知内容の概要**：エラーコード（`ErrorCodes` enum値）、エラーメッセージ、ソースコード位置情報（`SourceLocation`）を含む`CompilerError`オブジェクトが通知される。

**期待されるアクション**：開発者がテンプレートの記述を修正する。エラーコードとソース位置情報により問題箇所の特定が容易になっている。

## 通知種別

エラーハンドリング（`throw SyntaxError` / `console.warn`）/ コールバック委譲（`onError` / `onWarn`）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 高（エラー時はthrow） / 中（警告時はconsole.warn） |
| リトライ | なし |

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

1. **エラー（onError）**: デフォルトでは`throw`する（`defaultOnError`）。コンパイルオプションで`onError`コールバックを指定すれば、throwせずにエラーを収集可能。
2. **警告（onWarn）**: デフォルトでは`console.warn`する（`defaultOnWarn`）。`__DEV__`がtrueの場合のみ動作する。コンパイルオプションで`onWarn`コールバックを指定可能。

## 通知テンプレート

### コンソール出力の場合（警告）

| 項目 | 内容 |
|-----|------|
| 送信元アドレス | N/A |
| 送信元名称 | `[Vue warn]` |
| 件名 | N/A |
| 形式 | テキスト |

### 本文テンプレート

```
[Vue warn] {CompilerError.message}
```

エラーの場合はSyntaxErrorとしてthrowされる：
```
SyntaxError: {エラーメッセージ}
  code: {ErrorCodes enum値}
  loc: {SourceLocation}
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| N/A | N/A | N/A | コンソール出力のため添付ファイルなし |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| code | エラーコード（ErrorCodes enum値） | コンパイラが検出したエラー種別 | Yes |
| message | エラーメッセージ | errorMessagesレコードから取得、またはVue公式URLへのリンク | Yes |
| loc | ソースコード位置情報 | コンパイラのパーサーが検出した位置 | No |
| additionalMessage | 追加メッセージ | 呼び出し元から渡される補足情報 | No |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| パースエラー | HTML構文エラー（22種類） | 常時 | ABRUPT_CLOSING_OF_EMPTY_COMMENT〜UNEXPECTED_SOLIDUS_IN_TAG |
| パースエラー | Vue固有パースエラー（5種類） | 常時 | X_INVALID_END_TAG〜X_MISSING_DYNAMIC_DIRECTIVE_ARGUMENT_END |
| 変換エラー | ディレクティブ変換エラー（19種類） | 常時 | X_V_IF_NO_EXPRESSION〜X_KEEP_ALIVE_INVALID_CHILDREN |
| 汎用エラー | ビルド構成エラー（4種類） | 常時 | X_PREFIX_ID_NOT_SUPPORTED〜X_SCOPE_ID_NOT_SUPPORTED |
| 非推奨警告 | VNodeフック非推奨（1種類） | 常時 | X_VNODE_HOOKS |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| `__DEV__` がfalse | defaultOnWarnのconsole.warn出力が抑止される |
| カスタムonError設定時 | throwの代わりにカスタムハンドラに委譲 |
| `__BROWSER__` がtrue | エラーメッセージがVue公式URLリンクに置換される（バンドルサイズ削減） |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[テンプレートパース/変換中にエラー検出] --> B[createCompilerError呼び出し]
    B --> C[ErrorCodesからメッセージ取得]
    C --> D{__DEV__ or !__BROWSER__?}
    D -->|Yes| E[errorMessages辞書からメッセージ取得]
    D -->|No| F[Vue公式URLリンクを使用]
    E --> G[SyntaxErrorオブジェクト生成]
    F --> G
    G --> H[code, locプロパティを付与]
    H --> I{onError or onWarn?}
    I -->|onError| J{カスタムonError設定?}
    J -->|未設定| K[defaultOnError: throw error]
    J -->|設定あり| L[カスタムハンドラに委譲]
    I -->|onWarn| M{__DEV__?}
    M -->|Yes| N["console.warn('[Vue warn] ' + msg.message)"]
    M -->|No| O[何もしない]
    K --> P[終了]
    L --> P
    N --> P
    O --> P
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| N/A | N/A | データベースは使用しない |

### テーブル別参照項目詳細

本通知はデータベースを使用しない。以下の定数データを参照する。

| 参照データ | 用途 | 取得方法 |
|-----------|------|---------|
| ErrorCodes (enum) | エラーコードの列挙 | errors.ts L40-110 |
| errorMessages (Record) | エラーコードに対応するメッセージ文字列 | errors.ts L112-193 |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| N/A | N/A | データベースの更新は行わない |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| SyntaxError throw | defaultOnErrorでエラーが発生した場合 | 呼び出し元でcatch |
| カスタムハンドラエラー | カスタムonErrorハンドラ内でエラー発生 | 呼び出し元の責任 |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

制限なし。

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

- テンプレートのソースコード位置情報が含まれるが、開発環境でのみ詳細メッセージが表示される
- 本番ビルド（`__BROWSER__` = true）ではメッセージがVue公式URLリンクに置換され、バンドルサイズが削減される

## 備考

- ErrorCodesは`__EXTEND_POINT__`を末尾に持ち、拡張コンパイラ（vue-compiler-dom等）がエラーコードを追加する際の衝突を防止する
- WatchErrorCodesはreactivityパッケージに移動されている（コード互換性維持のためErrorCodes内にコメントアウトで残存）
- X_V_BIND_INVALID_SAME_NAME_ARGUMENT（同名省略記法エラー）はv3.5以降で追加された比較的新しいエラーコード
- 約40種類のエラーコードは大きく4カテゴリに分類される：HTMLパースエラー（22種）、Vue固有パースエラー（5種）、変換エラー（19種）、汎用エラー（5種）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | errors.ts | `packages/compiler-core/src/errors.ts` | L3-10: CompilerError, CoreCompilerErrorインターフェース。code, loc, messageプロパティ |
| 1-2 | errors.ts | `packages/compiler-core/src/errors.ts` | L40-110: ErrorCodes enum。約40種類のエラーコード定義 |
| 1-3 | errors.ts | `packages/compiler-core/src/errors.ts` | L112-193: errorMessagesレコード。各エラーコードに対応するメッセージ文字列 |

**読解のコツ**: ErrorCodesはHTMLパースエラー、Vue固有パースエラー、変換エラー、汎用エラーの4カテゴリに分かれている。コメントで区切られているため視認性が高い。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | errors.ts | `packages/compiler-core/src/errors.ts` | L24-38: createCompilerError関数。エラーオブジェクトの生成ロジック |
| 2-2 | errors.ts | `packages/compiler-core/src/errors.ts` | L12-18: defaultOnError/defaultOnWarn関数。デフォルトのエラー/警告ハンドラ |

**主要処理フロー**:
1. **L30-33**: `__DEV__ || !__BROWSER__`の条件でメッセージソースを切替（開発時は詳細メッセージ、本番時はURLリンク）
2. **L34**: `SyntaxError`オブジェクトを生成
3. **L35-36**: `code`と`loc`プロパティを付与
4. **L12-13**: defaultOnError - `throw error`で例外を送出
5. **L16-17**: defaultOnWarn - `__DEV__`時のみ`console.warn`で出力

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

```
[テンプレートパーサー / トランスフォーマー]
    |
    +-- createCompilerError(code, loc, messages)  [errors.ts:24]
    |       |
    |       +-- errorMessages[code]                [errors.ts:112]
    |       +-- new SyntaxError(msg)
    |       +-- error.code = code
    |       +-- error.loc = loc
    |
    +-- onError(error)                             [コンパイルオプション]
    |       |
    |       +-- [デフォルト] defaultOnError()       [errors.ts:12]
    |       |       +-- throw error
    |       |
    |       +-- [カスタム] ユーザー定義ハンドラ
    |
    +-- onWarn(error)                              [コンパイルオプション]
            |
            +-- [デフォルト] defaultOnWarn()        [errors.ts:16]
            |       +-- console.warn()
            |
            +-- [カスタム] ユーザー定義ハンドラ
```

### データフロー図

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

code (ErrorCodes)     +-- createCompilerError()         +-- throw SyntaxError
  |                   |     |                           |     (defaultOnError)
loc (SourceLocation) ---->|  +-- errorMessages参照        |
  |                   |     +-- SyntaxError生成      ---->+-- console.warn()
additionalMessage --->|     +-- code/loc付与             |     (defaultOnWarn)
                      |                                 |
                      +-- onError / onWarn              +-- カスタムハンドラ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| errors.ts | `packages/compiler-core/src/errors.ts` | ソース | CompilerError型、ErrorCodes enum、createCompilerError関数、デフォルトハンドラ |
| ast.ts | `packages/compiler-core/src/ast.ts` | ソース | SourceLocation型の定義 |
