Fix for wrong name of file that broke zeitwerk

Author: etewiah

app/jobs/pwb/zoho/base_job.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative '../../../services/pwb/zoho/errors'
+require_relative '../../../services/pwb/zoho/error'
 
 module Pwb
   module Zoho

app/services/pwb/zoho/client.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-# Load error classes explicitly since they don't follow zeitwerk naming convention
-require_relative 'errors'
+# Load error classes explicitly
+require_relative 'error'
 
 module Pwb
   module Zoho

app/services/pwb/zoho/errors.rb app/services/pwb/zoho/error.rbapp/services/pwb/zoho/errors.rb renamed to app/services/pwb/zoho/error.rb

@@ -0,0 +1,137 @@
+# Zeitwerk Naming Convention Fix
+
+**Date**: 2026-01-09  
+**Issue**: Staging environment failed to boot with `uninitialized constant Pwb::Zoho::Errors`  
+**Status**: ✅ Fixed
+
+## Problem
+
+The app crashed when starting in staging environment (where eager_load is enabled):
+
+```
+uninitialized constant Pwb::Zoho::Errors (NameError)
+```
+
+But it worked fine in development and all tests passed! ❌
+
+## Root Cause
+
+**Zeitwerk file naming mismatch**:
+
+| File Name | Expected Constant | Actual Constant | Result |
+|-----------|-------------------|-----------------|--------|
+| `errors.rb` | `Errors` (module) | `Error` (class) | ❌ Mismatch |
+| `error.rb` | `Error` (class) | `Error` (class) | ✅ Match |
+
+Zeitwerk's autoloader expects:
+- `errors.rb` → defines `Errors` module/class
+- `error.rb` → defines `Error` class
+
+Our file was named `errors.rb` but defined `Error` class (and subclasses).
+
+## Why Tests Didn't Catch This
+
+1. **Test environment doesn't eager load by default**
+   ```ruby
+   # config/environments/test.rb
+   config.eager_load = false  # Default setting
+   ```
+
+2. **Development uses autoloading**
+   - Files load on-demand (lazy loading)
+   - If code never references `Pwb::Zoho::Errors`, file never loads
+   - No error occurs
+
+3. **Staging/Production use eager loading**
+   - ALL files loaded at boot (for performance)
+   - Zeitwerk validates all file/constant name mappings
+   - Mismatch causes immediate error
+
+4. **No eager load validation test**
+   - Tests never validated that eager_load works
+
+## The Fix
+
+### 1. Renamed the File
+```bash
+mv app/services/pwb/zoho/errors.rb app/services/pwb/zoho/error.rb
+```
+
+### 2. Updated require_relative References
+```ruby
+# app/jobs/pwb/zoho/base_job.rb
+# Before:
+require_relative '../../../services/pwb/zoho/errors'
+
+# After:
+require_relative '../../../services/pwb/zoho/error'
+```
+
+```ruby
+# app/services/pwb/zoho/client.rb
+# Before:
+require_relative 'errors'
+
+# After:
+require_relative 'error'
+```
+
+### 3. Added Eager Load Test
+Created `spec/zeitwerk_spec.rb`:
+```ruby
+RSpec.describe 'Zeitwerk eager loading' do
+  it 'eager loads all constants without errors' do
+    expect { Rails.application.eager_load! }.not_to raise_error
+  end
+end
+```
+
+This test will catch similar issues in the future!
+
+## Files Changed
+
+- ✅ Renamed: `app/services/pwb/zoho/errors.rb` → `error.rb`
+- ✅ Updated: `app/jobs/pwb/zoho/base_job.rb`
+- ✅ Updated: `app/services/pwb/zoho/client.rb`
+- ✅ Created: `spec/zeitwerk_spec.rb`
+
+## Verification
+
+```bash
+# Test passes
+bundle exec rspec spec/zeitwerk_spec.rb
+# 2 examples, 0 failures ✅
+
+# Staging boots
+RAILS_ENV=staging rails runner "puts 'Success!'"
+# Staging boots successfully! ✅
+```
+
+## Prevention
+
+The new `spec/zeitwerk_spec.rb` test will now catch these issues:
+
+- File naming mismatches (e.g., `errors.rb` with `Error` class)
+- Missing module definitions
+- Circular dependencies
+- Other autoloading issues that only appear in production
+
+**Always run the full test suite before deploying!**
+
+## Zeitwerk Naming Rules (Reference)
+
+| File Path | Must Define |
+|-----------|-------------|
+| `app/models/user.rb` | `User` class |
+| `app/models/users.rb` | `Users` module |
+| `app/services/billing/error.rb` | `Billing::Error` |
+| `app/services/billing/errors.rb` | `Billing::Errors` |
+| `app/controllers/api/v1/users_controller.rb` | `Api::V1::UsersController` |
+
+**Rule**: File name must match the constant name (singular/plural matters!)
+
+---
+
+**Status**: ✅ Fixed and Protected
+
+This type of issue will now be caught in tests before it reaches staging/production!

docs/ZEITWERK_FIX.md

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.describe 'Zeitwerk eager loading' do
+  # This test ensures all constants can be eager loaded without errors.
+  # It catches file naming issues that only appear in production/staging
+  # where eager_load is enabled.
+  #
+  # Common issues caught:
+  # - File named `errors.rb` but defines `Error` class (should be `error.rb`)
+  # - File named `user.rb` but defines `Users` module (should be `users.rb`)
+  # - Missing module definitions
+  # - Circular dependencies
+  #
+  it 'eager loads all constants without errors' do
+    expect { Rails.application.eager_load! }.not_to raise_error
+  end
+
+  # Verify Zeitwerk is actually configured
+  it 'uses Zeitwerk for autoloading' do
+    expect(Rails.autoloaders.zeitwerk_enabled?).to be true
+  end
+end