# 通知設計書 21-UnsupportedFeatureWarning

## 概要

本ドキュメントは、Webpackにおける `UnsupportedFeatureWarning` の通知仕様を定義する。サポートされていない言語機能やmagic commentの不正な使用を検出した場合にモジュール単位で発行される警告クラスである。

### 本通知の処理概要

UnsupportedFeatureWarningは、Webpackのモジュール解析・パース処理時にサポートされていない機能や不正な構文の使用を検出した際に発行される警告通知である。

**業務上の目的・背景**：Webpackがサポートしていない機能や、magic comment（webpackIgnore、webpackChunkName、webpackMode等）の不正な値を開発者に通知することで、意図しないビルド結果やランタイムエラーを未然に防ぐ。開発者がソースコード中の問題箇所を特定し、早期に修正できるようにするために必要な警告である。

**通知の送信タイミング**：モジュールの解析（パース）フェーズにおいて、以下の場面で発行される。(1) JavaScript/CSSパーサーがサポートされていない式を検出した場合、(2) dynamic import()のmagic commentで不正な型の値が渡された場合（webpackIgnore、webpackChunkName、webpackMode、webpackPrefetch、webpackPreload、webpackFetchPriority、webpackInclude、webpackExclude、webpackExports）、(3) CommonJS require()のmagic commentで不正な値が検出された場合、(4) AMDスタイルのrequire()で静的解析が不可能な場合、(5) new Worker()やnew URL()のmagic commentで不正な値が検出された場合。

**通知の受信者**：Webpackビルドを実行する開発者。compilation.warningsに蓄積され、ビルド出力（コンソール、Stats出力）として表示される。

**通知内容の概要**：警告メッセージ（不正な構文や値の説明）と、問題が発生したソースコード上の位置情報（loc: 行番号・列番号）を含む。スタックトレースは非表示（hideStack = true）である。

**期待されるアクション**：開発者はlocで示されるソースコード位置を確認し、magic commentの値を正しい型に修正するか、サポートされていない機能の使用を代替手段に置き換える。

## 通知種別

ビルド警告（Webpack Compilation Warning）。コンソール出力およびStats APIを通じて開発者に通知される。

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（パース処理中に即座に生成） |
| 優先度 | 中（警告レベル） |
| リトライ | なし（一度きりの警告発行） |

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

モジュールのパース処理中に `parser.state.module.addWarning()` を通じてモジュールに直接紐付けられ、compilation.warningsに集約される。受信者はビルドプロセスを実行している開発者全員である。

## 通知テンプレート

### メール通知の場合

該当なし。本通知はメール通知ではなく、Webpackビルド出力として表示される。

### 本文テンプレート

```
WARNING in {モジュールパス} {行:列}

UnsupportedFeatureWarning: {警告メッセージ}
```

具体的なメッセージパターン:
- `` `webpackIgnore` expected a boolean, but received: {value}. ``
- `` `webpackChunkName` expected a string, but received: {value}. ``
- `` `webpackMode` expected 'lazy', 'lazy-once', 'eager' or 'weak', but received: {value}. ``
- `` `webpackPrefetch` expected true or a number, but received: {value}. ``
- `` `webpackPreload` expected true or a number, but received: {value}. ``
- `` `webpackFetchPriority` expected true or "low", "high" or "auto", but received: {value}. ``
- `` `webpackInclude` expected a regular expression, but received: {value}. ``
- `` `webpackExclude` expected a regular expression, but received: {value}. ``
- `` `webpackExports` expected a string or an array of strings, but received: {value}. ``
- ``Cannot statically analyse 'require(...)' in line {lineNumber}``

### 添付ファイル

