# 通知設計書 33-Invalid-option-value

## 概要

本ドキュメントは、Prettier CLIまたはAPIにおいてオプション値のバリデーションエラーが発生した場合に表示されるエラー通知「Invalid option value」の設計仕様を記載する。

### 本通知の処理概要

本通知は、ユーザーが指定したオプション値が期待される型や範囲に適合しない場合にエラーメッセージを出力し、正しいオプション値を指定するよう促す機能を提供する。

**業務上の目的・背景**：Prettierには多数の設定オプションがあり、各オプションには型や許容値の制約がある。例えば`printWidth`は整数値、`trailingComma`は`all`/`es5`/`none`のいずれかでなければならない。このエラー通知により、ユーザーが無効なオプション値を指定した際に、期待される値の形式を即座に把握でき、設定の修正が容易になる。

**通知の送信タイミング**：オプションの正規化フェーズ（`normalizeOptions`関数）において、`vnopts`ライブラリによるバリデーションが実行される。バリデーション失敗時にエラーが生成される。CLIの場合はファイルごとの処理時、APIの場合はformat関数呼び出し時に発生する。

**通知の受信者**：Prettier CLIを実行しているユーザー、またはPrettier APIを利用しているアプリケーション開発者。

**通知内容の概要**：「Invalid {オプション名} value. Expected {期待される形式}, but received {実際の値}.」という形式のエラーメッセージが出力される。オプション名、期待される値、実際に受け取った値が動的に埋め込まれる。

**期待されるアクション**：ユーザーは以下の対応を行うことが期待される：
1. エラーメッセージに記載された期待される形式を確認する
2. 設定ファイルまたはCLIオプションを修正する
3. 再度Prettierを実行する

## 通知種別

CLI標準エラー出力（stderr）へのエラーメッセージ

## 送信仕様

### 基本情報

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

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

CLIを実行したプロセスの標準エラー出力に直接出力される。ロガーの`error`メソッドを経由し、`[error]`プレフィックス付きで赤色表示される。バリデーションエラーが1つのファイルで発生すると、全ファイルに影響するため`process.exit(1)`で即座に終了する。

## 通知テンプレート

### CLI出力の場合

| 項目 | 内容 |
|-----|------|
| 出力先 | stderr |
| プレフィックス | [error] |
| 色 | 赤（red） |

### 本文テンプレート

```
[error] Invalid {optionName} value. Expected {expectedType}, but received {receivedValue}.
```

#### 具体例

整数型オプション（printWidth）の場合：
```
[error] Invalid printWidth value. Expected an integer, but received 0.5.
```

選択型オプション（trailingComma）の場合：
```
[error] Invalid trailingComma value. Expected "all", "es5" or "none", but received "wow".
```

CLIオプション（--config-precedence）の場合：
```
[error] Invalid --config-precedence value. Expected one of the following values, but received "option/configPrecedence".
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| optionName | バリデーション失敗したオプション名 | vnoptsスキーマ | Yes |
| expectedType | 期待される値の形式/型 | vnoptsスキーマ定義 | Yes |
| receivedValue | 実際に指定された値 | ユーザー入力 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| オプションバリデーション | normalizeOptions実行時 | オプション値がスキーマに適合しない | vnopts検証失敗 |
| ファイルフォーマット | format/handleError実行時 | isValidationError判定が真 | `/^Invalid \S+ value\./`にマッチ |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| オプション値がスキーマに適合する場合 | 正常なバリデーション |
| exceptionハンドラで許可された値の場合 | 特別に許可された例外値 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[オプション指定] --> B[normalizeOptions呼び出し]
    B --> C[vnoptsスキーマ検証]
    C --> D{バリデーション結果}
    D -->|成功| E[フォーマット処理続行]
    D -->|失敗| F[エラーオブジェクト生成]
    F --> G[handleError呼び出し]
    G --> H{isValidationError判定}
    H -->|Yes| I[logger.error呼び出し]
    I --> J[process.exit 1]
    H -->|No| K[通常エラー処理]
```

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

### 参照テーブル一覧

該当なし（CLIツールのためデータベースは使用しない）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 整数型バリデーション失敗 | 整数でない値を整数オプションに指定 | エラーメッセージを出力して終了 |
| 選択型バリデーション失敗 | 許可されていない値を選択オプションに指定 | エラーメッセージを出力して終了 |
| 文字列型バリデーション失敗 | 文字列でない値を文字列オプションに指定 | エラーメッセージを出力して終了 |

