spec_forge 0.5.0 → 0.7.0

data/lib/spec_forge/attribute/chainable.rb

@@ -2,84 +2,272 @@
 
 module SpecForge
   class Attribute
+    #
+    # Adds support for an attribute to accept n-number of chained calls. It supports chaining
+    # methods, hash keys, and array indexes. It also works well alongside Parameterized attributes
+    #
+    # This module requires being included into a class first before it can be used
+    #
+    # @example Basic usage in YAML
+    #   my_variable: variable.users.first
+    #
+    # @example Advanced usage in YAML
+    #   my_variable: variable.users.0.posts.second.author.name
+    #
+    # @example Basic usage in code
+    #   faker = SpecForge::Attribute.from("faker.name.name.upcase")
+    #   faker.resolved #=> BENDING UNIT 22
+    #
     module Chainable
+      #
+      # Regular expression that matches pure numeric strings
+      # Used for detecting potential array index operations
+      #
+      # @return [Regexp] A case-insensitive regex matching strings containing only digits
+      #
       NUMBER_REGEX = /^\d+$/i
 
-      attr_reader :header, :invocation_chain, :base_object
+      #
+      # The first part of the chained attribute
+      #
+      # @return [Symbol] The first component of the chained attribute
+      #
+      attr_reader :keyword
+
+      #
+      # The second part of the chained attribute
+      #
+      # @return [Symbol] The second component of the chained attribute
+      #
+      attr_reader :header
+
+      #
+      # The remaining parts of the attribute chain after the header
+      #
+      # @return [Array<Symbol>] The remaining method/key invocations in the chain
+      #
+      attr_reader :invocation_chain
 
       #
-      # Represents any attribute that is a series of chained invocations:
+      # The initial object from which the chain will start traversing
+      #
+      # @return [Object] The base object that starts the method/attribute chain
       #
-      #   <keyword>.<header>.<segment(hash_key | method | index)>...
+      attr_reader :base_object
+
       #
-      # This module is not used as is, but is included in another class.
-      # Note: There can be any n number of segments.
+      # Initializes a new chainable attribute by parsing the input into components
       #
       def initialize(...)
         super
 
-        # Drop the keyword
-        sections = input.split(".")[1..]
+        sections = input.split(".")
 
-        @header = sections.first&.to_sym
-        @invocation_chain = sections[1..] || []
+        @keyword = sections.first.to_sym
+        @header = sections.second&.to_sym
+        @invocation_chain = sections[2..] || []
       end
 
+      #
+      # Returns the value of this attribute by resolving the chain
+      # Will return a new value on each call for dynamic attributes like Faker
+      #
+      # @return [Object] The result of invoking the chain on the base object
+      #
       def value
         invoke_chain
       end
 
-      def resolve
+      #
+      # Resolves the chain and stores the result
+      # The result is memoized, so subsequent calls return the same value
+      # even for dynamic attributes like Faker and Factory
+      #
+      # @return [Object] The fully resolved and memoized value
+      #
+      def resolved
         @resolved ||= resolve_chain
       end
 
       private
 
+      #
+      # Invokes the chain by calling #value on each object
+      #
+      # @return [Object] The result of invoking the chain
+      #
+      # @private
+      #
       def invoke_chain
         traverse_chain(resolve: false)
       end
 
+      #
+      # Resolves the chain by calling #resolve on each object
+      #
+      # @return [Object] The fully resolved result
+      #
+      # @private
+      #
       def resolve_chain
-        __resolve(traverse_chain(resolve: true))
+        traverse_chain(resolve: true)
       end
 
+      #
+      # Traverses the chain of invocations step by step
+      #
+      # @param resolve [Boolean] Whether to use resolve during traversal
+      #
+      # @return [Object] The result of the traversal
+      #
+      # @private
+      #
       def traverse_chain(resolve:)
-        result = invocation_chain.reduce(base_object) do |current_value, step|
-          next_value = retrieve_value(current_value, resolve:)
+        resolution_path = {}
+
+        current_path = "#{keyword}.#{header}"
+        current_object = base_object
+
+        invocation_chain.each do |step|
+          next_value = retrieve_value(current_object, resolve:)
+
+          # Store this step's resolution for error reporting
+          resolution_path[current_path] = describe_value(next_value)
+          current_path += ".#{step}"
+
+          # Try to invoke the next step
+          current_object = invoke(step, next_value)
+        rescue Error::InvalidInvocationError => e
+          resolution_path[current_path] = "Error: #{e.message}"
 
