# バッチ設計書 11-toolkit clippy

## 概要

本ドキュメントは、Nushellプロジェクトにおける`toolkit clippy`コマンドのバッチ設計書です。Rust言語の静的解析ツールであるClippyを使用して、コード品質チェックを実行するコマンドの仕様を定義します。

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

`toolkit clippy`は、Nushellのソースコード全体に対してClippyによる静的解析を実行し、コードの品質問題や潜在的なバグを検出するバッチ処理です。

**業務上の目的・背景**：Rustプロジェクトにおいて、コンパイラが検出しない潜在的な問題（不要なコード、非効率なパターン、バグの可能性があるコード）を早期に発見することが重要です。Clippyはこれらの問題を検出し、コードの品質を維持・向上させるために使用されます。PR提出前のチェックとして、チーム全体で一貫した品質基準を維持するために本バッチが必要です。

**バッチの実行タイミング**：開発者がコード変更を行った後、PR提出前に手動で実行します。また、`toolkit check pr`の一部として自動的に実行されます。CI/CDパイプラインでも実行されます。

**主要な処理内容**：
1. ワークスペース全体（プラグインを除く）に対してClippyを実行
2. テストコードに対してClippyを実行（unwrap使用の許可あり）
3. プラグインパッケージに対してClippyを実行

**前後の処理との関連**：`toolkit check pr`コマンドの一部として、`toolkit fmt`の後に実行されます。clippyチェック成功後に`toolkit test`が実行されます。

**影響範囲**：Nushellワークスペース全体のRustソースコード。ビルド成果物やソースコードの変更は行いません（読み取り専用の静的解析）。

## バッチ種別

コード品質チェック / 静的解析

## 実行スケジュール

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

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Rust環境 | Rustツールチェーンがインストールされていること |
| Clippyコンポーネント | `rustup component add clippy`でClippyがインストールされていること |
| Nushell環境 | Nushellがインストールされ、toolkitモジュールが利用可能であること |
| プロジェクトディレクトリ | Nushellプロジェクトのルートディレクトリで実行すること |

### 実行可否判定

Cargoプロジェクトとして正常にビルドできる状態であれば実行可能。コンパイルエラーがある場合は、Clippy実行前にエラーが発生します。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| --verbose | flag | No | false | 追加の進捗情報を表示する |
| --features | list<string> | No | [] | Clippyを実行する機能のリスト |

### 入力データソース

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

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | Clippy警告・エラーメッセージ |
| 標準エラー出力 | テキスト | エラーメッセージ |

### 出力ファイル仕様

ファイル出力はありません（コンソール出力のみ）。

## 処理フロー

### 処理シーケンス

```
1. verboseモードの場合、実行開始メッセージを表示
   └─ "running `toolkit clippy`"を出力

2. ワークスペース全体のClippyチェック実行
   └─ cargo clippy --workspace --exclude nu_plugin_* --features {features}
   └─ -D warnings -D clippy::unwrap_used -D clippy::unchecked_duration_subtraction

3. テストコードのClippyチェック実行
   └─ cargo clippy --tests --workspace --exclude nu_plugin_*
   └─ -D warnings（unwrap_usedは除外）

4. プラグインのClippyチェック実行
   └─ cargo clippy --package nu_plugin_*
   └─ -D warnings -D clippy::unwrap_used -D clippy::unchecked_duration_subtraction

5. エラー発生時は修正を促すメッセージを表示して終了
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B{verbose?}
    B -->|Yes| C[進捗メッセージ表示]
    B -->|No| D[ワークスペースClippy実行]
    C --> D
    D --> E{エラー発生?}
    E -->|Yes| F[エラーメッセージ表示]
    F --> G[異常終了]
    E -->|No| H[テストコードClippy実行]
    H --> I{エラー発生?}
    I -->|Yes| F
    I -->|No| J[プラグインClippy実行]
    J --> K{エラー発生?}
    K -->|Yes| F
    K -->|No| L[正常終了]
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Clippy警告 | コードスタイル違反検出 | 指摘箇所を修正する |
| - | unwrap_used | .unwrap()の使用検出 | expect()またはエラーハンドリングに置き換え |
| - | unchecked_duration_subtraction | 期間計算の未チェック | checked_subを使用する |
| - | コンパイルエラー | 構文エラー等 | ソースコードのエラーを修正する |

### リトライ仕様

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

### 障害時対応

Clippyエラーが発生した場合、出力されたエラーメッセージに従ってソースコードを修正し、再度`toolkit clippy`を実行します。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし（読み取り専用） |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | プロジェクト全体のRustファイル |
| 目標処理時間 | 数分〜10分程度（環境依存） |
| メモリ使用量上限 | Cargoビルドに依存 |

## 排他制御

同一ディレクトリでの複数Cargo操作は競合する可能性があります。Cargo.lockによるファイルロックが使用されます。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | verbose時のバッチ開始時 | "running `toolkit clippy`" |
| 進捗ログ | 各フェーズ開始時（verbose） | 対象フェーズ名 |
| エラーログ | エラー発生時 | Clippyエラーメッセージ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理時間 | CI/CDタイムアウト設定に依存 | CI/CDシステム |
| エラー件数 | 1件以上でビルド失敗 | CI/CD通知 |

## 備考

- CI設定ファイル（`.github/workflows/ci.yml`）と同一の設定を使用しています
- テストコードでは`unwrap()`の使用が許可されています（テスト専用の緩和設定）
- プラグインは個別のパッケージとして検査されます
