spec_forge 0.6.0 → 0.7.0

data/lib/spec_forge/documentation/generators/openapi/base.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    module Generators
+      module OpenAPI
+        #
+        # Base class for OpenAPI generators
+        #
+        # Provides common functionality for OpenAPI generators of different versions.
+        #
+        class Base < Generators::Base
+          #
+          # Converts the generator's version to a semantic version object
+          #
+          # @return [SemVersion] The semantic version
+          #
+          def self.to_sem_version
+            SemVersion.new(CURRENT_VERSION)
+          end
+
+          #
+          # Generates OpenAPI documentation from test data with optional caching
+          #
+          # Loads endpoint data from tests (either fresh or cached), creates a document,
+          # and generates the OpenAPI specification using the appropriate version generator.
+          #
+          # @param use_cache [Boolean] Whether to use cached test data if available
+          #
+          # @return [Hash] The generated OpenAPI specification
+          #
+          def self.generate(use_cache: false)
+            document = Documentation::Loader.load_document(use_cache:)
+            new(document).generate
+          end
+
+          #
+          # Validates an OpenAPI specification against the standard
+          #
+          # Uses the openapi3_parser gem to validate the generated specification
+          # and provides detailed error reporting if validation fails.
+          #
+          # @param output [Hash] The OpenAPI specification to validate
+          #
+          # @return [void]
+          #
+          # @raise [Error::InvalidOASDocument] If the specification is invalid
+          #
+          def self.validate!(output)
+            document = Openapi3Parser.load(output)
+            if document.valid?
+              puts "✅ No validation errors found!"
+              return
+            end
+
+            puts ErrorFormatter.format(document.errors.errors)
+            raise Error::InvalidOASDocument
+          end
+
+          protected
+
+          #
+          # Loads OpenAPI configuration from YAML
+          #
+          # @return [Hash] The normalized OpenAPI configuration
+          #
+          # @api private
+          #
+          def config
+            @config ||= begin
+              file_extension_glob = "*.{yml,yaml}"
+              base_path = SpecForge.openapi_path.join("config")
+
+              root_paths = base_path.join(file_extension_glob)
+              path_paths = base_path.join("paths", "**", file_extension_glob)
+              component_paths = base_path.join("components", "**", file_extension_glob)
+
+              config = load_yml_from_paths(root_paths).to_merged_h
+              paths_config = load_yml_from_paths(path_paths).to_merged_h
+              component_config = load_yml_from_paths(component_paths).to_merged_h
+
+              (config["paths"] ||= {}).deep_merge!(paths_config)
+              (config["components"] ||= {}).deep_merge!(component_config)
+
+              config
+            end
+          end
+
+          private
+
+          def load_yml_from_paths(paths)
+            Dir[paths].map do |path|
+              YAML.safe_load_file(path)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/documentation/generators/openapi/error_formatter.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    module Generators
+      module OpenAPI
+        #
+        # Formats OpenAPI validation errors into human-readable messages
+        #
+        # Takes validation errors from OpenAPI parsers and transforms them into
+        # structured, easy-to-understand error messages with context information
+        # and suggestions for resolution.
+        #
+        # @example Formatting validation errors
+        #   errors = openapi_parser.errors
+        #   formatted = ErrorFormatter.format(errors)
+        #   puts formatted
+        #
+        class ErrorFormatter
+          #
+          # Regular expression for matching path-related validation errors
+          #
+          # Captures path, HTTP method, and response code from OpenAPI error contexts
+          # to provide meaningful location information in error messages.
+          #
+          # @api private
+          #
+          PATHS_REGEX = %r{#/paths/(.+?)/(get|post|put|patch|delete|head|options)/responses/(.+)}i
+
+          #
+          # Regular expression for matching schema-related validation errors
+          #
+          # Captures schema name and field path from OpenAPI error contexts
+          # to identify specific schema validation failures.
+          #
+          # @api private
+          #
+          SCHEMA_REGEX = %r{#/components/schemas/(.+?)/(.+)}i
+
+          #
+          # Formats an array of validation errors into a readable string
+          #
+          # @param errors [Array] Array of validation error objects
+          #
+          # @return [String, nil] Formatted error message or nil if no errors
+          #
+          def self.format(errors)
+            new(errors).format
+          end
+
+          #
+          # Creates a new error formatter
+          #
+          # @param errors [Array] Array of validation error objects to format
+          #
+          # @return [ErrorFormatter] A new formatter instance
+          #
+          def initialize(errors)
+            @errors = errors
+          end
+
+          #
+          # Formats the errors into a structured, readable message
+          #
+          # Groups errors by type (unexpected vs validation), formats each error
+          # with context and location information, and returns a comprehensive
+          # error report with resolution guidance.
+          #
+          # @return [String, nil] Formatted error message or nil if no errors
+          #
+          def format
+            return if @errors.blank?
+
+            unexpected_errors, errors = @errors.partition { |e| e.message.include?("Unexpected") }
+
+            unexpected_errors = format_errors(unexpected_errors)
+            errors = format_errors(errors, start_index: unexpected_errors.size)
+
+            if unexpected_errors.size > 0
+              unexpected_message = <<~STRING
+
+                Field errors (resolve these first):
+
+                #{unexpected_errors.join("\n\n")}
+
+                -------
+
+                Other validation errors:
+              STRING
+            end
+
+            <<~STRING
+              ========================================
+              🚨 Validation Errors
+              ========================================
+              #{unexpected_message}
+              #{errors.join("\n\n")}
+
+              Total errors: #{errors.size}
+            STRING
+          end
+
+          private
+
+          def format_errors(errors, start_index: 0)
+            errors.map.with_index do |error, index|
+              format_single_error(error, start_index + index + 1)
+            end
+          end
+
+          def format_single_error(error, number)
+            context_path = simplify_context_path(error.context.to_s)
+            error_message =
+              <<~STRING
+                Error ##{number}:
+                  Message: #{error.message}
+                  Location: #{context_path}
+              STRING
+
+            error_message += "  Type: #{error.for_type}" if error.for_type
+            error_message
+          end
+
+          def simplify_context_path(context_path)
+            # Clean up the basic encoding mess first
+            path = context_path.gsub(/.*source_location: /, "")
+              .gsub("%7B", "{")
+              .gsub("%7D", "}")
+              .gsub("~1", "/")
+              .gsub("~0", "~")
+              .gsub("%24", "$")
+
+            # Now try to make it human-readable
+            if (match = path.match(PATHS_REGEX))
+              full_path, method, rest = match.captures
+
+              "#{method.upcase} #{full_path} → responses/#{rest}"
+            elsif (match = path.match(SCHEMA_REGEX))
+              schema, rest = match.captures
+              "Schemas → #{schema} → #{rest}"
+            else
+              path
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/documentation/generators/openapi/v3_0.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    module Generators
+      module OpenAPI
+        # https://spec.openapis.org/oas/v3.0.4.html
+        class V3_0 < Base # standard:disable Naming/ClassAndModuleCamelCase
+          #
+          # Current OpenAPI 3.0 version supported by this generator
+          #
+          # @api private
+          #
+          CURRENT_VERSION = "3.0.4"
+
+          #
+          # Alias for OpenAPI V3.0 classes for cleaner code
+          #
+          # @api private
+          #
+          OAS = Documentation::OpenAPI::V3_0
+
+          #
+          # Generates an OpenAPI 3.0 specification from the input document
+          #
+          # Creates a complete OpenAPI specification by combining the document's
+          # endpoint data with configuration files and ensuring compliance with
+          # OpenAPI 3.0.4 standards.
+          #
+          # @return [Hash] Complete OpenAPI 3.0 specification
+          #
+          def generate
+            output = {
+              openapi: CURRENT_VERSION,
+              paths:
+            }
+
+            output.deep_stringify_keys!
+            output.deep_merge!(config)
+
+            output
+          end
+
+          #
+          # Transforms document endpoints into OpenAPI paths structure
+          #
+          # Converts the internal endpoint representation into the OpenAPI paths
+          # format, with each path containing operations organized by HTTP method.
+          #
+          # @return [Hash] OpenAPI paths object with operations
+          #
+          def paths
+            paths = input.endpoints.deep_dup
+
+            paths.each do |path, operations|
+              operations.transform_values! do |document|
+                OAS::Operation.new(document).to_h
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/documentation/generators/openapi.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "openapi/base"
+require_relative "openapi/error_formatter"
+require_relative "openapi/v3_0"
+
+module SpecForge
+  module Documentation
+    module Generators
+      #
+      # Namespace for OpenAPI generators
+      #
+      # Contains version-specific OpenAPI generators and helper methods
+      # for selecting the appropriate generator.
+      #
+      module OpenAPI
+        #
+        # Current OpenAPI version used as default
+        #
+        # Points to the latest supported OpenAPI version for new specifications.
+        #
+        # @api private
+        #
+        CURRENT_VERSION = V3_0::CURRENT_VERSION
+
+        #
+        # Mapping of OpenAPI versions to their generator classes
+        #
+        # Used for version selection when generating OpenAPI documentation.
+        # Keys are SemVersion objects, values are generator classes.
+        #
+        # @api private
+        #
+        VERSIONS = {
+          V3_0.to_sem_version => V3_0
+        }.freeze
+
+        #
+        # Selects an OpenAPI generator by version
+        #
+        # @param version [String] OpenAPI version (e.g., "3.0")
+        #
+        # @return [Class] The appropriate generator class
+        # @raise [ArgumentError] If the version is not supported
+        #
+        def self.[](version)
+          version = SemVersion.from_loose_version(version)
+          generator = VERSIONS.value_where { |k, _v| k.satisfies?("~> #{version}") }
+
+          if generator.nil?
+            raise ArgumentError, "Invalid OpenAPI version provided: #{version.to_s.in_quotes}"
+          end
+
+          generator
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/documentation/generators.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    #
+    # Documentation rendering functionality
+    #
+    # Contains generator classes for transforming SpecForge documents
+    # into various output formats like OpenAPI specifications.
+    #
+    module Generators
+    end
+  end
+end
+
+require_relative "generators/base"
+require_relative "generators/openapi"

data/lib/spec_forge/documentation/loader/cache.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    class Loader
+      #
+      # Manages caching of test execution data for documentation generation
+      #
+      # Provides caching of endpoint data extracted from tests,
+      # checking file modification times to determine cache validity and
+      # avoiding unnecessary test re-execution when specs haven't changed.
+      #
+      # @example Using the cache
+      #   cache = Cache.new
+      #   if cache.valid?
+      #     endpoints = cache.read
+      #   else
+      #     endpoints = run_tests_and_extract_data
+      #     cache.create(endpoints)
+      #   end
+      #
+      class Cache
+        #
+        # Creates a new cache manager
+        #
+        # Sets up file paths for endpoint and spec caches in the OpenAPI
+        # generated directory structure.
+        #
+        # @return [Cache] A new cache instance
+        #
+        def initialize
+          @endpoint_cache = SpecForge.openapi_path.join("generated", ".cache", "endpoints.yml")
+          @spec_cache = SpecForge.openapi_path.join("generated", ".cache", "specs.yml")
+        end
+
+        #
+        # Checks if the cache is valid and can be used
+        #
+        # Determines cache validity by checking if endpoint cache exists
+        # and whether any spec files have been modified since the cache
+        # was created.
+        #
+        # @return [Boolean] true if cache is valid and can be used
+        #
+        def valid?
+          endpoint_cache? && !specs_updated?
+        end
+
+        #
+        # Creates a cache entry with endpoint data and spec file metadata
+        #
+        # Writes both the endpoint data and current spec file modification times
+        # to enable cache invalidation when specs change.
+        #
+        # @param endpoints [Array<Hash>] Endpoint data to cache
+        #
+        # @return [void]
+        #
+        def create(endpoints)
+          write_spec_cache
+          write(endpoints)
+        end
+
+        #
+        # Writes endpoint data to the cache file
+        #
+        # @param endpoints [Array<Hash>] Endpoint data to write
+        #
+        # @return [void]
+        #
+        def write(endpoints)
+          write_to_file(endpoints, @endpoint_cache)
+        end
+
+        #
+        # Reads cached endpoint data from disk
+        #
+        # @return [Array<Hash>] Previously cached endpoint data
+        #
+        # @raise [StandardError] If cache file is missing or corrupted
+        #
+        def read
+          read_from_file(@endpoint_cache)
+        end
+
+        private
+
+        def write_to_file(data, path)
+          File.write(path, data.to_yaml(stringify_names: true))
+        end
+
+        def read_from_file(path)
+          YAML.safe_load_file(path, symbolize_names: true, permitted_classes: [Symbol, Time])
+        end
+
+        def specs_updated?
+          return true if !File.exist?(@spec_cache)
+
+          cache = read_from_file(@spec_cache)
+          new_cache = generate_spec_cache
+
+          different?(cache, new_cache)
+        end
+
+        def endpoint_cache?
+          File.exist?(@endpoint_cache)
+        end
+
+        def generate_spec_cache
+          paths = SpecForge.forge_path.join("specs", "**", "*.{yml,yaml}")
+
+          Dir[paths].each_with_object({}) do |path, hash|
+            hash[path.to_sym] = File.mtime(path)
+          end
+        end
+
+        def write_spec_cache
+          data = generate_spec_cache
+          write_to_file(data, @spec_cache)
+        end
+
+        def different?(cache_left, cache_right)
+          # The number of files changed
+          return true if cache_left.size != cache_right.size
+
+          default_time = Time.now
+
+          # Check if any of the files have changed since last time
+          cache_left.any? do |path, time_left|
+            time_right = cache_right[path] || default_time
+
+            time_left != time_right
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/documentation/loader.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require_relative "loader/cache"
+
+module SpecForge
+  module Documentation
+    #
+    # Extracts API documentation data from SpecForge tests
+    #
+    # This class runs all tests and captures successful test contexts
+    # to extract endpoint information, including request/response data.
+    #
+    # @example Extracting documentation data
+    #   endpoints = Loader.extract_from_tests
+    #
+    class Loader
+      #
+      # Loads a documentation document with optional caching
+      #
+      # Extracts endpoint data from SpecForge tests, either from cache (if valid
+      # and requested) or by running fresh tests. Returns a structured document
+      # ready for generator consumption.
+      #
+      # @param use_cache [Boolean] Whether to use cached data if available
+      #
+      # @return [Document] Structured document containing endpoint data
+      #
+      def self.load_document(use_cache: false)
+        cache = Cache.new
+
+        endpoints =
+          if use_cache && cache.valid?
+            puts "Loading from cache..."
+            cache.read
+          else
+            puts "Cache invalid - Regenerating..." if use_cache
+
+            endpoints = extract_from_tests
+            cache.create(endpoints)
+
+            endpoints
+          end
+
+        Builder.document_from_endpoints(endpoints)
+      end
+
+      #
+      # Runs tests and extracts endpoint data
+      #
+      # @return [Array<Hash>] Extracted endpoint data from successful tests
+      #
+      def self.extract_from_tests
+        new
+          .run_tests
+          .extract_and_normalize_data
+      end
+
+      #
+      # Initializes a new loader
+      #
+      # Sets up a unique callback and prepares storage for successful test results
+      #
+      # @return [Loader] A new loader instance
+      #
+      def initialize
+        @callback_name = "__sf_docs_#{SpecForge.generate_id(self)}"
+        @successes = []
+      end
+
+      #
+      # Runs all tests and captures successful test results
+      #
+      # Registers a callback to capture test context and runs all tests
+      #
+      # @return [self] Returns self for method chaining
+      #
+      def run_tests
+        @successes.clear
+
+        Callbacks.register(@callback_name) do |context|
+          next if context.expectation.documentation == false || context.spec.documentation == false
+
+          @successes << context if context.example.execution_result.status == :passed
+        end
+
+        forges = prepare_forges
+
+        Runner.run(forges, exit_on_finish: false, exit_on_failure: true)
+
+        self
+      ensure
+        Callbacks.deregister(@callback_name)
+      end
+
+      #
+      # Prepares forge objects for test execution
+      #
+      # Adds the documentation callback to each forge
+      #
+      # @return [Array<Forge>] Array of prepared forge objects
+      #
+      def prepare_forges
+        forges = Runner.prepare
+
+        forges.each do |forge|
+          forge.global[:callbacks] << {after_each: @callback_name}
+        end
+
+        forges
+      end
+
+      #
+      # Extracts and normalizes endpoint data from test results
+      #
+      # @return [Array<Hash>] Normalized endpoint data
+      #
+      def extract_and_normalize_data
+        @successes.map { |d| extract_endpoint(d) }
+      end
+
+      private
+
+      def extract_endpoint(context)
+        request_hash = context.request.to_h
+        response_hash = context.response.to_hash
+
+        # Only pull the headers that the user explicitly checked for.
+        # This keeps the extra unrelated headers from being included
+        response_headers = context.expectation
+          .constraints
+          .headers
+          .keys
+          .map { |h| h.to_s.downcase }
+
+        response_headers = response_hash[:response_headers].slice(*response_headers)
+
+        {
+          # Metadata
+          spec_name: context.spec.name,
+          expectation_name: context.expectation.name,
+
+          # Request data
+          base_url: request_hash[:base_url],
+          url: request_hash[:url],
+          http_verb: request_hash[:http_verb],
+          content_type: request_hash[:content_type],
+          request_body: request_hash[:body],
+          request_headers: request_hash[:headers],
+          request_query: request_hash[:query],
+
+          # Response data
+          response_status: response_hash[:status],
+          response_body: response_hash[:body],
+          response_headers:
+        }
+      end
+    end
+  end
+end