該当なし。

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| message | 警告メッセージ本文 | コンストラクタ引数 | Yes |
| loc | ソースコード上の位置情報（start/end行列） | コンストラクタ引数（DependencyLocation） | Yes |
| name | 警告名 | 固定値 "UnsupportedFeatureWarning" | Yes |
| hideStack | スタックトレース非表示フラグ | 固定値 true | Yes |
| module | 警告元モジュール | parser.state.module（addWarning時に自動設定） | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| パース処理 | JavascriptParserHelpers.expressionIsUnsupported() | サポートされていない式が評価された場合 | `(void 0)` に置換された上で警告発行 |
| パース処理 | ImportParserPlugin（dynamic import解析） | magic commentの値が期待する型でない場合 | webpackIgnore, webpackChunkName等の各種オプション |
| パース処理 | CommonJsImportsParserPlugin（require解析） | webpackIgnoreの値がboolean以外の場合 | CommonJS require()のmagic comment |
| パース処理 | AMDRequireDependenciesBlockParserPlugin | AMD require()が静的解析できない場合 | エラーとして追加される場合もある |
| パース処理 | WorkerPlugin（Worker生成解析） | magic commentの値が期待する型でない場合 | new Worker()のオプション |
| パース処理 | URLParserPlugin（URL生成解析） | magic commentの値が期待する型でない場合 | new URL()のオプション |
| パース処理 | CssParser（CSS解析） | webpackIgnoreの値がboolean以外の場合 | @import, url()等のCSS構文 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| parser.state.moduleが未設定 | JavascriptParserHelpers.expressionIsUnsupported()内でmoduleが存在しない場合はスキップ |
| magic commentの値が正しい型 | 各パーサープラグインで型チェックに合格した場合は警告なし |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[モジュールのパース開始] --> B[式の評価/magic comment解析]
    B --> C{サポートされた機能/正しい型か?}
    C -->|Yes| D[通常処理継続]
    C -->|No| E[UnsupportedFeatureWarning生成]
    E --> F[message と loc を設定]
    F --> G[module.addWarning で警告追加]
    G --> H[compilation.warnings に集約]
    H --> I[Stats出力でコンソール表示]
    D --> J[パース処理継続]
```

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

### 参照テーブル一覧

該当なし。Webpackはデータベースを使用しない。警告はインメモリのcompilationオブジェクトに蓄積される。

### 更新テーブル一覧

該当なし。

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| モジュール未設定 | parser.state.moduleがundefinedの場合 | 警告追加をスキップし処理を続行 |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

制限なし。ビルド実行時に即座に警告が生成される。

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

ソースコードのパス情報と行番号が警告メッセージに含まれるため、ビルド出力の公開範囲に注意が必要。magic commentの値はそのまま警告メッセージに埋め込まれるが、ビルド環境内の情報であるためリスクは低い。

## 備考

- WebpackErrorを基底クラスとして継承している
- `makeSerializable` でシリアライズ対応（キャッシュ永続化に対応）
- hideStack = true であるため、スタックトレースは表示されない
- AMDRequireDependenciesBlockParserPlugin では `addWarning` ではなく `addError` として追加される場合がある（ただしクラス自体はWarningのまま）

---

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

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

### 推奨読解順序

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

まず、UnsupportedFeatureWarningクラスのデータ構造と基底クラスWebpackErrorの関係を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | WebpackError.js | `lib/WebpackError.js` | 基底クラス。message, details, module, loc, hideStack, chunkプロパティを持つ |
| 1-2 | UnsupportedFeatureWarning.js | `lib/UnsupportedFeatureWarning.js` | 本クラス。message, locをコンストラクタで受け取り、hideStack=trueを固定設定 |

**読解のコツ**: WebpackErrorはErrorクラスを継承しており、serialize/deserializeメソッドでキャッシュ永続化に対応している。UnsupportedFeatureWarningはmakeSerializableでシリアライズ登録されている。

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

UnsupportedFeatureWarningが生成される主要な起点を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | JavascriptParserHelpers.js | `lib/javascript/JavascriptParserHelpers.js` | expressionIsUnsupported関数（91-108行目）がUnsupportedFeatureWarningの主要生成元 |

**主要処理フロー**:
1. **93-97行目**: ConstDependencyを `(void 0)` として生成し、元の式を置換
2. **100行目**: parser.state.moduleの存在チェック
3. **101-106行目**: module.addWarningでUnsupportedFeatureWarningを生成・追加

#### Step 3: ImportParserPlugin での使用を理解する

dynamic import()のmagic comment解析時の警告生成を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ImportParserPlugin.js | `lib/dependencies/ImportParserPlugin.js` | 各magic commentの型バリデーション時にUnsupportedFeatureWarningを生成 |

**主要処理フロー**:
- **317-322行目**: webpackIgnoreのboolean型チェック
- **330-335行目**: webpackChunkNameのstring型チェック
- **342-347行目**: webpackModeのstring型チェック
- **358-363行目**: webpackPrefetchの型チェック
- **372-377行目**: webpackPreloadの型チェック
- **389-394行目**: webpackFetchPriorityの型チェック
- **402-407行目**: webpackIncludeのRegExp型チェック
- **417-422行目**: webpackExcludeのRegExp型チェック
- **437-442行目**: webpackExportsのstring/配列チェック

#### Step 4: その他のパーサープラグインでの使用を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | CommonJsImportsParserPlugin.js | `lib/dependencies/CommonJsImportsParserPlugin.js` | CommonJS require()でのwebpackIgnoreバリデーション |
| 4-2 | AMDRequireDependenciesBlockParserPlugin.js | `lib/dependencies/AMDRequireDependenciesBlockParserPlugin.js` | AMD require()の静的解析不能時にaddErrorとして使用 |
| 4-3 | WorkerPlugin.js | `lib/dependencies/WorkerPlugin.js` | new Worker()でのmagic commentバリデーション |
| 4-4 | URLParserPlugin.js | `lib/url/URLParserPlugin.js` | new URL()でのmagic commentバリデーション |
| 4-5 | CssParser.js | `lib/css/CssParser.js` | CSS解析時のwebpackIgnoreバリデーション |

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

```
[各パーサープラグイン]
    |
    +-- ImportParserPlugin.js (dynamic import解析)
    |       |
    |       +-- new UnsupportedFeatureWarning(message, loc)
    |       +-- parser.state.module.addWarning(warning)
    |
    +-- JavascriptParserHelpers.js (expressionIsUnsupported)
    |       |
    |       +-- new ConstDependency("(void 0)", range, null)
    |       +-- new UnsupportedFeatureWarning(message, loc)
    |       +-- parser.state.module.addWarning(warning)
    |
    +-- CommonJsImportsParserPlugin.js (require解析)
    |       +-- new UnsupportedFeatureWarning(message, loc)
    |
    +-- AMDRequireDependenciesBlockParserPlugin.js (AMD require解析)
    |       +-- new UnsupportedFeatureWarning(message, loc)
    |
    +-- WorkerPlugin.js (Worker生成解析)
    |       +-- new UnsupportedFeatureWarning(message, loc)
    |
    +-- URLParserPlugin.js (URL生成解析)
    |       +-- new UnsupportedFeatureWarning(message, loc)
    |
    +-- CssParser.js (CSS解析)
            +-- new UnsupportedFeatureWarning(message, loc)
