# 帳票設計書 7-json

## 概要

本ドキュメントは、Jestテストフレームワークにおけるカバレッジレポート形式「json」の設計仕様を定義する。jsonレポーターは、コードカバレッジ情報をJSON形式で出力し、coverage/coverage-final.jsonとしてファイルに保存する。他のツールやダッシュボードとの連携に使用される標準的なカバレッジデータ形式である。

### 本帳票の処理概要

jsonカバレッジレポーターは、istanbul-reportsライブラリのjsonレポーターを使用して、テスト実行後に収集されたカバレッジデータをJSON形式でファイルに出力する。このJSON形式はIstanbul/NYCの標準形式であり、ファイルごとのStatement、Branch、Function、Lineカバレッジの詳細情報を含む。生成されたJSONファイルは、カバレッジダッシュボード、継続的な品質監視ツール、カスタムレポート生成などに活用できる。

**業務上の目的・背景**：カバレッジデータを機械可読な形式で保存することで、他のツールとの連携や履歴データの蓄積が可能になる。JSON形式は広くサポートされており、codecov、coveralls、SonarQubeなどの品質管理ツールとの統合に使用される。また、カスタムダッシュボードやレポート生成ツールの入力データとしても活用できる。

**帳票の利用シーン**：CI/CDパイプラインでのカバレッジデータ保存、品質管理ツールへのアップロード、カバレッジ履歴の分析、カスタムレポート生成などに使用される。

**主要な出力内容**：
1. ファイルパスをキーとするカバレッジオブジェクト
2. Statement カバレッジマップ（statementMap）と実行回数（s）
3. Branch カバレッジマップ（branchMap）と実行回数（b）
4. Function カバレッジマップ（fnMap）と実行回数（f）
5. ファイルパス情報（path）

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

**帳票の利用者**：DevOpsエンジニア、品質管理チーム、CI/CDシステム、カバレッジ分析ツール

## 帳票種別

カバレッジレポート形式 / JSON形式

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| N/A | ファイル出力 | N/A | `jest --coverage`実行 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | JSON |
| 用紙サイズ | N/A |
| 向き | N/A |
| ファイル名 | coverage-final.json |
| 出力方法 | ファイル出力 |
| 文字コード | UTF-8 |

### 出力パス

| 項目 | 内容 |
|-----|------|
| デフォルトパス | `<coverageDirectory>/coverage-final.json` |
| coverageDirectory | globalConfig.coverageDirectoryで設定（デフォルト: `<rootDir>/coverage/`） |

## 帳票レイアウト

### レイアウト概要

JSON形式のカバレッジレポートは、ファイルパスをキーとするオブジェクトで構成される。

```json
{
  "/path/to/file1.ts": {
    "path": "/path/to/file1.ts",
    "statementMap": { ... },
    "fnMap": { ... },
    "branchMap": { ... },
    "s": { ... },
    "f": { ... },
    "b": { ... }
  },
  "/path/to/file2.ts": { ... }
}
```

### ファイルカバレッジオブジェクト

| No | 項目名 | 説明 | データ型 | 備考 |
|----|-------|------|---------|------|
| 1 | path | ファイルの絶対パス | string | ファイル識別子 |
| 2 | statementMap | Statement位置情報 | object | 各Statementの開始・終了位置 |
| 3 | fnMap | Function位置情報 | object | 各Functionの名前・位置 |
| 4 | branchMap | Branch位置情報 | object | 各Branchの種類・位置 |
| 5 | s | Statement実行回数 | object | キー: Statement ID, 値: 実行回数 |
| 6 | f | Function実行回数 | object | キー: Function ID, 値: 実行回数 |
| 7 | b | Branch実行回数 | object | キー: Branch ID, 値: 各分岐の実行回数配列 |

### 位置情報フォーマット

```json
{
  "start": { "line": 10, "column": 0 },
  "end": { "line": 10, "column": 50 }
}
```

## 出力条件

### 抽出条件

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

### 設定例

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

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

### 参照テーブル一覧

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

### データ構造参照

#### istanbulCoverage.CoverageMap

| 参照項目 | 帳票項目との対応 | 用途 |
|---------|----------------|------|
| files() | ルートキー | ファイル一覧 |
| fileCoverageFor(path) | ファイルオブジェクト | ファイル別カバレッジ |

## 計算仕様

### 計算項目一覧

N/A（istanbul-reportsのjsonレポーターが直接出力）

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[CoverageReporter.onRunComplete] --> B[_getCoverageResult]
    B --> C[istanbulReports.create 'json']
    C --> D[レポーター.execute]
    D --> E[coverage-final.json出力]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| ファイル書き込み失敗 | ディレクトリ権限エラー等 | "Failed to write coverage reports: ERROR: {message}" | 赤色でエラー出力 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 数千ファイルまで対応 |
| 目標出力時間 | カバレッジデータサイズに依存 |
| ファイルサイズ | 大規模プロジェクトでは数十MB |

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

- JSONファイルにはソースコードの構造（関数名、変数名、行番号）が含まれる
- CI/CDアーティファクトとして保存する場合はアクセス制御に注意
- 公開リポジトリではカバレッジデータの公開範囲を検討

## 備考

- istanbul-reportsのjsonレポーターを使用
- 出力されるJSON形式はIstanbul/NYC標準形式
- codecov、coveralls等のサービスと互換性あり
- `--coverageReporters`コマンドラインオプションでも指定可能

---

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

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

### 推奨読解順序

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

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

**主要処理フロー**:
- **83-93行目**: coverageReportersをループして各レポーターを実行
- **88-93行目**: `istanbulReports.create(reporter, {...}).execute(reportContext)`

#### Step 2: istanbul-reportsの処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | istanbul-reports | `node_modules/istanbul-reports` | jsonレポーターの実装を確認 |

**読解のコツ**: istanbul-reportsはサードパーティライブラリのため、APIドキュメントを参照。

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

```
CoverageReporter.onRunComplete
    │
    ├─ _getCoverageResult
    │      └─ istanbulCoverage.CoverageMap
    │
    └─ istanbulReports.create('json')
           │
           └─ execute(reportContext)
                  │
                  └─ coverage-final.json出力
```

### データフロー図

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

CoverageMap ───────────▶ istanbulReports.create('json')
       │                       │
       ├─ files()              ├─▶ JSON変換
       │                       │
       └─ fileCoverageFor()    └─▶ ファイル書き込み ──────▶ coverage-final.json
```

### 関連ファイル一覧

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