### リトライ仕様

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

## 配信設定

### レート制限

該当なし（CLI同期処理のため）

### 配信時間帯

該当なし（CLI実行時即座に出力）

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

- ユーザー入力値がエラーメッセージに含まれるが、stderrへの出力のみであり、ログファイルへの永続化やネットワーク送信は行われない
- 悪意のあるオプション値がそのまま出力される可能性があるため、エラーメッセージのパース時には注意が必要

## 備考

- バリデーションエラーが発生すると、1つのファイルだけでなく全ファイルの処理が停止する
- これは、同じ設定が全ファイルに適用されるため、1つのファイルで失敗する設定は全ファイルで失敗するためである
- `vnopts`ライブラリがバリデーションロジックを提供している
- オプション定義は`src/main/normalize-options.js`で`optionInfosToSchemas`関数によりvnoptsスキーマに変換される

---

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

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

### 推奨読解順序

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

オプション定義とバリデーションスキーマの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | normalize-options.js | `src/main/normalize-options.js` | optionInfoToSchema関数でオプション型ごとのスキーマ生成（113-163行目） |
| 1-2 | cli-options.evaluate.js | `src/cli/cli-options.evaluate.js` | 各オプションのtype定義 |

**読解のコツ**: `vnopts`ライブラリの各スキーマ型（IntegerSchema, ChoiceSchema等）がどのオプションtypeにマッピングされるかを理解する。

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

バリデーションエラーが検出される場所を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | format.js | `src/cli/format.js` | handleError関数のisValidationError判定（50-60行目） |

**主要処理フロー**:
1. **51行目**: `isValidationError`の正規表現パターン `/^Invalid \S+ value\./`
2. **56-60行目**: バリデーションエラーまたはConfigError時の処理
3. **60行目**: `process.exit(1)`で即座に終了

#### Step 3: オプション正規化処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | normalize-options.js | `src/main/normalize-options.js` | normalizeOptions関数とvnopts.Normalizer（14-76行目） |
| 3-2 | get-options-for-file.js | `src/cli/options/get-options-for-file.js` | ファイルごとのオプション取得と正規化 |

**主要処理フロー**:
- **54-59行目**: Normalizerインスタンスの生成と設定
- **68行目**: `normalizer.normalize(options)`の呼び出し

#### Step 4: スキーマ生成ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | normalize-options.js | `src/main/normalize-options.js` | optionInfoToSchema関数（113-213行目） |

**主要処理フロー**:
- **121-126行目**: int型 → IntegerSchema
- **130-141行目**: choice型 → ChoiceSchema（選択肢のリダイレクト対応含む）
- **143-144行目**: boolean型 → BooleanSchema

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

```
formatFiles/formatStdin (src/cli/format.js)
    │
    ├─ getOptionsForFile (src/cli/options/get-options-for-file.js)
    │      │
    │      └─ normalizeApiOptions (src/main/normalize-options.js)
    │             │
    │             └─ vnopts.Normalizer.normalize
    │                    └─ スキーマバリデーション失敗時 → Error
    │
    └─ format/処理実行
           │
           └─ catch → handleError (src/cli/format.js:26)
                  │
                  ├─ isValidationError判定 (51行目)
                  └─ process.exit(1) (60行目)
```

### データフロー図

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

設定ファイル
printWidth: 0.5    ───▶  normalizeOptions
                              ↓
                         optionInfoToSchema
                              ↓
                         IntegerSchema.validate
                              ↓
                         バリデーション失敗
                              ↓
                         Error生成
                              ↓
                         handleError ───────▶ stderr: [error] Invalid printWidth value...
                              ↓
                         process.exit(1)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| format.js | `src/cli/format.js` | ソース | handleError関数、isValidationError判定 |
| normalize-options.js | `src/main/normalize-options.js` | ソース | オプション正規化、vnoptsスキーマ生成 |
| get-options-for-file.js | `src/cli/options/get-options-for-file.js` | ソース | ファイルごとのオプション取得と正規化呼び出し |
| cli-options.evaluate.js | `src/cli/cli-options.evaluate.js` | ソース | CLIオプション定義（type/choices等） |
| logger.js | `src/cli/logger.js` | ソース | ログ出力機能 |
| vnopts | 外部ライブラリ | 依存関係 | オプションバリデーションライブラリ |
