test: enforce zeitwerk compliance in ready gate

Author: gildesmarais

Makefile

@@ -58,6 +58,8 @@ lint: lint-ruby lint-js ## Run all linters (Ruby + Frontend) - errors when issue
 lint-ruby: ## Run Ruby linter (RuboCop) - errors when issues found
 	@echo "Running RuboCop linting..."
 	bundle exec rubocop
+	@echo "Running Zeitwerk eager-load check..."
+	bundle exec rake zeitwerk:verify
 	@echo "Running YARD public-method docs check..."
 	bundle exec rake yard:verify_public_docs
 	@echo "Ruby linting complete!"

README.md

@@ -66,6 +66,9 @@ make openapi
 
 Dev URLs: Ruby app at `http://localhost:4000`, frontend dev server at `http://localhost:4001`.
 
+Backend code under the `Html2rss::Web` namespace now lives under `app/web/**`, so Zeitwerk can mirror constant paths directly instead of relying on directory-specific namespace wiring.
+`make ready` also runs `rake zeitwerk:verify`, which eager-loads the app and fails on loader drift early.
+
 ## Make Targets
 
 | Command              | Purpose                                                 |

Rakefile

@@ -139,3 +139,14 @@ namespace :yard do
     puts 'YARD public method documentation check passed.'
   end
 end
+
+namespace :zeitwerk do
+  desc 'Fail when Zeitwerk cannot eager load the app tree cleanly'
+  task :verify do
+    ENV['RACK_ENV'] ||= 'test'
+    require_relative 'app'
+
+    Html2rss::Web::Boot.eager_load!
+    puts 'Zeitwerk eager load check passed.'
+  end
+end

spec/html2rss/web/app_integration_spec.rb

@@ -7,7 +7,7 @@
 require 'securerandom'
 require_relative '../../../app'
 
-RSpec.describe Html2rss::Web::App do # rubocop:disable RSpec/MultipleMemoizedHelpers
+RSpec.describe Html2rss::Web::App, :aggregate_failures do # rubocop:disable RSpec/MultipleMemoizedHelpers
   include Rack::Test::Methods
 
   let(:app) { described_class.freeze.app }
@@ -75,7 +75,7 @@
   end
 
   describe 'GET /api/v1/feeds/:token' do # rubocop:disable RSpec/MultipleMemoizedHelpers
-    it 'returns unauthorized for invalid tokens', :aggregate_failures do
+    it 'returns unauthorized for invalid tokens' do
       allow(Html2rss::Web::FeedToken).to receive(:decode).and_return(nil)
 
       get '/api/v1/feeds/invalid-token', {}, { 'HTTP_ACCEPT' => 'application/xml' }
@@ -85,7 +85,7 @@
       expect(last_response.body).to include('Invalid token')
     end
 
-    it 'renders the XML feed with cache headers', :aggregate_failures do
+    it 'renders the XML feed with cache headers' do
       get "/api/v1/feeds/#{feed_token}", {}, { 'HTTP_HOST' => 'localhost:3000', 'HTTP_ACCEPT' => 'application/xml' }
 
       expect(last_response.status).to eq(200)
@@ -96,7 +96,7 @@
       expect(last_response.body).to eq('<rss version="2.0"></rss>')
     end
 
-    it 'accepts URL-escaped public feed tokens', :aggregate_failures do
+    it 'accepts URL-escaped public feed tokens' do
       padded_feed_token = 'signed-public-token='
       encoded_padded_feed_token = CGI.escape(padded_feed_token)
 
@@ -108,53 +108,53 @@
       expect(last_response.headers['Content-Type']).to eq('application/xml')
     end
 
-    it 'renders the JSON feed when requested by extension', :aggregate_failures do
+    it 'renders the JSON feed when requested by extension' do
       get "/api/v1/feeds/#{feed_token}.json"
 
       expect(last_response.status).to eq(200)
       expect(last_response.headers['Content-Type']).to eq('application/feed+json')
     end
 
-    it 'renders the JSON feed when requested through Accept', :aggregate_failures do
+    it 'renders the JSON feed when requested through Accept' do
       get "/api/v1/feeds/#{feed_token}", {}, { 'HTTP_ACCEPT' => 'application/feed+json' }
       expect([last_response.status, last_response.headers['Content-Type']]).to eq([200, 'application/feed+json'])
       expect(last_response.headers['Cache-Control']).to include('max-age=600')
       expect(last_response.headers['Vary']).to include('Accept')
     end
 
