spec_forge 0.5.0 → 0.6.0

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)
       #
-      #   keyword:
-      #     <attribute>:
-      #       <keyword_arg>: <value>
+      # @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
+      #   }
       #
-      #   positional:
-      #     <attribute>:
-      #     - <positional_arg>
-      #     - <positional_arg>
+      attr_reader :arguments
+
+      #
+      # 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,6 +91,8 @@ 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

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

data/lib/spec_forge/attribute/resolvable_array.rb

@@ -3,23 +3,81 @@
 module SpecForge
   class Attribute
     #
-    # Represents an Array that may contain Attributes
+    # Represents an array that may contain attributes that need resolution
+    #
+    # This delegator wraps an array and provides methods to recursively resolve
+    # any attribute objects contained within it. It allows arrays to contain
+    # dynamic content like variables and faker values.
+    #
+    # @example In code
+    #   array = [1, Attribute::Variable.new("variables.user_id"), 3]
+    #   resolvable = Attribute::ResolvableArray.new(array)
+    #   resolvable.resolved # => [1, 42, 3]  # assuming user_id resolves to 42
     #
     class ResolvableArray < SimpleDelegator
       include Resolvable
 
+      #
+      # Returns the underlying array
+      #
+      # @return [Array] The delegated array
+      #
       def value
         __getobj__
       end
 
+      #
+      # Returns a new array with all items fully resolved to their final values.
+      # Uses the cached version of each item if available.
+      #
+      # @return [Array] A new array with all items fully resolved to their final values
+      #
+      # @example
+      #   array_attr = Attribute::ResolvableArray.new([Attribute::Faker.new("faker.name.name")])
+      #   array_attr.resolved # => ["Jane Doe"] (with result cached)
+      #
+      def resolved
+        value.map(&resolved_proc)
+      end
+
+      #
+      # Freshly resolves all items in the array.
+      # Unlike #resolved, this doesn't use cached values, ensuring fresh resolution.
+      #
+      # @return [Array] A new array with all items freshly resolved
+      #
+      # @example
+      #   array_attr = Attribute::ResolvableArray.new([Attribute::Faker.new("faker.name.name")])
+      #   array_attr.resolve # => ["John Smith"] (fresh value each time)
+      #
       def resolve
-        value.map(&resolvable_proc)
+        value.map(&resolve_proc)
       end
 
-      def resolve_value
-        value.map(&resolvable_value_proc)
+      #
+      # Converts all items in the array to RSpec matchers.
+      # First converts each array element to a matcher using resolve_as_matcher_proc,
+      # then wraps the entire result in a matcher suitable for array comparison.
+      #
+      # This ensures all elements in the array are proper matchers,
+      # which is essential for compound matchers and proper failure messages.
+      #
+      # @return [RSpec::Matchers::BuiltIn::BaseMatcher] A matcher for this array
+      #
+      # @example
+      #   array = Attribute::ResolvableArray.new(["test", /pattern/, 42])
+      #   array.resolve_as_matcher # => contain_exactly(eq("test"), match(/pattern/), eq(42))
+      #
+      def resolve_as_matcher
+        result = value.map(&resolve_as_matcher_proc)
+        Attribute::Literal.new(result).resolve_as_matcher
       end
 
+      #
+      # Binds variables to any attribute objects in the array
+      #
+      # @param variables [Hash] The variables to bind
+      #
       def bind_variables(variables)
         value.each { |v| Attribute.bind_variables(v, variables) }
       end

data/lib/spec_forge/attribute/resolvable_hash.rb

@@ -3,23 +3,81 @@
 module SpecForge
   class Attribute
     #
-    # Represents a hash that may contain Attributes
+    # Represents a hash that may contain attributes that need resolution
+    #
+    # This delegator wraps a hash and provides methods to recursively resolve
+    # any attribute objects contained within it. It allows hashes to contain
+    # dynamic content like variables and faker values.
+    #
+    # @example In code
+    #   hash = {name: Attribute::Faker.new("faker.name.name"), id: 123}
+    #   resolvable = Attribute::ResolvableHash.new(hash)
+    #   resolvable.resolved # => {name: "John Smith", id: 123}
     #
     class ResolvableHash < SimpleDelegator
       include Resolvable
 
