spec_forge 0.4.0 → 0.6.0

data/lib/spec_forge/attribute/global.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Attribute
+    #
+    # Represents an attribute that references values from the global context
+    #
+    # This class allows accessing shared data defined at the global level through
+    # namespaced references. It provides access to global variables that are shared
+    # across all specs in a file, enabling consistent test data without repetition.
+    #
+    # Currently supports the "variables" namespace.
+    #
+    # @example Basic usage in YAML
+    #   # Reference a global variable in a spec
+    #   session_token: global.variables.session_token
+    #
+    #   # Using within a request body
+    #   body:
+    #     api_version: global.variables.api_version
+    #     auth_token: global.variables.auth_token
+    #
+    class Global < Attribute
+      #
+      # Regular expression pattern that matches attribute keywords with this prefix
+      # Used for identifying this attribute type during parsing
+      #
+      # @return [Regexp]
+      #
+      KEYWORD_REGEX = /^global\./i
+
+      #
+      # An array of valid namespaces that can be access on global
+      #
+      # @return [Array<String>]
+      #
+      VALID_NAMESPACES = %w[
+        variables
+      ].freeze
+
+      #
+      # Creates a new global attribute from the input string
+      #
+      # Parses the input string to extract the namespace to validate it
+      # Conversion happens when `#value` is called
+      #
+      # @raise [Error::InvalidGlobalNamespaceError] If an unsupported namespace is referenced
+      #
+      def initialize(...)
+        super
+
+        # Check to make sure the namespace is valid
+        namespace = input.split(".").second
+
+        if !VALID_NAMESPACES.include?(namespace)
+          raise Error::InvalidGlobalNamespaceError, namespace
+        end
+      end
+
+      #
+      # Converts the global reference into an underlying attribute
+      #
+      # Parses the input and returns the corresponding attribute based on the namespace.
+      # Currently supports extracting variables from the global context.
+      #
+      # @return [Attribute] An attribute representing the referenced global value
+      #
+      def value
+        # Skip the "global" prefix
+        components = input.split(".")[1..]
+        namespace = components.first
+
+        global_context = SpecForge.context.global
+
+        case namespace
+        when "variables"
+          variable_input = components.join(".")
+          variable = Attribute::Variable.new(variable_input)
+          variable.bind_variables(global_context.variables.to_h)
+          variable
+        end
+      end
+
+      #
+      # Resolves the global reference to its actual value
+      #
+      # Delegates resolution to the underlying attribute and caches the result
+      #
+      # @return [Object] The fully resolved value from the global context
+      #
+      def resolved
+        @resolved ||= value.resolved
+      end
+    end
+  end
+end

data/lib/spec_forge/attribute/literal.rb

@@ -2,12 +2,25 @@
 
 module SpecForge
   class Attribute
+    #
+    # Represents an attribute that is a literal value
+    #
+    # This is the simplest form of attribute, storing values like strings, numbers,
+    # and booleans without any processing.
+    #
+    # @example Basic usage in YAML
+    #   name: "John Doe"
+    #   age: 42
+    #   active: true
+    #
     class Literal < Attribute
+      # @return [Object] The literal value
       attr_reader :value
 
       #
-      # Represents any attribute that is a literal value.
-      # A literal value can be any value YAML value, except Array and Hash
+      # Creates a new literal attribute with the specified value
+      #
+      # @param input [Object] The value to store
       #
       def initialize(input)
         super

data/lib/spec_forge/attribute/matcher.rb

@@ -2,28 +2,65 @@
 
 module SpecForge
   class Attribute
+    #
+    # Represents an attribute that uses RSpec matchers for response validation
+    #
+    # This class allows SpecForge to integrate with RSpec's powerful matchers
+    # for flexible response validation. It supports most of the built-in RSpec matchers
+    # and most custom matchers, assuming they do not require more Ruby code
+    #
+    # @example Basic matchers in YAML
+    #   be_true: be.true
+    #   include_admin:
+    #     matcher.include:
+    #     - admin
+    #
+    # @example Comparison matchers
+    #   count:
+    #     be.greater_than: 5
+    #
+    # @example Type checking
+    #   name: kind_of.string
+    #   id: kind_of.integer
+    #
     class Matcher < Parameterized
