# 機能設計書 56-統計プリセット

## 概要

本ドキュメントは、webpackにおける統計プリセット機能（DefaultStatsPresetPlugin）の設計仕様を記述する。'errors-only'、'minimal'、'normal'、'verbose'等の名前付きプリセットを提供し、統計出力オプションのデフォルト値適用と正規化を行う機能である。

### 本機能の処理概要

**業務上の目的・背景**：webpackの統計出力オプションは50以上の個別設定項目を持つが、開発者が全項目を個別設定するのは煩雑である。統計プリセット機能は、ユースケースに応じた名前付きプリセット（'errors-only', 'minimal', 'normal', 'verbose'等）を提供し、一つの文字列指定で適切なデフォルト値群を適用する。さらに、個別設定値の正規化（型変換、デフォルト値補完）も担当する。

**機能の利用シーン**：webpack設定ファイルでの`stats: 'errors-only'`等の指定、webpack-dev-serverの`stats`オプション、CLI実行時の統計出力レベル制御に利用される。

**主要な処理内容**：
1. 名前付きプリセット（verbose, detailed, minimal, errors-only, errors-warnings, summary, none）を定義する
2. compilation.hooks.statsPresetフックで、プリセット名に基づくデフォルト値を適用する
3. compilation.hooks.statsNormalizeフックで、未設定項目へのデフォルト値適用と値の正規化を行う
4. forToString（文字列出力向け）かどうかに応じてデフォルト値を切り替える
5. excludeModules, warningsFilter等のフィルタ値を正規化する

**関連システム・外部連携**：Compilation.createStatsOptions()から呼び出され、StatsFactory/StatsPrinterの動作を制御する。

**権限による制御**：特になし。webpack設定のstatsオプションで制御する。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本機能はUIを持たない内部処理であり、直接関連する画面は存在しない |

## 機能種別

構成管理 / オプション正規化

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| preset | string | No | プリセット名（"verbose", "minimal", "errors-only"等） | NAMED_PRESETSに存在するキー |
| options | NormalizedStatsOptions | Yes | 正規化前の統計オプション | - |
| context | CreateStatsOptionsContext | Yes | forToString等のコンテキスト | - |

### 入力データソース

- webpack設定のstatsフィールド: プリセット名または個別オプションオブジェクト
- CreateStatsOptionsContext: forToString（文字列出力向けか）等のコンテキスト情報

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| options | NormalizedStatsOptions | デフォルト値適用・正規化済みの統計オプション |

### 出力先

NormalizedStatsOptionsオブジェクトとして、StatsFactory/StatsPrinterに渡される

## 処理フロー

### 処理シーケンス

```
1. compilation.hooks.statsPreset.for(presetName) 発火
   └─ プリセット名に対応するデフォルト値セットを適用
2. compilation.hooks.statsNormalize 発火
   └─ 未設定項目にDEFAULTSの値を適用
3. NORMALIZER適用
   └─ excludeModules, excludeAssets, warningsFilter, logging, loggingDebug等を正規化
```

### フローチャート

