rage_arch 0.1.4 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 152d8ad4517ebc11b70103f2dadbc68d14363d66e93c83ed8513755b7f4d3faa
-  data.tar.gz: 5c15a711f1676d67644a75a66f7a7731504f56bc76ef75d1a2f420f4d900dae6
+  metadata.gz: 67361dabc2170be9ff033ec5cacbc0c271d01351bccde53e04804417043fc1ac
+  data.tar.gz: fede1669810366cc822f31ce1e14152c564365ed5934cab2b34eb0707e5245c6
 SHA512:
-  metadata.gz: bb854fce9230a8e3dc7efbec5257ca1ea9f98d91bb417262d4fe3d3a014d1e47df337acffb93eea453f438d2c525f92c06d003b1e2eabc63f99d95af3a10e3bf
-  data.tar.gz: b350e0aa5995ac0b63a30a8ade4ab78314b1755f56884998622434b585fa1f5b7bf16ade394666706b6569561ea256c1be74386f8b711232ab73c16dd8982947
+  metadata.gz: 725210b1791995e3dd9f7964676b2ca7a87016113eb05454dcb7e327efdde2f2715e3691b8689c47ac56292cc800244a32faa9f8d1374a1d0d3e434b58c69664
+  data.tar.gz: d846584108e497e4b2ab036a3965f7ef6d6466a6ad57c1fa33e63aab005223b618583153f3710380663ad0e3ae3b3837a2b069b7d1d90fc462b2500d7997a0ef

data/README.md

@@ -35,50 +35,6 @@ result.errors    # => ["Validation error"]
 
 ---
 
-### `RageArch::UseCase::Base` — use cases
-
-```ruby
-class CreateOrder < RageArch::UseCase::Base
-  use_case_symbol :create_order
-  deps :order_store, :notifications  # injected by symbol
-
-  def call(params = {})
-    order = order_store.build(params)
-    return failure(order.errors) unless order_store.save(order)
-    notifications.notify(:order_created, order)
-    success(order)
-  end
-end
-```
-
-Build and run manually:
-
-```ruby
-use_case = RageArch::UseCase::Base.build(:create_order)
-result = use_case.call(reference: "REF-1", total_cents: 1000)
-```
-
-#### `ar_dep` — inline ActiveRecord dep
-
-When a dep is a simple wrapper over an ActiveRecord model, declare it directly in the use case instead of creating a separate class:
-
-```ruby
-class Posts::Create < RageArch::UseCase::Base
-  use_case_symbol :posts_create
-  ar_dep :post_store, Post  # auto-creates an AR adapter if :post_store is not registered
-
-  def call(params = {})
-    post = post_store.build(params)
-    return failure(post.errors.full_messages) unless post_store.save(post)
-    success(post: post)
-  end
-end
-```
-
-If `:post_store` is registered in the container, that implementation is used. Otherwise, `RageArch::Deps::ActiveRecord.for(Post)` is used as fallback.
-
----
-
 ### `RageArch::Container` — dependency registration
 
 ```ruby
@@ -98,6 +54,15 @@ RageArch.resolve(:order_store)  # => the registered implementation
 RageArch.registered?(:order_store)  # => true
 ```
 
+**Convention-based auto-registration:** Use cases from `app/use_cases/` and deps from `app/deps/` are auto-registered at boot. The initializer is only needed to override conventions or register external adapters.
+
+**AR model auto-resolution:** If a dep symbol ends in `_store` or `_repo` and no file exists in `app/deps/`, rage_arch looks for an ActiveRecord model automatically:
+
+- `:post_store` or `:post_repo` resolves to `Post`
+- `:appointment_store` or `:appointment_repo` resolves to `Appointment`
+
+Explicit `RageArch.register(...)` always takes priority.
+
 ---
 
 ### Dependencies (Deps)