-      class Methods
+      #
+      # Helper class to access RSpec matcher methods
+      #
+      class RSpecMatchers
         include RSpec::Matchers
       end
 
-      MATCHER_METHODS = Methods.new.freeze
-      KEYWORD_REGEX = /^matcher\.|^be\.|^kind_of\./i
+      #
+      # Regular expression pattern that matches attribute keywords with this prefix
+      # Used for identifying this attribute type during parsing
+      #
+      # @return [Regexp]
+      #
+      KEYWORD_REGEX = /^matchers?\.|^be\.|^kind_of\./i
+
+      #
+      # Instance of Methods providing access to all RSpec matchers
+      #
+      MATCHER_METHODS = RSpecMatchers.new.freeze
 
+      #
+      # Mapping of literal string values to their Ruby equivalents
+      # Used for be.nil, be.true, and be.false matchers
+      #
       LITERAL_MAPPINGS = {
         "nil" => nil,
         "true" => true,
         "false" => false
       }.freeze
 
+      #
+      # The resolved RSpec matcher method to call
+      #
       attr_reader :matcher_method
 
       #
-      # Represents any attribute that is a matcher call.
-      #
-      #   matcher.<method>
-      #   be.<method>
-      #   kind_of.<method>
+      # Creates a new matcher attribute with the specified matcher and arguments
       #
       def initialize(...)
         super
@@ -37,28 +74,87 @@ module SpecForge
           when "kind_of"
             resolve_kind_of_matcher(method)
           else
-            resolve_matcher(method)
+            resolve_base_matcher(method)
           end
 
         prepare_arguments!
+
+        # An argument can be an expanded version of something (such as matcher.include)
+        # Move it to where it belongs
+        if (keyword = arguments[:keyword]) && !Type.hash?(keyword)
+          arguments[:positional] << keyword
+          arguments[:keyword] = {}
+        end
       end
 
+      #
+      # Returns the result of applying the matcher with the given arguments
+      # Creates an RSpec matcher that can be used in expectations
+      #
+      # @return [RSpec::Matchers::BuiltIn::BaseMatcher] The configured matcher
+      #
       def value
-        if uses_positional_arguments?(matcher_method)
-          positional = arguments[:positional].resolve.each do |value|
+        if (positional = arguments[:positional]) && positional.present?
+          positional = positional.resolved.each do |value|
             value.deep_stringify_keys! if value.respond_to?(:deep_stringify_keys!)
           end
 
           matcher_method.call(*positional)
-        elsif uses_keyword_arguments?(matcher_method)
-          matcher_method.call(**arguments[:keyword].resolve.deep_stringify_keys)
+        elsif (keyword = arguments[:keyword]) && keyword.present?
+          matcher_method.call(**keyword.resolved.deep_stringify_keys)
         else
           matcher_method.call
         end
       end
 
+      #
+      # Ensures proper conversion of nested matcher arguments based on context
+      #
+      # This method overrides handles a special case of matchers that take arguments
+      # which themselves might need to be converted to matchers. It skips conversion
+      # for string arguments that should remain strings
+      # (like with include, start_with, and end_with) while correctly handling nested
+      # matchers and other argument types.
+      #
+      # @example Problem case handled
+      #   # In YAML:
+      #   matcher.all:
+      #     matcher.include:
+      #     - /@/  # Should become match(/@/) when used with include
+      #
+      # @example Edge case handled
+      #   # In YAML:
+      #   matcher.include: "." # Should remain a string, not eq(".")
+      #
+      # @return [RSpec::Matchers::BuiltIn::BaseMatcher] The properly configured matcher
+      #   with all arguments correctly converted based on context
+      #
+      def resolve_as_matcher
+        # Argument conversion only matters for the base matchers
+        if input.start_with?("matcher")
+          block = lambda do |argument|
+            next argument unless convert_argument?(argument)
+
+            argument.resolve_as_matcher
+          end
+
+          arguments[:positional].map!(&block)
+          arguments[:keyword].transform_values!(&block)
+        end
+
+        super
+      end
+
       private
 
