spec_forge 0.7.1 → 1.0.0

data/lib/spec_forge/step/expect.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Step
+    #
+    # Represents an expectation block within a step
+    #
+    # Holds the expected status, headers, and body (raw or JSON) that
+    # will be validated against the HTTP response. Provides methods
+    # to convert expectations into RSpec matchers.
+    #
+    class Expect < Data.define(:status, :headers, :raw, :json)
+      def initialize(status: nil, headers: nil, raw: nil, json: nil)
+        super(
+          status: status ? Attribute.from(status) : nil,
+          headers: extract_headers(headers),
+          raw: raw ? Attribute.from(raw) : nil,
+          json: extract_json(json)
+        )
+      end
+
+      #
+      # Returns the total number of assertions in this expectation
+      #
+      # Counts all non-blank assertions (status, headers, raw, JSON size/schema/content).
+      #
+      # @return [Integer] Number of assertions
+      #
+      def size
+        [
+          status,
+          headers,
+          raw,
+          json[:size],
+          json[:schema],
+          json[:content]
+        ].compact_blank.size
+      end
+
+      #
+      # Returns the status code as an RSpec matcher
+      #
+      # @return [RSpec::Matchers::BuiltIn::BaseMatcher, nil] Status matcher or nil
+      #
+      def status_matcher
+        return if status.blank?
+
+        status.resolve_as_matcher
+      end
+
+      #
+      # Returns headers as a hash of matchers
+      #
+      # @return [Hash, nil] Header matchers keyed by header name
+      #
+      def headers_matcher
+        return if headers.blank?
+
+        headers.transform_values(&Attribute.resolve_as_matcher_proc)
+      end
+
+      #
+      # Returns the JSON size matcher
+      #
+      # @return [RSpec::Matchers::BuiltIn::BaseMatcher, nil] Size matcher or nil
+      #
+      def json_size_matcher
+        json[:size]&.resolve_as_matcher
+      end
+
+      #
+      # Returns the JSON schema structure for validation
+      #
+      # @return [Hash, nil] The schema definition or nil
+      #
+      def json_schema
+        json[:schema]
+      end
+
+      #
+      # Returns the JSON content matcher
+      #
+      # @return [RSpec::Matchers::BuiltIn::BaseMatcher, nil] Content matcher or nil
+      #
+      def json_content_matcher
+        json[:content]&.resolve_as_matcher
+      end
+
+      private
+
+      def extract_headers(headers)
+        return if headers.blank?
+
+        headers.stringify_keys.transform_values { |v| Attribute.from(v) }
+      end
+
+      def extract_json(json)
+        return {} if json.blank?
+
+        output = {}
+
+        output[:content] = Attribute.from(json[:content]) if json[:content]
+        output[:size] = Attribute.from(json[:size]) if json[:size]
+        output[:schema] = json[:schema] || json[:shape]
+
+        output
+      end
+    end
+  end
+end

data/lib/spec_forge/step/source.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Step
+    #
+    # Represents the source location of a step in a blueprint file
+    #
+    # Tracks which file and line number a step came from, which is
+    # useful for error messages and debugging output.
+    #
+    class Source < Data.define(:file_name, :line_number)
+      #
+      # Returns a formatted string representation of the source location
+      #
+      # @return [String] Format: "file_name:line_number"
+      #
+      def to_s
+        "#{file_name}:#{line_number}"
+      end
+    end
+  end
+end