@@ -129,21 +94,7 @@ module Posts
 end
 ```
 
-Register it in `config/initializers/rage_arch.rb`:
-
-```ruby
-RageArch.register(:post_store, Posts::PostStore.new)
-```
-
-#### ActiveRecord dep (generated)
-
-For deps that simply wrap an AR model with standard CRUD, use the generator:
-
-```bash
-rails g rage_arch:ar_dep post_store Post
-```
-
-This creates `app/deps/posts/post_store.rb` with `build`, `find`, `save`, `update`, `destroy`, and `list` methods backed by `RageArch::Deps::ActiveRecord.for(Post)`.
+Auto-registered by convention from `app/deps/` — no manual registration needed.
 
 #### Generating a dep from use case analysis
 
@@ -172,6 +123,79 @@ The generator scans `app/deps/` for files matching the symbol, updates `config/i
 
 ---
 
+### `RageArch::UseCase::Base` — use cases
+
+Use cases declare their dependencies by symbol, receive them via injection, and return a `Result`. The symbol is inferred from the class name by convention:
+
+```ruby
+class Orders::Create < RageArch::UseCase::Base
+  # symbol :orders_create is inferred automatically
+  deps :order_store, :notifications
+
+  def call(params = {})
+    order = order_store.build(params)
+    return failure(order.errors) unless order_store.save(order)
+    notifications.notify(:order_created, order)
+    success(order: order)
+  end
+end
+```
+
+Symbol inference: `Orders::Create` becomes `:orders_create`. Explicit `use_case_symbol :my_symbol` still works as override.
+
+Build and run manually:
+
+```ruby
+use_case = RageArch::UseCase::Base.build(:orders_create)
+result = use_case.call(reference: "REF-1", total_cents: 1000)
+```
+
+---
+
+### undo — automatic rollback on failure
+
+Define `def undo(value)` on any use case. If `call` returns `failure(...)`, `undo` is called automatically:
+
+```ruby
+class Payments::Charge < RageArch::UseCase::Base
+  deps :payment_gateway
+
+  def call(params = {})
+    charge = payment_gateway.charge(params[:amount])
+    return failure(["Payment failed"]) unless charge.success?
+    success(charge_id: charge.id)
+  end
+
+  def undo(value)
+    payment_gateway.refund(value[:charge_id]) if value
+  end
+end
+```
+
+**Cascade undo with `use_cases`:** When a parent use case orchestrates children via `use_cases` and returns failure, each successfully-completed child has its `undo` called in reverse order:
+
+```ruby
+class Bookings::Create < RageArch::UseCase::Base
+  use_cases :payments_charge, :slots_reserve, :notifications_send
+
+  def call(params = {})
+    charge = payments_charge.call(amount: params[:amount])
+    return charge unless charge.success?
+
+    reserve = slots_reserve.call(slot_id: params[:slot_id])
+    return failure(reserve.errors) unless reserve.success?
+    # If this fails, slots_reserve.undo and payments_charge.undo run automatically
+
+    notifications_send.call(booking: params)
+    success(booking: params)
+  end
+end
+```
+
+No DSL, no configuration. Just define `undo` where you need rollback.
+
+---
+
 ### `RageArch::Controller` — thin controller mixin
 
 ```ruby
@@ -202,13 +226,12 @@ end
 
 ### `RageArch::EventPublisher` — domain events
 
-Every use case automatically publishes an event when it finishes. Other use cases subscribe to react:
+Every use case automatically publishes an event when it finishes. Other use cases subscribe to react. **Subscribers run asynchronously via ActiveJob by default:**
 
 ```ruby
 class Notifications::SendPostCreatedEmail < RageArch::UseCase::Base
-  use_case_symbol :send_post_created_email
   deps :mailer
-  subscribe :posts_create  # runs when :posts_create event is published
+  subscribe :posts_create  # async by default
 
   def call(payload = {})
     return success unless payload[:success]
@@ -218,6 +241,12 @@ class Notifications::SendPostCreatedEmail < RageArch::UseCase::Base
 end
 ```
 
+**Synchronous subscribers** (opt-in):
+
+```ruby
+subscribe :posts_create, async: false
+```
+
 Subscribe to multiple events or everything:
 
 ```ruby
