spec_forge 0.7.1 → 1.0.0

data/lib/spec_forge/attribute/chainable.rb

@@ -58,6 +58,8 @@ module SpecForge
       #
       # Initializes a new chainable attribute by parsing the input into components
       #
+      # Parses the input string into keyword, header, and invocation chain parts.
+      #
       def initialize(...)
         super
 
@@ -125,7 +127,7 @@ module SpecForge
       def traverse_chain(resolve:)
         resolution_path = {}
 
-        current_path = "#{keyword}.#{header}"
+        current_path = keyword.present? ? "#{keyword}.#{header}" : header.to_s
         current_object = base_object
 
         invocation_chain.each do |step|
@@ -160,7 +162,7 @@ module SpecForge
       def retrieve_value(object, resolve:)
         return object unless object.is_a?(Attribute)
 
-        resolve ? object.resolved : object.value
+        resolve ? object.resolve : object.value
       end
 
       #
@@ -174,19 +176,17 @@ module SpecForge
       #
       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
+        when Array
           # 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
+        when Hash
           # Preview the first 5 keys
           keys = value.keys.take(5)
 

data/lib/spec_forge/attribute/environment.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Attribute
+    #
+    # Represents an attribute that retrieves its value from an environment variable.
+    # This allows specs to reference environment variables dynamically.
+    #
+    # @example Basic usage in YAML
+    #   api_key: "{{ env.API_KEY }}"
+    #   database_url: "{{ env.DATABASE_URL }}"
+    #   secret: "{{ env.MY_SECRET_TOKEN }}"
+    #
+    class Environment < Attribute
+      #
+      # Regular expression pattern that matches attribute keywords with this prefix.
+      # Used for identifying this attribute type during parsing.
+      # Matches case-insensitively (env., ENV., Env., etc.)
+      #
+      # @return [Regexp]
+      #
+      KEYWORD_REGEX = /^env\./i
+
+      #
+      # Creates a new environment attribute by extracting the variable name
+      #
+      # @param input [String] The environment variable reference (e.g., "env.API_KEY")
+      #
+      def initialize(...)
+        super
+
+        @variable_name = input.sub(KEYWORD_REGEX, "")
+      end
+
+      #
+      # Returns the value of the referenced environment variable
+      #
+      # @return [String, nil] The environment variable value, or nil if not set
+      #
+      def value
+        ENV[@variable_name]
+      end
+    end
+  end
+end

data/lib/spec_forge/attribute/factory.rb

@@ -76,13 +76,15 @@ module SpecForge
       #
       # Creates a new factory attribute with the specified name and arguments
       #
+      # @see Parameterized#initialize
+      #
       def initialize(...)
         super
 
         # Check the arguments before preparing them
         arguments[:keyword] = Normalizer.normalize!(arguments[:keyword], using: :factory_reference)
 
-        prepare_arguments!
+        prepare_arguments
       end
 
       #
@@ -116,10 +118,10 @@ module SpecForge
       #
       def resolve
         case value
-        when ArrayLike
-          value.map(&resolved_proc)
-        when HashLike
-          value.transform_values(&resolved_proc)
+        when Array
+          value.map(&resolve_proc)
+        when Hash
+          value.transform_values(&resolve_proc)
         else
           value
         end
@@ -133,21 +135,28 @@ module SpecForge
       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
-        ]
+        # Extract and resolve traits
+        traits = (attributes[:traits].resolve || []).map(&:to_sym)
 
-        # Insert the list size after the strategy
-        # FactoryBot.<build_strategy>_list(factory_name, list_size, **attributes)
+        # Build arguments depend on whether it's a list strategy
+        # For list strategies: FactoryBot.build_list(factory_name, count, *traits, **attributes)
+        # For other strategies: FactoryBot.build(factory_name, *traits, **attributes)
         if build_strategy.end_with?("_list")
-          build_arguments.insert(2, list_size)
+          [
+            build_strategy,
+            factory_name,
+            list_size,
+            *traits,
+            **attributes[:attributes].resolve
+          ]
+        else
+          [
+            build_strategy,
+            factory_name,
+            *traits,
+            **attributes[:attributes].resolve
+          ]
         end
