# バッチ設計書 10-toolkit-fmt

## 概要

本ドキュメントは、コードフォーマットをチェックまたは適用するNushellコマンド `toolkit fmt` のバッチ設計書です。Nushellプロジェクトの開発ツールキットの一部として、Rustコードのフォーマット統一を担当します。

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

このバッチは、Nushellプロジェクト全体のRustコードに対して `cargo fmt` を実行し、コードフォーマットを統一します。`--check` オプションを使用することで、フォーマット変更を適用せずに構文のみをチェックすることも可能です。PR提出前のコード品質チェックの第一段階として使用されます。

**業務上の目的・背景**：チーム開発において、コードのフォーマットを統一することは可読性とメンテナンス性の向上に不可欠です。Rustコミュニティでは `rustfmt` によるフォーマット統一が標準的であり、本コマンドはそれをNushellのtoolkit経由で簡単に実行できるようにします。CI/CDパイプラインやPRレビューでフォーマットの一貫性を強制し、コードレビューでのフォーマット指摘を削減します。

**バッチの実行タイミング**：コード変更後のローカルチェック時、PR提出前の品質確認時、CI/CDパイプラインでの自動チェック時に実行します。

**主要な処理内容**：
1. `--check` オプション指定時：`cargo fmt --all -- --check` でフォーマットチェックのみ実行
2. オプションなし時：`cargo fmt --all` でフォーマットを適用
3. チェックモードで不一致がある場合、エラーメッセージを出力して終了

**前後の処理との関連**：`toolkit check pr` コマンドの最初のステップとして実行されます。フォーマットチェック後、`toolkit clippy` によるコード品質チェック、`toolkit test` によるテスト実行が続きます。

**影響範囲**：フォーマット適用時は、ワークスペース内の全Rustソースファイルが変更される可能性があります。

## バッチ種別

コードフォーマット / 品質管理

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時 |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動実行 / CI/CDパイプライン |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Nushell環境 | Nushellがインストールされていること |
| Rust/Cargo環境 | Rustツールチェーンがインストールされていること |
| rustfmt | rustfmtがインストールされていること（通常はRustに含まれる） |
| ソースコード | Nushellリポジトリのクローンが存在すること |

### 実行可否判定

- `nu` コマンドが実行可能であること
- `cargo fmt` コマンドが実行可能であること

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| --check | フラグ | No | false | フォーマット変更を適用せず、チェックのみ行う |
| --verbose | フラグ | No | false | 追加情報を出力する |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| ワークスペース全体 | ディレクトリ | 全Rustソースファイル |
| rustfmt.toml | ファイル | フォーマット設定（存在する場合） |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| Rustソースファイル | *.rs | フォーマット適用時に変更 |
| 標準出力 | テキスト | 進捗メッセージ（verbose時） |
| 標準エラー | テキスト | エラーメッセージ（チェック失敗時） |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| 対象ファイル | ワークスペース内の全 *.rs ファイル |
| 変更内容 | インデント、空白、改行などのフォーマット |
| フォーマット規則 | rustfmt デフォルト設定 + rustfmt.toml |

## 処理フロー

### 処理シーケンス

```
1. オプション解析
   └─ --check, --verbose フラグの確認
2. verbose出力（オプション）
   └─ "running `toolkit fmt`" メッセージ
3. フォーマット実行
   └─ --check時: cargo fmt --all -- --check
   └─ 通常時: cargo fmt --all
4. 結果判定
   └─ 成功: 正常終了
   └─ 失敗（--check時）: エラーメッセージ出力
```

### フローチャート

```mermaid
flowchart TD
    A[コマンド開始] --> B{--verbose?}
    B -->|Yes| C[進捗メッセージ出力]
    B -->|No| D{--check?}
    C --> D
    D -->|Yes| E[cargo fmt --all -- --check]
    D -->|No| F[cargo fmt --all]
    E --> G{チェック成功?}
    F --> H[コマンド終了]
    G -->|Yes| H
    G -->|No| I[エラーメッセージ出力]
    I --> J[エラー終了]
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | フォーマット不一致 | --checkでフォーマット差分がある場合 | `toolkit fmt` を実行してフォーマット適用 |
| 1 | rustfmt未インストール | rustfmtがない場合 | `rustup component add rustfmt` を実行 |
| 1 | パース エラー | Rustコードに構文エラーがある場合 | ソースコードを修正 |

### リトライ仕様

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

### 障害時対応

フォーマットチェック失敗時は、エラーメッセージに "please run `toolkit fmt` to fix formatting!" と表示されます。`toolkit fmt`（--checkなし）を実行してフォーマットを適用してください。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 全ファイル一括 |
| コミットタイミング | cargo fmt 完了時 |
| ロールバック条件 | 自動ロールバックなし（gitで復元可能） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | ワークスペース内の全Rustファイル |
| 目標処理時間 | 数秒〜数十秒 |
| メモリ使用量上限 | 最小限 |

## 排他制御

同一環境での並列実行は非推奨です。同じファイルに対する同時変更を避けてください。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | verbose時 | "running `toolkit fmt`" |
| 進捗ログ | 該当なし | cargoの出力に依存 |
| 終了ログ | 該当なし | 特になし |
| エラーログ | チェック失敗時 | "please run `toolkit fmt` to fix formatting!" |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| チェック結果 | 失敗 | 標準エラー出力 |
| 処理時間 | 1分以上 | 手動確認 |

## 備考

- `cargo fmt --all` はワークスペース内の全クレートに対してフォーマットを実行
- `-- --check` オプションは cargo fmt への引数として渡され、変更を適用せずにチェックのみ行う
- `pretty-format-command` ヘルパー関数を使用して、エラーメッセージ内のコマンドをバッククォートで囲んでフォーマット
- `toolkit check pr` の最初のステップとして自動実行される
- PR提出前には必ず `toolkit fmt` を実行し、フォーマットの一貫性を確保することが推奨される
- CIの設定（.github/workflows/ci.yml）でも同様のチェックが行われる
- `error make --unspanned` を使用してスパン情報なしのエラーを生成
