# 機能設計書 72-スキーマバリデーション

## 概要

本ドキュメントは、webpackのJSON Schemaに基づく設定値の妥当性検証機能について、その処理内容・入出力仕様・エラーメッセージ生成ルールを詳細に記述した機能設計書である。

### 本機能の処理概要

スキーマバリデーション機能は、ユーザーが指定したwebpack設定オブジェクトをJSON Schemaに基づいて検証し、不正な設定値を検出してわかりやすいエラーメッセージを生成する機能である。

**業務上の目的・背景**：webpackの設定オプションは非常に多岐にわたり、複雑な階層構造を持つ。不正な設定値がビルドプロセスの深部で初めて検出された場合、エラーの原因特定が困難になる。バリデーション機能により、設定ファイル読み込み直後に不正値を検出し、具体的な修正方法を含むエラーメッセージを提示することで、開発者の設定作業を効率化する。

**機能の利用シーン**：webpack.config.jsの設定値をCompilerに渡す際の初期バリデーション。プラグインオプションの検証（各プラグインが個別にcreateSchemaValidationを使用）。CLIからの引数解析後の検証。

**主要な処理内容**：
1. schema-utilsライブラリのvalidate関数を使用したJSON Schemaバリデーション
2. webpack固有のエラーメッセージポストフォーマット（DID_YOU_MEAN、REMOVED、devtool、output/filename等）
3. 非推奨オプションの検出と代替オプションの提案
4. 削除済みオプションの検出とBREAKING CHANGEメッセージの生成

**関連システム・外部連携**：schema-utilsパッケージのvalidate関数に依存。schemas/WebpackOptions.jsonおよび各プラグイン用スキーマファイルを参照。

**権限による制御**：本機能に権限による制御はない。

## 関連画面

本機能に直接関連する画面はない。設定ファイルのバリデーションはビルド開始前に行われる内部処理である。

## 機能種別

バリデーション処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| schema | JSONSchema | Yes | バリデーションに使用するJSONスキーマ | - |
| options | object | Yes | バリデーション対象の設定オブジェクト | - |
| validationConfiguration | object | No | エラーメッセージ生成の設定 | 未指定時はwebpackデフォルト設定を使用 |

### 入力データソース

