# 帳票設計書 10-clover

## 概要

本ドキュメントは、Jestテストフレームワークにおけるカバレッジレポート形式「clover」の設計仕様を定義する。cloverレポーターは、コードカバレッジ情報をClover XML形式でファイルに出力し、coverage/clover.xmlとして保存する。Clover形式は、Atlassian社が開発したカバレッジツールの形式であり、JenkinsやBambooなどのCI/CDツールと高い互換性を持つ。

### 本帳票の処理概要

cloverカバレッジレポーターは、istanbul-reportsライブラリのcloverレポーターを使用して、テスト実行後に収集されたカバレッジデータをClover XML形式でファイルに出力する。Clover形式は、プロジェクト、パッケージ、ファイル、クラス、メソッドの階層構造でカバレッジ情報を表現し、各レベルでのStatement、Branch、Methodカバレッジのメトリクスを含む。

**業務上の目的・背景**：Clover XML形式は、Java開発で広く使用されているカバレッジ形式であり、多くのCI/CDツールがネイティブサポートしている。cloverレポーターを使用することで、Jenkins、Bamboo、TeamCityなどのビルドツールのカバレッジプラグインと直接連携できる。また、カバレッジトレンドの可視化やビルドの成功/失敗判定にも活用される。

**帳票の利用シーン**：Jenkins/Bambooでのカバレッジレポート表示、CI/CDパイプラインでのカバレッジゲート、カバレッジトレンドダッシュボード、品質ゲートの実装などに使用される。

**主要な出力内容**：
1. プロジェクト情報（project要素）
2. パッケージ情報（package要素）
3. ファイル情報（file要素）
4. メトリクス情報（metrics要素：statements、conditionals、methods、elements等）
5. 行カバレッジ詳細（line要素）

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

**帳票の利用者**：DevOpsエンジニア、品質管理チーム、CI/CDシステム、ビルドツール

## 帳票種別

カバレッジレポート形式 / Clover XML形式

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| N/A | ファイル出力 | N/A | `jest --coverage`実行 |
| Jenkins | カバレッジレポートビュー | /job/{name}/coverage | Cloverプラグイン表示 |

## 出力形式

### 基本仕様

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

### 出力パス

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

## 帳票レイアウト

### レイアウト概要

Clover XML形式は、階層構造のXMLで構成される。

```xml
<?xml version="1.0" encoding="UTF-8"?>
<coverage generated="1234567890" clover="3.2.0">
  <project timestamp="1234567890" name="All files">
    <metrics statements="100" coveredstatements="80"
             conditionals="50" coveredconditionals="40"
             methods="20" coveredmethods="18"
             elements="170" coveredelements="138"
             complexity="0" loc="1000" ncloc="800"
             packages="5" files="20" classes="20"/>
    <package name="src">
      <metrics .../>
      <file name="index.ts" path="/path/to/index.ts">
        <metrics .../>
        <line num="1" count="5" type="stmt"/>
        <line num="10" count="3" type="cond" truecount="2" falsecount="1"/>
        ...
      </file>
    </package>
  </project>
</coverage>
```

### XML要素

| 要素 | 説明 | 属性 |
|------|------|------|
| coverage | ルート要素 | generated, clover |
| project | プロジェクト情報 | timestamp, name |
| package | パッケージ情報 | name |
| file | ファイル情報 | name, path |
| metrics | メトリクス | 下記参照 |
| line | 行カバレッジ | num, count, type |

### metrics要素の属性

| 属性 | 説明 | データ取得元 |
|------|------|-------------|
| statements | Statement総数 | CoverageSummary.statements.total |
| coveredstatements | カバーされたStatement数 | CoverageSummary.statements.covered |
| conditionals | 分岐総数 | CoverageSummary.branches.total |
| coveredconditionals | カバーされた分岐数 | CoverageSummary.branches.covered |
| methods | メソッド総数 | CoverageSummary.functions.total |
| coveredmethods | カバーされたメソッド数 | CoverageSummary.functions.covered |
| elements | 要素総数 | statements + conditionals + methods |
| coveredelements | カバーされた要素数 | covered合計 |
| loc | 行数 | FileCoverage.lines |
| ncloc | 非コメント行数 | 実装依存 |
| packages | パッケージ数 | ディレクトリ数 |
| files | ファイル数 | ファイル数 |
| classes | クラス数 | ファイル数 |

### line要素の属性

| 属性 | 説明 | 値 |
|------|------|-----|
| num | 行番号 | 数値 |
| count | 実行回数 | 数値 |
| type | 行タイプ | stmt / cond / method |
| truecount | true分岐実行回数 | 数値（type="cond"時） |
| falsecount | false分岐実行回数 | 数値（type="cond"時） |

## 出力条件

### 抽出条件

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

### 設定例

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

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

### 参照テーブル一覧

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

### データ構造参照

#### istanbulCoverage.CoverageSummary

| 参照項目 | 帳票項目との対応 | 用途 |
|---------|----------------|------|
| statements.total | metrics.statements | Statement総数 |
| statements.covered | metrics.coveredstatements | カバー数 |
| branches.total | metrics.conditionals | 分岐総数 |
| branches.covered | metrics.coveredconditionals | カバー数 |
| functions.total | metrics.methods | メソッド総数 |
| functions.covered | metrics.coveredmethods | カバー数 |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| elements | statements + conditionals + methods | なし | 要素総数 |
| coveredelements | coveredstatements + coveredconditionals + coveredmethods | なし | カバー総数 |

## 処理フロー

### 出力フロー

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

## エラー処理

### エラーケース一覧

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 数千ファイルまで対応 |
| 目標出力時間 | カバレッジデータサイズに依存 |
| ファイルサイズ | ファイル数と行数に比例（XMLのためJSON/LCOVより大きい） |

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

- XMLファイルにはファイルの絶対パスが含まれる
- メソッド名、行番号などコード構造が公開される
- CI/CDアーティファクトとして保存する場合はアクセス制御に注意
- XMLパーサーの脆弱性に注意（XXE攻撃等）

## 備考

- istanbul-reportsのcloverレポーターを使用
- Clover形式はAtlassian社のCloverツールが起源
- JenkinsのClover Pluginと直接互換性あり
- BambooのCloverタスクとも連携可能
- Java/Groovyプロジェクトとの統合が容易

---

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

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

### 推奨読解順序

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

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

**主要処理フロー**:
- **88-93行目**: `istanbulReports.create(reporter, {...}).execute(reportContext)`

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

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

**読解のコツ**: cloverレポーターはXML形式の出力を生成する。

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

```
CoverageReporter.onRunComplete
    │
    ├─ _getCoverageResult
    │      └─ istanbulCoverage.CoverageMap
    │
    └─ istanbulReports.create('clover')
           │
           └─ execute(reportContext)
                  │
                  └─ clover.xml出力
```

### データフロー図

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

CoverageMap ───────────▶ istanbulReports.create('clover')
       │                       │
       ├─ files()              ├─▶ XML構造生成
       │                       │      │
       └─ fileCoverageFor()    │      ├─▶ project要素
              │                │      ├─▶ package要素
              ├─ path          │      ├─▶ file要素
              ├─ toSummary()   │      ├─▶ metrics要素
              │      │         │      └─▶ line要素
              │      ├─ statements
              │      ├─ branches
              │      └─ functions
              │
              └─ statementMap + s ─────────────────▶ clover.xml
```

### 関連ファイル一覧

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