# 通知設計書 20-EnvironmentNotSupportAsyncWarning

## 概要

本ドキュメントは、Webpackにおけるターゲット環境のasync/awaitサポート不足警告通知（EnvironmentNotSupportAsyncWarning）の設計を定義する。EnvironmentNotSupportAsyncWarningは、生成されるコードにasync/awaitが含まれるが、ターゲット環境がasync/awaitをサポートしない場合に発行される警告通知である。

### 本通知の処理概要

EnvironmentNotSupportAsyncWarningは、Webpackが非同期モジュール（top-level await、WebAssembly、外部スクリプト/プロミス/インポート等）のコードを生成する際に、ターゲット環境の`output.environment.asyncFunction`設定がasync/awaitをサポートしないことを示している場合に開発者に警告する。

**業務上の目的・背景**：Webpackは様々なターゲット環境（ブラウザ、Node.js等）向けにコードを生成する。特にWebAssemblyの非同期モジュール、トップレベルawait、外部モジュール（promise/script/import/module型）を使用する場合、生成コードにasync/awaitが含まれる。ターゲット環境がasync/awaitをサポートしない場合（例：古いブラウザ向け設定）、ランタイムエラーが発生する。この警告は、開発者にターゲット環境の設定見直しを促し、デプロイ後のランタイムエラーを未然に防ぐ目的で設計されている。

**通知の送信タイミング**：以下の4つのモジュール/機能でasync/awaitが必要になる場合に、静的メソッド`EnvironmentNotSupportAsyncWarning.check()`を通じて発行される。
1. トップレベルawait使用時（HarmonyDetectionParserPlugin.js）
2. 外部モジュール（import/script/promise/module型）使用時（ExternalModule.js）
3. 非同期WebAssemblyモジュール使用時（AsyncWebAssemblyParser.js）

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

**通知内容の概要**：使用中の機能名（feature）と、ターゲット環境がasync/awaitをサポートしないという警告、ランタイムエラーの可能性が含まれる。

**期待されるアクション**：開発者は、`output.environment.asyncFunction: true`の設定、またはターゲットブラウザ/Node.jsバージョンの変更、必要に応じてBabelなどのトランスパイラの追加を行うことが期待される。

## 通知種別

コンソール警告出力 / Webpack Stats API警告レポート / ビルド警告（module.addWarning経由）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（モジュールビルド/パース処理内で即座に生成） |
| 優先度 | 中（ビルドは成功するがランタイムエラーの可能性） |
| リトライ | 無（1回の警告表示のみ） |

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

静的メソッド`EnvironmentNotSupportAsyncWarning.check(module, runtimeTemplate, feature)`が呼び出されると、`runtimeTemplate.supportsAsyncFunction()`を評価する。戻り値がfalsyの場合、`module.addWarning(new EnvironmentNotSupportAsyncWarning(module, feature))`で警告をモジュールに追加する。runtimeTemplate.supportsAsyncFunction()は`output.environment.asyncFunction`設定値を参照する。

## 通知テンプレート

### メール通知の場合

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

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

### 本文テンプレート

```
The generated code contains 'async/await' because this module is using "{feature}".
However, your target environment does not appear to support 'async/await'.
As a result, the code may not run as expected or may cause runtime errors.
```

### 添付ファイル

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

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| feature | 使用中の非同期機能名 | check()メソッドの引数 | Yes |
| module | 警告対象のモジュール | check()メソッドの引数 | Yes |

### featureの取りうる値

| 値 | 説明 | 発行元 |
|---|------|--------|
| "asyncWebAssembly" | 非同期WebAssemblyモジュール | AsyncWebAssemblyParser.js |
| "topLevelAwait" | トップレベルawait使用 | HarmonyDetectionParserPlugin.js |
| "external promise" | 外部プロミスモジュール | ExternalModule.js |
| "external script" | 外部スクリプトモジュール | ExternalModule.js |
| "external import" | 外部インポートモジュール | ExternalModule.js |
| "external module" | 外部モジュール | ExternalModule.js |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| モジュール解析 | HarmonyDetectionParserPlugin - top-level await検出 | supportsAsyncFunction()がfalsy | HarmonyDetectionParserPlugin.js 67-71行目 |
| モジュールビルド | ExternalModule.build - import/script/promise/module型 | supportsAsyncFunction()がfalsy | ExternalModule.js 754-787行目 |
| モジュール解析 | AsyncWebAssemblyParser.parse | supportsAsyncFunction()がfalsy | AsyncWebAssemblyParser.js 45-49行目 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| output.environment.asyncFunctionがtrueの場合 | ターゲット環境はasync/awaitサポート済み |
| 非同期モジュール機能を使用していない場合 | check()メソッドが呼ばれない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[非同期機能を使用するモジュール検出] --> B{機能種別}
    B --> C[topLevelAwait]
    B --> D[asyncWebAssembly]
    B --> E["external (promise/script/import/module)"]
    C --> F["EnvironmentNotSupportAsyncWarning.check()"]
    D --> F
    E --> F
    F --> G{"runtimeTemplate.supportsAsyncFunction()"}
    G -->|true| H[警告なし]
    G -->|false| I[EnvironmentNotSupportAsyncWarning生成]
    I --> J["module.addWarning(warning)"]
    J --> K[compilation.warningsに集約]
    K --> L[終了]
    H --> L
