spec_forge 0.7.1 → 1.0.0

data/lib/spec_forge/attribute/template.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Attribute
+    #
+    # Handles string interpolation with {{ }} template syntax
+    #
+    # Parses strings containing {{ variable }} placeholders and resolves them
+    # at runtime by looking up variables, faker calls, or other attribute types.
+    #
+    # @example Template interpolation
+    #   Template.new("Hello {{ user_name }}!")
+    #   # When resolved with user_name = "Alice": "Hello Alice!"
+    #
+    # @example Multiple templates
+    #   Template.new("/users/{{ user_id }}/posts/{{ post_id }}")
+    #
+    class Template < Attribute
+      # Regex pattern for matching {{ variable }} placeholders
+      #
+      # @return [Regexp]
+      REGEX = /\{\{\s*[\w.]+\s*\}\}/
+
+      #
+      # Creates a new template attribute by parsing placeholders
+      #
+      # @see Attribute#initialize
+      #
+      def initialize(...)
+        super
+
+        @parsed, @templates = parse_templates
+      end
+
+      #
+      # Returns the interpolated string value
+      #
+      # Replaces all {{ }} placeholders with their resolved values.
+      # If the entire string is a single placeholder, returns the value
+      # in its original type (not stringified).
+      #
+      # @return [Object] The interpolated value
+      #
+      def value
+        value =
+          @templates.each_with_object(@parsed.dup) do |(placeholder, attribute), string|
+            value = attribute.value
+
+            replacement_value =
+              case value
+              when Hash, Array
+                value.to_json
+              else
+                value.to_s
+              end
+
+            string.gsub!(placeholder, replacement_value)
+          end
+
+        if @templates.size == 1
+          placeholder, template_value = @templates.first
+          value = cast_to_type(value, template_value.value) if @parsed == placeholder
+        end
+
+        value
+      end
+
+      private
+
+      def parse_templates
+        templates = {}
+        reverse_lookup = {}
+
+        result = @input.gsub(REGEX).with_index do |match, index|
+          content = match[2..-3].strip
+
+          # We've already processed this content, use the same placeholder
+          if (placeholder = reverse_lookup[content])
+            next placeholder
+          end
+
+          attribute = Attribute.from(content, **@options)
+
+          # There is no such thing as a Literal inside a Template.
+          # This makes it significantly easier to detect variables
+          attribute = Attribute::Variable.new(content, **@options) if attribute.is_a?(Attribute::Literal)
+
+          placeholder = "⬣→SF#{index}"
+          templates[placeholder] = attribute
+          reverse_lookup[content] = placeholder
+
+          placeholder
+        end
+
+        [result, templates]
+      end
+
+      def cast_to_type(input, template_value)
+        case template_value
+        when Integer
+          input.to_i
+        when Float
+          input.to_f
+        when TrueClass, FalseClass
+          input == "true"
+        when Array
+          input.to_a
+        when Hash
+          input.to_h
+        when String
+          input
+        else
+          template_value # Matchers, etc.
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/attribute/transform.rb

@@ -5,16 +5,12 @@ module SpecForge
     #
     # 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.
+    # This class provides transformation functions 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
+    # Note: String concatenation is handled via string interpolation ({{ }}) syntax
+    # rather than transformation functions.
     #
     class Transform < Parameterized
       #
@@ -30,24 +26,27 @@ module SpecForge
       #
       # @return [Array<String>]
       #
-      TRANSFORM_METHODS = %w[
-        join
-      ].freeze
+      TRANSFORM_METHODS = %w[].freeze
 
+      # @return [String] The transformation function name
       attr_reader :function
 
       #
       # Creates a new transform attribute with the specified function and arguments
       #
+      # @raise [Error::InvalidTransformFunctionError] If the function is not supported
+      #
+      # @see Parameterized#initialize
+      #
       def initialize(...)
         super
 
         # Remove prefix
         @function = @input.sub("transform.", "")
 
