spec_forge 0.7.0 → 1.0.0

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].resolved.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