# 通知設計書 5-InvalidDocError

## 概要

本ドキュメントは、Prettierにおいて無効なドキュメント構造（Doc）が検出された場合に発生するエラー通知「InvalidDocError」の設計を記述する。

### 本通知の処理概要

InvalidDocErrorは、Prettierの内部ドキュメント構造（Doc）の処理中に、無効または不正なDoc構造が検出された場合に発生するエラー通知である。

**業務上の目的・背景**：Prettierは内部的に「Doc」と呼ばれる中間表現を使用してコードのフォーマットを行う。各プリンターはASTを受け取り、Docを生成する。その後、DocプリンターがDocを最終的な文字列に変換する。Docは特定の構造を持つ必要があり、無効な構造（例：不正なtype、nullやundefinedの混入等）が検出された場合、このエラーが発生する。これは主にPrettierプラグイン開発者向けの内部エラーである。

**通知の送信タイミング**：`prettier.format()`等のAPI呼び出し時、またはCLI実行時に、Docの走査（traverse）、マッピング（map）、印刷（print）処理中に無効なDoc構造が検出された場合に発生する。主に`src/document/utilities/`および`src/document/printer/printer.js`で検出される。

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

**通知内容の概要**：無効なDocの種類（型）、および期待されるDoc型のリスト。

**期待されるアクション**：プラグイン開発者は生成しているDoc構造を確認し、有効なDoc型を使用するよう修正する。一般ユーザーの場合は、Prettierのバグとしてissue報告を行う。

## 通知種別

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

## 送信仕様

### 基本情報

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

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

エラーが発生した時点で即座に例外としてスローされ、CLIではキャッチされて標準エラー出力（stderr）に出力される。プロセス終了コードは2に設定される。

## 通知テンプレート

### メール通知の場合

該当なし（CLI出力のみ）

### 本文テンプレート

型が不正な場合：
```
[error] {filename}: InvalidDocError: Unexpected doc '{type}',
Expected it to be 'string' or 'object'.
```

オブジェクトだが不正なtype値の場合：
```
[error] {filename}: InvalidDocError: Unexpected doc.type '{type}'.
Expected it to be 'align', 'break-parent', 'cursor', 'fill', 'group', 'if-break', 'indent', 'indent-if-break', 'label', 'line', 'line-suffix', 'line-suffix-boundary', or 'trim'.
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| filename | 対象ファイル名 | 引数filename | Yes |
| type | 無効なDocの型またはdoc.type値 | typeof doc または doc.type | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| API呼び出し | format/formatWithCursor実行 | Doc走査中に無効なDocを検出 | traverseDoc関数で発生 |
| API呼び出し | format/formatWithCursor実行 | Docマッピング中に無効なDocを検出 | mapDoc関数で発生 |
| API呼び出し | format/formatWithCursor実行 | Doc印刷中に無効なDocを検出 | printer.js内で発生 |

### 送信抑止条件

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

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[format呼び出し] --> B[プリンターでDoc生成]
    B --> C[Docプリンターで処理]
    C --> D[traverseDoc/mapDoc/fits等]
    D --> E{Doc構造検証}
    E -->|有効| F[処理継続]
    E -->|無効| G[InvalidDocError発生]
    G --> H[getDocErrorMessage呼び出し]
    H --> I[エラーをスロー]
    I --> J[handleError]
    J --> K[エラーメッセージ出力]
    K --> L[終了コード2設定]
```

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

### 参照テーブル一覧

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

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 不正な型 | docがstring/object以外 | プラグインのDoc生成コードを確認 |
| null値 | docがnull | プラグインのDoc生成コードを確認 |
| 不正なtype | doc.typeが有効な値でない | 正しいDoc builder関数を使用 |

### リトライ仕様

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

## 配信設定

### レート制限

該当なし

### 配信時間帯

該当なし

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

Docの型情報がエラーメッセージに含まれるが、これは内部的な識別子であり、機密情報ではない。無効なDocオブジェクト自体はエラーオブジェクトの`doc`プロパティとして保持される。

## 備考

