rampart-core 0.1.1

data/lib/rampart/domain/value_object.rb

@@ -0,0 +1,12 @@
+require "dry-struct"
+
+module Rampart
+  module Domain
+    class ValueObject < Dry::Struct
+      # Value objects are compared by their attributes
+      # Dry::Struct provides immutability and value equality by default
+    end
+  end
+end
+
+

data/lib/rampart/engine_loader.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Rampart
+  # Generic loader for Rails engines using hexagonal architecture
+  #
+  # This loader handles auto-discovery and loading of domain, application, and
+  # infrastructure components in the correct order. It works around the mismatch
+  # between directory structure (app/{layer}/{context}/) and Ruby namespace
+  # conventions by using explicit eager loading.
+  #
+  # Usage in your engine:
+  #   module YourContext
+  #     class Engine < ::Rails::Engine
+  #       config.to_prepare do
+  #         Rampart::EngineLoader.load_all(
+  #           engine_root: YourContext::Engine.root,
+  #           context_name: "your_context"
+  #         )
+  #       end
+  #     end
+  #   end
+  class EngineLoader
+    class << self
+      # Load all hexagonal architecture components for an engine
+      #
+      # @param engine_root [Pathname] Root path of the Rails engine
+      # @param context_name [String] Snake-case name of the bounded context (e.g., "cat_content")
+      def load_all(engine_root:, context_name:)
+        load_domain_layer(engine_root, context_name)
+        load_application_layer(engine_root, context_name)
+        load_infrastructure_layer(engine_root, context_name)
+      end
+
+      private
+
+      def load_domain_layer(root, context_name)
+        domain = root.join("app/domain/#{context_name}")
+        return unless domain.exist?
+
+        # Load files in specific order: errors, value objects, entities, events, aggregates, services, ports
+        load_directory(domain, pattern: "*_error.rb")
+        load_directory(domain, pattern: "*_exception.rb")
+        load_directory(domain.join("value_objects"))
+        load_directory(domain.join("entities"))
+        load_directory(domain.join("events"))
+        load_directory(domain.join("aggregates"))
+        load_directory(domain.join("services"))
+        load_directory(domain.join("ports"))
+        
+        # Load any remaining files at domain root
+        load_directory(domain, pattern: "*.rb")
+      end
+
+      def load_application_layer(root, context_name)
+        app = root.join("app/application/#{context_name}")
+        return unless app.exist?
+
+        # Load all application layer files
+        load_directory(app.join("commands"))
+        load_directory(app.join("queries"))
+        load_directory(app.join("services"))
+        load_directory(app, pattern: "*.rb")
+      end
+
+      def load_infrastructure_layer(root, context_name)
+        infra = root.join("app/infrastructure/#{context_name}")
+        return unless infra.exist?
+
+        # Load persistence layer first (base_record before models)
+        persistence = infra.join("persistence")
+        if persistence.exist?
+          load_directory(persistence, pattern: "base_record.rb")
+          load_directory(persistence.join("models"))
+          load_directory(persistence.join("mappers"))
+          load_directory(persistence.join("repositories"))
+        end
+
+        # Load other infrastructure components
+        load_directory(infra.join("adapters"))
+        load_directory(infra.join("http"))
+        load_directory(infra.join("wiring"))
+        load_directory(infra, pattern: "*.rb")
+      end
+
+      def load_directory(dir, pattern: "**/*.rb")
+        return unless dir.exist?
+
+        Dir.glob(dir.join(pattern)).sort.each do |file|
+          next if File.directory?(file)
+          if Rails.env.development? || Rails.env.test?
+            load file.to_s
+          else
+            require_dependency file
+          end
+        end
+      end
+    end
+  end
+end
+
+

data/lib/rampart/ports/event_bus_port.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Rampart
+  module Ports
+    class EventBusPort < SecondaryPort
+      # Publish one or many domain events to downstream subscribers or transports.
+      abstract_method :publish
+    end
+  end
+end

data/lib/rampart/ports/secondary_port.rb

