# バッチ設計書 7-coverage-local.sh

## 概要

本ドキュメントは、コードカバレッジを生成してlcov.infoを出力するシェルスクリプト `coverage-local.sh` のバッチ設計書です。Linux/macOS環境向けのカバレッジ計測バッチとして設計されています。

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

このバッチは、Nushellプロジェクトのコードカバレッジを計測し、lcov形式のレポートファイルを出力します。cargo-llvm-covを使用してLLVMベースのカバレッジ計測を行い、テストカバレッジの可視化と品質管理に使用されます。

**業務上の目的・背景**：コード品質の維持・向上のため、テストがどの程度コードをカバーしているかを計測する必要があります。特にCI/CDパイプラインやPRレビューにおいて、新しいコードに対するテストの網羅性を確認するために使用されます。カバレッジレポートは開発者のローカル環境でも確認可能で、テスト不足の箇所を特定できます。

**バッチの実行タイミング**：コードカバレッジの計測が必要な際に手動で実行します。リリース前の品質確認や、大規模な変更後のカバレッジ確認時に使用されます。

**主要な処理内容**：
1. 環境変数 `NUSHELL_CARGO_PROFILE=ci` を設定
2. cargo-llvm-covの環境変数を読み込み
3. 既存のカバレッジデータをクリーンアップ
4. ciプロファイルでワークスペース全体をビルド
5. ciプロファイルでワークスペース全体のテストを実行
6. lcov形式でカバレッジレポートを出力

**前後の処理との関連**：事前に `cargo install cargo-llvm-cov` でツールのインストールが必要です。出力された `lcov.info` はVS Codeの Coverage Gutters等のツールで可視化できます。

**影響範囲**：リポジトリルートに `lcov.info` ファイルが生成されます。`target/` ディレクトリにビルド成果物とカバレッジデータが生成されます。

## バッチ種別

カバレッジ計測 / 品質管理

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時 |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動実行 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Rust/Cargo環境 | Rustツールチェーンがインストールされていること |
| cargo-llvm-cov | cargo-llvm-covがインストールされていること |
| LLVMツール | rustup経由でllvm-toolsがインストールされていること |
| ソースコード | Nushellリポジトリのクローンが存在すること |
| シェル環境 | Bash互換シェルが利用可能であること |

### 実行可否判定

- `cargo llvm-cov` コマンドが実行可能であること
- 初回実行時は `cargo llvm-cov clean` の実行確認が必要な場合がある

## 入力仕様

### 入力パラメータ

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

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| リポジトリ全体 | ディレクトリ | Nushellワークスペースのソースコード |
| Cargo.toml | ファイル | ワークスペース設定 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| lcov.info | lcov | カバレッジレポートファイル |
| target/ | ディレクトリ | ビルド成果物とカバレッジデータ |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | lcov.info |
| 出力先 | リポジトリルート |
| 形式 | lcov形式テキストファイル |
| 文字コード | UTF-8 |

## 処理フロー

### 処理シーケンス

```
1. 環境変数設定
   └─ NUSHELL_CARGO_PROFILE=ci を設定
2. リポジトリルートに移動
   └─ スクリプト位置から算出
3. LLVMカバレッジ環境設定
   └─ cargo llvm-cov show-env の出力を source で読み込み
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
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[環境変数設定]
    B --> C[リポジトリルートに移動]
    C --> D[LLVMカバレッジ環境読込]
    D --> E[カバレッジデータクリーン]
    E --> F[ワークスペースビルド]
    F --> G[テスト実行]
    G --> H[レポート生成]
    H --> I[バッチ終了]
```

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

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

本バッチはデータベース操作を行いません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | ツール未インストール | cargo-llvm-covがない場合 | `cargo install cargo-llvm-cov` を実行 |
| 1 | コンパイルエラー | ソースコードに問題がある場合 | ソースコードを修正 |
| 1 | テスト失敗 | テストが失敗した場合 | テストを修正 |
| 1 | 初回実行確認 | 追加ツールのインストール確認待ち | `y` を入力して続行 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0回（自動リトライなし） |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

エラー発生時は出力を確認し、原因に応じて対処してください。初回実行時は `cargo llvm-cov clean` を手動で実行し、追加ツールのインストールを完了させてから再実行することを推奨します。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 全処理を一括実行 |
| コミットタイミング | レポート生成完了時 |
| ロールバック条件 | 自動ロールバックなし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1回（フルカバレッジ計測） |
| 目標処理時間 | 環境依存（数十分〜数時間） |
| メモリ使用量上限 | ビルド＋テスト実行に依存 |

## 排他制御

同一環境での並列実行は非推奨です。カバレッジデータの競合を避けてください。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | 該当なし | コメントのみ |
| 進捗ログ | 各ステップ | cargoの出力 |
| 終了ログ | 該当なし | 特になし |
| エラーログ | エラー発生時 | cargoのエラー出力 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理時間 | 環境依存 | 手動確認 |
| エラー件数 | 1件以上 | 標準エラー出力 |

## 備考

- `--profile=ci` を使用し、デバッグビルドから不要なシンボルを削除してバイナリサイズを削減
- `nu!` マクロを使用するテストのカバレッジも収集するため、環境変数経由でLLVMカバレッジを有効化
- 出力された `lcov.info` は以下のエディタ拡張機能で可視化可能：
  - VS Code: Coverage Gutters
  - Vim: vim-lcov
  - Neovim: nvim-coverage
- 初回実行時はrustupツールチェーンへの追加インストールの確認プロンプトが表示される場合がある
- 環境変数 `NUSHELL_CARGO_PROFILE` は一部の内部テストで参照される
