spec_forge 0.7.0 → 1.0.0

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

@@ -1,65 +0,0 @@
-# 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

@@ -1,59 +0,0 @@
-# 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

@@ -1,17 +0,0 @@
-# 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.rb

@@ -1,159 +0,0 @@
-# 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

@@ -1,33 +0,0 @@
-# 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/filter.rb

@@ -1,86 +0,0 @@
-# frozen_string_literal: true
-
-module SpecForge
-  #
-  # Provides filtering capabilities for test suites based on different criteria
-  #
-  # The Filter class allows running specific tests by filtering forges, specs,
-  # and expectations based on file name, spec name, and expectation name.
-  #
-  # @example Filtering specs by name
-  #   forges = Loader.load_from_files
-  #   filtered = Filter.apply(forges, file_name: "users", spec_name: "create_user")
-  #
-  class Filter
-    class << self
-      #
-      # Prints out a message if any of the filters were used
-      #
-      # @param forges [Array<Forge>] The collection of forges that was filtered
-      # @param file_name [String, nil] Optional file name that was used by the filter
-      # @param spec_name [String, nil] Optional spec name that was used by the filter
-      # @param expectation_name [String, nil] Optional expectation name that was used by the filter
-      #
-      def announce(forges, file_name:, spec_name:, expectation_name:)
-        filters = {file_name:, spec_name:, expectation_name:}.compact_blank
-        return if filters.size == 0
-
-        filters_display = filters.join_map(", ") { |k, v| "#{k.in_quotes} => #{v.in_quotes}" }
-
-        expectation_count = forges.sum do |forge|
-          forge.specs.sum { |spec| spec.expectations.size }
-        end
-
-        puts "Applied filter #{filters_display}"
-        puts "Found #{expectation_count} #{"expectation".pluralize(expectation_count)}"
-      end
-
-      #
-      # Filters a collection of forges based on specified criteria
-      #
-      # This method allows running specific tests by filtering forges, specs,
-      # and expectations based on file name, spec name, and expectation name.
-      # It returns only the forges, specs, and expectations that match the criteria.
-      #
-      # @param forges [Array<Forge>] The collection of forges to filter
-      # @param file_name [String, nil] Optional file name to filter by
-      # @param spec_name [String, nil] Optional spec name to filter by
-      # @param expectation_name [String, nil] Optional expectation name to filter by
-      #
-      # @return [Array<Forge>] The filtered collection of forges
-      #
-      # @raise [ArgumentError] If filtering parameters are provided in an invalid combination
-      #
-      def apply(forges, file_name: nil, spec_name: nil, expectation_name: nil)
-        # Guard against invalid partial filters
-        if expectation_name && spec_name.blank?
-          raise ArgumentError, "The spec's name is required when filtering by an expectation's name"
-        end
-
-        if spec_name && file_name.blank?
-          raise ArgumentError, "The spec's filename is required when filtering by a spec's name"
-        end
-
-        forges.filter_map do |forge|
-          specs = forge.specs.filter_map do |spec|
-            next if file_name && spec.file_name != file_name  # File filter
-            next if spec_name && spec.name != spec_name       # Name filter
-
-            # Expectation filter
-            next spec unless expectation_name
-
-            spec.expectations.select! { |e| e.name == expectation_name }
-            next if spec.expectations.empty?
-
-            spec
-          end
-
-          next if specs.empty?
-
-          forge.specs = specs
-          forge
-        end
-      end
-    end
-  end
-end

data/lib/spec_forge/normalizer/definition.rb

