# 通知設計書 20-カバレッジエラー通知

## 概要

本ドキュメントは、Jestテストフレームワークにおけるカバレッジエラー通知機能の設計について記載する。CoverageReporterクラスの`onRunComplete`メソッド内のエラーハンドリングによって実装され、カバレッジレポート生成に失敗した場合にエラーメッセージを出力する。

### 本通知の処理概要

**業務上の目的・背景**：カバレッジレポートの生成は、ファイルシステムの書き込みや外部ライブラリ（istanbul-reports等）の処理を伴うため、様々な理由で失敗する可能性がある。エラーが発生した場合、開発者が問題を特定・解決できるよう、エラーメッセージとスタックトレースを表示する必要がある。

**通知の送信タイミング**：`onRunComplete`メソッド内でカバレッジレポートを生成する際に例外が発生した場合に出力される。try-catchブロックでキャッチされたエラーが対象となる。

**通知の受信者**：コンソールを監視している開発者。CI/CD環境ではビルドログに記録される。

**通知内容の概要**：赤色で「Failed to write coverage reports:」というヘッダーとともに、エラーメッセージ（error.toString()）とスタックトレース（error.stack）が出力される。console.errorを使用して標準エラー出力に出力される。

**期待されるアクション**：開発者はエラーメッセージを確認し、カバレッジレポート生成の失敗原因を調査・修正する。よくある原因としては、出力ディレクトリへの書き込み権限不足、ディスク容量不足、不正なレポーター設定などがある。

## 通知種別

コンソール出力（標準エラー出力）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 高（エラー） |
| リトライ | なし |

### 送信先決定ロジック

console.errorで標準エラー出力（stderr）に直接出力される。

## 通知テンプレート

### コンソール出力形式

| 項目 | 内容 |
|-----|------|
| 出力先 | 標準エラー出力（stderr） |
| 形式 | テキスト（ANSIカラーコード付き、赤色） |

### 本文テンプレート

```
        Failed to write coverage reports:
        ERROR: {エラーメッセージ}
        STACK: {スタックトレース}

```

スタイル: `chalk.red`（赤色）

### エラーメッセージ例

```
        Failed to write coverage reports:
        ERROR: ENOENT: no such file or directory, open '/path/to/coverage/lcov.info'
        STACK: Error: ENOENT: no such file or directory, open '/path/to/coverage/lcov.info'
            at Object.openSync (fs.js:498:3)
            at Object.writeFileSync (fs.js:1546:35)
            ...

```

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| error.toString() | エラーメッセージ | catch節のerror | Yes |
| error.stack | スタックトレース | catch節のerror | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| レポート生成エラー | onRunComplete内のtry-catch | 例外発生時 | CoverageReporter.onRunComplete()で実行 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| エラーなし | レポート生成が正常に完了した場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[onRunComplete呼び出し] --> B[_addUntestedFiles]
    B --> C[_getCoverageResult]
    C --> D[try: レポート生成開始]
    D --> E[coverageReporters設定取得]
    E --> F[各レポーター実行ループ]
    F --> G{istanbulReports.create}
    G -->|成功| H[execute実行]
    G -->|失敗| I[catch節へ]
    H -->|成功| J[次のレポーター]
    H -->|失敗| I
    J --> F
    F -->|完了| K[coverageMap設定]
    K --> L[_checkThreshold]
    I --> M[console.error: chalk.red]
    M --> N[エラーメッセージ出力]
    N --> O[スタックトレース出力]
    O --> L
    L --> Z[終了]
