servactory 2.16.1 → 3.0.0.rc1

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

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Matchers
+        module Base
+          # Registry mixin providing DSL for registering submatchers in attribute matchers.
+          #
+          # ## Purpose
+          #
+          # SubmatcherRegistry provides a class-level DSL for declaratively registering
+          # submatchers in AttributeMatcher subclasses. It handles inheritance of
+          # submatcher definitions and configuration options for each submatcher.
+          #
+          # ## Usage
+          #
+          # Include this module in AttributeMatcher subclasses:
+          #
+          # ```ruby
+          # class HaveServiceInputMatcher < Base::AttributeMatcher
+          #   include SubmatcherRegistry
+          #
+          #   register_submatcher :required,
+          #                       class_name: "Input::RequiredSubmatcher",
+          #                       mutually_exclusive_with: [:optional]
+          #
+          #   register_submatcher :types,
+          #                       class_name: "Shared::TypesSubmatcher",
+          #                       chain_method: :type,
+          #                       chain_aliases: [:types],
+          #                       stores_option_types: true
+          # end
+          # ```
+          #
+          # ## Features
+          #
+          # - **Declarative Registration** - register submatchers with options hash
+          # - **Chain Method Generation** - creates fluent API methods automatically
+          # - **Inheritance Support** - subclasses inherit parent's submatcher definitions
+          # - **Argument Transformation** - customize how arguments are passed to submatchers
+          # - **Mutual Exclusivity** - define conflicting submatchers that replace each other
+          #
+          # ## Architecture
+          #
+          # Works with:
+          # - AttributeMatcher - uses registry to build chain methods
+          # - SubmatcherDefinition - holds configuration for each submatcher
+          # - Submatcher - base class for actual validation logic
+          module SubmatcherRegistry
+            # Extends the including class with ClassMethods.
+            #
+            # @param base [Class] The class including this module
+            # @return [void]
+            def self.included(base)
+              base.extend(ClassMethods)
+            end
+
+            # Class methods added to the including class.
+            module ClassMethods
+              # Returns the hash of registered submatcher definitions.
+              #
+              # @return [Hash{Symbol => SubmatcherDefinition}] Submatcher definitions by name
+              def submatcher_definitions
+                @submatcher_definitions ||= {}
+              end
+
+              # Registers a new submatcher with configuration options.
+              #
+              # ## Options
+              #
+              # - `:class_name` - Relative class path (e.g., "Input::RequiredSubmatcher")
+              # - `:chain_method` - Method name for fluent API (defaults to name)
+              # - `:chain_aliases` - Additional method names that call chain_method
+              # - `:transform_args` - Lambda to transform method args before passing to submatcher
+              # - `:requires_option_types` - Pass option_types to submatcher context
+              # - `:requires_last_submatcher` - Pass previous submatcher to context
+              # - `:mutually_exclusive_with` - Array of submatcher names to remove when this is added
+              # - `:stores_option_types` - Store transformed args as option_types
+              # - `:accepts_trailing_options` - Extract trailing hash as keyword arguments
+              #
+              # @param name [Symbol] Unique identifier for this submatcher
+              # @param options [Hash] Configuration options
+              # @return [SubmatcherDefinition] The created definition
+              def register_submatcher(name, options = {}) # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+                submatcher_definitions[name] = SubmatcherDefinition.new(
+                  name:,
+                  class_name: options[:class_name],
+                  chain_method: options[:chain_method] || name,
+                  chain_aliases: options[:chain_aliases] || [],
+                  transform_args: options[:transform_args] || ->(args, _kwargs = {}) { args },
+                  requires_option_types: options[:requires_option_types] || false,
+                  requires_last_submatcher: options[:requires_last_submatcher] || false,
+                  mutually_exclusive_with: options[:mutually_exclusive_with] || [],
+                  stores_option_types: options[:stores_option_types] || false,
+                  accepts_trailing_options: options[:accepts_trailing_options] || false
+                )
+              end
+
+              # Copies submatcher definitions to subclasses.
+              #
+              # @param subclass [Class] The inheriting class
+              # @return [void]
+              def inherited(subclass)
+                super
+                subclass.instance_variable_set(
+                  :@submatcher_definitions,
+                  submatcher_definitions.dup
+                )
+              end
+            end
+
+            # Value object holding configuration for a single submatcher registration.
+            #
+            # ## Purpose
+            #
+            # Encapsulates all configuration options for a submatcher, including
+            # how to generate chain methods, transform arguments, and handle
+            # mutual exclusivity with other submatchers.
+            #
+            # ## Attributes
+            #
+            # - `name` - Unique identifier for this submatcher
+            # - `class_name` - Relative path to submatcher class
+            # - `chain_method` - Name of the fluent API method
+            # - `chain_aliases` - Alternative method names
+            # - `transform_args` - Lambda for argument transformation
+            # - `requires_option_types` - Whether submatcher needs type information
+            # - `requires_last_submatcher` - Whether submatcher needs previous submatcher
+            # - `mutually_exclusive_with` - Conflicting submatcher names
+            # - `stores_option_types` - Whether to store args as option_types
+            # - `accepts_trailing_options` - Whether to extract trailing hash
+            class SubmatcherDefinition
+              # @return [Symbol] Unique identifier for this submatcher
+              attr_reader :name
+
+              # @return [String] Relative class path (e.g., "Input::RequiredSubmatcher")
+              attr_reader :class_name
+
+              # @return [Symbol] Method name for the fluent API
+              attr_reader :chain_method
+
+              # @return [Array<Symbol>] Alternative method names
+              attr_reader :chain_aliases
+
+              # @return [Proc] Lambda to transform arguments
+              attr_reader :transform_args
+
+              # @return [Boolean] Whether submatcher needs option_types in context
+              attr_reader :requires_option_types
+
+              # @return [Boolean] Whether submatcher needs last_submatcher in context
+              attr_reader :requires_last_submatcher
+
+              # @return [Array<Symbol>] Names of mutually exclusive submatchers
+              attr_reader :mutually_exclusive_with
+
+              # @return [Boolean] Whether to store transformed args as option_types
+              attr_reader :stores_option_types
+
+              # @return [Boolean] Whether to extract trailing hash as options
+              attr_reader :accepts_trailing_options
+
+              # Creates a new submatcher definition.
+              #
+              # @param name [Symbol] Unique identifier
+              # @param class_name [String] Relative class path
+              # @param chain_method [Symbol] Fluent API method name
+              # @param chain_aliases [Array<Symbol>] Alternative method names
+              # @param transform_args [Proc] Argument transformation lambda
+              # @param requires_option_types [Boolean] Pass option_types to context
+              # @param requires_last_submatcher [Boolean] Pass last_submatcher to context
+              # @param mutually_exclusive_with [Array<Symbol>] Conflicting submatchers
+              # @param stores_option_types [Boolean] Store args as option_types
+              # @param accepts_trailing_options [Boolean] Extract trailing hash
+              def initialize(
+                name:,
+                class_name:,
+                chain_method: nil,
+                chain_aliases: nil,
+                transform_args: nil,
+                requires_option_types: false,
+                requires_last_submatcher: false,
+                mutually_exclusive_with: nil,
+                stores_option_types: false,
+                accepts_trailing_options: false
+              )
+                @name = name
+                @class_name = class_name
+                @chain_method = chain_method
+                @chain_aliases = chain_aliases
+                @transform_args = transform_args
+                @requires_option_types = requires_option_types
+                @requires_last_submatcher = requires_last_submatcher
+                @mutually_exclusive_with = mutually_exclusive_with
+                @stores_option_types = stores_option_types
+                @accepts_trailing_options = accepts_trailing_options
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/servactory/test_kit/rspec/matchers/concerns/attribute_data_access.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Matchers
+        module Concerns
+          # Concern providing accessor methods for attribute data in submatchers.
+          #
+          # ## Purpose
+          #
+          # AttributeDataAccess provides convenient methods for submatchers to access
+          # attribute definition data from the context. This includes the service class,
+          # attribute metadata, and helper methods for fetching specific options.
+          #
+          # ## Usage
+          #
+          # Include in submatcher classes:
+          #
+          # ```ruby
+          # class MySubmatcher < Base::Submatcher
+          #   include Concerns::AttributeDataAccess
+          #
+          #   def passes?
+          #     # Access attribute data directly
+          #     fetch_option(:required) == true
+          #   end
+          # end
+          # ```
+          #
+          # ## Methods Provided
+          #
+          # - `described_class` - the service class being tested
+          # - `attribute_type` - :input, :internal, or :output
+          # - `attribute_name` - name of the attribute
+          # - `attribute_data` - full attribute definition hash
+          # - `fetch_option` - get specific option from attribute data
+          # - `option_present?` - check if option exists and has value
+          module AttributeDataAccess
+            # Includes InstanceMethods in the including class.
+            #
+            # @param base [Class] The class including this concern
+            # @return [void]
+            def self.included(base)
+              base.include(InstanceMethods)
+            end
+
+            # Instance methods added by this concern.
+            module InstanceMethods
+              # @return [Class, nil] The Servactory service class from context
+              def described_class = context&.described_class
+
+              # @return [Symbol, nil] The attribute type from context
+              def attribute_type = context&.attribute_type
+
+              # @return [Symbol, nil] The attribute name from context
+              def attribute_name = context&.attribute_name
+
+              # @return [Symbol, nil] The pluralized attribute type from context
+              def attribute_type_plural = context&.attribute_type_plural
+
+              # @return [String, nil] The i18n root key from context
+              def i18n_root_key = context&.i18n_root_key
+
+              # Returns the attribute definition data hash.
+              #
+              # @return [Hash] The attribute data from context
+              def attribute_data
+                context.attribute_data
+              end
+
+              # Fetches a specific option from attribute data.
+              #
+              # @param key [Symbol] The option key to fetch
+              # @param default [Object, nil] Default value if key not present
+              # @return [Object] The option value or default
+              def fetch_option(key, default = nil)
+                attribute_data.fetch(key, default)
+              end
+
+              # Checks if an option is present and has a meaningful value.
+              #
+              # Returns false if the key doesn't exist, or if the value is nil
+              # or empty (for collections).
+              #
+              # @param key [Symbol] The option key to check
+              # @return [Boolean] True if option exists with non-empty value
+              def option_present?(key)
+                return false unless attribute_data.key?(key)
+
+                value = attribute_data[key]
+                !value.nil? && (!value.respond_to?(:empty?) || !value.empty?)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/servactory/test_kit/rspec/matchers/concerns/error_message_builder.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Matchers
+        module Concerns
+          # Concern providing helper methods for building error messages in submatchers.
+          #
+          # ## Purpose
+          #
+          # ErrorMessageBuilder provides consistent formatting methods for constructing
+          # readable failure messages. It handles diff-style messages showing expected
+          # vs actual values, and list formatting.
+          #
+          # ## Usage
+          #
+          # Include in submatcher classes:
+          #
+          # ```ruby
+          # class TypesSubmatcher < Base::Submatcher
+          #   include Concerns::ErrorMessageBuilder
+          #
+          #   def build_failure_message
+          #     build_diff_message(
+          #       expected: [String, Integer],
+          #       actual: [Boolean],
+          #       prefix: "type mismatch"
+          #     )
+          #   end
+          # end
+          # ```
+          #
+          # ## Methods Provided
+          #
+          # - `build_diff_message` - creates expected/got diff output
+          # - `format_value` - formats values for display (handles Arrays, Classes, etc.)
+          # - `build_list_message` - formats item lists with optional prefix
+          module ErrorMessageBuilder
+            # Includes InstanceMethods in the including class.
+            #
+            # @param base [Class] The class including this concern
+            # @return [void]
+            def self.included(base)
+              base.include(InstanceMethods)
+            end
+
+            # Instance methods added by this concern.
+            module InstanceMethods
+              # Builds a diff-style message showing expected vs actual values.
+              #
+              # @param expected [Object] The expected value
+              # @param actual [Object] The actual value found
+              # @param prefix [String] Optional prefix text before the diff
+              # @return [String] Formatted diff message
+              def build_diff_message(expected:, actual:, prefix: "")
+                <<~MESSAGE
+                  #{prefix}
+                    expected: #{format_value(expected)}
+                         got: #{format_value(actual)}
+                MESSAGE
+              end
+
+              # Formats a value for human-readable display.
+              #
+              # Handles special cases:
+              # - Arrays: formats each element recursively
+              # - Hashes: uses inspect
+              # - Classes: shows class name
+              # - nil: shows "nil" string
+              # - Others: uses inspect
+              #
+              # @param value [Object] The value to format
+              # @return [String] Formatted string representation
+              def format_value(value) # rubocop:disable Metrics/MethodLength
+                case value
+                when Array
+                  "[#{value.map { |v| format_value(v) }.join(', ')}]"
+                when Hash
+                  value.inspect
+                when Class
+                  value.name
+                when nil
+                  "nil"
+                else # rubocop:disable Lint/DuplicateBranch
+                  value.inspect
+                end
+              end
+
+              # Builds a comma-separated list message.
+              #
+              # @param items [Array] Items to list
+              # @param prefix [String] Optional prefix before the list
+              # @return [String] Formatted list or "(empty)" if no items
+              def build_list_message(items, prefix: "")
+                return "#{prefix}(empty)" if items.empty?
+
+                "#{prefix}#{items.join(', ')}"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/servactory/test_kit/rspec/matchers/concerns/value_comparison.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Servactory
+  module TestKit
+    module Rspec
+      module Matchers
+        module Concerns
+          # Concern providing value comparison methods for submatchers.
+          #
+          # ## Purpose
+          #
+          # ValueComparison provides flexible comparison methods that handle various
+          # types of expected values including RSpec matchers, classes (for type checking),
+          # arrays, and plain values.
+          #
+          # ## Usage
+          #
+          # Include in submatcher classes:
+          #
+          # ```ruby
+          # class DefaultSubmatcher < Base::Submatcher
+          #   include Concerns::ValueComparison
+          #
+          #   def passes?
+          #     values_match?(@expected_default, fetch_option(:default))
+          #   end
+          # end
+          # ```
+          #
+          # ## Comparison Rules
+          #
+          # - RSpec matchers (respond_to :matches?) - delegates to matcher
+          # - Classes - checks if actual is_a?(expected)
+          # - Arrays - element-wise recursive comparison
+          # - Other values - uses equality (==)
+          module ValueComparison
+            # Includes InstanceMethods in the including class.
+            #
+            # @param base [Class] The class including this concern
+            # @return [void]
+            def self.included(base)
+              base.include(InstanceMethods)
+            end
+
+            # Instance methods added by this concern.
+            module InstanceMethods
+              # Compares expected and actual values with type-aware logic.
+              #
+              # Supports:
+              # - RSpec matchers (anything responding to :matches?)
+              # - Class comparison (type checking with is_a?)
+              # - Array comparison (recursive element-wise)
+              # - Standard equality (==)
+              #
+              # @param expected [Object] The expected value or matcher
+              # @param actual [Object] The actual value to compare
+              # @return [Boolean] True if values match
+              def values_match?(expected, actual)
+                if expected.respond_to?(:matches?)
+                  expected.matches?(actual)
+                elsif expected.is_a?(Class)
+                  actual.is_a?(expected)
+                elsif expected.is_a?(Array) && actual.is_a?(Array)
+                  arrays_match?(expected, actual)
+                else
+                  expected == actual
+                end
+              end
+
+              # Compares two arrays element-by-element.
+              #
+              # @param expected [Array] Expected array
+              # @param actual [Array] Actual array
+              # @return [Boolean] True if arrays match (same size and matching elements)
+              def arrays_match?(expected, actual)
+                return false unless expected.size == actual.size
+
+                expected.zip(actual).all? { |e, a| values_match?(e, a) }
+              end
+
+              # Compares two type collections for equality (order-independent).
+              #
+              # @param expected_types [Array<Class>] Expected type classes
+              # @param actual_types [Array<Class>] Actual type classes
+              # @return [Boolean] True if same set of types
+              def types_match?(expected_types, actual_types)
+                expected_set = Set.new(expected_types)
+                actual_set = Set.new(actual_types)
+                expected_set == actual_set
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end