# 帳票設計書 1-Stats JSON レポート

## 概要

本ドキュメントは、webpackのビルド結果統計情報をJSON形式で出力する「Stats JSON レポート」の設計仕様を定義する。

### 本帳票の処理概要

Stats JSON レポートは、webpackのビルド（コンパイル）結果に関する統計情報を構造化されたJSONオブジェクトとして出力する帳票である。`Stats.toJson()` メソッドを呼び出すことで、モジュール、チャンク、アセット、エラー、警告、エントリーポイント、チャンクグループ、ロギング情報など、ビルドプロセスのあらゆる詳細情報を包括的に取得できる。

**業務上の目的・背景**：webpackのビルド結果を機械可読な形式で取得し、CI/CDパイプラインでのビルド品質監視、バンドルサイズの追跡、ビルドパフォーマンスの分析、カスタムレポートツールとの連携を可能にするために必要である。テキスト出力では困難なプログラムによるデータ解析を実現する。

**帳票の利用シーン**：CI/CDパイプラインでのビルド結果の自動解析、webpack-bundle-analyzerなどのサードパーティツールへのデータ提供、ビルドパフォーマンスのダッシュボード構築、カスタムビルドレポートの生成時に利用される。

**主要な出力内容**：
1. ビルドメタ情報（バージョン、ハッシュ、ビルド時間、publicPath、outputPath）
2. アセット情報（ファイル名、サイズ、チャンク関連、emitted状態）
3. モジュール情報（識別子、名前、サイズ、依存関係、キャッシュ状態）
4. チャンク情報（ID、名前、サイズ、含有モジュール、初期/非同期区分）
5. エントリーポイント・チャンクグループ情報
6. エラー・警告情報（メッセージ、モジュール、位置、スタックトレース）
7. ロギング情報（ログレベル、メッセージ、時間、トレース）

**帳票の出力タイミング**：ビルド完了後、`Stats.toJson(options)` メソッドの呼び出し時に生成される。webpack CLIの `--json` フラグ指定時、またはNode.js APIで `stats.toJson()` を呼び出した際に出力される。

**帳票の利用者**：フロントエンド開発者、DevOpsエンジニア、CI/CDパイプライン、バンドル分析ツール、ビルド監視システム。

## 帳票種別

構造化データ出力（JSON）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | CLI | `webpack --json` | `--json` フラグ指定 |
| - | Node.js API | プログラム内呼び出し | `stats.toJson(options)` メソッド呼び出し |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | JSON |
| 用紙サイズ | N/A（データ出力） |
| 向き | N/A |
| ファイル名 | 任意（CLIでは標準出力、APIではオブジェクト返却） |
| 出力方法 | 標準出力 / オブジェクト返却 |
| 文字コード | UTF-8 |

## 帳票レイアウト

### レイアウト概要

StatsCompilation型のJSONオブジェクトとして出力される。トップレベルのキーにビルド情報の各カテゴリが格納される。

