# バッチ設計書 8-coverage-local.nu

## 概要

本ドキュメントは、コードカバレッジを生成してlcov.infoを出力するNushellスクリプト `coverage-local.nu` のバッチ設計書です。Nushell環境で実行可能なカバレッジ計測バッチとして設計されていますが、現在は非推奨となっており、`toolkit cov` コマンドの使用が推奨されています。

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

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

**業務上の目的・背景**：コード品質の維持・向上のため、テストがどの程度コードをカバーしているかを計測する必要があります。`coverage-local.sh` と同等の機能をNushellスクリプトで提供し、Nushellユーザーにとって馴染みやすいインターフェースを提供します。ただし、現在は `toolkit cov` コマンドへの移行が推奨されており、本スクリプトは非推奨（deprecated）です。

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

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

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

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

## バッチ種別

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

## 実行スケジュール

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

## 実行条件

### 前提条件

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

### 実行可否判定

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

## 入力仕様

### 入力パラメータ

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

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| $env.CURRENT_FILE | 環境変数 | スクリプト自身のパス |
| リポジトリ全体 | ディレクトリ | Nushellワークスペースのソースコード |
| Cargo.toml | ファイル | ワークスペース設定 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| lcov.info | lcov | カバレッジレポートファイル |
| target/ | ディレクトリ | ビルド成果物とカバレッジデータ |
| 標準出力 | テキスト | 進捗メッセージと処理時間 |

### 出力ファイル仕様

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

## 処理フロー

### 処理シーケンス

```
1. 開始時刻記録
   └─ date now で現在時刻を取得
2. 環境変数設定
   └─ $env.NUSHELL_CARGO_PROFILE = "ci"
3. 非推奨警告出力
   └─ "coverage-local.nu will be deprecated" メッセージ
4. カバレッジ計測処理（compute-coverage関数）
   └─ 4.1 リポジトリルートに移動
   └─ 4.2 cargo llvm-cov show-env をTOML形式でパースして環境変数に読込
   └─ 4.3 cargo llvm-cov clean --workspace
   └─ 4.4 cargo build --workspace --profile=ci
   └─ 4.5 cargo test --workspace --profile=ci
   └─ 4.6 cargo llvm-cov report --lcov --output-path lcov.info --profile=ci
5. 終了時刻記録
   └─ date now で現在時刻を取得
6. 処理時間出力
   └─ 開始時刻と終了時刻の差分を表示
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[開始時刻記録]
    B --> C[環境変数設定]
    C --> D[非推奨警告出力]
    D --> E[compute-coverage関数呼出]
    E --> F[LLVM環境変数読込]
    F --> G[カバレッジデータクリーン]
    G --> H[ワークスペースビルド]
    H --> I[テスト実行]
    I --> J[レポート生成]
    J --> K[終了時刻記録]
    K --> L[処理時間出力]
    L --> M[バッチ終了]
```

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

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

### 障害時対応

エラー発生時はNushellの標準エラー処理により停止します。出力を確認し、原因に応じて対処してください。

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

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

## パフォーマンス要件

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

## 排他制御

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

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 警告ログ | バッチ開始時 | 非推奨警告メッセージ |
| 進捗ログ | 各ステップ | "Setting up environment variables for coverage" 等 |
| 終了ログ | バッチ終了時 | "Coverage generation took {duration}." |
| エラーログ | エラー発生時 | Nushellのエラー出力 |

## 監視・アラート

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

## 備考

- **非推奨（Deprecated）**：本スクリプトは非推奨です。代わりに `toolkit cov` コマンドを使用してください
- `std/log` モジュールの `warning` 関数を使用して非推奨警告を出力します
- Windows環境では `cargo llvm-cov show-env` の出力に含まれる `"C:\..."` 形式のパスがエスケープシーケンスとして解釈されないよう、ダブルクォートをシングルクォートに置換してからTOMLとしてパースします
- `date now` を使用して処理時間を計測し、終了時に表示します
- `$env.CURRENT_FILE` を使用してスクリプトの位置からリポジトリルートを算出します
- 出力された `lcov.info` は以下のエディタ拡張機能で可視化可能：
  - VS Code: Coverage Gutters
  - Vim: vim-lcov
  - Neovim: nvim-coverage
