# 通知設計書 3-ModuleDependencyWarning

## 概要

本ドキュメントは、Webpackにおけるモジュール依存関係の解析時に発生する警告を表す `ModuleDependencyWarning` クラスの設計仕様を記述する。依存関係オブジェクトの `getWarnings()` メソッドから返される警告を、モジュールおよび位置情報と関連付けてラップする。

### 本通知の処理概要

ModuleDependencyWarning は、依存関係解析フェーズで検出された警告をモジュール情報・ソースコード位置情報と共に保持するクラスである。Compilationの `reportDependencyErrorsAndWarnings` メソッド内で、各依存関係の `getWarnings()` の結果をラップする形で生成される。

**業務上の目的・背景**：Webpackのモジュール依存関係解析では、import/require文の解析やマジックコメントの処理など、さまざまな警告が発生しうる。これらの警告を、どのモジュールのどの位置で発生したかという情報と共に開発者に通知することで、問題箇所の特定を容易にする。CSSパーサーやImportMetaPluginなど、複数のパーサー/プラグインがこの警告クラスを使用する。

**通知の送信タイミング**：(1) Compilation.reportDependencyErrorsAndWarnings実行時（Compilation.js 行3561）、(2) CSSパーサーでの警告検出時（CssParser.js 行628）、(3) ImportMetaPluginでの警告検出時（ImportMetaPlugin.js 行190）。

**通知の受信者**：Webpackビルドを実行した開発者。Stats出力を通じて表示される。

**通知内容の概要**：元の警告エラーメッセージ、発生モジュール情報（module）、ソースコード上の位置情報（loc）が含まれる。元エラーの `hideStack` フラグに応じて、スタックトレースの表示方法が変わる。

**期待されるアクション**：開発者は、位置情報（loc）を参照して該当ソースコードを確認し、依存関係の記述方法の修正やマジックコメントの見直しを行う。

## 通知種別

ビルドプロセス内警告通知（コンソール出力 / Stats JSON / Stats HTML）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（Compilation.warnings配列への直接push） |
| 優先度 | 中（警告） |
| リトライ | なし |

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

Compilationの `reportDependencyErrorsAndWarnings` メソッド内で、各依存関係ブロックを再帰的に走査し、依存関係の `getWarnings()` が返す警告をModuleDependencyWarningでラップして `Compilation.warnings` 配列に直接pushする。また、CSSパーサーやImportMetaPlugin内では `module.addWarning()` 経由で追加される場合もある。

## 通知テンプレート

### メール通知の場合

該当なし（ビルド出力として表示される）。

### 本文テンプレート

```
{err.message}
```

hideStack=false の場合のdetails:
```
{err.stackの2行目以降}
```

hideStack=true の場合のstack:
```
{err.stackの2行目以降}

{元のWebpackError.stack}
```

### 添付ファイル

該当なし。

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| module | 依存関係を持つモジュール | コンストラクタ引数 | Yes |
| err | 元のエラーオブジェクト（ErrorWithHideStack型） | 依存関係のgetWarnings()戻り値 | Yes |
| loc | 依存関係のソースコード位置情報 | 依存関係オブジェクトのlocプロパティ | Yes |
| name | エラー名称（固定値 "ModuleDependencyWarning"） | クラス内で設定 | Yes |
| details | スタックトレース（hideStack=falseの場合） | err.stackの加工結果 | No |
| error | 元のエラーオブジェクト参照 | コンストラクタ引数のerr | No |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 依存関係報告 | Compilation.reportDependencyErrorsAndWarnings | dependency.getWarnings()が値を返す場合 | Compilation.js 行3558-3564 |
| CSSパーサー | CSS解析時の警告検出 | パーサーが警告を生成した場合 | CssParser.js 行628 |
| ImportMetaPlugin | import.meta の不正使用検出 | import.metaが単独式として使用された場合 | ImportMetaPlugin.js 行190 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| stats.warnings=false | webpack設定でwarnings表示を無効にしている場合 |
| getWarnings()がnull/undefinedを返す | 依存関係に警告がない場合は生成されない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[Compilation.reportDependencyErrorsAndWarnings] --> B[依存関係ブロックを走査]
    B --> C[dependency.getWarnings 呼び出し]
    C --> D{警告あり?}
    D -->|Yes| E[ModuleDependencyWarning生成]
    D -->|No| F[スキップ]
    E --> G{err.hideStack?}
    G -->|false| H[detailsにスタックトレース設定]
    G -->|true| I[stackプロパティに結合]
    H --> J[Compilation.warnings.push]
    I --> J
    J --> K[Stats出力]
    F --> L[次の依存関係へ]
