rage_arch 0.1.0

data/lib/rage_arch/dep_scanner.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+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.
+  # Also tracks which use case path each symbol appears in (for folder inference).
+  class DepScanner
+    def initialize(use_cases_root = nil)
+      @use_cases_root = use_cases_root || default_use_cases_root
+      @paths_for = nil
+    end
+
+    # Returns Hash symbol => Set of method names (e.g. { repo: [:save, :delete], gateway: [:get, :post] })
+    def scan
+      result = Hash.new { |h, k| h[k] = Set.new }
+      @paths_for = Hash.new { |h, k| h[k] = Set.new }
+      return result unless @use_cases_root && File.directory?(@use_cases_root)
+
+      root = @use_cases_root.to_s
+      root = root.chomp(File::SEPARATOR) + File::SEPARATOR
+
+      Dir[File.join(@use_cases_root, "**", "*.rb")].each do |path|
+        relative = path.sub(/\A#{Regexp.escape(root)}/, "")
+        content = File.read(path)
+        scan_file_content(content, result, relative)
+      end
+      result
+    end
+
+    # Returns Set of method names for the given symbol, or empty Set if unknown.
+    def methods_for(symbol)
+      scan[symbol.to_sym]
+    end
+
+      # Returns the folder name (first path segment) from use cases that reference this symbol,
+      # e.g. "likes" when the symbol is used in app/use_cases/likes/create.rb. Returns nil if
+      # no use cases reference the symbol or they are all at use_cases root.
+      def folder_for(symbol)
+        scan
+        paths = @paths_for[symbol.to_sym]
+        return nil if paths.nil? || paths.empty?
+
+        first_path = paths.min
+        seg = first_path.split(File::SEPARATOR).first
+        (seg && seg != first_path) ? seg : nil
+      end
+
+    private
+
+    def default_use_cases_root
+      return nil unless defined?(Rails) && Rails.respond_to?(:root)
+      Rails.root.join("app", "use_cases").to_s
+    end
+
+    def scan_file_content(content, result, relative_path = nil)
+      # 1) Constructor deps: deps :repo, :gateway, :service
+      constructor_symbols = content.scan(/deps\s*([^\n]+)/).flat_map do |match|
+        match[0].scan(/:(\w+)/).flatten.map(&:to_sym)
+      end.uniq
+
+      constructor_symbols.each { |sym| @paths_for[sym] << relative_path } if relative_path && @paths_for
+
+      # 2) Dynamic dep assignments: store = dep(:repo) or store = dep(:repo, default: Order)
+      var_to_symbol = {}
+      content.scan(/(\w+)\s*=\s*dep\s*\(\s*:(\w+)/) do |var, sym|
+        var_to_symbol[var] = sym.to_sym
+        @paths_for[sym.to_sym] << relative_path if relative_path && @paths_for
+      end
+
+      # 3) All symbols we care about (constructor + dynamic)
+      all_symbols = (constructor_symbols + var_to_symbol.values).uniq
+
+      # 4) Inline calls: dep(:repo).save( or dep(:repo, default: X).update(
+      content.scan(/dep\s*\(\s*:(\w+)[^)]*\)\s*\.\s*(\w+)\s*[\(]/m) do |sym, method|
+        result[sym.to_sym] << method.to_sym
+        @paths_for[sym.to_sym] << relative_path if relative_path && @paths_for
+      end
+
+      # 5) Method calls on constructor dep (receiver name == symbol): repo.save(, gateway.get(, service.get_all_items
+      #    Require a dot so we don't match "service\n  def call" as service.def
+      constructor_symbols.each do |sym|
+        regex = /\b#{Regexp.escape(sym.to_s)}\.\s*(\w+)\s*[\(\s]/m
+        content.scan(regex) { |m| result[sym] << (m.is_a?(Array) ? m[0] : m).to_sym }
+      end
+
+      # 6) Method calls on assigned variable (require dot)
+      var_to_symbol.each do |var, sym|
+        regex = /\b#{Regexp.escape(var)}\.\s*(\w+)\s*[\(\s]/m
+        content.scan(regex) { |m| result[sym] << (m.is_a?(Array) ? m[0] : m).to_sym }
+      end
+    end
+  end
+end

data/lib/rage_arch/deps/active_record.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+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))
+    class ActiveRecord
+      def self.for(model_class)
+        new(model_class)
+      end
+
+      def initialize(model_class)
+        @model_class = model_class
+      end
+
+      def find(id)
+        @model_class.find_by(id: id)
+      end
+
+      def build(attrs = {})
+        @model_class.new(attrs)
+      end
+
+      def save(record)
+        record.save
+      end
+
+      def update(record, attrs)
+        record.assign_attributes(attrs)
+        record.save
+      end
+
+      def destroy(record)
+        record.destroy
+      end
+
+      def list(filters: {})
+        scope = @model_class.all
+        filters.each { |key, value| scope = scope.where(key => value) if value.present? }
+        scope.to_a
+      end
+    end
+  end
+end