+      #
+      # Extracts the namespace and method name from the input string
+      # For example, "be.empty" would return ["be", "empty"]
+      #
+      # @return [Array<String, String>] The namespace and method name
+      #
+      # @private
+      #
       def extract_namespace_and_method
         sections = input.split(".", 2)
 
@@ -69,10 +165,51 @@ module SpecForge
         end
       end
 
+      #
+      # Resolves a matcher with the "matcher" prefix
+      #
+      # @param method [String] The method part after "matcher."
+      #
+      # @return [Method] The resolved matcher method
+      #
+      # @private
+      #
+      def resolve_base_matcher(method)
+        if method == "and"
+          resolve_matcher("forge_and")
+        else
+          resolve_matcher(method)
+        end
+      end
+
+      #
+      # Resolves a matcher method by name from the given namespace
+      #
+      # @param method_name [String, Symbol] The matcher method name
+      # @param namespace [Object] The object to resolve the method from
+      #
+      # @return [Method] The resolved matcher method
+      #
+      # @private
+      #
       def resolve_matcher(method_name, namespace: MATCHER_METHODS)
+        if !namespace.respond_to?(method_name)
+          raise Error::UndefinedMatcherError, method_name
+        end
+
         namespace.public_method(method_name)
       end
 
+      #
+      # Resolves a matcher with the "be" prefix
+      # Handles special cases like be.true, be.nil, comparison operators, etc.
+      #
+      # @param method [String] The method part after "be."
+      #
+      # @return [Method] The resolved matcher method
+      #
+      # @private
+      #
       def resolve_be_matcher(method)
         # Resolve any custom matchers
         resolved_matcher =
@@ -107,12 +244,50 @@ module SpecForge
         resolve_matcher(:"be_#{method}")
       end
 
+      #
+      # Resolves a kind_of matcher for the given type
+      # For example, kind_of.string would check if an object is a String
+      #
+      # @param method [String] The type name to check for
+      #
+      # @return [Method] The resolved matcher method
+      #
+      # @private
+      #
       def resolve_kind_of_matcher(method)
         type_class = Object.const_get(method.capitalize)
         arguments[:positional].insert(0, type_class)
 
         resolve_matcher(:be_kind_of)
       end
+
+      #
+      # Determines whether an argument should skip conversion to a matcher
+      #
+      # This helper method handles the case where string arguments to certain matchers
+      # (include, start_with, end_with) should remain as strings rather than being
+      # converted to eq() matchers.
+      #
+      # @param argument [Object] The argument to analyze
+      #
+      # @return [Boolean] true if the argument should skip conversion, false otherwise
+      #
+      # @example Skip conversion
+      #   skip_argument_conversion?(Attribute::Literal.new(".")) #=> true
+      #   # When used with include, start_with, or end_with
+      #
+      # @example Apply conversion
+      #   skip_argument_conversion?(Attribute::Regex.new("/@/")) #=> false
+      #   # Regex should be converted to match(/@/)
+      #
+      def convert_argument?(argument)
+        return true if argument.is_a?(Attribute::Matcher) || argument.is_a?(Attribute::Regex)
+
+        return true unless [:include, :start_with, :end_with].include?(matcher_method.name)
+
+        resolved = argument.resolved
+        resolved.is_a?(Array) || resolved.is_a?(Hash)
+      end
     end
   end
 end

data/lib/spec_forge/attribute/parameterized.rb

@@ -2,7 +2,33 @@
 
 module SpecForge
   class Attribute
+    #
+    # Base class for attributes that support positional and keyword arguments
+    #
+    # This class provides the foundation for attributes that need to accept
+    # arguments, such as Faker, Matcher, and Factory. It handles both positional
+    # (array-style) and keyword (hash-style) arguments.
+    #
+    # @example With keyword arguments in YAML
+    #   example:
+    #     keyword:
+    #       arg1: value1
+    #       arg2: value2
+    #
+    # @example With positional arguments in YAML
+    #   example:
+    #     keyword:
+    #     - arg1
+    #     - arg2
+    #
     class Parameterized < Attribute
