# 帳票設計書 5-Stats 警告レポート

## 概要

本ドキュメントは、webpackビルド時の警告情報を構造化して出力する「Stats 警告レポート」の設計仕様を定義する。

### 本帳票の処理概要

Stats 警告レポートは、ビルド時に発生した警告情報を構造化して出力する帳票である。エラーレポート（No.4）と同一のデータ構造（`EXTRACT_ERROR`）を使用し、`SIMPLE_EXTRACTORS.compilation.warnings` により生成される。warningsFilterによるフィルタリング機能を持つ点がエラーレポートとの主な差異である。

**業務上の目的・背景**：ビルド時の警告を開発者に通知し、コード品質やパフォーマンスの潜在的な問題を早期に検出するために必要である。非推奨APIの使用、未解決のimport、パフォーマンス上限超過などの警告を提供する。

**帳票の利用シーン**：ビルド完了時の警告確認、CIパイプラインでの品質チェック、コードレビュー時の参照情報として利用される。

**主要な出力内容**：
1. 警告メッセージ（message）
2. 警告発生モジュール（moduleIdentifier, moduleName）
3. 警告発生位置（loc）
4. 警告関連チャンク（chunkName, chunkId）
5. 警告詳細（details）
6. モジュールトレース（moduleTrace）
7. 原因チェーン（cause）
8. 集約エラー（errors）

**帳票の出力タイミング**：`Stats.toJson()` または `Stats.toString()` 呼び出し時に、StatsFactoryの `compilation.warnings` 抽出処理で生成される。

**帳票の利用者**：フロントエンド開発者、CI/CDシステム、コード品質監視ツール。

## 帳票種別

警告情報構造化出力

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | CLI | `webpack` | ビルド時に警告が存在する場合自動出力 |
| - | Node.js API | プログラム内 | `stats.toJson()` / `stats.toString()` |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | JSON（toJson時）/ テキスト（toString時） |
| 用紙サイズ | N/A |
| 向き | N/A |
| ファイル名 | N/A |
| 出力方法 | StatsCompilation.warningsフィールドとして出力 |
| 文字コード | UTF-8 |

## 帳票レイアウト

### レイアウト概要

StatsError型の配列として出力される。データ構造はエラーレポート（No.4）と同一。

