spec_forge 0.6.0 → 0.7.0

data/lib/spec_forge/http/request.rb

@@ -7,7 +7,15 @@ module SpecForge
     #
     # @return [Array<Symbol>]
     #
-    REQUEST_ATTRIBUTES = [:base_url, :url, :http_verb, :headers, :query, :body].freeze
+    REQUEST_ATTRIBUTES = %i[
+      base_url
+      url
+      http_verb
+      content_type
+      headers
+      query
+      body
+    ].freeze
 
     #
     # Represents an HTTP request configuration
@@ -52,8 +60,9 @@ module SpecForge
         query = Attribute.from(options[:query] || {})
         body = Attribute.from(options[:body] || {})
         headers = normalize_headers(options[:headers] || {})
+        content_type = "application/json"
 
-        super(base_url:, url:, http_verb:, headers:, query:, body:)
+        super(base_url:, url:, http_verb:, content_type:, headers:, query:, body:)
       end
 
       #
@@ -62,7 +71,9 @@ module SpecForge
       # @return [Hash] The request data with all dynamic values resolved
       #
       def to_h
-        super.transform_values { |v| v.respond_to?(:resolved) ? v.resolved : v }
+        hash = super.transform_values { |v| v.respond_to?(:resolved) ? v.resolved : v }
+        hash[:http_verb] = hash[:http_verb].to_s
+        hash
       end
 
       private

data/lib/spec_forge/loader.rb

@@ -23,14 +23,14 @@ module SpecForge
         load_specs_from_files.map do |global, metadata, specs|
           global =
             begin
-              Normalizer.normalize_global_context!(global)
+              Normalizer.normalize!(global, using: :global_context)
             rescue => e
               raise Error::SpecLoadError.new(e, metadata[:relative_path])
             end
 
           specs =
             specs.map do |spec|
-              Normalizer.normalize_spec!(spec, label: "spec \"#{spec[:name]}\"")
+              Normalizer.normalize!(spec, using: :spec, label: "spec \"#{spec[:name]}\"")
             rescue => e
               raise Error::SpecLoadError.new(e, metadata[:relative_path], spec:)
             end
@@ -86,7 +86,7 @@ module SpecForge
         files.map do |file_path, content|
           relative_path = Pathname.new(file_path).relative_path_from(base_path)
 
-          hash = YAML.load(content).deep_symbolize_keys
+          hash = YAML.safe_load(content, symbolize_names: true)
 
           file_line_numbers = extract_line_numbers(content, hash)
 
@@ -103,7 +103,7 @@ module SpecForge
             hash.map do |spec_name, spec_hash|
               line_number, *expectation_line_numbers = file_line_numbers[spec_name]
 
-              spec_hash[:id] = "spec_#{generate_id(spec_hash)}"
+              spec_hash[:id] = "spec_#{SpecForge.generate_id(spec_hash)}"
               spec_hash[:name] = spec_name.to_s
               spec_hash[:file_path] = metadata[:file_path]
               spec_hash[:file_name] = metadata[:file_name]
@@ -112,7 +112,7 @@ module SpecForge
               # Check for expectations instead of defaulting. I want it to error
               if (expectations = spec_hash[:expectations])
                 expectations.zip(expectation_line_numbers) do |expectation_hash, line_number|
-                  expectation_hash[:id] = "expect_#{generate_id(expectation_hash)}"
+                  expectation_hash[:id] = "expect_#{SpecForge.generate_id(expectation_hash)}"
                   expectation_hash[:name] = build_expectation_name(spec_hash, expectation_hash)
                   expectation_hash[:line_number] = line_number
                 end
@@ -191,19 +191,6 @@ module SpecForge
         keys
       end
 
-      #
-      # Generates a unique ID for an object based on hash and object_id
-      #
-      # @param object [Object] The object to generate an ID for
-      #
-      # @return [String] A unique ID string
-      #
-      # @private
-      #
-      def generate_id(object)
-        "#{object.hash.abs.to_s(36)}_#{object.object_id.to_s(36)}"
-      end
-
       #
       # Builds a name for an expectation based on HTTP verb, URL, and optional name
       #
@@ -215,14 +202,17 @@ module SpecForge
       # @private
       #
       def build_expectation_name(spec_hash, expectation_hash)
-        # Create a structure for these two attributes
-        # Removing the defaults and validators to avoid issues
-        structure = Normalizer::SHARED_ATTRIBUTES.slice(:http_verb, :url)
+        # Create a structure for http_verb and url
+        # Removing the defaults and validators to avoid triggering extra logic
+        structure = Normalizer.structures[:spec][:structure].slice(:http_verb, :url)
           .transform_values { |v| v.except(:default, :validator) }
 
-        # Ignore any errors. It'll be caught above anyway
-        normalized_spec, _errors = Normalizer.new("", spec_hash, structure:).normalize
-        normalized_expectation, _errors = Normalizer.new("", expectation_hash, structure:).normalize
+        # Ignore any errors. These will be validated later
+        normalized_spec, _ = Normalizer.normalize(spec_hash, using: structure, label: "n/a")
+        normalized_expectation, _ = Normalizer.normalize(
+          expectation_hash,
+          using: structure, label: "n/a"
+        )
 
         request_data = normalized_spec.deep_merge(normalized_expectation)
 

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