spec_forge 0.7.0 → 1.0.0

data/lib/spec_forge/http/client.rb

@@ -3,23 +3,19 @@
 module SpecForge
   module HTTP
     #
-    # HTTP client that executes requests and returns responses
+    # High-level HTTP client for executing requests
     #
-    # This class serves as a mediator between the test expectations
-    # and the actual HTTP backend implementation.
-    #
-    # @example Basic usage
-    #   client = HTTP::Client.new(base_url: "https://api.example.com")
-    #   response = client.call(request)
+    # Client wraps Backend and provides a simple interface for executing
+    # HTTP::Request objects and returning responses.
     #
     class Client
       #
-      # Creates a new HTTP client with configured backend
+      # Creates a new HTTP client with a backend
       #
-      # @return [Client] A new HTTP client instance
+      # @return [Client] A new client instance
       #
-      def initialize(**)
-        @backend = Backend.new(HTTP::Request.new(**))
+      def initialize
+        @backend = Backend.new
       end
 
       #
@@ -29,13 +25,14 @@ module SpecForge
       #
       # @return [Faraday::Response] The HTTP response
       #
-      def call(request)
+      def perform(request)
         @backend.public_send(
-          request.http_verb.to_s.downcase,
-          request.url,
-          headers: request.headers.resolved,
-          query: request.query.resolved,
-          body: request.body.resolved
+          request.http_verb.downcase,
+          base_url: request.base_url,
+          url: request.url.delete_prefix("/"),
+          headers: request.headers,
+          query: request.query,
+          body: request.body
         )
       end
     end

data/lib/spec_forge/http/request.rb

@@ -3,110 +3,63 @@
 module SpecForge
   module HTTP
     #
-    # The attributes used to build a Request
+    # Represents an HTTP request with all its components
     #
-    # @return [Array<Symbol>]
+    # Request is a value object that holds the URL, method, headers,
+    # query parameters, and body for an HTTP request.
     #
-    REQUEST_ATTRIBUTES = %i[
-      base_url
-      url
-      http_verb
-      content_type
-      headers
-      query
-      body
-    ].freeze
-
-    #
-    # Represents an HTTP request configuration
-    #
-    # This data object contains all the necessary information to construct
-    # an HTTP request, including URL, method, headers, query params, and body.
-    #
-    # @example Creating a request
-    #   request = HTTP::Request.new(
-    #     base_url: "https://api.example.com",
-    #     url: "/users",
-    #     http_verb: "GET",
-    #     headers: {"Content-Type" => "application/json"},
-    #     query: {page: 1},
-    #     body: {}
-    #   )
-    #
-    class Request < Data.define(*REQUEST_ATTRIBUTES)
-      #
-      # Regex that attempts to match a valid header
-      #
-      # @return [Regexp]
-      #
-      HEADER = /^[A-Z][A-Za-z0-9!-]*$/
-
+    class Request < Struct.new(:base_url, :url, :http_verb, :headers, :query, :body)
       #
-      # Creates a new Request with standardized headers and values
+      # Creates a new HTTP request with the specified options
       #
-      # @param base_url [String, nil] The base URL for the request
-      # @param url [String, nil] The path portion of the URL
-      # @param http_verb [String, Symbol, nil] The HTTP method (GET, POST, etc.)
-      # @param headers [Hash, nil] HTTP headers for the request
-      # @param query [Hash, nil] Query parameters to include
-      # @param body [Hash, nil] Request body data
+      # @param options [Hash] Request options
+      # @option options [String] :base_url The base URL for the request
+      # @option options [String] :url The URL path for the request
+      # @option options [String] :http_verb The HTTP method (defaults to "GET")
+      # @option options [Hash] :headers HTTP headers
+      # @option options [Hash] :query Query parameters
+      # @option options [Hash, String] :body Request body
       #
-      # @return [Request] A new immutable request object
+      # @return [Request] A new request instance
       #
       def initialize(**options)
-        base_url = options[:base_url] || ""
-        url = options[:url] || ""
-        http_verb = Verb.from(options[:http_verb].presence || "GET")
-        query = Attribute.from(options[:query] || {})
-        body = Attribute.from(options[:body] || {})
-        headers = normalize_headers(options[:headers] || {})
-        content_type = "application/json"
-
-        super(base_url:, url:, http_verb:, content_type:, headers:, query:, body:)
+        super(
+          base_url: options[:base_url] || "",
+          url: options[:url] || "",
+          http_verb: Verb.from(options[:http_verb].presence || "GET"),
+          headers: options[:headers] || {},
+          query: options[:query] || {},
+          body: options[:body] || {}
+        )
       end
 
       #
