# 通知設計書 18-CaseSensitiveModulesWarning

## 概要

本ドキュメントは、Webpackにおけるモジュール名の大文字小文字差異警告通知（CaseSensitiveModulesWarning）の設計を定義する。CaseSensitiveModulesWarningは、大文字小文字のみが異なるモジュール名が複数存在する場合に発行される警告通知である。

### 本通知の処理概要

CaseSensitiveModulesWarningは、ビルド対象のモジュール群の中に、パスの大文字小文字のみが異なる複数のモジュールが検出された場合に開発者に警告する仕組みである。OS間のファイルシステムの違い（WindowsはCase-insensitive、Linux/macOSはCase-sensitive）に起因する潜在的な問題を検出する。

**業務上の目的・背景**：Windowsのファイルシステム（NTFS等）は大文字小文字を区別しないが、LinuxやmacOS（デフォルト設定）は区別する。開発者がWindowsで`import './Component'`と`import './component'`を混在させてもWindowsでは同一ファイルとして解決されるが、Linux環境にデプロイすると異なるモジュールとして扱われ、ビルド失敗やランタイムエラーを引き起こす。この警告は、クロスプラットフォームでの一貫性を確保するために設計されている。

**通知の送信タイミング**：WarnCaseSensitiveModulesPluginがcompilation.hooks.sealフックのタイミングで全モジュールを検査し、大文字小文字のみが異なるモジュールが検出された場合にcompilation.warningsに追加される。

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

**通知内容の概要**：大文字小文字のみが異なるモジュールの識別子一覧と、各モジュールの使用元（インポート元）の情報が含まれる。

**期待されるアクション**：開発者は、import文やrequire文で使用しているモジュールパスの大文字小文字を統一し、すべてのOS環境で一貫した動作を確保することが期待される。

## 通知種別

コンソール警告出力 / Webpack Stats API警告レポート / ビルド警告（compilation.warningsへの追加）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（sealフック内で即座に追加） |
| 優先度 | 中（クロスプラットフォーム互換性の問題） |
| リトライ | 無（1回の警告表示のみ） |

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

WarnCaseSensitiveModulesPluginがcompilation.hooks.sealフックで全モジュールのidentifier()を小文字変換して比較する。同一小文字identifierを持つモジュールが2つ以上存在する場合、CaseSensitiveModulesWarningを生成してcompilation.warningsに追加する。data: URLのモジュールは除外される。

## 通知テンプレート

### メール通知の場合

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

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

### 本文テンプレート

```
There are multiple modules with names that only differ in casing.
This can lead to unexpected behavior when compiling on a filesystem with other case-semantic.
Use equal casing. Compare these module identifiers:
* {モジュール識別子1}
    Used by {N} module(s), i. e.
    {使用元モジュール識別子}
* {モジュール識別子2}
    Used by {N} module(s), i. e.
    {使用元モジュール識別子}
```

### 添付ファイル

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

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| modules | 大文字小文字のみが異なるモジュール群 | compilation.modules | Yes |
| moduleGraph | モジュール依存関係グラフ | compilation.moduleGraph | Yes |
| module.identifier() | モジュールの識別子 | Moduleインスタンス | Yes |
| getIncomingConnectionsByOriginModule | 使用元モジュール情報 | ModuleGraph | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| ビルド処理 | compilation.hooks.seal | 小文字変換後のidentifierが重複するモジュールが2つ以上存在 | WarnCaseSensitiveModulesPlugin.js 24-58行目 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| 大文字小文字が異なるモジュールが存在しない場合 | 警告は発行されない |
| data: URLモジュール | encodedContent !== undefinedの場合はスキップ |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[compilation.hooks.seal発火] --> B[全モジュールを走査]
    B --> C{data: URLモジュール？}
    C -->|Yes| D[スキップ]
    C -->|No| E[identifier()を小文字変換]
    E --> F[moduleWithoutCaseマップに追加]
    D --> G[次のモジュール]
    F --> G
    G --> H{全モジュール処理完了}
    H --> I[各エントリの重複チェック]
    I --> J{map.size > 1?}
    J -->|Yes| K[CaseSensitiveModulesWarning生成]
    J -->|No| L[次のエントリ]
    K --> M[compilation.warnings.push]
    M --> L
    L --> N[終了]
