servactory 2.16.1 → 3.0.0.rc1

data/lib/servactory/test_kit/rspec/matchers/base/attribute_matcher.rb

@@ -0,0 +1,324 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Matchers
+        module Base
+          # Base class for RSpec matchers that validate Servactory attribute definitions.
+          #
+          # ## Purpose
+          #
+          # AttributeMatcher provides the foundation for testing service attribute
+          # definitions (inputs, internals, outputs) in Servactory services. It implements
+          # the RSpec matcher protocol with fluent API for chaining validation rules.
+          #
+          # ## Usage
+          #
+          # Subclasses define specific attribute type matchers:
+          #
+          # ```ruby
+          # class HaveServiceInputMatcher < Base::AttributeMatcher
+          #   for_attribute_type :input
+          #
+          #   register_submatcher :required,
+          #                       class_name: "Input::RequiredSubmatcher",
+          #                       mutually_exclusive_with: [:optional]
+          # end
+          # ```
+          #
+          # In RSpec tests:
+          #
+          # ```ruby
+          # expect(MyService).to have_service_input(:name)
+          #   .type(String)
+          #   .required
+          #   .inclusion(%w[admin user])
+          # ```
+          #
+          # ## Architecture
+          #
+          # Works with:
+          # - SubmatcherRegistry - provides DSL for registering submatchers
+          # - SubmatcherContext - carries context data to submatchers
+          # - Submatcher - base class for individual validation rules
+          #
+          # ## Features
+          #
+          # - **Fluent API** - chain methods for readable test assertions
+          # - **Dynamic Chain Methods** - generated from submatcher registry
+          # - **Mutual Exclusivity** - conflicting options replace each other
+          # - **Composable** - works with RSpec's compound matchers
+          # - **Block Expectations** - supports `expect { }.to` syntax
+          class AttributeMatcher # rubocop:disable Metrics/ClassLength
+            include SubmatcherRegistry
+            include RSpec::Matchers::Composable
+
+            class << self
+              # @return [Symbol] The attribute type this matcher validates (:input, :internal, :output)
+              attr_reader :attribute_type
+
+              # Sets the attribute type for this matcher class.
+              #
+              # @param type [Symbol] The attribute type (:input, :internal, :output)
+              # @return [void]
+              def for_attribute_type(type)
+                @attribute_type = type
+              end
+            end
+
+            # @return [Class] The Servactory service class being tested
+            attr_reader :described_class
+
+            # @return [Symbol] The name of the attribute being validated
+            attr_reader :attribute_name
+
+            # @return [Array, nil] Type classes passed to the types chain method
+            attr_reader :option_types
+
+            # Creates a new attribute matcher instance.
+            #
+            # @param described_class [Class] The Servactory service class to test
+            # @param attribute_name [Symbol] The name of the attribute to validate
+            def initialize(described_class, attribute_name)
+              @described_class = described_class
+              @attribute_name = attribute_name
+              @submatchers = []
+              @option_types = nil
+              @last_submatcher = nil
+
+              build_chain_methods_from_registry
+            end
+
+            # Indicates this matcher supports block expectations.
+            #
+            # Required by RSpec for matchers used with `expect { }.to` syntax.
+            #
+            # @return [Boolean] Always returns true
+            def supports_block_expectations?
+              true
+            end
+
+            # Checks if all submatchers pass for the given subject.
+            #
+            # @param subject [Object] The RSpec subject (typically nil for service class matchers)
+            # @return [Boolean] True if all submatchers pass, false otherwise
+            def matches?(subject)
+              @subject = subject
+              failing_submatchers.empty?
+            end
+
+            # Builds a human-readable description of what this matcher validates.
+            #
+            # @return [String] Description including attribute name and all submatcher descriptions
+            def description
+              submatcher_descriptions = submatchers.map(&:description).join(", ")
+              "#{attribute_name} with #{submatcher_descriptions}"
+            end
+
+            # Builds the failure message when the matcher does not pass.
+            #
+            # @return [String] Explanation of what was expected and what was missing
+            def failure_message
+              "Expected #{expectation}, which #{missing_options}"
+            end
+
+            # Builds the failure message for negated expectations.
+            #
+            # @return [String] Explanation for negated expectation failure
+            def failure_message_when_negated
+              "Did not expect #{expectation} with specified options"
+            end
+
+            protected
+
+            # @return [Array<Submatcher>] Collection of registered submatchers
+            attr_reader :submatchers
+
+            # @return [Object] The RSpec subject passed to matches?
+            attr_reader :subject
+
+            # @return [Submatcher, nil] The most recently added submatcher
+            attr_reader :last_submatcher
+
+            # Returns the attribute type from the class-level setting.
+            #
+            # @return [Symbol] The attribute type (:input, :internal, :output)
+            def attribute_type
+              self.class.attribute_type
+            end
+
+            # Returns the pluralized attribute type for accessing service info.
+            #
+            # @return [Symbol] Pluralized attribute type (:inputs, :internals, :outputs)
+            def attribute_type_plural
+              @attribute_type_plural ||= attribute_type.to_s.pluralize.to_sym
+            end
+
+            # Fetches attribute definition data from the service class.
+            #
+            # @return [Hash] The attribute definition hash from service info
+            def attribute_data
+              @attribute_data ||=
+                described_class
+                .info
+                .public_send(attribute_type_plural)
+                .fetch(attribute_name)
+            end
+
+            # Returns the i18n root key configured for the service.
+            #
+            # @return [String, nil] The i18n root key for error messages
+            def i18n_root_key
+              @i18n_root_key ||= described_class.config.i18n_root_key
+            end
+
+            # Builds the expectation string for failure messages.
+            #
+            # @return [String] Human-readable expectation description
+            def expectation
+              "#{described_class.name} to have a service #{attribute_type} attribute named #{attribute_name}"
+            end
+
+            # Finds submatchers that did not pass validation.
+            #
+            # @return [Array<Submatcher>] Submatchers where matches? returned false
+            def failing_submatchers
+              @failing_submatchers ||= submatchers.reject { |m| m.matches?(subject) }
+            end
+
+            # Collects missing option messages from failing submatchers.
+            #
+            # @return [String] Comma-separated list of missing option descriptions
+            def missing_options
+              failing_submatchers.map(&:missing_option).select(&:present?).join(", ")
+            end
+
+            # Adds a submatcher to the collection, replacing any of the same class.
+            #
+            # @param submatcher [Submatcher] The submatcher to add
+            # @return [void]
+            def add_submatcher(submatcher)
+              remove_submatcher(submatcher.class)
+              @last_submatcher = submatcher
+              submatchers << submatcher
+            end
+
+            # Removes all submatchers of the specified class.
+            #
+            # @param matcher_class [Class] The submatcher class to remove
+            # @return [void]
+            def remove_submatcher(matcher_class)
+              submatchers.delete_if { |sm| sm.is_a?(matcher_class) }
+            end
+
+            private
+
+            # Dynamically defines chain methods from registered submatcher definitions.
+            #
+            # Called during initialization to create fluent API methods like
+            # `.type()`, `.required()`, `.optional()`, etc.
+            #
+            # @return [void]
+            def build_chain_methods_from_registry
+              self.class.submatcher_definitions.each_value do |definition|
+                define_chain_method_for(definition)
+              end
+            end
+
+            # Defines a chain method and its aliases for a submatcher definition.
+            #
+            # Creates a singleton method that:
+            # 1. Extracts options hash if applicable
+            # 2. Removes mutually exclusive submatchers
+            # 3. Stores option_types if needed
+            # 4. Builds and adds the submatcher
+            #
+            # @param definition [SubmatcherDefinition] The submatcher definition
+            # @return [void]
+            def define_chain_method_for(definition) # rubocop:disable Metrics/MethodLength
+              define_singleton_method(definition.chain_method) do |*args|
+                # For methods that accept trailing options hash (like target(value, name: :option)),
+                # we need to extract it. We use a heuristic: if the method expects options AND
+                # the last arg is a Hash with Symbol keys that look like option keys.
+                options = extract_options_hash(args, definition)
+
+                handle_mutually_exclusive(definition)
+
+                @option_types = definition.transform_args.call(args, options) if definition.stores_option_types
+
+                submatcher = build_submatcher(definition, args, options)
+                add_submatcher(submatcher)
+                self
+              end
+
+              definition.chain_aliases.each do |alias_name|
+                define_singleton_method(alias_name) do |*args|
+                  public_send(definition.chain_method, *args)
+                end
+              end
+            end
+
+            # Extracts trailing options hash from arguments if the definition accepts them.
+            #
+            # @param args [Array] The method arguments
+            # @param definition [SubmatcherDefinition] The submatcher definition
+            # @return [Hash] Extracted options hash or empty hash
+            def extract_options_hash(args, definition)
+              # Only extract trailing options hash if the definition explicitly accepts them.
+              return {} unless definition.accepts_trailing_options
+              return {} unless args.last.is_a?(Hash)
+              return {} if args.last.is_a?(Class)
+
+              args.pop || {}
+            end
+
+            # Removes submatchers that are mutually exclusive with the current one.
+            #
+            # @param definition [SubmatcherDefinition] The current submatcher definition
+            # @return [void]
+            def handle_mutually_exclusive(definition)
+              definition.mutually_exclusive_with.each do |exclusive_name|
+                exclusive_def = self.class.submatcher_definitions[exclusive_name]
+                next unless exclusive_def
+
+                submatcher_class = resolve_submatcher_class(exclusive_def.class_name)
+                remove_submatcher(submatcher_class)
+              end
+            end
+
+            # Builds a submatcher instance with context and transformed arguments.
+            #
+            # @param definition [SubmatcherDefinition] The submatcher definition
+            # @param args [Array] Original method arguments
+            # @param options [Hash] Extracted options hash
+            # @return [Submatcher] The constructed submatcher instance
+            def build_submatcher(definition, args, options) # rubocop:disable Metrics/MethodLength
+              context = SubmatcherContext.new(
+                described_class:,
+                attribute_type:,
+                attribute_name:,
+                attribute_data:,
+                option_types: definition.requires_option_types ? option_types : nil,
+                last_submatcher: definition.requires_last_submatcher ? last_submatcher : nil,
+                i18n_root_key:
+              )
+
+              transformed_args = definition.transform_args.call(args, options)
+              submatcher_class = resolve_submatcher_class(definition.class_name)
+              submatcher_class.new(context, *transformed_args)
+            end
+
+            # Resolves submatcher class name to actual class constant.
+            #
+            # @param class_name [String] Relative class name (e.g., "Input::RequiredSubmatcher")
+            # @return [Class] The submatcher class
+            def resolve_submatcher_class(class_name)
+              "Servactory::TestKit::Rspec::Matchers::Submatchers::#{class_name}".constantize
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/servactory/test_kit/rspec/matchers/base/submatcher.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Matchers
+        module Base
+          # Abstract base class for individual validation rules in attribute matchers.
+          #
+          # ## Purpose
+          #
+          # Submatcher provides the foundation for specific validation checks like
+          # type validation, required/optional status, default values, etc.
+          # Each submatcher validates one aspect of a service attribute definition.
+          #
+          # ## Usage
+          #
+          # Create a subclass and implement required abstract methods:
+          #
+          # ```ruby
+          # class RequiredSubmatcher < Base::Submatcher
+          #   def description
+          #     "required"
+          #   end
+          #
+          #   protected
+          #
+          #   def passes?
+          #     fetch_option(:required) == true
+          #   end
+          #
+          #   def build_failure_message
+          #     "expected input to be required, but it was optional"
+          #   end
+          # end
+          # ```
+          #
+          # ## Abstract Methods
+          #
+          # Subclasses must implement:
+          # - `description` - human-readable description for test output
+          # - `passes?` - validation logic returning boolean
+          # - `build_failure_message` - explanation when validation fails
+          #
+          # ## Architecture
+          #
+          # Works with:
+          # - SubmatcherContext - provides attribute data and metadata
+          # - AttributeMatcher - manages collection of submatchers
+          # - Concerns - provides helper methods for data access and comparison
+          class Submatcher
+            include RSpec::Matchers::Composable
+            include Concerns::AttributeDataAccess
+            include Concerns::ErrorMessageBuilder
+            include Concerns::ValueComparison
+
+            # @return [String] Failure message when validation does not pass
+            attr_reader :missing_option
+
+            # Creates a new submatcher instance.
+            #
+            # @param context [SubmatcherContext] Context with attribute data and metadata
+            def initialize(context)
+              @context = context
+              @missing_option = ""
+            end
+
+            # Checks if this submatcher's validation passes.
+            #
+            # @param _subject [Object] RSpec subject (unused, kept for interface compatibility)
+            # @return [Boolean] True if validation passes
+            def matches?(_subject)
+              if passes?
+                true
+              else
+                @missing_option = build_failure_message
+                false
+              end
+            end
+
+            # Returns the failure message for RSpec output.
+            #
+            # @return [String] The failure message
+            def failure_message
+              @missing_option
+            end
+
+            # Returns the failure message for negated expectations.
+            #
+            # @return [String] The negated failure message
+            def failure_message_when_negated
+              "expected not to #{description}"
+            end
+
+            # Returns a human-readable description of what this submatcher validates.
+            #
+            # @abstract Subclasses must implement this method
+            # @return [String] Description for test output
+            # @raise [NotImplementedError] If not implemented by subclass
+            def description
+              raise NotImplementedError, "#{self.class} must implement #description"
+            end
+
+            protected
+
+            # Performs the actual validation logic.
+            #
+            # @abstract Subclasses must implement this method
+            # @return [Boolean] True if validation passes
+            # @raise [NotImplementedError] If not implemented by subclass
+            def passes?
+              raise NotImplementedError, "#{self.class} must implement #passes?"
+            end
+
+            # Builds a descriptive failure message when validation fails.
+            #
+            # @abstract Subclasses must implement this method
+            # @return [String] Explanation of why validation failed
+            # @raise [NotImplementedError] If not implemented by subclass
+            def build_failure_message
+              raise NotImplementedError, "#{self.class} must implement #build_failure_message"
+            end
+
+            private
+
+            # @return [SubmatcherContext] The context with attribute data
+            attr_reader :context
+          end
+        end
+      end
+    end
+  end
+end