```
{
    "message":           警告メッセージ,
    "moduleIdentifier":  モジュール識別子,
    "moduleName":        モジュール名,
    "loc":              警告位置,
    "chunkName":        関連チャンク名,
    "chunkId":          関連チャンクID,
    "file":             関連ファイル,
    "moduleId":         モジュールID,
    "details":          警告詳細,
    "stack":            スタックトレース,
    "moduleTrace":      モジュール依存トレース
}
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | message | 警告メッセージ | WebpackError.message | 文字列 |

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|-----|
| 1 | moduleIdentifier | モジュール識別子 | error.module.identifier() | 文字列 | - |
| 2 | moduleName | モジュール名 | error.module.readableIdentifier() | 文字列 | - |
| 3 | loc | 警告位置 | formatLocation(error.loc) | "行:列" 形式 | - |
| 4 | chunkName | 関連チャンク名 | error.chunk.name | 文字列 | - |
| 5 | file | 関連ファイル | error.file | 文字列 | - |
| 6 | details | 警告詳細 | error.details | 文字列 | - |

### フッター部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | warningsCount | 警告総数 | countWithChildren() | 数値 |
| 2 | filteredWarningDetailsCount | フィルタされた詳細数 | filtered + filteredBySpace | 数値 |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| errorDetails | 警告詳細出力の有効/無効 | No（デフォルト: "auto"） |
| warningsFilter | 警告フィルタ関数配列 | No |
| warningsSpace | 警告表示のスペース制限 | No |

### ソート順

警告は発生順（compilation.getWarnings()の返却順序）で出力される。

### 改ページ条件

N/A

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

### 参照テーブル一覧

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| Compilation | 警告一覧取得 | compilation.getWarnings() |
| ModuleGraph | モジュール依存トレース | moduleGraph.getIssuer() |
| ChunkGraph | モジュールID取得 | chunkGraph.getModuleId() |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| warningsCount | countWithChildren(compilation, getWarnings) - warningsFilterでフィルタ済み分 | なし | warningsFilter適用後のカウント |
| filteredWarningDetailsCount | filtered（auto判定分） + filteredBySpace（スペース制限分） | なし | - |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[SIMPLE_EXTRACTORS.compilation.warnings] --> B[cachedGetWarnings で全警告取得]
    B --> C[factory.create compilation.warnings 呼び出し]
    C --> D[EXTRACT_ERROR で構造化 エラーレポートと同一処理]
    D --> E{errorDetails auto?}
    E -->|Yes| F[詳細フィルタ数カウント]
    E -->|No| G[全詳細出力 or 非出力]
    F --> H{warningsSpace有限?}
    G --> H
    H -->|Yes| I[errorsSpaceLimit で表示制限]
    H -->|No| J[全警告出力]
    I --> K[StatsError配列返却]
    J --> K
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| warningsFilter非推奨 | config.stats.warningsFilterを使用 | DEP_WEBPACK_STATS_WARNINGS_FILTERの非推奨警告 | config.ignoreWarningsに移行 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 警告数件〜数十件 |
| 目標出力時間 | 警告数に比例（通常ミリ秒単位） |
| 同時出力数上限 | 1 |

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

エラーレポートと同様、警告メッセージにファイルパス情報が含まれる可能性がある。

## 備考

- EXTRACT_ERRORをエラーレポートと共有しているため、データ構造はStatsError型で同一
- `warningsFilter` オプションは `config.ignoreWarnings` に置き換えが推奨されている（`DEP_WEBPACK_STATS_WARNINGS_FILTER`）
- FILTER_RESULTSの`compilation.warnings.warningsFilter`でutil.deprecateによる非推奨警告が発行される
- `warningsCount` はwarningsFilterを考慮した値となる

---

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

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

### 推奨読解順序

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

StatsError型（No.4と同一）と、warnings固有の処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | DefaultStatsFactoryPlugin.js | `lib/stats/DefaultStatsFactoryPlugin.js` | 行294-313: `KnownStatsError` 型定義（エラーレポートと共通） |

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

compilation.warnings 抽出処理を読む。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | DefaultStatsFactoryPlugin.js | `lib/stats/DefaultStatsFactoryPlugin.js` | 行948-979: `SIMPLE_EXTRACTORS.compilation.warnings` - cachedGetWarningsで警告取得、factory.createで構造化 |
| 2-2 | DefaultStatsFactoryPlugin.js | `lib/stats/DefaultStatsFactoryPlugin.js` | 行980-1017: `SIMPLE_EXTRACTORS.compilation.warningsCount` - warningsFilterを考慮したカウント |

**主要処理フロー**:
1. **行949**: `cachedGetWarnings(compilation)` で全警告取得
2. **行950-954**: `factory.create("compilation.warnings", ...)` で構造化
3. **行956-963**: `errorDetails: "auto"` で詳細フィルタ数カウント
4. **行972-976**: `errorsSpaceLimit` でスペース制限適用

#### Step 3: warningsFilterの非推奨処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | DefaultStatsFactoryPlugin.js | `lib/stats/DefaultStatsFactoryPlugin.js` | 行1682-1698: `FILTER_RESULTS["compilation.warnings"].warningsFilter` - util.deprecateによる非推奨警告付きフィルタ |

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

```
SIMPLE_EXTRACTORS.compilation.warnings()
    |
    +-- cachedGetWarnings(compilation)
    +-- factory.create("compilation.warnings", warnings, context)
    |       |
    |       +-- EXTRACT_ERROR._()         (エラーレポートと同一)
    |       +-- EXTRACT_ERROR.ids()
    |       +-- EXTRACT_ERROR.moduleTrace()
    |       +-- EXTRACT_ERROR.errorDetails()
    |       +-- EXTRACT_ERROR.errorStack()
    |       +-- EXTRACT_ERROR.errorCause()
    |       +-- EXTRACT_ERROR.errorErrors()
    |
    +-- FILTER_RESULTS["compilation.warnings"].warningsFilter()
    |       +-- util.deprecate() 非推奨警告
    |
    +-- errorsSpaceLimit(rawWarnings, warningsSpace)

SIMPLE_EXTRACTORS.compilation.warningsCount()
    +-- countWithChildren(compilation, cachedGetWarnings)
    +-- warningsFilter適用（存在する場合）
```

### データフロー図

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

compilation.getWarnings()  -->  EXTRACT_ERROR                  -->  StatsError[]
                           -->  warningsFilter（非推奨）        -->  フィルタ済みStatsError[]
                           -->  errorsSpaceLimit               -->  スペース制限済みStatsError[]
                           -->  countWithChildren              -->  warningsCount
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| DefaultStatsFactoryPlugin.js | `lib/stats/DefaultStatsFactoryPlugin.js` | ソース | EXTRACT_ERROR共有、compilation.warnings/warningsCount抽出 |
| StatsFactory.js | `lib/stats/StatsFactory.js` | ソース | データ変換パイプライン |
| Stats.js | `lib/Stats.js` | ソース | toJson() / toString() エントリーポイント |
| Compilation.js | `lib/Compilation.js` | ソース | getWarnings()メソッド提供 |
| WebpackError.js | `lib/WebpackError.js` | ソース | 警告の基底クラス |
