rage_arch 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4be8aa2c59b8c0e1f4d15a2af2c9075a21a674cf80401ddd7e8ad655ce3a6f8
-  data.tar.gz: e2cccfe9fec1c8e630b2b3eff45eab25ec208075dcce4d54422f913693b1f14e
+  metadata.gz: 5977f7f0cda9c29591b5fada240de2a007facc8c3922e8f2a9c6a5ae08ed1f5b
+  data.tar.gz: 05b8e5a3a44cb57099c64b33c9cffba6a0abf80dc6256c41eabe87e86d48378e
 SHA512:
-  metadata.gz: c03dd919d2b32226ec4ea0975c2d748d2e4f6049b44a5e635e192b9d5cecac120b68ec600151e2c08ca94e7b5f4a28a456ffb4cf92365c516f13de1ba250efa6
-  data.tar.gz: 2087a0af99636d741197191157c7f2c395ba81183363c656ead9e437fba232360f6d2072a428f2fb0a363ee4743c2646182e8c46dfa38075804680df22b11bf6
+  metadata.gz: 25f7ef50af078a7b61663d26fd8586c5d512709b116ca206266c8d04e1d364c19caf5bf131c0886d0061fc7b1db0e7de3c47f2a827360f2a03b03d911ee5336d
+  data.tar.gz: 06fea4288ebf3eeb5a6e1c3a2baf2895c22514389fbb169a5741474ef500baaaa52b129d0711ee645025fc713a6bd58e2436be05979445c64ec1831206af1437

data/README.md

@@ -35,39 +35,165 @@ result.errors    # => ["Validation error"]
 
 ---
 
+### `RageArch::Container` — dependency registration
+
+```ruby
+# Register by instance
+RageArch.register(:order_store, MyApp::Deps::OrderStore.new)
+
+# Register with a block (lazy evaluation)
+RageArch.register(:mailer) { Mailer.new }
+
+# Register an ActiveRecord model as dep (wraps it automatically)
+RageArch.register_ar(:user_store, User)
+
+# Resolve
+RageArch.resolve(:order_store)  # => the registered implementation
+
+# Check if registered
+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` and no file exists in `app/deps/`, rage_arch looks for an ActiveRecord model automatically:
+
+- `:post_store` resolves to `Post`
+- `:appointment_store` resolves to `Appointment`
+
+Explicit `RageArch.register(...)` always takes priority.
+
+---
+
+### Dependencies (Deps)
+
+A dep is any object that a use case needs from the outside world: persistence, mailers, external APIs, caches, etc. No base class required — any Ruby object can be a dep.
+
+#### Writing a dep manually
+
+```ruby
+# app/deps/posts/post_store.rb
+module Posts
+  class PostStore
+    def build(attrs = {})
+      Post.new(attrs)
+    end
+
+    def save(record)
+      record.save
+    end
+
+    def find(id)
+      Post.find_by(id: id)
+    end
+
+    def list(filters: {})
+      Post.where(filters).to_a
+    end
+  end
+end
+```
+
+Auto-registered by convention from `app/deps/` — no manual registration needed.
+
+#### Generating a dep from use case analysis
+
+```bash
+rails g rage_arch:dep post_store
+```
+
+Scans your use cases for method calls on `:post_store` and generates a class with stub methods for each one. If the file already exists, only missing methods are added.
+
+#### Switching dep implementations
+
+Use `dep_switch` to swap between multiple implementations of the same dep:
+
+```bash
+# Interactive — lists all available implementations and prompts you to choose
+rails g rage_arch:dep_switch post_store
+
+# Direct — activate a specific implementation
+rails g rage_arch:dep_switch post_store PostgresPostStore
+
+# Switch to ActiveRecord adapter
+rails g rage_arch:dep_switch post_store ar
+```
+
+The generator scans `app/deps/` for files matching the symbol, updates `config/initializers/rage_arch.rb` by commenting out the old registration and adding the new one.
+
+---
+
 ### `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 CreateOrder < RageArch::UseCase::Base
-  use_case_symbol :create_order
-  deps :order_store, :notifications  # injected by symbol
+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)
+    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(:create_order)
+use_case = RageArch::UseCase::Base.build(:orders_create)
 result = use_case.call(reference: "REF-1", total_cents: 1000)
 ```
 
 ---
 
-### `RageArch::Container` — dependency registration
+### undo — automatic rollback on failure
+
+Define `def undo(value)` on any use case. If `call` returns `failure(...)`, `undo` is called automatically:
 
 ```ruby