+      #
+      # Creates a new attribute instance from a hash representation
+      #
+      # @param hash [Hash] A hash containing the attribute name and arguments
+      #
+      # @return [Parameterized] A new parameterized attribute instance
+      #
       def self.from_hash(hash)
         metadata = hash.first
 
@@ -21,22 +47,22 @@ module SpecForge
         end
       end
 
-      attr_reader :arguments
-
       #
-      # Represents any attribute that is written in expanded form.
-      # Expanded form is just a fancy name for a hash.
+      # A hash containing both positional and keyword arguments for this attribute
+      # The hash has two keys: :positional (Array) and :keyword (Hash)
+      #
+      # @return [Hash{Symbol => Object}] The arguments hash with structure:
+      #   {
+      #     positional: Array - Contains positional arguments in order
+      #     keyword: Hash - Contains keyword arguments as key-value pairs
+      #   }
       #
-      #   keyword:
-      #     <attribute>:
-      #       <keyword_arg>: <value>
+      attr_reader :arguments
+
       #
-      #   positional:
-      #     <attribute>:
-      #     - <positional_arg>
-      #     - <positional_arg>
+      # Creates a new parameterized attribute with the specified arguments
       #
-      # @param input [Hash] The key that contains these arguments
+      # @param input [String, Symbol] The key that contains these arguments
       # @param positional [Array] Any positional arguments
       # @param keyword [Hash] Any keyword arguments
       #
@@ -46,6 +72,11 @@ module SpecForge
         @arguments = {positional:, keyword:}
       end
 
+      #
+      # Binds variables to any nested attributes in the arguments
+      #
+      # @param variables [Hash] A hash of variable attributes
+      #
       def bind_variables(variables)
         arguments[:positional].each { |v| Attribute.bind_variables(v, variables) }
         arguments[:keyword].each_value { |v| Attribute.bind_variables(v, variables) }
@@ -60,17 +91,11 @@ module SpecForge
       #   This is to allow inheriting classes to normalize their arguments before
       #   they are converted to Attributes
       #
+      # @private
+      #
       def prepare_arguments!
         @arguments = Attribute.from(arguments)
       end
-
-      def uses_positional_arguments?(method)
-        method.parameters.any? { |a| [:req, :opt, :rest].include?(a.first) }
-      end
-
-      def uses_keyword_arguments?(method)
-        method.parameters.any? { |a| [:keyreq, :key, :keyrest].include?(a.first) }
-      end
     end
   end
 end

data/lib/spec_forge/attribute/regex.rb

@@ -2,23 +2,62 @@
 
 module SpecForge
   class Attribute
+    #
+    # Represents a regular expression attribute using Ruby's Regexp class.
+    # This class handles the parsing of regex strings from YAML into actual Regexp objects,
+    # including support for standard regex flags (m, n, i, x).
+    #
+    # @example Basic usage in YAML
+    #   matcher: /pattern/i     # Case-insensitive matching
+    #   email: /@/              # Simple pattern matching
+    #   slug: /^[a-z0-9-]+$/    # Pattern with start/end anchors
+    #
+    # @example With flags
+    #   description: /hello world/i   # Case-insensitive match using 'i' flag
+    #   text_block: /^hello\s+\w+/m   # Multi-line match using 'm' flag
+    #   mixed: /complex pattern/imx   # Multiple flags: case-insensitive, multi-line, extended mode
+    #
     class Regex < Attribute
+      #
+      # Regular expression pattern that matches attribute keywords with this prefix
+      # Used for identifying this attribute type during parsing
+      #
+      # @return [Regexp]
+      #
       KEYWORD_REGEX = /^\/(?<content>[\s\S]+)\/(?<flags>[mnix\s]*)$/i
 