-    it 'prefers the path extension over Accept negotiation', :aggregate_failures do
+    it 'prefers the path extension over Accept negotiation' do
       header 'Accept', 'application/feed+json'
       get "/api/v1/feeds/#{feed_token}.xml"
 
       expect(last_response.status).to eq(200)
       expect(last_response.headers['Content-Type']).to eq('application/xml')
     end
 
-    it 'honors Accept quality values for feed negotiation', :aggregate_failures do
+    it 'honors Accept quality values for feed negotiation' do
       header 'Accept', 'application/xml;q=1.0, application/feed+json;q=0.2'
       get "/api/v1/feeds/#{feed_token}"
 
       expect(last_response.status).to eq(200)
       expect(last_response.headers['Content-Type']).to eq('application/xml')
     end
 
-    it 'treats wildcard Accept as rss unless json is more specific', :aggregate_failures do
+    it 'treats wildcard Accept as rss unless json is more specific' do
       header 'Accept', '*/*'
       get "/api/v1/feeds/#{feed_token}"
 
       expect(last_response.status).to eq(200)
       expect(last_response.headers['Content-Type']).to eq('application/xml')
     end
 
-    it 'ignores q=0 json feed media types during negotiation', :aggregate_failures do
+    it 'ignores q=0 json feed media types during negotiation' do
       header 'Accept', 'application/feed+json;q=0, application/xml;q=0.4'
       get "/api/v1/feeds/#{feed_token}"
 
       expect(last_response.status).to eq(200)
       expect(last_response.headers['Content-Type']).to eq('application/xml')
     end
 
-    it 'serves HEAD requests for token feeds with negotiated headers only', :aggregate_failures do
+    it 'serves HEAD requests for token feeds with negotiated headers only' do
       head "/api/v1/feeds/#{feed_token}", {}, { 'HTTP_ACCEPT' => 'application/feed+json' }
 
       expect(last_response.status).to eq(200)
@@ -163,7 +163,7 @@
       expect(last_response.body).to eq('')
     end
 
-    it 'ignores query param strategy overrides', :aggregate_failures do
+    it 'ignores query param strategy overrides' do
       header 'Accept', 'application/xml'
       get "/api/v1/feeds/#{feed_token}", { 'strategy' => 'invalid' }
 
@@ -227,7 +227,7 @@ def stub_escaped_feed_token(raw_token:, encoded_token:)
     context 'without authentication' do # rubocop:disable RSpec/MultipleMemoizedHelpers
       before { allow(Html2rss::Web::Auth).to receive(:authenticate).and_return(nil) }
 
-      it 'requires authentication', :aggregate_failures do
+      it 'requires authentication' do
         post '/api/v1/feeds', request_payload.to_json, json_headers
 
         expect(last_response.status).to eq(401)
@@ -239,15 +239,15 @@ def stub_escaped_feed_token(raw_token:, encoded_token:)
     context 'with authenticated account' do # rubocop:disable RSpec/MultipleMemoizedHelpers
       before { allow(Html2rss::Web::Auth).to receive(:authenticate).and_return(account) }
 
-      it 'returns bad request when JSON payload is invalid', :aggregate_failures do
+      it 'returns bad request when JSON payload is invalid' do
         post '/api/v1/feeds', '{ invalid', json_headers
 
         expect(last_response.status).to eq(400)
         expect(last_response.content_type).to include('application/json')
         expect(json_body).to include('error' => include('message' => 'Invalid JSON payload'))
       end
 
-      it 'returns bad request when URL is missing', :aggregate_failures do
+      it 'returns bad request when URL is missing' do
         allow(Html2rss::Web::Api::V1::FeedMetadata).to receive(:site_title_for).and_return('Example')
 
         post '/api/v1/feeds', request_payload.merge(url: '').to_json, auth_headers
@@ -258,7 +258,7 @@ def stub_escaped_feed_token(raw_token:, encoded_token:)
         )
       end
 
-      it 'returns forbidden when URL is not allowed for account', :aggregate_failures do
+      it 'returns forbidden when URL is not allowed for account' do
         allow(Html2rss::Web::UrlValidator).to receive(:url_allowed?).and_return(false)
 
         post '/api/v1/feeds', request_payload.to_json, auth_headers
@@ -269,7 +269,7 @@ def stub_escaped_feed_token(raw_token:, encoded_token:)
         )
       end
 
-      it 'returns bad request for unsupported strategy', :aggregate_failures do
+      it 'returns bad request for unsupported strategy' do
         post '/api/v1/feeds', request_payload.merge(strategy: 'unsupported').to_json, auth_headers
 
         expect(last_response.status).to eq(400)
