# 帳票設計書 8-text

## 概要

本ドキュメントは、Jestテストフレームワークにおけるカバレッジレポート形式「text」の設計仕様を定義する。textレポーターは、コードカバレッジ情報をテキストテーブル形式でコンソールに出力し、各ファイルのStatement、Branch、Function、Lineカバレッジ率と未カバー行番号を表示する。

### 本帳票の処理概要

textカバレッジレポーターは、istanbul-reportsライブラリのtextレポーターを使用して、テスト実行後に収集されたカバレッジデータをASCIIテーブル形式でコンソールに出力する。ディレクトリ構造に従った階層表示を行い、各ファイルおよびディレクトリのカバレッジ率を一目で確認できる。低いカバレッジ率は色分けで強調表示され、未カバー行番号も表示される。

**業務上の目的・背景**：テスト実行後に即座にカバレッジ状況を確認することは、開発効率と品質管理に重要である。textレポーターは、ターミナル上でファイル別のカバレッジ率を表形式で表示し、どのファイルのカバレッジが低いかを視覚的に把握できるようにする。特に、CI/CDログでのカバレッジ確認やローカル開発でのクイックチェックに有用である。

**帳票の利用シーン**：ローカル開発環境でのカバレッジ確認、CI/CDパイプラインでのログ出力、カバレッジ低下の即時検出などに使用される。

**主要な出力内容**：
1. ファイル/ディレクトリ名
2. Statement カバレッジ率（% Stmts）
3. Branch カバレッジ率（% Branch）
4. Function カバレッジ率（% Funcs）
5. Line カバレッジ率（% Lines）
6. 未カバー行番号（Uncovered Line #s）

**帳票の出力タイミング**：テスト実行完了後、CoverageReporterのonRunCompleteイベント時にカバレッジレポートの一部としてコンソールに出力される。

**帳票の利用者**：ソフトウェア開発者、QAエンジニア、DevOpsエンジニア

## 帳票種別

カバレッジレポート形式 / テキストテーブル形式

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| CLI-01 | コマンドライン | N/A | `jest --coverage`実行 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | テキスト（コンソール出力） |
| 用紙サイズ | N/A |
| 向き | N/A |
| ファイル名 | N/A（コンソール出力） |
| 出力方法 | process.stdout |
| 文字コード | UTF-8 |

### 表示設定

| 項目 | 内容 |
|-----|------|
| 最大列幅 | process.stdout.columns または無限大 |
| 色出力 | ANSIカラーコード対応 |
| ウォーターマーク | getWatermarks()で取得した閾値で色分け |

## 帳票レイアウト

### レイアウト概要

textレポートは、ASCIIテーブル形式で出力される。

```
----------|---------|----------|---------|---------|-------------------
File      | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
----------|---------|----------|---------|---------|-------------------
All files |   85.00 |    80.00 |   90.00 |   87.50 |
 src/     |   85.00 |    80.00 |   90.00 |   87.50 |
  index.ts|   90.00 |    85.00 |  100.00 |   92.00 |
  utils.ts|   75.00 |    70.00 |   80.00 |   78.00 | 15-20,35,40-45
----------|---------|----------|---------|---------|-------------------
```

### ヘッダー行

| No | 列名 | 説明 | 幅 |
|----|------|------|-----|
| 1 | File | ファイル/ディレクトリ名 | 可変 |
| 2 | % Stmts | Statement カバレッジ率 | 9 |
| 3 | % Branch | Branch カバレッジ率 | 10 |
| 4 | % Funcs | Function カバレッジ率 | 9 |
| 5 | % Lines | Line カバレッジ率 | 9 |
| 6 | Uncovered Line #s | 未カバー行番号 | 可変 |

### データ行

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | File | 相対ファイルパス | CoverageMap.files() | インデント付きパス |
| 2 | % Stmts | Statement カバレッジ率 | CoverageSummary.statements.pct | 小数点2桁 |
| 3 | % Branch | Branch カバレッジ率 | CoverageSummary.branches.pct | 小数点2桁 |
| 4 | % Funcs | Function カバレッジ率 | CoverageSummary.functions.pct | 小数点2桁 |
| 5 | % Lines | Line カバレッジ率 | CoverageSummary.lines.pct | 小数点2桁 |
| 6 | Uncovered | 未カバー行番号 | FileCoverage | 行番号リスト |

