# バッチ設計書 15-toolkit cov

## 概要

本ドキュメントは、Nushellプロジェクトにおける`toolkit cov`コマンドのバッチ設計書です。コードカバレッジを生成し、lcov.info形式で出力するコマンドの仕様を定義します。

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

`toolkit cov`は、Nushellプロジェクトのテストを実行しながらコードカバレッジ情報を収集し、lcov.info形式のレポートファイルを生成するバッチ処理です。

**業務上の目的・背景**：コードカバレッジは、テストがソースコードのどの程度をカバーしているかを測定する指標です。カバレッジ情報を可視化することで、テストが不足している領域を特定し、テストの品質向上に役立てることができます。また、PRレビュー時にカバレッジ変化を確認することで、新規コードに対するテストの網羅性を評価できます。

**バッチの実行タイミング**：開発者がカバレッジを確認したいときに手動で実行します。CI/CDでカバレッジレポートを生成する際にも使用されます。

**主要な処理内容**：
1. LLVM coverage用の環境変数を設定
2. 既存のカバレッジデータをクリーンアップ
3. ワークスペース全体をprofile=ciでビルド
4. テストを実行してカバレッジデータを収集
5. lcov.info形式でカバレッジレポートを生成

**前後の処理との関連**：独立したコマンドとして実行されます。生成されたlcov.infoは、カバレッジ可視化ツール（VSCode Coverage Gutters、vim-lcov等）で使用できます。

**影響範囲**：プロジェクトルートにlcov.infoファイルを出力します。targetディレクトリにビルド成果物が生成されます。

## バッチ種別

カバレッジ生成 / レポート生成

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（手動実行） |
| 実行時刻 | 任意 |
| 実行曜日 | 任意 |
| 実行日 | 任意 |
| トリガー | 手動 / CI/CD |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Rust環境 | Rustツールチェーンがインストールされていること |
| cargo-llvm-cov | `cargo install cargo-llvm-cov`でインストールされていること |
| LLVMツール | cargo-llvm-covの依存ツールがインストールされていること |
| Nushell環境 | Nushellがインストールされ、toolkitモジュールが利用可能であること |
| プロジェクトディレクトリ | Nushellプロジェクトのルートディレクトリで実行すること |

### 実行可否判定

cargo-llvm-covがインストールされ、Cargoプロジェクトとして正常にビルドできる状態であれば実行可能。初回実行時は追加のツールインストール確認が必要な場合があります。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| （なし） | - | - | - | パラメータなし |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| ソースコード | Rustファイル群 | ワークスペース配下の全ソースファイル |
| テストコード | Rustファイル群 | 全テストファイル |
| Cargo.toml | TOML | ワークスペースとクレートの設定 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | 処理進捗メッセージ |
| lcov.info | LCOVテキスト形式 | カバレッジレポートファイル |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | lcov.info |
| 出力先 | プロジェクトルートディレクトリ |
| 文字コード | UTF-8 |
| 形式 | LCOV tracefile形式 |

## 処理フロー

### 処理シーケンス

```
1. 開始時刻の記録
   └─ date nowで現在時刻を取得

2. 環境変数の設定
   └─ NUSHELL_CARGO_PROFILE=ci

3. LLVM coverage環境変数の設定
   └─ cargo llvm-cov show-envの出力をload-env

4. 既存カバレッジデータのクリーンアップ
   └─ cargo llvm-cov clean --workspace

5. ワークスペースのビルド
   └─ cargo build --workspace --profile=ci

6. テスト実行とカバレッジ収集
   └─ cargo test --workspace --profile=ci

7. カバレッジレポート生成
   └─ cargo llvm-cov report --lcov --output-path lcov.info --profile=ci

8. 処理時間の出力
   └─ 開始時刻からの経過時間を表示
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[開始時刻記録]
    B --> C[NUSHELL_CARGO_PROFILE=ci設定]
    C --> D[LLVM coverage環境変数設定]
    D --> E[既存カバレッジデータクリーン]
    E --> F[ワークスペースビルド]
    F --> G[テスト実行・カバレッジ収集]
    G --> H[lcov.info生成]
    H --> I[処理時間出力]
    I --> J[正常終了]
```

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

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

データベース操作はありません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | cargo-llvm-cov未インストール | ツールがない | cargo install cargo-llvm-cov |
| - | LLVMツール未確認 | 初回実行時 | プロンプトで'y'を入力 |
| - | ビルドエラー | コンパイルエラー | ソースコードを修正 |
| - | テスト失敗 | アサーション失敗 | テストコードを修正 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（手動再実行） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

エラーが発生した場合、エラーメッセージを確認して問題を解決し、再度`toolkit cov`を実行します。初回実行時にツールインストールを求められた場合は`cargo llvm-cov clean`を手動で実行して確認します。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | プロジェクト全体のファイル |
| 目標処理時間 | 数十分（環境・プロジェクトサイズ依存） |
| メモリ使用量上限 | ビルド・テスト実行に依存 |

## 排他制御

同一ディレクトリでの複数Cargo操作は競合する可能性があります。Cargo.lockによるファイルロックが使用されます。カバレッジ実行中は他のビルド操作を避けることを推奨します。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | 各フェーズ開始時 | フェーズ説明メッセージ |
| 進捗ログ | ビルド・テスト中 | Cargoの標準出力 |
| 終了ログ | バッチ終了時 | "Coverage generation took {時間}" |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理時間 | 環境依存 | なし（手動実行） |
| ファイル生成 | lcov.info存在確認 | なし |

## 備考

- `--profile=ci`は基本的にdebugビルドですが、不要なシンボルを削除してバイナリサイズを小さくします
- 一部のテストはcargoプロファイルに依存するため、`NUSHELL_CARGO_PROFILE`環境変数で`ci`を指定します
- 生成されたlcov.infoは以下のエディタ拡張で可視化できます：
  - VSCode: Coverage Gutters
  - Vim: vim-lcov
  - Neovim: nvim-coverage
- cargo-llvm-covの詳細: https://github.com/taiki-e/cargo-llvm-cov
- `nu!`マクロを使用するテストのカバレッジも収集されます