@@ -237,7 +266,6 @@ skip_auto_publish
 
 ```ruby
 class CreateOrderWithNotification < RageArch::UseCase::Base
-  use_case_symbol :create_order_with_notification
   deps :order_store
   use_cases :orders_create, :notifications_send
 
@@ -260,12 +288,15 @@ end
 | `rails g rage_arch:scaffold Post title:string` | Full CRUD: model, use cases, dep, controller, views, routes |
 | `rails g rage_arch:scaffold Post title:string --api` | Same but API-only (JSON responses) |
 | `rails g rage_arch:scaffold Post title:string --skip-model` | Skip model/migration if it already exists |
+| `rails g rage_arch:resource Post title:string` | Like scaffold but without views (API-style controller) |
+| `rails g rage_arch:controller Pages home about` | Thin controller + use case per action + routes |
 | `rails g rage_arch:use_case CreateOrder` | Generates a base use case file |
 | `rails g rage_arch:use_case orders/create` | Generates a namespaced use case (`Orders::Create`) |
 | `rails g rage_arch:dep post_store` | Generates a dep class by scanning method calls in use cases |
-| `rails g rage_arch:ar_dep post_store Post` | Generates a dep that wraps an ActiveRecord model |
 | `rails g rage_arch:dep_switch post_store` | Lists implementations and switches which one is registered |
 | `rails g rage_arch:dep_switch post_store PostgresPostStore` | Directly activates a specific implementation |
+| `rails g rage_arch:mailer PostMailer post_created` | Rails mailer + dep wrapper (auto-registered) |
+| `rails g rage_arch:job ProcessOrder orders_create` | ActiveJob that runs a use case by symbol |
 
 ---
 
@@ -274,7 +305,23 @@ end
 ```ruby
 # spec/rails_helper.rb
 require "rage_arch/rspec_matchers"
+require "rage_arch/rspec_helpers"
 require "rage_arch/fake_event_publisher"
+
+RSpec.configure do |config|
+  config.include RageArch::RSpecHelpers  # auto-isolates each test
+end
+```
+
+**Test isolation:** `RageArch::RSpecHelpers` wraps each example in `RageArch.isolate`, so dep registrations never bleed between tests.
+
+**Manual isolation** (without the helper):
+
+```ruby
+RageArch.isolate do
+  RageArch.register(:payment_gateway, FakeGateway.new)
+  # registrations inside are scoped; originals restored on exit
+end
 ```
 
 **Result matchers:**
@@ -306,6 +353,9 @@ config.rage_arch.auto_publish_events = false
 
 # Disable boot verification (default: true)
 config.rage_arch.verify_deps = false
+
+# Run all subscribers synchronously — useful for test environments (default: true)
+config.rage_arch.async_subscribers = false
 ```
 
 ---
@@ -314,16 +364,17 @@ config.rage_arch.verify_deps = false
 
 At boot, `RageArch.verify_deps!` runs automatically and raises if it finds wiring problems. It checks:
 
-- Every dep declared with `deps :symbol` is registered in the container
+- Every dep declared with `deps :symbol` is registered in the container (or auto-resolved for `_store`/`_repo` deps)
 - Every method called on a dep is implemented by the registered object (via static analysis)
 - Every use case declared with `use_cases :symbol` exists in the registry
+- Warns if `use_case_symbol` doesn't match the convention-inferred symbol
 
 Example error output:
 
 ```
 RageArch boot verification failed:
-  UseCase :posts_create (Posts::Create) declares dep :post_store — not registered in container
-  UseCase :posts_create (Posts::Create) calls :post_store#save — Posts::PostStore does not implement #save
+  UseCase :posts_create (Posts::Create) declares dep :post_store — not registered in container and no AR model found for _store/_repo
+  UseCase :posts_create (Posts::Create) calls dep :post_store#save — Posts::PostStore does not implement #save
   UseCase :posts_notify (Posts::Notify) declares use_cases :email_send — not registered in use case registry
 ```
 
