# 帳票設計書 21-Stats verbose プリセット

## 概要

本ドキュメントは、webpackのビルド統計情報を最も詳細に出力する「verbose」プリセットの設計仕様を定義する。DefaultStatsPresetPlugin.jsにおけるNAMED_PRESETS.verboseの定義に基づく。

### 本帳票の処理概要

verboseプリセットは、webpackビルドの全統計情報を制限なく詳細に出力するための統計レポートプリセットである。全ての出力スペース制限がInfinityに設定されており、モジュール・チャンク・アセット・エラー・警告等の全情報が省略なしで出力される。

**業務上の目的・背景**：ビルドの全容を把握する必要がある場合に使用される。通常のプリセットでは省略される情報（孤立モジュール、ランタイムモジュール、モジュール深度、usedExports、providedExports等）も全て出力されるため、ビルドの問題を網羅的に調査する際に不可欠である。デバッグ時やビルド構成の最適化を行う際の詳細分析に利用される。

**帳票の利用シーン**：ビルドエラーの原因調査、モジュール依存関係の完全な可視化、バンドルサイズの詳細分析、チャンク分割の検証、Tree Shakingの効果確認、最適化ベイルアウトの調査など、ビルドプロセスの全貌を把握する必要がある場面で使用される。

**主要な出力内容**：
1. ビルドハッシュ・ビルド日時・パブリックパス等のメタ情報
2. エントリーポイント・チャンクグループの完全な情報
3. 全チャンクの詳細情報（チャンク関係・チャンクモジュール・チャンクオリジン含む）
4. 全モジュールの詳細情報（依存モジュール・深度・usedExports・providedExports・最適化ベイルアウト含む）
5. 孤立モジュール・ランタイムモジュール情報
6. エラー・警告の完全な詳細情報（スタックトレース・原因チェーン・内部エラー含む）
7. verbose レベルのロギング情報
8. 子コンパイレーション情報
9. 環境情報

**帳票の出力タイミング**：webpack設定の`stats`オプションに`"verbose"`を指定した場合、またはStats.toString("verbose")・Stats.toJson("verbose")を呼び出した場合に出力される。

**帳票の利用者**：webpack開発者、ビルドエンジニア、フロントエンド開発者（デバッグ時）

## 帳票種別

統計レポート（プリセット設定）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | CLI | webpack --stats verbose | コマンドライン引数指定 |
| - | webpack設定ファイル | webpack.config.js | stats: "verbose" 設定 |
| - | Node.js API | - | Stats.toString("verbose") / Stats.toJson("verbose") |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | テキスト（toString）/ JSON（toJson） |
| 用紙サイズ | 該当なし（コンソール/ファイル出力） |
| 向き | 該当なし |
| ファイル名 | 標準出力またはユーザー指定 |
| 出力方法 | コンソール出力 / プログラマティック取得 |
| 文字コード | UTF-8 |

## 帳票レイアウト

### レイアウト概要

verboseプリセットは以下の全セクションを出力する。各スペース制限はInfinityに設定されており、全データが省略なく表示される。

