# バッチ設計書 12-mapCoverage

## 概要

本ドキュメントは、Jestリポジトリのカバレッジレポートパスマッピングスクリプト `mapCoverage.mjs` の設計仕様を記載する。このバッチは、build/ディレクトリとsrc/ディレクトリのパス変換を行い、統合されたカバレッジレポートを生成する。

### 本バッチの処理概要

このバッチは、Jestのテストカバレッジ計測において発生するパスの不一致問題を解決し、正確なカバレッジレポートを生成する。ビルド済みファイルとソースファイルの両方からのカバレッジ情報を統合する。

**業務上の目的・背景**：Jestはモノレポ構成でビルドステップを持つため、テスト実行時に同一ファイルがbuild/ディレクトリとsrc/ディレクトリの両方から参照される可能性がある。相対パスでrequireした場合はsrc/から、パッケージ名でrequireした場合はLernaのシンボリックリンク経由でbuild/から読み込まれる。これにより、同一コードに対するカバレッジ情報が分散してしまう。このバッチは、すべてのカバレッジパスをsrc/に統一することで、正確なカバレッジメトリクスを算出可能にする。

**バッチの実行タイミング**：CI/CDパイプラインのカバレッジ集計フェーズで実行される。テスト実行後、カバレッジレポートのアップロード前に実行する。

**主要な処理内容**：
1. coverage/coverage-final.jsonからカバレッジデータを読み込み
2. 各ファイルのパスをbuild/からsrc/に変換
3. 変換後のデータをistanbul-lib-coverageでマージ
4. json、lcov、text形式でレポートを出力

**前後の処理との関連**：このバッチはテスト実行（yarn jest-coverage）の後に実行される。出力されたレポートはCodecovなどのカバレッジサービスにアップロードされる。

**影響範囲**：coverage/ディレクトリ内のカバレッジレポートファイルが更新される。既存のcoverage-final.jsonは読み取り専用で使用され、新しいマージ済みレポートが別途生成される。

## バッチ種別

レポート生成 / データ変換

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | CI実行時（PRごと、main pushごと） |
| 実行時刻 | CI実行に依存 |
| 実行曜日 | 指定なし |
| 実行日 | 指定なし |
| トリガー | CI/CDパイプライン（テスト完了後） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Node.js環境 | Node.js 18.14.0以上、20.x、22.x、または24.x以上が必要 |
| 依存パッケージ | istanbul-lib-coverage、istanbul-lib-report、istanbul-reportsがインストール済み |
| カバレッジデータ | coverage/coverage-final.jsonが存在すること |

### 実行可否判定

coverage/coverage-final.jsonが存在しない場合、requireでエラーとなりバッチは異常終了する。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | コマンドライン引数は受け付けない |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| coverage/coverage-final.json | JSON | Jestが出力したカバレッジデータ。ファイルパスごとのカバレッジ情報を含む |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| coverage/ | JSON | マージ済みカバレッジデータ（json reporter） |
| coverage/ | LCOV | LCOVフォーマットのカバレッジレポート |
| 標準出力 | TEXT | テキスト形式のカバレッジサマリー |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | istanbul-reportsのデフォルト命名規則に従う |
| 出力先 | coverage/ |
| 文字コード | UTF-8 |
| 形式 | JSON、LCOV、TEXT |

## 処理フロー

### 処理シーケンス

```
1. モジュールインポート
   └─ istanbul-lib-coverage、istanbul-lib-report、istanbul-reportsをインポート
2. カバレッジデータ読み込み
   └─ createRequireでcoverage/coverage-final.jsonをrequire
3. カバレッジマップ作成
   └─ istanbulCoverage.createCoverageMap()で空のマップを作成
4. パスマッピング処理
   └─ 各ファイルのパスを正規表現で変換（build → src）
5. マップへの追加
   └─ 変換後のカバレッジ情報をマップに追加
6. レポートコンテキスト作成
   └─ istanbulReport.createContext()でレポート生成用コンテキストを作成
7. 複数形式でレポート出力
   └─ json、lcov、text形式でそれぞれレポートを生成
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[coverage-final.json読み込み]
    B --> C[カバレッジマップ作成]
    C --> D{全ファイル処理完了?}
    D -->|No| E[ファイルパスをbuild→srcに変換]
    E --> F[マップにカバレッジ追加]
    F --> D
    D -->|Yes| G[レポートコンテキスト作成]
    G --> H[JSONレポート出力]
    H --> I[LCOVレポート出力]
    I --> J[TEXTレポート出力]
    J --> K[バッチ終了]
```

## データベース操作仕様

### 操作別データベース影響一覧

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| なし | - | - | データベース操作は行わない |

### テーブル別操作詳細

データベース操作は行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| MODULE_NOT_FOUND | モジュール不在 | coverage/coverage-final.jsonが存在しない | テストをカバレッジ有効で再実行 |
| ENOENT | ファイル不在 | coverage/ディレクトリが存在しない | カバレッジ収集を先に実行 |
| SyntaxError | JSON解析エラー | coverage-final.jsonが不正なJSON形式 | カバレッジデータを再生成 |

### リトライ仕様

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

### 障害時対応

バッチ失敗時は以下の手順でリカバリを行う：
1. エラーメッセージを確認し、原因を特定
2. coverage/coverage-final.jsonの存在と形式を確認
3. 必要に応じて `yarn jest-coverage` でカバレッジデータを再生成
4. 再実行

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | なし（ファイルシステム操作） |
| コミットタイミング | 各レポート出力完了時 |
| ロールバック条件 | 自動ロールバックなし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 数百〜数千ファイルのカバレッジ情報 |
| 目標処理時間 | 数秒〜十数秒 |
| メモリ使用量上限 | 特に制限なし（カバレッジデータサイズに依存） |

## 排他制御

同時実行の制御は行わない。CI/CDパイプラインでは通常、ジョブごとに独立したワークスペースで実行されるため、排他制御は不要。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | なし | ログ出力機能なし |
| 進捗ログ | なし | ログ出力機能なし |
| 終了ログ | なし | ログ出力機能なし |
| カバレッジサマリー | text reporter実行時 | カバレッジ統計情報（標準出力） |
| エラーログ | エラー発生時 | Node.jsの標準エラー出力 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| なし | - | CI/CDパイプラインの結果で監視 |

## 備考

- パスマッピングの正規表現: `/(.*packages\/.*\/)(build)(\/.*)/` → `$1src$3`
- この変換により、build/index.jsへのカバレッジがsrc/index.tsのカバレッジとしてマージされる
- istanbul-reportsは標準的なカバレッジレポートライブラリで、Codecov等のサービスと互換性がある
- text reporterは標準出力にサマリーを出力し、CI/CDログで確認可能