-
-        build_arguments
       end
 
       #

data/lib/spec_forge/attribute/faker.rb

@@ -41,12 +41,17 @@ module SpecForge
       #
       # Creates a new faker attribute with the specified name and arguments
       #
+      # @raise [Error::InvalidFakerClassError] If the faker class doesn't exist
+      # @raise [Error::InvalidFakerMethodError] If the faker method doesn't exist
+      #
+      # @see Parameterized#initialize
+      #
       def initialize(...)
         super
 
         @faker_class, @faker_method = extract_faker_call
 
-        prepare_arguments!
+        prepare_arguments
       end
 
       #

data/lib/spec_forge/attribute/generate.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Attribute
+    #
+    # Represents an attribute that generates data structures dynamically.
+    #
+    # This class provides generation functions like `array` that can create
+    # collections of arbitrary size with evaluated values. It's useful for
+    # testing batch endpoints or generating large payloads.
+    #
+    # @example Generate an array of static values
+    #   generate.array:
+    #     size: 5
+    #     value: "test"
+    #
+    # @example Generate an array with faker values
+    #   generate.array:
+    #     size: 100
+    #     value: "{{ faker.string.alphanumeric }}"
+    #
+    # @example Generate an array with sequential indices
+    #   generate.array:
+    #     size: 3
+    #     value: "user_{{ index }}"
+    #   # Produces: ["user_0", "user_1", "user_2"]
+    #
+    # @example Combine faker with index
+    #   generate.array:
+    #     size: 10
+    #     value: "{{ faker.internet.username }}_{{ index }}"
+    #
+    class Generate < Parameterized
+      #
+      # Regular expression pattern that matches attribute keywords with this prefix.
+      # Used for identifying this attribute type during parsing.
+      # Matches case-insensitively (generate., GENERATE., Generate., etc.)
+      #
+      # @return [Regexp]
+      #
+      KEYWORD_REGEX = /^generate\./i
+
+      #
+      # The available generation methods
+      #
+      # @return [Array<String>]
+      #
+      METHODS = %w[
+        array
+      ].freeze
+
+      #
+      # The generation function name (e.g., "array")
+      #
+      # @return [String]
+      #
+      attr_reader :function
+
+      #
+      # Creates a new generate attribute with the specified function and arguments
+      #
+      # @raise [Error::InvalidGenerateFunctionError] If the function is not supported
+      #
+      # @see Parameterized#initialize
+      #
+      def initialize(...)
+        super
+
+        @function = @input.sub(KEYWORD_REGEX, "")
+        raise Error::InvalidGenerateFunctionError.new(input, METHODS) unless METHODS.include?(function)
+
+        prepare_arguments
+      end
+
+      #
+      # Returns the result of applying the generation function
+      #
+      # @return [Object] The generated value
+      #
+      def value
+        case function
+        when "array"
+          generate_array
+        end
+      end
+
+      private
+
+      #
+      # Generates an array of the specified size with evaluated values
+      #
+      # The special variable `index` (0-based) is available within `value` expressions
+      # and will shadow any existing variable with the same name during generation.
+      #
+      # @return [Array] The generated array
+      #
+      # @private
+      #
+      def generate_array
+        args = @arguments[:keyword]
+        size = args[:size].resolve
+        value_template = args[:value]
+        variables = SpecForge::Forge.context.variables
+
+        Array.new(size) do |index|
+          variables[:index] = index
+          value_template.value
+        ensure
+          variables.delete(:index)
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/attribute/literal.rb

@@ -14,20 +14,7 @@ module SpecForge
     #   active: true
     #
     class Literal < Attribute
-      # @return [Object] The literal value
-      attr_reader :value
-
-      #
-      # Creates a new literal attribute with the specified value
-      #
-      # @param input [Object] The value to store
-      #
-      def initialize(input)
-        super
-
-        @value = input
-      end
-
+      alias_method :value, :input
       alias_method :resolve, :value
     end
   end

data/lib/spec_forge/attribute/matcher.rb

