spec_forge 0.5.0 → 0.7.0

data/lib/spec_forge/http/request.rb

@@ -2,88 +2,111 @@
 
 module SpecForge
   module HTTP
-    class Request < Data.define(:base_url, :url, :http_method, :headers, :query, :body)
-      HEADER = /^[A-Z][A-Za-z0-9!-]*$/
+    #
+    # The attributes used to build a Request
+    #
+    # @return [Array<Symbol>]
+    #
+    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)
       #
-      # Initializes a new Request instance with the given options
-      #
-      # @param [Hash] options The options to create the Request with
+      # Regex that attempts to match a valid header
       #
-      # @option options [String] :url The request URL
+      # @return [Regexp]
       #
-      # @option options [String, Verb] :http_method The HTTP method to use
+      HEADER = /^[A-Z][A-Za-z0-9!-]*$/
+
       #
-      # @option options [Hash] :headers Any headers
+      # Creates a new Request with standardized headers and values
       #
-      # @option options [Hash] :query The query parameters for the request (defaults to {})
+      # @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
       #
-      # @option options [Hash] :body The request body (defaults to {})
+      # @return [Request] A new immutable request object
       #
       def initialize(**options)
-        url = extract_url(options)
-        base_url = extract_base_url(options)
-        http_method = normalize_http_method(options)
-        headers = normalize_headers(options)
-        query = normalize_query(options)
-        body = normalize_body(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_method:, headers:, query:, body:)
-      end
-
-      def http_verb
-        http_method.name.downcase
+        super(base_url:, url:, http_verb:, content_type:, headers:, query:, body:)
       end
 
+      #
+      # Returns a hash representation with all attributes fully resolved
+      #
+      # @return [Hash] The request data with all dynamic values resolved
+      #
       def to_h
-        super.transform_values { |v| v.respond_to?(:resolve) ? v.resolve : v }
+        hash = super.transform_values { |v| v.respond_to?(:resolved) ? v.resolved : v }
+        hash[:http_verb] = hash[:http_verb].to_s
+        hash
       end
 
       private
 
-      def extract_base_url(options)
-        options[:base_url].resolve
-      end
-
-      def extract_url(options)
-        options[:url].resolve
-      end
-
-      def normalize_http_method(options)
-        method = options[:http_method].resolve.presence || "GET"
-
-        if method.is_a?(String)
-          Verb.from(method)
-        else
-          method
-        end
-      end
-
-      def normalize_headers(options)
-        headers = options[:headers].transform_keys do |key|
-          key = key.to_s
+      #
+      # Normalizes HTTP header keys to standard format
+      #
+      # Converts snake_case and other formats to HTTP Header-Case format
+      # Examples:
+      #   content_type -> Content-Type
+      #   api_key -> Api-Key
+      #
+      # @param headers [Hash] The headers to normalize
+      #
+      # @return [Attribute::ResolvableHash] Normalized headers as attributes
+      #
+      # @private
+      #
+      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+/, "-")
+            # 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
-        end
-
-        headers = Attribute.bind_variables(headers, options[:variables])
-        Attribute::ResolvableHash.new(headers)
-      end
-
-      def normalize_query(options)
-        query = Attribute.bind_variables(options[:query], options[:variables])
-        Attribute::ResolvableHash.new(query)
-      end
 
-      def normalize_body(options)
-        body = Attribute.bind_variables(options[:body], options[:variables])
-        Attribute::ResolvableHash.new(body)
+        Attribute.from(headers)
       end
     end
   end

data/lib/spec_forge/http/verb.rb

@@ -2,33 +2,112 @@
 
 module SpecForge
   module HTTP
+    #
+    # Represents an HTTP verb (method)
+    #
+    # This class provides a type-safe way to work with HTTP methods,
+    # with predefined constants for common verbs like GET, POST, etc.
+    #
+    # @example Using predefined verbs
+    #   HTTP::Verb::GET    # => #<HTTP::Verb::Get @name="GET">
+    #   HTTP::Verb::POST   # => #<HTTP::Verb::Post @name="POST">
+    #
+    # @example Checking verb types
+    #   verb = HTTP::Verb::POST
+    #   verb.post?   # => true
+    #   verb.get?    # => false
+    #
     class Verb < Data.define(:name)
+      #
+      # Represents the HTTP DELETE method
+      #
+      # @return [Delete] A DELETE verb instance
+      #
       class Delete < Verb
         def initialize = super(name: "DELETE")
       end
 
