# 通知設計書 3-SyntaxError

## 概要

本ドキュメントは、Prettierにおいてファイルのパース時にシンタックスエラー（構文解析エラー）が検出された場合に発生するエラー通知「SyntaxError」の設計を記述する。

### 本通知の処理概要

SyntaxErrorは、ソースコードの構文解析中に文法的な誤りが検出された場合に発生するエラー通知であり、エラーの発生位置（行番号・列番号）を含む詳細な情報を提供する。

**業務上の目的・背景**：Prettierはソースコードをフォーマットする前に、各言語のパーサーを使用してコードを抽象構文木（AST）に変換する。コードに文法的な誤りがある場合、パーサーは構文解析に失敗し、エラーを発生させる。ユーザーはエラーメッセージと位置情報を元に、コードの問題箇所を特定して修正する必要がある。

**通知の送信タイミング**：`prettier.format()`等のAPI呼び出し時、またはCLI実行時に、各言語パーサー（Babel、TypeScript、Flow、Acorn、Meriyah、espree、hermes、PostCSS、GraphQL、YAML、HTML、Handlebars等）が構文解析エラーを検出した場合に発生する。`src/common/parser-create-error.js`の`createError`関数を通じてエラーオブジェクトが生成される。

**通知の受信者**：CLIを使用しているユーザー、またはAPI経由でPrettierを呼び出しているアプリケーション開発者。

**通知内容の概要**：構文エラーの内容、およびエラーが発生した行番号・列番号。パーサーによってはエラーの詳細な説明も含まれる。

**期待されるアクション**：ユーザーはエラーメッセージで示された位置のコードを確認し、構文エラーを修正する必要がある。

## 通知種別

CLIエラー出力（標準エラー出力への出力）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 高 |
| リトライ | なし |

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

エラーが発生した時点で即座に標準エラー出力（stderr）に出力される。CLI実行時には`context.logger.error()`を通じて出力され、プロセス終了コードは2に設定される。

## 通知テンプレート

### メール通知の場合

該当なし（CLI出力のみ）

### 本文テンプレート

```
[error] {filename}: SyntaxError: {message} ({line}:{column})
```

例：
```
[error] index.js: SyntaxError: Unexpected token (1:10)
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| filename | 対象ファイル名 | 引数filename | Yes |
| message | エラーメッセージ | error.message | Yes |
| line | エラー発生行 | error.loc.start.line | Yes |
| column | エラー発生列 | error.loc.start.column | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| API呼び出し | format/formatWithCursor実行 | パース時に構文エラー検出 | JavaScript/TypeScript等のパースエラー |
| CLI実行 | prettierコマンド実行 | ファイルのパース失敗 | 各言語パーサーでのエラー |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| なし | SyntaxErrorは常に表示される |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[format呼び出し] --> B[パーサー選択]
    B --> C[パース処理実行]
    C --> D{パース成功?}
    D -->|Yes| E[フォーマット処理継続]
    D -->|No| F[createError呼び出し]
    F --> G[SyntaxError生成]
    G --> H[エラーをスロー]
    H --> I[handleError]
    I --> J[エラーメッセージ出力]
    J --> K[終了コード2設定]
```

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

### 参照テーブル一覧

該当なし（Prettierはデータベースを使用しない）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| JavaScript構文エラー | JS/TS/JSXの構文誤り | エラー位置のコードを修正 |
| CSS構文エラー | CSS/SCSS/LESSの構文誤り | エラー位置のコードを修正 |
| HTML構文エラー | HTML/Vue/Angularの構文誤り | エラー位置のコードを修正 |
| JSON構文エラー | JSON/JSONC/JSON5の構文誤り | エラー位置のコードを修正 |
| Markdown構文エラー | Markdownの構文誤り | エラー位置のコードを修正 |
| YAML構文エラー | YAMLの構文誤り | エラー位置のコードを修正 |
| GraphQL構文エラー | GraphQLの構文誤り | エラー位置のコードを修正 |

### リトライ仕様

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

## 配信設定

### レート制限

該当なし

### 配信時間帯

該当なし

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

ファイル名とエラー位置がエラーメッセージに含まれるが、コードの内容自体は含まれないため、機密情報漏洩のリスクは低い。

## 備考

- SyntaxErrorは標準のJavaScript SyntaxErrorクラスを拡張したオブジェクト
- `error.loc`プロパティに位置情報が含まれる
- 各言語パーサーごとにエラーメッセージの形式が異なる場合がある
- エラーハンドリングでは`error?.loc`の存在で構文エラーかどうかを判定

