# 帳票設計書 9-lcov

## 概要

本ドキュメントは、Jestテストフレームワークにおけるカバレッジレポート形式「lcov」の設計仕様を定義する。lcovレポーターは、コードカバレッジ情報をLCOV形式でファイルに出力し、coverage/lcov.infoとして保存する。LCOV形式は広く使用されているカバレッジデータ形式であり、多くのカバレッジツールやサービスと互換性がある。

### 本帳票の処理概要

lcovカバレッジレポーターは、istanbul-reportsライブラリのlcovonlyレポーターを使用して、テスト実行後に収集されたカバレッジデータをLCOV形式でファイルに出力する。LCOV形式は、Linux Test Project が開発したGCOV/LCOVツールの出力形式であり、ファイルごとの行カバレッジ、関数カバレッジ、分岐カバレッジを含む。生成されたlcov.infoファイルは、Coveralls、Codecov、SonarQubeなどの品質管理サービスにアップロードできる。

**業務上の目的・背景**：LCOV形式は業界標準のカバレッジデータ形式であり、多くのCI/CDツールやカバレッジサービスがネイティブサポートしている。lcovレポーターを使用することで、既存のカバレッジ分析ワークフローにJestのカバレッジデータをシームレスに統合できる。また、genhtmlツールを使用してHTMLレポートを生成することも可能である。

**帳票の利用シーン**：CI/CDパイプラインでのカバレッジサービスへのアップロード、カバレッジトレンドの追跡、コードレビュー時のカバレッジ確認、品質ゲートの実装などに使用される。

**主要な出力内容**：
1. テスト対象ファイル情報（SF:）
2. 関数カバレッジ情報（FN:, FNDA:, FNF:, FNH:）
3. 分岐カバレッジ情報（BRDA:, BRF:, BRH:）
4. 行カバレッジ情報（DA:, LF:, LH:）
5. ファイル終了マーカー（end_of_record）

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

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

## 帳票種別

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

## 利用画面

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

## 出力形式

### 基本仕様

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

### 出力パス

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

## 帳票レイアウト

### レイアウト概要

LCOV形式は、ファイルごとにセクション分けされたテキスト形式である。

```
TN:
SF:/path/to/file1.ts
FN:10,functionName
FNDA:5,functionName
FNF:1
FNH:1
BRDA:15,0,0,3
BRDA:15,0,1,2
BRF:2
BRH:2
DA:10,5
DA:11,5
DA:12,0
LF:3
LH:2
end_of_record
SF:/path/to/file2.ts
...
```

### レコードタイプ

| タイプ | 説明 | 形式 |
|-------|------|------|
| TN | テスト名 | TN:{test_name} |
| SF | ソースファイル | SF:{absolute_path} |
| FN | 関数定義 | FN:{line},{name} |
| FNDA | 関数呼び出し回数 | FNDA:{count},{name} |
| FNF | 関数総数 | FNF:{count} |
| FNH | 呼び出された関数数 | FNH:{count} |
| BRDA | 分岐データ | BRDA:{line},{block},{branch},{count} |
| BRF | 分岐総数 | BRF:{count} |
| BRH | 実行された分岐数 | BRH:{count} |
| DA | 行データ | DA:{line},{count} |
| LF | 行総数 | LF:{count} |
| LH | 実行された行数 | LH:{count} |
| end_of_record | ファイル終了 | end_of_record |

### 各レコードの詳細

| No | レコード | データ取得元 | 備考 |
|----|---------|-------------|------|
| 1 | SF | FileCoverage.path | 絶対パス |
| 2 | FN | fnMap | 関数名と開始行 |
| 3 | FNDA | f | 関数実行回数 |
| 4 | BRDA | branchMap + b | 分岐実行情報 |
| 5 | DA | statementMap + s | 行実行回数 |

## 出力条件

### 抽出条件

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

### 設定例

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

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

### 参照テーブル一覧

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

### データ構造参照

#### istanbulCoverage.FileCoverage

| 参照項目 | 帳票項目との対応 | 用途 |
|---------|----------------|------|
| path | SF | ファイルパス |
| fnMap | FN | 関数マップ |
| f | FNDA | 関数実行回数 |
| branchMap | BRDA | 分岐マップ |
| b | BRDA | 分岐実行回数 |
| statementMap | DA（間接） | Statement位置 |
| s | DA（間接） | Statement実行回数 |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| FNF | Object.keys(fnMap).length | なし | 関数総数 |
| FNH | f内で count > 0 の数 | なし | 呼び出された関数数 |
| BRF | 全分岐数 | なし | 分岐総数 |
| BRH | count > 0 の分岐数 | なし | 実行された分岐数 |
| LF | Object.keys(statementMap).length | なし | 行総数 |
| LH | s内で count > 0 の数 | なし | 実行された行数 |

## 処理フロー

### 出力フロー

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

## エラー処理

### エラーケース一覧

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 数千ファイルまで対応 |
| 目標出力時間 | カバレッジデータサイズに依存 |
| ファイルサイズ | ファイル数と行数に比例 |

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

- LCOVファイルにはファイルの絶対パスが含まれる
- 関数名がファイルに含まれるため、コード構造が公開される
- CI/CDアーティファクトとして保存する場合はアクセス制御に注意

## 備考

- istanbul-reportsのlcovonlyレポーターを使用
- LCOV形式はLinux Test ProjectのLCOVツールが起源
- Coveralls、Codecov、SonarQube等と直接互換性あり
- genhtmlツールでHTMLレポートを生成可能
- `genhtml coverage/lcov.info --output-directory coverage/html`

---

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

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

### 推奨読解順序

#### 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` | lcovonlyレポーターの実装を確認 |

**読解のコツ**: lcovレポーターは実際にはlcovonlyレポーターとして実装されている。

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

```
CoverageReporter.onRunComplete
    │
    ├─ _getCoverageResult
    │      └─ istanbulCoverage.CoverageMap
    │
    └─ istanbulReports.create('lcov')  // 内部的にlcovonly
           │
           └─ execute(reportContext)
                  │
                  └─ lcov.info出力
```

### データフロー図

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

CoverageMap ───────────▶ istanbulReports.create('lcov')
       │                       │
       ├─ files()              ├─▶ LCOV形式変換
       │                       │
       └─ fileCoverageFor()    │
              │                │
              ├─ path ─────────┼─▶ SF:
              ├─ fnMap ────────┼─▶ FN:, FNF:
              ├─ f ────────────┼─▶ FNDA:, FNH:
              ├─ branchMap ────┼─▶ BRDA:, BRF:
              ├─ b ────────────┼─▶ BRH:
              └─ s ────────────┴─▶ DA:, LF:, LH: ─▶ lcov.info
```

### 関連ファイル一覧

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