@@ -1,248 +0,0 @@
-# frozen_string_literal: true
-
-module SpecForge
-  class Normalizer
-    #
-    # Manages structure definitions for the Normalizer
-    #
-    # Handles loading structure definitions from YAML files, processing references
-    # between structures, and normalizing structure formats for consistent validation.
-    #
-    # @example Loading all structure definitions
-    #   structures = SpecForge::Normalizer::Definition.from_files
-    #
-    class Definition
-      #
-      # Mapping of structure names to their human-readable labels
-      #
-      # @return [Hash<Symbol, String>]
-      #
-      LABELS = {
-        factory_reference: "factory reference",
-        global_context: "global context"
-      }.freeze
-
-      #
-      # Core structure definition used to validate other structures
-      #
-      # Defines the valid attributes and types for structure definitions,
-      # creating a meta-structure that validates other structure definitions.
-      #
-      # @return [Hash]
-      #
-      STRUCTURE = {
-        type: {
-          type: [String, Array, Class],
-          default: nil,
-          validator: :present?
-        },
-        default: {
-          type: [String, NilClass, Numeric, Array, Hash, TrueClass, FalseClass],
-          required: false
-        },
-        required: {
-          type: [TrueClass, FalseClass],
-          required: false
-        },
-        aliases: {
-          type: Array,
-          required: false,
-          structure: {type: String}
-        },
-        structure: {
-          type: Hash,
-          required: false
-        },
-        validator: {
-          type: String,
-          required: false
-        }
-      }.freeze
-
-      #
-      # Loads normalizer definitions from YAML files
-      #
-      # Reads all YAML files in the normalizers directory, processes shared
-      # references, and prepares them for use by the Normalizer.
-      #
-      # @return [Hash] A hash mapping structure names to their definitions
-      #
-      def self.from_files
-        base_path = Pathname.new(File.expand_path("../normalizers", __dir__))
-        paths = Dir[base_path.join("**/*.yml")].sort
-
-        normalizers =
-          paths.each_with_object({}) do |path, hash|
-            path = Pathname.new(path)
-
-            # Include the directory name in the path to include normalizers in directories
-            name = path.relative_path_from(base_path).to_s.delete_suffix(".yml").to_sym
-
-            input = YAML.safe_load_file(path, symbolize_names: true)
-            raise Error, "Normalizer defined at #{path.to_s.in_quotes} is empty" if input.blank?
-
-            hash[name] = new(input, label: LABELS[name] || name.to_s.humanize.downcase)
-          end
-
-        # Pull the shared structures and prepare it
-        structures = normalizers.delete(:_shared).normalize
-
-        # Merge in the normalizers to allow referencing other normalizers
-        structures.merge!(normalizers.transform_values(&:input))
-
-        # Now prepare all of the other definitions with access to references
-        normalizers.transform_values!(with_key: true) do |definition, name|
-          structure = definition.normalize(structures)
-
-          {
-            label: definition.label,
-            structure:
-          }
-        end
-
-        normalizers
-      end
-
-      ##########################################################################
-
-      attr_reader :input, :label
-
-      def initialize(input, label: "")
-        @input = input
-        @label = label
-      end
-
-      #
-      # Normalizes a structure definition
-      #
-      # Processes references, resolves types, and ensures all attributes
-      # have a consistent format for validation.
-      #
-      # @param shared_structures [Hash] Optional shared structures for resolving references
-      #
-      # @return [Hash] The normalized structure definition
-      #
-      def normalize(shared_structures = {})
-        hash = @input.deep_dup
-
-        # First, we'll deeply replace any references
-        replace_references(hash, shared_structures)
-
-        # Second, normalize the root level keys
-        hash.transform_values!(with_key: true) do |attribute, name|
-          next if STRUCTURE.key?(name)
-
-          normalize_attribute(name, attribute)
-        end
-
-        # Third, normalize the underlying structures
-        hash.each do |name, attribute|
-          next unless attribute.is_a?(Hash)
-
-          structure = attribute[:structure]
-          next if structure.blank?
-
-          attribute[:structure] = normalize_structure(name, attribute)
-        end
-
-        hash
-      end
-
-      private
-
-      def replace_references(attributes, shared_structures)
-        return if shared_structures.blank?
-
-        # The goal is to walk down the hash and recursively replace any references
-        attributes.each do |attribute_name, attribute|
-          # Replace the top level reference
-          replace_with_reference(attribute_name, attribute, shared_structures:)
-          next unless attribute.is_a?(Hash) && attribute[:structure].present?
-
-          # Allow structures to reference other structures
-          if attribute.dig(:structure, :reference)
-            replace_with_reference(
-              "#{attribute_name}'s structure",
-              attribute[:structure],
-              shared_structures:
-            )
-          end
-
-          # Recursively replace any structures that have references
-          if [Array, "array"].include?(attribute[:type])
-            result = replace_references(attribute.slice(:structure), shared_structures)
-            attribute.merge!(result)
-          elsif [Hash, "hash"].include?(attribute[:type])
-            replace_references(attribute[:structure], shared_structures)
-          end
-        end
-      end
-
-      def replace_with_reference(attribute_name, attribute, shared_structures: {})
-        return unless attribute.is_a?(Hash) && attribute.key?(:reference)
-
-        reference_name = attribute.delete(:reference)
-        reference = shared_structures[reference_name.to_sym]
-
-        if reference.nil?
-          structures_names = shared_structures.keys.map(&:in_quotes).to_or_sentence
-
-          raise Error, "Attribute #{attribute_name.in_quotes}: Invalid reference name. Got #{reference_name&.in_quotes}, expected one of #{structures_names} in #{@label}"
-        end
-
-        # Allows overwriting data on the reference
-        attribute.reverse_merge!(reference)
-      end
-
-      def normalize_attribute(attribute_name, attribute)
-        case attribute
-        when String, Array # Array is multiple types
-          hash = {type: resolve_type(attribute)}
-
-          default = Normalizer.default(structure: STRUCTURE)
-          hash.merge!(default)
-        when Hash
-          hash = Normalizer.raise_errors! do
-            Normalizer.new(
-              "#{attribute_name.in_quotes} in #{@label}",
-              attribute,
-              structure: STRUCTURE
-            ).normalize
-          end
-
-          hash[:type] = resolve_type(attribute[:type])
-
-          if hash[:structure].present?
-            hash[:structure] = normalize_structure(attribute_name, hash) || {}
-          end
-
-          hash
-        else
-          raise ArgumentError, "Attribute #{attribute_name.in_quotes}: Expected String or Hash, got #{attribute.inspect}"
-        end
-      end
-
-      def normalize_structure(name, hash)
-        if hash[:type] == Array
-          normalize_attribute(name, hash[:structure])
-        elsif hash[:type] == Hash
-          hash[:structure].transform_values(with_key: true) { |v, k| normalize_attribute(k, v) }
-        end
-      end
-
-      def resolve_type(type)
-        if type == "boolean"
-          [TrueClass, FalseClass]
-        elsif type.instance_of?(Array)
-          type.map { |t| resolve_type(t) }
-        elsif type.is_a?(String)
-          type.classify.constantize
-        else
-          type
-        end
-      rescue NameError => e
-        raise Error, "#{e}. #{type.inspect} is not a valid type found in #{@label}"
-      end
-    end
-  end
-end