-        raise Error::InvalidTransformFunctionError, input unless TRANSFORM_METHODS.include?(function)
+        raise Error::InvalidTransformFunctionError.new(input, TRANSFORM_METHODS) unless TRANSFORM_METHODS.include?(function)
 
-        prepare_arguments!
+        prepare_arguments
       end
 
       #
@@ -56,11 +55,7 @@ module SpecForge
       # @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
-        end
+        # Noop
       end
     end
   end

data/lib/spec_forge/attribute/variable.rb

@@ -3,57 +3,57 @@
 module SpecForge
   class Attribute
     #
-    # Represents an attribute that references a variable
+    # Represents a variable reference in a template
     #
-    # This class allows referencing variables defined in the test context.
-    # It supports chained access to methods and properties of variable values.
+    # Variables are resolved at runtime by looking up values stored in the
+    # current execution context. Supports dot notation for accessing nested
+    # properties (e.g., "response.body.id").
     #
-    # @example Basic usage in YAML
-    #   user_id: variables.user.id
-    #   company_name: variables.company.name
+    # @example Simple variable
+    #   Variable.new("user_id")  # Looks up :user_id in context
     #
-    # @example Nested access in YAML
-    #   post_author: variables.post.comments.first.author.name
+    # @example Nested access
+    #   Variable.new("response.body.token")  # response[:body][:token]
     #
     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
+      # Creates a new variable attribute
       #
-      # @raise [Error::MissingVariableError] If the variable is not found
-      # @raise [Error::InvalidTypeError] If variables is not a hash
+      # @param input [String] The variable path (e.g., "user_id", "response.body.id")
       #
-      def bind_variables(variables)
-        if !Type.hash?(variables)
-          raise Error::InvalidTypeError.new(variables, Hash, for: "'variables'")
-        end
+      def initialize(...)
+        super
 
-        # Don't nil check here.
-        raise Error::MissingVariableError, variable_name unless variables.key?(variable_name)
+        # Unset the keyword to keep chainable from displaying it in error messages
+        @keyword = nil
 
-        @variable = variables[variable_name]
+        sections = @input.split(".")
+        @header = sections.first&.to_sym
+        @invocation_chain = sections[1..] || []
       end
 
       #
-      # Returns the base object for the variable chain
+      # Returns the base object for this variable from the current context
       #
-      # @return [Object] The variable value
+      # Looks up the variable name in the current Forge context's variables.
+      # Raises an error if the variable is not defined.
+      #
+      # @return [Object] The value stored under this variable name
+      #
+      # @raise [Error::MissingVariableError] If the variable is not defined
       #
       def base_object
-        @variable || bind_variables(SpecForge.context.variables)
+        variables = @options[:context] || Forge.context&.variables || {}
+
+        if !variables.key?(variable_name)
+          raise Error::MissingVariableError.new(variable_name, available_variables: variables.keys)
+        end
+
+        variables[variable_name]
       end
     end
   end

data/lib/spec_forge/attribute.rb

@@ -1,10 +1,5 @@
 # frozen_string_literal: true
 
-# Need to be first
-require_relative "attribute/parameterized"
-require_relative "attribute/chainable"
-require_relative "attribute/resolvable"
-
 module SpecForge
   #
   # Base class for all attribute types in SpecForge.
@@ -21,50 +16,37 @@ module SpecForge
   #   user_id: variables.user.id           # A variable reference
   #
   class Attribute
-    include Resolvable
-
-    #
-    # Binds variables to Attribute objects
-    #
-    # @param input [Array, Hash, Attribute] The input to loop through or bind to
-    # @param variables [Hash] Any variables to available to assign
-    #
-    # @return [Array, Hash, Attribute] The input with bounded variables
-    #
-    def self.bind_variables(input, variables = {})
-      case input
-      when ArrayLike
-        input.each { |v| v.bind_variables(variables) }
-      when HashLike
-        input.each_value { |v| v.bind_variables(variables) }
-      when Attribute
-        input.bind_variables(variables)
-      end
-
-      input
+    class << self
+      include Resolvable
     end
 
