# 帳票設計書 3-Stats Compilation サマリー

## 概要

本ドキュメントは、webpackのビルドサマリー情報をフォーマットして出力する「Stats Compilation サマリー」の設計仕様を定義する。

### 本帳票の処理概要

Stats Compilation サマリーは、ビルドのサマリー情報（バージョン、ハッシュ、ビルド時間、エラー数、警告数）を1行のフォーマット済みテキストとして出力する帳票である。`compilation.summary!` プリンターにより生成され、Statsテキストレポートの先頭行に表示される。

**業務上の目的・背景**：ビルドの成功・失敗を一目で判断できるサマリー行を提供するために必要である。CIログやコンソール出力で最初に確認される重要な情報であり、エラー・警告の有無とビルド時間を即座に把握できるようにする。

**帳票の利用シーン**：webpack CLIの通常実行時のビルド結果確認、CIパイプラインのビルドステータス判定、webpack-dev-serverのリビルド通知に利用される。

**主要な出力内容**：
1. ビルド日時（builtAt）
2. コンパイル名（name）とwebpackバージョン（version）
3. コンパイルステータス（successfully / with N errors / with N warnings）
4. ビルド所要時間（time）
5. ビルドハッシュ（hash）

**帳票の出力タイミング**：`Stats.toString()` 呼び出し時に、StatsPrinterの `compilation.summary!` フックとして実行される。

**帳票の利用者**：フロントエンド開発者、CIシステム、DevOpsエンジニア。

## 帳票種別

サマリーテキスト出力

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | CLI / コンソール | - | webpack実行結果の先頭行 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | プレーンテキスト（ANSIカラーコード付き） |
| 用紙サイズ | N/A |
| 向き | N/A |
| ファイル名 | N/A（テキストレポートの一部として出力） |
| 出力方法 | 標準出力 |
| 文字コード | UTF-8 |

## 帳票レイアウト

### レイアウト概要

1行のサマリーテキストとして出力される。

```
{builtAt}: {name} ({version}) compiled {status} in {time} ({hash})
```

