spec_forge 0.5.0 → 0.7.0

data/lib/spec_forge/matchers.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module SpecForge
+  #
+  # Provides custom RSpec matchers for SpecForge
+  #
+  # This singleton class is responsible for defining custom RSpec matchers
+  # that can be used in SpecForge tests. It makes these matchers available
+  # through RSpec's matcher system.
+  #
+  # @example Defining all matchers
+  #   SpecForge::Matchers.define
+  #
+  class Matchers
+    include Singleton
+
+    #
+    # Defines all custom matchers for use in SpecForge tests
+    #
+    # This is the main entry point that should be called once during
+    # initialization to make all custom matchers available.
+    #
+    def self.define
+      instance.define_all
+    end
+
+    #
+    # Defines all available custom matchers
+    #
+    # This method calls individual definition methods for each
+    # custom matcher supported by SpecForge.
+    #
+    def define_all
+      define_forge_and
+      define_have_size
+    end
+
+    private
+
+    #
+    # Defines the forge_and matcher for combining multiple matchers.
+    # Explicitly has "forge_" prefix to avoid potentially clashing with someone's
+    # existing custom matchers.
+    #
+    # This matcher allows chaining multiple matchers together with an AND
+    # condition, requiring all matchers to pass. It provides detailed
+    # failure messages showing which specific matchers failed.
+    #
+    # @example Using forge_and in a test
+    #   expect(response.body).to forge_and(
+    #     have_key("name"),
+    #     have_key("email"),
+    #     include("active" => be_truthy)
+    #   )
+    #
+    # @private
+    #
+    def define_forge_and
+      RSpec::Matchers.define :forge_and do |*matchers|
+        match do |actual|
+          @failures = []
+
+          matchers.each do |matcher|
+            next if matcher.matches?(actual)
+
+            @failures << [matcher, matcher.failure_message]
+          end
+
+          @failures.empty?
+        end
+
+        failure_message do
+          pass_count = matchers.size - @failures.size
+
+          message = "Expected to satisfy ALL of these conditions on:\n   #{actual.inspect}\n\n"
+
+          matchers.each_with_index do |matcher, i|
+            failure = @failures.find { |m, _| m == matcher }
+
+            if failure
+              message += "❌ #{i + 1}. #{matcher.description}\n"
+              message += "      → #{failure[1].gsub(/\s+/, " ").strip}\n\n"
+            else
+              message += "✅ #{i + 1}. #{matcher.description}\n\n"
+            end
+          end
+
+          message += "#{pass_count}/#{matchers.size} conditions met"
+          message
+        end
+
+        description do
+          "match all: " + matchers.join_map(", ", &:description)
+        end
+      end
+    end
+
+    #
+    # Defines the have_size matcher for checking collection sizes
+    #
+    # This matcher verifies that an object responds to the :size method
+    # and that its size matches the expected value.
+    #
+    # @example Using have_size in a test
+    #   expect(response.body["items"]).to have_size(5)
+    #
+    # @private
+    #
+    def define_have_size
+      RSpec::Matchers.define :have_size do |expected|
+        expected = RSpec::Matchers::BuiltIn::Eq.new(expected) if expected.is_a?(Integer)
+
+        match do |actual|
+          actual.respond_to?(:size) && expected.matches?(actual.size)
+        end
+
+        failure_message do |actual|
+          if actual.respond_to?(:size)
+            "expected #{actual.inspect} size to #{expected.description}, but got #{actual.size}"
+          else
+            "expected #{actual.inspect} to respond to :size"
+          end
+        end
+      end
+    end
+  end
+end
+
+# Define the custom matchers
+SpecForge::Matchers.define