```

## データベース参照・更新仕様

### 参照テーブル一覧

本機能はデータベースを使用しない。

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

該当なし

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| ファイル書き込みエラー | 出力ディレクトリへの書き込み権限不足 | エラーメッセージを表示、処理は継続 |
| ディスク容量不足 | coverageDirectoryにファイルを書き込めない | エラーメッセージを表示、処理は継続 |
| レポーター設定エラー | 不正なレポーター名の指定 | エラーメッセージを表示、処理は継続 |
| istanbulライブラリエラー | istanbul-reportsの内部エラー | エラーメッセージを表示、処理は継続 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | なし |
| 1日あたり上限 | なし |

### 配信時間帯

制限なし

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

- スタックトレースにはファイルパスが含まれる
- エラーメッセージには内部的な設定情報が含まれる可能性がある

## 備考

- エラーが発生してもテスト実行全体は失敗にならない（処理は継続）
- _checkThresholdはtry-catchの後に呼ばれるため、エラー時も閾値チェックは実行される
- console.errorはthis.logとは異なり、直接stderrに出力される

---

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

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

### 推奨読解順序

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

エラー通知で扱うデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | CoverageReporter.ts | `packages/jest-reporters/src/CoverageReporter.ts` | L96: catch節のerror: any型 |

**読解のコツ**: JavaScriptの標準Errorオブジェクト（toString(), stack）を使用。

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

処理の起点となるonRunCompleteメソッドを特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | CoverageReporter.ts | `packages/jest-reporters/src/CoverageReporter.ts` | L70-107: onRunCompleteメソッド |

**主要処理フロー**:
1. **L74**: `_addUntestedFiles`で未テストファイルのカバレッジ収集
2. **L75**: `_getCoverageResult`でカバレッジ結果を取得
3. **L77**: try開始
4. **L78-95**: レポート生成処理
5. **L96**: catch節開始
6. **L97-103**: エラーメッセージ出力
7. **L106**: `_checkThreshold`（try-catchの外）

#### Step 3: エラーハンドリングの詳細

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | CoverageReporter.ts | `packages/jest-reporters/src/CoverageReporter.ts` | L96-104: catch節 |

**主要処理フロー**:
- **L96**: `catch (error: any)`
- **L97-103**: console.errorでchalk.redを使用
- **L99**: 「Failed to write coverage reports:」ヘッダー
- **L100**: `ERROR: ${error.toString()}`
- **L101**: `STACK: ${error.stack}`

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

```
CoverageReporter.onRunComplete (L70)
    │
    ├─ _addUntestedFiles (L74)
    │
    ├─ _getCoverageResult (L75)
    │
    ├─ try (L77)
    │      │
    │      ├─ coverageReportersデフォルト設定 (L78-81)
    │      │
    │      └─ 各レポーター処理 (L83-94)
    │             │
    │             ├─ istanbulReports.create (L88)
    │             │
    │             └─ execute (L93)
    │
    ├─ catch (L96)
    │      │
    │      └─ console.error (L97)
    │             │
    │             └─ chalk.red (L98)
    │                    │
    │                    ├─ "Failed to write coverage reports:" (L99)
    │                    │
    │                    ├─ error.toString() (L100)
    │                    │
    │                    └─ error.stack (L101)
    │
    └─ _checkThreshold (L106) ← try-catchの外
```

### データフロー図

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

testContexts ─────────────▶ onRunComplete
                                  │
                                  ▼
                           _addUntestedFiles
                                  │
                                  ▼
                           _getCoverageResult
                                  │
                                  ▼
                             try {
                                  │
                                  ▼
                           レポート生成
                                  │
                            ┌─────┴─────┐
                            │           │
                            ▼           ▼
                         成功        例外発生
                            │           │
                            │           ▼
                            │      catch (error)
                            │           │
                            │           ▼
                            │    console.error(chalk.red(...))
                            │           │
                            │           ├─ "Failed to write..."
                            │           │
                            │           ├─ error.toString()
                            │           │
                            │           └─ error.stack
                            │           │
                            │           ▼
                            │        stderr ──────────▶ [出力]
                            │           │
                            └─────┬─────┘
                                  │
                                  ▼
                           _checkThreshold
                                  │
                                  ▼
                                終了
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| CoverageReporter.ts | `packages/jest-reporters/src/CoverageReporter.ts` | ソース | メイン実装ファイル |
| istanbul-reports | (外部) | ライブラリ | レポート生成（エラーの発生元の可能性） |
| istanbul-lib-report | (外部) | ライブラリ | レポートコンテキスト（エラーの発生元の可能性） |
| graceful-fs | (外部) | ライブラリ | ファイル操作（エラーの発生元の可能性） |
