spec_forge 0.5.0 → 0.7.0

data/lib/spec_forge/context/store.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Context
+    #
+    # Manages storage of API responses for use in subsequent tests
+    #
+    # This class provides a mechanism to store HTTP requests and responses
+    # during test execution, allowing values to be referenced in later tests
+    # through the `store.id.body.attribute` syntax.
+    #
+    # @example Storing and retrieving a response in specs
+    #   # In one expectation:
+    #   store_as: user_creation
+    #
+    #   # In a later test:
+    #   query:
+    #     id: store.user_creation.body.id
+    #
+    class Store
+      #
+      # Represents a stored entry containing arbitrary data from test execution
+      #
+      # Entries are created during test execution to store custom data that can be
+      # accessed in subsequent tests. Unlike the original rigid Data structure, this
+      # OpenStruct-based approach allows storing any key-value pairs, making it perfect
+      # for complex test scenarios that need custom configuration, metadata, or
+      # computed values.
+      #
+      # @example Storing custom configuration data
+      #   SpecForge.context.store.set(
+      #     "app_config",
+      #     api_version: "v2.1",
+      #     feature_flags: { advanced_search: true }
+      #   )
+      #
+      # @example Accessing stored data in tests
+      #   headers:
+      #     X-API-Version: store.app_config.api_version
+      #   query:
+      #     search_enabled: store.app_config.feature_flags.advanced_search
+      #
+      class Entry < OpenStruct
+        #
+        # Creates a new store entry
+        #
+        # @param scope [Symbol] Scope of this entry, either :file or :spec
+        #
+        # @return [Entry] A new entry instance
+        #
+        def initialize(scope: :file, **)
+          super
+        end
+
+        #
+        # Returns all available methods that can be called
+        #
+        # @return [Array] The method names
+        #
+        def available_methods
+          @table.keys
+        end
+      end
+
+      #
+      # Creates a new empty store
+      #
+      # @return [Store] A new store instance
+      #
+      def initialize
+        @inner = {}
+      end
+
+      #
+      # Retrieves a stored entry by ID
+      #
+      # @param id [String, Symbol] The identifier for the stored entry
+      #
+      # @return [Entry, nil] The stored entry or nil if not found
+      #
+      def [](id)
+        @inner[id]
+      end
+
+      #
+      # Returns the number of entries in the store
+      #
+      # @return [Integer] The count of stored entries
+      #
+      def size
+        @inner.size
+      end
+
+      #
+      # Stores an entry with the specified ID
+      #
+      # @param id [String, Symbol] The identifier to store the entry under
+      #
+      # @return [self]
+      #
+      def set(id, **)
+        @inner[id] = Entry.new(**)
+
+        self
+      end
+
+      #
+      # Removes all entries from the store
+      #
+      def clear
+        @inner.clear
+      end
+
+      #
+      # Removes all spec entries from the store
+      #
+      def clear_specs
+        @inner.delete_if { |_k, v| v.scope == :spec }
+      end
+
+      #
+      # Returns a hash representation of store
+      #
+      # @return [Hash]
+      #
+      def to_h
+        @inner.transform_values(&:to_h).deep_stringify_keys
+      end
+    end
+  end
+end

