# 帳票設計書 22-Stats detailed プリセット

## 概要

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

### 本帳票の処理概要

detailedプリセットは、verboseプリセットより一部の項目を制限しつつも、広範なビルド統計情報を出力するプリセットである。チャンクモジュールの表示が無効化され、スペース制限が1000に設定されている点がverboseとの主な違いである。

**業務上の目的・背景**：verboseほどの全量出力は不要だが、通常のデフォルト出力よりも詳しい情報が必要な場合に使用される。大規模プロジェクトでverboseを使うと出力量が膨大になるため、適度に制限された詳細情報が必要な場面で有用である。モジュール最適化の検証やチャンク構成の確認など、特定の問題調査に十分な情報を提供する。

**帳票の利用シーン**：ビルド構成の検証、モジュール依存関係の調査、チャンク分割の確認、usedExports/providedExportsの確認、最適化ベイルアウトの調査など、日常的な開発作業での詳細分析に使用される。

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

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

**帳票の利用者**：webpack開発者、ビルドエンジニア、フロントエンド開発者

## 帳票種別

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

## 利用画面

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

## 出力形式

### 基本仕様

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

## 帳票レイアウト

### レイアウト概要

detailedプリセットはverboseと類似した構成だが、チャンクモジュール・依存モジュール・孤立モジュール・エラースタック・環境情報・子コンパイレーションが除外され、スペース制限が適用される。

```
┌─────────────────────────────────────┐
│         コンパイルサマリー            │
│   (バージョン・ハッシュ・時間・日時)    │
├─────────────────────────────────────┤
│         パブリックパス               │
├─────────────────────────────────────┤
│         エントリーポイント            │
├─────────────────────────────────────┤
│         チャンクグループ              │
├─────────────────────────────────────┤
│     アセット一覧（max 1000件）       │
│      (relatedAssets含む)            │
├─────────────────────────────────────┤
│    モジュール一覧（max 1000件）      │
│   (runtime含む, depth/usedExports等)│
├─────────────────────────────────────┤
│         チャンク一覧                 │
│   (chunkRelations/chunkOrigins)    │
├─────────────────────────────────────┤
│    エラー詳細（max 1000件）          │
│       (cause/errors含む)            │
├─────────────────────────────────────┤
│    警告詳細（max 1000件）            │
├─────────────────────────────────────┤
│         ロギング (log)               │
└─────────────────────────────────────┘
```

### ヘッダー部

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

### 明細部

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

### フッター部

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

## 出力条件

### 抽出条件

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

### ソート順

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

### 改ページ条件

該当なし（コンソール出力）。スペース制限1000件を超えるデータは省略表示される。

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

### 参照テーブル一覧

本帳票はデータベースを参照しない。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 -->|detailed| D[NAMED_PRESETS.detailed適用]
    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取得を行う |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 各セクション最大1000件 |
| 目標出力時間 | ビルド規模に依存（verboseより高速） |
| 同時出力数上限 | 1（ビルドごとに1回） |

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

detailedプリセットはファイルシステムのパス情報を含むため、出力結果を外部に公開する際はRequestShortenerによるパス短縮を確認すること。verboseと異なりenv情報は含まれないため、環境変数の漏洩リスクは低い。

## 備考

- verboseとの主な違い：chunkModules: false（verboseではtrue）、dependentModules未設定、orphanModules未設定、errorStack未設定、env未設定、children未設定、reasons未設定
- スペース制限が全て1000に設定されているため、大規模プロジェクトでもverboseほど出力量が膨大にならない
- logging: trueは「log」レベルに正規化される（NORMALIZERの行366-367）

---

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

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

### 推奨読解順序

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

detailedプリセットの設定とverboseとの差分を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | DefaultStatsPresetPlugin.js | `lib/stats/DefaultStatsPresetPlugin.js` | 行73-100: NAMED_PRESETS.detailedの全プロパティ定義を確認する |
| 1-2 | DefaultStatsPresetPlugin.js | `lib/stats/DefaultStatsPresetPlugin.js` | 行36-71: verboseプリセットとの差分を比較する |

**読解のコツ**: detailedにはverboseに存在する`modules`, `dependentModules`, `depth`(明示的), `env`, `reasons`, `errorStack`, `orphanModules`, `children`, `exclude`が存在しない。これらはDEFAULTSから補完される。

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

verboseプリセット（No.21）と同一のエントリーポイントである。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Stats.js | `lib/Stats.js` | 行57-86: toJson()/toString()メソッド |

**主要処理フロー**:
1. **行58**: `createStatsOptions("detailed", { forToString: false/true })` でオプションを正規化
2. **行62-64**: StatsFactoryによるデータ抽出

#### Step 3: プリセット適用と正規化を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | DefaultStatsPresetPlugin.js | `lib/stats/DefaultStatsPresetPlugin.js` | 行388-396: statsPresetフック - applyDefaults(options, NAMED_PRESETS.detailed)の呼び出し |
| 3-2 | DefaultStatsPresetPlugin.js | `lib/stats/DefaultStatsPresetPlugin.js` | 行365-367: NORMALIZERのlogging変換 - trueを"log"に変換する処理 |

**主要処理フロー**:
- **行366**: `if (value === true) value = "log"` - logging: trueが"log"レベルに変換される

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

```
Stats.toString("detailed") / Stats.toJson("detailed")
    |
    +-- Compilation.createStatsOptions("detailed", context)
    |       |
    |       +-- compilation.hooks.statsPreset.for("detailed").call(options)
    |       |       |
    |       |       +-- applyDefaults(options, NAMED_PRESETS.detailed)
    |       |
    |       +-- compilation.hooks.statsNormalize.call(options, context)
    |               |
    |               +-- DEFAULTS適用（未設定項目の補完）
    |               +-- NORMALIZER適用（logging: true -> "log"）
    |
    +-- StatsFactory.create("compilation", compilation, context)
    |
    +-- [toStringの場合] StatsPrinter.print("compilation", data)
```

### データフロー図

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

webpack.config.js          DefaultStatsPresetPlugin            コンソール/JSON
  stats: "detailed"  --->    statsPresetフック             ---> Stats テキスト/JSON
                               |                                (スペース制限
                          applyDefaults()                         1000件適用)
                               |
                          logging: true -> "log" 変換
                               |
Compilation              StatsFactory.create()
  .modules          --->   extractフック               ---> StatsCompilation
  .chunks                   |
  .assets                filter/sort/group
  .errors                (Space=1000制限)
  .warnings
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| 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フック実装 |