data/lib/rage_arch/event_publisher.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module RageArch
+  # Simple in-process event publisher for domain events.
+  # Use cases can subscribe via subscribe :event_name (or :all) in the use case class; wire with Base.wire_subscriptions_to(publisher).
+  # Handlers (blocks, callables, or use case symbols) run synchronously. For subscribe :all, payload includes :event.
+  #
+  # Setup in config/initializers/rage_arch.rb:
+  #   publisher = RageArch::EventPublisher.new
+  #   RageArch::UseCase::Base.wire_subscriptions_to(publisher)
+  #   Rage.register(:event_publisher, publisher)
+  class EventPublisher
+    def initialize
+      @handlers = Hash.new { |h, k| h[k] = [] }
+      @publish_depth = 0
+      @max_publish_depth = 100
+    end
+
+    # Subscribe to an event. Handler can be:
+    # - A block: called with payload (Hash with symbol keys)
+    # - A symbol: use case symbol; publisher runs UseCase::Base.build(symbol).call(payload)
+    # - Any callable responding to call(payload)
+    # For event_name :all, the payload passed to handlers includes :event (the name of the event being published).
+    def subscribe(event_name, handler = nil, &block)
+      callable = handler || block
+      callable = use_case_runner(handler) if handler.is_a?(Symbol)
+      raise ArgumentError, "Provide a block or a callable handler" unless callable
+      @handlers[event_name.to_sym] << callable
+      self
+    end
+
+    # Publish an event. Payload is passed as a Hash (symbol keys) to each handler.
+    # Handlers for this event run first; then handlers for :all run with payload.merge(event: event_name).
+    # Re-entrancy is limited to avoid infinite loops (e.g. a handler that publishes the same event).
+    def publish(event_name, **payload)
+      event_sym = event_name.to_sym
+      @publish_depth += 1
+      raise "Event publisher re-entrancy limit reached (possible circular publish)" if @publish_depth > @max_publish_depth
+      begin
+        @handlers[event_sym].each do |callable|
+          callable.call(payload)
+        end
+        all_payload = payload.merge(event: event_sym)
+        @handlers[:all].each do |callable|
+          callable.call(all_payload)
+        end
+      ensure
+        @publish_depth -= 1
+      end
+      nil
+    end
+
+    private
+
+    def use_case_runner(symbol)
+      ->(payload) { UseCase::Base.build(symbol).call(payload) }
+    end
+  end
+end

data/lib/rage_arch/fake_event_publisher.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module RageArch
+  # Event publisher that records all published events for tests. Does not run any handlers.
+  # Use it to assert that a use case (or code) published expected events.
+  #
+  #   publisher = RageArch::FakeEventPublisher.new
+  #   Rage.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))
+  #   )
+  #   publisher.clear  # optional: reset between examples
+  class FakeEventPublisher
+    attr_reader :published
+
+    def initialize
+      @published = []
+    end
+
+    # Same signature as EventPublisher#publish. Records the event and payload; does not run handlers.
+    def publish(event_name, **payload)
+      @published << { event: event_name.to_sym, payload: payload }
+      nil
+    end
+
+    def subscribe(_event_name, _handler = nil, &_block)
+      # No-op: we don't run handlers in tests
+      self
+    end
+
+    def clear
+      @published.clear
+      self
+    end
+  end
+end