-      # Returns a hash representation with all attributes fully resolved
+      # Returns the Content-Type header value
       #
-      # @return [Hash] The request data with all dynamic values resolved
+      # @return [String, nil] The content type or nil if not set
       #
-      def to_h
-        hash = super.transform_values { |v| v.respond_to?(:resolved) ? v.resolved : v }
-        hash[:http_verb] = hash[:http_verb].to_s
-        hash
+      def content_type
+        headers["content-type"]
       end
 
-      private
-
       #
-      # Normalizes HTTP header keys to standard format
+      # Returns whether this request has a JSON content type
       #
-      # Converts snake_case and other formats to HTTP Header-Case format
-      # Examples:
-      #   content_type -> Content-Type
-      #   api_key -> Api-Key
+      # @return [Boolean] True if content type is application/json
       #
-      # @param headers [Hash] The headers to normalize
+      def json?
+        content_type == "application/json"
+      end
+
       #
-      # @return [Attribute::ResolvableHash] Normalized headers as attributes
+      # Converts the request to a hash with stringified verb
       #
-      # @private
+      # @return [Hash] Hash representation of the request
       #
-      def normalize_headers(headers)
-        headers =
-          headers.transform_keys do |key|
-            key = key.to_s
-
-            # If the key is already like a header, don't change it
-            if key.match?(HEADER)
-              key
-            else
-              # content_type => Content-Type
-              key.downcase.titleize.gsub(/\s+/, "-")
-            end
-          end
-
-        Attribute.from(headers)
+      def to_h
+        super.tap do |h|
+          h[:http_verb] = h[:http_verb].to_s
+        end
       end
     end
   end

data/lib/spec_forge/http/verb.rb

@@ -124,6 +124,8 @@ module SpecForge
       # @return [Verb, nil] The corresponding Verb instance, or nil if not found
       #
       def self.from(name)
+        return name if name.is_a?(Verb)
+
         VERBS[name.downcase.to_sym]
       end
 
@@ -148,6 +150,8 @@ module SpecForge
 
       alias_method :to_s, :name
 
+      delegate :downcase, to: :to_s
+
       #
       # Returns if this Verb is a DELETE
       #

data/lib/spec_forge/http.rb

@@ -104,8 +104,3 @@ module SpecForge
     end
   end
 end
-
-require_relative "http/backend"
-require_relative "http/client"
-require_relative "http/verb"
-require_relative "http/request"

data/lib/spec_forge/loader/filter.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Loader
+    #
+    # Filters blueprints and steps by path and tags
+    #
+    # Applied after step processing to reduce the set of blueprints
+    # and steps that will be executed based on CLI options.
+    #
+    class Filter
+      #
+      # Creates a new filter for the given blueprints
+      #
+      # @param blueprints [Array<Hash>] The blueprints to filter
+      #
+      # @return [Filter] A new filter instance
+      #
+      def initialize(blueprints)
+        @blueprints = blueprints
+      end
+
+      #
+      # Applies filters to the blueprints
+      #
+      # @param path [Pathname, nil] Path prefix to filter by
+      # @param tags [Array<String>] Tags that steps must have (OR logic)
+      # @param skip_tags [Array<String>] Tags that exclude steps
+      #
+      # @return [Array<Hash>] Filtered blueprints
+      #
+      def run(path: nil, tags: [], skip_tags: [])
+        filter_by_path(path)
+        filter_by_tags(tags, skip_tags)
+        remove_empty_blueprints
+
+        @blueprints
+      end
+
+      private
+
+      def filter_by_path(path)
+        return if path.blank?
+
+        base_path = SpecForge.blueprints_path
+        path = path.relative_path_from(base_path).to_s
+          .delete_suffix(".yml")
+          .delete_suffix(".yaml")
+
+        @blueprints.select! do |blueprint|
+          blueprint[:name].starts_with?(path)
+        end
+      end
+
+      def filter_by_tags(tags, skip_tags)
+        include_by_tag(tags)
+        exclude_by_tag(skip_tags)
+      end
+
+      def include_by_tag(tags)
+        return if tags.blank?
+
+        @blueprints.each do |blueprint|
+          blueprint[:steps].select! do |step|
+            step[:tags].intersect?(tags)
+          end
+        end
+      end
+
+      def exclude_by_tag(tags)
+        return if tags.blank?
+
+        @blueprints.each do |blueprint|
+          blueprint[:steps].reject! do |step|
+            step[:tags].intersect?(tags)
+          end
+        end
+      end
+
+      def remove_empty_blueprints
+        @blueprints.delete_if { |blueprint| blueprint[:steps].blank? }
+      end
+    end
+  end
+end