```

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

### 参照テーブル一覧

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

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| RuntimeTemplate | async/awaitサポート判定 | outputOptions.environment.asyncFunction |
| Module | 警告追加先 | addWarning()メソッド |

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

#### RuntimeTemplateインスタンス

| 参照項目（メソッド/プロパティ名） | 用途 | 取得条件 |
|-------------------|------|---------|
| supportsAsyncFunction() | ターゲット環境のasync/awaitサポート判定 | outputOptions.environment.asyncFunctionを返す（RuntimeTemplate.js 138-140行目） |

#### EnvironmentNotSupportAsyncWarningインスタンス

| 参照項目（プロパティ名） | 用途 | 取得条件 |
|-------------------|------|---------|
| name | 警告名表示 | 固定値 "EnvironmentNotSupportAsyncWarning" |
| message | 警告メッセージ表示 | コンストラクタで生成（featureを含む） |
| module | 警告対象モジュール | コンストラクタ引数 |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| module.warnings | INSERT | module.addWarning()経由で追加 |

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

| 操作 | 項目（プロパティ名） | 更新値 | 備考 |
|-----|-----------------|-------|------|
| INSERT | module.warnings | EnvironmentNotSupportAsyncWarningインスタンス | module.addWarning()経由 |

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 制限なし（非同期機能を使用するモジュールごとに1警告） |
| 1日あたり上限 | 制限なし |

### 配信時間帯

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

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

- feature名のみが動的に含まれるため、セキュリティリスクは低い
- モジュール情報は直接メッセージに含まれない

## 備考

- 静的メソッドcheck()による発行パターンは、他のWebpackエラー/警告クラスには見られないユニークな設計
- makeSerializableにより永続キャッシュ対応（シリアライズ/デシリアライズ可能）
- Feature型は6つの文字列リテラル型の共用体型として定義されている
- 著者はGengkun He（@ahabhgk）
- module.addWarning()を使用するため、compilation.warningsではなくモジュール単位で警告が管理される

---

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

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

### 推奨読解順序

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

EnvironmentNotSupportAsyncWarningクラスの構造と静的メソッドcheck()を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | WebpackError.js | `lib/WebpackError.js` | 基底クラスのプロパティ定義（17-38行目） |
| 1-2 | EnvironmentNotSupportAsyncWarning.js | `lib/EnvironmentNotSupportAsyncWarning.js` | 警告クラス定義（15-43行目）。コンストラクタ（21-31行目）と静的メソッドcheck()（39-43行目） |
| 1-3 | RuntimeTemplate.js | `lib/RuntimeTemplate.js` | supportsAsyncFunction()メソッド（138-140行目）。outputOptions.environment.asyncFunctionを返す |

**読解のコツ**: check()は静的メソッドであり、インスタンス生成とmodule.addWarning()をカプセル化している。supportsAsyncFunction()の戻り値がfalsyの場合にのみ警告が生成される点に注目。Feature型定義（13行目）で取りうる6つの値を確認すること。

#### Step 2: エントリーポイントを理解する（3つの呼び出し元）

check()メソッドが呼ばれる3つの箇所をそれぞれ理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | HarmonyDetectionParserPlugin.js | `lib/dependencies/HarmonyDetectionParserPlugin.js` | top-level await検出時のcheck()呼び出し（67-71行目） |
| 2-2 | ExternalModule.js | `lib/ExternalModule.js` | 外部モジュールビルド時のcheck()呼び出し（754, 767, 775, 783行目付近） |
| 2-3 | AsyncWebAssemblyParser.js | `lib/wasm-async/AsyncWebAssemblyParser.js` | 非同期WebAssembly解析時のcheck()呼び出し（45-49行目） |

**主要処理フロー（HarmonyDetectionParserPlugin.js）**:
1. **66行目**: `module.buildMeta.async = true` - 非同期モジュールとしてマーク
2. **67-71行目**: `EnvironmentNotSupportAsyncWarning.check(module, parser.state.compilation.runtimeTemplate, "topLevelAwait")` - 環境チェック

**主要処理フロー（ExternalModule.js）**:
- **753-754行目**: `this.buildMeta.async = true` + check(this, compilation.runtimeTemplate, "external module")
- **766-770行目**: `this.buildMeta.async = true` + check(this, compilation.runtimeTemplate, "external script")
- **774-778行目**: `this.buildMeta.async = true` + check(this, compilation.runtimeTemplate, "external promise")
- **782-787行目**: `this.buildMeta.async = true` + check(this, compilation.runtimeTemplate, "external import")

**主要処理フロー（AsyncWebAssemblyParser.js）**:
1. **44行目**: `BuildMeta.async = true` - 非同期モジュールとしてマーク
2. **45-49行目**: `EnvironmentNotSupportAsyncWarning.check(state.module, state.compilation.runtimeTemplate, "asyncWebAssembly")` - 環境チェック

#### Step 3: 環境判定ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | RuntimeTemplate.js | `lib/RuntimeTemplate.js` | supportsAsyncFunction()の実装（138-140行目） |

**主要処理フロー**:
- **138行目**: `supportsAsyncFunction()` メソッド定義
- **139行目**: `return this.outputOptions.environment.asyncFunction` - output.environment.asyncFunctionの値を返す

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

```
[呼び出し元1] HarmonyDetectionParserPlugin
    |
    +-- parser.hooks.topLevelAwait
            |
            +-- EnvironmentNotSupportAsyncWarning.check(module, runtimeTemplate, "topLevelAwait")