```

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

### 参照テーブル一覧

本通知はデータベースを使用しない。Webpackのインメモリデータ構造を参照する。

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| compilation.modules | 全モジュール一覧 | Setコレクション |
| ModuleGraph | モジュール間の依存関係 | グラフデータ構造 |

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

#### CaseSensitiveModulesWarningインスタンス

| 参照項目（プロパティ名） | 用途 | 取得条件 |
|-------------------|------|---------|
| name | 警告名表示 | 固定値 "CaseSensitiveModulesWarning" |
| message | 警告メッセージ表示 | sortModulesとcreateModulesListMessageで生成 |
| module | 最初のモジュール | sortedModules[0] |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| compilation.warnings | INSERT | CaseSensitiveModulesWarningインスタンスの追加 |

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

| 操作 | 項目（プロパティ名） | 更新値 | 備考 |
|-----|-----------------|-------|------|
| INSERT | compilation.warnings[] | CaseSensitiveModulesWarningインスタンス | sealフック内 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| N/A | - | 本通知は警告であり、エラーケースは存在しない |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | N/A（警告通知のため不要） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 制限なし（重複モジュールグループごとに1警告） |
| 1日あたり上限 | 制限なし |

### 配信時間帯

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

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

- モジュールのフルパス（識別子）が警告メッセージに含まれるため、ディレクトリ構造の情報が表示される
- 使用元モジュールの識別子も表示される

## 備考

- sortModules関数でモジュールをidentifier()のアルファベット順にソートし、一貫した出力順序を保証
- createModulesListMessage関数でモジュールごとの使用元情報をフォーマット
- WarnCaseSensitiveModulesPluginはWebpackOptionsApply.jsで無条件に登録される（779行目）
- moduleプロパティにはソートされたモジュール配列の最初の要素が設定される
- data: URLモジュール（resourceResolveData.encodedContentが存在）は判定から除外される

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | WebpackError.js | `lib/WebpackError.js` | 基底クラスのプロパティ定義（17-38行目） |
| 1-2 | CaseSensitiveModulesWarning.js | `lib/CaseSensitiveModulesWarning.js` | ヘルパー関数sortModules（17-27行目）とcreateModulesListMessage（34-50行目）、クラス定義（52-70行目） |

**読解のコツ**: sortModules関数はidentifier()でアルファベット順ソート、createModulesListMessage関数はmoduleGraph.getIncomingConnectionsByOriginModuleで使用元を取得してメッセージを構築する。

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

WarnCaseSensitiveModulesPluginの検出ロジックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | WarnCaseSensitiveModulesPlugin.js | `lib/WarnCaseSensitiveModulesPlugin.js` | sealフック内の検出ロジック（24-58行目） |
| 2-2 | WebpackOptionsApply.js | `lib/WebpackOptionsApply.js` | プラグイン登録（779行目） |

**主要処理フロー**:
1. **24行目**: compilation.hooks.seal.tapでフック登録
2. **26行目**: moduleWithoutCaseマップ初期化
3. **27-47行目**: 全モジュールを走査し小文字identifierでグループ化（data: URLは除外）
4. **48-57行目**: 重複グループに対してCaseSensitiveModulesWarningを生成

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

```
webpack()
    |
    +-- WebpackOptionsApply.process()
            |
            +-- new WarnCaseSensitiveModulesPlugin().apply(compiler)
                    |
                    +-- compiler.hooks.compilation.tap()
                            |
                            +-- compilation.hooks.seal.tap()
                                    |
                                    +-- [seal発火時]
                                            |
                                            +-- [全モジュール走査]
                                            |       |
                                            |       +-- module.identifier().toLowerCase()
                                            |       |
                                            |       +-- moduleWithoutCaseマップに蓄積
                                            |
                                            +-- [重複チェック]
                                                    |
                                                    +-- sortModules()
                                                    |
                                                    +-- createModulesListMessage()
                                                    |
                                                    +-- new CaseSensitiveModulesWarning()
                                                    |
                                                    +-- compilation.warnings.push()
```

### データフロー図

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

compilation.modules         --> WarnCaseSensitiveModulesPlugin      --> compilation.warnings[]
(全モジュール)                |  - identifier()小文字変換
                             |  - 重複検出
moduleGraph                 --> CaseSensitiveModulesWarning         --> コンソール警告出力
(依存関係グラフ)              |  - sortModules()
                             |  - createModulesListMessage()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| WebpackError.js | `lib/WebpackError.js` | ソース | 基底エラークラス |
| CaseSensitiveModulesWarning.js | `lib/CaseSensitiveModulesWarning.js` | ソース | 警告クラス定義・ヘルパー関数 |
| WarnCaseSensitiveModulesPlugin.js | `lib/WarnCaseSensitiveModulesPlugin.js` | ソース | 検出・警告発行プラグイン |
| WebpackOptionsApply.js | `lib/WebpackOptionsApply.js` | ソース | プラグイン登録元 |
| ModuleGraph.js | `lib/ModuleGraph.js` | ソース | 使用元モジュール情報の提供 |