+      #
+      # Represents the HTTP GET method
+      #
+      # @return [Get] A GET verb instance
+      #
       class Get < Verb
         def initialize = super(name: "GET")
       end
 
+      #
+      # Represents the HTTP PATCH method
+      #
+      # @return [Patch] A PATCH verb instance
+      #
       class Patch < Verb
         def initialize = super(name: "PATCH")
       end
 
+      #
+      # Represents the HTTP POST method
+      #
+      # @return [Post] A POST verb instance
+      #
       class Post < Verb
         def initialize = super(name: "POST")
       end
 
+      #
+      # Represents the HTTP PUT method
+      #
+      # @return [Put] A PUT verb instance
+      #
       class Put < Verb
         def initialize = super(name: "PUT")
       end
 
+      #
+      # A predefined DELETE verb instance for HTTP method usage
+      #
+      # @return [Verb::Delete] A singleton instance representing the HTTP DELETE method
+      # @see Verb
+      #
       DELETE = Delete.new
+
+      #
+      # A predefined GET verb instance for HTTP method usage
+      #
+      # @return [Verb::Get] A singleton instance representing the HTTP GET method
+      # @see Verb
+      #
       GET = Get.new
+
+      #
+      # A predefined PATCH verb instance for HTTP method usage
+      #
+      # @return [Verb::Patch] A singleton instance representing the HTTP PATCH method
+      # @see Verb
+      #
       PATCH = Patch.new
+
+      #
+      # A predefined POST verb instance for HTTP method usage
+      #
+      # @return [Verb::Post] A singleton instance representing the HTTP POST method
+      # @see Verb
+      #
       POST = Post.new
+
+      #
+      # A predefined PUT verb instance for HTTP method usage
+      #
+      # @return [Verb::Put] A singleton instance representing the HTTP PUT method
+      # @see Verb
+      #
       PUT = Put.new
 