+      #
+      # Returns the underlying hash
+      #
+      # @return [Hash] The delegated hash
+      #
       def value
         __getobj__
       end
 
+      #
+      # Returns a new hash with all values fully resolved to their final values.
+      # Uses the cached version of each value if available.
+      #
+      # @return [Hash] A new hash with all values fully resolved to their final values
+      #
+      # @example
+      #   hash_attr = Attribute::ResolvableHash.new({name: Attribute::Faker.new("faker.name.name")})
+      #   hash_attr.resolved # => {name: "Jane Doe"} (with result cached)
+      #
+      def resolved
+        value.transform_values(&resolved_proc)
+      end
+
+      #
+      # Freshly resolves all values in the hash.
+      # Unlike #resolved, this doesn't use cached values, ensuring fresh resolution.
+      #
+      # @return [Hash] A new hash with all values freshly resolved
+      #
+      # @example
+      #   hash_attr = Attribute::ResolvableHash.new({name: Attribute::Faker.new("faker.name.name")})
+      #   hash_attr.resolve # => {name: "John Smith"} (fresh value each time)
+      #
       def resolve
-        value.transform_values(&resolvable_proc)
+        value.transform_values(&resolve_proc)
       end
 
-      def resolve_value
-        value.transform_values(&resolvable_value_proc)
+      #
+      # Converts all values in the hash to RSpec matchers.
+      # Transforms each hash value to a matcher using resolve_as_matcher_proc,
+      # then wraps the entire result in a matcher suitable for hash comparison.
+      #
+      # This ensures proper nesting of matchers in hash structures,
+      # which is vital for readable failure messages in complex expectations.
+      #
+      # @return [RSpec::Matchers::BuiltIn::BaseMatcher] A matcher for this hash
+      #
+      # @example
+      #   hash = Attribute::ResolvableHash.new({name: "Test", age: 42})
+      #   hash.resolve_as_matcher # => include("name" => eq("Test"), "age" => eq(42))
+      #
+      def resolve_as_matcher
+        result = value.transform_values(&resolve_as_matcher_proc)
+        Attribute::Literal.new(result).resolve_as_matcher
       end
 
+      #
+      # Binds variables to any attribute objects in the hash values
+      #
+      # @param variables [Hash] The variables to bind
+      #
       def bind_variables(variables)
         value.each_value { |v| Attribute.bind_variables(v, variables) }
       end

data/lib/spec_forge/attribute/store.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Attribute
+    #
+    # Represents an attribute that references values from stored test results
+    #
+    # This class allows accessing data from previous test executions that were
+    # saved using the `store_as` directive. It provides access to response data
+    # including status, headers, and body from previously run expectations.
+    #
+    # @example Basic usage in YAML
+    #   create_user:
+    #     path: /users
+    #     method: post
+    #     expectations:
+    #     - store_as: new_user
+    #       body:
+    #         name: faker.name.name
+    #       expect:
+    #         status: 201
+    #
+    #   get_user:
+    #     path: /users/{id}
+    #     expectations:
+    #     - query:
+    #         id: store.new_user.body.id
+    #       expect:
+    #         status: 200
+    #
+    # @example Accessing specific response components
+    #   check_status:
+    #     path: /health
+    #     expectations:
+    #     - variables:
+    #         expected_status: store.new_user.status
+    #         auth_token: store.new_user.headers.authorization
+    #         user_name: store.new_user.body.user.name
+    #       expect:
+    #         status: 200
+    #
+    class Store < Attribute
+      include Chainable
+
+      #
+      # Regular expression pattern that matches attribute keywords with this prefix
+      # Used for identifying this attribute type during parsing
+      #
+      # @return [Regexp]
+      #
+      KEYWORD_REGEX = /^store\./i
+
+      alias_method :stored_id, :header
+
+      #
+      # Returns the base object for the variable chain
+      #
+      # @return [Context::Store::Entry, nil] The stored entry or nil if not found
+      #
+      def base_object
+        @base_object ||= SpecForge.context.store[stored_id.to_s]
+      end
+    end
+  end
+end