+    include Resolvable
+
     #
     # Creates an Attribute instance based on the input value's type and content.
     # Recursively converts Array and Hash
     #
     # @param value [Object] The input value to convert into an Attribute
+    # @param options [Hash] Additional options passed to attribute constructors
+    # @option options [Hash] :context Custom variable context for resolution
     #
     # @return [Attribute] A new Attribute instance of the appropriate subclass
     #
-    def self.from(value)
+    def self.from(value, **options)
       case value
       when String
-        from_string(value)
-      when HashLike
-        from_hash(value)
-      when Attribute
+        from_string(value, **options)
+      when Hash
+        from_hash(value, **options)
+      when Attribute, ResolvableArray, ResolvableHash, ResolvableStruct
         value
-      when ArrayLike
-        array = value.map { |v| Attribute.from(v) }
-        Attribute::ResolvableArray.new(array)
+      when Array
+        array = value.map { |v| Attribute.from(v, **options) }
+        ResolvableArray.new(array)
+      when Struct, Data, OpenStruct
+        ResolvableStruct.new(value)
       else
-        Literal.new(value)
+        Literal.new(value, **options)
       end
     end
 
@@ -72,59 +54,63 @@ module SpecForge
     # Creates an Attribute instance from a string
     #
     # @param string [String] The input string
+    # @param options [Hash] Additional options passed to attribute constructors
+    # @option options [Hash] :context Custom variable context for resolution
     #
     # @return [Attribute]
     #
     # @private
     #
-    def self.from_string(string)
+    def self.from_string(string, **options)
       klass =
         case string
+        when Template::REGEX
+          Template
+        when Environment::KEYWORD_REGEX
+          Environment
         when Factory::KEYWORD_REGEX
           Factory
         when Faker::KEYWORD_REGEX
           Faker
-        when Global::KEYWORD_REGEX
-          Global
         when Matcher::KEYWORD_REGEX
           Matcher
         when Regex::KEYWORD_REGEX
           Regex
-        when Store::KEYWORD_REGEX
-          Store
-        when Variable::KEYWORD_REGEX
-          Variable
         else
           Literal
         end
 
-      klass.new(string)
+      klass.new(string, **options)
     end
 
     #
     # Creates an Attribute instance from a hash
     #
     # @param hash [Hash] The input hash
+    # @param options [Hash] Additional options passed to attribute constructors
+    # @option options [Hash] :context Custom variable context for resolution
     #
     # @return [Attribute]
     #
     # @private
     #
-    def self.from_hash(hash)
+    def self.from_hash(hash, **options)
       # Determine if the hash is an expanded macro call
       has_macro = ->(h, regex) { h.any? { |k, _| k.match?(regex) } }
 
       if has_macro.call(hash, Transform::KEYWORD_REGEX)
-        Transform.from_hash(hash)
+        Transform.from_hash(hash, **options)
+      elsif has_macro.call(hash, Generate::KEYWORD_REGEX)
+        Generate.from_hash(hash, **options)
       elsif has_macro.call(hash, Faker::KEYWORD_REGEX)
-        Faker.from_hash(hash)
+        Faker.from_hash(hash, **options)
       elsif has_macro.call(hash, Matcher::KEYWORD_REGEX)
-        Matcher.from_hash(hash)
+        Matcher.from_hash(hash, **options)
       elsif has_macro.call(hash, Factory::KEYWORD_REGEX)
-        Factory.from_hash(hash)
+        Factory.from_hash(hash, **options)
       else
-        hash = hash.transform_values { |v| Attribute.from(v) }
-        Attribute::ResolvableHash.new(hash)
+        hash = hash.transform_values { |v| Attribute.from(v, **options) }
+        ResolvableHash.new(hash)
       end
     end
 
@@ -139,9 +125,13 @@ module SpecForge
     # Creates a new attribute
     #
     # @param input [Object] The original input value
+    # @param options [Hash] Additional options for attribute behavior
+    # @option options [Hash] :context Custom variable context for resolution,
+    #   bypassing Forge.context lookup
     #
-    def initialize(input)
+    def initialize(input, **options)
       @input = input