@@ -346,9 +397,14 @@ end
 
 ## Documentation
 
-- [`doc/REFERENCE.md`](doc/REFERENCE.md) — Full API reference with all options and examples
-- [`doc/DOCUMENTATION.md`](doc/DOCUMENTATION.md) — Detailed behaviour (use cases, deps, events, config)
 - [`doc/GETTING_STARTED.md`](doc/GETTING_STARTED.md) — Getting started guide with common tasks
+- [`doc/TUTORIAL.md`](doc/TUTORIAL.md) — Side-by-side Rails vs Rails+RageArch comparison
+- [`doc/DOCUMENTATION.md`](doc/DOCUMENTATION.md) — Detailed behaviour (use cases, deps, events, config)
+- [`doc/REFERENCE.md`](doc/REFERENCE.md) — Quick-lookup API reference (classes, methods, options)
+
+## AI context
+
+If you use an AI coding agent, point it to [`IA.md`](IA.md) for a compact reference of the full gem API, conventions, and architecture.
 
 ## License
 

data/lib/generators/rage_arch/controller_generator.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module RageArch
+  module Generators
+    class ControllerGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      argument :actions, type: :array, default: [], banner: "action action"
+
+      desc "Generate a thin RageArch controller with use cases for each action."
+      def create_controller
+        template "controller/controller.rb.tt", File.join("app/controllers", "#{plural_file_name}_controller.rb")
+      end
+
+      def create_use_cases
+        actions.each do |action|
+          @current_action = action
+          template "controller/action_use_case.rb.tt", File.join("app/use_cases", plural_file_name, "#{action}.rb")
+        end
+      end
+
+      def add_routes
+        return if actions.empty?
+        lines = actions.map { |a| "  get \"#{plural_file_name}/#{a}\", to: \"#{plural_file_name}##{a}\"" }
+        route lines.join("\n")
+      end
+
+      private
+
+      def plural_file_name
+        file_name.pluralize
+      end
+
+      def controller_class_name
+        plural_file_name.camelize
+      end
+
+      def module_name
+        plural_file_name.camelize
+      end
+
+      def current_action
+        @current_action
+      end
+
+      def use_case_symbol(action)
+        "#{plural_file_name}_#{action}"
+      end
+    end
+  end
+end

data/lib/generators/rage_arch/dep_generator.rb

@@ -27,6 +27,8 @@ module RageArch
         end
       end
 
+      private
+
       # When the dep file already exists, parse it for existing method names and insert only stubs for missing ones.
       def add_missing_methods_only(relative_path)
         full_path = File.join(destination_root, relative_path)

data/lib/generators/rage_arch/job_generator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module RageArch
+  module Generators
+    class JobGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      argument :use_case_symbol, type: :string, required: false, default: nil, banner: "use_case_symbol"
+
+      desc "Generate an ActiveJob that runs a RageArch use case by symbol."
+      def create_job
+        template "job/job.rb.tt", File.join("app/jobs", "#{file_name}_job.rb")
+      end
+
+      private
+
+      def job_class_name
+        file_name.camelize
+      end
+
+      def inferred_symbol
+        use_case_symbol || file_name
+      end
+    end
+  end
+end

data/lib/generators/rage_arch/mailer_generator.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module RageArch
+  module Generators
+    class MailerGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      argument :actions, type: :array, default: [], banner: "action action"
+
+      desc "Generate a Rails mailer and a RageArch dep wrapper (auto-registered from app/deps/)."
+      def create_rails_mailer
+        args = [name] + actions
+        invoke "mailer", args
+      end
+
+      def create_dep
+        dep_dir = File.join("app/deps")
+        template "mailer/mailer_dep.rb.tt", File.join(dep_dir, "#{dep_file_name}.rb")
+      end
+
+      private
+
+      def mailer_class_name
+        name.camelize
+      end
+
+      def dep_class_name
+        "#{mailer_class_name}Dep"
+      end
+
+      def dep_file_name
+        "#{file_name}_dep"
+      end
+
+      def dep_symbol
+        file_name.underscore
+      end
+    end
+  end
+end