```
{
    "name":           コンパイル名（オプション）,
    "hash":           ビルドハッシュ,
    "version":        webpackバージョン,
    "time":           ビルド所要時間(ms),
    "builtAt":        ビルド完了タイムスタンプ,
    "publicPath":     公開パス,
    "outputPath":     出力パス,
    "assetsByChunkName": チャンク名→アセット名マッピング,
    "assets":         アセット一覧,
    "chunks":         チャンク一覧,
    "modules":        モジュール一覧,
    "entrypoints":    エントリーポイント,
    "namedChunkGroups": 名前付きチャンクグループ,
    "errors":         エラー一覧,
    "errorsCount":    エラー総数,
    "warnings":       警告一覧,
    "warningsCount":  警告総数,
    "children":       子コンパイル,
    "logging":        ロギング情報
}
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | name | コンパイル名 | compilation.name | 文字列 |
| 2 | hash | ビルドハッシュ | compilation.hash | 文字列 |
| 3 | version | webpackバージョン | package.json.version | 文字列（例: "5.x.x"） |
| 4 | time | ビルド所要時間 | compilation.endTime - compilation.startTime | 数値（ミリ秒） |
| 5 | builtAt | ビルド完了時刻 | compilation.endTime | 数値（UNIXタイムスタンプ） |
| 6 | publicPath | 公開パス | compilation.outputOptions.publicPath | 文字列 |
| 7 | outputPath | 出力パス | compilation.outputOptions.path | 文字列 |
| 8 | needAdditionalPass | 追加パス要否 | compilation.needAdditionalPass | 真偽値 |
| 9 | env | 環境変数 | options._env | オブジェクト |

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|-----|
| 1 | assets | アセット一覧 | compilation.getAssets() | StatsAsset[] | - |
| 2 | assetsByChunkName | チャンク名別アセット | compilationFileToChunks | Record<string, string[]> | - |
| 3 | chunks | チャンク一覧 | compilation.chunks | StatsChunk[] | - |
| 4 | modules | モジュール一覧 | compilation.modules | StatsModule[] | - |
| 5 | entrypoints | エントリーポイント | compilation.entrypoints | Record<string, StatsChunkGroup> | - |
| 6 | namedChunkGroups | 名前付きチャンクグループ | compilation.namedChunkGroups | Record<string, StatsChunkGroup> | - |
| 7 | errors | エラー一覧 | compilation.getErrors() | StatsError[] | - |
| 8 | warnings | 警告一覧 | compilation.getWarnings() | StatsError[] | - |
| 9 | children | 子コンパイル | compilation.children | StatsCompilation[] | - |
| 10 | logging | ロギング情報 | compilation.logging | Record<string, StatsLogging> | - |

### フッター部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | errorsCount | エラー総数（子含む） | countWithChildren() | 数値 |
| 2 | warningsCount | 警告総数（子含む） | countWithChildren() | 数値 |
| 3 | filteredModules | フィルタ済みモジュール数 | spaceLimited() | 数値 |
| 4 | filteredAssets | フィルタ済みアセット数 | spaceLimited() | 数値 |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| StatsOptions | stats設定オブジェクト。出力する情報の範囲を制御する | No（デフォルト値あり） |
| forToString | false固定（JSON出力時） | Yes（内部設定） |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | modules: depth | 昇順 |
| 2 | modules: preOrderIndex | 昇順 |
| 3 | modules: identifier | 昇順 |
| 4 | chunks: id | 昇順 |

### 改ページ条件

N/A（JSONデータ出力のため改ページなし）

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

### 参照テーブル一覧

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

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

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

#### Compilation

| 参照項目（カラム名） | 帳票項目との対応 | 取得条件 | 備考 |
|-------------------|----------------|---------|------|
| hash | hash | - | ビルドハッシュ |
| startTime / endTime | time | endTime - startTime | ビルド所要時間を算出 |
| modules | modules | - | Set<Module> |
| chunks | chunks | - | Set<Chunk> |
| entrypoints | entrypoints | - | Map<string, ChunkGroup> |
| errors | errors | - | WebpackError[] |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| time | compilation.endTime - compilation.startTime | なし | ミリ秒単位 |
| errorsCount | countWithChildren(compilation, getErrors) | なし | 子コンパイルを再帰的にカウント |
| warningsCount | countWithChildren(compilation, getWarnings) | なし | 子コンパイルを再帰的にカウント |
| module.size | module.size() | なし | バイト単位 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[Stats.toJson呼び出し] --> B[createStatsOptions でオプション正規化]
    B --> C[createStatsFactory でStatsFactory生成]
    C --> D[statsFactory.create compilation実行]
    D --> E[SIMPLE_EXTRACTORS.compilation で各フィールド抽出]
    E --> F{配列データ?}
    F -->|Yes| G[filter → sort → filterSorted → map → sortResults → groupResults → filterResults → merge]
    F -->|No| H[extract → result]
    G --> I[StatsCompilation JSONオブジェクト返却]
    H --> I
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| データなし | compilation が undefined | TypeError | ビルド完了後に呼び出すこと |
| オプション不正 | 不正なstatsオプション | 内部でデフォルト値にフォールバック | 正しいStatsOptions形式で指定 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | モジュール数千〜数万、チャンク数十〜数百 |
| 目標出力時間 | ビルド規模に依存（通常数百ミリ秒以内） |
| 同時出力数上限 | 1（シングルスレッド処理） |

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

JSON出力にはファイルシステムの絶対パスが含まれる可能性がある。`makePathsRelative` によりパスの相対化が行われるが、`requestShortener` の設定に依存する。公開環境ではソースパス情報の漏洩に注意が必要。

## 備考

- StatsOptionsにより出力項目を細かく制御可能（例: `modules: false` でモジュール情報を除外）
- `spaceLimited` 関数により、大量データの場合は表示件数が制限され `filteredModules` / `filteredAssets` にフィルタ数が記録される
- 子コンパイル（`compilation.children`）がある場合、再帰的にデータが収集される

---

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

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

### 推奨読解順序

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

まず、Stats JSON レポートの出力データ構造を定義する型定義を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | DefaultStatsFactoryPlugin.js | `lib/stats/DefaultStatsFactoryPlugin.js` | 行66-312: `KnownStatsCompilation`, `KnownStatsAsset`, `KnownStatsModule`, `KnownStatsChunk`, `KnownStatsError` 等のJSDoc型定義を読み、出力JSONの構造を把握する |

**読解のコツ**: JSDocの `@typedef` で定義される型がそのまま出力JSONのスキーマとなる。`KnownStatsCompilation`（行68-94）がトップレベル構造。

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

処理の起点となる `Stats` クラスの `toJson()` メソッドを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Stats.js | `lib/Stats.js` | 行57-67: `toJson()` メソッドがStatsFactoryを生成し、`create("compilation", ...)` を呼び出す流れ |

**主要処理フロー**:
1. **行58-60**: `createStatsOptions` でオプションを正規化（`forToString: false`）
2. **行62**: `createStatsFactory` でStatsFactoryインスタンスを生成
3. **行64-66**: `statsFactory.create("compilation", this.compilation, ...)` で JSON生成を開始

#### Step 3: StatsFactory のデータ生成パイプラインを理解する

StatsFactoryの `create` / `_create` メソッドがデータ変換パイプラインの中核。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | StatsFactory.js | `lib/stats/StatsFactory.js` | 行235-403: `create` メソッドと `_create` メソッド。配列データとオブジェクトデータで処理が分岐する |

**主要処理フロー**:
- **行259-264**: コンテキスト生成
- **行265-386**: 配列データの場合: filter → sort → filterSorted → map(再帰) → sortResults → groupResults → filterResults → merge → result
- **行387-402**: オブジェクトデータの場合: extract → result

#### Step 4: DefaultStatsFactoryPlugin のデータ抽出ロジックを理解する

実際のデータ抽出処理を行う `SIMPLE_EXTRACTORS` オブジェクトを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | DefaultStatsFactoryPlugin.js | `lib/stats/DefaultStatsFactoryPlugin.js` | 行549-1026: `SIMPLE_EXTRACTORS.compilation` セクションで、compilation オブジェクトからJSON出力用データを抽出する各フィールドの処理を読む |

**主要処理フロー**:
- **行551-728**: `compilation._` - 基本的なメタ情報抽出（名前、ロギング）
- **行729-731**: `compilation.hash` - ハッシュ抽出
- **行732-734**: `compilation.version` - バージョン抽出
- **行738-742**: `compilation.timings` - ビルド時間算出
- **行754-843**: `compilation.assets` - アセット情報抽出
- **行844-851**: `compilation.chunks` - チャンク情報抽出
- **行852-859**: `compilation.modules` - モジュール情報抽出
- **行910-942**: `compilation.errors` - エラー情報抽出
- **行948-979**: `compilation.warnings` - 警告情報抽出

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

```
Stats.toJson(options)
    |
    +-- compilation.createStatsOptions(options, { forToString: false })
    |
    +-- compilation.createStatsFactory(normalizedOptions)
    |
    +-- statsFactory.create("compilation", compilation, context)
            |
            +-- SIMPLE_EXTRACTORS.compilation._()
            |       +-- makePathsRelative / cachedGetErrors / cachedGetWarnings 初期化
            |       +-- ロギング情報抽出
            |
            +-- SIMPLE_EXTRACTORS.compilation.hash()
            +-- SIMPLE_EXTRACTORS.compilation.version()
            +-- SIMPLE_EXTRACTORS.compilation.timings()
            +-- SIMPLE_EXTRACTORS.compilation.builtAt()
            +-- SIMPLE_EXTRACTORS.compilation.publicPath()
            +-- SIMPLE_EXTRACTORS.compilation.outputPath()
            |
            +-- SIMPLE_EXTRACTORS.compilation.assets()
            |       +-- factory.create("compilation.assets", [...assets], context)
            |           +-- SIMPLE_EXTRACTORS.asset._()
            |           +-- SIMPLE_EXTRACTORS.asset$visible._()
            |
            +-- SIMPLE_EXTRACTORS.compilation.modules()
            |       +-- factory.create("compilation.modules", array, context)
            |           +-- SIMPLE_EXTRACTORS.module._()
            |           +-- SIMPLE_EXTRACTORS.module$visible._()
            |
            +-- SIMPLE_EXTRACTORS.compilation.chunks()
            |       +-- factory.create("compilation.chunks", [...chunks], context)
            |           +-- SIMPLE_EXTRACTORS.chunk._()
            |
            +-- SIMPLE_EXTRACTORS.compilation.entrypoints()
            +-- SIMPLE_EXTRACTORS.compilation.chunkGroups()
            +-- SIMPLE_EXTRACTORS.compilation.errors()
            +-- SIMPLE_EXTRACTORS.compilation.warnings()
            +-- SIMPLE_EXTRACTORS.compilation.children()