- 主に内部エラー・プラグイン開発者向けエラーとして位置づけられる
- 有効なDoc型は`src/document/builders/types.js`で定義されている
- `VALID_OBJECT_DOC_TYPES`に定義された型以外はすべて無効
- エラーメッセージは`getDocErrorMessage`関数で生成される
- Intl.ListFormatを使用して有効な型のリストをフォーマット

---

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

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

### 推奨読解順序

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

InvalidDocErrorクラスの定義とエラーメッセージ生成ロジックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | invalid-doc-error.js | `src/document/utilities/invalid-doc-error.js` | InvalidDocErrorクラスの定義（1-40行目） |

**読解のコツ**:
- 4-5行目: `disjunctionListFormat` - 有効なDoc型リストを「or」形式でフォーマット
- 7-28行目: `getDocErrorMessage` - エラーメッセージ生成ロジック
- 8-11行目: nullまたは非オブジェクト/非文字列のチェック
- 19-22行目: オブジェクトだが不正な型のチェック
- 24-28行目: 有効なDoc型リストを含むエラーメッセージ生成
- 31-38行目: InvalidDocErrorクラス定義

#### Step 2: エラー発生箇所を理解する

InvalidDocErrorがスローされる箇所を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | traverse-doc.js | `src/document/utilities/traverse-doc.js` | traverseDoc関数でのエラー発生（53行目、108行目） |
| 2-2 | index.js | `src/document/utilities/index.js` | mapDoc等でのエラー発生（96行目、256行目、341行目） |
| 2-3 | printer.js | `src/document/printer/printer.js` | Docプリンターでのエラー発生（527行目） |

**主要処理フロー**（traverse-doc.jsの例）:
- **51行目**: `getDocType(doc)`でDoc型を取得
- **52-53行目**: 型が取得できない場合`throw new InvalidDocError(doc)`
- **107-108行目**: switch文のdefaultで同様にエラー

#### Step 3: 有効なDoc型を理解する

有効なDoc型の定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | types.js | `src/document/builders/types.js` | VALID_OBJECT_DOC_TYPESの定義 |

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

```
prettier.format() / CLI実行
    │
    ├─ print() [各プリンター]
    │      └─ Doc生成
    │
    ├─ Docプリンター処理
    │      │
    │      ├─ traverseDoc() [src/document/utilities/traverse-doc.js]
    │      │      ├─ getDocType(doc) [51行目]
    │      │      └─ throw InvalidDocError [53行目, 108行目]
    │      │
    │      ├─ mapDoc() [src/document/utilities/index.js]
    │      │      └─ throw InvalidDocError [96行目]
    │      │
    │      └─ printDocument() [src/document/printer/printer.js]
    │             └─ throw InvalidDocError [527行目]
    │
    └─ handleError() [src/cli/format.js:26] (CLI使用時)
           ├─ context.logger.error() [67行目]
           └─ process.exitCode = 2 [71行目]
```

### データフロー図

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

AST                  プリンター               InvalidDocError
  │                    │                         │
  v                    v                         │
              Doc生成（各言語プリンター）           │
                  │                             │
                  v                             v
              Docプリンター             handleError()
              ├─ traverseDoc()               │
              ├─ mapDoc()                    v
              ├─ fits()                  stderr出力
              └─ getDocType()           [error] InvalidDocError: ...
                   │
                   v
              無効なDoc検出
                   │
                   v
            throw InvalidDocError
            ├─ doc
            └─ message (getDocErrorMessage)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| invalid-doc-error.js | `src/document/utilities/invalid-doc-error.js` | ソース | InvalidDocErrorクラス定義 |
| traverse-doc.js | `src/document/utilities/traverse-doc.js` | ソース | Doc走査ユーティリティ |
| index.js | `src/document/utilities/index.js` | ソース | Docユーティリティ関数群 |
| get-doc-type.js | `src/document/utilities/get-doc-type.js` | ソース | Doc型取得関数 |
| printer.js | `src/document/printer/printer.js` | ソース | Docプリンター |
| types.js | `src/document/builders/types.js` | ソース | 有効なDoc型定義 |
| format.js | `src/cli/format.js` | ソース | CLIでのエラーハンドリング |