@@ -62,6 +62,10 @@ module SpecForge
       #
       # Creates a new matcher attribute with the specified matcher and arguments
       #
+      # @raise [Error::UndefinedMatcherError] If the matcher is not available
+      #
+      # @see Parameterized#initialize
+      #
       def initialize(...)
         super
 
@@ -77,11 +81,11 @@ module SpecForge
             resolve_base_matcher(method)
           end
 
-        prepare_arguments!
+        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)
+        if (keyword = arguments[:keyword]) && !keyword.is_a?(Hash)
           arguments[:positional] << keyword
           arguments[:keyword] = {}
         end

data/lib/spec_forge/attribute/parameterized.rb

@@ -26,24 +26,24 @@ module SpecForge
       # Creates a new attribute instance from a hash representation
       #
       # @param hash [Hash] A hash containing the attribute name and arguments
+      # @param options [Hash] Additional options to pass to the attribute (e.g., context)
       #
       # @return [Parameterized] A new parameterized attribute instance
       #
-      def self.from_hash(hash)
+      def self.from_hash(hash, **options)
         metadata = hash.first
 
         input = metadata.first
         arguments = metadata.second
 
         case arguments
-        when ArrayLike
-          new(input, arguments)
-        when HashLike
-          # Offset for positional arguments. No support for both at this time
-          new(input, [], arguments)
+        when Array
+          new(input, positional: arguments, **options)
+        when Hash
+          new(input, keyword: arguments, **options)
         else
           # Single value
-          new(input, [arguments])
+          new(input, positional: [arguments], **options)
         end
       end
 
@@ -63,23 +63,21 @@ module SpecForge
       # Creates a new parameterized attribute with the specified arguments
       #
       # @param input [String, Symbol] The key that contains these arguments
-      # @param positional [Array] Any positional arguments
-      # @param keyword [Hash] Any keyword arguments
+      # @param options [Hash] Options including positional and keyword arguments
+      # @option options [Array] :positional Positional arguments
+      # @option options [Hash] :keyword Keyword arguments
       #
-      def initialize(input, positional = [], keyword = {})
-        super(input.to_s.downcase)
+      def initialize(...)
+        super
 
-        @arguments = {positional:, keyword:}
-      end
+        @input = @input.to_s.downcase
 
-      #
-      # 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) }
+        @arguments = {
+          positional: @options[:positional] || [],
+          keyword: @options[:keyword] || {}
+        }
+
+        @options.clear # No need to store a duplicate
       end
 
       protected
@@ -93,7 +91,7 @@ module SpecForge
       #
       # @private
       #
-      def prepare_arguments!
+      def prepare_arguments
         @arguments = Attribute.from(arguments)
       end
     end

data/lib/spec_forge/attribute/resolvable_array.rb

@@ -5,7 +5,7 @@ module SpecForge
     #
     # Represents an array that may contain attributes that need resolution
     #
-    # This delegator wraps an array and provides methods to recursively resolve
+    # This class extends 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.
     #
@@ -14,16 +14,25 @@ module SpecForge
     #   resolvable = Attribute::ResolvableArray.new(array)
     #   resolvable.resolved # => [1, 42, 3]  # assuming user_id resolves to 42
     #
-    class ResolvableArray < SimpleDelegator
+    class ResolvableArray < Array
       include Resolvable
 
+      #
+      # Creates a new ResolvableArray from the given array
+      #
+      # @param array [Array] The array to wrap
+      #
+      def initialize(array = [])
+        super
+      end
+
       #
       # Returns the underlying array
       #
-      # @return [Array] The delegated array
+      # @return [Array] The array itself
       #
       def value
-        __getobj__
+        self
       end
 
       #
@@ -37,7 +46,7 @@ module SpecForge
       #   array_attr.resolved # => ["Jane Doe"] (with result cached)
       #
       def resolved
-        value.map(&resolved_proc)
+        map(&resolved_proc)
       end
 
       #
@@ -51,7 +60,7 @@ module SpecForge
       #   array_attr.resolve # => ["John Smith"] (fresh value each time)
       #
       def resolve