```

### データフロー図

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

Compilation        -->  Stats.toJson()                  -->  StatsCompilation (JSON)
  .modules         -->    StatsFactory.create()         -->    .modules[]
  .chunks          -->    SIMPLE_EXTRACTORS.compilation  -->    .chunks[]
  .entrypoints     -->    SIMPLE_EXTRACTORS.asset       -->    .assets[]
  .getAssets()     -->    SIMPLE_EXTRACTORS.module      -->    .entrypoints{}
  .getErrors()     -->    SIMPLE_EXTRACTORS.chunk       -->    .errors[]
  .getWarnings()   -->    SIMPLE_EXTRACTORS.chunkGroup  -->    .warnings[]
  .logging         -->    EXTRACT_ERROR                 -->    .logging{}
  .children        -->    spaceLimited()                -->    .children[]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Stats.js | `lib/Stats.js` | ソース | エントリーポイント。toJson() / toString() メソッドを提供 |
| StatsFactory.js | `lib/stats/StatsFactory.js` | ソース | データ変換パイプラインを管理するファクトリクラス |
| DefaultStatsFactoryPlugin.js | `lib/stats/DefaultStatsFactoryPlugin.js` | ソース | データ抽出ロジック（SIMPLE_EXTRACTORS, EXTRACT_ERROR）を定義 |
| StatsPrinter.js | `lib/stats/StatsPrinter.js` | ソース | テキスト出力用プリンター（JSON出力では間接的に関連） |
| DefaultStatsPrinterPlugin.js | `lib/stats/DefaultStatsPrinterPlugin.js` | ソース | テキスト出力用フォーマット定義 |
| Compilation.js | `lib/Compilation.js` | ソース | ビルド結果を保持するコンパイルオブジェクト |
| DefaultStatsPresetPlugin.js | `lib/stats/DefaultStatsPresetPlugin.js` | ソース | Stats出力プリセット定義（verbose, detailed, minimal等） |
