# 通知設計書 22-AssetsOverSizeLimitWarning

## 概要

本ドキュメントは、Webpackにおける `AssetsOverSizeLimitWarning` の通知仕様を定義する。個別のアセット（バンドルファイル）のサイズが推奨制限を超過した場合に発行されるパフォーマンス警告クラスである。

### 本通知の処理概要

AssetsOverSizeLimitWarningは、Webpackビルドの出力フェーズ（afterEmit）において、生成されたアセットファイルのサイズが設定された推奨制限（デフォルト244KiB = 250,000バイト）を超過した場合に発行される警告通知である。

**業務上の目的・背景**：Webアプリケーションのパフォーマンスに直結するバンドルサイズの肥大化を検知し、開発者に早期の対応を促すために必要な警告である。大きすぎるアセットは初期読み込み時間の増大やモバイル環境でのパフォーマンス劣化を引き起こす。Webpackのperformance設定で有効化される。

**通知の送信タイミング**：compiler.hooks.afterEmitフック実行時（全アセットの出力完了後）に、SizeLimitsPluginが各アセットのサイズを検査し、制限超過を検出した時点で発行される。

**通知の受信者**：Webpackビルドを実行する開発者。performance.hints設定に応じて、compilation.warningsまたはcompilation.errorsに蓄積される。

**通知内容の概要**：制限超過した全アセットの名前とサイズの一覧を含む警告メッセージ。formatSize関数によりサイズは人間が読みやすい形式（KiB、MiB等）で表示される。

**期待されるアクション**：開発者は、コード分割（import()によるlazy loading）、Tree Shaking、外部ライブラリの最適化等を行い、アセットサイズを推奨制限以内に収める。

## 通知種別

ビルド警告（Webpack Compilation Warning）またはビルドエラー（performance.hints = "error" の場合）。コンソール出力およびStats APIを通じて開発者に通知される。

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（afterEmitフック内で即座に生成） |
| 優先度 | 中（警告レベル）/ 高（hints="error"の場合はエラーレベル） |
| リトライ | なし（一度きりの警告発行） |

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

SizeLimitsPlugin.apply()内のcompiler.hooks.afterEmitタップで、全アセットのサイズを検査し、制限超過アセットを検出した場合に生成される。performance.hints設定により `compilation.warnings` または `compilation.errors` に追加される。

## 通知テンプレート

### メール通知の場合

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

### 本文テンプレート

```
WARNING in asset size limit: The following asset(s) exceed the recommended size limit ({制限サイズ}).
This can impact web performance.
Assets:
  {アセット名1} ({サイズ1})
  {アセット名2} ({サイズ2})
```

### 添付ファイル

該当なし。

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| assetsOverSizeLimit | 制限超過アセットの配列（{name, size}） | compilation.getAssets()からフィルタ | Yes |
| assetLimit | アセットサイズ制限値（バイト） | performance.maxAssetSize（デフォルト250000） | Yes |
| name | 警告名 | 固定値 "AssetsOverSizeLimitWarning" | Yes |
| assets | 制限超過アセット配列（インスタンスプロパティ） | コンストラクタ引数をそのまま保持 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| フック実行 | compiler.hooks.afterEmit | performance.hints が truthy かつ、いずれかのアセットサイズが maxAssetSize を超過 | SizeLimitsPluginが検査を実行 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| performance.hints が false/未設定 | パフォーマンスヒント自体が無効化されている場合 |
| assetFilter で除外されたアセット | development用アセット（ソースマップ等）はデフォルトで除外される |
| アセットサイズが制限以下 | 全アセットが制限内の場合はこの警告は発行されない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[compiler.hooks.afterEmit発火] --> B[SizeLimitsPlugin処理開始]
    B --> C[compilation.getAssets でアセット一覧取得]
    C --> D{assetFilter通過?}
    D -->|No| E[スキップ]
    D -->|Yes| F{サイズ > maxAssetSize?}
    F -->|No| E
    F -->|Yes| G[assetsOverSizeLimit配列に追加]
    G --> H{超過アセットあり?}
    H -->|No| I[終了]
    H -->|Yes| J[AssetsOverSizeLimitWarning生成]
    J --> K{hints === 'error'?}
    K -->|Yes| L[compilation.errorsに追加]
    K -->|No| M[compilation.warningsに追加]
    L --> I
    M --> I
