# 帳票設計書 18-AssetsOverSizeLimitWarning

## 概要

本ドキュメントは、設定されたサイズ上限を超過したアセットの警告レポートを出力する「AssetsOverSizeLimitWarning」の設計仕様を定義するものである。

### 本帳票の処理概要

AssetsOverSizeLimitWarning は、webpackビルドで生成されたアセット（JavaScript、CSS等のファイル）が設定されたサイズ上限（デフォルト: 250KB）を超過した場合に、警告メッセージとして出力される帳票である。超過したアセットの名前とサイズを一覧表示し、Webパフォーマンスへの影響を開発者に通知する。

**業務上の目的・背景**：バンドルサイズの肥大化はWebページの読み込み速度を低下させ、ユーザー体験を悪化させる。サイズ上限を設定してビルド時に警告を出すことで、パフォーマンス劣化の早期検知と対策を促進する。

**帳票の利用シーン**：本番ビルド時のパフォーマンスチェック、CI/CDパイプラインでのサイズ制限チェック（hints: "error" 設定時はビルドエラー扱い）。

**主要な出力内容**：
1. 警告メッセージ - "asset size limit: The following asset(s) exceed the recommended size limit (XXX KiB)."
2. 超過アセット一覧 - アセット名とサイズの一覧
3. パフォーマンス影響の注意書き - "This can impact web performance."

**帳票の出力タイミング**：webpackビルドの `afterEmit` フックで SizeLimitsPlugin により実行される。ビルド成果物の出力完了後にサイズチェックが行われる。

**帳票の利用者**：フロントエンド開発者、QAエンジニア、DevOpsエンジニア。

## 帳票種別

警告レポート（パフォーマンス警告）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | webpack設定 | `performance: { maxAssetSize: 250000, hints: 'warning' }` | ビルド実行時に自動判定 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | テキスト（WebpackError の message プロパティ） |
| 用紙サイズ | N/A |
| 向き | N/A |
| ファイル名 | N/A（compilation.warnings / compilation.errors に追加） |
| 出力方法 | 標準エラー出力（Stats出力時に表示） |
| 文字コード | UTF-8 |

## 帳票レイアウト

### レイアウト概要

警告メッセージは以下の形式で出力される。