data/lib/generators/rage_arch/resource_generator.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module RageArch
+  module Generators
+    class ResourceGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      argument :attributes, type: :array, default: [], banner: "field:type field:type"
+      class_option :skip_model, type: :boolean, default: false, desc: "Skip model and migration (use when model already exists)"
+
+      desc "Generate a RageArch resource: model, migration, CRUD use cases, dep, API-style controller, and routes (no views)."
+      def create_all
+        create_model_and_migration
+        create_use_cases
+        create_dep
+        create_controller
+        add_route
+      end
+
+      private
+
+      def create_model_and_migration
+        return if options[:skip_model]
+        args = [name] + attributes.map(&:to_s)
+        invoke "active_record:model", args
+      end
+
+      def create_use_cases
+        dir = File.join("app/use_cases", plural_name)
+        empty_directory dir
+        template "scaffold/list.rb.tt",    File.join(dir, "list.rb")
+        template "scaffold/show.rb.tt",    File.join(dir, "show.rb")
+        template "scaffold/new.rb.tt",     File.join(dir, "new.rb")
+        template "scaffold/create.rb.tt",  File.join(dir, "create.rb")
+        template "scaffold/update.rb.tt",  File.join(dir, "update.rb")
+        template "scaffold/destroy.rb.tt", File.join(dir, "destroy.rb")
+      end
+
+      def create_dep
+        dep_dir = File.join("app/deps", plural_name)
+        empty_directory dep_dir
+        template "scaffold/post_repo.rb.tt", File.join(dep_dir, "#{singular_name}_repo.rb")
+      end
+
+      def create_controller
+        template "scaffold/api_controller.rb.tt", File.join("app/controllers", "#{plural_name}_controller.rb")
+      end
+
+      def add_route
+        route "resources :#{plural_name}"
+      end
+
+      def plural_name
+        name.underscore.pluralize
+      end
+
+      def singular_name
+        name.underscore
+      end
+
+      def model_class_name
+        name.camelize
+      end
+
+      def module_name
+        plural_name.camelize
+      end
+
+      def repo_symbol
+        "#{singular_name}_repo"
+      end
+
+      def repo_class_name
+        "#{module_name}::#{singular_name.camelize}Repo"
+      end
+
+      def list_symbol
+        "#{plural_name}_list"
+      end
+
+      def show_symbol
+        "#{plural_name}_show"
+      end
+
+      def create_symbol
+        "#{plural_name}_create"
+      end
+
+      def update_symbol
+        "#{plural_name}_update"
+      end
+
+      def destroy_symbol
+        "#{plural_name}_destroy"
+      end
+
+      def new_symbol
+        "#{plural_name}_new"
+      end
+
+      def attribute_names_for_permit
+        return [] if attributes.blank?
+        attributes.map { |a| a.to_s.split(":").first.to_sym }
+      end
+    end
+  end
+end

data/lib/generators/rage_arch/scaffold_generator.rb

@@ -20,7 +20,6 @@ module RageArch
         invoke_rails_scaffold_views
         create_controller
         add_route
-        inject_register_ar
       end
 
       private
@@ -65,17 +64,6 @@ module RageArch
         route "resources :#{plural_name}"
       end
 
-      def inject_register_ar
-        initializer_path = File.join(destination_root, "config/initializers/rage_arch.rb")
-        return unless File.exist?(initializer_path)
-        content = File.read(initializer_path)
-        return if content.include?("register_ar(:#{repo_symbol})")
-        inject_line = "  RageArch.register_ar(:#{repo_symbol}, #{model_class_name})\n"
-        content.sub!(/(Rails\.application\.config\.after_initialize do\s*\n)/m, "\\1#{inject_line}")
-        File.write(initializer_path, content)
-        say_status :inject, "config/initializers/rage_arch.rb (register_ar :#{repo_symbol})", :green
-      end
-
       def plural_name
         name.underscore.pluralize
       end

