rage_arch 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4be8aa2c59b8c0e1f4d15a2af2c9075a21a674cf80401ddd7e8ad655ce3a6f8
-  data.tar.gz: e2cccfe9fec1c8e630b2b3eff45eab25ec208075dcce4d54422f913693b1f14e
+  metadata.gz: 152d8ad4517ebc11b70103f2dadbc68d14363d66e93c83ed8513755b7f4d3faa
+  data.tar.gz: 5c15a711f1676d67644a75a66f7a7731504f56bc76ef75d1a2f420f4d900dae6
 SHA512:
-  metadata.gz: c03dd919d2b32226ec4ea0975c2d748d2e4f6049b44a5e635e192b9d5cecac120b68ec600151e2c08ca94e7b5f4a28a456ffb4cf92365c516f13de1ba250efa6
-  data.tar.gz: 2087a0af99636d741197191157c7f2c395ba81183363c656ead9e437fba232360f6d2072a428f2fb0a363ee4743c2646182e8c46dfa38075804680df22b11bf6
+  metadata.gz: bb854fce9230a8e3dc7efbec5257ca1ea9f98d91bb417262d4fe3d3a014d1e47df337acffb93eea453f438d2c525f92c06d003b1e2eabc63f99d95af3a10e3bf
+  data.tar.gz: b350e0aa5995ac0b63a30a8ade4ab78314b1755f56884998622434b585fa1f5b7bf16ade394666706b6569561ea256c1be74386f8b711232ab73c16dd8982947

data/README.md

@@ -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/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/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,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/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.3"
+  VERSION = "0.1.4"
 end

data/lib/rage_arch.rb

@@ -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.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Rage Corp