# バッチ設計書 15-zeitwerk:check

## 概要

本ドキュメントは、Railsフレームワークに含まれるRakeタスク `zeitwerk:check` の設計仕様を記載したものです。このタスクはプロジェクト構造がZeitwerkオートローダーと互換性があるかをチェックします。

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

このバッチは、RailsアプリケーションのコードがZeitwerkオートローダーの命名規則に準拠しているかを検証します。eager loadingを実行することで、すべての定数が正しく読み込めるかを確認します。

**業務上の目的・背景**：Rails 6以降、Zeitwerkがデフォルトのオートローダーとして採用されました。Zeitwerkはファイル名とクラス名/モジュール名の対応に厳格なルールを持っており、これに違反するとロード時にエラーが発生します。このタスクは、アプリケーションのすべてのコードがZeitwerkの規則に準拠しているかを事前にチェックすることで、本番環境でのロードエラーを防止します。特にRails 5以前からのアップグレード時や、新しいファイル追加時に有用です。

**バッチの実行タイミング**：開発時やCI/CDパイプラインで実行されます。特に、Railsアップグレード後、新しいモデル/クラスの追加後、またはファイル名の変更後に実行することを推奨します。

**主要な処理内容**：
1. Railsアプリケーション環境をロード
2. Zeitwerk::Loader.eager_load_allを実行してすべての定数を読み込み
3. autoload_pathsとeager_load_pathsを比較
4. チェックされなかったディレクトリを警告として報告

**前後の処理との関連**：このタスクは独立した検証タスクであり、他のタスクとの依存関係はありません。CIパイプラインの一部として実行されることが推奨されます。

**影響範囲**：読み取り専用のタスクであり、データベースやファイルシステムへの変更は行いません。ただし、eager loadingによりすべてのクラスがメモリにロードされます。

## バッチ種別

検証 / コード品質チェック

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（手動実行またはCI/CD） |
| 実行時刻 | 指定なし |
| 実行曜日 | 指定なし |
| 実行日 | 指定なし |
| トリガー | 手動（bin/rails zeitwerk:check）またはCI/CDパイプライン |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Railsアプリケーション | 有効なRailsプロジェクト内で実行すること |
| Zeitwerk | Zeitwerkがオートローダーとして設定されていること |
| 環境ロード可能 | :environment タスクが正常に完了すること |

### 実行可否判定

Rails環境がロードできれば実行可能です。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | このタスクはパラメータを受け取りません |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| autoload_paths | Ruby Array | オートロード対象のパス一覧 |
| eager_load_paths | Ruby Array | eager load対象のパス一覧 |
| アプリケーションコード | Ruby Files | app/, lib/配下等のRubyファイル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力（STDOUT） | テキスト | 検証結果 |

### 出力ファイル仕様

ファイル出力はありません。標準出力のみです。

出力形式例（成功時）：
```
Hold on, I am eager loading the application.
All is good!
```

出力形式例（チェックされないディレクトリがある場合）：
```
Hold on, I am eager loading the application.

WARNING: The following directories will only be checked if you configure
them to be eager loaded:

  app/services
  lib/custom

You may verify them manually, or add them to config.eager_load_paths
in config/application.rb and run zeitwerk:check again.

Otherwise, all is good!
```

出力形式例（エラー発生時）：
```
Hold on, I am eager loading the application.
expected file app/models/user_account.rb to define constant UserAccount, but didn't
```

## 処理フロー

### 処理シーケンス

```
1. Rails環境のロード（:environment依存タスク）
   └─ アプリケーション初期化処理を実行
2. 開始メッセージの表示
   └─ "Hold on, I am eager loading the application."
3. Rails::ZeitwerkChecker.checkの実行
   └─ Zeitwerk::Loader.eager_load_all を実行
   └─ autoload_pathsとeager_load_pathsの差分を計算
4. 結果の判定
   └─ NameErrorが発生した場合はエラーメッセージを表示してabort
   └─ 未チェックディレクトリがある場合は警告を表示
   └─ 問題なければ"All is good!"を表示
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[Rails環境ロード]
    B --> C[開始メッセージ表示]
    C --> D[ZeitwerkChecker.check実行]
    D --> E{NameError発生?}
    E -->|はい| F[エラーメッセージ表示]
    F --> G[abort終了]
    E -->|いいえ| H{未チェックディレクトリあり?}
    H -->|あり| I[警告メッセージ表示]
    I --> J["Otherwise, all is good!" 表示]
    H -->|なし| K["All is good!" 表示]
    J --> L[バッチ正常終了]
    K --> L
```

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

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

データベース操作はありませんが、:environmentタスクの依存によりデータベース接続が確立される場合があります。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| abort | Zeitwerk::NameError | ファイル名とクラス名が一致しない | ファイル名またはクラス名を修正 |

### リトライ仕様

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

### 障害時対応

1. エラーメッセージを確認
2. 指摘されたファイルのパスとクラス名を確認
3. Zeitwerkの命名規則に従ってファイル名またはクラス名を修正
   - 例: `app/models/user_account.rb` は `UserAccount` クラスを定義する必要がある
4. 再度 `zeitwerk:check` を実行して確認

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | アプリケーションの全クラス数に依存 |
| 目標処理時間 | アプリケーション規模に依存（通常数秒〜数十秒） |
| メモリ使用量上限 | eager loadingにより全クラスがメモリにロードされる |

## 排他制御

排他制御は不要です。読み取り専用のタスクであり、同時実行しても問題ありません。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 標準出力 | 開始時 | "Hold on, I am eager loading the application." |
| 標準出力 | 完了時 | "All is good!" または警告メッセージ |
| エラー出力 | エラー発生時 | NameErrorのメッセージ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 終了コード | 0以外 | CI/CDシステム |

## 備考

- Zeitwerkの命名規則：
  - `app/models/user.rb` → `User`
  - `app/models/admin/user.rb` → `Admin::User`
  - `app/models/html_parser.rb` → `HtmlParser`（アクロニムの場合は`HTMLParser`も可、設定による）
- config.eager_load_pathsに追加されていないディレクトリは検証対象外となります
- 本番環境ではeager_loadが有効になるため、このチェックを通過しないコードは本番デプロイ時にエラーになります
- Rails.root.to_sはエラーメッセージから除去されて表示されます（可読性向上のため）
