# 機能設計書 79-@babel/helper-validator-option

## 概要

本ドキュメントは、@babel/helper-validator-optionの機能設計について記載する。このパッケージは、Babelプラグインやプリセットのオプション検証を行うためのヘルパー関数を提供するモジュールである。

### 本機能の処理概要

**業務上の目的・背景**：Babelプラグインやプリセットは様々なオプションを受け取るが、ユーザーが誤ったオプション名や型を指定することがある。本パッケージは、オプションの検証機能を提供し、タイプミスの場合には類似するオプション名を提案するなど、ユーザーフレンドリーなエラーメッセージを生成する。これにより、設定ミスの早期発見と迅速な修正が可能になる。

**機能の利用シーン**：Babelプラグインやプリセットの初期化時にオプションを検証する際に使用される。特に@babel/preset-envや@babel/helper-compilation-targetsなどで、ユーザー指定のオプションが正しいかどうかをチェックするために利用される。

**主要な処理内容**：
1. OptionValidator: オプション検証クラス
   - validateTopLevelOptions: トップレベルオプション名の検証
   - validateBooleanOption: boolean型オプションの検証
   - validateStringOption: 文字列型オプションの検証
   - invariant: 条件アサーション
2. findSuggestion: レーベンシュタイン距離に基づく類似オプション提案

**関連システム・外部連携**：Babelプラグイン/プリセット全般で利用される。

**権限による制御**：権限による実行制御は行わない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | プラグイン/プリセット設定時に使用 |

## 機能種別

オプション検証 / エラー生成 / ユーティリティ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| descriptor | string | Yes（コンストラクタ） | パッケージ名（エラーメッセージ用） | - |
| options | object | Yes（validateTopLevelOptions） | 検証対象のオプションオブジェクト | - |
| TopLevelOptionShape | object | Yes（validateTopLevelOptions） | 有効なオプション名のテンプレート | - |
| name | string | Yes（validateXxxOption） | オプション名 | - |
| value | any | No | オプション値 | - |
| defaultValue | any | No | デフォルト値 | - |

### 入力データソース

Babelプラグイン/プリセットの設定オブジェクトから呼び出し

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| validateBooleanOption | boolean | 検証済みの値またはデフォルト値 |
| validateStringOption | string | 検証済みの値またはデフォルト値 |
| findSuggestion | string | 最も類似した候補文字列 |

### 出力先

呼び出し元に対して検証済みの値を返却

## 処理フロー

### 処理シーケンス

```
1. OptionValidator初期化
   └─ descriptorを設定（エラーメッセージプレフィックス）

2. validateTopLevelOptions呼び出し
   ├─ TopLevelOptionShapeからキー一覧を取得
   ├─ optionsの各キーをチェック
   │   └─ 無効なキーがあれば
   │       ├─ findSuggestionで類似候補を検索
   │       └─ エラーをスロー
   └─ 正常終了

3. validateBooleanOption呼び出し
   ├─ valueがundefined → defaultValueを返却
   └─ typeof value !== "boolean" → エラー

4. validateStringOption呼び出し
   ├─ valueがundefined → defaultValueを返却
   └─ typeof value !== "string" → エラー
```

### フローチャート

