# 通知設計書 5-CommentCompilationWarning

## 概要

本ドキュメントは、Webpackのコード内コメント（マジックコメント）のパース時に発生する警告を表す `CommentCompilationWarning` クラスの設計仕様を記述する。

### 本通知の処理概要

CommentCompilationWarning は、Webpackマジックコメント（`/* webpackChunkName: "..." */` 等）の解析に失敗した場合に発生する警告クラスである。import()式やrequire()式、CSS url()、new Worker()などに付随するマジックコメントの構文エラーを検出して開発者に通知する。

**業務上の目的・背景**：Webpackはコード内のマジックコメントを解析してチャンク名、プリフェッチ、プリロード、フェッチプライオリティなどのビルド制御を行う。これらのコメントに構文エラーがある場合、意図した最適化が適用されないため、開発者に早期に通知して修正を促す必要がある。

**通知の送信タイミング**：JavaScriptパーサーの `parseCommentOptions` メソッドがマジックコメントの解析中にエラーを検出した時。具体的には以下の場面で発生する: (1) dynamic import文のコメント解析（ImportParserPlugin.js 行300）、(2) CommonJS require式のコメント解析（CommonJsImportsParserPlugin.js 行150, 289）、(3) CSS url()のコメント解析（CssParser.js 行797, 892, 960, 1025）、(4) new Worker()のコメント解析（WorkerPlugin.js 行309）、(5) URL()のコメント解析（URLParserPlugin.js 行128）、(6) import phase式のコメント解析（ImportPhase.js 行90, 110）。

**通知の受信者**：Webpackビルドを実行した開発者。

**通知内容の概要**：「Compilation error while processing magic comment(-s): /\*{コメント内容}\*/: {エラーメッセージ}」の形式で、不正なコメントの内容とエラーの詳細が表示される。位置情報（loc）により、ソースコード上のどの位置でエラーが発生したかも特定可能。

**期待されるアクション**：開発者は該当のマジックコメントの構文を修正する（JSONとして有効な形式にする、正しいキー名を使用するなど）。

## 通知種別

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

## 送信仕様

### 基本情報

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

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

パーサープラグイン内で `parser.parseCommentOptions()` の結果からエラーが検出された場合、`parser.state.module.addWarning()` で該当モジュールの警告リストに追加される。

## 通知テンプレート

### メール通知の場合

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

### 本文テンプレート

```
Compilation error while processing magic comment(-s): /*{comment.value}*/: {error.message}
```

### 添付ファイル

該当なし。

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| message | 警告メッセージ | コンストラクタ引数 | Yes |
| loc | コメントのソースコード位置情報 | comment.loc（AST上のコメントノード位置） | Yes |
| name | エラー名称（固定値 "CommentCompilationWarning"） | クラス内で設定 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| import()文 | parseCommentOptionsでエラー検出 | commentErrorsが非空 | ImportParserPlugin.js 行296-305 |
| require()文 | parseCommentOptionsでエラー検出 | commentErrorsが非空 | CommonJsImportsParserPlugin.js 行150, 289 |
| CSS url() | parseCommentOptionsでエラー検出 | commentErrorsが非空 | CssParser.js 行797, 892, 960, 1025 |
| new Worker() | parseCommentOptionsでエラー検出 | commentErrorsが非空 | WorkerPlugin.js 行309 |
| URL() | parseCommentOptionsでエラー検出 | commentErrorsが非空 | URLParserPlugin.js 行128 |
| import phase | parseCommentOptionsでエラー検出 | commentErrorsが非空 | ImportPhase.js 行90, 110 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| parseCommentOptionsがエラーを返さない | マジックコメントの構文が正しい場合は警告なし |
| stats.warnings=false | Stats出力で表示が抑制される |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[import/require/url等の式の解析] --> B[parseCommentOptions呼び出し]
    B --> C{commentErrors あり?}
    C -->|Yes| D[各エラーについてループ]
    C -->|No| E[正常処理継続]
    D --> F[CommentCompilationWarning生成]
    F --> G[module.addWarning で追加]
    G --> H[次のエラーへ]
    H --> D