```
┌─────────────────────────────────────┐
│         コンパイルサマリー            │
│   (バージョン・ハッシュ・時間・日時)    │
├─────────────────────────────────────┤
│         環境情報 (env)               │
├─────────────────────────────────────┤
│         パブリックパス               │
├─────────────────────────────────────┤
│         エントリーポイント            │
├─────────────────────────────────────┤
│         チャンクグループ              │
├─────────────────────────────────────┤
│         アセット一覧                 │
│      (relatedAssets含む)            │
├─────────────────────────────────────┤
│         モジュール一覧               │
│   (orphan/runtime/chunk modules)   │
│   (depth/reasons/usedExports等)    │
├─────────────────────────────────────┤
│         チャンク一覧                 │
│   (chunkRelations/chunkOrigins)    │
├─────────────────────────────────────┤
│         エラー詳細                   │
│   (stack/cause/errors含む)         │
├─────────────────────────────────────┤
│         警告詳細                     │
├─────────────────────────────────────┤
│         ロギング (verbose)           │
├─────────────────────────────────────┤
│         子コンパイレーション           │
└─────────────────────────────────────┘
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | hash | ビルドハッシュ | compilation.hash | 文字列 |
| 2 | builtAt | ビルド日時 | compilation.endTime | タイムスタンプ |
| 3 | version | webpackバージョン | - | 文字列 |
| 4 | timings | ビルド所要時間 | endTime - startTime | ミリ秒 |
| 5 | env | 環境変数情報 | compilation.compiler.options.env | オブジェクト |
| 6 | publicPath | パブリックパス | compilation.outputOptions.publicPath | 文字列 |

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|-----|
| 1 | entrypoints | エントリーポイント情報 | compilation.entrypoints | 構造化データ | - |
| 2 | chunkGroups | チャンクグループ | compilation.namedChunkGroups | 構造化データ | - |
| 3 | assets | アセット一覧 | compilation.getAssets() | 構造化データ | - |
| 4 | modules | モジュール一覧（orphan/runtime含む） | compilation.modules | 構造化データ | - |
| 5 | chunks | チャンク一覧 | compilation.chunks | 構造化データ | - |
| 6 | errors | エラー一覧 | compilation.errors | 構造化データ | - |
| 7 | warnings | 警告一覧 | compilation.getWarnings() | 構造化データ | - |
| 8 | logging | ロギング情報 | compilation.logging | 構造化データ | - |
| 9 | children | 子コンパイレーション | compilation.children | 構造化データ | - |

### フッター部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | errorsCount | エラー総数 | compilation.errors.length | 数値 |
| 2 | warningsCount | 警告総数 | compilation.getWarnings().length | 数値 |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| statsオプション指定 | stats: "verbose" の指定 | Yes |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | modules: depth | 昇順 |
| 2 | chunkModules: name | 昇順 |
| 3 | assets: !size | 降順（サイズ大順） |

### 改ページ条件

該当なし（コンソール出力のため改ページは存在しない）。全スペース制限がInfinityのため、データの省略も発生しない。

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

### 参照テーブル一覧

本帳票はデータベースを参照しない。webpack Compilationオブジェクトから直接データを取得する。

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| Compilation | ビルド結果全体 | - |
| ModuleGraph | モジュール依存関係 | compilation.moduleGraph |
| ChunkGraph | チャンク情報 | compilation.chunkGraph |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| ビルド時間 | endTime - startTime | なし | ミリ秒単位 |
| アセットサイズ | source.size() | なし | バイト単位 |
| モジュールサイズ | module.size() | なし | バイト単位 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[Stats.toString/toJson呼出] --> B[createStatsOptions]
    B --> C{statsPresetフック}
    C -->|verbose| D[NAMED_PRESETS.verbose適用]
    D --> E[statsNormalizeフック]
    E --> F[DEFAULTSで未設定値補完]
    F --> G[NORMALIZERで値正規化]
    G --> H[StatsFactory.create]
    H --> I[extractフックで各種データ抽出]
    I --> J{出力形式}
    J -->|toString| K[StatsPrinter.print]
    J -->|toJson| L[JSONオブジェクト返却]
    K --> M[テキスト出力]
    L --> N[JSON出力]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| 不正なプリセット名 | 存在しないプリセット名を指定 | - | NAMED_PRESETSに登録された名前を使用する |
| Compilationなし | ビルド未実行状態でStats取得 | - | ビルド完了後にStats取得を行う |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 全モジュール・チャンク・アセット（制限なし） |
| 目標出力時間 | ビルド規模に依存（大規模プロジェクトでは数秒〜数十秒） |
| 同時出力数上限 | 1（ビルドごとに1回） |

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

verboseプリセットはファイルシステムのパス情報を含むため、出力結果を外部に公開する際はRequestShortenerによるパス短縮を確認すること。env情報が含まれるため、環境変数に機密情報が含まれる場合は注意が必要。

## 備考

- verboseプリセットでは`modules: false`が設定されているが、これは`chunkModules: true`と組み合わせることで、トップレベルのモジュール一覧ではなくチャンク単位でモジュールを表示する動作となる。DEFAULTSの`modules`計算ロジック（行219-224）により、`chunks`と`chunkModules`が両方trueの場合、forToStringコンテキストでmodulesがfalseに解決される。
- `exclude: false`が設定されており、モジュールの除外フィルタが無効化されている。
- 全スペース制限（errorsSpace, warningsSpace, modulesSpace, chunkModulesSpace, assetsSpace, reasonsSpace）がInfinityに設定されている。

---

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

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

### 推奨読解順序

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

verboseプリセットの設定オブジェクトの構造を理解することが最初のステップである。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | DefaultStatsPresetPlugin.js | `lib/stats/DefaultStatsPresetPlugin.js` | 行36-71: NAMED_PRESETS.verboseの全プロパティ定義を確認する |
| 1-2 | DefaultStatsPresetPlugin.js | `lib/stats/DefaultStatsPresetPlugin.js` | 行186-285: DEFAULTSオブジェクトでプリセット未指定の項目がどうデフォルト値で補完されるか |

**読解のコツ**: NAMED_PRESETSで明示的に設定された値と、DEFAULTSで補完される値の関係を理解すること。verboseではほぼ全項目が明示的に設定されているが、一部のグルーピングオプション等はDEFAULTSから補完される。

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

statsプリセットが適用される起点を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Stats.js | `lib/Stats.js` | 行57-67: toJson()メソッド - createStatsOptions呼出からStatsFactory.createまでの流れ |
| 2-2 | Stats.js | `lib/Stats.js` | 行73-86: toString()メソッド - toJson()に加えてStatsPrinter.printを経由する流れ |

**主要処理フロー**:
1. **行58**: `createStatsOptions(options, { forToString: false })` でオプションを正規化
2. **行62**: `createStatsFactory(normalizedOptions)` でStatsFactoryインスタンスを生成
3. **行64**: `statsFactory.create("compilation", this.compilation, ...)` でデータを抽出

#### Step 3: プリセット適用メカニズムを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | DefaultStatsPresetPlugin.js | `lib/stats/DefaultStatsPresetPlugin.js` | 行23-31: applyDefaults関数 - プリセットのデフォルト値をオプションに適用するロジック |
| 3-2 | DefaultStatsPresetPlugin.js | `lib/stats/DefaultStatsPresetPlugin.js` | 行381-414: apply()メソッド - statsPresetフックとstatsNormalizeフックの登録 |
| 3-3 | DefaultStatsPresetPlugin.js | `lib/stats/DefaultStatsPresetPlugin.js` | 行388-396: statsPreset.for(key)でプリセット名に対応するフックを登録 |
| 3-4 | DefaultStatsPresetPlugin.js | `lib/stats/DefaultStatsPresetPlugin.js` | 行397-412: statsNormalizeフックでDEFAULTSとNORMALIZERを適用 |

**主要処理フロー**:
- **行389-395**: 各プリセット名（verbose, detailed等）に対してstatsPresetフックを登録し、applyDefaultsでプリセットの設定値を適用
- **行397-412**: statsNormalizeフックで未設定の項目にDEFAULTS値を設定し、NORMALIZERで値を正規化

#### Step 4: データ抽出の仕組みを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | StatsFactory.js | `lib/stats/StatsFactory.js` | 行235-248: create()メソッド - データ抽出のエントリーポイント |
| 4-2 | StatsFactory.js | `lib/stats/StatsFactory.js` | 行259-403: _create()メソッド - 配列/オブジェクトに対するextract・filter・sort・group・merge・resultフックの実行 |

#### Step 5: 出力フォーマットを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | StatsPrinter.js | `lib/stats/StatsPrinter.js` | 行184-195: print()メソッド - テキスト出力のエントリーポイント |
| 5-2 | StatsPrinter.js | `lib/stats/StatsPrinter.js` | 行204-297: _print()メソッド - 再帰的なprint処理（要素ソート・印刷・結果処理） |

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

```
Stats.toString("verbose") / Stats.toJson("verbose")
    |
    +-- Compilation.createStatsOptions("verbose", context)
    |       |
    |       +-- compilation.hooks.statsPreset.for("verbose").call(options)
    |       |       |
    |       |       +-- DefaultStatsPresetPlugin: applyDefaults(options, NAMED_PRESETS.verbose)
    |       |
    |       +-- compilation.hooks.statsNormalize.call(options, context)
    |               |
    |               +-- DefaultStatsPresetPlugin: DEFAULTS適用 + NORMALIZER適用
    |
    +-- Compilation.createStatsFactory(normalizedOptions)
    |       |
    |       +-- StatsFactory.create("compilation", compilation, context)
    |               |
    |               +-- hooks.extract: 各データセクションの抽出
    |               +-- hooks.filter / sort / group: データの整形
    |
    +-- [toStringの場合] Compilation.createStatsPrinter(normalizedOptions)
            |
            +-- StatsPrinter.print("compilation", data)
                    |
                    +-- hooks.print / printElements / printItems: テキスト整形
