# 通知設計書 13-ModuleRestoreError

## 概要

本ドキュメントは、Webpackにおけるキャッシュからのモジュール復元エラー通知（ModuleRestoreError）の設計を定義する。ModuleRestoreErrorは、永続キャッシュからモジュールを復元（デシリアライズ）する際にエラーが発生した場合に発行されるエラー通知である。

### 本通知の処理概要

ModuleRestoreErrorは、Webpackのキャッシュシステムにおいてキャッシュされたモジュールデータの復元に失敗した場合に開発者に通知する仕組みである。永続キャッシュ機能（cache.type: 'filesystem'）を使用している場合に特に関連する。

**業務上の目的・背景**：Webpack 5で導入された永続キャッシュ機能は、ビルド時間を大幅に短縮する重要な機能である。しかし、キャッシュデータが破損したり、互換性のないバージョン間でキャッシュを共有しようとした場合、モジュールの復元に失敗する可能性がある。ModuleRestoreErrorは、このようなキャッシュ復元失敗をビルドエラーとして開発者に通知し、キャッシュのクリアや設定見直しを促す目的で設計されている。

**通知の送信タイミング**：Compilation.jsの_modulesCache.get呼び出し時にコールバックがエラーを返した場合。具体的にはCompilation.js 1492-1493行目付近でキャッシュ取得のコールバックエラーが発生した時点で生成される。

**通知の受信者**：Webpackのビルドを実行した開発者。コンソール出力またはWebpack Stats APIを通じてエラー情報が伝達される。

**通知内容の概要**：「Module restore failed:」に続いて元のエラーのスタックトレースまたはメッセージが含まれる。エラーオブジェクトの型に応じた適切なメッセージ変換が行われる。

**期待されるアクション**：開発者は、キャッシュディレクトリのクリア、キャッシュ設定の確認、またはcache.versionの変更を行うことが期待される。

## 通知種別

コンソールエラー出力 / Webpack Stats APIエラーレポート / ビルドエラー（callbackを通じた伝搬）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 非同期（キャッシュ取得コールバック内で生成） |
| 優先度 | 高（ビルドプロセスに影響するエラー） |
| リトライ | 無（コールバック経由で即座にエラー返却） |

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

Compilation.jsの_modulesCache.get呼び出しのコールバックでerrが返された場合、new ModuleRestoreError(module, err)でインスタンスが生成され、callback経由で呼び出し元に返却される。

## 通知テンプレート

### メール通知の場合

本通知はメール送信ではなく、Webpackビルドコンソール出力として表示される。

| 項目 | 内容 |
|-----|------|
| 送信元アドレス | N/A（コンソール出力） |
| 送信元名称 | webpack |
| 件名 | N/A |
| 形式 | テキスト |

### 本文テンプレート

```
Module restore failed: {元のエラースタックトレースまたはメッセージ}
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| N/A | - | - | 添付ファイルなし |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| err | 元のエラー（Error or string） | _modulesCache.getコールバック | Yes |
| err.stack | エラーのスタックトレース | Errorオブジェクト | No |
| err.message | エラーメッセージ | Errorオブジェクト | No |
| module | 復元対象モジュール | Compilation処理対象 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| キャッシュ処理 | _modulesCache.get()コールバック | コールバックのerrパラメータがtruthyの場合 | Compilation.js 1492-1493行目付近 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| キャッシュ復元が正常に完了した場合 | エラーは発行されない |
| キャッシュが存在しない場合 | エラーではなくnullが返される |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[Compilation - モジュール復元処理開始] --> B[_modulesCache.get呼び出し]
    B --> C{キャッシュ取得結果}
    C -->|エラーあり| D[ModuleRestoreError生成]
    C -->|正常| E[キャッシュデータでモジュール復元]
    C -->|キャッシュなし| F[新規ビルド処理へ]
    D --> G[callback経由でエラー返却]
    G --> H[終了]
    E --> H
    F --> H
```

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

### 参照テーブル一覧