data/lib/spec_forge/loader/step_processor.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Loader
+    #
+    # Processes raw step hashes into normalized, flattened step arrays
+    #
+    # Handles the heavy lifting of load-time processing: normalizing step
+    # structures, expanding includes, inheriting configuration from parents,
+    # applying tags, and flattening nested hierarchies.
+    #
+    class StepProcessor
+      #
+      # Action attributes that execute behavior and cannot be combined with steps
+      #
+      ACTION_ATTRIBUTES = %i[request expects calls debug store].freeze
+
+      #
+      # Creates a new step processor for the given blueprints
+      #
+      # @param blueprints [Hash<String, Hash>] Blueprints indexed by name
+      #
+      # @return [StepProcessor] A new step processor instance
+      #
+      def initialize(blueprints)
+        @blueprints = blueprints
+
+        @global_hooks = SpecForge.configuration.hooks.transform_values do |callbacks|
+          Normalizer::Transformers.call(:normalize_callback, callbacks)
+        end
+
+        @forge_hooks = {
+          before: Set.new(@global_hooks[:before_forge]),
+          after: Set.new(@global_hooks[:after_forge])
+        }
+      end
+
+      #
+      # Processes all blueprints and returns the flattened, normalized steps
+      #
+      # Performs two passes over the blueprints:
+      # 1. Preprocessing: normalizes steps and assigns source information
+      # 2. Main processing: expands includes, inherits shared config, extracts
+      #    hooks, applies tags, and flattens nested step hierarchies
+      #
+      # @return [Array<Array<Hash>, Hash>] Tuple of processed blueprints and forge hooks
+      #
+      def run
+        # Do a preprocessing pass to ensure all steps are normalized and ready to be referenced
+        @blueprints.each do |name, blueprint|
+          blueprint[:hooks] = {
+            before: Set.new(@global_hooks[:before_blueprint]),
+            after: Set.new(@global_hooks[:after_blueprint])
+          }
+
+          blueprint[:steps] = assign_source(blueprint[:steps], file_name: blueprint[:name])
+            .then { |s| normalize_steps(s) }
+        end
+
+        @blueprints.each do |name, blueprint|
+          hooks = {
+            before: Set.new(@global_hooks[:before_step]),
+            after: Set.new(@global_hooks[:after_step])
+          }
+
+          blueprint[:steps] = expand_steps(blueprint[:steps])
+            .then { |s| inherit_shared(s) }
+            .then { |s| validate_steps(s) }
+            .then { |s| extract_and_assign_hooks(s, blueprint, all: hooks) }
+            .then { |s| tag_steps(s) }
+            .then { |s| flatten_steps(s) }
+            .then { |s| remove_empty_steps(s) }
+        end
+
+        [@blueprints.values, @forge_hooks]
+      end
+
+      private
+
+      def assign_source(steps, file_name:)
+        steps.each do |step|
+          step[:source] = {file_name:, line_number: step.delete(:line_number)}
+          step[:steps] = assign_source(step[:steps], file_name:) if step[:steps]
+        end
+      end
+
+      def normalize_steps(steps)
+        return steps if steps.blank?
+
+        steps.map do |step|
+          # System data (not included in normalizer)
+          source = step.delete(:source)
+
+          # We'll normalize these separately (not included in normalizer)
+          sub_steps = step.delete(:steps) || []
+
+          begin
+            step = Normalizer.normalize!(step, using: :step, label: "")
+            step[:steps] = normalize_steps(sub_steps)
+          ensure
+            step[:source] = source
+          end
+
+          # Pluralize these to be consistent
+          step.rename_key_unordered!(:call, :calls)
+          step.rename_key_unordered!(:expect, :expects)
+
+          step
+        rescue => e
+          raise Error::LoadStepError.new(e, step)
+        end
+      end
+
+      def extract_and_assign_hooks(steps, blueprint, all:)
+        steps.each do |step|
+          hooks = step.delete(:hook) || {}
+          hooks.default = []
+
+          # Forge
+          @forge_hooks[:before].merge(hooks[:before_forge])
+          @forge_hooks[:after].merge(hooks[:after_forge])
+
+          # Blueprint
+          blueprint[:hooks][:before].merge(hooks[:before_blueprint])
+          blueprint[:hooks][:after].merge(hooks[:after_blueprint])
+
+          # Step
+          before = all[:before].merge(hooks[:before_step])
+          after = all[:after].merge(hooks[:after_step])
+
+          if step[:steps].blank?
+            step[:hooks] = {before: before.to_a, after: after.to_a.reverse}
+          else
+            extract_and_assign_hooks(step[:steps], blueprint, all: all.deep_dup)
+          end
+        end
+      end
+
+      def expand_steps(steps)
+        return if steps.blank?
+
+        output_steps = []
+
+        steps.each do |step|
+          output_steps <<
+            if (names = step.delete(:include)) && names.size > 0
+              load_included_steps(step, names)
+            else
+              step
+            end
+
+          step[:steps] = expand_steps(step[:steps])
+        end
+
+        output_steps
+      end
+
+      def load_included_steps(step, names)
+        step[:steps] +=
+          names.flat_map do |name|
+            blueprint = @blueprints[name]
+
+            if blueprint.nil?
+              raise Error, <<~STRING
+                Blueprint #{name.in_quotes} not found
+                Referenced in: #{step[:source][:file_name]}:#{step[:source][:line_number]}
+
+                Available blueprints: #{@blueprints.keys.join_map(", ", &:in_quotes)}
+              STRING
+            end
+
+            steps = blueprint[:steps].deep_dup
+            steps = assign_included_by(step, steps)
+            steps
+          end
+
+        step
+      end
+
+      def assign_included_by(source_step, steps)
+        steps.each do |step|
+          step[:included_by] = source_step[:source]
+          step[:steps] = assign_included_by(source_step, step[:steps]) if step[:steps]
+        end
+      end
+
+      def inherit_shared(steps, shared: {})
+        steps.each do |step|
+          # Apply inherited values to this step
+          step[:request] = merge_request(shared[:request], step[:request])
+          step[:hook] = merge_hooks(shared[:hook], step[:hook])
+
+          if step[:steps].present?
+            step_shared = step.delete(:shared) || {}
+
+            # Combine parent's shared with this step's shared for children
+            inherit_shared(
+              step[:steps],
+              shared: {
+                request: merge_request(shared[:request], step_shared[:request]),
+                hook: merge_hooks(shared[:hook], step_shared[:hook])
+              }
+            )
+          end
+        end
+      end
+
+      def merge_request(parent, child)
+        return child if parent.blank?
+        return parent if child.blank?
+
+        parent.deep_merge(child)
+      end
+
+      def merge_hooks(parent, child)
+        return child if parent.blank?
+        return parent if child.blank?
+
+        parent.merge(child) { |_, a, b| a + b }
+      end
+
+      def tag_steps(steps, parent_tags: [])
+        steps.each do |step|
+          step[:tags] = (parent_tags + (step[:tags] || [])).uniq
+
+          tag_steps(step[:steps], parent_tags: step[:tags]) if step[:steps]
+        end
+      end
+
+      def flatten_steps(steps)
+        steps.flat_map do |step|
+          if (sub_steps = step.delete(:steps))
+            flatten_steps(sub_steps)
+          else
+            step
+          end
+        end
+      end
+
+      def remove_empty_steps(steps)
+        steps.select do |step|
+          step = step.except(:name, :source, :tags, :documentation)
+          step.compact_blank!
+
+          step.except(:hooks).present?
+        end
+      end
+
+      def validate_steps(steps)
+        steps.each do |step|
+          validate_no_action_with_steps(step)
+          validate_expects_requires_request(step)
+
+          validate_steps(step[:steps]) if step[:steps].present?
+        end
+      end
+
+      def validate_no_action_with_steps(step)
+        return if step[:steps].blank?
+
+        action_attrs = ACTION_ATTRIBUTES.select { |attr| step[attr].present? }
+        return if action_attrs.empty?
+
+        raise Error::InvalidStepError.new(
+          "cannot combine action attributes (#{action_attrs.join(", ")}) with steps. " \
+          "Use 'shared:' to pass configuration to substeps, or separate into distinct steps.",
+          step
+        )
+      end
+
+      def validate_expects_requires_request(step)
+        return if step[:expects].blank?
+        return if step[:request].present?
+
+        raise Error::InvalidStepError.new(
+          "cannot use \"expects\" without \"request\" - nothing to validate against",
+          step
+        )
+      end
+    end
+  end
+end