```

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

### 参照テーブル一覧

該当なし（データベースは使用しない）。

### 更新テーブル一覧

該当なし（データベースは使用しない）。

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| errがnullの場合 | getWarnings()が不正な値を返す | 空文字メッセージでインスタンス生成（行22: `err ? err.message : ""`） |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

## 配信設定

### レート制限

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

### 配信時間帯

制限なし（ビルド実行時に即座に出力される）。

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

スタックトレースにファイルパス情報が含まれるため、本番環境でのログ公開時には注意が必要。

## 備考

- `makeSerializable` によりキャッシュのシリアライズ/デシリアライズに対応しているが、`error` プロパティはシリアライズされない（行32のコメント参照）。そのため、デシリアライズ後は `error` が `undefined` になる可能性がある。
- `hideStack` フラグの挙動: `true` の場合はスタックトレースが `this.stack` に結合される（行35-40）。`false` の場合はスタックトレースが `details` に設定される（行26-29）。

---

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

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

### 推奨読解順序

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

ModuleDependencyWarningの構造と、ErrorWithHideStack型の関係を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ModuleDependencyWarning.js | `lib/ModuleDependencyWarning.js` | コンストラクタ引数（module, err, loc）、hideStackによるスタック処理の分岐 |
| 1-2 | WebpackError.js | `lib/WebpackError.js` | 基底クラスのプロパティ定義 |

**読解のコツ**: コンストラクタ（行21-41）では `err.hideStack` の値によって `details` と `this.stack` の設定が分岐する点が最重要。hideStack=true の場合、元エラーのスタックトレースが現在のスタックに結合される独特な挙動を持つ。

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

Compilation.reportDependencyErrorsAndWarningsがどのようにModuleDependencyWarningを生成するかを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Compilation.js | `lib/Compilation.js` | reportDependencyErrorsAndWarningsメソッド（行3552-3581）の再帰構造 |

**主要処理フロー**:
1. **行3552**: `reportDependencyErrorsAndWarnings(module, blocks)` メソッド開始
2. **行3554**: blocksを走査するforループ
3. **行3558**: `d.getWarnings(this.moduleGraph)` で各依存関係の警告を取得
4. **行3561**: `new ModuleDependencyWarning(module, w, d.loc)` でインスタンス生成
5. **行3562**: `this.warnings.push(warning)` でCompilationの警告配列に追加
6. **行3576**: 再帰呼び出しでネストされたブロックも処理

#### Step 3: 他の生成元を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | CssParser.js | `lib/css/CssParser.js` | CSS解析時の直接的なModuleDependencyWarning生成（行628） |
| 3-2 | ImportMetaPlugin.js | `lib/dependencies/ImportMetaPlugin.js` | import.meta単独使用時の警告生成（行190-197） |

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

```
Compilation.reportDependencyErrorsAndWarnings()  [Compilation.js 行3552]
    │
    ├─ dependency.getWarnings(moduleGraph)         [行3558]
    │      └─ (各依存関係クラスのgetWarnings実装)
    │
    └─ new ModuleDependencyWarning(module, w, d.loc)  [行3561]
           ├─ super(err.message)                       [行22]
           └─ hideStack分岐処理                        [行26-40]

CssParser.parse()                                [CssParser.js]
    └─ new ModuleDependencyWarning(module, error, loc)  [行628]

ImportMetaPlugin                                 [ImportMetaPlugin.js]
    └─ module.addWarning(new ModuleDependencyWarning(...))  [行190]
```

### データフロー図

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

dependency              ───> getWarnings()               ───> WebpackError[]
    │                                                          │
    │                                                          v
module, err, loc        ───> ModuleDependencyWarning     ───> Compilation.warnings[]
                              コンストラクタ                     │
                              hideStack分岐                     v
                                                          Stats出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ModuleDependencyWarning.js | `lib/ModuleDependencyWarning.js` | ソース | 依存関係警告クラス定義 |
| WebpackError.js | `lib/WebpackError.js` | ソース | 基底エラー/警告クラス |
| Compilation.js | `lib/Compilation.js` | ソース | reportDependencyErrorsAndWarningsメソッド |
| CssParser.js | `lib/css/CssParser.js` | ソース | CSS解析時の警告生成元 |
| ImportMetaPlugin.js | `lib/dependencies/ImportMetaPlugin.js` | ソース | import.meta関連の警告生成元 |
| makeSerializable.js | `lib/util/makeSerializable.js` | ソース | シリアライズ登録ユーティリティ |
