rage_arch 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f6bda89e7d56a1bf058696878ebc40945b37536545435ec404256fa4de31933
-  data.tar.gz: 84dbdbfbe17258e5b9863234ccbcccfab633df75c74e576af390531f2e19080b
+  metadata.gz: 152d8ad4517ebc11b70103f2dadbc68d14363d66e93c83ed8513755b7f4d3faa
+  data.tar.gz: 5c15a711f1676d67644a75a66f7a7731504f56bc76ef75d1a2f420f4d900dae6
 SHA512:
-  metadata.gz: fee18ed0cdff7bf681d7e8c88188e572d22c74bc967602718c28768585601ab39dbf35096cc1f048527249b1dca26ba7aa7c50120212f9dee3319dca8454a30b
-  data.tar.gz: 5e10b325a636f84c10c539bcf4f72029a8b4acc64d15ec6f1d816cd794244c24167fae784358d2d7d4b9cce63e1ba2defa4b2136b091e33cbdde25e92e091317
+  metadata.gz: bb854fce9230a8e3dc7efbec5257ca1ea9f98d91bb417262d4fe3d3a014d1e47df337acffb93eea453f438d2c525f92c06d003b1e2eabc63f99d95af3a10e3bf
+  data.tar.gz: b350e0aa5995ac0b63a30a8ade4ab78314b1755f56884998622434b585fa1f5b7bf16ade394666706b6569561ea256c1be74386f8b711232ab73c16dd8982947

data/README.md

@@ -1,4 +1,4 @@
-# Rage
+# RageArch
 
 **Clean Architecture Light for Rails.** Business logic in testable use cases, thin controllers, and models free of callbacks.
 
@@ -58,18 +58,120 @@ 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
+# Register by instance
 RageArch.register(:order_store, MyApp::Deps::OrderStore.new)
-RageArch.register_ar(:user_store, User)  # automatic ActiveRecord wrapper
-RageArch.resolve(:order_store)
+
+# 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
 ```
 
 ---
 
+### 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
+```
+
+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)`.
+
+#### 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::Controller` — thin controller mixin
 
 ```ruby
@@ -84,6 +186,18 @@ 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
@@ -147,8 +261,11 @@ 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 |
 
 ---
 
@@ -179,15 +296,51 @@ 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
+```
+
+---
+
 ## 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
