spec_forge 0.7.0 → 1.0.0

data/lib/spec_forge/documentation/builder.rb

@@ -3,380 +3,128 @@
 module SpecForge
   module Documentation
     #
-    # Transforms extracted test data into a structured document
+    # Builds API documentation by running blueprints and extracting endpoint data
     #
-    # This class processes raw endpoint data from tests into a hierarchical document
-    # structure suitable for rendering as API documentation.
+    # The Builder orchestrates the documentation generation process by:
+    # 1. Loading and running blueprint test files
+    # 2. Capturing request/response data from successful test executions
+    # 3. Compiling the raw data into a structured Document
     #
-    # @example Creating a document from test data
-    #   document = Builder.document_from_endpoints(endpoints)
+    # It supports caching to avoid re-running tests when blueprints haven't changed.
+    #
+    # @example Creating a document from blueprints
+    #   document = Builder.create_document!(paths: "spec/blueprints/api.yml")
+    #
+    # @example Using the builder directly for raw endpoint data
+    #   builder = Builder.new(paths: "spec/blueprints/api.yml")
+    #   endpoints = builder.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.
+      # Creates a complete Document from blueprint files
       #
-      # @api private
-      #
-      FLOAT_REGEX = /^-?\d+\.\d+$/
-
+      # This is the primary entry point for generating documentation.
+      # It instantiates a Builder, extracts endpoints, compiles them,
+      # and returns a structured Document object.
       #
-      # Creates a document from endpoint data
+      # @option base_path [String, Pathname, nil] Base directory for blueprint files
+      # @option paths [String, Pathname, nil] Specific blueprint file paths
+      # @option verbosity_level [Integer] Output verbosity (0 = silent)
+      # @option use_cache [Boolean] Whether to use cached endpoint data if available
       #
-      # @param endpoints [Array<Hash>] Array of endpoint data extracted from tests
+      # @return [Document] A structured document containing all API endpoints
       #
-      # @return [Document] A structured documentation document
+      # @raise [Error::NoBlueprintsError] If no blueprints are found
       #
-      def self.document_from_endpoints(endpoints = [])
-        new(endpoints).export_as_document
-      end
+      def self.create_document!(**)
+        endpoints = new(**).endpoints
+        endpoints = Compiler.new(endpoints).compile
 
-      #
-      # 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
+      # Creates a new Builder instance
       #
-      # @return [Hash] Endpoints grouped by path and method
+      # @param base_path [String, Pathname, nil] Base directory for blueprint files
+      # @param paths [String, Pathname, nil] Specific blueprint file paths
+      # @param verbosity_level [Integer] Output verbosity during test execution (0 = silent)
+      # @param use_cache [Boolean] Whether to use cached endpoint data if valid
       #
-      # @private
+      # @return [Builder] A new builder instance
       #
-      def group_endpoints(endpoints)
-        grouped = Hash.new_nested_hash(depth: 1)
+      def initialize(base_path: nil, paths: nil, verbosity_level: 0, use_cache: false)
+        @cache = Cache.new
 
-        # 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
+        @base_path = base_path
+        @paths = paths
+        @use_cache = use_cache
+        @verbosity_level = verbosity_level
       end
 
       #
-      # Sanitizes operations that represent error responses
+      # Extracts endpoint data from blueprint test executions
       #
-      # Removes request details from operations with 4xx/5xx responses
-      # to prevent invalid data from appearing in documentation.
+      # Runs all blueprints and captures request/response data from each
+      # successful test step. Results are cached for subsequent calls
+      # when caching is enabled.
       #
-      # @param operations [Array<Hash>] Array of operations
+      # @return [Array<Hash>] Array of endpoint data hashes containing
+      #   request and response information
       #
-      # @return [Array<Hash>] Sanitized operations
+      # @raise [Error::NoBlueprintsError] If no blueprints are found
       #
-      # @private
-      #
-      def sanitize_error_operations(operations)
-        operations.each do |operation|
-          next unless operation[:response_status] >= 400
+      def endpoints
+        return @cache.read if @use_cache && @cache.valid?
 
-          # 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
+        endpoints = capture_endpoint_data
+        @cache.create(endpoints)
 
-      #
-      # 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
+        endpoints
       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
+      private
 
-        description = operations.key_map(:expectation_name)
-          .reject(&:blank?)
-          .first
-          &.split(" - ")
-          &.second || ""
+      def capture_endpoint_data
+        # contexts will be empty until the blueprints have been ran
+        # Must be done before blueprints are loaded
+        contexts = register_callback
 
-        parameters = normalize_parameters(operations)
-        requests = normalize_requests(operations)
-        responses = normalize_responses(operations)
+        blueprints, forge_hooks = SpecForge::Loader.load_blueprints(base_path: @base_path, paths: @paths)
+        raise Error::NoBlueprintsError if blueprints.empty?
 