```

### データフロー図

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

webpack.config.js          DefaultStatsPresetPlugin            コンソール/JSON
  stats: "verbose"   --->    statsPresetフック             ---> Stats テキスト/JSON
                               |
                          applyDefaults()
                               |
                          statsNormalizeフック
                               |
Compilation              StatsFactory.create()
  .modules          --->   extractフック               ---> StatsCompilation
  .chunks                   |                               オブジェクト
  .assets                filter/sort/group
  .errors                   |
  .warnings          StatsPrinter.print()
  .logging          --->   print/printElements         ---> フォーマット済み
                           フック                          テキスト文字列
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| DefaultStatsPresetPlugin.js | `lib/stats/DefaultStatsPresetPlugin.js` | ソース | プリセット定義・デフォルト値・正規化処理 |
| Stats.js | `lib/Stats.js` | ソース | Stats API（toJson/toString）のエントリーポイント |
| StatsFactory.js | `lib/stats/StatsFactory.js` | ソース | 統計データの抽出・変換エンジン |
| StatsPrinter.js | `lib/stats/StatsPrinter.js` | ソース | 統計データのテキスト整形エンジン |
| DefaultStatsFactoryPlugin.js | `lib/stats/DefaultStatsFactoryPlugin.js` | ソース | 各データセクションのextractフック実装 |
| DefaultStatsPrinterPlugin.js | `lib/stats/DefaultStatsPrinterPlugin.js` | ソース | 各データセクションのprintフック実装 |
| Compilation.js | `lib/Compilation.js` | ソース | createStatsOptions/createStatsFactory/createStatsPrinterメソッド |