-          invoke(step, next_value)
+          raise e.with_resolution_path(resolution_path)
         end
 
-        retrieve_value(result, resolve:)
+        # Return final result
+        retrieve_value(current_object, resolve:)
       end
 
+      #
+      # Retrieves the value from an object, resolving it if needed
+      #
+      # @param object [Object] The object to retrieve a value from
+      # @param resolve [Boolean] Whether to resolve the object's value
+      #
+      # @return [Object] The retrieved value
+      #
+      # @private
+      #
       def retrieve_value(object, resolve:)
         return object unless object.is_a?(Attribute)
 
-        resolve ? object.resolve : object.value
+        resolve ? object.resolved : object.value
+      end
+
+      #
+      # Creates a description of a value for error messages
+      #
+      # @param value [Object] The value to describe
+      #
+      # @return [String] A description
+      #
+      # @private
+      #
+      def describe_value(value)
+        case value
+        when Context::Store::Entry
+          "Store with attributes: #{value.available_methods.join_map(", ", &:in_quotes)}"
+        when OpenStruct
+          "Object with attributes: #{value.table.keys.join_map(", ", &:in_quotes)}"
+        when Struct, Data
+          "Object with attributes: #{value.members.join_map(", ", &:in_quotes)}"
+        when ArrayLike
+          # Preview the first 5 value's classes
+          preview = value.take(5).map(&:class)
+          preview << "..." if value.size > 5
+
+          "Array with #{value.size} #{"element".pluralize(value.size)}: #{preview}"
+        when HashLike
+          # Preview the first 5 keys
+          keys = value.keys.take(5)
+
+          preview = keys.join_map(", ") { |key| "\"#{key}\"" }
+          preview += ", ..." if value.keys.size > 5
+
+          "Hash with #{"key".pluralize(keys.size)}: #{preview}"
+        when String
+          "\"#{value.truncate(50)}\""
+        when NilClass
+          "nil"
+        when Proc
+          "Proc defined at #{value.source_location.join(":")}"
+        else
+          "#{value.class}: #{value.inspect[0..50]}"
+        end
       end
 
+      #
+      # Invokes an operation on an object based on the step type (hash key, array index, or method)
+      #
+      # @param step [String] The step to invoke
+      # @param object [Object] The object to invoke the step on
+      #
+      # @return [Object] The result of the invocation
+      #
+      # @raise [Error::InvalidInvocationError] If the step cannot be invoked on the object
+      #
+      # @private
+      #
       def invoke(step, object)
         if hash_key?(object, step)
-          object[step.to_sym]
+          object[step.to_s] || object[step.to_sym]
         elsif index?(object, step)
           object[step.to_i]
         elsif method?(object, step)
           object.public_send(step)
         else
-          raise InvalidInvocationError.new(step, object)
+          raise Error::InvalidInvocationError.new(step, object)
         end
       end
 
+      #
+      # Checks if the object can be accessed with the given key
+      #
+      # @param object [Object] The object to check
+      # @param key [String] The key to check
+      #
+      # @return [Boolean] Whether the object supports hash-like access with the key
+      #
+      # @private
+      #
       def hash_key?(object, key)
-        # This is to support the silly delegator
-        method?(object, :key?) && object.key?(key.to_sym)
+        # This is to support the silly delegator and both symbol/string
+        method?(object, :key?) && (object.key?(key.to_s) || object.key?(key.to_sym))
       end
 
+      #
+      # Checks if the object responds to the given method
+      #
+      # @param object [Object] The object to check
+      # @param method_name [String, Symbol] The method name to check
+      #
+      # @return [Boolean] Whether the object responds to the method
+      #
+      # @private
+      #
       def method?(object, method_name)
         object.respond_to?(method_name)
       end
 
+      #
+      # Checks if the object supports array-like access with the given index
+      #
+      # @param object [Object] The object to check
+      # @param step [String] The potential index
+      #
+      # @return [Boolean] Whether the object supports array-like access with the step
+      #
+      # @private
+      #
       def index?(object, step)
         # This is to support the silly delegator
         method?(object, :index) && step.match?(NUMBER_REGEX)

data/lib/spec_forge/attribute/factory.rb

@@ -2,13 +2,54 @@
 
 module SpecForge
   class Attribute