- webpack設定オブジェクト（webpack.config.jsまたはCLI引数から生成）
- schemas/WebpackOptions.json（メインスキーマ）
- schemas/plugins/*.json（各プラグイン用スキーマ）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (なし) | void | バリデーション成功時は何も返さない |
| ValidationError | Error | バリデーション失敗時にスローされるエラー（schema-utilsのValidationError） |

### 出力先

バリデーションエラーはValidationErrorとしてスローされ、呼び出し元で捕捉される。

## 処理フロー

### 処理シーケンス

```
1. validateSchema関数の呼び出し
   └─ schema, options, validationConfigurationを受け取る
2. schema-utilsのvalidate関数を実行
   ├─ validationConfigurationが指定されている場合はそのまま使用
   └─ 未指定の場合はwebpackデフォルト設定を適用
       └─ name: "Webpack", postFormatter関数を設定
3. postFormatter関数によるエラーメッセージの加工
   ├─ 3a. output/filenameの絶対パスエラー → output.path使用の提案
   ├─ 3b. devtoolパターンエラー → BREAKING CHANGE警告
   ├─ 3c. additionalPropertiesエラー
   │   ├─ DID_YOU_MEANマッピングで正しいオプション名を提案
   │   ├─ REMOVEDマッピングで削除済みオプションを通知
   │   ├─ debugプロパティ → webpack 2.0.0での削除を通知
   │   └─ その他 → LoaderOptionsPlugin使用の提案
   └─ 3d. 上記に該当しない場合はそのまま返却
4. バリデーション失敗時はValidationErrorをスロー
```

### フローチャート

```mermaid
flowchart TD
    A[validateSchema呼び出し] --> B{validationConfiguration指定?}
    B -->|Yes| C[指定された設定で検証]
    B -->|No| D[webpackデフォルト設定で検証]
    C --> E{バリデーション成功?}
    D --> E
    E -->|Yes| F[正常終了]
    E -->|No| G[postFormatterでメッセージ加工]
    G --> H{エラー種別判定}
    H -->|absolutePath + /output/filename| I[output.path使用を提案]
    H -->|pattern + /devtool| J[BREAKING CHANGE警告]
    H -->|additionalProperties| K{DID_YOU_MEAN?}
    K -->|Yes| L[正しいオプション名を提案]
    K -->|No| M{REMOVED?}
    M -->|Yes| N[削除済み通知]
    M -->|No| O[汎用提案メッセージ]
    I --> P[ValidationErrorスロー]
    J --> P
    L --> P
    N --> P
    O --> P
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-72-01 | DID_YOU_MEAN提案 | 誤ったプロパティ名に対して正しいプロパティ名を提案する（22項目） | additionalPropertiesエラー時 |
| BR-72-02 | REMOVED通知 | 削除済みプロパティ（concord、devtoolLineToLine）にBREAKING CHANGEメッセージを表示 | additionalPropertiesエラー時 |
| BR-72-03 | devtoolパターン警告 | devtoolオプションのパターンエラー時にwebpack 5での変更を通知 | pattern + /devtoolエラー時 |
| BR-72-04 | 絶対パス警告 | output.filenameの絶対パスエラー時にoutput.pathの使用を提案 | absolutePath + /output/filenameエラー時 |
| BR-72-05 | debugプロパティ移行 | debugプロパティ使用時にLoaderOptionsPluginへの移行を案内 | ルートレベルのdebugプロパティ検出時 |

### 計算ロジック

特になし。

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

本機能にデータベース操作はない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ValidationError | 設定値がスキーマに適合しない場合 | エラーメッセージに従い設定を修正。DID_YOU_MEAN提案がある場合は提案に従う |

### リトライ仕様

リトライは不要。設定修正後に再実行する。

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

トランザクション管理は不要。

## パフォーマンス要件

バリデーションは起動時に一度だけ実行されるため、パフォーマンス要件は厳しくない。ただし、WebpackOptions.check.jsは事前コンパイル済みスキーマとして提供されており、バリデーション性能の最適化が図られている。

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

特になし。設定オブジェクトの検証のみであり、外部入力を直接処理しない。

## 備考

- DID_YOU_MEANマッピングにはwebpack 5のBREAKING CHANGEに関する項目が多数含まれる（jsonpFunction、hotUpdateFunction等）
- Node.jsポリフィル削除に関するBufferおよびprocessの提案メッセージはProvidePluginの使用を案内する

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | WebpackOptions.json | `schemas/WebpackOptions.json` | webpack設定のメインJSONスキーマ。全設定項目の型・制約を定義 |

**読解のコツ**: JSONスキーマは$refによる参照が多用されている。definitions/セクションに共通型定義がまとめられている。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | validateSchema.js | `lib/validateSchema.js` | バリデーション機能の本体。validate関数の呼び出しとpostFormatter |

**主要処理フロー**:
1. **8行目**: schema-utilsからvalidateをインポート
2. **11-61行目**: DID_YOU_MEANマッピング定義（22項目の誤プロパティ名→正プロパティ名マッピング）
3. **63-68行目**: REMOVEDマッピング定義（削除済みプロパティのBREAKING CHANGEメッセージ）
4. **77-175行目**: validateSchema関数本体
5. **83-173行目**: postFormatter関数（エラーメッセージの加工ロジック）

#### Step 3: スキーマファイル構成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | WebpackOptions.check.js | `schemas/WebpackOptions.check.js` | 事前コンパイル済みバリデーション関数 |
| 3-2 | create-schema-validation.js | `lib/util/create-schema-validation.js` | プラグイン用バリデーション関数の遅延生成ユーティリティ |

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

```
webpack(config) / Compiler初期化
    |
    +-- validateSchema(schema, options)
            |
            +-- schema-utils.validate(schema, options, configuration)
            |       |
            |       +-- postFormatter(formattedError, error)
            |               |
            |               +-- DID_YOU_MEAN チェック
            |               +-- REMOVED チェック
            |               +-- devtool パターンチェック
            |               +-- output/filename 絶対パスチェック
            |
            +-- [ValidationError スロー（失敗時）]

Plugin.constructor(options)
    |
    +-- createSchemaValidation(check, schema, config)
            |
            +-- validate(schema, options, config)
```

### データフロー図

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

webpack.config.js ------> validateSchema() ---------> void (成功)
                              |                             |
schemas/                      v                     ValidationError (失敗)
  WebpackOptions.json --> schema-utils.validate()
                              |
                              v
                          postFormatter()
                              |
                              v
                          DID_YOU_MEAN / REMOVED
                          マッピング参照
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| validateSchema.js | `lib/validateSchema.js` | ソース | スキーマバリデーション関数本体 |
| WebpackOptions.json | `schemas/WebpackOptions.json` | スキーマ | webpack設定のメインJSONスキーマ |
| WebpackOptions.check.js | `schemas/WebpackOptions.check.js` | スキーマ | 事前コンパイル済みバリデーション関数 |
| create-schema-validation.js | `lib/util/create-schema-validation.js` | ソース | 遅延ロード対応のバリデーション関数生成ユーティリティ |
| ManifestPlugin.check.js | `schemas/plugins/ManifestPlugin.check.js` | スキーマ | ManifestPlugin用コンパイル済みスキーマ（例） |
| ManifestPlugin.json | `schemas/plugins/ManifestPlugin.json` | スキーマ | ManifestPlugin用JSONスキーマ（例） |
