# 帳票設計書 12-Stats ロギングレポート

## 概要

本ドキュメントは、webpackビルド中のログエントリ（ログレベル・メッセージ・時間・トレース等）を構造化して出力する「Stats ロギングレポート」の設計仕様を定義するものである。

### 本帳票の処理概要

Stats ロギングレポートは、webpackビルドプロセス中にプラグインやローダーが出力したログメッセージを収集・構造化して出力する帳票である。ログはオリジン（出力元）ごとにグループ化され、ログレベル（error / warn / info / log / debug等）によるフィルタリング、グループのネスト構造の展開/折りたたみ、時間計測エントリのフォーマットなどの加工処理を経て出力される。

**業務上の目的・背景**：ビルドプロセスの透明性を確保し、プラグインやローダーが出力する診断情報・デバッグ情報を統一的に参照可能にするために本帳票が必要である。特に、ビルドの問題調査やプラグイン開発時のデバッグに不可欠な情報源となる。

**帳票の利用シーン**：ビルドの問題調査、プラグインの動作確認、パフォーマンス分析時に利用される。`stats.toJson({ logging: 'verbose' })` のようにloggingオプションを指定したビルド実行後に出力される。

**主要な出力内容**：
1. ログエントリ一覧（タイプ・メッセージ・トレース・子エントリ・引数・時間）
2. オリジン（ログ出力元）ごとのグループ化
3. フィルタリングされたエントリ数
4. デバッグモードフラグ

**帳票の出力タイミング**：webpackビルド完了後、`Stats.toJson()` または `Stats.toString()` が呼び出された際に、`logging` オプションが有効な場合に出力される。

**帳票の利用者**：フロントエンド開発者、プラグイン開発者、ビルドエンジニア。

## 帳票種別

統計レポート（ビルドログ集約用）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | CLI / API | `webpack --stats-logging verbose` | ビルドコマンド実行 |
| - | Node.js API | `stats.toJson({ logging: 'verbose' })` | API呼び出し |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | JSON（Stats JSONの一部） |
| 用紙サイズ | N/A（データ出力） |
| 向き | N/A |
| ファイル名 | stats.json（Stats JSON全体の一部として出力） |
| 出力方法 | 標準出力 / ファイル出力 / API戻り値 |
| 文字コード | UTF-8 |

## 帳票レイアウト

### レイアウト概要

Stats ロギングレポートは、Stats JSONの `logging` プロパティとして出力される。オリジンごとにキーが設定され、各オリジンに対してログエントリの配列とメタ情報が格納される。

```
StatsCompilation
└── logging: Record<string, StatsLogging>
    └── [origin名]
        ├── entries: StatsLoggingEntry[]
        │   ├── type: string
        │   ├── message: string
        │   ├── trace: string[]
        │   ├── children: StatsLoggingEntry[]
        │   ├── args: any[]
        │   └── time: number
        ├── filteredEntries: number
        └── debug: boolean
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | オリジン名 | ログの出力元名称（プラグイン名等） | compilation.logging のキー | 文字列（相対パス化済み） |

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|-----|
| 1 | type | ログエントリの種別 | LogType（error/warn/info/log/debug/trace/group/groupCollapsed/groupEnd/profile/profileEnd/time/clear/status） | 文字列 | - |
| 2 | message | ログメッセージ | util.format()でフォーマットされた文字列、time型の場合は `label: xxx ms` 形式 | 文字列 | - |
| 3 | trace | スタックトレース | entry.trace | 文字列配列 | - |
| 4 | children | 子ログエントリ（グループの場合） | group/groupCollapsed時に生成 | StatsLoggingEntry[] | - |
| 5 | args | ログ引数 | entry.args | any[] | - |
| 6 | time | タイムスタンプ | entry.time | 数値 | - |

### フッター部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | filteredEntries | フィルタリングされたエントリ数 | logEntries.length - processedLogEntries | 数値 |
| 2 | debug | デバッグモードフラグ | loggingDebug マッチ結果 | boolean |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| loggingオプション | Stats オプションの `logging` が false 以外であること（error/warn/info/log/verbose のいずれか） | Yes |
| loggingDebugオプション | 特定オリジンのデバッグモードを有効にするフィルタ関数配列 | No |
| loggingTraceオプション | トレース情報を含めるかどうか | No |

### ソート順

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

### 改ページ条件

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

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

### 参照テーブル一覧

本帳票はデータベースを参照せず、webpackの内部データ構造を参照する。

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| compilation.logging（Map） | ビルド中に蓄積されたログエントリの格納先 | Map<string, LogEntry[]> |
| WebpackLogger（内部クラス） | ログ出力API | compilation.getLogger() |

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

#### compilation.logging

| 参照項目 | 帳票項目との対応 | 取得条件 | 備考 |
|---------|----------------|---------|------|
| origin（Mapキー） | オリジン名 | - | makePathsRelative で相対化 |
| logEntries（Map値） | entries | loggingオプションによるフィルタ | LogType に基づくフィルタリング |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| filteredEntries | logEntries.length - processedLogEntries | なし | フィルタされたエントリ数 |
| message（time型） | `${label}: ${first * 1000 + second / 1000000} ms` | なし | process.hrtime の秒・ナノ秒をミリ秒に変換 |
| message（その他） | util.format(args[0], ...args.slice(1)) | なし | Node.js のフォーマット関数 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[Stats.toJson 呼び出し] --> B[compilation extractor]
    B --> C{logging/loggingDebug 有効?}
    C -->|No| Z[logging なしで出力]
    C -->|Yes| D[logging レベルに応じた acceptedTypes 決定]
    D --> E[compilation.logging イテレーション]
    E --> F[各 origin について]
    F --> G{debugMode or acceptedTypes にマッチ?}
    G -->|No| F
    G -->|Yes| H[ログエントリ処理]
    H --> I{type が groupEnd?}
    I -->|Yes| J[グループスタックから pop]
    I -->|No| K{type が time?}
    K -->|Yes| L[時間フォーマット変換]
    K -->|No| M[util.format でメッセージ生成]
    L --> N[newEntry 生成]
    M --> N
    N --> O{type が group/groupCollapsed?}
    O -->|Yes| P[グループスタックに push, children 配列設定]
    O -->|No| Q[currentList に追加]
    P --> Q
    J --> F
    Q --> F
    F --> R[origin名を相対化して logging に格納]
    R --> S[出力完了]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| ログなし | compilation.logging が空 | エラーは発生せず logging が空オブジェクトとなる | 正常動作 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | プラグイン・ローダー数に依存（数十〜数千エントリ） |
| 目標出力時間 | Stats全体の出力に含まれる |
| 同時出力数上限 | N/A |

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

ログメッセージにファイルパスや内部構造情報が含まれる場合があるため、外部公開時は注意が必要。`makePathsRelative` によりオリジン名は相対パスに変換される。

## 備考

- loggingオプションの各レベルで含まれるLogTypeは以下の通り：
  - `error`: error
  - `warn`: error, warn
  - `info`: error, warn, info
  - `log`: error, warn, info, log, group, groupEnd, groupCollapsed, clear
  - `verbose`: error, warn, info, log, group, groupEnd, groupCollapsed, profile, profileEnd, time, status, clear
- `verbose` レベルでは `collapsedGroups` が true となり、groupCollapsed が group として展開される。
- 同名オリジンが存在する場合、`name#1`, `name#2` のように連番が付与される。