data/lib/spec_forge/context/variables.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module SpecForge
+  class Context
+    #
+    # Manages variable resolution across different expectations in SpecForge tests.
+    #
+    # The Variables class handles two layers of variable definitions:
+    #   - Base variables: The core set of variables defined at the spec level
+    #   - Overlay variables: Additional variables defined at the expectation level
+    #       that can override base variables with the same name.
+    #
+    # @example Basic usage
+    #   variables = Variables.new(
+    #     base: {user_id: 123, name: "Test User"},
+    #     overlay: {
+    #       "expectation_1": {name: "Override User"}
+    #     }
+    #   )
+    #
+    #   variables[:user_id] #=> 123
+    #   variables[:name]    #=> "Test User"
+    #
+    #   variables.use_overlay("expectation_1")
+    #   variables[:name]    #=> "Override User"
+    #   variables[:user_id] #=> 123 (unchanged)
+    #
+    class Variables < Hash
+      attr_reader :base, :overlay
+
+      #
+      # Creates a new Variables container with base and overlay definitions
+      #
+      # @param base [Hash] The base set of variables (typically defined at spec level)
+      # @param overlay [Hash<String, Hash>] A hash of overlay variable sets keyed by ID
+      #
+      # @return [Variables]
+      #
+      def initialize(base: {}, overlay: {})
+        set(base:, overlay:)
+      end
+
+      #
+      # Sets the base and overlay variable hashes
+      #
+      # @param base [Hash] The new base variable hash
+      # @param overlay [Hash<String, Hash>] The new overlay variable hashes
+      #
+      # @return [self]
+      #
+      def set(base:, overlay: {})
+        @base = Attribute.from(base)
+        @overlay = overlay
+
+        resolve_into_self(@base)
+        self
+      end
+
+      #
+      # Applies a specific overlay to the base variables
+      # If the overlay doesn't exist or is empty, no changes are made.
+      #
+      # @param id [String] The ID of the overlay to apply
+      #
+      # @return [nil]
+      #
+      def use_overlay(id)
+        active = @base
+
+        if (overlay = @overlay[id]) && overlay.present?
+          active = active.deep_merge(overlay)
+        end
+
+        resolve_into_self(active)
+        self
+      end
+
+      private
+
+      def resolve_into_self(hash)
+        # Start fresh
+        clear
+
+        # Load the resolved values into self
+        hash.each do |key, value|
+          self[key] = Attribute.from(value).resolved
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/context.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module SpecForge
+  #
+  # Core data structure that maintains context during test execution
+  #
+  # Context stores and provides access to global variables, test variables, and
+  # shared state across specs.
+  # It acts as a central repository for test data during execution.
+  #
+  # @example Accessing the current context
+  #   SpecForge.context.variables[:user_id] #=> 123
+  #
+  class Context < Data.define(:global, :store, :variables)
+    #
+    # Creates a new context with default values
+    #
+    # @param global [Hash] Global variables shared across all specs
+    # @param variables [Hash] Test variables specific to the current context
+    #
+    # @return [Context] A new context instance
+    #
+    def initialize(global: {}, variables: {})
+      super(
+        global: Global.new(**global),
+        store: Store.new,
+        variables: Variables.new(**variables)
+      )
+    end
+  end
+end
+
+require_relative "context/callbacks"
+require_relative "context/global"
+require_relative "context/store"
+require_relative "context/variables"

data/lib/spec_forge/core_ext/array.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+#
+# Extensions to Ruby's Array class for SpecForge functionality
+#
+# Adds utility methods used throughout SpecForge for array manipulation
+# and data processing.
+#
+class Array
+  #
+  # Merges an array of hashes into a single hash
+  #
+  # Performs a deep merge on each hash in the array, combining them
+  # into a single hash with all keys and values.
+  #
+  # @return [Hash] A hash containing the merged contents of all hashes in the array
+  #
+  # @example Merging an array of hashes
+  #   [{a: 1}, {b: 2}, {a: 3}].to_merged_h
+  #   # => {a: 3, b: 2}
+  #
+  def to_merged_h
+    each_with_object({}) do |hash, output|
+      output.deep_merge!(hash)
+    end
+  end
+end

data/lib/spec_forge/core_ext/rspec.rb

@@ -2,19 +2,37 @@
 
 return if defined?(SPEC_FORGE_INTERNAL_TESTING)
 
+#
+# RSpec's core testing framework module
+# Provides the fundamental structure and functionality for RSpec tests
+#
 module RSpec
+  #
+  # Core implementation details and extensions for RSpec
+  # Contains the fundamental building blocks of the RSpec testing framework
+  #
   module Core
+    #
+    # Handles notifications and reporting for RSpec test runs
+    # Manages how test results and metadata are processed and communicated
+    #
     module Notifications
       #
-      # I did attempt to do this without monkey patching
-      # Getting around the `rspec` word was making it difficult
+      # A monkey patch of an internal RSpec class to allow SpecForge to replace parts of
+      # RSpec's reporting output in order to provide useful feedback to the user.
+      # This replaces "rspec" in commands with "spec_forge", removes any line numbers, and
+      # ensures that failures properly report the YAML file that it occurred in.
       #
       class SummaryNotification
+        #
+        # Create an alias to RSpec original colorized_rerun_commands so it can be called at a
+        # later point.
+        #
+        alias_method :og_colorized_rerun_commands, :colorized_rerun_commands
+
         # Customizes RSpec's failure output to:
         # 1. Use 'spec_forge' instead of 'rspec' for rerun commands
         # 2. Remove line numbers since SpecForge uses dynamic spec generation
-        alias_method :og_colorized_rerun_commands, :colorized_rerun_commands
-
         def colorized_rerun_commands(colorizer)
           # Updating these at this point fixes the re-run for some failures - it depends
           failed_examples.each do |example|

data/lib/spec_forge/documentation/builder.rb