本通知はデータベースを使用しない。Webpackのキャッシュシステム（メモリまたはファイルシステム）を参照する。

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| _modulesCache | モジュールキャッシュの取得 | CacheFacadeインスタンス |

### テーブル別参照項目詳細

#### ModuleRestoreErrorインスタンス

| 参照項目（プロパティ名） | 用途 | 取得条件 |
|-------------------|------|---------|
| name | エラー名表示 | 固定値 "ModuleRestoreError" |
| message | エラーメッセージ表示 | コンストラクタで生成 |
| details | 詳細情報 | undefined（コード上は未使用） |
| module | エラー発生モジュール | コンストラクタ引数 |
| error | 元のエラーオブジェクト | コンストラクタ引数 |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| N/A | - | callback経由で返却（配列への直接追加はない） |

#### 送信ログテーブル

| 操作 | 項目（プロパティ名） | 更新値 | 備考 |
|-----|-----------------|-------|------|
| CALLBACK | err | ModuleRestoreErrorインスタンス | callback(new ModuleRestoreError(module, err)) |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| キャッシュ復元失敗 | デシリアライズエラー、キャッシュ破損 | キャッシュディレクトリのクリア |
| キャッシュバージョン不一致 | Webpack/プラグインバージョン変更後 | cache.versionの更新 |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 制限なし |
| 1日あたり上限 | 制限なし |

### 配信時間帯

制限なし。Webpackビルド実行時に即座に通知される。

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

- スタックトレースにファイルパスが含まれる可能性がある
- キャッシュファイルのパス情報が表示される可能性がある

## 備考

- コンストラクタのエラーメッセージ生成では、errの型（object/string/その他）に応じた分岐処理が行われる（21-32行目）
- detailsプロパティはconstで宣言されundefinedが設定されるが、実質的に使用されていない
- makeSerializableによる登録がないため、このエラー自体はシリアライズ対象外

---

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

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

### 推奨読解順序

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

ModuleRestoreErrorクラスのメッセージ生成ロジックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | WebpackError.js | `lib/WebpackError.js` | 基底クラスのプロパティ定義（17-38行目） |
| 1-2 | ModuleRestoreError.js | `lib/ModuleRestoreError.js` | メッセージ生成の条件分岐（21-32行目）。errがobjectの場合はstack > message > toString()の優先順、それ以外はString(err) |

**読解のコツ**: コンストラクタ内のif-elseチェーンは、errの型と内容に応じて最も情報量の多いメッセージを選択するロジック。stack > message > オブジェクト全体 > 文字列変換の優先順に注目。

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

ModuleRestoreErrorが生成されるCompilation.jsのキャッシュ復元処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Compilation.js | `lib/Compilation.js` | _modulesCache.getコールバック内のエラー処理（1488-1498行目付近） |

**主要処理フロー**:
1. **1488-1489行目**: プロファイル記録開始（restoring開始マーク）
2. **1492行目**: _modulesCache.get(identifier, null, callback)でキャッシュ取得
3. **1493行目**: errがある場合、callback(new ModuleRestoreError(module, err))でエラー返却

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

```
Compilation.addModule() / _handleModuleBuildAndDependencies()
    |
    +-- _modulesCache.get(identifier, null, callback)
            |
            +-- [コールバック]
                    |
                    +-- [エラー時] new ModuleRestoreError(module, err)
                    |       |
                    |       +-- WebpackError.constructor(message)
                    |
                    +-- callback(error) でエラー伝搬
```

### データフロー図

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

Module                 --> ModuleRestoreError             --> エラーメッセージ文字列
err (string|Error)      |  コンストラクタ                  --> callback経由で返却
                        |  - "Module restore failed: "
                        |  + err.stack || err.message
                        |    || err || String(err)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| WebpackError.js | `lib/WebpackError.js` | ソース | 基底エラークラス |
| ModuleRestoreError.js | `lib/ModuleRestoreError.js` | ソース | 復元エラークラス定義 |
| Compilation.js | `lib/Compilation.js` | ソース | エラー発行元（_modulesCache.get） |