+      #
+      # All HTTP verbs as a lookup hash
+      #
+      # @return [Hash<Symbol, Verb>]
+      #
       VERBS = {
         delete: DELETE,
         get: GET,

data/lib/spec_forge/http.rb

@@ -1,5 +1,110 @@
 # frozen_string_literal: true
 
+module SpecForge
+  #
+  # HTTP module providing request and response handling for API testing
+  #
+  # This module contains the HTTP client, request object, and other components
+  # needed to make API calls and validate responses against expectations.
+  #
+  module HTTP
+    #
+    # A mapping of HTTP status codes to their standard descriptions
+    #
+    # This constant provides a lookup table of common HTTP status codes with their
+    # official descriptions according to HTTP specifications. Used internally
+    # to generate human-readable test output.
+    #
+    # @example Looking up a status code description
+    #   HTTP::STATUS_DESCRIPTIONS[200] # => "OK"
+    #   HTTP::STATUS_DESCRIPTIONS[404] # => "Not Found"
+    #
+    STATUS_DESCRIPTIONS = {
+      # Success codes
+      200 => "OK",
+      201 => "Created",
+      202 => "Accepted",
+      204 => "No Content",
+
+      # Redirection
+      301 => "Moved Permanently",
+      302 => "Found",
+      304 => "Not Modified",
+      307 => "Temporary Redirect",
+      308 => "Permanent Redirect",
+
+      # Client errors
+      400 => "Bad Request",
+      401 => "Unauthorized",
+      403 => "Forbidden",
+      404 => "Not Found",
+      405 => "Method Not Allowed",
+      406 => "Not Acceptable",
+      407 => "Proxy Authentication Required",
+      409 => "Conflict",
+      410 => "Gone",
+      411 => "Length Required",
+      413 => "Payload Too Large",
+      414 => "URI Too Long",
+      415 => "Unsupported Media Type",
+      421 => "Misdirected Request",
+      422 => "Unprocessable Content",
+      423 => "Locked",
+      424 => "Failed Dependency",
+      428 => "Precondition Required",
+      429 => "Too Many Requests",
+      431 => "Request Header Fields Too Large",
+
+      # Server errors
+      500 => "Internal Server Error",
+      501 => "Not Implemented",
+      502 => "Bad Gateway",
+      503 => "Service Unavailable",
+      504 => "Gateway Timeout"
+    }
+
+    #
+    # Converts an HTTP status code to a human-readable description
+    #
+    # Takes a numeric status code and returns a formatted string containing both
+    # the code and its description. Uses predefined descriptions for common codes,
+    # with fallbacks to category-based descriptions for uncommon codes.
+    #
+    # @param code [Integer, String] The HTTP status code to convert
+    #
+    # @return [String] A formatted description string (e.g., "200 OK", "404 Not Found")
+    #
+    # @example Common status codes
+    #   HTTP.status_code_to_description(200) # => "200 OK"
+    #   HTTP.status_code_to_description(404) # => "404 Not Found"
+    #
+    # @example Fallback descriptions for uncommon codes
+    #   HTTP.status_code_to_description(299) # => "299 Success"
+    #   HTTP.status_code_to_description(499) # => "499 Client Error"
+    #
+    def self.status_code_to_description(code)
+      code = code.to_i
+      description = STATUS_DESCRIPTIONS[code]
+      return "#{code} #{description}" if description
+
+      # Fallbacks by range
+      if code >= 100 && code < 200
+        "#{code} Informational"
+      elsif code >= 200 && code < 300
+        "#{code} Success"
+      elsif code >= 300 && code < 400
+        "#{code} Redirection"
+      elsif code >= 400 && code < 500
+        "#{code} Client Error"
+      elsif code >= 500 && code < 600
+        "#{code} Server Error"
+      else
+        code.to_s
+      end
+    end
+  end
+end
+
 require_relative "http/backend"
 require_relative "http/client"
 require_relative "http/verb"

data/lib/spec_forge/loader.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+module SpecForge
+  #
+  # Responsible for loading specs from YAML files and converting them to testable objects
+  #
+  # The Loader reads spec files, parses them as YAML, and transforms them into
+  # a structure that can be used to create Forge objects. It also extracts
+  # metadata like line numbers for error reporting.
+  #
+  # @example Loading all specs
+  #   specs = Loader.load_from_files
+  #
+  class Loader
+    class << self
+      #
+      # Loads all spec YAML files and transforms them into normalized structures
+      #
+      # @return [Array<Array>] Array of [global, metadata, specs] for each loaded file
+      #
+      def load_from_files
+        # metadata is not normalized because its not user managed
+        load_specs_from_files.map do |global, metadata, specs|
+          global =
+            begin
+              Normalizer.normalize!(global, using: :global_context)
+            rescue => e
+              raise Error::SpecLoadError.new(e, metadata[:relative_path])
+            end
+
+          specs =
+            specs.map do |spec|
+              Normalizer.normalize!(spec, using: :spec, label: "spec \"#{spec[:name]}\"")
+            rescue => e
+              raise Error::SpecLoadError.new(e, metadata[:relative_path], spec:)
+            end
+
+          [global, metadata, specs]
+        end
+      end
+
+      #
+      # Internal method that handles loading specs from files
+      #
+      # This method coordinates the entire spec loading process by:
+      # 1. Reading files from the specs directory
+      # 2. Parsing them as YAML
+      # 3. Transforming them into the proper structure
+      #
+      # @return [Array<Array>] Array of [global, metadata, specs] for each loaded file
+      #
+      # @private
+      #
+      def load_specs_from_files
+        files = read_from_files
+        parse_and_transform_specs(files)
+      end
+
+      #
+      # Reads spec files from the spec_forge/specs directory
+      #
+      # @return [Array<Array<String, String>>] Array of [file_path, file_content] pairs
+      #
+      # @private
+      #
+      def read_from_files
+        path = SpecForge.forge_path.join("specs")
+
+        Dir[path.join("**/*.yml")].map do |file_path|
+          [file_path, File.read(file_path)]
+        end
+      end
+
+      #
+      # Parses YAML content and extracts line numbers for error reporting
+      #
+      # @param files [Array<Array<String, String>>] Array of [file_path, file_content] pairs
+      #
+      # @return [Array<Array>] Array of [global, metadata, specs] for each file
+      #
+      # @private
+      #
+      def parse_and_transform_specs(files)
+        base_path = SpecForge.forge_path.join("specs")
+
+        files.map do |file_path, content|
+          relative_path = Pathname.new(file_path).relative_path_from(base_path)
+
+          hash = YAML.safe_load(content, symbolize_names: true)
+
+          file_line_numbers = extract_line_numbers(content, hash)
+
+          # Currently, only holds onto global variables
+          global = hash.delete(:global) || {}
+
+          metadata = {
+            file_name: relative_path.basename(".yml").to_s,
+            relative_path: relative_path.to_s,
+            file_path:
+          }
+
+          specs =
+            hash.map do |spec_name, spec_hash|
+              line_number, *expectation_line_numbers = file_line_numbers[spec_name]
+
+              spec_hash[:id] = "spec_#{SpecForge.generate_id(spec_hash)}"
+              spec_hash[:name] = spec_name.to_s
+              spec_hash[:file_path] = metadata[:file_path]
+              spec_hash[:file_name] = metadata[:file_name]
+              spec_hash[:line_number] = line_number
+
+              # Check for expectations instead of defaulting. I want it to error
+              if (expectations = spec_hash[:expectations])
+                expectations.zip(expectation_line_numbers) do |expectation_hash, line_number|
+                  expectation_hash[:id] = "expect_#{SpecForge.generate_id(expectation_hash)}"
+                  expectation_hash[:name] = build_expectation_name(spec_hash, expectation_hash)
+                  expectation_hash[:line_number] = line_number
+                end
+              end
+
+              spec_hash
+            end
+
+          [global, metadata, specs]
+        end
+      end
+
+      #
+      # Extracts line numbers from each YAML section for error reporting
+      #
+      # @param content [String] The raw file content
+      # @param input_hash [Hash] The parsed YAML structure
+      #
+      # @return [Hash] A mapping of spec names to line numbers
+      #
+      # @private
+      #
+      def extract_line_numbers(content, input_hash)
+        # I hate this code, lol, and it hates me.
+        # I've tried to make it better, I've tried to clean it up, but every time I break it.
+        # If you know how to make this better, please submit a PR and save me.
+        spec_names = input_hash.keys
+        keys = {}
+
+        current_spec_name = nil
+        expectations_line = nil
+        expectations_indent = nil
+
+        content.lines.each_with_index do |line, index|
+          line_number = index + 1
+          clean_line = line.rstrip
+          indentation = line[/^\s*/].size
+
+          # Skip blank lines
+          next if clean_line.empty?
+
+          # Reset on top-level elements
+          if indentation == 0
+            current_spec_name = nil
+            expectations_line = nil
+            expectations_indent = nil
+
+            # Check if this line starts a spec we're interested in
+            spec_names.each do |spec_name|
+              next unless clean_line.start_with?("#{spec_name}:")
+
+              current_spec_name = spec_name
+              keys[current_spec_name] = [line_number]
+              break
+            end
+
+            next
+          end
+
+          # Skip if we're not in a relevant spec
+          next unless current_spec_name
+
+          # Found expectations section
+          if clean_line.match?(/^[^#]\s*expectations:/i)
+            expectations_line = line_number
+            expectations_indent = indentation
+            next
+          end
+
+          # Found an expectation item
+          if expectations_line && clean_line.start_with?("#{" " * expectations_indent}- ")
+            keys[current_spec_name] << line_number
+          end
+        end
+
+        keys
+      end
+
+      #
+      # Builds a name for an expectation based on HTTP verb, URL, and optional name
+      #
+      # @param spec_hash [Hash] The spec configuration
+      # @param expectation_hash [Hash] The expectation configuration
+      #
+      # @return [String] A formatted expectation name (e.g., "GET /users - Find User")
+      #
+      # @private
+      #
+      def build_expectation_name(spec_hash, expectation_hash)
+        # Create a structure for http_verb and url
+        # Removing the defaults and validators to avoid triggering extra logic
+        structure = Normalizer.structures[:spec][:structure].slice(:http_verb, :url)
+          .transform_values { |v| v.except(:default, :validator) }
+
+        # Ignore any errors. These will be validated later
+        normalized_spec, _ = Normalizer.normalize(spec_hash, using: structure, label: "n/a")
+        normalized_expectation, _ = Normalizer.normalize(
+          expectation_hash,
+          using: structure, label: "n/a"
+        )
+
+        request_data = normalized_spec.deep_merge(normalized_expectation)
+
+        url = request_data[:url]
+        http_verb = request_data[:http_verb].presence || "GET"
+
+        # Finally generate the name
+        generate_expectation_name(http_verb:, url:, name: expectation_hash[:name])
+      end
+
+      #
+      # Generates an expectation name from its components
+      #
+      # @param http_verb [String] The HTTP verb (GET, POST, etc.)
+      # @param url [String] The URL path
+      # @param name [String, nil] Optional descriptive name
+      #
+      # @return [String] A formatted expectation name
+      #
+      # @private
+      #
+      def generate_expectation_name(http_verb:, url:, name: nil)
+        base = "#{http_verb.upcase} #{url}"   # GET /users
+        base += " - #{name}" if name.present? # GET /users - Returns 404 because y not?
+        base
+      end
+    end
+  end
+end