-RageArch.register(:order_store, MyApp::Deps::OrderStore.new)
-RageArch.register_ar(:user_store, User)  # automatic ActiveRecord wrapper
-RageArch.resolve(:order_store)
+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
@@ -84,17 +210,28 @@ end
 - `run_result(symbol, params)` — runs and returns the `Result` directly
 - `flash_errors(result)` — sets `flash.now[:alert]` from `result.errors`
 
+**API controller example (JSON):**
+
+```ruby
+class Api::PostsController < ApplicationController
+  def create
+    run :posts_create, post_params,
+      success: ->(r) { render json: r.value[:post], status: :created },
+      failure: ->(r) { render json: { errors: r.errors }, status: :unprocessable_entity }
+  end
+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]
@@ -104,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
@@ -123,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
 
@@ -147,8 +289,10 @@ end
 | `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: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 |
 
 ---
 
@@ -157,7 +301,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:**
@@ -179,23 +339,67 @@ publisher.clear
 
 ---
 
+## Configuration
+
+```ruby
+# config/application.rb or config/initializers/rage_arch.rb
+
+# Disable automatic event publishing when use cases finish (default: true)
+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
+```
+
+---
+
 ## Boot verification
 
-At boot, `RageArch.verify_deps!` runs automatically and raises if any dep, method, or use case reference is unregistered. Disable with `config.rage.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 (or auto-resolved for `_store` 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 and no AR model found
+  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
+```
+
+Disable with `config.rage_arch.verify_deps = false`.
 
 ---
 
 ## Instrumentation
 