@@ -0,0 +1,13 @@
+module Rampart
+  module Ports
+    class SecondaryPort
+      def self.abstract_method(*names)
+        names.each do |name|
+          define_method(name) { |*| raise NotImplementedError, "#{self.class}##{name}" }
+        end
+      end
+    end
+  end
+end
+
+

data/lib/rampart/support/container.rb

@@ -0,0 +1,28 @@
+require "dry-container"
+require "dry-auto_inject"
+
+module Rampart
+  # Base container for dependency registration.
+  # Each bounded context should create its own container extending this.
+  #
+  # Example:
+  #   module CatContent
+  #     class Container
+  #       extend Dry::Container::Mixin
+  #
+  #       register(:cat_listing_repo) { Infrastructure::CatListingRepository.new }
+  #       register(:id_generator) { Infrastructure::UuidGenerator.new }
+  #       register(:clock) { Infrastructure::SystemClock.new }
+  #       register(:transaction) { Infrastructure::ActiveRecordTransaction.new }
+  #       register(:event_bus) { Infrastructure::EventBus.new }
+  #     end
+  #
+  #     Import = Dry::AutoInject(Container)
+  #   end
+  module Container
+    def self.included(base)
+      base.extend(Dry::Container::Mixin)
+    end
+  end
+end
+

data/lib/rampart/support/result.rb

@@ -0,0 +1,9 @@
+require "dry-monads"
+
+module Rampart
+  module Result
+    include Dry::Monads[:result]
+  end
+end
+
+

data/lib/rampart/support/types.rb

@@ -0,0 +1,9 @@
+require "dry-types"
+
+module Rampart
+  module Types
+    include Dry.Types()
+  end
+end
+
+