---

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

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

### 推奨読解順序

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

ログエントリのデータ構造と、出力データ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Logger.js | `lib/logging/Logger.js` | LogType 定義（8-28行目）。ログの種別一覧を確認 |
| 1-2 | Logger.js | `lib/logging/Logger.js` | WebpackLogger クラス（43-221行目）。ログ出力API（error, warn, info, log, debug, group等） |
| 1-3 | DefaultStatsFactoryPlugin.js | `lib/stats/DefaultStatsFactoryPlugin.js` | KnownStatsLogging 型定義（98-102行目）、KnownStatsLoggingEntry 型定義（105-113行目） |

**読解のコツ**: LogType はフリーズされたオブジェクトで、キーと値が同一文字列。WebpackLogger は LOG_SYMBOL を使ってプライベートなログ関数を呼び出す設計。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Stats.js | `lib/Stats.js` | toJson() メソッド（57-67行目）が Stats 出力のエントリーポイント |

**主要処理フロー**:
1. **57行目**: `toJson(options)` - Stats出力オプションの正規化
2. **64行目**: `statsFactory.create("compilation", ...)` - compilation全体のStats生成開始

#### Step 3: ロギングデータの抽出・変換

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | DefaultStatsFactoryPlugin.js | `lib/stats/DefaultStatsFactoryPlugin.js` | compilation extractor のlogging処理（585-727行目） |

**主要処理フロー**:
- **585-586行目**: logging, loggingDebug, loggingTrace オプション取得
- **593-639行目**: ログレベルに応じた acceptedTypes の決定（switch文）
- **645-646行目**: `compilation.logging` のイテレーションとデバッグモード判定
- **654-711行目**: 各ログエントリの処理（グループ管理、メッセージフォーマット）
- **683-687行目**: time型エントリのミリ秒変換フォーマット
- **688-689行目**: util.format による一般メッセージ生成
- **713-719行目**: 同名オリジンの連番付与処理
- **721-725行目**: StatsLogging オブジェクトの生成と格納

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

```
Stats.toJson()
    │
    └─ StatsFactory.create("compilation", compilation)
           │
           └─ compilation extractor (logging処理)
                  │
                  ├─ logging レベル判定 → acceptedTypes 生成
                  │
                  ├─ compilation.logging イテレーション
                  │      │
                  │      ├─ loggingDebug によるデバッグモード判定
                  │      │
                  │      ├─ 各 logEntry の処理
                  │      │      ├─ LogType フィルタリング
                  │      │      ├─ groupCollapsed → group 展開（verbose時）
                  │      │      ├─ time型: ミリ秒変換
                  │      │      └─ その他: util.format
                  │      │
                  │      └─ origin 名の相対化・重複処理
                  │
                  └─ StatsLogging オブジェクト生成
```

### データフロー図

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

compilation.logging          DefaultStatsFactoryPlugin           StatsLogging (JSON)
(Map<string, LogEntry[]>)    compilation extractor               (entries[],
       │                     ────────────────────▶                filteredEntries,
       │                     ログレベルフィルタリング              debug)
       │                     + メッセージフォーマット
       │                     + グループ構造化
       │
WebpackLogger
(error/warn/info/
 log/debug/group 等)
       │
       └─▶ compilation.logging に蓄積
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Logger.js | `lib/logging/Logger.js` | ソース | LogType定義とWebpackLoggerクラス |
| Stats.js | `lib/Stats.js` | ソース | Stats出力のエントリーポイント |
| DefaultStatsFactoryPlugin.js | `lib/stats/DefaultStatsFactoryPlugin.js` | ソース | ロギングデータの抽出・変換ロジック |
| StatsFactory.js | `lib/stats/StatsFactory.js` | ソース | Stats生成のファクトリクラス |
| Compilation.js | `lib/Compilation.js` | ソース | compilation.loggingの保持・getLogger()の提供 |