[呼び出し元2] ExternalModule.build()
    |
    +-- [import/script/promise/module型の判定]
            |
            +-- EnvironmentNotSupportAsyncWarning.check(this, runtimeTemplate, feature)

[呼び出し元3] AsyncWebAssemblyParser.parse()
    |
    +-- EnvironmentNotSupportAsyncWarning.check(state.module, runtimeTemplate, "asyncWebAssembly")

[共通処理]
EnvironmentNotSupportAsyncWarning.check()
    |
    +-- runtimeTemplate.supportsAsyncFunction()
    |       |
    |       +-- return outputOptions.environment.asyncFunction
    |
    +-- [falsy時] new EnvironmentNotSupportAsyncWarning(module, feature)
    |
    +-- module.addWarning(warning)
```

### データフロー図

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

Module                          --> EnvironmentNotSupportAsyncWarning      --> 警告メッセージ
RuntimeTemplate                  |  .check() 静的メソッド                    --> module.warnings
Feature (string)                 |  - supportsAsyncFunction() 判定
                                 |  - falsy時にインスタンス生成
                                 |  - module.addWarning() で追加

output.environment.asyncFunction --> RuntimeTemplate                       --> true/false判定
                                    .supportsAsyncFunction()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| WebpackError.js | `lib/WebpackError.js` | ソース | 基底エラークラス |
| EnvironmentNotSupportAsyncWarning.js | `lib/EnvironmentNotSupportAsyncWarning.js` | ソース | 警告クラス定義・check()静的メソッド |
| RuntimeTemplate.js | `lib/RuntimeTemplate.js` | ソース | 環境判定（supportsAsyncFunction） |
| HarmonyDetectionParserPlugin.js | `lib/dependencies/HarmonyDetectionParserPlugin.js` | ソース | top-level await検出時の呼び出し元 |
| ExternalModule.js | `lib/ExternalModule.js` | ソース | 外部モジュールビルド時の呼び出し元 |
| AsyncWebAssemblyParser.js | `lib/wasm-async/AsyncWebAssemblyParser.js` | ソース | 非同期WASM解析時の呼び出し元 |
| makeSerializable.js | `lib/util/makeSerializable.js` | ソース | シリアライズ登録ユーティリティ |
| internalSerializables.js | `lib/util/internalSerializables.js` | ソース | シリアライズ可能クラスの登録簿 |
