# 帳票設計書 13-text-summary

## 概要

本ドキュメントは、Jestのカバレッジレポート機能におけるテキストサマリー形式レポートの設計仕様を定義する。istanbul-reportsライブラリを使用し、コンソールにカバレッジの概要のみを簡潔に出力する機能について詳述する。

### 本帳票の処理概要

テキストサマリーカバレッジレポートは、Jestテスト実行時に収集されたコードカバレッジ情報を、コンソール上にコンパクトなサマリー形式で出力する帳票である。ファイル別の詳細は表示せず、プロジェクト全体のステートメント、分岐、関数、行の各カバレッジ率を一目で確認できる形式で出力する。

**業務上の目的・背景**：開発者がテスト実行時にカバレッジの概要を素早く確認するために使用される。詳細なレポートは不要で、全体的なカバレッジ状況のみを把握したい場合に最適である。CI/CDパイプラインでのログ出力や、`useStderr`オプション有効時のデフォルト出力としても使用される。

**帳票の利用シーン**：テスト実行後の素早いカバレッジ確認、CI/CDログでの簡潔なカバレッジ表示、`useStderr`設定時のデフォルト出力、`coverageReporters`が空の場合のフォールバック出力において利用される。

**主要な出力内容**：
1. カバレッジサマリーヘッダー（区切り線）
2. Statements カバレッジ（パーセンテージと件数）
3. Branches カバレッジ（パーセンテージと件数）
4. Functions カバレッジ（パーセンテージと件数）
5. Lines カバレッジ（パーセンテージと件数）
6. サマリーフッター（区切り線）

**帳票の出力タイミング**：`jest --coverage` コマンド実行時、または `collectCoverage: true` 設定時にテスト完了後に自動生成される。`coverageReporters` に `'text-summary'` を含めることで出力される。また、`useStderr: true` かつ `coverageReporters` が空の場合にデフォルトで出力される。

**帳票の利用者**：開発者、CI/CDシステム、テスト自動化スクリプト

## 帳票種別

カバレッジサマリーレポート（コンソール出力）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | CLI（コマンドライン） | - | `jest --coverage` コマンド実行 |
| - | 設定ファイル | jest.config.js | `coverageReporters: ['text-summary']` 設定 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | テキスト（標準出力/標準エラー出力） |
| 用紙サイズ | N/A（コンソール出力） |
| 向き | N/A |
| ファイル名 | N/A（コンソール出力のためファイル出力なし） |
| 出力方法 | stdout または stderr |
| 文字コード | UTF-8 |

### コンソール出力固有設定

| 項目 | 内容 |
|-----|------|
| 出力先 | `process.stdout` または `process.stderr`（useStderr設定による） |
| 色付け | chalkによるANSIカラーコード |
| 幅制限 | `process.stdout.columns` または無制限 |

## 帳票レイアウト

### レイアウト概要

テキストサマリーは固定フォーマットの表形式でコンソールに出力される。

```
=============================== Coverage summary ===============================
Statements   : 85.71% ( 30/35 )
Branches     : 75.00% ( 12/16 )
Functions    : 90.00% ( 9/10 )
Lines        : 87.50% ( 28/32 )
================================================================================
```

### サマリー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | ヘッダー線 | 上部区切り線 | 固定値 | `=` の繰り返し |
| 2 | Coverage summary | タイトル | 固定値 | 中央揃えテキスト |
| 3 | Statements | ステートメントカバレッジ | CoverageSummary.statements | `XX.XX% ( covered/total )` |
| 4 | Branches | 分岐カバレッジ | CoverageSummary.branches | `XX.XX% ( covered/total )` |
| 5 | Functions | 関数カバレッジ | CoverageSummary.functions | `XX.XX% ( covered/total )` |
| 6 | Lines | 行カバレッジ | CoverageSummary.lines | `XX.XX% ( covered/total )` |
| 7 | フッター線 | 下部区切り線 | 固定値 | `=` の繰り返し |

### 色分けルール

| カバレッジ率 | 色 | 条件 |
|------------|-----|------|
| 高（緑） | green | pct >= watermarks.high |
| 中（黄） | yellow | watermarks.low <= pct < watermarks.high |
| 低（赤） | red | pct < watermarks.low |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| collectCoverage | カバレッジ収集が有効であること | Yes |
| coverageReporters | `'text-summary'` が含まれている、または空でuseStderrがtrue | Yes |

### ソート順

N/A（サマリーのみのため順序なし）

### 改ページ条件

N/A（コンソール出力のため改ページは発生しない）

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

### 参照テーブル一覧

本帳票はデータベースを使用せず、テスト実行時に収集されたカバレッジデータ（メモリ上のCoverageMap）を参照する。

| データソース名 | 用途 | 取得方法 |
|---------------|------|---------|
| CoverageMap | カバレッジ情報全体 | `istanbulCoverage.createCoverageMap()` |
| CoverageSummary | サマリー情報 | `map.getCoverageSummary()` |

### データ構造詳細

#### CoverageSummary

| フィールド | 説明 | 型 |
|-----------|------|-----|
| statements | ステートメントカバレッジ | `{total, covered, skipped, pct}` |
| branches | 分岐カバレッジ | `{total, covered, skipped, pct}` |
| functions | 関数カバレッジ | `{total, covered, skipped, pct}` |
| lines | 行カバレッジ | `{total, covered, skipped, pct}` |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| カバレッジ率 | `(covered / total) * 100` | 小数点以下2桁 | total=0の場合は"Unknown"表示 |
| Watermark判定 | 閾値との比較 | - | low/medium/high の3段階で色分け |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[テスト実行完了] --> B[CoverageReporter.onRunComplete]
    B --> C[カバレッジデータ収集]
    C --> D{coverageReportersは空?}
    D -->|Yes| E{useStderrはtrue?}
    D -->|No| F[coverageReportersをループ]
    E -->|Yes| G[text-summaryを追加]
    E -->|No| F
    G --> F
    F --> H[istanbulReports.create text-summary 呼び出し]
    H --> I[reportContext生成]
    I --> J[サマリー計算]
    J --> K[コンソールに出力]
    K --> L[終了]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| データなし | カバレッジデータが収集されていない | サマリーが空またはUnknown表示 | collectCoverageの有効化を確認 |