@@ -278,7 +278,7 @@ def stub_escaped_feed_token(raw_token:, encoded_token:)
         )
       end
 
-      it 'returns error when feed creation fails', :aggregate_failures do
+      it 'returns error when feed creation fails' do
         allow(Html2rss::Web::AutoSource).to receive(:create_stable_feed).and_return(nil)
 
         post '/api/v1/feeds', request_payload.to_json, auth_headers
@@ -289,7 +289,7 @@ def stub_escaped_feed_token(raw_token:, encoded_token:)
         )
       end
 
-      it 'returns created feed metadata', :aggregate_failures do
+      it 'returns created feed metadata' do
         post '/api/v1/feeds', request_payload.to_json, auth_headers
 
         expect(last_response.status).to eq(201)

spec/html2rss/web/app_spec.rb

@@ -77,20 +77,20 @@ def service_error_response_tuple(path)
 
   it { expect(described_class).to be < Roda }
 
-  context 'with Rack::Test' do
+  context 'with Rack::Test', :aggregate_failures do
     include Rack::Test::Methods
 
     def app = described_class
 
-    it 'serves the homepage with core security headers', :aggregate_failures do
+    it 'serves the homepage with core security headers' do
       get '/'
 
       expect(last_response).to be_ok
       expect(last_response.headers['Content-Security-Policy']).to include("default-src 'none'")
       expect(last_response.headers['Strict-Transport-Security']).to include('max-age=31536000')
     end
 
-    it 'serves static feed routes with caching headers', :aggregate_failures do
+    it 'serves static feed routes with caching headers' do
       stub_static_feed
 
       get '/legacy'
@@ -103,7 +103,7 @@ def app = described_class
       expect(last_response.body).to eq('<rss/>')
     end
 
-    it 'serves static json feed routes when json is requested by extension', :aggregate_failures do
+    it 'serves static json feed routes when json is requested by extension' do
       stub_static_feed
       get '/legacy.json'
 
@@ -112,7 +112,7 @@ def app = described_class
       )
     end
 
-    it 'serves HEAD requests for static feed routes with negotiated headers only', :aggregate_failures do
+    it 'serves HEAD requests for static feed routes with negotiated headers only' do
       stub_static_feed
       head '/legacy'
 
@@ -122,7 +122,14 @@ def app = described_class
       expect(last_response.body).to eq('')
     end
 
-    it 'coerces string ttl values before cache expiry math', :aggregate_failures do
+    it 'returns method not allowed for unsupported verbs on token feed routes' do
+      post '/api/v1/feeds/test-token'
+
+      expect(last_response.status).to eq(405)
+      expect(last_response.headers['Allow']).to eq('GET')
+    end
+
+    it 'coerces string ttl values before cache expiry math' do
       stub_static_feed(ttl: '180')
 
       get '/legacy'
@@ -131,7 +138,7 @@ def app = described_class
       expect(last_response.headers['Cache-Control']).to include('max-age=10800')
     end
 
-    it 'renders XML error when static feed generation fails', :aggregate_failures do
+    it 'renders XML error when static feed generation fails' do
       allow(Html2rss::Web::XmlBuilder).to receive(:build_error_feed).and_return('<error/>')
 
       get '/missing-feed'
@@ -141,7 +148,7 @@ def app = described_class
       expect(last_response.body).to eq('<error/>')
     end
 
-    it 'renders JSON Feed-shaped errors when static json feed generation fails', :aggregate_failures do
+    it 'renders JSON Feed-shaped errors when static json feed generation fails' do
       get '/missing-feed.json'
 
       expect(json_feed_error_tuple).to eq(
@@ -150,15 +157,15 @@ def app = described_class
       )
     end
 
-    it 'renders service failures as non-cacheable xml feed errors', :aggregate_failures do
+    it 'renders service failures as non-cacheable xml feed errors' do
       stub_static_service_error('legacy-service-error')
 
       expect(service_error_response_tuple('/legacy-service-error')).to eq(
         [500, 'application/xml', %w[max-age=0 must-revalidate no-cache no-store private], '<error/>']
       )
     end
 
-    it 'hides unexpected internal error details from API responses', :aggregate_failures do
+    it 'hides unexpected internal error details from API responses' do
       allow(Html2rss::Web::Routes::ApiV1).to receive(:call).and_raise(StandardError, 'boom')
 
       get '/api/v1'