# 通知設計書 2-ModuleWarning

## 概要

本ドキュメントは、Webpackにおけるモジュール処理時の一般的な警告メッセージを表す `ModuleWarning` クラスの設計仕様を記述する。ローダーやプラグインが `emitWarning` を通じて発行する警告を、統一されたフォーマットでラップする役割を持つ。

### 本通知の処理概要

ModuleWarning は、ローダーの実行やソースマップの処理時に発生する警告を表現するクラスである。ローダーが `loaderContext.emitWarning()` を呼び出した際に生成され、NormalModuleの警告リストに追加される。

**業務上の目的・背景**：Webpackのビルドプロセスでは、ローダー（babel-loader, css-loader等）やプラグインがモジュール処理中に非致命的な問題を検出することがある。これらの警告を開発者に伝達し、潜在的な問題の早期発見を支援することが目的である。ModuleWarningは、発生元のローダー名を含むフォーマットされたメッセージを提供し、警告の出所を明確にする。

**通知の送信タイミング**：(1) ローダーの `emitWarning` コールバックが呼ばれた時（NormalModule.js 行754-762）、(2) ソースマップの解析に失敗した時（NormalModule.js 行1112）。いずれもモジュールのビルドフェーズで発生する。

**通知の受信者**：Webpackビルドを実行した開発者。Stats出力を通じてコンソールやJSON形式で表示される。

**通知内容の概要**：「Module Warning (from {ローダー名}): {元の警告メッセージ}」の形式で表示される。元の警告がErrorオブジェクトの場合は、そのスタックトレースをcleanUp処理した上でdetailsプロパティに保持する。

**期待されるアクション**：開発者はローダーやプラグインの設定を見直し、警告の原因となっている設定ミスやコードの問題を修正する。

## 通知種別

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

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（Module.addWarning経由でCompilation.warningsに追加） |
| 優先度 | 中（警告） |
| リトライ | なし |

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

NormalModuleの `addWarning` メソッド経由でモジュールの警告リストに追加される。その後、Compilationがモジュールの警告を収集し、Stats出力時にビルド実行者に表示する。

## 通知テンプレート

### メール通知の場合

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

### 本文テンプレート

fromパラメータがある場合:
```
Module Warning (from {from}):
{warning.message}
```

fromパラメータがない場合:
```
Module Warning: {warning.message}
```

### 添付ファイル

該当なし。

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| warning | 元の警告Errorオブジェクト | ローダー/プラグインからのemitWarning引数 | Yes |
| from | 警告発生元のローダー名 | getCurrentLoaderName()の戻り値 | No |
| name | エラー名称（固定値 "ModuleWarning"） | クラス内で設定 | Yes |
| details | スタックトレースのクリーンアップ結果 | ErrorHelpers.cleanUp() | No |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| ローダー実行 | loaderContext.emitWarning()呼び出し | 常に（emitWarning呼び出し時） | NormalModule.js 行754-762 |
| ソースマップ処理 | SourceMap解析失敗 | ソースマップの解析でエラーが発生した場合 | NormalModule.js 行1112 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| stats.warnings=false | webpack設定でwarnings表示を無効にしている場合、Stats出力に含まれない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[ローダー内でemitWarning呼び出し] --> B{warningがError型か?}
    B -->|No| C[NonErrorEmittedErrorでラップ]
    B -->|Yes| D[ModuleWarningインスタンス生成]
    C --> D
    D --> E[from パラメータ付きメッセージ構築]
    E --> F[warning.stackをcleanUpしてdetailsに設定]
    F --> G[Module.addWarning で警告追加]
    G --> H[Compilation.warnings に収集]
    H --> I[Stats出力]
