spec_forge 0.5.0 → 0.7.0

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

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    module OpenAPI
+      #
+      # Base class for OpenAPI documentation objects
+      #
+      # Provides common functionality for OpenAPI specification objects
+      # like operations, responses, and schemas.
+      #
+      class Base
+        #
+        # The document object containing structured API data
+        #
+        # @return [Object] The document with endpoint information
+        #
+        attr_reader :document
+
+        #
+        # Creates a new OpenAPI base object
+        #
+        # @param document [Object] The document object containing API data
+        #
+        # @return [Base] A new base instance
+        #
+        def initialize(document)
+          @document = document
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    module OpenAPI
+      module V3_0 # standard:disable Naming/ClassAndModuleCamelCase
+        #
+        # Represents an OpenAPI 3.0 Example object
+        #
+        # Creates example objects for request/response documentation with
+        # optional summary, description, and external reference support.
+        #
+        # @see https://spec.openapis.org/oas/v3.0.4.html#example-object
+        #
+        class Example < Data.define(:summary, :description, :value, :external_value)
+          #
+          # Creates a new OpenAPI example object
+          #
+          # @param summary [String, nil] Brief summary of the example's purpose
+          # @param description [String, nil] Detailed description of the example
+          # @param value [Object, nil] The actual example value
+          # @param external_value [String, nil] URL pointing to the example value
+          #
+          # @return [Example] A new example instance
+          #
+          def initialize(summary: nil, description: nil, value: nil, external_value: nil)
+            super
+          end
+
+          #
+          # Converts the example to an OpenAPI-compliant hash
+          #
+          # @return [Hash] OpenAPI-formatted example object
+          #
+          def to_h
+            super
+              .rename_key_unordered!(:external_value, :externalValue)
+              .compact_blank!
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    module OpenAPI
+      module V3_0 # standard:disable Naming/ClassAndModuleCamelCase
+        #
+        # Represents an OpenAPI 3.0 Media Type object
+        #
+        # Handles media type definitions for request and response bodies,
+        # including schema definitions, examples, and encoding information.
+        #
+        # @see https://spec.openapis.org/oas/v3.0.4.html#media-type-object
+        #
+        class MediaType < Data.define(:schema, :example, :examples, :encoding)
+          #
+          # Creates a new OpenAPI media type object
+          #
+          # @param schema [Hash, nil] Schema definition for the media type
+          # @param example [Object, nil] Single example value
+          # @param examples [Hash, nil] Multiple named examples
+          # @param encoding [Hash, nil] Encoding information for the media type
+          #
+          # @return [MediaType] A new media type instance
+          #
+          def initialize(schema: nil, example: nil, examples: nil, encoding: nil)
+            super
+          end
+
+          #
+          # Converts the media type to an OpenAPI-compliant hash
+          #
+          # @return [Hash] OpenAPI-formatted media type object
+          #
+          def to_h
+            super.compact_blank!
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    module OpenAPI
+      module V3_0 # standard:disable Naming/ClassAndModuleCamelCase
+        #
+        # Represents an OpenAPI 3.0 Operation object
+        #
+        # Handles the complete definition of API operations including parameters,
+        # request bodies, responses, and security requirements for OpenAPI specs.
+        #
+        # @see https://spec.openapis.org/oas/v3.0.4.html#operation-object
+        #
+        class Operation < OpenAPI::Base
+          #
+          # Converts the operation to an OpenAPI-compliant hash
+          #
+          # Builds the complete operation object with all required and optional
+          # fields properly formatted for OpenAPI specification.
+          #
+          # @return [Hash] OpenAPI-formatted operation object
+          #
+          def to_h
+            {
+              # Required
+              responses:,
+              security:
+            }.merge_compact(
+              # All optional
+              tags:,
+              summary:,
+              description:,
+              operationId:,
+              parameters:,
+              requestBody:
+            )
+          end
+
+          #
+          # Returns the operation's unique identifier
+          #
+          # @return [String] The operation ID
+          #
+          def id
+            # The object ID is added to make every ID unique
+            document.id.to_camelcase(:lower) + object_id.to_s
+          end
+
+          alias_method :operationId, :id
+
+          #
+          # Returns a human-readable summary of the operation
+          #
+          # @return [String, nil] Brief operation summary
+          #
+          def summary
+            document.id.humanize
+          end
+
+          #
+          # Returns detailed description of the operation
+          #
+          # @return [String] Detailed operation description
+          #
+          def description
+            document.description
+          end
+
+          #
+          # Returns security requirements for the operation
+          #
+          # @return [Array] Array of security requirement objects
+          #
+          def security
+            # User defined
+            []
+          end
+
+          #
+          # Returns tags for categorizing the operation
+          #
+          # @return [Array] Array of tag names
+          #
+          def tags
+            # User defined
+            []
+          end
+
+          #
+          # Returns parameter definitions for the operation
+          #
+          # Transforms document parameters into OpenAPI parameter objects
+          # with proper schema types and location information.
+          #
+          # @return [Array] Array of parameter objects
+          #
+          def parameters
+            document.parameters.values.map do |parameter|
+              schema = Schema.new(type: parameter.type).to_h
+
+              {
+                schema:,
+                name: parameter.name,
+                in: parameter.location,
+                required: parameter.location == "path" || false
+              }
+            end
+          end
+
+          #
+          # Returns request body definition for the operation
+          #
+          # Groups requests by content type and creates proper OpenAPI
+          # request body object with examples and schemas.
+          #
+          # @return [Hash, nil] Request body object
+          #
+          def request_body
+            requests = document.requests
+            return if requests.blank?
+
+            requests = requests.group_by(&:content_type)
+
+            content =
+              requests.transform_values do |grouped_requests|
+                media_type_from_requests(grouped_requests)
+              end
+
+            {
+              description: "",
+              content:
+            }
+          end
+
+          alias_method :requestBody, :request_body
+
+          #
+          # Returns response definitions for the operation
+          #
+          # Groups responses by status code and transforms them into
+          # OpenAPI response objects with proper formatting.
+          #
+          # @return [Hash] Hash mapping status codes to response objects
+          #
+          def responses
+            document.responses
+              .group_by(&:status)
+              .transform_values! do |responses|
+                response = responses.first
+                Response.new(response).to_h
+              end
+          end
+
+          private
+
+          def media_type_from_requests(requests)
+            request = requests.first
+            schema = Schema.new(type: request.type, content: request.content).to_h
+
+            examples =
+              requests.to_h do |request|
+                example_name = request.name.to_camelcase(:lower)
+                example = Example.new(summary: request.name, value: request.content).to_h
+
+                [example_name, example]
+              end
+
+            MediaType.new(schema:, examples:).to_h
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    module OpenAPI
+      module V3_0 # standard:disable Naming/ClassAndModuleCamelCase
+        #
+        # Represents an OpenAPI 3.0 Response object
+        #
+        # Handles response definitions including status descriptions, content types,
+        # headers, and links for OpenAPI specifications.
+        #
+        # @see https://spec.openapis.org/oas/v3.0.4.html#response-object
+        #
+        class Response < OpenAPI::Base
+          #
+          # Converts the response to an OpenAPI-compliant hash
+          #
+          # Builds the complete response object with required description and
+          # optional content, headers, and links.
+          #
+          # @return [Hash] OpenAPI-formatted response object
+          #
+          def to_h
+            {
+              # Required
+              description: "",
+              content:
+            }.merge_compact(
+              # Optional
+              headers:
+            )
+          end
+
+          #
+          # Returns content definitions for the response
+          #
+          # Creates media type objects with schemas and merges with any
+          # documentation-provided content definitions.
+          #
+          # @return [Hash] Content definitions by media type
+          #
+          def content
+            schema = Schema.new(type: document.body.type).to_h
+
+            {
+              document.content_type => MediaType.new(schema:).to_h
+            }
+          end
+
+          #
+          # Returns header definitions for the response
+          #
+          # Merges document headers with documentation-provided headers.
+          #
+          # @return [Hash, nil] Header definitions
+          #
+          def headers
+            document.headers.presence
+          end
+        end
+      end
+    end
+  end
+end