data/lib/rampart/testing/architecture_matchers.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+require "ripper"
+
+module Rampart
+  module Testing
+    # RSpec matchers for enforcing architectural rules in Rampart applications.
+    # These matchers verify layer boundaries, dependency injection policies,
+    # immutability, and structural contracts.
+    module ArchitectureMatchers
+      extend RSpec::Matchers::DSL
+
+      # Helper methods for AST analysis using Ripper.
+      # Encapsulates the complexity of parsing Ruby code to finding method calls,
+      # constant references (legacy), and variable mutations.
+      class MatcherHelpers
+        # Returns the source file path for a given class.
+        def self.source_file_for(klass)
+          Object.const_source_location(klass.name)&.first
+        end
+
+        # Returns an array of file:line locations where instance variables are mutated
+        # (assigned to) outside of the initialize method.
+        def self.mutable_instance_var_locations(source_file)
+          sexp = Ripper.sexp(File.read(source_file))
+          return [] unless sexp
+
+          collect_ivasgn(sexp, nil, [], source_file).uniq
+        end
+
+        # Recursively collects instance variable assignments (:ivasgn) from the AST.
+        # Ignores assignments within the 'initialize' method.
+        def self.collect_ivasgn(node, current_method, mutations, source_file)
+          return mutations unless node.is_a?(Array)
+
+          case node[0]
+          when :def
+            method_name = node[1][1]
+            body = node[3]
+            collect_ivasgn(body, method_name, mutations, source_file)
+          when :defs
+            method_name = node[2][1]
+            body = node[4]
+            collect_ivasgn(body, method_name, mutations, source_file)
+          when :ivasgn
+            token = node[1]
+            line = token[2][0] if token.is_a?(Array)
+            mutations << "#{source_file}:#{line}" if current_method != "initialize"
+          else
+            node.each do |child|
+              collect_ivasgn(child, current_method, mutations, source_file)
+            end
+          end
+
+          mutations
+        end
+
+        # Scans ruby content for `resolve(:key)` method calls.
+        # Yields the key (symbol/string) and line number for each occurrence.
+        # Used to verify DI wiring in controllers/services.
+        def self.scan_resolves(content, &block)
+          sexp = Ripper.sexp(content)
+          return unless sexp
+
+          recursive_scan_resolves(sexp, &block)
+        end
+
+        # Recursively traverses AST looking for method calls named "resolve".
+        # Supports `resolve(:key)` and `resolve :key`.
+        def self.recursive_scan_resolves(node, &block)
+          return unless node.is_a?(Array)
+
+          if node[0] == :method_add_arg
+            # Case: resolve(:key) -> [:method_add_arg, call_node, args_node]
+            call_node = node[1]
+            args_node = node[2]
+            
+            method_name = extract_method_name(call_node)
+            if method_name == "resolve"
+              key = extract_symbol_from_args(args_node)
+              line = extract_line_number(call_node)
+              yield(key, line) if key
+            end
+          elsif node[0] == :command || node[0] == :command_call
+             # Case: resolve :key -> [:command, name, args]
+             method_name = extract_method_name(node)
+             if method_name == "resolve"
+                # Args are usually the last element
+                args_node = node.last
+                key = extract_symbol_from_args(args_node)
+                line = extract_line_number(node)
+                yield(key, line) if key
+             end
+          end
+
+          node.each do |child|
+            recursive_scan_resolves(child, &block) if child.is_a?(Array)
+          end
+        end
+
+        # Extracts method name from various call node types (:fcall, :call, :command, etc.)
+        def self.extract_method_name(node)
+          if node[0] == :fcall || node[0] == :command
+            # [:fcall, [:@ident, "resolve", ...]]
+            return node[1][1]
+          elsif node[0] == :call
+            # [:call, receiver, :., [:@ident, "resolve", ...]]
+            return node[3][1]
+          elsif node[0] == :command_call
+            # [:command_call, receiver, :., [:@ident, "resolve", ...], args]
+            return node[3][1]
+          end
+          nil
+        end
+
+        # Extracts the first symbol argument from an arguments node list.
+        def self.extract_symbol_from_args(node)
+          found = nil
+          traverse_for_symbol(node) { |s| found = s }
+          found
+        end
+
+        # Traverses argument nodes to find a symbol literal.
+        def self.traverse_for_symbol(node, &block)
+          return unless node.is_a?(Array)
+          if node[0] == :symbol_literal
+             symbol_node = node[1]
+             if symbol_node[0] == :symbol
+               content = symbol_node[1]
+               # Handle :@ident (bare symbol) or :@tstring_content (quoted symbol)
+               if content[0] == :@ident || content[0] == :@tstring_content
+                  yield content[1]
+               end
+             end
+          end
+          node.each { |c| traverse_for_symbol(c, &block) if c.is_a?(Array) }
+        end
+        
+        # Extracts line number from a node or its children.
+        def self.extract_line_number(node)
+           line = nil
+           traverse_for_line(node) { |l| line = l; break }
+           line
+        end
+        
+        # Traverses node to find the first token with line number information.
+        def self.traverse_for_line(node, &block)
+           return unless node.is_a?(Array)
+           node.each do |child|
+             # Token structure: [type, value, [line, col]]
+             if child.is_a?(Array) && child.size >= 2 && child.last.is_a?(Array) && child.last.size == 2 && child.last.first.is_a?(Integer)
+               yield child.last.first
+             else
+               traverse_for_line(child, &block)
+             end
+           end
+        end
+        
+        # Returns ancestors of a class that are Rails components.
+        def self.rails_ancestors_for(klass)
+          rails_prefixes = %w[ActiveRecord ActionDispatch ActionController ActiveSupport Rails]
+          shared = Object.ancestors
+          klass.ancestors.compact.reject { |ancestor| shared.include?(ancestor) }.select do |ancestor|
+            rails_prefixes.any? { |prefix| ancestor.name&.start_with?(prefix) }
+          end
+        end
+      end
+
+      # Verifies that a class does not inherit from any Rails classes/modules
+      # (ActiveRecord, ActionController, etc.).
+      matcher :have_no_rails_dependencies do
+        match do |klass|
+          @rails_ancestors = MatcherHelpers.rails_ancestors_for(klass)
+          @rails_ancestors.empty?
+        end
+
+        failure_message do |klass|
+          "expected #{klass} to avoid Rails dependencies, found #{@rails_ancestors.map(&:name).join(', ')}"
+        end
+      end
+
+      # Verifies that a class inherits from a specific Rampart base class.
+      matcher :inherit_from_rampart_base do |base_class|
+        match do |klass|
+          klass < base_class
+        end
+
+        failure_message do |klass|
+          "expected #{klass} to inherit from #{base_class}, but ancestors are: #{klass.ancestors.take(5).map(&:name).join(' -> ')}"
+        end
+      end
+
+      # Verifies that a class implements all abstract methods defined in a Port module.
+      # Checks that the method is defined on the class itself, not just inherited/mixed in from the port.
+      matcher :implement_all_abstract_methods do |port_class|
+        match do |implementation_class|
+          @abstract_methods = port_class.instance_methods(false)
+          @missing_methods = @abstract_methods.reject do |method_name|
+            implementation_class.instance_methods.include?(method_name) &&
+              implementation_class.instance_method(method_name).owner != port_class
+          end
+          @missing_methods.empty?
+        end
+
+        failure_message do |implementation_class|
+          "expected #{implementation_class} to implement #{port_class} abstract methods: #{@missing_methods.join(', ')}"
+        end
+      end
+
+      # Verifies that a class has no public setter methods (ending in `=`).
+      matcher :be_immutable do
+        match do |klass|
+          @setter_methods = klass.instance_methods(false).grep(/=$/).reject { |name| name == :== }
+          @setter_methods.empty?
+        end
+
+        failure_message do |klass|
+          "expected #{klass} to be immutable, found setter methods: #{@setter_methods.join(', ')}"
+        end
+      end
+
+      # Verifies that a class does not mutate instance variables outside of `initialize`.
+      # Uses static analysis (Ripper) to find assignments.
+      matcher :have_no_mutable_instance_variables do
+        match do |klass|
+          source_file = MatcherHelpers.source_file_for(klass)
+          return true unless source_file
+
+          @mutation_locations = MatcherHelpers.mutable_instance_var_locations(source_file)
+          @mutation_locations.empty?
+        end
+
+        failure_message do |klass|
+          "expected #{klass} to avoid instance variable mutation outside initialize, found assignments at: #{@mutation_locations.join(', ')}"
+        end
+      end
+
+      # Verifies that an object instance has dependencies (instance variables) of expected types.
+      # dependency_types: { ivar_name: ExpectedClass }
+      matcher :have_dependencies do |dependency_types|
+        match do |object|
+          @mismatches = []
+          dependency_types.each do |ivar_name, expected_type|
+            value = object.instance_variable_get("@#{ivar_name}")
+            if value.nil?
+              @mismatches << "Missing dependency @#{ivar_name}"
+            elsif !value.is_a?(expected_type) && !value.class.ancestors.include?(expected_type)
+              @mismatches << "Dependency @#{ivar_name} is a #{value.class}, expected #{expected_type}"
+            end
+          end
+          @mismatches.empty?
+        end
+
+        failure_message do |object|
+          "expected #{object} to have correct dependencies:\n#{@mismatches.join("\n")}"
+        end
+      end
+
+      # Verifies that a source file only calls `resolve(:key)` for keys in the allowed list.
+      # Uses static analysis to find `resolve` calls.
+      matcher :only_resolve_allowed_dependencies do |allowed_keys|
+        match do |file_path|
+          @violations = []
+          content = File.read(file_path)
+          
+          MatcherHelpers.scan_resolves(content) do |key, line|
+            unless allowed_keys.include?(key.to_sym)
+              @violations << "Line #{line}: resolves :#{key} (not in allowed list)"
+            end
+          end
+          @violations.empty?
+        end
+
+        failure_message do |file_path|
+          "expected #{file_path} to only resolve allowed dependencies:\n#{@violations.join("\n")}\nAllowed: #{allowed_keys.sort.join(', ')}"
+        end
+      end
+    end
+  end
+end