+- 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
+
+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_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
+```
 
 ---
 

data/lib/generators/rage_arch/ar_dep_generator.rb

@@ -15,7 +15,7 @@ module RageArch
       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: Rage.register(:#{symbol_name}, #{full_class_name}.new)", :green
+        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

data/lib/generators/rage_arch/dep_switch_generator.rb

@@ -18,7 +18,7 @@ module RageArch
         if options.empty?
           say "No implementations found for :#{symbol}.", :red
           say "Create a dep with: rails g rage_arch:dep #{symbol} [ClassName]"
-          say "Or add Rage.register_ar(:#{symbol}, Model) in config/initializers/rage_arch.rb", :red
+          say "Or add RageArch.register_ar(:#{symbol}, Model) in config/initializers/rage_arch.rb", :red
           return
         end
         chosen = if class_name_arg.present?
@@ -48,19 +48,19 @@ module RageArch
       end
 
       def initializer_path
-        File.join(destination_root, "config", "initializers", "rage.rb")
+        File.join(destination_root, "config", "initializers", "rage_arch.rb")
       end
 
       def find_ar_registration(symbol)
         path = initializer_path
         return nil unless File.exist?(path)
         content = File.read(path)
-        # Match active or commented: Rage.register_ar(:post_store, Post) or Rage.register_ar :post_store, Post
+        # Match active or commented: RageArch.register_ar(:post_store, Post) or RageArch.register_ar :post_store, Post
         content.each_line do |line|
           stripped = line.strip
           next if stripped.start_with?("#")
-          if stripped =~ /Rage\.register_ar\s*\(\s*:\s*#{Regexp.escape(symbol)}\s*,\s*(\w+)\s*\)/ ||
-             stripped =~ /Rage\.register_ar\s+:\s*#{Regexp.escape(symbol)}\s*,\s*(\w+)/
+          if stripped =~ /RageArch\.register_ar\s*\(\s*:\s*#{Regexp.escape(symbol)}\s*,\s*(\w+)\s*\)/ ||
+             stripped =~ /RageArch\.register_ar\s+:\s*#{Regexp.escape(symbol)}\s*,\s*(\w+)/
             return $1
           end
         end
@@ -68,8 +68,8 @@ module RageArch
         content.each_line do |line|
           stripped = line.strip.delete_prefix("#").strip
           next if stripped.empty?
-          if stripped =~ /Rage\.register_ar\s*\(\s*:\s*#{Regexp.escape(symbol)}\s*,\s*(\w+)\s*\)/ ||
-             stripped =~ /Rage\.register_ar\s+:\s*#{Regexp.escape(symbol)}\s*,\s*(\w+)/
+          if stripped =~ /RageArch\.register_ar\s*\(\s*:\s*#{Regexp.escape(symbol)}\s*,\s*(\w+)\s*\)/ ||
+             stripped =~ /RageArch\.register_ar\s+:\s*#{Regexp.escape(symbol)}\s*,\s*(\w+)/
             return $1
           end
         end
@@ -160,20 +160,20 @@ module RageArch
         content = comment_line_matching(content, symbol, :register_ar)
         # Uncomment or add the chosen registration
         chosen_line = option[:type] == :ar ?
-          "Rage.register_ar(:#{symbol}, #{option[:model]})" :
-          "Rage.register(:#{symbol}, #{option[:name]}.new)"
+          "RageArch.register_ar(:#{symbol}, #{option[:model]})" :
+          "RageArch.register(:#{symbol}, #{option[:name]}.new)"
         content = uncomment_or_add(content, symbol, option, chosen_line)
         File.write(path, content)
       end
 
       def comment_line_matching(content, symbol, form)
         if form == :register
-          content.gsub(/^(\s*)(Rage\.register\(:#{Regexp.escape(symbol)},\s*\S+\.new\))\s*$/, '\1# \2')
+          content.gsub(/^(\s*)(RageArch\.register\(:#{Regexp.escape(symbol)},\s*\S+\.new\))\s*$/, '\1# \2')
         else
           # register_ar with parens or with space
           content
-            .gsub(/^(\s*)(Rage\.register_ar\s*\(\s*:\s*#{Regexp.escape(symbol)}\s*,\s*\S+\s*\))\s*$/, '\1# \2')
-            .gsub(/^(\s*)(Rage\.register_ar\s+:\s*#{Regexp.escape(symbol)}\s*,\s*\S+)\s*$/, '\1# \2')
+            .gsub(/^(\s*)(RageArch\.register_ar\s*\(\s*:\s*#{Regexp.escape(symbol)}\s*,\s*\S+\s*\))\s*$/, '\1# \2')
+            .gsub(/^(\s*)(RageArch\.register_ar\s+:\s*#{Regexp.escape(symbol)}\s*,\s*\S+)\s*$/, '\1# \2')
         end
       end
 
@@ -182,18 +182,18 @@ module RageArch
           model = option[:model]
           # Uncomment if there is a commented register_ar line for this symbol and model
           content = content.gsub(
-            /^(\s*)#\s*(Rage\.register_ar\s*\(\s*:\s*#{Regexp.escape(symbol)}\s*,\s*#{Regexp.escape(model)}\s*\))\s*$/,
+            /^(\s*)#\s*(RageArch\.register_ar\s*\(\s*:\s*#{Regexp.escape(symbol)}\s*,\s*#{Regexp.escape(model)}\s*\))\s*$/,
             '\1\2'
           )
           content = content.gsub(
-            /^(\s*)#\s*(Rage\.register_ar\s+:\s*#{Regexp.escape(symbol)}\s*,\s*#{Regexp.escape(model)})\s*$/,
+            /^(\s*)#\s*(RageArch\.register_ar\s+:\s*#{Regexp.escape(symbol)}\s*,\s*#{Regexp.escape(model)})\s*$/,
             '\1\2'
           )
         else
           class_name = option[:name]
-          # Uncomment if there is a commented Rage.register line for this symbol and class
+          # Uncomment if there is a commented RageArch.register line for this symbol and class
           content = content.gsub(
-            /^(\s*)#\s*(Rage\.register\(:#{Regexp.escape(symbol)},\s*#{Regexp.escape(class_name)}\.new\))\s*$/,
+            /^(\s*)#\s*(RageArch\.register\(:#{Regexp.escape(symbol)},\s*#{Regexp.escape(class_name)}\.new\))\s*$/,
             '\1\2'
           )
         end

data/lib/generators/rage_arch/install_generator.rb

@@ -23,7 +23,7 @@ module RageArch
           say_status :skip, path, :yellow
           return
         end
-        template "rage.rb.tt", path
+        template "rage_arch.rb.tt", path
       end
 
       def create_directories

data/lib/generators/rage_arch/scaffold_generator.rb

@@ -12,7 +12,7 @@ module RageArch
       class_option :skip_model, type: :boolean, default: false, desc: "Skip model and migration (use when model already exists)"
       class_option :api, type: :boolean, default: false, desc: "Generate API-only controller (JSON responses, no views)"
 
-      desc "Generate a full Rage CRUD: model, migration, use cases (list/show/create/update/destroy), dep (AR), controller, and routes. With --api: JSON responses only, no views."
+      desc "Generate a full RageArch CRUD: model, migration, use cases (list/show/create/update/destroy), dep (AR), controller, and routes. With --api: JSON responses only, no views."
       def create_all
         create_model_and_migration
         create_use_cases
@@ -70,7 +70,7 @@ module RageArch
         return unless File.exist?(initializer_path)
         content = File.read(initializer_path)
         return if content.include?("register_ar(:#{repo_symbol})")
-        inject_line = "  Rage.register_ar(:#{repo_symbol}, #{model_class_name})\n"
+        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

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
+# Registered by rage_arch:scaffold in config/initializers/rage_arch.rb
 module <%= module_name %>
   class <%= singular_name.camelize %>Repo
     def initialize

data/lib/rage_arch/container.rb

@@ -2,7 +2,7 @@
 
 module RageArch
   # Container to register and resolve dependencies by symbol.
-  # Usage: Rage.register(:order_store, MyAdapter.new); Rage.resolve(:order_store)
+  # Usage: RageArch.register(:order_store, MyAdapter.new); RageArch.resolve(:order_store)
   class Container
     class << self
       def register(symbol, implementation = nil, &block)

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/deps/active_record.rb

@@ -4,7 +4,7 @@ module RageArch
   module Deps
     # Helper to use an Active Record model as a dep (minimal adapter).
     # Usage: RageArch::Deps::ActiveRecord.for(Order) → object exposing build, find, etc. on Order.
-    # In the container: Rage.register(:order_store, RageArch::Deps::ActiveRecord.for(Order))
+    # In the container: RageArch.register(:order_store, RageArch::Deps::ActiveRecord.for(Order))
     class ActiveRecord
       def self.for(model_class)
         new(model_class)

data/lib/rage_arch/event_publisher.rb

@@ -8,7 +8,7 @@ module RageArch
   # Setup in config/initializers/rage_arch.rb:
   #   publisher = RageArch::EventPublisher.new
   #   RageArch::UseCase::Base.wire_subscriptions_to(publisher)
-  #   Rage.register(:event_publisher, publisher)
+  #   RageArch.register(:event_publisher, publisher)
   class EventPublisher
     def initialize
       @handlers = Hash.new { |h, k| h[k] = [] }

data/lib/rage_arch/fake_event_publisher.rb

@@ -5,7 +5,7 @@ module RageArch
   # Use it to assert that a use case (or code) published expected events.
   #
   #   publisher = RageArch::FakeEventPublisher.new
-  #   Rage.register(:event_publisher, publisher)
+  #   RageArch.register(:event_publisher, publisher)
   #   RageArch::UseCase::Base.build(:create_post).call(title: "Hi")
   #   expect(publisher.published).to include(
   #     hash_including(event: :post_created, post_id: kind_of(Integer))

data/lib/rage_arch/railtie.rb

@@ -5,9 +5,9 @@ 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
 
     # 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.
@@ -25,7 +25,7 @@ module RageArch
       # 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.
+      # Set config.rage_arch.verify_deps = false to opt out.
     end
   end
 end

data/lib/rage_arch/rspec_matchers.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module RageArch
-  # RSpec matchers and helpers for testing Rage use cases and results.
+  # RSpec matchers and helpers for testing RageArch use cases and results.
   # In spec_helper.rb or rails_helper.rb add:
   #   require "rage_arch/rspec_matchers"
   # Then use: expect(result).to succeed_with(post: post) or expect(result).to fail_with_errors(["error"])

data/lib/rage_arch/use_case.rb

@@ -33,7 +33,7 @@ module RageArch
         def call(params = {})
           sym = self.class.use_case_symbol
           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?
@@ -66,8 +66,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
 

data/lib/rage_arch/version.rb

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

data/lib/rage_arch.rb

@@ -16,7 +16,7 @@ module RageArch
     end
 
     # Registers a dep that uses Active Record for the given model.
-    # Example: Rage.register_ar(:user_store, User)
+    # Example: RageArch.register_ar(:user_store, User)
     def register_ar(symbol, model_class)
       register(symbol, Deps::ActiveRecord.for(model_class))
     end
@@ -31,7 +31,7 @@ module RageArch
 
     # 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.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rage_arch
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.4
 platform: ruby
 authors:
 - Rage Corp