# 通知設計書 1-UndefinedParserError

## 概要

本ドキュメントは、Prettierにおいてパーサーが指定されておらず、ファイルパスからも推論できない場合に発生するエラー通知「UndefinedParserError」の設計を記述する。

### 本通知の処理概要

UndefinedParserErrorは、Prettierがソースコードをフォーマットする際に、適切なパーサーを決定できない場合に発生するエラー通知である。

**業務上の目的・背景**：Prettierは多数の言語に対応しており、各言語に対応するパーサーを使用してコードをフォーマットする。ユーザーがパーサーを明示的に指定しなかった場合、Prettierはファイルの拡張子やファイル名からパーサーを推論しようとする。しかし、推論が不可能な場合（例：標準入力からの入力でファイルパスがない場合、未知の拡張子の場合）、適切なエラーメッセージを表示してユーザーに状況を通知する必要がある。

**通知の送信タイミング**：`prettier.format()`や`prettier.formatWithCursor()`が呼び出され、オプションに`parser`が指定されておらず、かつファイルパス（`filepath`オプション）からパーサーを推論できない場合に発生する。具体的には、`src/main/normalize-format-options.js`の`normalizeFormatOptions`関数内で検出される。

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

**通知内容の概要**：パーサーが未定義であること、およびその理由（ファイルパスがない、または推論できないファイルパスである）を示すエラーメッセージ。

**期待されるアクション**：ユーザーは`--parser`オプションを指定するか、`--stdin-filepath`オプションでファイルパスを指定することで、適切なパーサーを明示的に選択する必要がある。

## 通知種別

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

## 送信仕様

### 基本情報

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

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

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

## 通知テンプレート

### メール通知の場合

該当なし（CLI出力のみ）

### 本文テンプレート

```
[error] No parser and no file path given, couldn't infer a parser.
```

または

```
[error] No parser could be inferred for file "{filepath}".
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| filepath | 対象ファイルのパス | options.filepath | No |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| API呼び出し | format/formatWithCursor実行 | parser未指定かつfilepath未指定 | ファイルパスがない場合 |
| API呼び出し | format/formatWithCursor実行 | parser未指定かつ拡張子から推論不可 | 未知の拡張子の場合 |
| CLI実行 | prettierコマンド実行 | --parserと--stdin-filepathが未指定でstdin入力 | 標準入力使用時 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| --ignore-unknown オプション指定時 | エラーを無視してスキップ |
| ignoreUnknown が true の場合 | ファイル展開時に不明なファイルを無視 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[format/formatWithCursor呼び出し] --> B{parserオプション指定?}
    B -->|Yes| C[指定パーサーを使用]
    B -->|No| D{filepathオプション指定?}
    D -->|No| E[UndefinedParserError発生]
    D -->|Yes| F{ファイルパスからパーサー推論}
    F -->|推論成功| C
    F -->|推論失敗| G[UndefinedParserError発生]
    E --> H[エラーメッセージ出力]
    G --> H
    H --> I[プロセス終了コード2設定]
```

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

### 参照テーブル一覧

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

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| UndefinedParserError | パーサー未指定かつ推論不可 | --parser または --stdin-filepath を指定 |

### リトライ仕様

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

## 配信設定

### レート制限

該当なし

### 配信時間帯

該当なし

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

ファイルパスがエラーメッセージに含まれるため、センシティブなパス情報が露出する可能性がある。ただし、これはローカル実行環境での出力であり、通常は問題とならない。

## 備考

- `--ignore-unknown`オプションを使用すると、このエラーを抑止してファイルをスキップできる
- CLIでは終了コード2が設定される
- API使用時は例外としてスローされる

---

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

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

### 推奨読解順序

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

UndefinedParserErrorクラスの定義を理解することで、エラーの基本構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | errors.js | `src/common/errors.js` | UndefinedParserErrorクラスの定義（5-7行目）。Errorクラスを継承したシンプルなエラークラス |

**読解のコツ**: ES6クラス構文を使用。`name`プロパティでエラー名を定義している。

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

パーサー推論ロジックの起点となるファイルを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | normalize-format-options.js | `src/main/normalize-format-options.js` | パーサー決定ロジックとエラー発生箇所（22-40行目） |

**主要処理フロー**:
1. **25行目**: `rawOptions.parser`が未指定かチェック
2. **26行目**: `rawOptions.filepath`も未指定の場合、27-29行目でUndefinedParserErrorをスロー
3. **31-33行目**: ファイルパスからパーサーを推論（`inferParser`呼び出し）
4. **34-37行目**: 推論失敗時にUndefinedParserErrorをスロー

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

CLIでエラーがどのように処理・表示されるかを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | format.js | `src/cli/format.js` | handleError関数でのUndefinedParserErrorの特別処理（26-48行目） |

**主要処理フロー**:
- **29-30行目**: エラーがUndefinedParserErrorかどうか判定
- **32-36行目**: `ignoreUnknown`オプションが有効な場合、エラーを無視してtrueを返す
- **44-48行目**: エラーメッセージを出力し、終了コード2を設定

#### Step 4: ロガーの実装を理解する

エラーメッセージの出力方法を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | logger.js | `src/cli/logger.js` | createLogger関数とerrorメソッドの実装（21-80行目） |

**主要処理フロー**:
- **24行目**: `error`メソッドは赤色（`red`）でプレフィックス`[error]`を付けて出力
- **35行目**: errorはstderrに出力される

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

```
prettier.format() / CLI実行
    │
    ├─ normalizeFormatOptions() [src/main/normalize-format-options.js:22]
    │      ├─ パーサーチェック [25行目]
    │      ├─ inferParser() [31行目]
    │      └─ throw UndefinedParserError [27行目 or 35行目]
    │
    └─ handleError() [src/cli/format.js:26] (CLI使用時)
           ├─ ignoreUnknownチェック [32行目]
           ├─ context.logger.error() [45行目]
           └─ process.exitCode = 2 [46行目]
```

### データフロー図

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

options              normalizeFormatOptions    UndefinedParserError
├── parser: undefined  ├─ parserチェック          │
├── filepath: ?        ├─ inferParser()          v
                       └─ エラー判定         handleError()
                                                  │
                                                  v
                                             stderr出力
                                             [error] メッセージ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| errors.js | `src/common/errors.js` | ソース | UndefinedParserErrorクラス定義 |
| normalize-format-options.js | `src/main/normalize-format-options.js` | ソース | パーサー推論とエラー発生 |
| format.js | `src/cli/format.js` | ソース | CLIでのエラーハンドリング |
| logger.js | `src/cli/logger.js` | ソース | エラーメッセージ出力 |
| infer-parser.js | `src/utilities/infer-parser.js` | ソース | ファイルパスからのパーサー推論 |