data/lib/rage_arch/railtie.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "rage_arch"
+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
+
+    # 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|
+      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
+
+      RageArch.verify_deps! if app.config.rage.verify_deps != false
+    end
+  end
+end

data/lib/rage_arch/result.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module RageArch
+  # Result object for an operation: success (with value) or failure (with errors).
+  # Controllers use result.success?, result.value, and result.errors.
+  class Result
+    def self.success(value)
+      new(success: true, value: value, errors: [])
+    end
+
+    def self.failure(errors)
+      new(success: false, value: nil, errors: Array(errors))
+    end
+
+    attr_reader :value, :errors
+
+    def initialize(success:, value:, errors:)
+      @success = success
+      @value = value
+      @errors = errors
+    end
+
+    def success?
+      @success
+    end
+
+    def failure?
+      !@success
+    end
+  end
+end

data/lib/rage_arch/rspec_matchers.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module RageArch
+  # RSpec matchers and helpers for testing Rage 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"])
+  module RSpecMatchers
+    # Matcher: expect(result).to succeed_with(key: value, ...)
+    # Asserts result.success? and that result.value (when a Hash) includes the given key/value pairs.
+    # When result.value is not a Hash, pass a single expected value: expect(result).to succeed_with(42)
+    def succeed_with(*expected_list, **expected_hash)
+      SucceedWithMatcher.new(expected_list, expected_hash)
+    end
+
+    # Matcher: expect(result).to fail_with_errors(errors)
+    # Asserts result.failure? and that result.errors matches the given errors (array or RSpec matcher).
+    def fail_with_errors(errors)
+      FailWithErrorsMatcher.new(errors)
+    end
+
+    class SucceedWithMatcher
+      include RSpec::Matchers::Composable
+
+      def initialize(expected_list, expected_hash)
+        @expected_list = expected_list
+        @expected_hash = expected_hash
+      end
+
+      def matches?(result)
+        @result = result
+        return false unless result.respond_to?(:success?) && result.success?
+
+        if @expected_hash.any?
+          return false unless result.value.is_a?(Hash)
+          value = result.value
+          @expected_hash.all? do |k, v|
+            val = value.key?(k) ? value[k] : value[k.to_s]
+            values_match?(v, val)
+          end
+        elsif @expected_list.one?
+          values_match?(@expected_list.first, result.value)
+        else
+          @expected_list.empty? ? true : values_match?(@expected_list, result.value)
+        end
+      end
+
+      def failure_message
+        return "expected success but got failure (errors: #{@result.errors.inspect})" if @result.respond_to?(:failure?) && @result.failure?
+        return "expected result.value to match" unless @result.respond_to?(:value)
+        "expected result.value #{@result.value.inspect} to match #{description}"
+      end
+
+      def description
+        if @expected_hash.any?
+          "succeed with #{@expected_hash.inspect}"
+        else
+          "succeed with #{@expected_list.inspect}"
+        end
+      end
+    end
+
+    class FailWithErrorsMatcher
+      include RSpec::Matchers::Composable
+
+      def initialize(errors)
+        @expected_errors = errors
+      end
+
+      def matches?(result)
+        @result = result
+        return false unless result.respond_to?(:failure?) && result.failure?
+        return false unless result.respond_to?(:errors)
+        values_match?(@expected_errors, @result.errors)
+      end
+
+      def failure_message
+        if @result.respond_to?(:success?) && @result.success?
+          "expected failure but got success (value: #{@result.value.inspect})"
+        else
+          "expected result.errors #{@result.errors.inspect} to match #{@expected_errors.inspect}"
+        end
+      end
+
+      def description
+        "fail with errors #{@expected_errors.inspect}"
+      end
+    end
+  end
+end
+
+RSpec.configure do |config|
+  config.include RageArch::RSpecMatchers
+end