```
asset size limit: The following asset(s) exceed the recommended size limit (250 KiB).
This can impact web performance.
Assets:
  main.js (350 KiB)
  vendor.js (500 KiB)
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | 警告タイトル | サイズ上限超過の警告見出し | 静的テキスト + formatSize(assetLimit) | 文字列 |
| 2 | 影響説明 | パフォーマンス影響の注意書き | 静的テキスト | 文字列 |

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|-----|
| 1 | name | 超過アセットのファイル名 | asset.name | 文字列 | - |
| 2 | size | アセットのサイズ | formatSize(asset.size) | フォーマット済み文字列（KiB等） | - |

### フッター部

該当なし。

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| performanceオプション | performance.hints が "warning" または "error" であること | Yes |
| maxAssetSize超過 | アセットサイズが performance.maxAssetSize を超過すること | Yes |
| assetFilter | assetFilter関数がtrueを返すこと（デフォルト: developmentアセットを除外） | Yes（自動） |
| ソース存在 | asset.source が truthy であること | Yes |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | compilation.getAssets() のイテレーション順 | 登録順 |

### 改ページ条件

N/A

## データベース参照仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| compilation.getAssets() | アセット一覧の取得 | Asset[] |

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

#### Asset

| 参照項目 | 帳票項目との対応 | 取得条件 | 備考 |
|---------|----------------|---------|------|
| name | name | - | アセットファイル名 |
| source | ソース存在判定 | truthyチェック | ソースが無いアセットはスキップ |
| info | assetFilter判定 | info.development で開発用除外 | デフォルトフィルタは !info.development |
| info.size \|\| source.size() | size | - | info.size 優先、なければ source.size() |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| size | info.size \|\| source.size() | なし | バイト単位 |
| 超過判定 | size > assetSizeLimit | なし | assetSizeLimit はバイト単位 |
| 表示サイズ | formatSize(size) | 小数点以下含む | KiB, MiB 等の単位に変換 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[afterEmit フック] --> B[compilation.getAssets イテレーション]
    B --> C{assetFilter 通過?}
    C -->|No| B
    C -->|Yes| D{source 存在?}
    D -->|No| B
    D -->|Yes| E[size = info.size or source.size]
    E --> F{size > maxAssetSize?}
    F -->|No| B
    F -->|Yes| G[assetsOverSizeLimit に追加]
    G --> H[isOverSizeLimitSet に登録]
    H --> B
    B --> I{assetsOverSizeLimit.length > 0?}
    I -->|No| J[警告なし]
    I -->|Yes| K[new AssetsOverSizeLimitWarning 生成]
    K --> L{hints === error?}
    L -->|Yes| M[compilation.errors に追加]
    L -->|No| N[compilation.warnings に追加]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| 特になし | - | - | 警告/エラーとして出力されるが、処理自体は失敗しない |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | アセット数に依存（通常数件〜数十件） |
| 目標出力時間 | 即時（アセットイテレーションのみ） |
| 同時出力数上限 | N/A |

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

特になし。警告メッセージにはアセットのファイル名とサイズのみが含まれる。

## 備考

- デフォルトの `assetFilter` は `(name, source, info) => !info.development` であり、ソースマップ等の開発用アセットは除外される。
- `hints: "error"` に設定すると、警告ではなくエラーとして `compilation.errors` に追加され、ビルドが失敗扱いとなる。
- `isOverSizeLimitSet` WeakSet により、超過アセットは Stats の出力で `isOverSizeLimit: true` フラグが付与される。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | SizeLimitsPlugin.js | `lib/performance/SizeLimitsPlugin.js` | AssetDetails 型定義（22-25行目）: name, size |

**読解のコツ**: AssetDetails は超過アセットの名前とサイズのみを保持するシンプルな型。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | SizeLimitsPlugin.js | `lib/performance/SizeLimitsPlugin.js` | apply()メソッド（72-183行目）。afterEmit フックでサイズチェック実行 |

**主要処理フロー**:
1. **78行目**: `compiler.hooks.afterEmit.tap` でフック登録
2. **102-116行目**: アセットイテレーションとサイズ超過判定
3. **147-153行目**: AssetsOverSizeLimitWarning のインスタンス生成と警告追加

#### Step 3: 警告メッセージ生成

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | AssetsOverSizeLimitWarning.js | `lib/performance/AssetsOverSizeLimitWarning.js` | コンストラクタ（18-33行目）で警告メッセージを生成 |

**主要処理フロー**:
- **19-21行目**: 超過アセット一覧をフォーマット（`\n  name (size)`）
- **23-27行目**: super() で WebpackError のメッセージを設定

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

```
SizeLimitsPlugin.apply(compiler)
    │
    └─ compiler.hooks.afterEmit.tap
           │
           ├─ compilation.getAssets() イテレーション
           │      ├─ assetFilter(name, source, info)
           │      ├─ size = info.size || source.size()
           │      └─ size > maxAssetSize → assetsOverSizeLimit.push
           │
           ├─ new AssetsOverSizeLimitWarning(assetsOverSizeLimit, assetSizeLimit)
           │      └─ formatSize() でサイズをフォーマット
           │
           └─ compilation.warnings.push / compilation.errors.push
```

### データフロー図

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

compilation.getAssets()   SizeLimitsPlugin                 AssetsOverSizeLimitWarning
(name, source, info)      afterEmit フック                  (WebpackError)
       │                  ────────────────────▶              │
       │                  サイズ超過判定                      ├── message: 警告テキスト
       │                  + assetFilter                     └── assets: AssetDetails[]
       │                  + formatSize
       │
performance options ───▶ maxAssetSize, hints
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| AssetsOverSizeLimitWarning.js | `lib/performance/AssetsOverSizeLimitWarning.js` | ソース | 警告メッセージの生成 |
| SizeLimitsPlugin.js | `lib/performance/SizeLimitsPlugin.js` | ソース | サイズチェックのメインロジック |
| SizeFormatHelpers.js | `lib/SizeFormatHelpers.js` | ソース | formatSize() 関数 |
| WebpackError.js | `lib/WebpackError.js` | ソース | 警告/エラーの基底クラス |