data/lib/spec_forge/step.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module SpecForge
+  #
+  # Represents a single executable step within a blueprint
+  #
+  # Steps are the fundamental unit of execution in SpecForge. Each step
+  # can contain a request, expectations, store operations, callbacks,
+  # and debug triggers. Steps are immutable value objects created from
+  # normalized YAML data.
+  #
+  class Step < Data.define(
+    :name,
+    :calls,
+    :debug,
+    :documentation,
+    :expects,
+    :hooks,
+    :included_by,
+    :request,
+    :source,
+    :store,
+    :tags
+  )
+    # @return [Boolean] Whether this step uses callbacks
+    # @return [Boolean] Whether debug mode is enabled for this step
+    # @return [Boolean] Whether this step registers callback hooks
+    # @return [Boolean] Whether this step has expectations
+    # @return [Boolean] Whether this step has a request action
+    # @return [Boolean] Whether this step has store operations
+    attr_predicate :calls, :debug, :expects, :hooks, :request, :store
+
+    #
+    # Creates a new Step from normalized YAML data
+    #
+    # Transforms raw step data into structured objects for execution.
+    # Converts requests, expectations, hooks, and other attributes
+    # into their runtime representations.
+    #
+    # @param step [Hash] Normalized step data from YAML
+    #
+    def initialize(**step)
+      step[:calls] = transform_calls(step[:calls])
+      step[:debug] = step[:debug] == true
+      step[:documentation] ||= nil
+      step[:expects] = transform_expect(step[:expects])
+      step[:hooks] = transform_hooks(step[:hooks])
+      step[:included_by] = transform_source(step[:included_by])
+      step[:request] = transform_request(step[:request])
+      step[:source] = transform_source(step[:source])
+      step[:store] = transform_store(step[:store])
+      step[:tags] ||= nil
+
+      super(step)
+    end
+
+    private
+
+    def transform_source(source)
+      return if source.blank?
+
+      Source.new(file_name: source[:file_name], line_number: source[:line_number])
+    end
+
+    def transform_calls(calls)
+      return if calls.blank?
+
+      calls.map { |call| Call.new(callback_name: call[:name], arguments: call[:arguments]) }
+    end
+
+    def transform_request(input)
+      return if input.blank?
+
+      request = {}
+
+      if (url = input[:base_url]) && url.present?
+        request[:base_url] = Attribute.from(url)
+      end
+
+      if (url = input[:url]) && url.present?
+        request[:url] = Attribute.from(url)
+      end
+
+      if (verb = input[:http_verb]) && verb.present?
+        request[:http_verb] = verb
+      end
+
+      headers = (input[:headers] || {}).transform_keys(&:downcase)
+
+      if input[:json].present?
+        headers["content-type"] ||= "application/json"
+      elsif headers.present?
+        headers["content-type"] ||= "text/plain"
+      end
+
+      if headers.present?
+        request[:headers] = Attribute.from(headers)
+      end
+
+      if (query = input[:query]) && query.present?
+        request[:query] = Attribute.from(query)
+      end
+
+      if (json = input[:json]) && json.present?
+        request[:body] = Attribute.from(json)
+      elsif (raw = input[:raw]) && raw.present?
+        request[:body] = Attribute.from(raw)
+      end
+
+      HTTP::Request.new(**request)
+    end
+
+    def transform_expect(expects)
+      return if expects.blank?
+
+      expects.map { |e| Expect.new(**e) }
+    end
+
+    def transform_store(store)
+      return if store.blank?
+
+      store.transform_values { |v| Attribute.from(v) }
+    end
+
+    def transform_hooks(hooks)
+      Step::Call.wrap_hooks(hooks)
+    end
+  end
+end

data/lib/spec_forge/type.rb

@@ -2,76 +2,125 @@
 
 module SpecForge
   #
-  # Provides helper methods for checking types
-  # Useful for working with both regular objects and Attribute delegators
+  # Utilities for converting between Ruby classes and type strings
+  #
+  # Type provides bidirectional conversion between Ruby types (Integer, String, etc.)
+  # and their string representations ("integer", "string", etc.) used in YAML
+  # schema definitions. Supports nullable types with the "?" prefix and optional
+  # fields with the "*" prefix.
   #
   module Type
-    #
-    # Checks if the object is a Hash or a ResolvableHash delegator
-    #
-    # @param object [Object] The object to check
-    #
-    # @return [Boolean] True if the object is a hash-like structure
-    #
-    def self.hash?(object)
-      object.is_a?(Hash) || object.is_a?(Attribute::ResolvableHash)
-    end
+    class << self
+      # Mapping from Ruby classes to type string names
+      #
+      # @return [Hash{Class => String}]
+      CLASS_TO_STRING = {
+        Integer => "integer",
+        Float => "float",
+        String => "string",
+        Hash => "hash",
+        Array => "array",
+        TrueClass => "boolean",
+        FalseClass => "boolean",
+        NilClass => "null"
+      }.freeze
 
-    #
-    # Checks if the object is an Array or a ResolvableArray delegator
-    #
-    # @param object [Object] The object to check
-    #
-    # @return [Boolean] True if the object is an array-like structure
-    #
-    def self.array?(object)
-      object.is_a?(Array) || object.is_a?(Attribute::ResolvableArray)
-    end
-  end
-end
+      # Mapping from type string names to Ruby classes
+      #
+      # @return [Hash{String => Array<Class>}]
+      STRING_TO_CLASS = {
+        "string" => [String],
+        "number" => [Integer, Float],
+        "numeric" => [Integer, Float],
+        "integer" => [Integer],
+        "float" => [Float],
+        "bool" => [TrueClass, FalseClass],
+        "boolean" => [TrueClass, FalseClass],
+        "array" => [Array],
+        "hash" => [Hash],
+        "object" => [Hash],
+        "null" => [NilClass],
+        "nil" => [NilClass]
+      }.freeze
 