-Every use case emits `"rage.use_case.run"` via `ActiveSupport::Notifications` with payload `symbol`, `params`, `success`, `errors`, `result`.
+Every use case emits `"rage_arch.use_case.run"` via `ActiveSupport::Notifications` with payload `symbol`, `params`, `success`, `errors`, `result`.
+
+```ruby
+ActiveSupport::Notifications.subscribe("rage_arch.use_case.run") do |*args|
+  event = ActiveSupport::Notifications::Event.new(*args)
+  Rails.logger.info "[UseCase] #{event.payload[:symbol]} (#{event.duration.round}ms) success=#{event.payload[:success]}"
+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/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/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/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/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/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

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

@@ -2,7 +2,7 @@
 
 class <%= module_name %>Controller < ApplicationController
   def index
-    run :<%= list_symbol %>, {},
+    run :<%= list_symbol %>,
       success: ->(r) { @<%= plural_name %> = r.value[:<%= singular_name %>s]; render :index },
       failure: ->(r) { redirect_to root_path, alert: r.errors.join(", ") }
   end
@@ -14,7 +14,7 @@ class <%= module_name %>Controller < ApplicationController
   end
 
   def new
-    run :<%= new_symbol %>, {},
+    run :<%= new_symbol %>,
       success: ->(r) { @<%= singular_name %> = r.value[:<%= singular_name %>]; render :new },
       failure: ->(r) { redirect_to <%= plural_name %>_path, alert: r.errors.join(", ") }
   end
@@ -22,7 +22,12 @@ class <%= module_name %>Controller < ApplicationController
   def create
     run :<%= create_symbol %>, <%= singular_name %>_params,
       success: ->(r) { redirect_to <%= singular_name %>_path(r.value[:<%= singular_name %>].id), notice: "<%= model_class_name %> was successfully created." },
-      failure: ->(r) { @<%= singular_name %> = run_result(:<%= new_symbol %>, {}).value[:<%= singular_name %>]; flash_errors(r); render :new, status: :unprocessable_entity }
+      failure: ->(r) {
+        new_result = run_result(:<%= new_symbol %>)
+        @<%= singular_name %> = new_result.success? ? new_result.value[:<%= singular_name %>] : nil
+        flash_errors(r)
+        render :new, status: :unprocessable_entity
+      }
   end
 
   def edit

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

@@ -2,7 +2,6 @@
 
 module <%= module_name %>
   class Create < RageArch::UseCase::Base
-    use_case_symbol :<%= create_symbol %>
     deps :<%= repo_symbol %>
 
     def call(params = {})

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

@@ -2,7 +2,6 @@
 
 module <%= module_name %>
   class Destroy < RageArch::UseCase::Base
-    use_case_symbol :<%= destroy_symbol %>
     deps :<%= repo_symbol %>
 
     def call(params = {})

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

@@ -2,7 +2,6 @@
 
 module <%= module_name %>
   class List < RageArch::UseCase::Base
-    use_case_symbol :<%= list_symbol %>
     deps :<%= repo_symbol %>
 
     def call(_params = {})

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

@@ -2,7 +2,6 @@
 
 module <%= module_name %>
   class New < RageArch::UseCase::Base
-    use_case_symbol :<%= new_symbol %>
     deps :<%= repo_symbol %>
 
     def call(_params = {})

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Dep for :<%= repo_symbol %>. Wraps the <%= model_class_name %> Active Record model.
-# Registered by rage:scaffold in config/initializers/rage_arch.rb
+# Auto-registered by convention from app/deps/
 module <%= module_name %>
   class <%= singular_name.camelize %>Repo
     def initialize

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

@@ -2,7 +2,6 @@
 
 module <%= module_name %>
   class Show < RageArch::UseCase::Base
-    use_case_symbol :<%= show_symbol %>
     deps :<%= repo_symbol %>
 
     def call(params = {})

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

@@ -2,7 +2,6 @@
 
 module <%= module_name %>
   class Update < RageArch::UseCase::Base
-    use_case_symbol :<%= update_symbol %>
     deps :<%= repo_symbol %>
 
     def call(params = {})

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

@@ -4,13 +4,11 @@
 module <%= class_path.map(&:camelize).join('::') %>
 <%- end -%>
 class <%= file_name.camelize %> < RageArch::UseCase::Base
-  use_case_symbol :<%= file_name %>
-
-  deps # e.g. :order_store, :notifications
+  # deps :example_repo
 
   def call(params = {})
     # TODO: implement use case logic
-    RageArch::Result.success(params)
+    success(params)
   end
 end
 <%- class_path.each do -%>

data/lib/rage_arch/auto_registrar.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module RageArch
+  # Auto-registers use cases and deps at boot by convention.
+  # Use cases: subclasses of RageArch::UseCase::Base → registered by inferred symbol.
+  # Deps: classes under app/deps/ → registered by inferred symbol.
+  # AR auto-resolution: deps ending in _store with no file in app/deps/ → resolves AR model.
+  class AutoRegistrar
+    class << self
+      def run
+        register_use_cases
+        register_deps
+        resolve_store_deps
+      end
+
+      private
+
+      def register_use_cases
+        RageArch::UseCase::Base.registry.each do |sym, _klass|
+          # Already in registry via use_case_symbol or infer_use_case_symbol — nothing to do.
+          # The act of calling use_case_symbol (explicit or inferred) registers the class.
+        end
+
+        # Ensure all subclasses have their symbol inferred and registered
+        RageArch::UseCase::Base.descendants.each do |klass|
+          next if klass.name.nil? # anonymous classes
+          klass.use_case_symbol # triggers inference + registration if not already set
+        end
+      end
+
+      def register_deps
+        return unless defined?(Rails) && Rails.application
+
+        deps_dir = Rails.root.join("app", "deps")
+        return unless deps_dir.exist?
+
+        Dir[deps_dir.join("**/*.rb")].sort.each do |file|
+          require file
+        end
+
+        # Register any class defined under app/deps/ that isn't already registered
+        ObjectSpace.each_object(Class).select do |klass|
+          next unless klass.name
+          next if klass.name.start_with?("RageArch::")
+
+          # Check if this class was loaded from app/deps/
+          source_file = begin
+            Object.const_source_location(klass.name)&.first
+          rescue
+            nil
+          end
+          next unless source_file && source_file.start_with?(deps_dir.to_s)
+
+          sym = ActiveSupport::Inflector.underscore(ActiveSupport::Inflector.demodulize(klass.name)).to_sym
+          unless Container.registered?(sym)
+            Container.register(sym, klass.new)
+          end
+        end
+      end
+
+      def resolve_store_deps
+        # For each use case, check declared deps ending in _store
+        RageArch::UseCase::Base.registry.each_value do |klass|
+          klass.declared_deps.each do |dep_sym|
+            next if Container.registered?(dep_sym)
+            next unless dep_sym.to_s.end_with?("_store")
+
+            model_name = dep_sym.to_s.sub(/_store\z/, "").camelize
+            model_class = begin
+              model_name.constantize
+            rescue NameError
+              nil
+            end
+
+            if model_class && defined?(ActiveRecord::Base) && model_class < ActiveRecord::Base
+              Container.register(dep_sym, Deps::ActiveRecord.for(model_class))
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rage_arch/container.rb

@@ -2,15 +2,19 @@
 
 module RageArch
   # Container to register and resolve dependencies by symbol.
-  # Usage: RageArch.register(:order_store, MyAdapter.new); RageArch.resolve(:order_store)
+  # Supports scoped isolation via RageArch.isolate for test environments.
   class Container
     class << self
       def register(symbol, implementation = nil, &block)
-        registry[symbol] = block || implementation
+        if current_scope
+          current_scope[symbol] = block || implementation
+        else
+          registry[symbol] = block || implementation
+        end
       end
 
       def resolve(symbol)
-        entry = registry[symbol]
+        entry = scoped_lookup(symbol)
         raise KeyError, "Dep not registered: #{symbol.inspect}" unless entry
 
         if entry.respond_to?(:call) && entry.is_a?(Proc)
@@ -23,6 +27,7 @@ module RageArch
       end
 
       def registered?(symbol)
+        return true if current_scope&.key?(symbol)
         registry.key?(symbol)
       end
 
@@ -33,6 +38,34 @@ module RageArch
       def reset!
         @registry = {}
       end
+
+      # --- Scope isolation for tests ---
+
+      def push_scope
+        scope_stack.push({})
+      end
+
+      def pop_scope
+        scope_stack.pop
+      end
+
+      private
+
+      def scope_stack
+        Thread.current[:rage_arch_container_scopes] ||= []
+      end
+
+      def current_scope
+        scope_stack.last
+      end
+
+      def scoped_lookup(symbol)
+        if current_scope&.key?(symbol)
+          current_scope[symbol]
+        else
+          registry[symbol]
+        end
+      end
     end
   end
 end

data/lib/rage_arch/dep_scanner.rb

@@ -4,7 +4,7 @@ require "set"
 
 module RageArch
   # Scans use case files to find dep symbols and the methods called on each dep.
-  # Used by the rage:dep generator to create stub classes with the right methods.
+  # Used by the rage_arch:dep generator to create stub classes with the right methods.
   # Also tracks which use case path each symbol appears in (for folder inference).
   class DepScanner
     def initialize(use_cases_root = nil)

data/lib/rage_arch/railtie.rb

@@ -5,27 +5,23 @@ require_relative "controller"
 
 module RageArch
   class Railtie < ::Rails::Railtie
-    config.rage = ActiveSupport::OrderedOptions.new
-    config.rage.auto_publish_events = true
-    config.rage.verify_deps = true
+    config.rage_arch = ActiveSupport::OrderedOptions.new
+    config.rage_arch.auto_publish_events = true
+    config.rage_arch.verify_deps = true
+    config.rage_arch.async_subscribers = true
 
-    # Load use case files so they register their symbols in the registry.
-    # Without this, build(:symbol) would fail until the use case constant was referenced.
-    config.after_initialize do |app|
-      # Skip everything during asset precompilation — no deps are registered then.
+    # Load use case and dep files, then auto-register by convention.
+    initializer "rage_arch.auto_register", after: :eager_load! do |app|
       next if ENV["SECRET_KEY_BASE_DUMMY"].present?
 
+      # Load use case files so they register their symbols in the registry.
       use_cases_dir = app.root.join("app/use_cases")
       if use_cases_dir.exist?
         Dir[use_cases_dir.join("**/*.rb")].sort.each { |f| require f }
       end
 
-      # NOTE: verify_deps! is intentionally NOT called here. This after_initialize
-      # runs before the app's own initializers' after_initialize blocks, so deps
-      # registered there would not be visible yet. Apps should call
-      # RageArch.verify_deps! manually at the end of their own after_initialize
-      # (config/initializers/rage_arch.rb), after all deps are registered.
-      # Set config.rage.verify_deps = false to opt out.
+      # Auto-register use cases and deps by convention.
+      RageArch::AutoRegistrar.run
     end
   end
 end

data/lib/rage_arch/rspec_helpers.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module RageArch
+  # RSpec helper that wraps each example in RageArch.isolate,
+  # preventing test pollution from dep registrations.
+  #
+  # Usage in spec/rails_helper.rb:
+  #   require "rage_arch/rspec_helpers"
+  #   RSpec.configure do |config|
+  #     config.include RageArch::RSpecHelpers
+  #   end
+  module RSpecHelpers
+    def self.included(base)
+      base.around(:each) do |example|
+        RageArch.isolate { example.run }
+      end
+    end
+  end
+end

data/lib/rage_arch/subscriber_job.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module RageArch
+  class SubscriberJob < ActiveJob::Base
+    queue_as :default
+
+    def perform(subscriber_symbol, payload)
+      sym = subscriber_symbol.to_sym
+      payload = payload.transform_keys(&:to_sym) if payload.is_a?(Hash)
+      RageArch::UseCase::Base.build(sym).call(payload)
+    end
+  end
+end

data/lib/rage_arch/use_case.rb

@@ -1,8 +1,47 @@
 # frozen_string_literal: true
 
+require "active_support/inflector"
+
 module RageArch
   module UseCase
-    # Runs another use case by symbol. Used when a use case declares use_cases :other_symbol.
+    # Tracks successful use case executions for cascade undo on failure.
+    class ExecutionTracker
+      def initialize
+        @recorded = []
+      end
+
+      def record(use_case_instance, result)
+        @recorded << { use_case: use_case_instance, result: result }
+      end
+
+      def undo_all
+        @recorded.reverse_each do |entry|
+          uc = entry[:use_case]
+          uc.undo(entry[:result].value) if uc.respond_to?(:undo)
+        end
+      end
+
+      def clear
+        @recorded.clear
+      end
+    end
+
+    # Wraps a use case runner to track successful calls for cascade undo.
+    class UseCaseProxy
+      def initialize(symbol, tracker:)
+        @symbol = symbol
+        @tracker = tracker
+      end
+
+      def call(params = {})
+        use_case = Base.build(@symbol)
+        result = use_case.call(params)
+        @tracker.record(use_case, result) if result.success?
+        result
+      end
+    end
+
+    # Runs another use case by symbol (legacy, used when no tracker is active).
     class Runner
       def initialize(symbol)
         @symbol = symbol
@@ -17,7 +56,6 @@ module RageArch
     #
     # Usage:
     #   class CreateOrder < RageArch::UseCase::Base
-    #     use_case_symbol :create_order
     #     deps :order_store, :notifications
     #
     #     def call(params = {})
@@ -32,24 +70,38 @@ module RageArch
       module Instrumentation
         def call(params = {})
           sym = self.class.use_case_symbol
+
+          # Set up execution tracker for cascade undo via use_cases
+          @_execution_tracker = ExecutionTracker.new
+
           if defined?(ActiveSupport::Notifications)
-            ActiveSupport::Notifications.instrument("rage.use_case.run", symbol: sym, params: params) do |payload|
+            ActiveSupport::Notifications.instrument("rage_arch.use_case.run", symbol: sym, params: params) do |payload|
               result = super(params)
               payload[:success] = result.success?
               payload[:errors] = result.errors unless result.success?
               payload[:result] = result
-              auto_publish_if_enabled(sym, params, result)
+              handle_undo_and_publish(sym, params, result)
               result
             end
           else
             result = super(params)
-            auto_publish_if_enabled(sym, params, result)
+            handle_undo_and_publish(sym, params, result)
             result
           end
         end
 
         private
 
+        def handle_undo_and_publish(use_case_symbol, params, result)
+          if result.failure?
+            # Cascade undo: reverse-order undo of tracked child use cases
+            @_execution_tracker&.undo_all
+            # Self undo
+            undo(result.value) if respond_to?(:undo)
+          end
+          auto_publish_if_enabled(use_case_symbol, params, result)
+        end
+
         def auto_publish_if_enabled(use_case_symbol, params, result)
           return unless auto_publish_enabled?
           return unless self.class.container.registered?(:event_publisher)
@@ -66,8 +118,8 @@ module RageArch
 
         def auto_publish_enabled?
           return false if self.class.skip_auto_publish?
-          return true unless defined?(Rails) && Rails.application.config.respond_to?(:rage) && Rails.application.config.rage
-          Rails.application.config.rage.auto_publish_events != false
+          return true unless defined?(Rails) && Rails.application.config.respond_to?(:rage_arch) && Rails.application.config.rage_arch
+          Rails.application.config.rage_arch.auto_publish_events != false
         end
       end
 
@@ -78,13 +130,14 @@ module RageArch
           super
           subclass.prepend(Instrumentation)
         end
+
         def use_case_symbol(sym = nil)
           if sym
             @use_case_symbol = sym
             Base.registry[sym] = self
             sym
           else
-            @use_case_symbol
+            @use_case_symbol ||= infer_use_case_symbol
           end
         end
 
@@ -99,12 +152,18 @@ module RageArch
         end
 
         # Declare other use cases this one can call. In call(), use e.g. posts_create.call(params)
-        # to run that use case and get its Result. Same layer can reference by symbol.
+        # to run that use case and get its Result. Tracked for cascade undo on failure.
         def use_cases(*symbols)
           @declared_use_cases ||= []
           @declared_use_cases.concat(symbols)
           symbols.each do |sym|
-            define_method(sym) { Runner.new(sym) }
+            define_method(sym) do
+              if @_execution_tracker
+                UseCaseProxy.new(sym, tracker: @_execution_tracker)
+              else
+                Runner.new(sym)
+              end
+            end
           end
           private(*symbols) if symbols.any?
           symbols
@@ -117,13 +176,20 @@ module RageArch
         # Subscribe this use case to domain events. When the event is published, this use case's call(payload) runs.
         # You can subscribe to multiple events: subscribe :post_created, :post_updated
         # Special: subscribe :all to run on every published event (payload will include :event).
-        def subscribe(*event_names)
+        # By default subscribers run asynchronously via ActiveJob. Use async: false for synchronous execution.
+        def subscribe(*event_names, async: true)
           @subscribed_events ||= []
-          @subscribed_events.concat(event_names.map(&:to_sym))
+          event_names.each do |ev|
+            @subscribed_events << { event: ev.to_sym, async: async }
+          end
           event_names
         end
 
         def subscribed_events
+          (@subscribed_events || []).map { |e| e[:event] }
+        end
+
+        def subscription_entries
           @subscribed_events || []
         end
 
@@ -140,26 +206,18 @@ module RageArch
         # subscribed_events with the publisher so they run when those events are published.
         def wire_subscriptions_to(publisher)
           registry.each do |symbol, klass|
-            next unless klass.respond_to?(:subscribed_events)
-            klass.subscribed_events.each do |event_name|
-              publisher.subscribe(event_name, symbol)
+            next unless klass.respond_to?(:subscription_entries)
+            klass.subscription_entries.each do |entry|
+              if entry[:async] && async_subscribers_enabled?
+                publisher.subscribe(entry[:event], async_runner(symbol))
+              else
+                publisher.subscribe(entry[:event], symbol)
+              end
             end
           end
           nil
         end
 
-        # Dep that uses Active Record for the model when not registered in the container.
-        # Example: ar_dep :user_store, User  (instead of default: RageArch::Deps::ActiveRecord.for(User))
-        def ar_dep(symbol, model_class)
-          @ar_deps ||= {}
-          @ar_deps[symbol] = model_class
-          deps(symbol)
-        end
-
-        def ar_deps
-          @ar_deps || {}
-        end
-
         def declared_deps
           @declared_deps || []
         end
@@ -175,12 +233,7 @@ module RageArch
         def build(symbol)
           klass = Base.resolve(symbol)
           deps_hash = klass.declared_deps.uniq.to_h do |s|
-            if klass.ar_deps.key?(s)
-              impl = container.registered?(s) ? container.resolve(s) : Deps::ActiveRecord.for(klass.ar_deps[s])
-              [s, impl]
-            else
-              [s, container.resolve(s)]
-            end
+            [s, container.resolve(s)]
           end
           klass.new(**deps_hash)
         end
@@ -188,6 +241,25 @@ module RageArch
         def container
           RageArch::Container
         end
+
+        private
+
+        def infer_use_case_symbol
+          return nil unless name
+          sym = ::ActiveSupport::Inflector.underscore(name).gsub("/", "_").to_sym
+          Base.registry[sym] = self
+          sym
+        end
+
+        def async_subscribers_enabled?
+          return false unless defined?(ActiveJob)
+          return true unless defined?(Rails) && Rails.application&.config&.respond_to?(:rage_arch) && Rails.application.config.rage_arch
+          Rails.application.config.rage_arch.async_subscribers != false
+        end
+
+        def async_runner(symbol)
+          ->(payload) { RageArch::SubscriberJob.perform_later(symbol.to_s, payload) }
+        end
       end
 
       def initialize(**injected_deps)
@@ -198,7 +270,6 @@ module RageArch
         raise NotImplementedError, "#{self.class}#call must be implemented"
       end
 
-      # From a use case: success(value) and failure(errors) instead of RageArch::Result.success/failure.
       def success(value = nil)
         RageArch::Result.success(value)
       end
@@ -213,10 +284,6 @@ module RageArch
         @injected_deps ||= {}
       end
 
-      # Resolve a dep: first the injected one; if missing, use the container.
-      # Optional: dep(:symbol, default: Implementation) when not registered.
-      # If default is an Active Record model class (e.g. Order), it is wrapped automatically
-      # with RageArch::Deps::ActiveRecord.for(default), so you can write dep(:order_store, default: Order).
       def dep(symbol, default: nil)
         return injected_deps[symbol] if injected_deps.key?(symbol)
 

data/lib/rage_arch/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RageArch
-  VERSION = "0.1.3"
+  VERSION = "0.2.0"
 end

data/lib/rage_arch.rb

@@ -8,6 +8,7 @@ require_relative "rage_arch/event_publisher"
 require_relative "rage_arch/use_case"
 require_relative "rage_arch/deps/active_record"
 require_relative "rage_arch/dep_scanner"
+require_relative "rage_arch/auto_registrar"
 
 module RageArch
   class << self
@@ -29,22 +30,49 @@ module RageArch
       Container.registered?(symbol)
     end
 
+    # Wraps execution in a sandboxed container scope.
+    # Registrations inside the block are scoped; originals are restored on exit.
+    def isolate(&block)
+      Container.push_scope
+      yield
+    ensure
+      Container.pop_scope
+    end
+
     # Verifies that all deps and use_cases declared by registered use cases are
     # available before the app handles any request. Call after all initializers run
-    # (done automatically by the Railtie unless config.rage.verify_deps = false).
+    # (done automatically by the Railtie unless config.rage_arch.verify_deps = false).
     #
     # Raises RuntimeError listing every missing dep/use_case if any are absent.
     # Returns true when everything is wired correctly.
     def verify_deps!
       errors = []
+      warnings = []
       scanned_methods = DepScanner.new.scan
 
       UseCase::Base.registry.each do |uc_symbol, klass|
-        klass.declared_deps.uniq.each do |dep_sym|
-          next if klass.ar_deps.key?(dep_sym) # ar_deps fall back to ActiveRecord, optional
+        # 6a. Symbol/convention mismatch warning
+        if klass.name
+          inferred = ActiveSupport::Inflector.underscore(klass.name).gsub("/", "_").to_sym
+          explicit = klass.instance_variable_get(:@use_case_symbol)
+          if explicit && explicit != inferred
+            warnings << "  #{klass} declares use_case_symbol :#{explicit} but convention infers :#{inferred} — explicit declaration overrides convention"
+          end
+        end
+
+        # 6c. Orphaned undo warning: undo defined but no call method
+        if klass.method_defined?(:undo) && !klass.method_defined?(:call, false)
+          warnings << "  #{klass} defines undo but has no call method"
+        end
 
+        klass.declared_deps.uniq.each do |dep_sym|
           unless Container.registered?(dep_sym)
-            errors << "  UseCase :#{uc_symbol} (#{klass}) declares dep :#{dep_sym} — not registered in container"
+            # 6b. AR model not found for _store dep
+            if dep_sym.to_s.end_with?("_store")
+              errors << "  UseCase :#{uc_symbol} (#{klass}) declares dep :#{dep_sym} — not registered in container and no AR model found"
+            else
+              errors << "  UseCase :#{uc_symbol} (#{klass}) declares dep :#{dep_sym} — not registered in container"
+            end
             next
           end
 
@@ -52,6 +80,7 @@ module RageArch
           next if required_methods.nil? || required_methods.empty?
 
           entry = Container.registry[dep_sym]
+          entry = Container.send(:scoped_lookup, dep_sym) if entry.nil?
           impl =
             if entry.is_a?(Class)
               entry
@@ -86,6 +115,11 @@ module RageArch
         end
       end
 
+      # Log warnings (non-fatal)
+      if warnings.any? && defined?(Rails) && Rails.logger
+        warnings.each { |w| Rails.logger.warn("[RageArch] #{w.strip}") }
+      end
+
       raise "RageArch boot verification failed:\n#{errors.join("\n")}" if errors.any?
 
       true

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rage_arch
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Rage Corp
@@ -65,23 +65,22 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-description: Gem to structure Rails apps with use cases, dependencies injectable by
-  symbol, and Result object (success/failure). Includes container, use case base,
-  and rails g rage_arch:use_case generator.
+description: Structure Rails apps with use cases, auto-registered dependencies, and
+  Result objects. Features convention-based wiring, domain events with async subscribers,
+  undo/rollback, ActiveRecord integration, and generators for scaffolds, use cases,
+  and deps.
 email:
-- ''
+- antonio.facundo1794@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
-- lib/generators/rage_arch/ar_dep_generator.rb
 - lib/generators/rage_arch/dep_generator.rb
 - lib/generators/rage_arch/dep_switch_generator.rb
 - lib/generators/rage_arch/install_generator.rb
 - lib/generators/rage_arch/scaffold_generator.rb
-- lib/generators/rage_arch/templates/ar_dep.rb.tt
 - lib/generators/rage_arch/templates/dep.rb.tt
 - lib/generators/rage_arch/templates/rage_arch.rb.tt
 - lib/generators/rage_arch/templates/scaffold/api_controller.rb.tt
@@ -96,6 +95,7 @@ files:
 - lib/generators/rage_arch/templates/use_case.rb.tt
 - lib/generators/rage_arch/use_case_generator.rb
 - lib/rage_arch.rb
+- lib/rage_arch/auto_registrar.rb
 - lib/rage_arch/container.rb
 - lib/rage_arch/controller.rb
 - lib/rage_arch/dep.rb
@@ -105,7 +105,9 @@ files:
 - lib/rage_arch/fake_event_publisher.rb
 - lib/rage_arch/railtie.rb
 - lib/rage_arch/result.rb
+- lib/rage_arch/rspec_helpers.rb
 - lib/rage_arch/rspec_matchers.rb
+- lib/rage_arch/subscriber_job.rb
 - lib/rage_arch/use_case.rb
 - lib/rage_arch/version.rb
 homepage: https://github.com/AntonioFacundo/rage_arch
@@ -129,5 +131,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.3
 specification_version: 4
-summary: 'Clean Architecture Light for Rails: use cases, injectable deps, Result.'
+summary: Convention-over-configuration Clean Architecture for Rails.
 test_files: []

data/lib/generators/rage_arch/ar_dep_generator.rb

@@ -1,74 +0,0 @@
-# frozen_string_literal: true
-
-require "rails/generators/base"
-require "rage_arch/dep_scanner"
-
-module RageArch
-  module Generators
-    class ArDepGenerator < ::Rails::Generators::Base
-      source_root File.expand_path("templates", __dir__)
-
-      argument :symbol_arg, type: :string, required: true, banner: "SYMBOL"
-      argument :model_arg, type: :string, required: true, banner: "MODEL"
-
-      desc "Create a dep class that wraps an Active Record model (build, find, save, update, destroy, list). Scans use cases for extra method calls and adds stubs for them. Example: rails g rage_arch:ar_dep post_store Post"
-      def create_ar_dep
-        @extra_methods = extra_methods
-        template "ar_dep.rb.tt", File.join("app/deps", module_dir, "#{dep_file_name}.rb")
-        say "Register in config/initializers/rage_arch.rb: RageArch.register(:#{symbol_name}, #{full_class_name}.new)", :green
-      end
-
-      STANDARD_AR_METHODS = %i[build find save update destroy list].freeze
-
-      # Methods that use cases call on this dep but are not in the standard AR adapter
-      def extra_methods
-        detected = scanner.methods_for(symbol_name).to_a
-        (detected - STANDARD_AR_METHODS).sort
-      end
-
-      def symbol_name
-        symbol_arg.to_s.underscore
-      end
-
-      def model_name
-        model_arg.camelize
-      end
-
-      def module_dir
-        inferred_module_dir || use_case_folder
-      end
-
-      def module_name
-        module_dir.camelize
-      end
-
-      def use_case_folder
-        scanner.folder_for(symbol_name)
-      end
-
-      def inferred_module_dir
-        entity = symbol_name.split("_").first
-        entity.pluralize
-      end
-
-      def dep_file_name
-        symbol_name
-      end
-
-      def class_name
-        symbol_name.camelize
-      end
-
-      def full_class_name
-        "#{module_name}::#{class_name}"
-      end
-
-      def scanner
-        @scanner ||= begin
-          root = destination_root
-          RageArch::DepScanner.new(File.join(root, "app", "use_cases")).tap(&:scan)
-        end
-      end
-    end
-  end
-end

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

@@ -1,46 +0,0 @@
-# frozen_string_literal: true
-
-# Dep for :<%= symbol_name %>. Wraps the <%= model_name %> Active Record model.
-# Register in config/initializers/rage_arch.rb: RageArch.register(:<%= symbol_name %>, <%= full_class_name %>.new)
-module <%= module_name %>
-  class <%= class_name %>
-    def initialize
-      @adapter = RageArch::Deps::ActiveRecord.for(<%= model_name %>)
-    end
-
-    def build(attrs = {})
-      @adapter.build(attrs)
-    end
-
-    def find(id)
-      @adapter.find(id)
-    end
-
-    def save(record)
-      @adapter.save(record)
-    end
-
-    def update(record, attrs)
-      @adapter.update(record, attrs)
-    end
-
-    def destroy(record)
-      @adapter.destroy(record)
-    end
-
-    def list(filters: {})
-      @adapter.list(filters: filters)
-    end
-<% if @extra_methods.any? -%>
-
-    # Extra methods detected from use cases — implement as needed
-<% @extra_methods.each do |method_name| -%>
-
-    def <%= method_name %>(*args, **kwargs)
-      # TODO: implement (e.g. delegate to @adapter or custom logic)
-      raise NotImplementedError, "<%= full_class_name %>#<%= method_name %>"
-    end
-<% end -%>
-<% end -%>
-  end
-end