---

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

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

### 推奨読解順序

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

createError関数によるSyntaxErrorオブジェクトの生成方法を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | parser-create-error.js | `src/common/parser-create-error.js` | createError関数の実装（1-17行目）。SyntaxErrorを拡張してloc情報を付加 |

**読解のコツ**:
- 5行目: 標準のSyntaxErrorを使用
- 7-10行目: メッセージに行番号・列番号を付加 `({line}:{column})`
- 14行目: `Object.assign`でlocなどの追加プロパティを設定

#### Step 2: 各パーサーでのエラー生成を理解する

代表的なパーサーでのcreateError使用例を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | typescript.js | `src/language-js/parse/typescript.js` | TypeScriptパーサーでのエラー生成（41行目） |
| 2-2 | acorn.js | `src/language-js/parse/acorn.js` | Acornパーサーでのエラー生成（47行目） |
| 2-3 | parser-postcss.js | `src/language-css/parser-postcss.js` | PostCSSパーサーでのエラー生成（399行目） |

**主要処理フロー**（TypeScriptの例）:
- **41行目**: `createError(message, { loc: { start: { line, column } }, cause: error })`

#### Step 3: CLI層でのエラーハンドリングを理解する

CLIでSyntaxErrorがどのように処理されるかを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | format.js | `src/cli/format.js` | handleError関数でのパースエラー処理（50-55行目） |

**主要処理フロー**:
- **50行目**: `const isParseError = Boolean(error?.loc)`でパースエラーを判定
- **53-55行目**: パースエラーの場合、`{filename}: {String(error)}`形式で出力

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

```
prettier.format() / CLI実行
    │
    ├─ parse() [各パーサー]
    │      │
    │      ├─ TypeScript: src/language-js/parse/typescript.js
    │      │      └─ createError() [41行目]
    │      │
    │      ├─ Acorn: src/language-js/parse/acorn.js
    │      │      └─ createError() [47行目]
    │      │
    │      ├─ Babel: src/language-js/parse/utilities/create-babel-parse-error.js
    │      │      └─ createError() [33行目]
    │      │
    │      └─ その他パーサー...
    │
    └─ handleError() [src/cli/format.js:26] (CLI使用時)
           ├─ isParseError判定 [50行目]
           ├─ context.logger.error() [55行目]
           └─ process.exitCode = 2 [71行目]
```

### データフロー図

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

sourceCode           各言語パーサー            SyntaxError
                     ├─ parse()                  │
                     ├─ 構文解析実行              │
                     └─ エラー検出時               v
                        createError()        handleError()
                        ├─ message              │
                        ├─ loc.start.line       v
                        └─ loc.start.column  stderr出力
                                             [error] filename: SyntaxError: message (line:column)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| parser-create-error.js | `src/common/parser-create-error.js` | ソース | createError関数（SyntaxError生成） |
| format.js | `src/cli/format.js` | ソース | CLIでのエラーハンドリング |
| typescript.js | `src/language-js/parse/typescript.js` | ソース | TypeScriptパーサー |
| acorn.js | `src/language-js/parse/acorn.js` | ソース | Acornパーサー |
| meriyah.js | `src/language-js/parse/meriyah.js` | ソース | Meriyahパーサー |
| flow.js | `src/language-js/parse/flow.js` | ソース | Flowパーサー |
| espree.js | `src/language-js/parse/espree.js` | ソース | Espreeパーサー |
| hermes.js | `src/language-js/parse/hermes.js` | ソース | Hermesパーサー |
| oxc.js | `src/language-js/parse/oxc.js` | ソース | OXCパーサー |
| angular.js | `src/language-js/parse/angular.js` | ソース | Angularテンプレートパーサー |
| create-babel-parse-error.js | `src/language-js/parse/utilities/create-babel-parse-error.js` | ソース | Babelパースエラー生成 |
| parser-postcss.js | `src/language-css/parser-postcss.js` | ソース | PostCSSパーサー |
| parser-yaml.js | `src/language-yaml/parser-yaml.js` | ソース | YAMLパーサー |
| parser-graphql.js | `src/language-graphql/parser-graphql.js` | ソース | GraphQLパーサー |
| parse.js | `src/language-html/parse/parse.js` | ソース | HTMLパーサー |
| parser-glimmer.js | `src/language-handlebars/parser-glimmer.js` | ソース | Handlebarsパーサー |
| json.js | `src/language-json/parse/json.js` | ソース | JSONパーサー |
