# 機能設計書 75-エラー・警告クラス群

## 概要

本ドキュメントは、webpackのビルドプロセスで使用されるエラー・警告クラス群について、その継承構造・エラー情報の構造化・シリアライズ対応を詳細に記述した機能設計書である。

### 本機能の処理概要

エラー・警告クラス群は、WebpackErrorを基底クラスとし、モジュールパースエラー、モジュールビルドエラー、Harmonyリンキングエラーなどのビルドプロセスで発生する各種エラーを構造化して管理する機能である。

**業務上の目的・背景**：webpackのビルドプロセスは多段階にわたり、各段階で異なる種類のエラーが発生しうる。エラーを構造化されたクラス階層で管理することで、エラーの種別識別、関連モジュール・位置情報の付与、キャッシュのためのシリアライズ、統計レポートへの出力を統一的に行うことができる。

**機能の利用シーン**：モジュールのパース時にSyntaxError等が発生した場合（ModuleParseError）。ローダー実行中にエラーが発生した場合（ModuleBuildError）。ESMのimport/exportリンクが解決できない場合（HarmonyLinkingError）。モジュール依存関係の解決に失敗した場合（ModuleNotFoundError）。

**主要な処理内容**：
1. WebpackError基底クラスによるエラー情報の標準化（module、loc、chunk、file、details、hideStack）
2. 各サブクラスによるエラー種別固有の情報付加とメッセージフォーマット
3. makeSerializableによるキャッシュ対応のシリアライズ/デシリアライズ機能
4. エラー発生コンテキスト（ローダー名、ソースコード抜粋、行番号等）の自動付加

**関連システム・外部連携**：lib/serialization/配下のシリアライゼーションフレームワーク。lib/stats/配下の統計レポート生成。

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

## 関連画面

本機能に直接関連する画面はない。エラー情報はCLI出力や統計レポートに表示される。

## 機能種別

エラーハンドリング・データ構造

## 入力仕様

### 入力パラメータ

WebpackError基底クラスのコンストラクタ:

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| message | string | No | エラーメッセージ | - |
| options | object | No | エラーオプション（causeプロパティ等） | - |

### 入力データソース

ビルドプロセスの各段階で発生するエラー情報

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| name | string | エラークラス名（例: "ModuleParseError"） |
| message | string | エラーメッセージ |
| details | string | 詳細情報（スタックトレース等） |
| module | Module | null | 関連するモジュール |
| loc | DependencyLocation | エラー発生位置 |
| hideStack | boolean | スタックトレースを非表示にするか |
| chunk | Chunk | 関連するチャンク |
| file | string | 関連するファイル |

### 出力先

compilation.errors / compilation.warningsに蓄積され、統計レポートやCLI出力を通じてユーザーに表示される。

## 処理フロー

### 処理シーケンス

```
1. エラー発生（パース、ビルド、リンキング等）
   └─ 発生箇所で適切なエラーサブクラスをインスタンス化
2. エラー情報の構造化
   ├─ ModuleParseError: ソースコード解析、行番号抽出、WASM検出
   ├─ ModuleBuildError: ローダー情報付加、スタックトレース加工
   └─ HarmonyLinkingError: hideStack=trueでスタック非表示
3. compilation.errors/warningsへの追加
4. 統計レポート生成時にエラー情報を出力
5. キャッシュ時にserialize/deserializeで永続化
```

### フローチャート