出力例：
```
2024-12-18T10:30:00: webpack 5.90.0 compiled successfully in 1234 ms (abc123def456)
2024-12-18T10:30:00: MyApp (webpack 5.90.0) compiled with 2 errors in 5678 ms (abc123def456)
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | builtAt | ビルド完了日時 | StatsCompilation.builtAt | formatDateTime() |
| 2 | name | コンパイル名 | StatsCompilation.name | bold() / `Child bold(name)` |
| 3 | version | webpackバージョン | StatsCompilation.version | `webpack {version}` |
| 4 | errorsCount | エラー数 | StatsCompilation.errorsCount | red(`N error(s)`) |
| 5 | warningsCount | 警告数 | StatsCompilation.warningsCount | yellow(`N warning(s)`) |
| 6 | time | ビルド時間 | StatsCompilation.time | formatTime() |
| 7 | hash | ビルドハッシュ | StatsCompilation.hash | 文字列 |

### 明細部

N/A（サマリー行のため明細なし）

### フッター部

N/A

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| builtAt / version / errorsMessage / warningsMessage / timeMessage / hashMessage のいずれかが存在 | サマリー行出力条件 | Yes |

### ソート順

N/A

### 改ページ条件

N/A

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

### 参照テーブル一覧

本帳票はデータベースを参照しない。StatsCompilationオブジェクトの各フィールドを参照する。

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| StatsCompilation | サマリー情報の参照元 | - |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| statusMessage | errorsCount > 0 かつ warningsCount > 0 → `compiled with N errors and N warnings` / errorsCount > 0 → `compiled with N errors` / warningsCount > 0 → `compiled with N warnings` / 両方0 → `compiled successfully` | なし | 色付きテキスト |
| subjectMessage | nameとversionの組み合わせ | なし | nameとversion両方あれば `name (version)` |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[compilation.summary! プリンター呼び出し] --> B[root判定 type === compilation.summary!]
    B --> C{errorsCount > 0?}
    C -->|Yes| D[errorsMessage = red N errors]
    C -->|No| E[errorsMessage = 空]
    D --> F{warningsCount > 0?}
    E --> F
    F -->|Yes| G[warningsMessage = yellow N warnings]
    F -->|No| H[warningsMessage = 空]
    G --> I[statusMessage組み立て]
    H --> I
    I --> J[builtAtMessage + subjectMessage + statusMessage + timeMessage + hashMessage]
    J --> K[サマリー行返却]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| 出力スキップ | builtAt/version/errorsMessage/warningsMessage/timeMessage/hashMessage すべて未設定 | undefined返却（行非表示） | 少なくとも1つの情報を設定 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 1（サマリー行1行） |
| 目標出力時間 | 1ミリ秒未満 |
| 同時出力数上限 | 1 |

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

サマリー行にはビルドハッシュが含まれるが、セキュリティ上のリスクは低い。コンパイル名にユーザー入力が含まれる場合、XSS等のリスクはコンソール出力のため存在しない。

## 備考

- ルートコンパイル（`type === "compilation.summary!"`）と子コンパイルで表示が異なる
  - ルート: `bold(name)` で太字表示、builtAtとtimeを表示
  - 子: `Child bold(name)` のプレフィックス付き、builtAtとtimeを非表示
- `plural` 関数により、エラー/警告数に応じて単数形・複数形が切り替わる

---

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

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

### 推奨読解順序

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

サマリーの入力データとなるStatsCompilationのサマリー関連フィールドを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | DefaultStatsFactoryPlugin.js | `lib/stats/DefaultStatsFactoryPlugin.js` | 行66-94: `KnownStatsCompilation`の`name`, `hash`, `version`, `time`, `builtAt`, `errorsCount`, `warningsCount`フィールド |

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

compilation.summary! プリンターの実装を読む。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | DefaultStatsPrinterPlugin.js | `lib/stats/DefaultStatsPrinterPlugin.js` | 行197-272: `COMPILATION_SIMPLE_PRINTERS["compilation.summary!"]` の実装を詳細に読む |

**主要処理フロー**:
1. **行218**: root判定（`type === "compilation.summary!"`）
2. **行219-224**: warningsMessage生成（warningsCount > 0の場合、yellow色付き）
3. **行225-231**: errorsMessage生成（errorsCount > 0の場合、red色付き）
4. **行232**: timeMessage生成（rootかつtimeが存在する場合）
5. **行233**: hashMessage生成
6. **行234-235**: builtAtMessage生成（rootかつbuiltAtが存在する場合）
7. **行236**: versionMessage生成（rootかつversionが存在する場合）
8. **行237-247**: nameMessage / subjectMessage組み立て
9. **行249-260**: statusMessage決定（4パターン分岐）
10. **行270**: 最終サマリー行文字列を返却

#### Step 3: 補助関数を理解する

plural関数やフォーマッター関数を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | DefaultStatsPrinterPlugin.js | `lib/stats/DefaultStatsPrinterPlugin.js` | 行44: `plural` 関数 - 単数/複数形の切り替え |

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

```
StatsPrinter._print("compilation", StatsCompilation)
    |
    +-- sortElements("compilation")
    +-- print("compilation.summary!", StatsCompilation)
    |       |
    |       +-- COMPILATION_SIMPLE_PRINTERS["compilation.summary!"]
    |               +-- plural(errorsCount, "error", "errors")
    |               +-- plural(warningsCount, "warning", "warnings")
    |               +-- formatDateTime(builtAt)
    |               +-- formatTime(time)
    |               +-- bold(name)
    |               +-- yellow(warningsMessage)
    |               +-- red(errorsMessage)
    |               +-- green("successfully")
    |
    +-- print("compilation.hash", ...)
    +-- print("compilation.assets", ...)
    +-- ... (他の要素)
```

### データフロー図

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

StatsCompilation           -->  compilation.summary!            -->  サマリー行テキスト
  .name                    -->    subjectMessage組み立て        -->
  .hash                    -->    hashMessage生成              -->
  .version                 -->    versionMessage生成           -->
  .time                    -->    formatTime()                 -->    "in Nms"
  .builtAt                 -->    formatDateTime()             -->    "YYYY-MM-DD HH:MM:SS:"
  .errorsCount             -->    red(N errors)                -->    赤色テキスト
  .warningsCount           -->    yellow(N warnings)           -->    黄色テキスト
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| DefaultStatsPrinterPlugin.js | `lib/stats/DefaultStatsPrinterPlugin.js` | ソース | compilation.summary!プリンターの実装 |
| StatsPrinter.js | `lib/stats/StatsPrinter.js` | ソース | プリンターパイプライン管理 |
| Stats.js | `lib/Stats.js` | ソース | toString()エントリーポイント |
| DefaultStatsFactoryPlugin.js | `lib/stats/DefaultStatsFactoryPlugin.js` | ソース | StatsCompilationデータ生成 |
