feat: migrate to zeitwerk (#878)

This pull request introduces a major refactor of the backend code
structure to adopt the Zeitwerk autoloader, improves backend
maintainability, and updates development and linting workflows. It
removes manual requires and directory-specific namespace wiring,
reorganizes files under the `app/web/**` directory, and ensures that all
code is autoloaded in a consistent, Rails-like fashion. Additionally, it
adds a Zeitwerk eager-load check to the linting process and updates
documentation accordingly. Several files are renamed or removed to
reflect the new structure, and some error-handling and validation logic
is refactored for clarity and consistency.

**Backend autoloading and structure improvements:**

- Introduced the `zeitwerk` gem and removed the `rack-unreloader` gem,
enabling Zeitwerk-based autoloading for backend code under the
`Html2rss::Web` namespace, and updated `app.rb` to use
`Html2rss::Web::Boot` for setup and eager loading.
[[1]](diffhunk://#diff-d09ea66f8227784ff4393d88a19836f321c915ae10031d16c93d67e6283ab55fR20-L25)
[[2]](diffhunk://#diff-f965f92b425fb2f75d38b491b2625fe21b8af20b7666217546bce8a42b198ea4L9-R12)
- Moved backend files into the `app/web/**` directory to match
Zeitwerk's expectations, and removed manual `require` statements in
favor of autoloading.
[[1]](diffhunk://#diff-f965f92b425fb2f75d38b491b2625fe21b8af20b7666217546bce8a42b198ea4L9-R12)
[[2]](diffhunk://#diff-17e1b7bf4af1869b4be3173dde8b6bffaff1e1e2a6e767b728c9a9f3685d490fL1-L52)
[[3]](diffhunk://#diff-02e7c9c52be0b12bd7c0a8910a098e50de253b9654172526667dec2bfdba4970L1-L57)
[[4]](diffhunk://#diff-884604050285643eb6fb29195c6342cd73a3abae7f3acba5b1bbc41a196d31e3L1-L70)
[[5]](diffhunk://#diff-9df4f6ed17ac1a74c68891a27d537de8e617e0b99e7803fbf42ab523a7043bb6L1-L158)
[[6]](diffhunk://#diff-f2b0bbe2a08fb1204f3985f426ee5aeda21d24f8d4b598e4162b43d87649b674L3-R11)
[[7]](diffhunk://#diff-0764627d99177e329667ae8f5c98c756ac3d8ae43bdf768b3af26403f713e281L6-R15)

**Development and linting workflow updates:**

- Added a Zeitwerk eager-load verification task (`rake zeitwerk:verify`)
to the `Makefile` linting process and as part of `make ready`, ensuring
loader drift is caught early in development.
[[1]](diffhunk://#diff-76ed074a9305c04054cdebb9e9aad2d818052b07091de1f20cad0bbac34ffb52R61-R62)
[[2]](diffhunk://#diff-ee98e028c59b193d58fde56ab4daf54d43c486ae674e63d50ddf300b07943e0fR142-R152)
[[3]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R69-R72)

**Error handling and validation refactoring:**

- Updated error handling in API modules to reference error classes via
the fully qualified `Html2rss::Web` namespace, and refactored validation
logic in `CreateFeed` for clarity and maintainability.
[[1]](diffhunk://#diff-0764627d99177e329667ae8f5c98c756ac3d8ae43bdf768b3af26403f713e281L44-R43)
[[2]](diffhunk://#diff-0764627d99177e329667ae8f5c98c756ac3d8ae43bdf768b3af26403f713e281L60-R80)
[[3]](diffhunk://#diff-0764627d99177e329667ae8f5c98c756ac3d8ae43bdf768b3af26403f713e281R90-R95)
[[4]](diffhunk://#diff-0764627d99177e329667ae8f5c98c756ac3d8ae43bdf768b3af26403f713e281L112-R123)
[[5]](diffhunk://#diff-0764627d99177e329667ae8f5c98c756ac3d8ae43bdf768b3af26403f713e281L134-R141)

**Roda plugin and middleware changes:**

- Added the `:head` and `:not_allowed` plugins to Roda configuration,
improving HTTP method handling.

**Documentation updates:**

- Updated `README.md` to explain the new backend file structure,
Zeitwerk integration, and contributor guidelines for backend code
placement.

Author: gildesmarais

Gemfile

@@ -17,12 +17,12 @@ gem 'rack-cache'
 gem 'rack-timeout'
 gem 'roda'
 gem 'ssrf_filter'
+gem 'zeitwerk'
 
 gem 'puma', require: false
 
 group :development do
   gem 'byebug'
-  gem 'rack-unreloader'
   gem 'rake', require: false
   gem 'rubocop', require: false
   gem 'rubocop-performance', require: false

Gemfile.lock

@@ -246,7 +246,6 @@ GEM
     rack-test (2.2.0)
       rack (>= 1.3)
     rack-timeout (0.7.0)
-    rack-unreloader (2.1.0)
     rails-dom-testing (2.3.0)
       activesupport (>= 5.0.0)
       minitest
@@ -375,7 +374,6 @@ DEPENDENCIES
   rack-cache
   rack-test
   rack-timeout
-  rack-unreloader
   rake
   roda
   rspec
@@ -393,6 +391,7 @@ DEPENDENCIES
   vcr
   webmock
   yard
+  zeitwerk
 
 CHECKSUMS
   actionpack (8.1.2) sha256=ced74147a1f0daafaa4bab7f677513fd4d3add574c7839958f7b4f1de44f8423
@@ -483,7 +482,6 @@ CHECKSUMS
   rack-session (2.1.1) sha256=0b6dc07dea7e4b583f58a48e8b806d4c9f1c6c9214ebc202ec94562cbea2e4e9
   rack-test (2.2.0) sha256=005a36692c306ac0b4a9350355ee080fd09ddef1148a5f8b2ac636c720f5c463
   rack-timeout (0.7.0) sha256=757337e9793cca999bb73a61fe2a7d4280aa9eefbaf787ce3b98d860749c87d9
-  rack-unreloader (2.1.0) sha256=18879cf2ced8ca21a01836bca706f65cce6ebe3f7d9d8a5157ce68ca62c7263a
   rails-dom-testing (2.3.0) sha256=8acc7953a7b911ca44588bf08737bc16719f431a1cc3091a292bca7317925c1d
   rails-html-sanitizer (1.7.0) sha256=28b145cceaf9cc214a9874feaa183c3acba036c9592b19886e0e45efc62b1e89
   rainbow (3.1.1) sha256=039491aa3a89f42efa1d6dec2fc4e62ede96eb6acd95e52f1ad581182b79bc6a

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,10 @@ 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.
+For contributors and AI agents changing backend structure, follow the placement rules in [docs/ai-agent-app-web.md](docs/ai-agent-app-web.md).
+
 ## 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

app.rb

@@ -6,7 +6,10 @@
 require 'base64'
 
 require 'html2rss'
-Dir[File.join(__dir__, 'app/**/*.rb')].each { |file| require file }
+require_relative 'app/web/boot'
+
+Html2rss::Web::Boot.setup!(reloadable: ENV['RACK_ENV'] == 'development')
+Html2rss::Web::Boot::Setup.call!
 
 module Html2rss
   module Web
@@ -31,13 +34,6 @@ class App < Roda
       def self.development? = EnvironmentValidator.development?
 
       def development? = self.class.development?
-      EnvironmentValidator.validate_environment!
-      EnvironmentValidator.validate_production_security!
-      Flags.validate!
-
-      Html2rss::RequestService.register_strategy(:ssrf_filter, SsrfFilterStrategy)
-      Html2rss::RequestService.default_strategy_name = :ssrf_filter
-      Html2rss::RequestService.unregister_strategy(:faraday)
       opts.merge!(check_dynamic_arity: false, check_arity: :warn)
       use RequestContextMiddleware
       use Rack::Cache, metastore: 'file:./tmp/rack-cache-meta', entitystore: 'file:./tmp/rack-cache-body',
@@ -85,6 +81,8 @@ def development? = self.class.development?
 
       plugin :json_parser
       plugin :public
+      plugin :head
+      plugin :not_allowed
       plugin :exception_page
       plugin :error_handler do |error|
         next exception_page(error) if development?