spec_forge 0.5.0 → 0.7.0

data/lib/spec_forge/documentation/document/operation.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    class Document
+      #
+      # Represents an API operation (endpoint + HTTP method)
+      #
+      # An Operation contains all the information about a specific API endpoint
+      # with a specific HTTP method, including parameters, request bodies,
+      # and possible responses.
+      #
+      # @example Operation for creating a user
+      #   operation = Operation.new(
+      #     id: "create_user",
+      #     description: "Creates a new user",
+      #     parameters: {id: {name: "id", location: "path", type: "integer"}},
+      #     requests: [{name: "example", content_type: "application/json", type: "object", content: {}}],
+      #     responses: [{status: 201, content_type: "application/json", headers: {}, body: {}}]
+      #   )
+      #
+      class Operation < Data.define(:id, :description, :parameters, :requests, :responses)
+        #
+        # Creates a new operation with normalized sub-components
+        #
+        # @param id [String] Unique identifier for the operation
+        # @param description [String] Human-readable description
+        # @param parameters [Hash] Parameters by name with their details
+        # @param requests [Array<Hash>] Request body examples
+        # @param responses [Array<Hash>] Possible responses
+        #
+        # @return [Operation] A new operation instance
+        #
+        def initialize(id:, description:, parameters:, requests:, responses:)
+          parameters = parameters.each_pair.map do |name, value|
+            [name, Parameter.new(name: name.to_s, **value)]
+          end.to_h
+
+          requests = requests.map { |r| RequestBody.new(**r) }
+          responses = responses.map { |r| Response.new(**r) }
+
+          super
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/documentation/document/parameter.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    class Document
+      #
+      # Represents a parameter for an API operation
+      #
+      # Parameters can appear in various locations (path, query, header)
+      # and have different types and validation rules.
+      #
+      # @example Path parameter
+      #   Parameter.new(name: "id", location: "path", type: "integer")
+      #
+      # @example Query parameter
+      #   Parameter.new(name: "limit", location: "query", type: "integer")
+      #
+      class Parameter < Data.define(:name, :location, :type)
+      end
+    end
+  end
+end

data/lib/spec_forge/documentation/document/request_body.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    class Document
+      #
+      # Represents a request body example for an API operation
+      #
+      # Contains the content type, data structure, and example content
+      # for a request body.
+      #
+      # @example JSON request body
+      #   RequestBody.new(
+      #     name: "Create User",
+      #     content_type: "application/json",
+      #     type: "object",
+      #     content: {name: "Example User", email: "user@example.com"}
+      #   )
+      #
+      class RequestBody < Data.define(:name, :content_type, :type, :content)
+      end
+    end
+  end
+end

data/lib/spec_forge/documentation/document/response.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    class Document
+      #
+      # Represents a possible response from an API operation
+      #
+      # Contains the status code, headers, and body content
+      # with content type information.
+      #
+      # @example Success response
+      #   Response.new(
+      #     content_type: "application/json",
+      #     status: 200,
+      #     headers: {"Cache-Control" => {type: "string"}},
+      #     body: {type: "object", content: {id: {type: "integer"}}}
+      #   )
+      #
+      class Response < Data.define(:content_type, :status, :headers, :body)
+        #
+        # Creates a new response with a normalized body
+        #
+        # @param content_type [String] The content type (e.g., "application/json")
+        # @param status [Integer] The HTTP status code
+        # @param headers [Hash] Response headers with their types
+        # @param body [Hash] Response body description
+        #
+        # @return [Response] A new response instance
+        #
+        def initialize(content_type:, status:, headers:, body:)
+          body = ResponseBody.new(**body) if body.present?
+
+          super
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/documentation/document/response_body.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    class Document
+      #
+      # Represents a response body structure
+      #
+      # Contains the type and content structure of a response body.
+      #
+      # @example Object response body
+      #   ResponseBody.new(
+      #     type: "object",
+      #     content: {user: {type: "object", content: {id: {type: "integer"}}}}
+      #   )
+      #
+      # @example Array response body
+      #   ResponseBody.new(
+      #     type: "array",
+      #     content: [{type: "string"}]
+      #   )
+      #
+      class ResponseBody < Data.define(:type, :content)
+      end
+    end
+  end
+end

data/lib/spec_forge/documentation/document.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    #
+    # Represents the structured API documentation
+    #
+    # This class is the central data structure for API documentation,
+    # containing all endpoints organized by path and HTTP method.
+    # It serves as the bridge between extracted test data and generators.
+    #
+    # @example Creating a document
+    #   document = Document.new(
+    #     endpoints: {
+    #       "/users" => {
+    #         "get" => {id: "list_users", description: "List all users"...},
+    #         "post" => {id: "create_user", description: "Create a user"...}
+    #       }
+    #     }
+    #   )
+    #
+    class Document < Data.define(:endpoints)
+      #
+      # Creates a new document with normalized endpoints
+      #
+      # @param endpoints [Hash] A hash mapping paths to operations by HTTP method
+      #
+      # @return [Document] A new document instance
+      #
+      def initialize(endpoints: {})
+        endpoints = endpoints.transform_values do |operations|
+          operations.transform_keys(&:downcase)
+            .transform_values! { |op| Operation.new(**op) }
+        end
+
+        endpoints.deep_symbolize_keys!
+
+        super
+      end
+    end
+  end
+end
+
+require_relative "document/operation"
+require_relative "document/parameter"
+require_relative "document/request_body"
+require_relative "document/response"
+require_relative "document/response_body"

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    module Generators
+      #
+      # Base class for all documentation generators
+      #
+      # Provides the common interface and shared functionality for generators
+      # that transform SpecForge documents into various output formats.
+      # Subclasses implement format-specific generation logic.
+      #
+      # @example Creating a custom generator
+      #   class MyGenerator < Base
+      #     def generate
+      #       # Transform input document to custom format
+      #     end
+      #   end
+      #
+      class Base
+        #
+        # Generates documentation from test data with optional caching
+        #
+        # @param use_cache [Boolean] Whether to use cached test data if available
+        #
+        # @return [Object] The generated documentation in the target format
+        #
+        # @raise [RuntimeError] Must be implemented by subclasses
+        #
+        def self.generate(use_cache: false)
+          raise "not implemented"
+        end
+
+        #
+        # Validates the generated output according to format specifications
+        #
+        # @param input [Object] The generated documentation to validate
+        #
+        # @return [void]
+        #
+        # @raise [RuntimeError] Must be implemented by subclasses
+        #
+        def self.validate!(input)
+          raise "not implemented"
+        end
+
+        #
+        # The input document containing structured API data
+        #
+        # Contains all the endpoint information extracted from tests,
+        # organized and ready for transformation into the target format.
+        #
+        # @return [Document] The document to be processed by the generator
+        #
+        attr_reader :input
+
+        #
+        # Initializes a new generators
+        #
+        # @param input [Hash, Document] The document to generate
+        #
+        # @return [Base] A new generator instance
+        #
+        def initialize(input = {})
+          @input = input
+        end
+
+        #
+        # Generates the document into a specific format
+        #
+        # @raise [RuntimeError] Must be implemented by subclasses
+        #
+        # @return [Object] The generated document
+        #
+        def generate
+          raise "not implemented"
+        end
+      end
+    end
+  end
+end

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"