```mermaid
flowchart TD
    A[stats設定取得] --> B{プリセット名指定?}
    B -->|Yes| C[statsPresetフックで該当プリセットのデフォルト適用]
    B -->|No| D[個別設定値をそのまま使用]
    C --> E[statsNormalizeフック]
    D --> E
    E --> F[未設定項目にDEFAULTS適用]
    F --> G{forToString?}
    G -->|Yes| H[文字列出力向けデフォルト]
    G -->|No| I[JSON出力向けデフォルト]
    H --> J[NORMALIZER適用]
    I --> J
    J --> K[正規化済みオプション返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-56-01 | プリセットverbose | hash, builtAt, entrypoints, chunks, chunkRelations, depth, reasons等を全表示。Space系は全てInfinity | stats: "verbose" |
| BR-56-02 | プリセットminimal | all:false, version, timings, modules, assets, errors, warnings, warningsCountのみ表示。Space系は0 | stats: "minimal" |
| BR-56-03 | プリセットerrors-only | all:false, errors, errorsCount, moduleTraceのみ表示。errorsSpaceはInfinity | stats: "errors-only" |
| BR-56-04 | プリセットnone | all:falseで全て非表示 | stats: "none" |
| BR-56-05 | forToString分岐 | 文字列出力(toString)とJSON出力(toJson)でデフォルト値を切り替える | ON_FOR_TO_STRING, OFF_FOR_TO_STRING, AUTO_FOR_TO_STRING |
| BR-56-06 | allオプション | all:falseで全項目無効、all:trueで全項目有効 | NORMAL_ON, NORMAL_OFF |
| BR-56-07 | modulesとchunkModulesの排他 | forToString時にchunksとchunkModulesがtrueの場合、modulesはfalseにする | DEFAULTS.modules |
| BR-56-08 | Space系デフォルト | forToString時はmodulesSpace:15, assetsSpace:15等の制限。JSON出力時はInfinity | DEFAULTSの各Space項目 |

### 計算ロジック

デフォルト値適用: 各オプションに対して`DEFAULTS[key](options, context, compilation)`を呼び出し、返却値をデフォルト値とする。NORMAL_ON = `all !== false`、NORMAL_OFF = `all === true`、ON_FOR_TO_STRING = `forToString ? all !== false : all === true`。

## データベース操作仕様

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | 本機能はデータベースを使用しない |

### テーブル別操作詳細

該当なし（インメモリ処理のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Error | warningsFilterに不正な型が渡された場合 | "Can only filter warnings with Strings or RegExps"エラーをスロー |

### リトライ仕様

該当なし。

## トランザクション仕様

該当なし（同期的なインメモリ処理）

## パフォーマンス要件

- プリセット適用と正規化は軽量なオプション操作であり、パフォーマンスへの影響は無視できる

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

特になし。

## 備考

- 7種類のプリセット: verbose, detailed, minimal, errors-only, errors-warnings, summary, none
- `stats: true`は"normal"プリセット相当、`stats: false`は"none"プリセット相当
- DEFAULTS定義は50項目以上で、forToStringに応じた条件分岐を持つ

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | DefaultStatsPresetPlugin.js | `lib/stats/DefaultStatsPresetPlugin.js` | NAMED_PRESETSの定義と各プリセットの設定値を確認する |

**読解のコツ**: NAMED_PRESETS→DEFAULTS→NORMALIZERの3段階で理解するのが効率的。まずプリセットの概要を掴み、次にデフォルト値の条件分岐を理解し、最後にフィルタ値の正規化を確認する。

- **36-44行目**: NAMED_PRESETS型定義
- **37-72行目**: verboseプリセット - hash, builtAt, entrypoints, chunks, depth, reasons等をtrue
- **73-100行目**: detailedプリセット - verboseより限定的
- **101-116行目**: minimalプリセット - all:false基本、version, timings, modules, errorsのみ
- **117-124行目**: errors-onlyプリセット - all:false基本、errors, errorsCount, moduleTraceのみ
- **125-134行目**: errors-warningsプリセット
- **135-140行目**: summaryプリセット - version, errorsCount, warningsCountのみ
- **141-143行目**: noneプリセット - all:false

#### Step 2: デフォルト値とforToString分岐

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | DefaultStatsPresetPlugin.js | `lib/stats/DefaultStatsPresetPlugin.js` | DEFAULTS定義とforToString分岐ロジック |

**主要処理フロー**:
- **150行目**: NORMAL_ON = `({all}) => all !== false`
- **155行目**: NORMAL_OFF = `({all}) => all === true`
- **161-162行目**: ON_FOR_TO_STRING = forToString ? all !== false : all === true
- **168-169行目**: OFF_FOR_TO_STRING = forToString ? all === true : all !== false
- **186-285行目**: DEFAULTSオブジェクト - 50+項目のデフォルト値定義
- **232-234行目**: modulesSpace, chunkModulesSpace - forToStringで15/10, それ以外はInfinity

#### Step 3: 正規化ロジック

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | DefaultStatsPresetPlugin.js | `lib/stats/DefaultStatsPresetPlugin.js` | NORMALIZERとapplyメソッド |

**主要処理フロー**:
- **297-312行目**: normalizeFilter関数 - 文字列/正規表現/関数/booleanをフィルタ関数に変換
- **325-377行目**: NORMALIZERオブジェクト - excludeModules, excludeAssets, warningsFilter, logging, loggingDebugの正規化
- **381-415行目**: applyメソッド - statsPresetフックとstatsNormalizeフックへのタップ

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

```
Compilation.createStatsOptions()
    │
    ├─ compilation.hooks.statsPreset.for(presetName)
    │      └─ DefaultStatsPresetPlugin
    │             └─ applyDefaults(options, NAMED_PRESETS[key])
    │
    └─ compilation.hooks.statsNormalize
           └─ DefaultStatsPresetPlugin
                  ├─ DEFAULTS[key](options, context, compilation) 適用
                  └─ NORMALIZER[key](options[key]) 正規化
```

### データフロー図

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

stats: "errors-only" ──────▶ statsPresetフック                     NormalizedStatsOptions
                               └─ NAMED_PRESETS["errors-only"]     ├─ errors: true
                                  適用                              ├─ errorsCount: true
                                                                    ├─ errorsSpace: Infinity
                              statsNormalizeフック                   ├─ moduleTrace: true
                               ├─ DEFAULTS適用                      └─ all: false
                               │   └─ forToString分岐
                               └─ NORMALIZER適用
                                   └─ フィルタ値正規化
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| DefaultStatsPresetPlugin.js | `lib/stats/DefaultStatsPresetPlugin.js` | ソース | プリセット定義・デフォルト適用・正規化 |
| StatsFactory.js | `lib/stats/StatsFactory.js` | ソース | 正規化済みオプションを使用する統計ファクトリ |
| StatsPrinter.js | `lib/stats/StatsPrinter.js` | ソース | 正規化済みオプションを使用する統計プリンタ |
| RequestShortener.js | `lib/RequestShortener.js` | ソース | requestShortenerのデフォルト値生成で使用 |
