spec_forge 0.6.0 → 0.7.0

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

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