+      @options = options
     end
 
     #
@@ -216,56 +206,41 @@ 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
     end
 
     #
-    # Converts this attribute to an appropriate RSpec matcher.
-    # Handles different types of values by creating the right matcher type:
-    # - Arrays become contain_exactly matchers
-    # - Hashes become include matchers
-    # - Regexp become match matchers
-    # - Existing matchers are passed through
-    # - Other values become eq matchers
-    #
-    # This method is crucial for nested matcher structures and compound matchers
-    # like matcher.and that require all values to be proper matchers.
-    #
-    # @return [RSpec::Matchers::BuiltIn::BaseMatcher] A matcher representing this attribute
+    # Converts the resolved value into an RSpec matcher
     #
-    # @example Converting different values to matchers
-    #   literal_attr = Attribute::Literal.new("hello")
-    #   literal_attr.resolve_as_matcher # => eq("hello")
+    # Transforms the attribute's resolved value into an appropriate RSpec matcher
+    # for use in expectations. Handles arrays, hashes, matchers, regexes, and
+    # literal values differently to produce the correct matcher type.
     #
-    #   array_attr = Attribute::ResolvableArray.new([1, 2, 3])
-    #   array_attr.resolve_as_matcher # => contain_exactly(eq(1), eq(2), eq(3))
-    #
-    #   hash_attr = Attribute::ResolvableHash.new({name: "Test"})
-    #   hash_attr.resolve_as_matcher # => include("name" => eq("Test"))
+    # @return [RSpec::Matchers::BuiltIn::BaseMatcher] An RSpec matcher for the value
     #
     def resolve_as_matcher
       methods = Attribute::Matcher::MATCHER_METHODS
 
       case resolved
-      when Array, ArrayLike
+      when Array
         resolved_array = resolved.map(&resolve_as_matcher_proc)
 
         if resolved_array.size > 0
-          methods.contain_exactly(*resolved_array)
+          resolved_array
         else
           methods.eq([])
         end
-      when Hash, HashLike
+      when Hash
         resolved_hash = resolved.transform_values(&resolve_as_matcher_proc).stringify_keys
 
         if resolved_hash.size > 0
-          methods.include(**resolved_hash)
+          resolved_hash
         else
           methods.eq({})
         end
@@ -279,26 +254,5 @@ module SpecForge
         methods.eq(resolved)
       end
     end
-
-    #
-    # Used to bind variables to self or any sub attributes
-    #
-    # @param variables [Hash] A hash of variable attributes
-    #
-    def bind_variables(variables)
-    end
   end
 end
-
-# Order doesn't matter
-require_relative "attribute/factory"
-require_relative "attribute/faker"
-require_relative "attribute/global"
-require_relative "attribute/literal"
-require_relative "attribute/matcher"
-require_relative "attribute/regex"
-require_relative "attribute/resolvable_array"
-require_relative "attribute/resolvable_hash"
-require_relative "attribute/store"
-require_relative "attribute/transform"
-require_relative "attribute/variable"

data/lib/spec_forge/blueprint.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module SpecForge
+  #
+  # Represents a loaded blueprint containing a sequence of test steps
+  #
+  # A Blueprint is the runtime representation of a YAML blueprint file.
+  # It contains metadata about the file and an ordered list of Step objects
+  # ready for execution.
+  #
+  # @example
+  #   blueprint = Blueprint.new(
+  #     file_path: Pathname.new("spec_forge/blueprints/users.yml"),
+  #     name: "users",
+  #     steps: [{name: "Create user", request: {...}}]
+  #   )
+  #
+  class Blueprint < Data.define(:file_path, :file_name, :hooks, :name, :steps)
+    def initialize(file_path:, name:, steps: [], hooks: {})
+      file_name = file_path.basename.to_s
+      steps = steps.map { |s| Step.new(**s) }
+      hooks = Step::Call.wrap_hooks(hooks)
+
+      super(file_path:, file_name:, hooks:, name:, steps:,)
+    end
+  end
+end

data/lib/spec_forge/cli/docs/generate.rb