```mermaid
flowchart TD
    A[エラー発生] --> B{エラー種別判定}
    B -->|パースエラー| C[ModuleParseError生成]
    B -->|ビルドエラー| D[ModuleBuildError生成]
    B -->|リンクエラー| E[HarmonyLinkingError生成]
    B -->|その他| F[その他WebpackErrorサブクラス]
    C --> G[メッセージフォーマット]
    D --> G
    E --> G
    F --> G
    G --> H[compilation.errors/warnings追加]
    H --> I[統計レポート出力]
    H --> J[キャッシュ永続化]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-75-01 | WASM検出 | ソースがWebAssemblyモジュールの場合、WASM有効化の案内メッセージを追加 | ModuleParseError時、バイナリヘッダが0x00616d73の場合 |
| BR-75-02 | ローダー提案 | ローダーが設定されていない場合、適切なローダーの使用を案内 | ModuleParseError時、loadersがfalsy |
| BR-75-03 | ソースコード抜粋 | エラー行の前後各2行を含むソースコード抜粋をメッセージに追加 | ModuleParseError時、テキストファイルでloc情報がある場合 |
| BR-75-04 | バイナリファイル検出 | 制御文字を含むソースの場合、ソースコード省略メッセージを表示 | ModuleParseError時、バイナリ判定に該当する場合 |
| BR-75-05 | hideStack制御 | HarmonyLinkingErrorはスタックトレースを非表示にする | HarmonyLinkingError時、常時 |
| BR-75-06 | ローダースタック切り詰め | ModuleBuildErrorでローダー実行部分をスタックトレースから除去 | ModuleBuildError時、cutOffLoaderExecution適用 |
| BR-75-07 | シリアライズ対応 | 全エラークラスはmakeSerializableで登録され、キャッシュ可能 | 常時 |

### 計算ロジック

特になし。

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

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

## エラー処理

エラー処理そのものが本機能の目的である。

### エラーケース一覧

各エラークラスの概要:

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ModuleParseError | パースエラー | モジュールのJavaScript/CSS等のパースに失敗 | 適切なローダーの設定、構文エラーの修正 |
| ModuleBuildError | ビルドエラー | ローダーの実行中にエラー発生 | ローダー設定の確認、ソースコードの修正 |
| HarmonyLinkingError | リンクエラー | ESMのimport/exportが解決不可 | エクスポート名の確認、モジュールパスの修正 |
| ModuleNotFoundError | 解決エラー | モジュールパスが解決不可 | パスの確認、パッケージのインストール |
| ModuleDependencyError | 依存性エラー | 依存モジュールの処理に失敗 | 依存関係の確認 |
| CodeGenerationError | コード生成エラー | コード生成フェーズでエラー発生 | プラグイン設定の確認 |

### リトライ仕様

リトライは行わない。

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

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

## パフォーマンス要件

エラーオブジェクトのインスタンス化は例外的なパスであるため、パフォーマンス要件は厳しくない。

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

エラーメッセージにファイルパスやソースコード抜粋が含まれる場合がある。本番環境のログに出力する際は機密情報の漏洩に注意が必要。

## 備考

- WebpackErrorはNode.jsのErrorクラスを継承し、util.inspect.customを実装している
- 各エラークラスはwebpackのシリアライゼーションフレームワーク（makeSerializable）に登録されている

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | WebpackError.js | `lib/WebpackError.js` | 基底クラスの構造。details、module、loc、hideStack、chunk、fileプロパティ |

**読解のコツ**: WebpackErrorはErrorを継承し、webpack固有のプロパティ（module、loc、chunk等）を追加している。serialize/deserializeメソッドでキャッシュ対応している。

#### Step 2: 主要なエラーサブクラス

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ModuleParseError.js | `lib/ModuleParseError.js` | パースエラー。WASM検出、ローダー提案、ソースコード抜粋ロジック |
| 2-2 | ModuleBuildError.js | `lib/ModuleBuildError.js` | ビルドエラー。ローダースタック切り詰め、hideStack制御 |
| 2-3 | HarmonyLinkingError.js | `lib/HarmonyLinkingError.js` | ESMリンクエラー。hideStack=true |

**主要処理フロー（ModuleParseError）**:
- **16行目**: WASMヘッダ定数（Buffer.from([0x00, 0x61, 0x73, 0x6d])）
- **25-91行目**: コンストラクタ。エラー種別判定、メッセージ構築、行番号からのソースコード抜粋
- **30-34行目**: WASM検出ロジック
- **43-56行目**: ローダー有無によるメッセージ分岐
- **58-87行目**: ソースコード抜粋（バイナリ判定含む）

**主要処理フロー（ModuleBuildError）**:
- **22-48行目**: コンストラクタ。from情報の付加、スタックトレースの加工、hideStack制御

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

```
WebpackError (基底クラス)
    |
    +-- ModuleParseError
    +-- ModuleBuildError
    +-- HarmonyLinkingError
    +-- ModuleNotFoundError
    +-- ModuleDependencyError
    +-- CodeGenerationError
    +-- ChunkRenderError
    +-- ConcurrentCompilationError
    +-- HookWebpackError
    +-- AbstractMethodError
    +-- ModuleError
    +-- ModuleRestoreError
    +-- ModuleStoreError
    +-- ModuleHashingError
    +-- AsyncDependencyToInitialChunkError
    +-- UnhandledSchemeError
    +-- NodeStuffInWebError
```

### データフロー図

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

エラー発生情報              エラークラスインスタンス化
  (err, source,             メッセージフォーマット
   loaders, type) -------> ModuleParseError -----------> compilation.errors
                           ModuleBuildError                     |
                           HarmonyLinkingError                  v
                           ...                            統計レポート
                                                         (stats出力)
                                                              |
                                                              v
                           serialize() <----------------- キャッシュ永続化
                           deserialize() <--------------- キャッシュ復元
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| WebpackError.js | `lib/WebpackError.js` | ソース | エラー基底クラス |
| ModuleParseError.js | `lib/ModuleParseError.js` | ソース | パースエラークラス |
| ModuleBuildError.js | `lib/ModuleBuildError.js` | ソース | ビルドエラークラス |
| HarmonyLinkingError.js | `lib/HarmonyLinkingError.js` | ソース | ESMリンクエラークラス |
| ModuleNotFoundError.js | `lib/ModuleNotFoundError.js` | ソース | モジュール未検出エラークラス |
| ModuleDependencyError.js | `lib/ModuleDependencyError.js` | ソース | 依存性エラークラス |
| CodeGenerationError.js | `lib/CodeGenerationError.js` | ソース | コード生成エラークラス |
| ChunkRenderError.js | `lib/ChunkRenderError.js` | ソース | チャンクレンダーエラークラス |
| ErrorHelpers.js | `lib/ErrorHelpers.js` | ソース | cutOffLoaderExecution等のヘルパー |
| makeSerializable.js | `lib/util/makeSerializable.js` | ソース | シリアライズ登録ユーティリティ |
