# 通知設計書 4-InvalidDependenciesModuleWarning

## 概要

本ドキュメントは、Webpackにおいてローダーやプラグインが無効な（非絶対パスの）依存関係を報告した場合に発生する警告を表す `InvalidDependenciesModuleWarning` クラスの設計仕様を記述する。

### 本通知の処理概要

InvalidDependenciesModuleWarning は、ローダーやプラグインが `addDependency`, `addMissingDependency`, `addContextDependency` に対して絶対パスではない依存関係パスを報告した場合に生成される警告クラスである。ファイルウォッチングやキャッシュの正常動作に影響するため、開発者に修正を促す。

**業務上の目的・背景**：Webpackのファイル監視（watching）とキャッシュ機能は、依存関係パスが絶対パスであることを前提としている。ローダーやプラグインが相対パスやグロブパターンなどの無効なパスを依存関係として報告すると、変更検知やキャッシュの破棄が正しく機能しなくなる。この警告は、ローダー/プラグインの開発者に対して絶対パスの使用を強く推奨するために存在する。なお、Webpackはベストエフォートで無効なパスの変換を試みるが、これは非推奨の動作である。

**通知の送信タイミング**：NormalModuleのビルド完了後、依存関係の検証フェーズで非絶対パスの依存関係が検出された時（NormalModule.js 行1381-1386）。

**通知の受信者**：Webpackビルドを実行した開発者、および問題のあるローダー/プラグインの開発者。

**通知内容の概要**：「Invalid dependencies have been reported...」という詳細なメッセージと共に、無効な依存関係パスの一覧（最初の3件+省略表記）が表示される。メッセージにはaddDependency, addMissingDependency, addContextDependencyの正しい使い方のガイダンスも含まれる。

**期待されるアクション**：ローダー/プラグインの開発者は、`this.addDependency()` 等に渡すパスを `path.resolve()` 等で絶対パスに変換する。グロブパターンの場合は、`addContextDependency` でディレクトリの絶対パスを使用する。

## 通知種別

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

## 送信仕様

### 基本情報

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

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

NormalModuleのビルド完了後のコールバック内で、fileDependencies, missingDependencies, contextDependenciesの各依存関係セットを検査し、非絶対パスが見つかった場合にModuleのaddWarningで追加される。

## 通知テンプレート

### メール通知の場合

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

### 本文テンプレート

```
Invalid dependencies have been reported by plugins or loaders for this module. All reported dependencies need to be absolute paths.
Invalid dependencies may lead to broken watching and caching.
As best effort we try to convert all invalid values to absolute paths and converting globs into context dependencies, but this is deprecated behavior.
Loaders: Pass absolute paths to this.addDependency (existing files), this.addMissingDependency (not existing files), and this.addContextDependency (directories).
Plugins: Pass absolute paths to fileDependencies (existing files), missingDependencies (not existing files), and contextDependencies (directories).
Globs: They are not supported. Pass absolute path to the directory as context dependencies.
The following invalid values have been reported:
 * "{無効パス1}"
 * "{無効パス2}"
 * "{無効パス3}"
 * and more ...
```

### 添付ファイル

該当なし。

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| module | 依存関係を持つモジュール | コンストラクタ引数 | Yes |
| deps | 無効な依存関係パスのIterable | 非絶対パス検出結果のSet | Yes |
| name | エラー名称（固定値 "InvalidDependenciesModuleWarning"） | クラス内で設定 | Yes |
| details | 4件目以降の無効パス一覧 | depsListのslice(3)結果 | No |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| ビルド完了 | NormalModule._doBuild完了後の依存関係検証 | nonAbsoluteDependenciesがundefinedでない場合 | NormalModule.js 行1381-1386 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| すべての依存関係が絶対パス | nonAbsoluteDependenciesがundefinedのまま、警告は生成されない |
| stats.warnings=false | Stats出力で表示が抑制される |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[NormalModule._doBuild完了] --> B[fileDependencies検査]
    B --> C[missingDependencies検査]
    C --> D[contextDependencies検査]
    D --> E{非絶対パスあり?}
    E -->|Yes| F[InvalidDependenciesModuleWarning生成]
    E -->|No| G[警告なし]
    F --> H[deps をソートしリスト化]
    H --> I[最初の3件をメッセージに含める]
    I --> J[4件目以降をdetailsに設定]
    J --> K[Module.addWarning で追加]
    K --> L[Stats出力]