data/lib/spec_forge/attribute/transform.rb

@@ -2,9 +2,34 @@
 
 module SpecForge
   class Attribute
+    #
+    # Represents an attribute that transforms other attributes
+    #
+    # This class provides transformation functions like join that can be applied
+    # to other attributes or values. It allows complex data manipulation without
+    # writing Ruby code.
+    #
+    # @example Join transformation in YAML
+    #   full_name:
+    #     transform.join:
+    #     - variables.first_name
+    #     - " "
+    #     - variables.last_name
+    #
     class Transform < Parameterized
+      #
+      # Regular expression pattern that matches attribute keywords with this prefix
+      # Used for identifying this attribute type during parsing
+      #
+      # @return [Regexp]
+      #
       KEYWORD_REGEX = /^transform\./i
 
+      #
+      # The available transformation methods
+      #
+      # @return [Array<String>]
+      #
       TRANSFORM_METHODS = %w[
         join
       ].freeze
@@ -12,9 +37,7 @@ module SpecForge
       attr_reader :function
 
       #
-      # Represents any attribute that is a transform call
-      #
-      #   transform.<function>
+      # Creates a new transform attribute with the specified function and arguments
       #
       def initialize(...)
         super
@@ -22,16 +45,21 @@ module SpecForge
         # Remove prefix
         @function = @input.sub("transform.", "")
 
-        raise InvalidTransformFunctionError, input unless TRANSFORM_METHODS.include?(function)
+        raise Error::InvalidTransformFunctionError, input unless TRANSFORM_METHODS.include?(function)
 
         prepare_arguments!
       end
 
+      #
+      # Returns the result of applying the transformation function
+      #
+      # @return [Object] The transformed value
+      #
       def value
         case function
         when "join"
           # Technically supports any attribute, but I ain't gonna test all them edge cases
-          arguments[:positional].resolve.join
+          arguments[:positional].resolved.join
         end
       end
     end

data/lib/spec_forge/attribute/variable.rb

@@ -3,26 +3,57 @@
 module SpecForge
   class Attribute
     #
-    # Represents any attribute that is a variable reference
+    # Represents an attribute that references a variable
     #
-    #   variables.<variable_name>
+    # This class allows referencing variables defined in the test context.
+    # It supports chained access to methods and properties of variable values.
+    #
+    # @example Basic usage in YAML
+    #   user_id: variables.user.id
+    #   company_name: variables.company.name
+    #
+    # @example Nested access in YAML
+    #   post_author: variables.post.comments.first.author.name
     #
     class Variable < Attribute
       include Chainable
 
+      #
+      # Regular expression pattern that matches attribute keywords with this prefix
+      # Used for identifying this attribute type during parsing
+      #
+      # @return [Regexp]
+      #
       KEYWORD_REGEX = /^variables\./i
 
       alias_method :variable_name, :header
 
+      #
+      # Binds the referenced variable to this attribute
+      #
+      # @param variables [Hash] A hash of variables to look up in
+      #
+      # @raise [Error::MissingVariableError] If the variable is not found
+      # @raise [Error::InvalidTypeError] If variables is not a hash
+      #
       def bind_variables(variables)
-        raise InvalidTypeError.new(variables, Hash, for: "'variables'") unless Type.hash?(variables)
+        if !Type.hash?(variables)
+          raise Error::InvalidTypeError.new(variables, Hash, for: "'variables'")
+        end
 
         # Don't nil check here.
-        raise MissingVariableError, variable_name unless variables.key?(variable_name)
+        raise Error::MissingVariableError, variable_name unless variables.key?(variable_name)
 
-        @base_object = variables[variable_name]
+        @variable = variables[variable_name]
+      end
 
-        self
+      #
+      # Returns the base object for the variable chain
+      #
+      # @return [Object] The variable value
+      #
+      def base_object
+        @variable || bind_variables(SpecForge.context.variables)
       end
     end
   end