-#
-# Represents Hash/ResolvableHash in a form that can be used in a case statement
-# Allows for type switching on hash-like objects
-#
-# @example
-#   case value
-#   when HashLike
-#     # Handle hash-like objects
-#   end
-#
-class HashLike
-  #
-  # Provides custom type matching for use in case statements
-  #
-  # @param object [Object] The object to check against the type
-  #
-  # @return [Boolean] Whether the object matches the type
-  #
-  def self.===(object)
-    SpecForge::Type.hash?(object)
-  end
-end
+      #
+      # Converts a type string to a hash containing Ruby classes and optional flag
+      #
+      # Supports nullable types with the "?" prefix (e.g., "?string") and optional
+      # fields with the "*" prefix (e.g., "*string"). Flags can be combined in any
+      # order (e.g., "*?string" or "?*string").
+      #
+      # @param input [String] The type string (e.g., "integer", "?string", "*?boolean")
+      #
+      # @return [Hash] Hash with :types (Array<Class>) and :optional (Boolean)
+      #
+      # @raise [ArgumentError] If input is nil or unknown type
+      #
+      # @example
+      #   Type.from_string("integer")   # => { types: [Integer], optional: false }
+      #   Type.from_string("?string")   # => { types: [String, NilClass], optional: false }
+      #   Type.from_string("*string")   # => { types: [String], optional: true }
+      #   Type.from_string("*?string")  # => { types: [String, NilClass], optional: true }
+      #
+      def from_string(input)
+        raise ArgumentError, "Input is nil" if input.nil?
 
-#
-# Represents Array/ResolvableArray in a form that can be used in a case statement
-# Allows for type switching on array-like objects
-#
-# @example
-#   case value
-#   when ArrayLike
-#     # Handle array-like objects
-#   end
-#
-class ArrayLike
-  #
-  # Provides custom type matching for use in case statements
-  #
-  # @param object [Object] The object to check against the type
-  #
-  # @return [Boolean] Whether the object matches the type
-  #
-  def self.===(object)
-    SpecForge::Type.array?(object)
+        # Extract flags from start of string
+        potential_flags = input[..2]
+        optional = potential_flags.include?("*")
+        nullable = potential_flags.include?("?")
+
+        if optional || nullable
+          offset = [optional, nullable].count(true)
+          input = input[offset..]
+        end
+
+        types = STRING_TO_CLASS[input.downcase]&.dup
+
+        if types.nil?
+          raise ArgumentError,
+            "Unknown type: #{input.in_quotes}. Valid types: string, number/numeric, integer, float, boolean/bool, array, hash/object, null/nil"
+        end
+
+        # Add NilClass if nullable
+        types << NilClass if nullable
+        types.uniq!
+
+        {types:, optional:}
+      end
+
+      #
+      # Converts Ruby classes to their type string representation
+      #
+      # Handles nullable types (includes NilClass) by adding "?" prefix.
+      # Normalizes boolean types (TrueClass/FalseClass) to single "boolean".
+      #
+      # @param types [Array<Class>] One or more Ruby classes
+      #
+      # @return [String, Array<String>] Type string or array if multiple distinct types
+      #
+      # @example
+      #   Type.to_string(Integer)                    # => "integer"
+      #   Type.to_string(String, NilClass)           # => "?string"
+      #   Type.to_string(TrueClass, FalseClass)      # => "boolean"
+      #   Type.to_string(Integer, String)            # => ["integer", "string"]
+      #
+      def to_string(*types)
+        types = types.map { |k| CLASS_TO_STRING[k] }
+
+        null = CLASS_TO_STRING[NilClass] # Just in case the name changes
+        if types.delete(null)
+          # We removed the nil above, no other types means this is just nil. No need to continue processing
+          return null if types.empty?
+
+          types.map! { |t| "?#{t}" }
+        end
+
+        # Remove "boolean", "boolean" that happens with TrueClass/FalseClass
+        types.uniq!
+
+        (types.size == 1) ? types.first : types
+      end
+    end
   end
 end

data/lib/spec_forge/version.rb

@@ -4,5 +4,5 @@ module SpecForge
   #
   # Current version of SpecForge
   #
-  VERSION = "0.7.1"
+  VERSION = "1.0.0"
 end

data/lib/spec_forge.rb

@@ -13,58 +13,50 @@ require "faraday"
 require "mime/types"
 require "openapi3_parser"
 require "pathname"
+require "pastel"
 require "rspec"
 require "sem_version"
 require "singleton"
 require "thor"
 require "webrick"
 require "yaml"