data/lib/servactory/test_kit/rspec/matchers/base/submatcher_context.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Matchers
+        module Base
+          # Data transfer object carrying context for submatcher validation.
+          #
+          # ## Purpose
+          #
+          # SubmatcherContext encapsulates all the information a submatcher needs
+          # to perform its validation. It provides a clean interface for passing
+          # attribute metadata, service class info, and dependent data between
+          # the parent matcher and individual submatchers.
+          #
+          # ## Usage
+          #
+          # Created by AttributeMatcher and passed to each submatcher:
+          #
+          # ```ruby
+          # context = SubmatcherContext.new(
+          #   described_class: MyService,
+          #   attribute_type: :input,
+          #   attribute_name: :user_id,
+          #   attribute_data: { type: Integer, required: true }
+          # )
+          #
+          # submatcher = RequiredSubmatcher.new(context)
+          # ```
+          #
+          # ## Attributes
+          #
+          # - `described_class` - The Servactory service class being tested
+          # - `attribute_type` - :input, :internal, or :output
+          # - `attribute_name` - Name of the attribute being validated
+          # - `attribute_data` - Hash with attribute definition (type, required, etc.)
+          # - `option_types` - Type classes passed via .type() chain method
+          # - `last_submatcher` - Previous submatcher (for dependent validations)
+          # - `i18n_root_key` - Root key for i18n error messages
+          class SubmatcherContext
+            # @return [Class] The Servactory service class being tested
+            attr_reader :described_class
+
+            # @return [Symbol] The attribute type (:input, :internal, :output)
+            attr_reader :attribute_type
+
+            # @return [Symbol] The name of the attribute being validated
+            attr_reader :attribute_name
+
+            # @return [Hash] The attribute definition data from service info
+            attr_reader :attribute_data
+
+            # @return [Array, nil] Type classes from the .type() chain method
+            attr_reader :option_types
+
+            # @return [Submatcher, nil] The previous submatcher for chained validations
+            attr_reader :last_submatcher
+
+            # @return [String, nil] The i18n root key for error messages
+            attr_reader :i18n_root_key
+
+            # Creates a new submatcher context.
+            #
+            # @param described_class [Class] The Servactory service class
+            # @param attribute_type [Symbol] The attribute type (:input, :internal, :output)
+            # @param attribute_name [Symbol] The attribute name
+            # @param attribute_data [Hash] The attribute definition data
+            # @param option_types [Array, nil] Type classes from .type() method
+            # @param last_submatcher [Submatcher, nil] Previous submatcher for chaining
+            # @param i18n_root_key [String, nil] Root key for i18n messages
+            def initialize(
+              described_class:,
+              attribute_type:,
+              attribute_name:,
+              attribute_data:,
+              option_types: nil,
+              last_submatcher: nil,
+              i18n_root_key: nil
+            )
+              @described_class = described_class
+              @attribute_type = attribute_type
+              @attribute_name = attribute_name
+              @attribute_data = attribute_data
+              @option_types = option_types
+              @last_submatcher = last_submatcher
+              @i18n_root_key = i18n_root_key
+            end
+
+            # Returns the pluralized attribute type for accessing service info.
+            #
+            # @return [Symbol] Pluralized type (:inputs, :internals, :outputs)
+            def attribute_type_plural
+              @attribute_type_plural ||= attribute_type.to_s.pluralize.to_sym
+            end
+          end
+        end
+      end
+    end
+  end
+end