spec_forge 0.7.1 → 1.0.0

data/lib/spec_forge/documentation/openapi/v3_0/response.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 Response object
         #
@@ -12,7 +12,23 @@ module SpecForge
         #
         # @see https://spec.openapis.org/oas/v3.0.4.html#response-object
         #
-        class Response < OpenAPI::Base
+        class Response
+          #
+          # The document object containing structured API data
+          #
+          # @return [Object] The document with endpoint information
+          #
+          attr_reader :document
+
+          #
+          # Creates a new Response from a document
+          #
+          # @param document [Object] The document containing response data
+          #
+          def initialize(document)
+            @document = document
+          end
+
           #
           # Converts the response to an OpenAPI-compliant hash
           #
@@ -38,10 +54,12 @@ module SpecForge
           # Creates media type objects with schemas and merges with any
           # documentation-provided content definitions.
           #
-          # @return [Hash] Content definitions by media type
+          # @return [Hash, nil] Content definitions by media type
           #
           def content
-            schema = Schema.new(type: document.body.type).to_h
+            return nil if document.content_type.blank?
+
+            schema = Schema.new(type: document.body.type, content: document.body.content).to_h
 
             {
               document.content_type => MediaType.new(schema:).to_h
@@ -51,12 +69,16 @@ module SpecForge
           #
           # Returns header definitions for the response
           #
-          # Merges document headers with documentation-provided headers.
+          # Transforms document headers into OpenAPI format with schema wrappers.
           #
           # @return [Hash, nil] Header definitions
           #
           def headers
-            document.headers.presence
+            return nil if document.headers.blank?
+
+            document.headers.transform_values do |header|
+              {schema: header}
+            end
           end
         end
       end

data/lib/spec_forge/documentation/openapi/v3_0/schema.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 Schema object
         #
@@ -27,16 +27,25 @@ module SpecForge
           #
           attr_reader :format
 
+          #
+          # The schema content (for arrays/objects)
+          #
+          # @return [Object, nil] The schema content
+          #
+          attr_reader :content
+
           #
           # Creates a new OpenAPI schema object
           #
           # @param options [Hash] Schema configuration options
           # @option options [String] :type The data type to convert to OpenAPI format
+          # @option options [Object] :content The content/items for arrays or properties for objects
           #
           # @return [Schema] A new schema instance
           #
           def initialize(options = {})
             @type, @format = transform_type(options[:type])
+            @content = options[:content]
           end
 
           #
@@ -45,10 +54,19 @@ module SpecForge
           # @return [Hash] OpenAPI-formatted schema object
           #
           def to_h
-            {
+            base = {
               type:,
               format:
             }.compact_blank!
+
+            # Add items for arrays
+            if type == "array" && content.present?
+              # Content is an array like [{type: "string"}], take first element as items schema
+              items_type = content.first&.dig(:type) || "object"
+              base[:items] = {type: items_type}
+            end
+
+            base
           end
 
           private

data/lib/spec_forge/documentation/openapi/v3_0/tag.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 Tag object
         #

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

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    module OpenAPI
+      # https://spec.openapis.org/oas/v3.0.4.html
+      class V30 < Generator
+        #
+        # Current OpenAPI 3.0 version supported by this generator
+        #
+        # @api private
+        #
+        CURRENT_VERSION = "3.0.4"
+
+        #
+        # 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
+
+        #
+        # 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|
+              Operation.new(document).to_h
+            end
+          end
+        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

data/lib/spec_forge/documentation/openapi.rb

@@ -3,21 +3,49 @@
 module SpecForge
   module Documentation
     #
-    # OpenAPI documentation generation functionality
+    # OpenAPI specification generation and version management
     #
-    # Contains classes and modules for generating OpenAPI specifications
-    # from SpecForge test data. Supports multiple OpenAPI versions.
+    # Provides version-aware access to OpenAPI generators and validators.
+    # Supports multiple OpenAPI versions through semantic versioning matching.
     #
     module OpenAPI
+      #
+      # Current OpenAPI version used as default
+      #
+      # Points to the latest supported OpenAPI version for new specifications.
+      #
+      # @api private
+      #
+      CURRENT_VERSION = V30::CURRENT_VERSION
+
+      #
+      # Mapping of semantic versions to their generator classes
+      #
+      # @return [Hash{SemVersion => Class}]
+      #
+      VERSIONS = {
+        V30.to_sem_version => V30
+      }.freeze
+
+      #
+      # Returns the generator class for the specified OpenAPI version
+      #
+      # @param version [String, SemVersion] The OpenAPI version (e.g., "3.0")
+      #
+      # @return [Class] The generator class for the requested version
+      #
+      # @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
-
-require_relative "openapi/base"
-
-require_relative "openapi/v3_0/example"
-require_relative "openapi/v3_0/media_type"
-require_relative "openapi/v3_0/operation"
-require_relative "openapi/v3_0/response"
-require_relative "openapi/v3_0/schema"
-require_relative "openapi/v3_0/tag"

data/lib/spec_forge/documentation.rb

@@ -14,14 +14,8 @@ module SpecForge
   #
   #   # Programmatically
   #   document = Documentation::Loader.load_document
-  #   spec = Documentation::Generators::OpenAPI["3.0"].new(document).generate
+  #   spec = Documentation::OpenAPI["3.0"].new(document).generate
   #
   module Documentation
   end
 end
-
-require_relative "documentation/builder"
-require_relative "documentation/document"
-require_relative "documentation/loader"
-require_relative "documentation/openapi"
-require_relative "documentation/generators"

data/lib/spec_forge/error.rb

@@ -5,17 +5,6 @@ module SpecForge
   # Base error class for all SpecForge-specific exceptions
   #
   class Error < StandardError
-    # Pass into to_sentence
-    OR_CONNECTOR = {
-      last_word_connector: ", or ",
-      two_words_connector: " or ",
-      # This is a minor performance improvement to avoid locales being loaded
-      # This will need to be removed if locales are added
-      locale: false
-    }.freeze
-
-    private_constant :OR_CONNECTOR
-
     #
     # Raised when a provided Faker class name doesn't exist
     # Provides helpful suggestions for similar class names
@@ -40,7 +29,7 @@ module SpecForge
         super(<<~STRING.chomp
           Undefined Faker class "#{input}". #{DidYouMean::Formatter.message_for(corrections)}
 
-          For available classes, please check https://github.com/faker-ruby/faker#generators.
+          For available classes, please check https://github.com/faker-ruby/faker/blob/main/GENERATORS.md.
         STRING
         )
       end
@@ -74,12 +63,30 @@ module SpecForge
     # Indicates when a transform name isn't supported
     #
     class InvalidTransformFunctionError < Error
-      def initialize(input)
-        # TODO: Update link to docs
+      def initialize(input, valid_functions)
+        formatted_functions = valid_functions.join_map(", ") { |f| "transform.#{f}".in_quotes }
+
         super(<<~STRING.chomp
           Undefined transform function "#{input}".
 
-          For available functions, please check https://github.com/itsthedevman/spec_forge.
+          Valid functions: #{formatted_functions}
+        STRING
+        )
+      end
+    end
+
+    #
+    # Raised when an unknown generation function is referenced
+    # Indicates when a generation name isn't supported
+    #
+    class InvalidGenerateFunctionError < Error
+      def initialize(input, valid_functions)
+        formatted_functions = valid_functions.join_map(", ") { |f| "generate.#{f}".in_quotes }
+
+        super(<<~STRING.chomp
+          Undefined generate function "#{input}".
+
+          Valid functions: #{formatted_functions}
         STRING
         )
       end
@@ -151,23 +158,48 @@ module SpecForge
     class InvalidTypeError < Error
       def initialize(object, expected_type, **opts)
         if expected_type.instance_of?(Array)
-          expected_type = expected_type.to_sentence(**OR_CONNECTOR)
+          expected_type = expected_type.to_or_sentence
         end
 
         message = "Expected #{expected_type}, got #{object.class}"
         message += " for #{opts[:for]}" if opts[:for].present?
 
+        if opts[:description] || opts[:examples]
+          message += "\n"
+
+          if opts[:description]
+            message += "\nAbout #{opts[:attribute_name].in_quotes}:"
+            message += "\n  #{opts[:description].gsub("\n", "\n  ")}"
+          end
+
+          if opts[:examples].present?
+            message += "\n\nExamples:\n  #{opts[:examples].join("\n\n").gsub("\n", "\n  ")}"
+          end
+        end
+
         super(message)
       end
     end
 
     #
-    # Raised when a variable reference cannot be resolved
-    # Indicates when a spec or expectation references an undefined variable
+    # Raised when a referenced variable is not defined in the current context
+    #
+    # Provides helpful suggestions for similar variable names using spell checking.
     #
     class MissingVariableError < Error
-      def initialize(variable_name)
-        super("Undefined variable \"#{variable_name}\" referenced in expectation")
+      def initialize(variable_name, available_variables: [])
+        message = "Undefined variable \"#{variable_name}\""
+
+        checker = DidYouMean::SpellChecker.new(dictionary: available_variables)
+        suggestions = checker.correct(variable_name.to_s)
+
+        message += ". #{DidYouMean::Formatter.message_for(suggestions)}" if suggestions.size > 0
+
+        if available_variables.size > 0 && available_variables.size <= 5
+          message += ".\nAvailable: #{available_variables.join_map(", ", &:in_quotes)}"
+        end
+
+        super(message)
       end
     end
 
@@ -195,7 +227,7 @@ module SpecForge
     #
     class InvalidBuildStrategy < Error
       def initialize(build_strategy)
-        valid_strategies = Attribute::Factory::BUILD_STRATEGIES.to_sentence(**OR_CONNECTOR)
+        valid_strategies = Attribute::Factory::BUILD_STRATEGIES.to_or_sentence
 
         super(<<~STRING.chomp
           Unknown build strategy "#{build_strategy}" referenced in spec.
@@ -207,37 +239,53 @@ module SpecForge
     end
 
     #
-    # Raised when a spec file cannot be loaded
-    # Provides detailed information about the cause of the loading error
+    # Raised when a step has an invalid configuration
     #
-    class SpecLoadError < Error
-      def initialize(error, file_path, spec: nil)
-        message =
-          if spec
-            "Error loading spec #{spec[:name].in_quotes} in file #{file_path.in_quotes} (line #{spec[:line_number]})"
-          else
-            "Error loading spec file #{file_path.in_quotes}"
-          end
-
-        causes = error.message.split("\n").map(&:strip).reject(&:empty?)
+    # Common cases:
+    # - Action attributes (request, expect, call, debug, store) combined with steps
+    # - Expects defined without a corresponding request
+    #
+    class InvalidStepError < Error
+      def initialize(message, step = nil)
+        if step
+          step_name = step[:name].presence || "(unnamed)"
 
-        message +=
-          if causes.size > 1
-            "\nCauses:\n  - #{causes.join_map("\n  - ")}"
+          line_info = if (source = step[:source])
+            "#{source[:file_name]}:#{source[:line_number]}"
           else
-            "\nCause: #{error}"
+            "unknown location"
           end
 
+          message = "Step #{step_name.in_quotes} [#{line_info}]: #{message}"
+        end
+
         super(message)
       end
     end
 
     #
-    # Raised when the provided namespace is not defined on the global context
+    # Raised when an error occurs while loading a step during blueprint processing
+    #
+    # Wraps the original error with step context information to help identify
+    # which step caused the problem.
     #
-    class InvalidGlobalNamespaceError < Error
-      def initialize(provided_namespace)
-        super("Invalid global namespace #{provided_namespace.in_quotes}. Currently supported namespaces are: \"variables\"")
+    class LoadStepError < Error
+      def initialize(error, step, depth = 0)
+        step_name = step[:name].presence || "(unnamed)"
+
+        line_info = if (source = step[:source])
+          "#{source[:file_name]}:#{source[:line_number]}"
+        end
+
+        message = "Step: #{step_name.in_quotes} [#{line_info}]"
+
+        cause_message = if error.is_a?(LoadStepError)
+          "\n#{error.message}"
+        else
+          "\n\nCaused by: \n  #{error.message.gsub("\n", "\n  ")}"
+        end
+
+        super(message + cause_message)
       end
     end
 
@@ -317,5 +365,131 @@ module SpecForge
     #
     class InvalidOASDocument < Error
     end
+
+    #
+    # Raised when one or more expectations fail during step execution
+    #
+    # Contains the list of failed RSpec examples for reporting purposes.
+    #
+    class ExpectationFailure < Error
+      attr_reader :failed_examples
+
+      def initialize(failed_examples)
+        @failed_examples = failed_examples
+
+        super("Failed expectations (#{@failed_examples.size})")
+      end
+    end
+
+    #
+    # Raised when JSON shape validation fails
+    #
+    # Contains structured failure information for all validation errors
+    # discovered during shape checking.
+    #
+    # @example Single failure
+    #   failures = [{path: ".id", expected_type: String, actual_type: Integer, actual_value: 42}]
+    #   raise SchemaValidationFailure.new(failures)
+    #
+    # @example Multiple failures
+    #   failures = [
+    #     {path: ".id", expected_type: String, actual_type: Integer, actual_value: 42},
+    #     {path: ".email", expected_type: String, actual_type: NilClass, actual_value: nil}
+    #   ]
+    #   raise SchemaValidationFailure.new(failures)
+    #
+    class SchemaValidationFailure < Error
+      attr_reader :failures
+
+      def initialize(failures)
+        @failures = failures
+
+        message =
+          if failures.size == 1
+            format_failure(failures.first)
+          else
+            failures.join_map("\n") do |failure|
+              format_failure(failure)
+            end
+          end
+
+        super(message)
+      end
+
+      private
+
+      def format_failure(failure)
+        expected_types =
+          if failure[:expected_type].size == 1
+            failure[:expected_type].first
+          else
+            failure[:expected_type].to_or_sentence
+          end
+
+        "#{failure[:path]}: expected #{expected_types}, got #{failure[:actual_type]} (#{failure[:actual_value].inspect})"
+      end
+    end
+
+    #
+    # Raised when JSON content validation fails
+    #
+    # Contains structured failure information for content mismatches.
+    #
+    class ContentValidationFailure < Error
+      attr_reader :failures
+
+      def initialize(failures)
+        @failures = failures
+        super(format_failures(failures))
+      end
+
+      private
+
+      def format_failures(failures)
+        if failures.size == 1
+          failure = failures.first
+          "#{failure[:path]}: #{failure[:message]}"
+        else
+          failures.join_map("\n") { |f| "#{f[:path]}: #{f[:message]}" }
+        end
+      end
+    end
+
+    #
+    # Raised when HTTP header validation fails
+    #
+    # Contains structured failure information for header mismatches.
+    #
+    class HeaderValidationFailure < Error
+      attr_reader :failures
+
+      def initialize(failures)
+        @failures = failures
+        super(format_failures(failures))
+      end
+
+      private
+
+      def format_failures(failures)
+        if failures.size == 1
+          failure = failures.first
+          "#{failure[:header].in_quotes}: #{failure[:message]}"
+        else
+          failures.join_map("\n") { |f| "#{f[:header].in_quotes}: #{f[:message]}" }
+        end
+      end
+    end
+
+    #
+    # Raised when no blueprints are found during loading
+    #
+    # This typically occurs when attempting to generate documentation
+    # but the blueprints directory is empty or doesn't contain valid files.
+    #
+    class NoBlueprintsError < Error
+      def initialize
+        super("No blueprints found. Please ensure your blueprints directory contains valid blueprint files.")
+      end
+    end
   end
 end