```mermaid
flowchart TD
    A[validateTopLevelOptions] --> B[有効キー一覧取得]
    B --> C{各オプションをチェック}
    C -->|有効| D[次のオプションへ]
    D --> C
    C -->|無効| E[findSuggestion]
    E --> F[エラーをスロー]
    C -->|完了| G[正常終了]

    H[validateBooleanOption] --> I{value == undefined?}
    I -->|Yes| J[return defaultValue]
    I -->|No| K{typeof value == boolean?}
    K -->|Yes| L[return value]
    K -->|No| M[invariantでエラー]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-79-01 | トップレベルオプション検証 | TopLevelOptionShapeに存在しないオプションはエラー | オプション指定時 |
| BR-79-02 | 類似候補提案 | 無効なオプションに対して最も類似する有効オプションを提案 | 無効オプション検出時 |
| BR-79-03 | boolean型検証 | valueがundefined以外でboolean型でない場合はエラー | validateBooleanOption時 |
| BR-79-04 | string型検証 | valueがundefined以外でstring型でない場合はエラー | validateStringOption時 |

### 計算ロジック

**レーベンシュタイン距離**：
```
2つの文字列間の編集距離（挿入、削除、置換の最小回数）
動的計画法で計算
距離が最小の候補を提案
```

## データベース操作仕様

### 操作別データベース影響一覧

データベース操作なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | オプションエラー | 無効なトップレベルオプション名 | 提案されたオプション名を使用 |
| - | 型エラー | booleanオプションがboolean型でない | boolean値を指定 |
| - | 型エラー | stringオプションがstring型でない | string値を指定 |
| - | アサーションエラー | invariantの条件が満たされない | 条件に従って修正 |

### リトライ仕様

リトライ対象外（設定エラーのため）

## トランザクション仕様

トランザクション処理なし

## パフォーマンス要件

- レーベンシュタイン距離計算はO(mn)だが、オプション名は短いため問題なし
- Babel設定読み込み時のみ実行されるため、ランタイムへの影響なし

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

特になし

## 備考

- @babel/preset-envで広く使用される
- @babel/helper-compilation-targetsとの連携あり
- エラーメッセージは「パッケージ名: メッセージ」の形式

---

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

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

### 推奨読解順序

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

まず、エントリーポイントとエクスポートを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/babel-helper-validator-option/src/index.ts` | エクスポート内容（1-2行目） |

**読解のコツ**: OptionValidatorクラスとfindSuggestion関数の2つが主要なエクスポートであることを理解する。

#### Step 2: OptionValidatorクラスを理解する

オプション検証クラスの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | validator.ts | `packages/babel-helper-validator-option/src/validator.ts` | OptionValidatorクラス（3-80行目） |

**主要処理フロー**:
1. **3-7行目**: コンストラクタでdescriptorを設定
2. **18-28行目**: validateTopLevelOptions - オプション名の検証、findSuggestionで提案
3. **32-46行目**: validateBooleanOption - boolean型の検証
4. **48-62行目**: validateStringOption - string型の検証
5. **71-75行目**: invariant - アサーション関数
6. **77-79行目**: formatMessage - エラーメッセージ整形

#### Step 3: findSuggestion関数を理解する

レーベンシュタイン距離を使った類似候補検索を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | find-suggestion.ts | `packages/babel-helper-validator-option/src/find-suggestion.ts` | levenshtein関数とfindSuggestion関数（1-48行目） |

**主要処理フロー**:
- **10-34行目**: levenshtein - 動的計画法でレーベンシュタイン距離を計算
- **45-48行目**: findSuggestion - 全候補の距離を計算し、最小距離の候補を返却

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

```
@babel/helper-validator-option/src/index.ts
    │
    ├─ validator.ts
    │      └─ OptionValidator
    │             ├─ validateTopLevelOptions()
    │             │      └─ findSuggestion()
    │             ├─ validateBooleanOption()
    │             │      └─ invariant()
    │             ├─ validateStringOption()
    │             │      └─ invariant()
    │             ├─ invariant()
    │             └─ formatMessage()
    │
    └─ find-suggestion.ts
           ├─ levenshtein()
           └─ findSuggestion()
```

### データフロー図

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

options ───▶ validateTopLevelOptions()
TopLevelOptionShape              │
                                 ├─ Object.keys比較
                                 │
                                 ├─ 無効オプション発見時
                                 │      │
                                 │      ▼
                                 │  findSuggestion()
                                 │      │
                                 │      ├─ levenshtein()計算
                                 │      │
                                 │      └─ 最小距離の候補返却
                                 │
                                 └─ エラーメッセージ生成


value ───▶ validateBooleanOption() ───▶ boolean | defaultValue
              │
              ├─ undefined → defaultValue返却
              │
              └─ typeof検証 → value返却 or エラー
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-helper-validator-option/src/index.ts` | ソース | エントリーポイント（re-export） |
| validator.ts | `packages/babel-helper-validator-option/src/validator.ts` | ソース | OptionValidatorクラス |
| find-suggestion.ts | `packages/babel-helper-validator-option/src/find-suggestion.ts` | ソース | レーベンシュタイン距離と提案関数 |