+require "zeitwerk"
+
+require_path = ->(path) { Dir.glob(path).sort.each { |p| require p } }
+
+# Require the overwrites
+root_path = Pathname.new(__dir__)
+
+core_ext_path = root_path.join("spec_forge", "core_ext")
+require_path.call(core_ext_path.join("**/*.rb"))
+
+types_path = root_path.join("spec_forge", "types")
+require_path.call(types_path.join("**/*.rb"))
+
+# Load the files
+loader = Zeitwerk::Loader.for_gem
+loader.inflector.inflect(
+  "cli" => "CLI",
+  "http" => "HTTP",
+  "openapi" => "OpenAPI",
+  "array_io" => "ArrayIO"
+)
+
+# spec_forge/forge/actions/*.rb -> SpecForge::Forge::*
+loader.collapse(root_path.join("spec_forge", "forge", "actions"))
+
+# spec_forge/types/*.rb -> SpecForge::*
+loader.collapse(types_path)
+
+# Loaded manually above
+loader.ignore(core_ext_path)
+loader.ignore(types_path)
+
+loader.setup
+# loader.eager_load(force: true)
 
-#
-# SpecForge: Write expressive API tests in YAML with the power of RSpec matchers
-#
-# SpecForge is a testing framework that allows writing API tests in a YAML format
-# that reads like documentation. It combines the readability of YAML with the
-# power of RSpec matchers, Faker data generation, and FactoryBot test objects.
-#
-# @example Basic spec in YAML
-#   get_user:
-#     path: /users/1
-#     expectations:
-#     - expect:
-#         status: 200
-#         json:
-#           name: kind_of.string
-#           email: /@/
-#
-# @example Running specs
-#   # Run all specs
-#   SpecForge.run
-#
-#   # Run specific file
-#   SpecForge.run(file_name: "users")
-#
-#   # Run specific spec
-#   SpecForge.run(file_name: "users", spec_name: "create_user")
-#
 module SpecForge
   class << self
-    #
-    # Loads all factories and specs and runs the tests with optional filtering
-    #
-    # This is the main entry point for running SpecForge tests. It loads the
-    # forge_helper.rb file if it exists, configures the environment, loads
-    # factories and specs, and runs the tests through RSpec.
-    #
-    # @param file_name [String, nil] Optional name of spec file to run
-    # @param spec_name [String, nil] Optional name of spec to run
-    # @param expectation_name [String, nil] Optional name of expectation to run
-    #
-    def run(file_name: nil, spec_name: nil, expectation_name: nil)
-      forges = Runner.prepare(file_name:, spec_name:, expectation_name:)
-      Runner.run(forges, exit_on_finish: true)
-    end
-
     #
     # Returns the directory root for the working directory
     #
@@ -83,6 +75,15 @@ module SpecForge
       @forge_path ||= root.join("spec_forge")
     end
 
+    #
+    # Returns SpecForge's blueprints directory
+    #
+    # @return [Pathname] The spec_forge blueprints directory path
+    #
+    def blueprints_path
+      @blueprints_path ||= forge_path.join("blueprints")
+    end
+
     #
     # Returns SpecForge's openapi directory
     #
@@ -132,68 +133,5 @@ module SpecForge
         cleaner
       end
     end
-
-    #
-    # Returns the current execution context
-    #
-    # @return [Context] The current context object
-    #
-    def context
-      @context ||= Context.new
-    end
-
-    #
-    # Registers a callback for a specific test lifecycle event
-    # Allows custom code execution at specific points during test execution
-    #
-    # @param name [Symbol, String] A unique identifier for this callback
-    # @yield A block to execute when the callback is triggered
-    # @yieldparam context [Object] An object containing context-specific state data, depending
-    #   on which hook the callback is triggered from.
-    #
-    # @return [Proc] The registered callback
-    #
-    # @example Registering a custom debug handler
-    #   SpecForge.register_callback(:clean_database) do |context|
-    #     DatabaseCleaner.clean
-    #   end
-    #
-    def register_callback(name, &)
-      Callbacks.register(name, &)
-    end
-
-    #
-    # Generates a unique ID for an object based on hash and object_id
-    #
-    # @param object [Object] The object to generate an ID for
-    #
-    # @return [String] A unique ID string
-    #
-    # @private
-    #
-    def generate_id(object)
-      "#{object.hash.abs.to_s(36)}_#{object.object_id.to_s(36)}"
-    end
   end
 end
-
-require_relative "spec_forge/attribute"
-require_relative "spec_forge/backtrace_formatter"
-require_relative "spec_forge/callbacks"
-require_relative "spec_forge/cli"
-require_relative "spec_forge/configuration"
-require_relative "spec_forge/context"
-require_relative "spec_forge/core_ext"
-require_relative "spec_forge/documentation"
-require_relative "spec_forge/error"
-require_relative "spec_forge/factory"
-require_relative "spec_forge/filter"
-require_relative "spec_forge/forge"
-require_relative "spec_forge/http"
-require_relative "spec_forge/loader"
-require_relative "spec_forge/matchers"
-require_relative "spec_forge/normalizer"
-require_relative "spec_forge/runner"
-require_relative "spec_forge/spec"
-require_relative "spec_forge/type"
-require_relative "spec_forge/version"