```

### データフロー図

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

ソースコードAST -------> パーサープラグイン解析 -------> UnsupportedFeatureWarning
(式/magic comment)        |                              |
                          v                              v
                    型バリデーション              module.addWarning()
                          |                              |
                          v                              v
                    不正値検出               compilation.warnings[]
                                                         |
                                                         v
                                                  Stats出力/コンソール
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| UnsupportedFeatureWarning.js | `lib/UnsupportedFeatureWarning.js` | ソース | 警告クラス本体 |
| WebpackError.js | `lib/WebpackError.js` | ソース | 基底エラー/警告クラス |
| JavascriptParserHelpers.js | `lib/javascript/JavascriptParserHelpers.js` | ソース | expressionIsUnsupported関数（主要生成元） |
| ImportParserPlugin.js | `lib/dependencies/ImportParserPlugin.js` | ソース | dynamic import()のmagic comment解析 |
| CommonJsImportsParserPlugin.js | `lib/dependencies/CommonJsImportsParserPlugin.js` | ソース | CommonJS require()の解析 |
| AMDRequireDependenciesBlockParserPlugin.js | `lib/dependencies/AMDRequireDependenciesBlockParserPlugin.js` | ソース | AMD require()の解析 |
| WorkerPlugin.js | `lib/dependencies/WorkerPlugin.js` | ソース | new Worker()の解析 |
| URLParserPlugin.js | `lib/url/URLParserPlugin.js` | ソース | new URL()の解析 |
| CssParser.js | `lib/css/CssParser.js` | ソース | CSS構文の解析 |
| makeSerializable.js | `lib/util/makeSerializable.js` | ソース | シリアライズ登録ユーティリティ |