```

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

### 参照テーブル一覧

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

### 更新テーブル一覧

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

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| NonErrorEmittedError | emitWarningに非Errorオブジェクトが渡された場合 | NonErrorEmittedErrorでラップしてから処理する |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

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

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

警告メッセージにローダーのファイルパスが含まれる場合がある（from パラメータ）。CI/CD環境のログ公開時には、内部ファイルパスの漏洩に注意する。

## 備考

- ModuleWarning は `makeSerializable` によりキャッシュのシリアライズ/デシリアライズに対応している。
- serialize/deserialize メソッドでは `warning` プロパティも保存・復元される。
- `ErrorHelpers.cleanUp` により、スタックトレースからローダー実行フラグ以降の行とメッセージ行が除去され、読みやすいdetailsが生成される。

---

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

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

### 推奨読解順序

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

ModuleWarningクラスの構造と、基底クラスWebpackErrorとの関係を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | WebpackError.js | `lib/WebpackError.js` | 基底クラスのプロパティ定義（message, details, module, loc等） |
| 1-2 | ModuleWarning.js | `lib/ModuleWarning.js` | コンストラクタでのメッセージ構築ロジック、warningプロパティ |

**読解のコツ**: ModuleWarning のコンストラクタ（行20-39）では、`from` パラメータの有無でメッセージフォーマットが変わる点に注目する。また、`cleanUp` 関数によるスタックトレース整形処理（行36-39）も重要。

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

ローダーの `emitWarning` がどのようにModuleWarningの生成につながるかを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | NormalModule.js | `lib/NormalModule.js` | _createLoaderContextメソッド内のemitWarning定義（行754-762）、ソースマップ処理時の警告（行1112） |

**主要処理フロー**:
1. **行754**: `emitWarning` コールバック定義
2. **行755-756**: 引数がError型でない場合、NonErrorEmittedErrorでラップ
3. **行758-762**: `new ModuleWarning(warning, { from: getCurrentLoaderName() })` でインスタンス生成
4. **行758**: `this.addWarning()` でモジュールの警告リストに追加

#### Step 3: スタックトレース整形を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ErrorHelpers.js | `lib/ErrorHelpers.js` | cleanUp関数（行77-81）: cutOffLoaderExecutionとcutOffMessageの組み合わせ |

**主要処理フロー**:
- **行77-81**: `cleanUp` = `cutOffLoaderExecution` + `cutOffMessage` の順で適用
- **行31**: `cutOffLoaderExecution` はスタックから "LOADER_EXECUTION" フラグ以降を除去

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

```
NormalModule._createLoaderContext()
    │
    ├─ emitWarning(warning)            [行754]
    │      ├─ new NonErrorEmittedError()  [行756] (非Error時)
    │      └─ new ModuleWarning(warning, {from})  [行759]
    │             ├─ super(message)        [行31]
    │             └─ cleanUp(warning.stack) [行37-38]
    │                    ├─ cutOffLoaderExecution() [ErrorHelpers.js 行31]
    │                    └─ cutOffMessage()         [ErrorHelpers.js 行63-70]
    │
    └─ (ソースマップ処理)
           └─ new ModuleWarning(err)     [行1112]
```

### データフロー図

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

ローダーからの      ───> NonErrorEmittedError        ───> ModuleWarning
Errorオブジェクト        (非Error時ラップ)                  │
                                                          │ addWarning()
from: ローダー名    ───> メッセージ構築               ───> Module.warnings[]
                         "Module Warning (from X): Y"      │
                                                          │ Compilation収集
warning.stack       ───> cleanUp()                   ───> Compilation.warnings[]
                         スタックトレース整形               │
                                                          v
                                                     Stats出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ModuleWarning.js | `lib/ModuleWarning.js` | ソース | モジュール警告クラス定義 |
| WebpackError.js | `lib/WebpackError.js` | ソース | 基底エラー/警告クラス |
| ErrorHelpers.js | `lib/ErrorHelpers.js` | ソース | スタックトレース整形ヘルパー |
| NormalModule.js | `lib/NormalModule.js` | ソース | ローダー実行コンテキスト、emitWarning定義 |
| makeSerializable.js | `lib/util/makeSerializable.js` | ソース | シリアライズ登録ユーティリティ |
| Compilation.js | `lib/Compilation.js` | ソース | warnings配列の管理 |