@@ -12,19 +12,26 @@ module SpecForge
       #
       module Generate
         #
-        # Generates OpenAPI documentation and writes it to disk
+        # Generates OpenAPI documentation from blueprint test results
         #
-        # Runs the documentation generation pipeline: executes tests, extracts
-        # endpoint data, generates OpenAPI spec, validates it, and writes the
+        # Runs blueprints with the configured verbosity level, extracts endpoint
+        # data, validates the specification (unless skipped), and writes the
         # output file in the specified format.
         #
-        # @return [Pathname] The path to the generated documentation file
+        # @param base_path [String, Pathname, nil] Optional base path for blueprints
         #
-        def generate_documentation
-          generator = Documentation::Generators::OpenAPI["3.0"]
-          output = generator.generate(use_cache: !options.fresh)
+        # @return [Pathname] Path to the generated documentation file
+        #
+        def generate_documentation(base_path: nil)
+          document = Documentation::Builder.create_document!(
+            base_path:,
+            use_cache: !options.fresh,
+            verbosity_level: determine_verbosity_level
+          )
+          generator_class = Documentation::OpenAPI["3.0"]
+          output = generator_class.new(document).generate
 
-          generator.validate!(output) unless options.skip_validation
+          generator_class.validate!(output) unless options.skip_validation
 
           # Determine output format and path
           file_format = determine_file_format
@@ -66,6 +73,19 @@ module SpecForge
             SpecForge.openapi_path.join("generated", "openapi.#{extension}")
           end
         end
+
+        #
+        # Determines verbosity level from command options
+        #
+        # @return [Integer] Verbosity level (0-3)
+        #
+        def determine_verbosity_level
+          return 3 if options.trace
+          return 2 if options.debug
+          return 1 if options.verbose
+
+          0
+        end
       end
     end
   end

data/lib/spec_forge/cli/docs.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "docs/generate"
-
 module SpecForge
   class CLI
     #
@@ -60,6 +58,9 @@ module SpecForge
       option "--format=FORMAT", "Output format: yml/yaml or json (default: yml)"
       option "--output=PATH", "Full file path for generated documentation"
       option "--skip-validation", "Skip OpenAPI specification validation during generation"
+      option "--verbose", "Show detailed step execution (verbosity level 1)"
+      option "--debug", "Show full request/response for failures (verbosity level 2)"
+      option "--trace", "Show everything for all steps (verbosity level 3)"
 
       #
       # Generates OpenAPI documentation from tests
@@ -86,6 +87,8 @@ module SpecForge
           Your OpenAPI specification is valid and ready to use.
           Output written to: #{file_path.relative_path_from(SpecForge.forge_path)}
         STRING
+      rescue NoBlueprintsError => e
+        puts e.message
       end
     end
   end

data/lib/spec_forge/cli/init.rb

@@ -17,7 +17,7 @@ module SpecForge
         Creates the SpecForge project structure.
 
         Sets up:
-          • spec_forge/specs/ for test files
+          • spec_forge/blueprints/ for test files
           • spec_forge/factories/ for test data (optional)
           • spec_forge/openapi/ for documentation config (optional)
           • forge_helper.rb for configuration
@@ -27,8 +27,8 @@ module SpecForge
       option "--skip-factories", "Skip generating the \"factories\" directory"
 
       #
-      # Creates the "spec_forge", "spec_forge/factories", and "spec_forge/specs" directories
-      # Also creates the "spec_forge.rb" initialization file
+      # Creates the "spec_forge", "spec_forge/factories", and "spec_forge/blueprints" directories
+      # Also creates the "forge_helper.rb" initialization file
       #
       def call
         initialize_forge
@@ -39,7 +39,7 @@ module SpecForge
 
       def initialize_forge
         base_path = SpecForge.forge_path
-        actions.empty_directory(base_path.join("specs"))
+        actions.empty_directory(base_path.join("blueprints"))
         actions.empty_directory(base_path.join("factories")) unless options.skip_factories
         actions.template("forge_helper.rb.tt", base_path.join("forge_helper.rb"))
       end