data/lib/generators/rage_arch/templates/controller/action_use_case.rb.tt

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module <%= module_name %>
+  class <%= current_action.camelize %> < RageArch::UseCase::Base
+    # deps :example_repo
+
+    def call(params = {})
+      # TODO: implement use case logic
+      success(params)
+    end
+  end
+end

data/lib/generators/rage_arch/templates/controller/controller.rb.tt

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+class <%= controller_class_name %>Controller < ApplicationController
+<%- actions.each do |action| -%>
+  def <%= action %>
+    run :<%= use_case_symbol(action) %>,
+      success: ->(r) { render :<%= action %> },
+      failure: ->(r) { flash_errors(r); redirect_to root_path }
+  end
+
+<%- end -%>
+end

data/lib/generators/rage_arch/templates/dep.rb.tt

@@ -2,7 +2,7 @@
 
 # Dep for :<%= symbol_name %>.
 # Methods detected from use cases: <%= @methods.join(', ') %>.
-# Register in config/initializers/rage_arch.rb: RageArch.register(:<%= symbol_name %>, <%= full_class_name %>.new)
+# Auto-registered by convention from app/deps/
 module <%= module_name %>
   class <%= class_name %>
 <% @methods.each do |method_name| -%>

data/lib/generators/rage_arch/templates/job/job.rb.tt

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class <%= job_class_name %>Job < ApplicationJob
+  queue_as :default
+
+  def perform(**params)
+    result = RageArch::UseCase::Base.build(:<%= inferred_symbol %>).call(params)
+
+    unless result.success?
+      Rails.logger.error "[<%= job_class_name %>Job] Use case :<%= inferred_symbol %> failed: #{result.errors.inspect}"
+    end
+
+    result
+  end
+end

data/lib/generators/rage_arch/templates/mailer/mailer_dep.rb.tt

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Dep for :<%= dep_symbol %>. Wraps <%= mailer_class_name %>.
+# Auto-registered by convention from app/deps/
+class <%= dep_class_name %>
+<%- actions.each do |action| -%>
+  def <%= action %>(*args)
+    <%= mailer_class_name %>.<%=action %>(*args).deliver_later
+  end
+
+<%- end -%>
+<%- if actions.empty? -%>
+  # def send_email(*args)
+  #   <%= mailer_class_name %>.send_email(*args).deliver_later
+  # end
+<%- end -%>
+end

data/lib/generators/rage_arch/templates/rage_arch.rb.tt

@@ -1,19 +1,16 @@
 # frozen_string_literal: true
 
-# Register your app's deps here. Deps are grouped by module (e.g. app/deps/posts/post_repo.rb → Posts::PostRepo).
-# Use RageArch.register(:symbol, ClassName.new) or RageArch.register_ar(:symbol, Model) for AR-backed deps.
+# rage_arch auto-registers use cases from app/use_cases/ and deps from app/deps/
+# Add registrations here only to override conventions or register external adapters.
+#
+# Example:
+#   RageArch.register(:payment_gateway, Payments::StripeGateway.new)
 
 Rails.application.config.after_initialize do
-  # Deps
-  # RageArch.register(:post_repo, Posts::PostRepo.new)
-  # RageArch.register_ar(:user_repo, User)
-
   # Event publisher: use cases that declare subscribe :event_name are wired here.
   publisher = RageArch::EventPublisher.new
   RageArch::UseCase::Base.wire_subscriptions_to(publisher)
   RageArch.register(:event_publisher, publisher)
 
-  # Called here (after all deps are registered) instead of relying on the Railtie,
-  # which runs before this block. Skipped during asset precompilation.
   RageArch.verify_deps! unless ENV["SECRET_KEY_BASE_DUMMY"].present?
 end