```

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

### 参照テーブル一覧

該当なし。Webpackはデータベースを使用しない。

### 更新テーブル一覧

該当なし。

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| sourceが未定義 | アセットのsourceオブジェクトがnullの場合 | フィルタ処理でスキップされる |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 制限なし（ビルド1回につき最大1つの警告） |
| 1日あたり上限 | 制限なし |

### 配信時間帯

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

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

アセットのファイル名とサイズ情報が警告メッセージに含まれるが、機密情報は含まれないためリスクは低い。

## 備考

- WebpackErrorを基底クラスとして継承している
- SizeLimitsPlugin は performance オプションが有効な場合のみ適用される
- isOverSizeLimitSet（WeakSet）でサイズ超過したアセットをマーキングし、外部からSizeLimitsPlugin.isOverSizeLimit()で判定可能
- デフォルトの assetFilter は development 属性を持つアセット（ソースマップ等）を除外する

---

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

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

### 推奨読解順序

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

まず、AssetsOverSizeLimitWarningクラスとその入力データ型を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | WebpackError.js | `lib/WebpackError.js` | 基底クラス。全警告/エラーの共通プロパティ |
| 1-2 | AssetsOverSizeLimitWarning.js | `lib/performance/AssetsOverSizeLimitWarning.js` | AssetDetails[]とassetLimitを受け取り、フォーマット済みメッセージを生成 |
| 1-3 | SizeFormatHelpers.js | `lib/SizeFormatHelpers.js` | formatSize関数。バイト数をKiB/MiB等の読みやすい形式に変換 |

**読解のコツ**: AssetDetails型は `{name: string, size: number}` の構造で、SizeLimitsPlugin内で定義されている。

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

SizeLimitsPluginの全体処理フローを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | SizeLimitsPlugin.js | `lib/performance/SizeLimitsPlugin.js` | compiler.hooks.afterEmitタップ（78行目）でアセットサイズ検査を実行 |

**主要処理フロー**:
1. **78行目**: compiler.hooks.afterEmit.tapでプラグインを登録
2. **103-116行目**: 全アセットをループし、assetFilter通過かつサイズ超過のものをassetsOverSizeLimit配列に追加
3. **109行目**: `info.size || source.size()` でサイズを取得
4. **114行目**: isOverSizeLimitSetにソースを追加（マーキング）
5. **147-153行目**: assetsOverSizeLimit.length > 0 の場合にAssetsOverSizeLimitWarningを生成
6. **174-178行目**: hints === "error" ならcompilation.errors、そうでなければcompilation.warningsに追加

#### Step 3: 警告メッセージ生成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | AssetsOverSizeLimitWarning.js | `lib/performance/AssetsOverSizeLimitWarning.js` | 19-27行目でアセット一覧をフォーマットしメッセージを構築 |

**主要処理フロー**:
- **19-21行目**: assetsOverSizeLimitをmap/joinで一覧文字列に変換
- **23-27行目**: superコンストラクタにフォーマット済みメッセージを渡す

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

```
compiler.hooks.afterEmit
    |
    +-- SizeLimitsPlugin.apply() (78行目)
            |
            +-- compilation.getAssets() でアセット一覧取得
            |
            +-- アセットサイズ検査ループ (103-116行目)
            |       |
            |       +-- assetFilter() でフィルタリング (104行目)
            |       +-- info.size || source.size() でサイズ取得 (108行目)
            |       +-- isOverSizeLimitSet.add(source) でマーキング (114行目)
            |
            +-- new AssetsOverSizeLimitWarning(assetsOverSizeLimit, assetSizeLimit)
            |       |
            |       +-- formatSize(assetLimit) でサイズフォーマット
            |       +-- formatSize(asset.size) で各アセットサイズフォーマット
            |
            +-- compilation.warnings.push() または compilation.errors.push()
```

### データフロー図

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

compilation.getAssets() --> assetFilter() で除外判定 --> assetsOverSizeLimit[]
                            |                              |
performance.maxAssetSize -> サイズ比較                       v
                            |                     AssetsOverSizeLimitWarning
performance.hints --------> 出力先判定             |
                                                   v
                                           compilation.warnings[]
                                           または compilation.errors[]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| AssetsOverSizeLimitWarning.js | `lib/performance/AssetsOverSizeLimitWarning.js` | ソース | 警告クラス本体 |
| SizeLimitsPlugin.js | `lib/performance/SizeLimitsPlugin.js` | ソース | 警告の生成・発行を行うプラグイン |
| WebpackError.js | `lib/WebpackError.js` | ソース | 基底エラー/警告クラス |
| SizeFormatHelpers.js | `lib/SizeFormatHelpers.js` | ソース | サイズフォーマットユーティリティ |