+    #
+    # Represents an attribute that references a factory to generate test data
+    #
+    # This class allows SpecForge to integrate with FactoryBot for test data generation.
+    # It supports various build strategies like create, build, build_stubbed, etc.
+    #
+    # @example Basic usage in YAML
+    #   user: factories.user
+    #
+    # @example With custom attributes
+    #   user:
+    #     factories.user:
+    #       attributes:
+    #         name: "Custom Name"
+    #         email: faker.internet.email
+    #
+    # @example With build strategy
+    #   user:
+    #     factories.user:
+    #       strategy: build
+    #       attributes:
+    #         admin: true
+    #
+    # @example With an array of 5 user attributes
+    #   user:
+    #     factories.user:
+    #       strategy: attributes_for
+    #       size: 5
+    #       attributes:
+    #         admin: true
+    #
     class Factory < Parameterized
       include Chainable
 
+      #
+      # Regular expression pattern that matches attribute keywords with this prefix
+      # Used for identifying this attribute type during parsing
+      #
+      # @return [Regexp]
+      #
       KEYWORD_REGEX = /^factories\./i
 
-      # These are the base strategies that can be provided either with or without size
-      # stubbed will be transformed into build_stubbed
+      #
+      # An array of base strategies that can be provided either with or
+      # without a size. "stubbed" will automatically be transformed into "build_stubbed"
+      #
+      # @return [Array<String>]
+      #
       BASE_STRATEGIES = %w[
         build
         create
@@ -16,7 +57,7 @@ module SpecForge
         attributes_for
       ].freeze
 