data/lib/spec_forge/normalizer/default.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Normalizer
+    #
+    # Provides default value generation for Normalizer structures
+    #
+    # Contains helper methods for creating default values based on type
+    # definitions and structure specifications.
+    #
+    module Default
+      private
+
+      def default_from_structure(structure, include_optional: false)
+        structure.each_with_object({}) do |(attribute_name, attribute), hash|
+          type = attribute[:type]
+          has_default = attribute.key?(:default)
+          required = attribute[:required] != false
+
+          next if !(include_optional || required || has_default)
+
+          hash[attribute_name] =
+            if has_default
+              default = attribute[:default]
+              next if default.nil?
+
+              default.dup
+            elsif type.instance_of?(Array)
+              default_value_for_type(type.first)
+            else
+              default_value_for_type(type)
+            end
+        end
+      end
+
+      def default_value_for_type(type_class)
+        if type_class == Integer
+          0
+        elsif type_class == Proc
+          -> {}
+        elsif type_class == TrueClass
+          true
+        elsif type_class == FalseClass
+          false
+        else
+          type_class.new
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/normalizer/definition.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Normalizer
+    #
+    # Manages structure definitions for the Normalizer
+    #
+    # Handles loading structure definitions from YAML files, processing references
+    # between structures, and normalizing structure formats for consistent validation.
+    #
+    # @example Loading all structure definitions
+    #   structures = SpecForge::Normalizer::Definition.from_files
+    #
+    class Definition
+      #
+      # Mapping of structure names to their human-readable labels
+      #
+      # @return [Hash<Symbol, String>]
+      #
+      LABELS = {
+        factory_reference: "factory reference",
+        global_context: "global context"
+      }.freeze
+
+      #
+      # Core structure definition used to validate other structures
+      #
+      # Defines the valid attributes and types for structure definitions,
+      # creating a meta-structure that validates other structure definitions.
+      #
+      # @return [Hash]
+      #
+      STRUCTURE = {
+        type: {
+          type: [String, Array, Class],
+          default: nil,
+          validator: :present?
+        },
+        default: {
+          type: [String, NilClass, Numeric, Array, Hash, TrueClass, FalseClass],
+          required: false
+        },
+        required: {
+          type: [TrueClass, FalseClass],
+          required: false
+        },
+        aliases: {
+          type: Array,
+          required: false,
+          structure: {type: String}
+        },
+        structure: {
+          type: Hash,
+          required: false
+        },
+        validator: {
+          type: String,
+          required: false
+        }
+      }.freeze
+
+      #
+      # Loads normalizer definitions from YAML files
+      #
+      # Reads all YAML files in the normalizers directory, processes shared
+      # references, and prepares them for use by the Normalizer.
+      #
+      # @return [Hash] A hash mapping structure names to their definitions
+      #
+      def self.from_files
+        base_path = Pathname.new(File.expand_path("../normalizers", __dir__))
+        paths = Dir[base_path.join("**/*.yml")].sort
+
+        normalizers =
+          paths.each_with_object({}) do |path, hash|
+            path = Pathname.new(path)
+
+            # Include the directory name in the path to include normalizers in directories
+            name = path.relative_path_from(base_path).to_s.delete_suffix(".yml").to_sym
+
+            input = YAML.safe_load_file(path, symbolize_names: true)
+            raise Error, "Normalizer defined at #{path.to_s.in_quotes} is empty" if input.blank?
+
+            hash[name] = new(input, label: LABELS[name] || name.to_s.humanize.downcase)
+          end
+
+        # Pull the shared structures and prepare it
+        structures = normalizers.delete(:_shared).normalize
+
+        # Merge in the normalizers to allow referencing other normalizers
+        structures.merge!(normalizers.transform_values(&:input))
+
+        # Now prepare all of the other definitions with access to references
+        normalizers.transform_values!(with_key: true) do |definition, name|
+          structure = definition.normalize(structures)
+
+          {
+            label: definition.label,
+            structure:
+          }
+        end
+
+        normalizers
+      end
+
+      ##########################################################################
+
+      attr_reader :input, :label
+
+      def initialize(input, label: "")
+        @input = input
+        @label = label
+      end
+
+      #
+      # Normalizes a structure definition
+      #
+      # Processes references, resolves types, and ensures all attributes
+      # have a consistent format for validation.
+      #
+      # @param shared_structures [Hash] Optional shared structures for resolving references
+      #
+      # @return [Hash] The normalized structure definition
+      #
+      def normalize(shared_structures = {})
+        hash = @input.deep_dup
+
+        # First, we'll deeply replace any references
+        replace_references(hash, shared_structures)
+
+        # Second, normalize the root level keys
+        hash.transform_values!(with_key: true) do |attribute, name|
+          next if STRUCTURE.key?(name)
+
+          normalize_attribute(name, attribute)
+        end
+
+        # Third, normalize the underlying structures
+        hash.each do |name, attribute|
+          next unless attribute.is_a?(Hash)
+
+          structure = attribute[:structure]
+          next if structure.blank?
+
+          attribute[:structure] = normalize_structure(name, attribute)
+        end
+
+        hash
+      end
+
+      private
+
+      def replace_references(attributes, shared_structures)
+        return if shared_structures.blank?
+
+        # The goal is to walk down the hash and recursively replace any references
+        attributes.each do |attribute_name, attribute|
+          # Replace the top level reference
+          replace_with_reference(attribute_name, attribute, shared_structures:)
+          next unless attribute.is_a?(Hash) && attribute[:structure].present?
+
+          # Allow structures to reference other structures
+          if attribute.dig(:structure, :reference)
+            replace_with_reference(
+              "#{attribute_name}'s structure",
+              attribute[:structure],
+              shared_structures:
+            )
+          end
+
+          # Recursively replace any structures that have references
+          if [Array, "array"].include?(attribute[:type])
+            result = replace_references(attribute.slice(:structure), shared_structures)
+            attribute.merge!(result)
+          elsif [Hash, "hash"].include?(attribute[:type])
+            replace_references(attribute[:structure], shared_structures)
+          end
+        end
+      end
+
+      def replace_with_reference(attribute_name, attribute, shared_structures: {})
+        return unless attribute.is_a?(Hash) && attribute.key?(:reference)
+
+        reference_name = attribute.delete(:reference)
+        reference = shared_structures[reference_name.to_sym]
+
+        if reference.nil?
+          structures_names = shared_structures.keys.map(&:in_quotes).to_or_sentence
+
+          raise Error, "Attribute #{attribute_name.in_quotes}: Invalid reference name. Got #{reference_name&.in_quotes}, expected one of #{structures_names} in #{@label}"
+        end
+
+        # Allows overwriting data on the reference
+        attribute.reverse_merge!(reference)
+      end
+
+      def normalize_attribute(attribute_name, attribute)
+        case attribute
+        when String, Array # Array is multiple types
+          hash = {type: resolve_type(attribute)}
+
+          default = Normalizer.default(structure: STRUCTURE)
+          hash.merge!(default)
+        when Hash
+          hash = Normalizer.raise_errors! do
+            Normalizer.new(
+              "#{attribute_name.in_quotes} in #{@label}",
+              attribute,
+              structure: STRUCTURE
+            ).normalize
+          end
+
+          hash[:type] = resolve_type(attribute[:type])
+
+          if hash[:structure].present?
+            hash[:structure] = normalize_structure(attribute_name, hash) || {}
+          end
+
+          hash
+        else
+          raise ArgumentError, "Attribute #{attribute_name.in_quotes}: Expected String or Hash, got #{attribute.inspect}"
+        end
+      end
+
+      def normalize_structure(name, hash)
+        if hash[:type] == Array
+          normalize_attribute(name, hash[:structure])
+        elsif hash[:type] == Hash
+          hash[:structure].transform_values(with_key: true) { |v, k| normalize_attribute(k, v) }
+        end
+      end
+
+      def resolve_type(type)
+        if type == "boolean"
+          [TrueClass, FalseClass]
+        elsif type.instance_of?(Array)
+          type.map { |t| resolve_type(t) }
+        elsif type.is_a?(String)
+          type.classify.constantize
+        else
+          type
+        end
+      rescue NameError => e
+        raise Error, "#{e}. #{type.inspect} is not a valid type found in #{@label}"
+      end
+    end
+  end
+end