```

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

### 参照テーブル一覧

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

### 更新テーブル一覧

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

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 該当なし | - | CommentCompilationWarning自体が警告通知であり、ビルドは継続される |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 制限なし（マジックコメントの数に依存） |
| 1日あたり上限 | 制限なし |

### 配信時間帯

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

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

マジックコメントの内容がメッセージに含まれるため、コメント内にセンシティブな情報が記載されている場合はログ公開時に注意する。

## 備考

- `makeSerializable` によりキャッシュのシリアライズ/デシリアライズに対応している。
- このクラスは非常にシンプルで、`message` と `loc` のみを保持する。`details` や `hideStack` は設定されない。
- Webpackの多数のパーサープラグインから使用されており、マジックコメントの共通エラーハンドリング機構として機能している。

---

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

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

### 推奨読解順序

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

CommentCompilationWarningクラスのシンプルな構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | CommentCompilationWarning.js | `lib/CommentCompilationWarning.js` | コンストラクタ（message, loc）の2引数構成、WebpackError継承 |

**読解のコツ**: このクラスは非常にシンプルで、コンストラクタ（行18-25）でmessageとlocを設定するのみ。serialize/deserializeメソッドのオーバーライドもない（基底クラスの実装をそのまま使用）。

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

マジックコメント解析の典型的なパターンを理解するために、ImportParserPluginでの使用例を読む。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ImportParserPlugin.js | `lib/dependencies/ImportParserPlugin.js` | parseCommentOptionsの呼び出しとエラーハンドリング（行293-305） |

**主要処理フロー**:
1. **行293-294**: `parser.parseCommentOptions(expr.range)` でマジックコメントを解析
2. **行296**: `if (commentErrors)` でエラーの存在を確認
3. **行297-305**: 各エラーについてループし、`new CommentCompilationWarning(メッセージ, comment.loc)` を生成
4. **行299**: `parser.state.module.addWarning()` でモジュールの警告に追加

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | CssParser.js | `lib/css/CssParser.js` | CSS内のマジックコメント解析（行797, 892, 960, 1025） |
| 3-2 | CommonJsImportsParserPlugin.js | `lib/dependencies/CommonJsImportsParserPlugin.js` | require()のマジックコメント解析（行150, 289） |
| 3-3 | WorkerPlugin.js | `lib/dependencies/WorkerPlugin.js` | new Worker()のマジックコメント解析（行309） |
| 3-4 | URLParserPlugin.js | `lib/url/URLParserPlugin.js` | URL()のマジックコメント解析（行128） |
| 3-5 | ImportPhase.js | `lib/dependencies/ImportPhase.js` | import phaseのマジックコメント解析（行90, 110） |

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

```
各パーサープラグイン
    │
    ├─ ImportParserPlugin.apply()           [ImportParserPlugin.js]
    │      ├─ parser.parseCommentOptions()  [行294]
    │      └─ new CommentCompilationWarning() [行300]
    │
    ├─ CommonJsImportsParserPlugin.apply()  [CommonJsImportsParserPlugin.js]
    │      ├─ parser.parseCommentOptions()
    │      └─ new CommentCompilationWarning() [行150, 289]
    │
    ├─ CssParser.parse()                    [CssParser.js]
    │      └─ new CommentCompilationWarning() [行797, 892, 960, 1025]
    │
    ├─ WorkerPlugin.apply()                 [WorkerPlugin.js]
    │      └─ new CommentCompilationWarning() [行309]
    │
    ├─ URLParserPlugin.apply()              [URLParserPlugin.js]
    │      └─ new CommentCompilationWarning() [行128]
    │
    └─ ImportPhase                          [ImportPhase.js]
           └─ new CommentCompilationWarning() [行90, 110]
```

### データフロー図

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

import()/require()/      ───> parser.parseCommentOptions() ───> {options, errors}
url()/Worker()等               マジックコメント解析                │
  のAST式                                                         v
                                                             commentErrors[]
                                                                  │
comment.value           ───> メッセージ構築                  ───> CommentCompilationWarning
comment.loc                  "Compilation error..."               │
                                                                  │ addWarning()
                                                                  v
                                                             Module.warnings[]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| CommentCompilationWarning.js | `lib/CommentCompilationWarning.js` | ソース | コメント解析警告クラス定義 |
| WebpackError.js | `lib/WebpackError.js` | ソース | 基底エラー/警告クラス |
| ImportParserPlugin.js | `lib/dependencies/ImportParserPlugin.js` | ソース | import()のマジックコメント解析 |
| CommonJsImportsParserPlugin.js | `lib/dependencies/CommonJsImportsParserPlugin.js` | ソース | require()のマジックコメント解析 |
| CssParser.js | `lib/css/CssParser.js` | ソース | CSS内のマジックコメント解析 |
| WorkerPlugin.js | `lib/dependencies/WorkerPlugin.js` | ソース | Worker()のマジックコメント解析 |
| URLParserPlugin.js | `lib/url/URLParserPlugin.js` | ソース | URL()のマジックコメント解析 |
| ImportPhase.js | `lib/dependencies/ImportPhase.js` | ソース | import phaseのマジックコメント解析 |
| makeSerializable.js | `lib/util/makeSerializable.js` | ソース | シリアライズ登録ユーティリティ |