-      # All available build strategies that are accepted
+      # @return [Array<String>] All available build strategies
       BUILD_STRATEGIES = %w[
         attributes_for
         attributes_for_list
@@ -33,21 +74,22 @@ module SpecForge
       alias_method :factory_name, :header
 
       #
-      # Represents any attribute that is a factory reference
-      #
-      #   factories.<factory_name>
+      # Creates a new factory attribute with the specified name and arguments
       #
       def initialize(...)
         super
 
         # Check the arguments before preparing them
-        arguments[:keyword] = Normalizer.normalize_factory_reference!(arguments[:keyword])
+        arguments[:keyword] = Normalizer.normalize!(arguments[:keyword], using: :factory_reference)
 
         prepare_arguments!
       end
 
-      private
-
+      #
+      # Returns the base object for the variable chain
+      #
+      # @return [Object] The result of the FactoryBot call
+      #
       def base_object
         attributes = arguments[:keyword]
 
@@ -58,19 +100,49 @@ module SpecForge
         FactoryBot.public_send(*build_arguments)
       end
 
+      #
+      # Similar to #resolved but doesn't cache the result, allowing for re-resolution.
+      # Recursively calls #resolve on all nested attributes without storing results.
+      #
+      # Use this when you need to ensure fresh values each time, particularly with
+      # factories or other attributes that should generate new values on each call.
+      #
+      # @return [Object] The completely resolved value without caching
+      #
+      # @example
+      #   factory_attr = Attribute::Factory.new("factories.user")
+      #   factory_attr.resolve # => User#1 (a new user)
+      #   factory_attr.resolve # => User#2 (another new user)
+      #
+      def resolve
+        case value
+        when ArrayLike
+          value.map(&resolved_proc)
+        when HashLike
+          value.transform_values(&resolved_proc)
+        else
+          value
+        end
+      end
+
+      private
+
+      #
+      # @private
+      #
       def construct_factory_parameters(attributes)
         build_strategy, list_size = determine_build_strategy(attributes)
 
         # This is set up for the base strategies + _pair
-        # FactoryBot.create(factory_name, **attributes)
+        # FactoryBot.<build_strategy>(factory_name, **attributes)
         build_arguments = [
           build_strategy,
           factory_name,
-          **attributes[:attributes].resolve_value
+          **attributes[:attributes].resolve
         ]
 
         # Insert the list size after the strategy
-        # FactoryBot.create_list(factory_name, list_size, **attributes)
+        # FactoryBot.<build_strategy>_list(factory_name, list_size, **attributes)
         if build_strategy.end_with?("_list")
           build_arguments.insert(2, list_size)
         end
@@ -78,10 +150,13 @@ module SpecForge
         build_arguments
       end
 
+      #
+      # @private
+      #
       def determine_build_strategy(attributes)
         # Determine build strat, and unfreeze
-        build_strategy = +attributes[:build_strategy].resolve_value
-        list_size = attributes[:size].resolve_value
+        build_strategy = +attributes[:build_strategy].resolve
+        list_size = attributes[:size].resolve
 
         # stubbed => build_stubbed
         build_strategy.prepend("build_") if build_strategy.start_with?("stubbed")
@@ -94,7 +169,9 @@ module SpecForge
           build_strategy += "_list"
         end
 
-        raise InvalidBuildStrategy, build_strategy unless BUILD_STRATEGIES.include?(build_strategy)
+        if !BUILD_STRATEGIES.include?(build_strategy)
+          raise Error::InvalidBuildStrategy, build_strategy
+        end
 
         [build_strategy, list_size]
       end

data/lib/spec_forge/attribute/faker.rb

@@ -2,17 +2,44 @@
 
 module SpecForge
   class Attribute
+    #
+    # Represents an attribute that generates fake data using the Faker gem
+    #
+    # This class allows SpecForge to integrate with the Faker library to generate realistic
+    # test data like names, emails, addresses, etc.
+    #
+    # @example Basic usage in YAML
+    #   name: faker.name.name
+    #   email: faker.internet.email
+    #
+    # @example With method arguments
+    #   age:
+    #     faker.number.between:
+    #       from: 18
+    #       to: 65
+    #
+    # @example Handles nested faker classes
+    #   character: faker.games.zelda.character
+    #
     class Faker < Parameterized
       include Chainable
 
+      #
+      # Regular expression pattern that matches attribute keywords with this prefix
+      # Used for identifying this attribute type during parsing
+      #
+      # @return [Regexp]
+      #
       KEYWORD_REGEX = /^faker\./i
 
-      attr_reader :faker_class, :faker_method
+      # @return [Class] The Faker class
+      attr_reader :faker_class
+
+      # @return [Method] The Faker class method
+      attr_reader :faker_method
 
       #
-      # Represents any attribute that is a faker call
-      #
-      #   faker.<faker_class>.<faker_method>
+      # Creates a new faker attribute with the specified name and arguments
       #
       def initialize(...)
         super
@@ -22,18 +49,37 @@ module SpecForge
         prepare_arguments!
       end
 
-      private
-
+      #
+      # Returns the base object for the variable chain
+      #
+      # @return [Object] The result of the Faker call
+      #
       def base_object
         if (positional = arguments[:positional]) && positional.present?
-          faker_method.call(*positional.resolve)
+          faker_method.call(*positional.resolved)
         elsif (keyword = arguments[:keyword]) && keyword.present?
-          faker_method.call(**keyword.resolve)
+          faker_method.call(**keyword.resolved)
         else
           faker_method.call
         end
       end
 
+      private
+
+      #
+      # Extracts the Faker class and method from the input string
+      # Handles both simple cases like "faker.name.first_name" and complex
+      # nested namespaces like "faker.games.zelda.game"
+      #
+      # @return [Array<Class, Method>] A two-element array containing:
+      #   1. The resolved Faker class (e.g., Faker::Name)
+      #   2. The method object to call on that class (e.g., #first_name)
+      #
+      # @raise [Error::InvalidFakerClassError] If the specified Faker class doesn't exist
+      # @raise [Error::InvalidFakerMethodError] If the specified method doesn't exist on the class
+      #
+      # @private
+      #
       def extract_faker_call
         class_name = header.downcase.to_s
 
@@ -42,10 +88,10 @@ module SpecForge
           return resolve_faker_class_and_method(class_name, invocation_chain.shift)
         end
 
-        # Try each part of the chain as a potential class name
-        # Example: faker.games.zelda.game.underscore
         namespace = []
 
+        # Try each part of the chain as a potential class name
+        # Example: faker.games.zelda.game.underscore
         while invocation_chain.any?
           part = invocation_chain.first.downcase
           test_class_name = ([class_name] + namespace + [part]).map(&:camelize).join("::")
@@ -65,22 +111,25 @@ module SpecForge
 
         # If we get here, we consumed all parts as classes but found no method
         class_name = ([class_name] + namespace).map(&:camelize).join("::")
-        raise InvalidFakerMethodError.new(nil, "::#{class_name}".constantize)
+        raise Error::InvalidFakerMethodError.new(nil, "::#{class_name}".constantize)
       end
 
+      #
+      # @private
+      #
       def resolve_faker_class_and_method(class_name, method_name)
         # Load the class
         faker_class = begin
           "::Faker::#{class_name.camelize}".constantize
         rescue NameError
-          raise InvalidFakerClassError, class_name
+          raise Error::InvalidFakerClassError, class_name
         end
 
         # Load the method
         faker_method = begin
           faker_class.method(method_name)
         rescue NameError
-          raise InvalidFakerMethodError.new(method_name, faker_class)
+          raise Error::InvalidFakerMethodError.new(method_name, faker_class)
         end
 
         [faker_class, faker_method]

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