data/lib/spec_forge/normalizer/validators.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Normalizer
+    #
+    # Provides validation methods for Normalizer structures
+    #
+    # Contains validation functions that can be referenced by name
+    # in structure definitions to perform custom validation logic.
+    #
+    # @example Validator in a structure definition
+    #   http_verb: {type: String, validator: :http_verb}
+    #
+    class Validators
+      #
+      # Calls a validator method with the provided value and context
+      #
+      # @param method_name [Symbol, String] The validator method to call
+      # @param value [Object] The value to validate
+      # @param label [String] A descriptive label for error messages
+      #
+      # @return [void]
+      #
+      # @raise [Error] If validation fails
+      #
+      def self.call(method_name, value, label:)
+        new(label).public_send(method_name, value)
+      end
+
+      #
+      # Initializes a new validator instance with a context label
+      #
+      # @param label [String] A descriptive label for error messages
+      #
+      # @return [Validators] A new validator instance
+      #
+      def initialize(label)
+        @label = label
+      end
+
+      #
+      # Validates that a value is not blank
+      #
+      # Ensures the provided value is not nil, empty, or contains only whitespace.
+      # This validator is useful for required fields that must have meaningful content.
+      #
+      # @param value [Object] The value to validate
+      #
+      # @raise [Error] If the value is blank
+      #
+      # @example Using the validator in a structure
+      #   name: {type: String, validator: :present?}
+      #
+      def present?(value)
+        raise Error, "Value cannot be blank for #{@label}" if value.blank?
+      end
+
+      #
+      # Validates that a value is a supported HTTP verb
+      #
+      # Ensures the provided value is one of the supported HTTP methods
+      # (GET, POST, PUT, PATCH, DELETE). Case-insensitive matching is used.
+      #
+      # @param value [String, Symbol, nil] The HTTP verb to validate, or nil
+      #
+      # @raise [Error] If the value is not a supported HTTP verb
+      #
+      # @example Using the validator in a structure
+      #   http_verb: {type: String, validator: :http_verb}
+      #
+      def http_verb(value)
+        valid_verbs = HTTP::Verb::VERBS.values.map(&:to_s)
+        return if value.blank? || valid_verbs.include?(value.to_s.upcase)
+
+        raise Error, "Invalid HTTP verb #{value.in_quotes} for #{@label}. Valid values are: #{valid_verbs.join_map(", ", &:in_quotes)}"
+      end
+
+      #
+      # Validates that a callback is registered in the system
+      #
+      # Ensures the referenced callback name has been registered with SpecForge
+      # before it's used in a test configuration.
+      #
+      # @param value [String, Symbol, nil] The callback name to validate, or nil
+      #
+      # @raise [Error::UndefinedCallbackError] If the callback is not registered
+      #
+      # @example Using the validator in a structure
+      #   before_file: {type: String, validator: :callback}
+      #
+      def callback(value)
+        return if value.blank?
+        return if SpecForge::Callbacks.registered?(value)
+
+        raise Error::UndefinedCallbackError.new(value, SpecForge::Callbacks.registered_names)
+      end
+    end
+  end
+end