spec_forge 0.4.0 → 0.6.0

data/flake.lock

@@ -20,11 +20,11 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1737469691,
-        "narHash": "sha256-nmKOgAU48S41dTPIXAq0AHZSehWUn6ZPrUKijHAMmIk=",
+        "lastModified": 1742422364,
+        "narHash": "sha256-mNqIplmEohk5jRkqYqG19GA8MbQ/D4gQSK0Mu4LvfRQ=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "9e4d5190a9482a1fb9d18adf0bdb83c6e506eaab",
+        "rev": "a84ebe20c6bc2ecbcfb000a50776219f48d134cc",
         "type": "github"
       },
       "original": {

data/flake.nix

@@ -6,8 +6,14 @@
     flake-utils.url = "github:numtide/flake-utils";
   };
 
-  outputs = { self, nixpkgs, flake-utils }:
-    flake-utils.lib.eachDefaultSystem (system:
+  outputs =
+    {
+      self,
+      nixpkgs,
+      flake-utils,
+    }:
+    flake-utils.lib.eachDefaultSystem (
+      system:
       let
         pkgs = nixpkgs.legacyPackages.${system};
       in

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,24 +2,79 @@
 
 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
 
-      BUILD_STRATEGIES = %w[
+      #
+      # 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
+        build_stubbed
+        attributes_for
+      ].freeze
+
+      # @return [Array<String>] All available build strategies
+      BUILD_STRATEGIES = %w[
         attributes_for
+        attributes_for_list
+        build
+        build_list
+        build_pair
         build_stubbed
+        build_stubbed_list
+        create
+        create_list
+        create_pair
       ].freeze
 
       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
@@ -30,21 +85,95 @@ module SpecForge
         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]
+
+        # Default functionality is to create ("factory.user")
         return FactoryBot.create(factory_name) if attributes.blank?
 
-        # Determine build strat
-        build_strategy = attributes[:build_strategy].resolve_value
+        build_arguments = construct_factory_parameters(attributes)
+        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.<build_strategy>(factory_name, **attributes)
+        build_arguments = [
+          build_strategy,
+          factory_name,
+          **attributes[:attributes].resolve
+        ]
+
+        # Insert the list size after the strategy
+        # FactoryBot.<build_strategy>_list(factory_name, list_size, **attributes)
+        if build_strategy.end_with?("_list")
+          build_arguments.insert(2, list_size)
+        end
+
+        build_arguments
+      end
+
+      #
+      # @private
+      #
+      def determine_build_strategy(attributes)
+        # Determine build strat, and unfreeze
+        build_strategy = +attributes[:build_strategy].resolve
+        list_size = attributes[:size].resolve
 
         # stubbed => build_stubbed
-        build_strategy.prepend("build_") if build_strategy == "stubbed"
-        raise InvalidBuildStrategy, build_strategy unless BUILD_STRATEGIES.include?(build_strategy)
+        build_strategy.prepend("build_") if build_strategy.start_with?("stubbed")
+
+        # create + size => create_list
+        # build + size => build_list
+        # build_stubbed + size => build_stubbed_list
+        # attributes_for + size => attributes_for_list
+        if list_size.positive? && BASE_STRATEGIES.include?(build_strategy)
+          build_strategy += "_list"
+        end
+
+        if !BUILD_STRATEGIES.include?(build_strategy)
+          raise Error::InvalidBuildStrategy, build_strategy
+        end
 
-        attributes = attributes[:attributes].resolve_value
-        FactoryBot.public_send(build_strategy, factory_name, **attributes)
+        [build_strategy, list_size]
       end
     end
   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 uses_positional_arguments?(faker_method)
-          faker_method.call(*arguments[:positional].resolve)
-        elsif uses_keyword_arguments?(faker_method)
-          faker_method.call(**arguments[:keyword].resolve)
+        if (positional = arguments[:positional]) && positional.present?
+          faker_method.call(*positional.resolved)
+        elsif (keyword = arguments[:keyword]) && keyword.present?
+          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]