data/lib/rage_arch/use_case.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+module RageArch
+  module UseCase
+    # Runs another use case by symbol. Used when a use case declares use_cases :other_symbol.
+    class Runner
+      def initialize(symbol)
+        @symbol = symbol
+      end
+
+      def call(*args, **kwargs)
+        Base.build(@symbol).call(*args, **kwargs)
+      end
+    end
+
+    # Base for use cases: register by symbol, deps injected via constructor.
+    #
+    # Usage:
+    #   class CreateOrder < RageArch::UseCase::Base
+    #     use_case_symbol :create_order
+    #     deps :order_store, :notifications
+    #
+    #     def call(params = {})
+    #       order = order_store.build(params)
+    #       success(order)
+    #     end
+    #   end
+    #
+    # Building: RageArch::UseCase::Base.build(:create_order) resolves deps from
+    # RageArch::Container and returns an instance of the use case.
+    class Base
+      module Instrumentation
+        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|
+              result = super(params)
+              payload[:success] = result.success?
+              payload[:errors] = result.errors unless result.success?
+              payload[:result] = result
+              auto_publish_if_enabled(sym, params, result)
+              result
+            end
+          else
+            result = super(params)
+            auto_publish_if_enabled(sym, params, result)
+            result
+          end
+        end
+
+        private
+
+        def auto_publish_if_enabled(use_case_symbol, params, result)
+          return unless auto_publish_enabled?
+          return unless self.class.container.registered?(:event_publisher)
+          publisher = self.class.container.resolve(:event_publisher)
+          publisher.publish(
+            use_case_symbol,
+            use_case: use_case_symbol,
+            params: params,
+            success: result.success?,
+            value: result.value,
+            errors: result.errors
+          )
+        end
+
+        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
+        end
+      end
+
+      include Instrumentation
+
+      class << self
+        def inherited(subclass)
+          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
+          end
+        end
+
+        def deps(*symbols)
+          @declared_deps ||= []
+          @declared_deps.concat(symbols)
+          symbols.each do |sym|
+            define_method(sym) { injected_deps.fetch(sym) }
+          end
+          private(*symbols) if symbols.any?
+          symbols
+        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.
+        def use_cases(*symbols)
+          @declared_use_cases ||= []
+          @declared_use_cases.concat(symbols)
+          symbols.each do |sym|
+            define_method(sym) { Runner.new(sym) }
+          end
+          private(*symbols) if symbols.any?
+          symbols
+        end
+
+        def declared_use_cases
+          @declared_use_cases || []
+        end
+
+        # 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)
+          @subscribed_events ||= []
+          @subscribed_events.concat(event_names.map(&:to_sym))
+          event_names
+        end
+
+        def subscribed_events
+          @subscribed_events || []
+        end
+
+        # Opt-out of auto-publish when this use case finishes (e.g. for the logger use case itself).
+        def skip_auto_publish
+          @skip_auto_publish = true
+        end
+
+        def skip_auto_publish?
+          @skip_auto_publish == true
+        end
+
+        # Call once after loading use cases and before registering the publisher. Registers each use case's
+        # 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)
+            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
+
+        def registry
+          @registry ||= {}
+        end
+
+        def resolve(symbol)
+          Base.registry[symbol] or raise KeyError, "Use case not registered: #{symbol.inspect}"
+        end
+
+        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
+          end
+          klass.new(**deps_hash)
+        end
+
+        def container
+          RageArch::Container
+        end
+      end
+
+      def initialize(**injected_deps)
+        @injected_deps = injected_deps
+      end
+
+      def call(_params = {})
+        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
+
+      def failure(errors)
+        RageArch::Result.failure(errors)
+      end
+
+      private
+
+      def injected_deps
+        @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)
+
+        if container.registered?(symbol)
+          container.resolve(symbol)
+        elsif default
+          impl = resolve_default(default)
+          impl.is_a?(Class) ? impl.new : impl
+        else
+          raise KeyError, "Dep not registered and no default: #{symbol.inspect}"
+        end
+      end
+
+      def resolve_default(default)
+        if default.is_a?(Class) && active_record_model?(default)
+          RageArch::Deps::ActiveRecord.for(default)
+        else
+          default
+        end
+      end
+
+      def active_record_model?(klass)
+        defined?(ActiveRecord::Base) && klass < ActiveRecord::Base
+      rescue
+        false
+      end
+
+      def container
+        self.class.container
+      end
+    end
+  end
+end

data/lib/rage_arch/version.rb

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