# 帳票設計書 19-EntrypointsOverSizeLimitWarning

## 概要

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

### 本帳票の処理概要

EntrypointsOverSizeLimitWarning は、webpackビルドで生成されたエントリーポイントの合算アセットサイズが設定されたサイズ上限（デフォルト: 250KB）を超過した場合に、警告メッセージとして出力される帳票である。エントリーポイントに含まれる全アセットの合計サイズを計算し、超過した場合にエントリーポイント名・合計サイズ・構成ファイル一覧を表示する。

**業務上の目的・背景**：個々のアセットが小さくても、エントリーポイントとして読み込まれるアセットの合計サイズが大きい場合、初期読み込み時間に影響する。エントリーポイント単位でのサイズ監視により、初期表示パフォーマンスの劣化を防止する。

**帳票の利用シーン**：本番ビルド時のパフォーマンスチェック、エントリーポイントの肥大化検知、コード分割の必要性判断。

**主要な出力内容**：
1. 警告メッセージ - "entrypoint size limit: The following entrypoint(s) combined asset size exceeds the recommended limit (XXX KiB)."
2. 超過エントリーポイント一覧 - エントリーポイント名、合計サイズ、構成ファイル一覧
3. パフォーマンス影響の注意書き - "This can impact web performance."

**帳票の出力タイミング**：webpackビルドの `afterEmit` フックで SizeLimitsPlugin により実行される。

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

## 帳票種別

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

## 利用画面

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

## 出力形式

### 基本仕様

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

## 帳票レイアウト

### レイアウト概要

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

```
entrypoint size limit: The following entrypoint(s) combined asset size exceeds the recommended limit (250 KiB). This can impact web performance.
Entrypoints:
  main (350 KiB)
      main.js
      main.css
  app (500 KiB)
      app.js
      app.css
      vendor.js
```

### ヘッダー部

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

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|-----|
| 1 | name | エントリーポイント名 | entrypoint.name | 文字列 | - |
| 2 | size | エントリーポイントの合計サイズ | formatSize(entrypoint.size) | フォーマット済み文字列 | - |
| 3 | files | 構成ファイル一覧 | entry.getFiles().filter(fileFilter) | 文字列配列 | - |

### フッター部

該当なし。

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| performanceオプション | performance.hints が "warning" または "error" であること | Yes |
| maxEntrypointSize超過 | エントリーポイントの合計アセットサイズが performance.maxEntrypointSize を超過すること | Yes |
| assetFilter | assetFilter関数がtrueを返すアセットのみ合算対象（デフォルト: developmentアセットを除外） | Yes（自動） |

### ソート順

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

### 改ページ条件

N/A

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

### 参照テーブル一覧

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| compilation.entrypoints | エントリーポイント一覧 | Map<string, Entrypoint> |
| compilation.getAsset(file) | アセット情報の取得 | ファイル名で検索 |

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

#### Entrypoint

| 参照項目 | 帳票項目との対応 | 取得条件 | 備考 |
|---------|----------------|---------|------|
| name | name | - | エントリーポイント名 |
| getFiles() | files | fileFilter でフィルタ | エントリーポイントの全ファイル |

#### Asset

| 参照項目 | 帳票項目との対応 | 取得条件 | 備考 |
|---------|----------------|---------|------|
| info.size \|\| source.size() | 合計サイズ計算 | assetFilter通過かつsource存在 | バイト単位 |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| entrypointSize | SUM(info.size \|\| source.size()) for each file in entrypoint.getFiles() | なし | assetFilter通過ファイルのみ合算 |
| 超過判定 | entrypointSize > entrypointSizeLimit | なし | entrypointSizeLimit はバイト単位 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[afterEmit フック] --> B[compilation.entrypoints イテレーション]
    B --> C[getEntrypointSize で合計サイズ算出]
    C --> D{size > maxEntrypointSize?}
    D -->|No| B
    D -->|Yes| E[entrypointsOverLimit に追加]
    E --> F[isOverSizeLimitSet に登録]
    F --> B
    B --> G{entrypointsOverLimit.length > 0?}
    G -->|No| H[警告なし]
    G -->|Yes| I[new EntrypointsOverSizeLimitWarning 生成]
    I --> J{hints === error?}
    J -->|Yes| K[compilation.errors に追加]
    J -->|No| L[compilation.warnings に追加]
```

## エラー処理

### エラーケース一覧

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | エントリーポイント数に依存（通常数件） |
| 目標出力時間 | 即時 |
| 同時出力数上限 | N/A |

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

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

## 備考

- エントリーポイントサイズは、エントリーポイントに含まれる全アセット（assetFilter通過分）の合計で計算される。
- `isOverSizeLimitSet` WeakSet により、超過エントリーポイントは Stats の出力で `isOverSizeLimit: true` フラグが付与される。
- AssetsOverSizeLimitWarning と EntrypointsOverSizeLimitWarning は独立して判定され、両方の警告が同時に出力される場合がある。

---

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

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

### 推奨読解順序

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

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

**読解のコツ**: EntrypointDetails は AssetDetails と異なり、files プロパティを追加で持つ。合計サイズと構成ファイル一覧の両方を保持する。

#### Step 2: エントリーポイントサイズ計算

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | SizeLimitsPlugin.js | `lib/performance/SizeLimitsPlugin.js` | getEntrypointSize 関数（86-99行目）。エントリーポイントの全ファイルのサイズを合算 |

**主要処理フロー**:
- **88行目**: `entrypoint.getFiles()` で全ファイル取得
- **89-94行目**: `compilation.getAsset(file)` で各アセット取得、assetFilter チェック
- **95行目**: `info.size || source.size()` でサイズ取得して合算

#### Step 3: 超過判定と警告生成

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | SizeLimitsPlugin.js | `lib/performance/SizeLimitsPlugin.js` | エントリーポイント超過チェック（128-140行目） |
| 3-2 | EntrypointsOverSizeLimitWarning.js | `lib/performance/EntrypointsOverSizeLimitWarning.js` | コンストラクタ（18-36行目）で警告メッセージを生成 |

**主要処理フロー**:
- **129-130行目**: `compilation.entrypoints` イテレーションとサイズ取得
- **132-139行目**: 超過判定と EntrypointDetails の生成
- **19-26行目（Warning）**: 各エントリーポイントのフォーマット（名前・サイズ・ファイル一覧）
- **27-30行目（Warning）**: super() でメッセージ設定

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

```
SizeLimitsPlugin.apply(compiler)
    │
    └─ compiler.hooks.afterEmit.tap
           │
           ├─ getEntrypointSize(entrypoint)
           │      ├─ entrypoint.getFiles()
           │      ├─ compilation.getAsset(file)
           │      ├─ assetFilter(name, source, info)
           │      └─ size += info.size || source.size()
           │
           ├─ size > entrypointSizeLimit 判定
           │
           ├─ new EntrypointsOverSizeLimitWarning(entrypointsOverLimit, limit)
           │      └─ formatSize() でサイズをフォーマット
           │
           └─ compilation.warnings.push / compilation.errors.push
```

### データフロー図

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

compilation.entrypoints      SizeLimitsPlugin                 EntrypointsOverSizeLimitWarning
(name, chunks, files)        afterEmit フック                  (WebpackError)
       │                     ────────────────────▶              │
       │                     合計サイズ計算                      ├── message: 警告テキスト
       │                     + 超過判定                         └── entrypoints: EntrypointDetails[]
       │                     + fileFilter
       │
performance options ───────▶ maxEntrypointSize, hints
```

### 関連ファイル一覧

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