-        value.map(&resolve_proc)
+        map(&resolve_proc)
       end
 
       #
@@ -69,18 +78,9 @@ module SpecForge
       #   array.resolve_as_matcher # => contain_exactly(eq("test"), match(/pattern/), eq(42))
       #
       def resolve_as_matcher
-        result = value.map(&resolve_as_matcher_proc)
+        result = 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
     end
   end
 end

data/lib/spec_forge/attribute/resolvable_hash.rb

@@ -5,7 +5,7 @@ module SpecForge
     #
     # Represents a hash that may contain attributes that need resolution
     #
-    # This delegator wraps a hash and provides methods to recursively resolve
+    # This class extends 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.
     #
@@ -14,16 +14,26 @@ module SpecForge
     #   resolvable = Attribute::ResolvableHash.new(hash)
     #   resolvable.resolved # => {name: "John Smith", id: 123}
     #
-    class ResolvableHash < SimpleDelegator
+    class ResolvableHash < Hash
       include Resolvable
 
+      #
+      # Creates a new ResolvableHash from the given hash
+      #
+      # @param hash [Hash] The hash to wrap
+      #
+      def initialize(hash = {})
+        super()
+        merge!(hash)
+      end
+
       #
       # Returns the underlying hash
       #
-      # @return [Hash] The delegated hash
+      # @return [Hash] The hash itself
       #
       def value
-        __getobj__
+        self
       end
 
       #
@@ -37,7 +47,7 @@ module SpecForge
       #   hash_attr.resolved # => {name: "Jane Doe"} (with result cached)
       #
       def resolved
-        value.transform_values(&resolved_proc)
+        transform_values(&resolved_proc)
       end
 
       #
@@ -51,7 +61,7 @@ module SpecForge
       #   hash_attr.resolve # => {name: "John Smith"} (fresh value each time)
       #
       def resolve
-        value.transform_values(&resolve_proc)
+        transform_values(&resolve_proc)
       end
 
       #
@@ -69,18 +79,9 @@ module SpecForge
       #   hash.resolve_as_matcher # => include("name" => eq("Test"), "age" => eq(42))
       #
       def resolve_as_matcher
-        result = value.transform_values(&resolve_as_matcher_proc)
+        result = 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
     end
   end
 end

data/lib/spec_forge/attribute/resolvable_struct.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Attribute
+    #
+    # Wraps struct-like objects (Struct, Data, OpenStruct) to make them resolvable
+    #
+    # Provides resolution capabilities for struct-like objects, allowing their
+    # values to be resolved recursively while maintaining the original struct type.
+    #
+    class ResolvableStruct < SimpleDelegator
+      include Resolvable
+
+      #
+      # Returns the wrapped struct object
+      #
+      # @return [Struct, Data, OpenStruct] The underlying struct-like object
+      #
+      def value
+        __getobj__
+      end
+
+      #
+      # Returns the struct with all values fully resolved and cached
+      #
+      # @return [Struct, Data, OpenStruct] A new struct-like object with resolved values
+      #
+      def resolved
+        hash = value.to_h.transform_values(&resolved_proc)
+        to_structlike(hash)
+      end
+
+      #
+      # Returns the struct with all values resolved (not cached)
+      #
+      # @return [Struct, Data, OpenStruct] A new struct-like object with resolved values
+      #
+      def resolve
+        hash = value.to_h.transform_values(&resolve_proc)
+        to_structlike(hash)
+      end
+
+      #
+      # Converts the struct's values into RSpec matchers
+      #
+      # @return [RSpec::Matchers::BuiltIn::BaseMatcher] An RSpec matcher for the struct
+      #
+      def resolve_as_matcher
+        result = value.to_h.transform_values(&resolve_as_matcher_proc)
+        Attribute::Literal.new(result).resolve_as_matcher
+      end
+
+      private
+
+      def to_structlike(hash)
+        case value
+        when OpenStruct
+          hash.to_ostruct
+        when Data
+          hash.to_istruct
+        else
+          hash.to_struct
+        end
+      end
+    end
+  end
+end