+      #
+      # The parsed Regexp object
+      #
+      # @return [Regexp]
+      #
       attr_reader :value
 
+      alias_method :resolved, :value
+      alias_method :resolve, :value
+
+      #
+      # Creates a new regex attribute by parsing the input string
+      #
+      # @param input [String] The regular expression pattern as a string
+      #
       def initialize(input)
         super
 
         @value = parse_regex(input)
       end
 
-      def resolve
-        @value
-      end
-
       private
 
+      #
+      # Parses a regex string into a Regexp object
+      #
+      # @param input [String] The string representation of the regex (e.g., "/pattern/i")
+      #
+      # @return [Regexp] The compiled regular expression
+      #
+      # @private
+      #
       def parse_regex(input)
         match = input.match(KEYWORD_REGEX)
         captures = match.named_captures.symbolize_keys
@@ -27,7 +66,18 @@ module SpecForge
         Regexp.new(captures[:content], flags)
       end
 
-      # I would've used Regexp.new(string, string), but it raises when "n" is provided as a flag
+      #
+      # Parses regex flags from a string into Regexp option bits
+      # Supports i (case insensitive), m (multiline), x (extended), and n (no encoding)
+      #
+      # @param flags [String] A string containing the flags (e.g., "imx")
+      #
+      # @return [Integer] The combined flag options as a bitmask
+      #
+      # @raise [ArgumentError] If an unknown regex flag is provided
+      #
+      # @private
+      #
       def parse_flags(flags)
         return 0 if flags.blank?
 

data/lib/spec_forge/attribute/resolvable.rb

@@ -3,16 +3,59 @@
 module SpecForge
   class Attribute
     #
-    # Helpers for ResolvableHash and ResolvableArray
+    # Provides helper methods for resolving attributes
+    #
+    # This module contains shared logic for handling attribute resolution
+    # in collection types. It defines procs that can be used with map and
+    # transform operations to recursively resolve nested attributes.
     #
     module Resolvable
-      # @private
-      def resolvable_proc
+      #
+      # Returns a proc that resolves objects to their cached final values.
+      # For objects that respond to #resolved, calls that method.
+      # For other objects, simply returns them unchanged.
+      #
+      # @return [Proc] A proc for resolving objects to their cached final values
+      #
+      # @example
+      #   proc = resolved_proc
+      #   proc.call(Attribute::Faker.new("faker.name.name")) # => "Jane Doe" (cached)
+      #   proc.call("already resolved") # => "already resolved" (unchanged)
+      #
+      def resolved_proc
+        ->(v) { v.respond_to?(:resolved) ? v.resolved : v }
+      end
+
+      #
+      # Returns a proc that freshly resolves objects.
+      # For objects that respond to #resolve, calls that method.
+      # For other objects, simply returns them unchanged.
+      #
+      # @return [Proc] A proc for freshly resolving objects
+      #
+      # @example
+      #   proc = resolve_proc
+      #   proc.call(Attribute::Faker.new("faker.name.name")) # => "John Smith" (fresh)
+      #   proc.call("already resolved") # => "already resolved" (unchanged)
+      #
+      def resolve_proc
         ->(v) { v.respond_to?(:resolve) ? v.resolve : v }
       end
 
-      def resolvable_value_proc
-        ->(v) { v.respond_to?(:resolve_value) ? v.resolve_value : v }
+      #
+      # Returns a proc that resolves attributes into their matcher form.
+      # For objects that respond to #resolve_as_matcher, calls that method.
+      # For other objects, simply returns them unchanged.
+      #
+      # @return [Proc] A proc for resolving attributes to matchers
+      #
+      # @example
+      #   proc = resolve_as_matcher_proc
+      #   proc.call(Attribute::Faker.new("faker.name.name")) # => eq("John Doe")
+      #   proc.call(Attribute::Regex.new("/hello/")) # => match(/hello/)
+      #
+      def resolve_as_matcher_proc
+        ->(v) { v.respond_to?(:resolve_as_matcher) ? v.resolve_as_matcher : v }
       end
     end
   end