-        {
-          id:,
-          description:,
-          parameters:,
-          requests:,
-          responses:
-        }
+        run_blueprints(blueprints, verbosity_level: @verbosity_level, hooks: forge_hooks)
+        build_endpoints(contexts)
+      ensure
+        SpecForge.configuration.deregister_callback(:documentation_builder)
       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 = {}
+      def register_callback
+        contexts = []
 
-        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:} }
+        SpecForge.configure do |config|
+          config.register_callback(:documentation_builder) do |context|
+            next if context.failure?
 
-          parameters.merge!(params)
-        end
+            step = context.step
+            next if step.nil? || step.documentation == false
+            next unless step.request?
 
-        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
+            contexts << context.with(variables: context.variables.dup)
+          end
 
-          {
-            name: name || "Example #{index}",
-            content_type: operation[:content_type],
-            type: determine_type(content),
-            content:
-          }
+          config.after(:step, :documentation_builder)
         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
+        contexts
       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
+      def run_blueprints(blueprints, **)
+        SpecForge::Forge.ignite.run(blueprints, **)
       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
+      def build_endpoints(contexts)
+        contexts.map { |context| Extractor.new(context).extract_endpoint }
       end
     end
   end

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

@@ -13,25 +13,25 @@ module SpecForge
       # @example Operation for creating a user
       #   operation = Operation.new(
       #     id: "create_user",
-      #     description: "Creates a new user",
+      #     summary: "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)
+      class Operation < Data.define(:id, :summary, :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 summary [String] Human-readable summary
         # @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:)
+        def initialize(id:, summary:, parameters:, requests:, responses:)
           parameters = parameters.each_pair.map do |name, value|
             [name, Parameter.new(name: name.to_s, **value)]
           end.to_h

data/lib/spec_forge/documentation/document.rb

@@ -40,9 +40,3 @@ module SpecForge
     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/generator.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    #
+    # 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 < Generator
+    #     def generate
+    #       # Transform input document to custom format
+    #     end
+    #   end
+    #
+    class Generator
+      #
+      # Converts the generator's version to a semantic version object
+      #
+      # @return [SemVersion] The semantic version
+      #
+      def self.to_sem_version
+        SemVersion.new(const_get("CURRENT_VERSION"))
+      end
+
+      #
+      # 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

data/lib/spec_forge/documentation/{generators/openapi → openapi/v3_0}/error_formatter.rb

@@ -2,8 +2,8 @@
 
 module SpecForge
   module Documentation
-    module Generators
-      module OpenAPI
+    module OpenAPI
+      class V30
         #
         # Formats OpenAPI validation errors into human-readable messages
         #

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

@@ -3,7 +3,7 @@
 module SpecForge
   module Documentation
     module OpenAPI
-      module V3_0 # standard:disable Naming/ClassAndModuleCamelCase
+      class V30
         #
         # Represents an OpenAPI 3.0 Example object
         #

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

@@ -3,7 +3,7 @@
 module SpecForge
   module Documentation
     module OpenAPI
-      module V3_0 # standard:disable Naming/ClassAndModuleCamelCase
+      class V30
         #
         # Represents an OpenAPI 3.0 Media Type object
         #

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

@@ -3,7 +3,7 @@
 module SpecForge
   module Documentation
     module OpenAPI
-      module V3_0 # standard:disable Naming/ClassAndModuleCamelCase
+      class V30
         #
         # Represents an OpenAPI 3.0 Operation object
         #
@@ -12,7 +12,23 @@ module SpecForge
         #
         # @see https://spec.openapis.org/oas/v3.0.4.html#operation-object
         #
-        class Operation < OpenAPI::Base
+        class Operation
+          #
+          # The document object containing structured API data
+          #
+          # @return [Object] The document with endpoint information
+          #
+          attr_reader :document
+
+          #
+          # Creates a new Operation from a document
+          #
+          # @param document [Object] The document containing operation data
+          #
+          def initialize(document)
+            @document = document
+          end
+
           #
           # Converts the operation to an OpenAPI-compliant hash
           #
@@ -26,7 +42,7 @@ module SpecForge
               # Required
               responses:,
               security:
-            }.merge_compact(
+            }.compact_merge(
               # All optional
               tags:,
               summary:,
@@ -44,7 +60,7 @@ module SpecForge
           #
           def id
             # The object ID is added to make every ID unique
-            document.id.to_camelcase(:lower) + object_id.to_s
+            document.id + object_id.to_s
           end
 
           alias_method :operationId, :id
@@ -55,7 +71,7 @@ module SpecForge
           # @return [String, nil] Brief operation summary
           #
           def summary
-            document.id.humanize
+            document.summary
           end
 
           #
@@ -64,7 +80,7 @@ module SpecForge
           # @return [String] Detailed operation description
           #
           def description
-            document.description
+            ""
           end
 
           #