spec_forge 0.5.0 → 0.6.0

data/lib/spec_forge/normalizer/constraint.rb

@@ -2,10 +2,26 @@
 
 module SpecForge
   class Normalizer
+    #
+    # Normalizes constraint hash structure for expectations
+    #
+    # Ensures that expectation constraints (status, json, etc.)
+    # have the correct structure and defaults.
+    #
     class Constraint < Normalizer
+      #
+      # Defines the normalized structure for configuration validation
+      #
+      # Specifies validation rules for configuration attributes:
+      # - Enforces specific data types
+      # - Provides default values
+      # - Supports alternative key names
+      #
+      # @return [Hash] Configuration attribute validation rules
+      #
       STRUCTURE = {
         status: {
-          type: Integer
+          type: [Integer, String]
         },
         json: {
           type: [Hash, Array],
@@ -19,7 +35,7 @@ module SpecForge
       #
       # Generates an empty constraint hash
       #
-      # @return [Hash]
+      # @return [Hash] Default constraint hash
       #
       def default_constraint
         Constraint.default
@@ -27,18 +43,15 @@ module SpecForge
 
       #
       # Normalize a constraint hash
-      # Used internally by .normalize_spec, but is available for utility
       #
-      # @param constraint [Hash] Constraint representation as a Hash
+      # @param constraint [Hash] Constraint hash
       #
-      # @return [Array] Two item array
-      #   First - The normalized hash
-      #   Second - Array of errors, if any
+      # @return [Array] [normalized_hash, errors]
       #
       # @private
       #
       def normalize_constraint(constraint)
-        raise InvalidTypeError.new(constraint, Hash, for: "expect") unless Type.hash?(constraint)
+        raise Error::InvalidTypeError.new(constraint, Hash, for: "expect") unless Type.hash?(constraint)
 
         Normalizer::Constraint.new("expect", constraint).normalize
       end

data/lib/spec_forge/normalizer/expectation.rb

@@ -2,17 +2,39 @@
 
 module SpecForge
   class Normalizer
+    #
+    # Normalizes expectation hash structure
+    #
+    # Ensures that expectation definitions have the correct structure
+    # and default values for all required settings.
+    #
     class Expectation < Normalizer
+      #
+      # Defines the normalized structure for configuration validation
+      #
+      # Specifies validation rules for configuration attributes:
+      # - Enforces specific data types
+      # - Provides default values
+      # - Supports alternative key names
+      #
+      # @return [Hash] Configuration attribute validation rules
+      #
       STRUCTURE = {
-        name: {type: String, default: ""},
+        # Internal
+        id: Normalizer::SHARED_ATTRIBUTES[:id],
+        line_number: Normalizer::SHARED_ATTRIBUTES[:line_number],
+
+        # User defined
+        name: Normalizer::SHARED_ATTRIBUTES[:name],
         base_url: Normalizer::SHARED_ATTRIBUTES[:base_url],
         url: Normalizer::SHARED_ATTRIBUTES[:url],
-        http_method: Normalizer::SHARED_ATTRIBUTES[:http_method],
+        http_verb: Normalizer::SHARED_ATTRIBUTES[:http_verb],
         headers: Normalizer::SHARED_ATTRIBUTES[:headers],
         query: Normalizer::SHARED_ATTRIBUTES[:query],
         body: Normalizer::SHARED_ATTRIBUTES[:body],
         variables: Normalizer::SHARED_ATTRIBUTES[:variables],
         debug: Normalizer::SHARED_ATTRIBUTES[:debug],
+        store_as: {type: String, default: ""},
         expect: {type: Hash}
       }.freeze
     end
@@ -22,7 +44,7 @@ module SpecForge
       #
       # Generates an empty expectation hash
       #
-      # @return [Hash]
+      # @return [Hash] Default expectation hash
       #
       def default_expectation
         Expectation.default
@@ -31,11 +53,11 @@ module SpecForge
       #
       # Normalize an array of expectation hashes
       #
-      # @raises InvalidStructureError if anything is missing/invalid type
+      # @param input [Array<Hash>] The array to normalize
       #
-      # @param input [Hash] The hash to normalize
+      # @return [Array<Hash>] Normalized array of expectation hashes
       #
-      # @return [Hash] A normalized hash as a new instance
+      # @raise [Error::InvalidStructureError] If validation fails
       #
       def normalize_expectations!(input)
         raise_errors! do
@@ -45,19 +67,16 @@ module SpecForge
 
       #
       # Normalize an array of expectation hashes
-      # Used internally by .normalize_spec, but is available for utility
       #
-      # @param expectations [Array<Hash>] An array of expectation hashes
+      # @param expectations [Array<Hash>] Array of expectation hashes
       #
-      # @return [Array] Two item array
-      #   First - The normalized Array<Hash>
-      #   Second - Array of errors, if any
+      # @return [Array] [normalized_array, errors]
       #
       # @private
       #
       def normalize_expectations(expectations)
         if !Type.array?(expectations)
-          raise InvalidTypeError.new(expectations, Array, for: "\"expectations\" on spec")
+          raise Error::InvalidTypeError.new(expectations, Array, for: "\"expectations\" on spec")
         end
 
         final_errors = Set.new

data/lib/spec_forge/normalizer/factory.rb

@@ -2,7 +2,23 @@
 
 module SpecForge
   class Normalizer
+    #
+    # Normalizes factory hash structure
+    #
+    # Ensures that factory definitions have the correct structure
+    # and default values for all required settings.
+    #
     class Factory < Normalizer
+      #
+      # Defines the normalized structure for configuration validation
+      #
+      # Specifies validation rules for configuration attributes:
+      # - Enforces specific data types
+      # - Provides default values
+      # - Supports alternative key names
+      #
+      # @return [Hash] Configuration attribute validation rules
+      #
       STRUCTURE = {
         model_class: {
           type: String,
@@ -22,20 +38,20 @@ module SpecForge
       #
       # Generates an empty factory hash
       #
-      # @return [Hash]
+      # @return [Hash] Default factory hash
       #
       def default_factory
         Factory.default
       end
 
       #
-      # Normalizes a factory hash by standardizing its keys while ensuring the required data
-      # is provided or defaulted.
-      # Raises InvalidStructureError if anything is missing/invalid type
+      # Normalizes a factory hash with validation
       #
       # @param input [Hash] The hash to normalize
       #
-      # @return [Hash] A normalized hash as a new instance
+      # @return [Hash] A normalized hash with defaults applied
+      #
+      # @raise [Error::InvalidStructureError] If validation fails
       #
       def normalize_factory!(input)
         raise_errors! do
@@ -45,18 +61,15 @@ module SpecForge
 
       #
       # Normalize a factory hash
-      # Used internally by .normalize_factory, but is available for utility
       #
-      # @param factory [Hash] Factory representation as a Hash
+      # @param factory [Hash] Factory hash
       #
-      # @return [Array] Two item array
-      #   First - The normalized hash
-      #   Second - Array of errors, if any
+      # @return [Array] [normalized_hash, errors]
       #
       # @private
       #
       def normalize_factory(factory)
-        raise InvalidTypeError.new(factory, Hash, for: "factory") unless Type.hash?(factory)
+        raise Error::InvalidTypeError.new(factory, Hash, for: "factory") unless Type.hash?(factory)
 
         Normalizer::Factory.new("factory", factory).normalize
       end

data/lib/spec_forge/normalizer/factory_reference.rb

@@ -2,7 +2,23 @@
 
 module SpecForge
   class Normalizer
+    #
+    # Normalizes factory reference hash structure
+    #
+    # Ensures that factory references have the correct structure
+    # and default values for all required settings.
+    #
     class FactoryReference < Normalizer
+      #
+      # Defines the normalized structure for configuration validation
+      #
+      # Specifies validation rules for configuration attributes:
+      # - Enforces specific data types
+      # - Provides default values
+      # - Supports alternative key names
+      #
+      # @return [Hash] Configuration attribute validation rules
+      #
       STRUCTURE = {
         attributes: {
           type: Hash,
@@ -24,22 +40,22 @@ module SpecForge
     # On Normalizer
     class << self
       #
-      # Generates an empty Attribute::Factory hash
+      # Generates an empty factory reference hash
       #
-      # @return [Hash]
+      # @return [Hash] Default factory reference hash
       #
       def default_factory_reference
         FactoryReference.default
       end
 
       #
-      # Normalizes a Attribute::Factory hash by standardizing
-      # its keys while ensuring the required data is provided or defaulted.
-      # Raises InvalidStructureError if anything is missing/invalid type
+      # Normalizes a factory reference hash with validation
       #
       # @param input [Hash] The hash to normalize
       #
-      # @return [Hash] A normalized hash as a new instance
+      # @return [Hash] A normalized hash with defaults applied
+      #
+      # @raise [Error::InvalidStructureError] If validation fails
       #
       def normalize_factory_reference!(input, **)
         raise_errors! do
@@ -48,20 +64,18 @@ module SpecForge
       end
 
       #
-      # Normalize a factory hash
-      # Used internally by .normalize_factory_reference, but is available for utility
+      # Normalize a factory reference hash
       #
-      # @param factory [Hash] Attribute::Factory representation as a Hash
+      # @param factory [Hash] Factory reference hash
+      # @param label [String] Label for error messages
       #
-      # @return [Array] Two item array
-      #   First - The normalized hash
-      #   Second - Array of errors, if any
+      # @return [Array] [normalized_hash, errors]
       #
       # @private
       #
       def normalize_factory_reference(factory, label: "factory reference")
         if !Type.hash?(factory)
-          raise InvalidTypeError.new(factory, Hash, for: "factory reference")
+          raise Error::InvalidTypeError.new(factory, Hash, for: "factory reference")
         end
 
         Normalizer::FactoryReference.new(label, factory).normalize

data/lib/spec_forge/normalizer/global_context.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Normalizer
+    #
+    # Normalizes global context hash structure
+    #
+    # Ensures that global context definitions have the correct structure
+    # and default values for all required settings.
+    #
+    class GlobalContext < Normalizer
+      #
+      # Defines the normalized structure for configuration validation
+      #
+      # Specifies validation rules for configuration attributes:
+      # - Enforces specific data types
+      # - Provides default values
+      # - Supports alternative key names
+      #
+      # @return [Hash] Configuration attribute validation rules
+      #
+      STRUCTURE = {
+        variables: Normalizer::SHARED_ATTRIBUTES[:variables],
+        callbacks: {
+          type: Array,
+          default: [],
+          structure: {
+            type: Hash,
+            default: {},
+            structure: {
+              before_file: Normalizer::SHARED_ATTRIBUTES[:callback],
+              before_spec: Normalizer::SHARED_ATTRIBUTES[:callback],
+              before_each: Normalizer::SHARED_ATTRIBUTES[:callback].merge(aliases: %i[before]),
+              around_each: Normalizer::SHARED_ATTRIBUTES[:callback].merge(aliases: %i[around]),
+              after_each: Normalizer::SHARED_ATTRIBUTES[:callback].merge(aliases: %i[after]),
+              after_spec: Normalizer::SHARED_ATTRIBUTES[:callback],
+              after_file: Normalizer::SHARED_ATTRIBUTES[:callback]
+            }
+          }
+        }
+      }.freeze
+    end
+
+    # On Normalizer
+    class << self
+      #
+      # Generates an empty global context hash
+      #
+      # @return [Hash] Default global context hash
+      #
+      def default_global_context
+        GlobalContext.default
+      end
+
+      #
+      # Normalizes a global context hash with validation
+      #
+      # @param input [Hash] The hash to normalize
+      #
+      # @return [Hash] A normalized hash with defaults applied
+      #
+      # @raise [Error::InvalidStructureError] If validation fails
+      #
+      def normalize_global_context!(input)
+        raise_errors! do
+          normalize_global_context(input)
+        end
+      end
+
+      #
+      # Normalize a global context hash
+      #
+      # @param global [Hash] Global context hash
+      #
+      # @return [Array] [normalized_hash, errors]
+      #
+      # @private
+      #
+      def normalize_global_context(global)
+        if !Type.hash?(global)
+          raise Error::InvalidTypeError.new(global, Hash, for: "global context")
+        end
+
+        Normalizer::GlobalContext.new("global context", global).normalize
+      end
+    end
+  end
+end

data/lib/spec_forge/normalizer/spec.rb

@@ -2,11 +2,35 @@
 
 module SpecForge
   class Normalizer
+    #
+    # Normalizes spec hash structure
+    #
+    # Ensures that spec definitions have the correct structure
+    # and default values for all required settings.
+    #
     class Spec < Normalizer
+      #
+      # Defines the normalized structure for configuration validation
+      #
+      # Specifies validation rules for configuration attributes:
+      # - Enforces specific data types
+      # - Provides default values
+      # - Supports alternative key names
+      #
+      # @return [Hash] Configuration attribute validation rules
+      #
       STRUCTURE = {
+        # Internal
+        id: Normalizer::SHARED_ATTRIBUTES[:id],
+        name: Normalizer::SHARED_ATTRIBUTES[:name],
+        file_name: {type: String},
+        file_path: {type: String},
+        line_number: Normalizer::SHARED_ATTRIBUTES[:line_number],
+
+        # User defined
         base_url: Normalizer::SHARED_ATTRIBUTES[:base_url],
         url: Normalizer::SHARED_ATTRIBUTES[:url],
-        http_method: Normalizer::SHARED_ATTRIBUTES[:http_method],
+        http_verb: Normalizer::SHARED_ATTRIBUTES[:http_verb],
         headers: Normalizer::SHARED_ATTRIBUTES[:headers],
         query: Normalizer::SHARED_ATTRIBUTES[:query],
         body: Normalizer::SHARED_ATTRIBUTES[:body],
@@ -21,24 +45,25 @@ module SpecForge
       #
       # Generates an empty spec hash
       #
-      # @return [Hash]
+      # @return [Hash] Default spec hash
       #
       def default_spec
         Spec.default
       end
 
       #
-      # Normalizes a complete spec hash by standardizing its keys while ensuring the required data
-      # is provided or defaulted.
-      # Raises InvalidStructureError if anything is missing/invalid type
+      # Normalizes a spec hash with validation and processes expectations
       #
       # @param input [Hash] The hash to normalize
+      # @param label [String] Label for error messages
+      #
+      # @return [Hash] A normalized hash with defaults applied
       #
-      # @return [Hash] A normalized hash as a new instance
+      # @raise [Error::InvalidStructureError] If validation fails
       #
-      def normalize_spec!(input)
+      def normalize_spec!(input, label: "spec")
         raise_errors! do
-          output, errors = normalize_spec(input)
+          output, errors = normalize_spec(input, label:)
 
           # Process expectations
           if (expectations = input[:expectations]) && Type.array?(expectations)
@@ -54,20 +79,18 @@ module SpecForge
 
       #
       # Normalize a spec hash
-      # Used internally by .normalize_spec, but is available for utility
       #
-      # @param spec [Hash] Spec representation as a Hash
+      # @param spec [Hash] Spec hash
+      # @param label [String] Label for error messages
       #
-      # @return [Array] Two item array
-      #   First - The normalized hash
-      #   Second - Array of errors, if any
+      # @return [Array] [normalized_hash, errors]
       #
       # @private
       #
-      def normalize_spec(spec)
-        raise InvalidTypeError.new(spec, Hash, for: "spec") unless Type.hash?(spec)
+      def normalize_spec(spec, label: "spec")
+        raise Error::InvalidTypeError.new(spec, Hash, for: label) unless Type.hash?(spec)
 
-        Normalizer::Spec.new("spec", spec).normalize
+        Normalizer::Spec.new(label, spec).normalize
       end
     end
   end