### 色分けルール

| 条件 | 色 | 意味 |
|------|-----|------|
| カバレッジ率 >= high watermark | 緑 | 良好 |
| カバレッジ率 >= low watermark | 黄 | 注意 |
| カバレッジ率 < low watermark | 赤 | 要改善 |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| カバレッジ収集 | `--coverage`オプションまたは`collectCoverage: true` | Yes |
| textレポーター指定 | `coverageReporters`に"text"を含む | Yes |

### 設定例

```javascript
// jest.config.js
module.exports = {
  collectCoverage: true,
  coverageReporters: ['text', 'json', 'lcov']
};
```

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

### 参照テーブル一覧

N/A（カバレッジマップから直接出力）

### データ構造参照

#### istanbulCoverage.CoverageSummary

| 参照項目 | 帳票項目との対応 | 用途 |
|---------|----------------|------|
| statements.pct | % Stmts | Statement カバレッジ率 |
| branches.pct | % Branch | Branch カバレッジ率 |
| functions.pct | % Funcs | Function カバレッジ率 |
| lines.pct | % Lines | Line カバレッジ率 |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| カバレッジ率 | (covered / total) * 100 | 小数点2桁 | istanbul-lib-coverageで計算 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[CoverageReporter.onRunComplete] --> B[_getCoverageResult]
    B --> C[istanbulReports.create 'text']
    C --> D[レポーター.execute]
    D --> E[コンソール出力]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| 出力エラー | コンソール出力失敗 | "Failed to write coverage reports: ERROR: {message}" | 赤色でエラー出力 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 数千ファイルまで対応 |
| 目標出力時間 | 即時（コンソール出力） |
| 同時出力数上限 | 1 |

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

- コンソール出力にはファイルパスと行番号が含まれる
- CI/CDログとして保存される場合、プロジェクト構造が公開される
- 機密性の高いファイル名がログに含まれないよう注意

## 備考

- istanbul-reportsのtextレポーターを使用
- maxColsオプションでターミナル幅に応じた表示調整
- ウォーターマーク（閾値）はcoverageThreshold.globalから取得
- ANSIカラーコードに非対応のターミナルでは色なしで表示

---

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

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

### 推奨読解順序

#### Step 1: レポーター呼び出しを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | CoverageReporter.ts | `packages/jest-reporters/src/CoverageReporter.ts` | istanbulReports.createの呼び出し（83-93行目） |

**主要処理フロー**:
- **90行目**: `maxCols: process.stdout.columns || Number.POSITIVE_INFINITY` - 列幅設定

#### Step 2: ウォーターマーク設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | getWatermarks.ts | `packages/jest-reporters/src/getWatermarks.ts` | ウォーターマーク取得 |

**主要処理フロー**:
- **11-36行目**: getWatermarks - coverageThreshold.globalから閾値を取得

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

```
CoverageReporter.onRunComplete
    │
    ├─ _getCoverageResult
    │      └─ istanbulCoverage.CoverageMap
    │
    ├─ getWatermarks
    │      └─ coverageThreshold.global
    │
    └─ istanbulReports.create('text')
           │
           └─ execute(reportContext)
                  │
                  └─ process.stdout出力
```

### データフロー図

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

CoverageMap ───────────▶ istanbulReports.create('text')
       │                       │
       ├─ files()              ├─▶ テーブル生成
       │                       │
       └─ fileCoverageFor()    └─▶ コンソール出力 ──────────▶ stdout
                                          │
Watermarks ────────────────────────────▶ 色分け処理
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| CoverageReporter.ts | `packages/jest-reporters/src/CoverageReporter.ts` | ソース | レポーター呼び出し |
| getWatermarks.ts | `packages/jest-reporters/src/getWatermarks.ts` | ソース | ウォーターマーク取得 |
| istanbul-reports | `node_modules/istanbul-reports` | 外部ライブラリ | テキストレポート生成 |