@@ -0,0 +1,383 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    #
+    # Transforms extracted test data into a structured document
+    #
+    # This class processes raw endpoint data from tests into a hierarchical document
+    # structure suitable for rendering as API documentation.
+    #
+    # @example Creating a document from test data
+    #   document = Builder.document_from_endpoints(endpoints)
+    #
+    class Builder
+      # Source: https://gist.github.com/johnelliott/cf77003f72f889abbc3f32785fa3df8d
+      UUID_REGEX = /^[0-9A-F]{8}-[0-9A-F]{4}-4[0-9A-F]{3}-[89AB][0-9A-F]{3}-[0-9A-F]{12}$/i
+
+      #
+      # Regular expression for matching floating point numbers in strings
+      #
+      # Matches decimal numbers with optional negative sign, used for type detection
+      # when analyzing API response data.
+      #
+      # @api private
+      #
+      INTEGER_REGEX = /^-?\d+$/
+
+      #
+      # Regular expression for matching integer numbers in strings
+      #
+      # Matches whole numbers with optional negative sign, used for type detection
+      # when analyzing API response data.
+      #
+      # @api private
+      #
+      FLOAT_REGEX = /^-?\d+\.\d+$/
+
+      #
+      # Creates a document from endpoint data
+      #
+      # @param endpoints [Array<Hash>] Array of endpoint data extracted from tests
+      #
+      # @return [Document] A structured documentation document
+      #
+      def self.document_from_endpoints(endpoints = [])
+        new(endpoints).export_as_document
+      end
+
+      #
+      # The processed endpoints organized by path and HTTP method
+      #
+      # Contains all endpoint data after grouping, sanitizing, merging,
+      # and flattening operations for document generation.
+      #
+      # @return [Hash] Processed endpoints ready for document creation
+      #
+      attr_reader :endpoints
+
+      #
+      # Initializes a new builder with endpoint data
+      #
+      # @param endpoints [Array<Hash>] Array of endpoint data extracted from tests
+      #
+      # @return [Builder] A new builder instance
+      #
+      def initialize(endpoints)
+        @endpoints = prepare_endpoints(endpoints)
+      end
+
+      #
+      # Prepares endpoint data for document creation
+      #
+      # Groups endpoints by path and HTTP method, sanitizes error responses,
+      # merges similar operations, and flattens the result.
+      #
+      # @param endpoints [Array<Hash>] Raw endpoint data from tests
+      #
+      # @return [Hash] Processed endpoints organized by path and method
+      #
+      def prepare_endpoints(endpoints)
+        # Step one, group the endpoints by their paths and verb
+        # { path: {get: [], post: []}, path_2: {get: []}, ... }
+        grouped = group_endpoints(endpoints)
+
+        grouped.each_value do |endpoint|
+          # Operations are those arrays
+          endpoint.transform_values! do |operations|
+            # Step two, clear data from any error (4xx, 5xx) operations
+            operations = sanitize_error_operations(operations)
+
+            # Step three, merge all of the operations into one single hash
+            operations = merge_operations(operations)
+
+            # Step four, flatten the operations into one
+            flatten_operations(operations)
+          end
+        end
+      end
+
+      #
+      # Exports the processed endpoints as a document
+      #
+      # @return [Document] A document containing the processed endpoints
+      #
+      def export_as_document
+        Document.new(endpoints:)
+      end
+
+      private
+
+      def determine_type(value)
+        case value
+        when true, false
+          "boolean"
+        when Float
+          # According to the docs: A Float object represents a sometimes-inexact real number
+          # using the native architecture’s double-precision floating point representation.
+          # So a double it is!
+          "double"
+        when Integer
+          "integer"
+        when Array
+          "array"
+        when NilClass
+          "null"
+        when DateTime, Time
+          "datetime"
+        when Date
+          "date"
+        when String, Symbol
+          if value.match?(UUID_REGEX)
+            "uuid"
+          elsif value.match?(INTEGER_REGEX)
+            "integer"
+          elsif value.match?(FLOAT_REGEX)
+            "double"
+          elsif value == "true" || value == "false"
+            "boolean"
+          else
+            "string"
+          end
+        when URI
+          "uri"
+        when Numeric
+          "number"
+        else
+          "object"
+        end
+      end
+
+      #
+      # Groups endpoints by path and HTTP method
+      #
+      # @param endpoints [Array<Hash>] Array of endpoint data
+      #
+      # @return [Hash] Endpoints grouped by path and method
+      #
+      # @private
+      #
+      def group_endpoints(endpoints)
+        grouped = Hash.new_nested_hash(depth: 1)
+
+        # Convert the endpoints from a flat array of objects into a hash
+        endpoints.each do |input|
+          # "/users" => {}
+          endpoint_hash = grouped[input[:url]]
+
+          # "GET" => []
+          (endpoint_hash[input[:http_verb]] ||= []) << input
+        end
+
+        grouped
+      end
+
+      #
+      # Sanitizes operations that represent error responses
+      #
+      # Removes request details from operations with 4xx/5xx responses
+      # to prevent invalid data from appearing in documentation.
+      #
+      # @param operations [Array<Hash>] Array of operations
+      #
+      # @return [Array<Hash>] Sanitized operations
+      #
+      # @private
+      #
+      def sanitize_error_operations(operations)
+        operations.each do |operation|
+          next unless operation[:response_status] >= 400
+
+          # This keeps tests that handle errors from including their invalid attributes
+          # and such in the output.
+          operation[:request_query] = {}
+          operation[:request_headers] = {}
+          operation[:request_body] = {}
+        end
+      end
+
+      #
+      # Merges similar operations into a single operation
+      #
+      # @param operations [Array<Hash>] Array of operations
+      #
+      # @return [Array<Hash>] Merged operations
+      #
+      # @private
+      #
+      def merge_operations(operations)
+        operations.group_by { |o| o[:response_status] }
+          .transform_values { |o| o.to_merged_h }
+          .values
+      end
+
+      #
+      # Flattens multiple operations into a single operation structure
+      #
+      # @param operations [Array<Hash>] Array of operations
+      #
+      # @return [Hash] Flattened operation
+      #
+      # @private
+      #
+      def flatten_operations(operations)
+        id = operations.key_map(:spec_name).reject(&:blank?).first
+
+        description = operations.key_map(:expectation_name)
+          .reject(&:blank?)
+          .first
+          &.split(" - ")
+          &.second || ""
+
+        parameters = normalize_parameters(operations)
+        requests = normalize_requests(operations)
+        responses = normalize_responses(operations)
+
+        {
+          id:,
+          description:,
+          parameters:,
+          requests:,
+          responses:
+        }
+      end
+
+      #
+      # Normalizes request parameters from operations
+      #
+      # Extracts and categorizes parameters as path or query parameters
+      # and determines their data types.
+      #
+      # @param operations [Array<Hash>] Array of operations
+      #
+      # @return [Hash] Normalized parameters
+      #
+      # @private
+      #
+      def normalize_parameters(operations)
+        parameters = {}
+
+        operations.each do |operation|
+          # Store the URL so it can be determined if the param is in the path or not
+          url = operation[:url]
+          params = operation[:request_query].transform_values { |value| {value:, url:} }
+
+          parameters.merge!(params)
+        end
+
+        parameters.transform_values!(with_key: true) do |data, key|
+          key_in_path = data[:url].include?("{#{key}}")
+
+          {
+            location: key_in_path ? "path" : "query",
+            type: determine_type(data[:value])
+          }
+        end
+      end
+
+      #
+      # Normalizes request bodies from operations
+      #
+      # Extracts request bodies from successful operations and
+      # determines their data types.
+      #
+      # @param operations [Array<Hash>] Array of operations
+      #
+      # @return [Array<Hash>] Normalized request bodies
+      #
+      # @private
+      #
+      def normalize_requests(operations)
+        successful_operations = operations.select { |o| o[:response_status] < 400 }
+        return [] if successful_operations.blank?
+
+        successful_operations.filter_map.with_index do |operation, index|
+          content = operation[:request_body]
+          next if content.blank?
+
+          name = operation[:expectation_name].split(" - ").second
+
+          {
+            name: name || "Example #{index}",
+            content_type: operation[:content_type],
+            type: determine_type(content),
+            content:
+          }
+        end
+      end
+
+      #
+      # Normalizes responses from operations
+      #
+      # Extracts response details including status, headers, and body
+      # and determines their data types.
+      #
+      # @param operations [Array<Hash>] Array of operations
+      #
+      # @return [Array<Hash>] Normalized responses
+      #
+      # @private
+      #
+      def normalize_responses(operations)
+        operations.map do |operation|
+          {
+            content_type: operation[:content_type],
+            status: operation[:response_status],
+            headers: normalize_headers(operation[:response_headers]),
+            body: normalize_response_body(operation[:response_body])
+          }
+        end
+      end
+
+      #
+      # Normalizes response headers
+      #
+      # @param headers [Hash] Response headers
+      #
+      # @return [Hash] Normalized headers with types
+      #
+      # @private
+      #
+      def normalize_headers(headers)
+        headers.transform_values do |value|
+          {type: determine_type(value)}
+        end
+      end
+
+      #
+      # Normalizes response body structure
+      #
+      # @param body [Hash, Array, String] Response body
+      #
+      # @return [Hash] Normalized body structure with type information
+      #
+      # @private
+      #
+      def normalize_response_body(body)
+        proc = lambda do |value|
+          {type: determine_type(value)}
+        end
+
+        case body
+        when Hash
+          {
+            type: "object",
+            content: body.deep_transform_values(&proc)
+          }
+        when Array
+          {
+            type: "array",
+            content: body.map(&proc)
+          }
+        when String
+          {
+            type: "string",
+            content: body
+          }
+        else
+          raise "Unexpected body: #{body.inspect}"
+        end
+      end
+    end
+  end
+end