```

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

### 参照テーブル一覧

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

### 更新テーブル一覧

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

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 該当なし | - | - |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

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

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

無効な依存関係パスがメッセージに含まれるため、内部ファイル構造が推測される可能性がある。ログの公開時には注意が必要。

## 備考

- 無効な依存関係パスはソートされた上でメッセージに含まれる（行19: `[...deps].sort()`）。
- メッセージには最初の3件のパスのみ表示され、4件以上ある場合は「and more ...」と省略される（行28-29）。
- 4件目以降のパスは `details` プロパティに格納される（行34）。
- `makeSerializable` により永続キャッシュへのシリアライズに対応している。

---

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

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

### 推奨読解順序

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

InvalidDependenciesModuleWarningのメッセージ構築ロジックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | InvalidDependenciesModuleWarning.js | `lib/InvalidDependenciesModuleWarning.js` | コンストラクタでのdepsソート、メッセージ構築、details設定 |

**読解のコツ**: コンストラクタ（行18-36）では、`deps` Iterableをソート済み配列に変換し、各パスを `JSON.stringify` でエスケープしてリスト化する。メッセージは複数行テンプレートリテラルで構築されるが、最初の3件のみ表示し残りをdetailsに分ける点が特徴的。

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

NormalModuleの依存関係検証でどのようにこの警告が生成されるかを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | NormalModule.js | `lib/NormalModule.js` | ビルド完了後の依存関係検証（行1370-1387）、checkDependencies関数による非絶対パス検出 |

**主要処理フロー**:
1. **行1370-1377**: fileDependencies, contextDependencies, missingDependenciesをbuildInfoから取得
2. **行1378-1380**: `checkDependencies()` で各依存関係セットを検査
3. **行1381**: `nonAbsoluteDependencies !== undefined` の条件チェック
4. **行1382-1383**: 遅延requireで `InvalidDependenciesModuleWarning` をロード
5. **行1384-1386**: `this.addWarning(new InvalidDependenciesModuleWarning(this, nonAbsoluteDependencies))` で警告追加

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

```
NormalModule._doBuild() コールバック
    │
    ├─ checkDependencies(fileDependencies)         [行1378]
    ├─ checkDependencies(missingDependencies)       [行1379]
    ├─ checkDependencies(contextDependencies)       [行1380]
    │      └─ 非絶対パスをnonAbsoluteDependenciesに収集
    │
    └─ new InvalidDependenciesModuleWarning(this, nonAbsoluteDependencies)  [行1385]
           ├─ [...deps].sort()                      [行19]
           ├─ depsList = deps.map(dep => ` * ${JSON.stringify(dep)}`)  [行20]
           ├─ super(複数行メッセージ)                [行21-30]
           └─ this.details = depsList.slice(3)      [行34]
```

### データフロー図

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

buildInfo.                ───> checkDependencies()            ───> nonAbsoluteDependencies
fileDependencies               非絶対パス検出                       (Set<string>)
missingDependencies                                                  │
contextDependencies                                                  v
                                                              InvalidDependenciesModuleWarning
                           ───> コンストラクタ                ───> Module.warnings[]
                                ソート・リスト化                      │
                                メッセージ構築                        v
                                                              Stats出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| InvalidDependenciesModuleWarning.js | `lib/InvalidDependenciesModuleWarning.js` | ソース | 無効依存関係警告クラス定義 |
| WebpackError.js | `lib/WebpackError.js` | ソース | 基底エラー/警告クラス |
| NormalModule.js | `lib/NormalModule.js` | ソース | 依存関係検証とこの警告の生成元 |
| makeSerializable.js | `lib/util/makeSerializable.js` | ソース | シリアライズ登録ユーティリティ |