| 出力失敗 | stdout/stderrへの書き込み失敗 | `Failed to write coverage reports: ERROR: ...` | 出力先の状態確認 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 全ファイルの集計値1件 |
| 目標出力時間 | ミリ秒単位（ほぼ瞬時） |
| 同時出力数上限 | 1 |

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

- コンソール出力のみのためセキュリティリスクは低い
- CI/CDログに出力される場合、パブリックリポジトリではログが公開される可能性があるが、サマリー情報のみのため機密情報は含まれない

## 備考

- text-summaryはデフォルトの `coverageReporters` には含まれていない
- `useStderr: true` かつ `coverageReporters` が空の場合、text-summaryがデフォルトで追加される（行80-81）
- `text` レポーターとの違い：`text` はファイル別の詳細を含むが、`text-summary` はサマリーのみ
- ANSIカラーコードに対応しているターミナルでは色付きで表示される

---

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

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

### 推奨読解順序

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

text-summaryレポート生成に使用されるカバレッジデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Config.ts | `packages/jest-types/src/Config.ts` | CoverageReporterName型の定義（行132） |

**読解のコツ**: `CoverageReporterName`には`text-summary`も含まれる。istanbul-reportsでサポートされているレポーター名の一つ。

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

カバレッジレポート生成のエントリーポイントとtext-summaryのデフォルト追加ロジックを特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | CoverageReporter.ts | `packages/jest-reporters/src/CoverageReporter.ts` | onRunCompleteメソッドでのtext-summaryデフォルト追加 |

**主要処理フロー**:
1. **行78**: `coverageReporters`配列を取得
2. **行80-82**: `!useStderr && coverageReporters.length === 0`の場合、`text-summary`を追加
3. **行83-94**: 各レポーターに対して`istanbulReports.create(reporter, options).execute(reportContext)`を呼び出し

#### Step 3: レポートコンテキスト生成を理解する

text-summaryレポートに渡されるコンテキストの生成プロセスを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | CoverageReporter.ts | `packages/jest-reporters/src/CoverageReporter.ts` | _getCoverageResultメソッド（行437-516） |
| 3-2 | getWatermarks.ts | `packages/jest-reporters/src/getWatermarks.ts` | Watermark閾値の計算（行11-36） |

**主要処理フロー**:
- **行498-504**: reportContext生成時にwatermarksが設定される
- **行501**: `watermarks: getWatermarks(this._globalConfig)`で色分け閾値が決定

#### Step 4: 設定のデフォルト値を理解する

text-summaryレポートの設定方法を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Defaults.ts | `packages/jest-config/src/Defaults.ts` | デフォルトのcoverageReporters（行28）とuseStderr（行93） |

**主要処理フロー**:
- **行28**: デフォルト値は `['json', 'text', 'lcov', 'clover']` でtext-summaryは含まれない
- **行93**: `useStderr: false` がデフォルト

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

```
jest --coverage
    │
    ├─ TestScheduler
    │      └─ CoverageReporter.onRunComplete()
    │             │
    │             ├─ _addUntestedFiles()（未テストファイルのカバレッジ追加）
    │             │
    │             ├─ _getCoverageResult()
    │             │      ├─ V8/Babelプロバイダーからデータ変換
    │             │      ├─ istanbulReport.createContext()
    │             │      └─ getWatermarks()
    │             │
    │             ├─ coverageReportersが空 && !useStderr の場合
    │             │      └─ 'text-summary' を追加
    │             │
    │             ├─ istanbulReports.create('text-summary', options)
    │             │      └─ .execute(reportContext)
    │             │             └─ コンソールにサマリー出力
    │             │
    │             └─ _checkThreshold()（閾値チェック）
    │
    └─ stdout/stderr にサマリー出力
```

### データフロー図

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

テスト実行結果         CoverageReporter              stdout/stderr
      │                      │                              │
V8Coverage ────────▶ _getCoverageResult() ─────▶ istanbul-reports
      │                      │                    (text-summary reporter)
BabelCoverage ─────▶ CoverageMap構築                       │
      │                      │                              │
                    CoverageSummary集計 ────────▶ ======= Coverage summary =======
                             │                    Statements : XX.XX%
                    Watermarks適用 ───────────▶ Branches   : XX.XX%
                             │                    Functions  : XX.XX%
                    色分け決定                    Lines      : XX.XX%
                                                  ================================
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| CoverageReporter.ts | `packages/jest-reporters/src/CoverageReporter.ts` | ソース | カバレッジレポート生成の主要ロジック（特に行80-82のデフォルト追加） |
| getWatermarks.ts | `packages/jest-reporters/src/getWatermarks.ts` | ソース | Watermark閾値計算（色分けに使用） |
| Config.ts | `packages/jest-types/src/Config.ts` | ソース | 型定義（CoverageReporterName等） |
| Defaults.ts | `packages/jest-config/src/Defaults.ts` | ソース | デフォルト設定値（useStderr含む） |
| CoverageReporter.test.js | `packages/jest-reporters/src/__tests__/CoverageReporter.test.js` | テスト | CoverageReporterのユニットテスト |
| Configuration.md | `docs/Configuration.md` | ドキュメント | coverageReportersの設定説明（行367でtext-summary言及） |
