spec_forge 0.5.0 → 0.7.0

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    module OpenAPI
+      module V3_0 # standard:disable Naming/ClassAndModuleCamelCase
+        #
+        # Represents an OpenAPI 3.0 Schema object
+        #
+        # Handles schema definitions for data types, converting internal type
+        # representations to OpenAPI-compliant schema objects.
+        #
+        # @see https://spec.openapis.org/oas/v3.0.4.html#schema-object
+        #
+        class Schema
+          #
+          # The schema type (string, integer, object, etc.)
+          #
+          # @return [String, nil] The OpenAPI schema type
+          #
+          attr_reader :type
+
+          #
+          # The schema format (date-time, int64, etc.)
+          #
+          # @return [String, nil] The OpenAPI schema format
+          #
+          attr_reader :format
+
+          #
+          # Creates a new OpenAPI schema object
+          #
+          # @param options [Hash] Schema configuration options
+          # @option options [String] :type The data type to convert to OpenAPI format
+          #
+          # @return [Schema] A new schema instance
+          #
+          def initialize(options = {})
+            @type, @format = transform_type(options[:type])
+          end
+
+          #
+          # Converts the schema to an OpenAPI-compliant hash
+          #
+          # @return [Hash] OpenAPI-formatted schema object
+          #
+          def to_h
+            {
+              type:,
+              format:
+            }.compact_blank!
+          end
+
+          private
+
+          def transform_type(format)
+            case format
+            when "datetime", "time"
+              ["string", "date-time"]
+            when "int64", "i64"
+              ["integer", "int64"]
+            when "int32", "i32"
+              ["integer", "int32"]
+            when "double", "float"
+              ["number", format]
+            when "object"
+              ["object"]
+            when "array"
+              ["array"]
+            when "boolean", "number", "integer", "string"
+              [format]
+            else
+              ["string", format]
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    module OpenAPI
+      module V3_0 # standard:disable Naming/ClassAndModuleCamelCase
+        #
+        # Represents an OpenAPI 3.0 Tag object
+        #
+        # Handles tag definitions for categorizing and organizing API operations
+        # with optional descriptions and external documentation links.
+        #
+        # @see https://spec.openapis.org/oas/v3.0.4.html#tag-object
+        #
+        class Tag < Data.define(:name, :description, :external_docs)
+          #
+          # Creates a tag object from name and data
+          #
+          # Handles both string descriptions and hash configurations with
+          # external documentation references.
+          #
+          # @param name [String, Symbol] The tag name
+          # @param data [String, Hash] Either a description string or full config hash
+          #
+          # @return [Tag] A new tag instance
+          #
+          def self.parse(name, data)
+            name = name.to_s
+
+            case data
+            when String
+              description = data
+            when Hash
+              description = data[:description]
+              external_docs = data[:external_docs]
+            end
+
+            new(name:, description:, external_docs:)
+          end
+
+          #
+          # Creates a new OpenAPI tag object
+          #
+          # @param name [String] The tag name
+          # @param description [String, nil] Optional tag description
+          # @param external_docs [Hash, nil] Optional external documentation reference
+          #
+          # @return [Tag] A new tag instance
+          #
+          def initialize(name:, description: nil, external_docs: nil)
+            super
+          end
+
+          #
+          # Converts the tag to an OpenAPI-compliant hash
+          #
+          # Transforms internal attribute names to match OpenAPI specification
+          # and removes any blank values for clean output.
+          #
+          # @return [Hash] OpenAPI-formatted tag object
+          #
+          def to_h
+            super
+              .rename_key_unordered!(:external_docs, :externalDocs)
+              .compact_blank!
+          end
+        end
+      end
+    end
+  end
+end

data/lib/spec_forge/documentation/openapi.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module SpecForge
+  module Documentation
+    #
+    # OpenAPI documentation generation functionality
+    #
+    # Contains classes and modules for generating OpenAPI specifications
+    # from SpecForge test data. Supports multiple OpenAPI versions.
+    #
+    module OpenAPI
+    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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module SpecForge
+  #
+  # API documentation generation functionality
+  #
+  # This module provides tools for extracting API documentation from SpecForge
+  # test files and generating various output formats like OpenAPI specifications.
+  # It handles the complete pipeline from test execution to documentation rendering.
+  #
+  # @example Generating OpenAPI documentation
+  #   # From CLI
+  #   spec_forge docs generate
+  #
+  #   # Programmatically
+  #   document = Documentation::Loader.load_document
+  #   spec = Documentation::Generators::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

@@ -1,150 +1,321 @@
 # frozen_string_literal: true
 
 module SpecForge
-  # 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
-
-  class Error < StandardError; end
-
   #
-  # Raised by Attribute::Faker when a provided classname does not exist in Faker
+  # Base error class for all SpecForge-specific exceptions
   #
-  class InvalidFakerClassError < Error
-    CLASS_CHECKER = DidYouMean::SpellChecker.new(
-      dictionary: Faker::Base.descendants.map { |c| c.to_s.downcase.gsub!("::", ".") }
-    )
+  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
 
-    def initialize(input)
-      corrections = CLASS_CHECKER.correct(input)
+    private_constant :OR_CONNECTOR
 
-      super(<<~STRING.chomp
-        Undefined Faker class "#{input}". #{DidYouMean::Formatter.message_for(corrections)}
-
-        For available classes, please check https://github.com/faker-ruby/faker#generators.
-      STRING
+    #
+    # Raised when a provided Faker class name doesn't exist
+    # Provides helpful suggestions for similar class names
+    #
+    # @example
+    #   Attribute::Faker.new("faker.invalid.method")
+    #   # => InvalidFakerClassError: Undefined Faker class "invalid". Did you mean? name, games, ...
+    #
+    class InvalidFakerClassError < Error
+      #
+      # A spell checker for Faker classes
+      #
+      # @return [DidYouMean::SpellChecker]
+      #
+      CLASS_CHECKER = DidYouMean::SpellChecker.new(
+        dictionary: Faker::Base.descendants.map { |c| c.to_s.downcase.gsub!("::", ".") }
       )
+
+      def initialize(input)
+        corrections = CLASS_CHECKER.correct(input)
+
+        super(<<~STRING.chomp
+          Undefined Faker class "#{input}". #{DidYouMean::Formatter.message_for(corrections)}
+
+          For available classes, please check https://github.com/faker-ruby/faker#generators.
+        STRING
+        )
+      end
     end
-  end
 
-  #
-  # Raised by Attribute::Faker when a provided method for a Faker class does not exist.
-  #
-  class InvalidFakerMethodError < Error
-    def initialize(input, klass)
-      spell_checker = DidYouMean::SpellChecker.new(dictionary: klass.public_methods)
-      corrections = spell_checker.correct(input)
+    #
+    # Raised when a provided method for a Faker class doesn't exist
+    # Provides helpful suggestions for similar method names
+    #
+    # @example
+    #   Attribute::Faker.new("faker.name.invlaid")
+    #   # => InvalidFakerMethodError: Undefined Faker method "invlaid" for "Faker::Name".
+    #                                 Did you mean? first_name, last_name, ...
+    #
+    class InvalidFakerMethodError < Error
+      def initialize(input, klass)
+        spell_checker = DidYouMean::SpellChecker.new(dictionary: klass.public_methods)
+        corrections = spell_checker.correct(input)
 
-      super(<<~STRING.chomp
-        Undefined Faker method "#{input}" for "#{klass}". #{DidYouMean::Formatter.message_for(corrections)}
+        super(<<~STRING.chomp
+          Undefined Faker method "#{input}" for "#{klass}". #{DidYouMean::Formatter.message_for(corrections)}
 
-        For available methods for this class, please check https://github.com/faker-ruby/faker#generators.
-      STRING
-      )
+          For available methods for this class, please check https://github.com/faker-ruby/faker#generators.
+        STRING
+        )
+      end
     end
-  end
 
-  #
-  # Raised by Attribute::Transform when the provided transform function is not valid
-  #
-  class InvalidTransformFunctionError < Error
-    def initialize(input)
-      # TODO: Update link to docs
-      super(<<~STRING.chomp
-        Undefined transform function "#{input}".
-
-        For available functions, please check https://github.com/itsthedevman/spec_forge.
-      STRING
-      )
+    #
+    # Raised when an unknown transform function is referenced
+    # Indicates when a transform name isn't supported
+    #
+    class InvalidTransformFunctionError < Error
+      def initialize(input)
+        # TODO: Update link to docs
+        super(<<~STRING.chomp
+          Undefined transform function "#{input}".
+
+          For available functions, please check https://github.com/itsthedevman/spec_forge.
+        STRING
+        )
+      end
     end
-  end
 
-  #
-  # Raised by Attribute::Chainable when an step in the invocation chain is invalid
-  #
-  class InvalidInvocationError < Error
-    def initialize(step, object)
-      valid_operations =
-        case object
-        when ArrayLike
-          "Array index (0, 1, 2, etc.) or any Array methods (first, last, size, etc.)"
-        when HashLike
-          "Any Hash key: #{object.keys.join(", ")}"
-        else
-          "Any method available on #{object.class}"
+    #
+    # Raised when a step in an invocation chain is invalid
+    # Provides detailed information about where in the chain the error occurred
+    #
+    # @example
+    #   variable_attr = Attribute::Variable.new("variables.user.invalid_method")
+    #   variable_attr.resolved
+    #   # => InvalidInvocationError: Cannot invoke "invalid_method" on User
+    #
+    class InvalidInvocationError < Error
+      def initialize(step, object, resolution_path = {})
+        @step = step
+        @object = object
+        @resolution_path = resolution_path
+
+        object_class =
+          case object
+          when Data
+            object.class.name || "Data"
+          when Struct
+            object.class.name || "Struct"
+          else
+            object.class
+          end
+
+        super(<<~STRING.chomp
+          Cannot invoke "#{step}" on #{object_class}
+          #{resolution_path_message}
+        STRING
+        )
+      end
+
+      #
+      # Creates a new InvalidInvocationError with a new resolution path
+      #
+      # @param path [Hash] The steps taken up until this point
+      #
+      def with_resolution_path(path)
+        self.class.new(@step, @object, path)
+      end
+
+      private
+
+      def resolution_path_message
+        return "" if @resolution_path.empty?
+
+        message =
+          @resolution_path.map.with_index do |(path, description), index|
+            "#{index + 1}. #{path} --> #{description}"
+          end.join("\n")
+
+        "\nResolution path:\n#{message}"
+      end
+    end
+
+    #
+    # An extended version of TypeError with better error messages
+    # Makes it easier to understand type mismatches in the codebase
+    #
+    # @example
+    #   raise Error::InvalidTypeError.new(123, String, for: "name parameter")
+    #   # => Expected String, got Integer for name parameter
+    #
+    class InvalidTypeError < Error
+      def initialize(object, expected_type, **opts)
+        if expected_type.instance_of?(Array)
+          expected_type = expected_type.to_sentence(**OR_CONNECTOR)
         end
 
-      super(<<~STRING.chomp
-        Cannot invoke "#{step}" on #{object.class}.
+        message = "Expected #{expected_type}, got #{object.class}"
+        message += " for #{opts[:for]}" if opts[:for].present?
 
-        Valid operations include: #{valid_operations}
-      STRING
-      )
+        super(message)
+      end
     end
-  end
 
-  #
-  # An extended version of TypeError to make things easier when reporting invalid types
-  #
-  class InvalidTypeError < Error
-    def initialize(object, expected_type, **opts)
-      if expected_type.instance_of?(Array)
-        expected_type = expected_type.to_sentence(**OR_CONNECTOR)
+    #
+    # Raised when a variable reference cannot be resolved
+    # Indicates when a spec or expectation references an undefined variable
+    #
+    class MissingVariableError < Error
+      def initialize(variable_name)
+        super("Undefined variable \"#{variable_name}\" referenced in expectation")
       end
+    end
 
-      message = "Expected #{expected_type}, got #{object.class}"
-      message += " for #{opts[:for]}" if opts[:for].present?
+    #
+    # Raised when a YAML structure doesn't match expectations
+    # Acts as a container for multiple validation errors
+    #
+    class InvalidStructureError < Error
+      def initialize(errors)
+        message = errors.to_a.join_map("\n") do |error|
+          next error if error.is_a?(SpecForge::Error)
+
+          # Normal errors, let's get verbose
+          backtrace = SpecForge.backtrace_cleaner.clean(error.backtrace)
+          "#{error.inspect}\n  # ./#{backtrace.join("\n  # ./")}\n"
+        end
 
-      super(message)
+        super(message)
+      end
     end
-  end
 
-  #
-  # Raised by Attribute::Variable when the provided variable name is not defined
-  #
-  class MissingVariableError < Error
-    def initialize(variable_name)
-      super("Undefined variable \"#{variable_name}\" referenced in expectation")
+    #
+    # Raised when an unknown factory build strategy is provided
+    # Indicates when a strategy string doesn't match supported options
+    #
+    class InvalidBuildStrategy < Error
+      def initialize(build_strategy)
+        valid_strategies = Attribute::Factory::BUILD_STRATEGIES.to_sentence(**OR_CONNECTOR)
+
+        super(<<~STRING.chomp
+          Unknown build strategy "#{build_strategy}" referenced in spec.
+
+          Valid strategies include: #{valid_strategies}
+        STRING
+        )
+      end
     end
-  end
 
-  #
-  # Raised by Normalizer when any errors are returned. Acts like a grouping of errors
-  #
-  class InvalidStructureError < Error
-    def initialize(errors)
-      message = errors.to_a.join_map("\n") do |error|
-        next error if error.is_a?(SpecForge::Error)
-
-        # Normal errors, let's get verbose
-        backtrace = SpecForge.backtrace_cleaner.clean(error.backtrace)
-        "#{error.inspect}\n  # ./#{backtrace.join("\n  # ./")}\n"
+    #
+    # Raised when a spec file cannot be loaded
+    # Provides detailed information about the cause of the loading error
+    #
+    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?)
+
+        message +=
+          if causes.size > 1
+            "\nCauses:\n  - #{causes.join_map("\n  - ")}"
+          else
+            "\nCause: #{error}"
+          end
+
+        super(message)
       end
+    end
 
-      super(message)
+    #
+    # Raised when the provided namespace is not defined on the global context
+    #
+    class InvalidGlobalNamespaceError < Error
+      def initialize(provided_namespace)
+        super("Invalid global namespace #{provided_namespace.in_quotes}. Currently supported namespaces are: \"variables\"")
+      end
     end
-  end
 
-  #
-  # Raised by Attribute::Factory when an unknown build strategy is provided
-  #
-  class InvalidBuildStrategy < Error
-    def initialize(build_strategy)
-      valid_strategies = Attribute::Factory::BUILD_STRATEGIES.to_sentence(**OR_CONNECTOR)
+    #
+    # Raised when the provided matcher name does not defined with RSpec
+    #
+    class UndefinedMatcherError < Error
+      def initialize(matcher_name)
+        matcher_categories = {
+          Equality: ["matcher.eq", "matcher.eql", "matcher.equal"],
+          Types: ["kind_of.string", "kind_of.integer", "kind_of.array", "kind_of.hash"],
+          Truthiness: ["be.true", "be.false", "be.nil"],
+          Comparison: ["be.within", "be.between", "be.greater_than", "be.less_than"],
+          Collections: ["matcher.include", "matcher.contain_exactly", "matcher.all"],
+          Strings: ["/regex/", "matcher.start_with", "matcher.end_with"]
+        }
 
-      super(<<~STRING.chomp
-        Unknown build strategy "#{build_strategy}" referenced in spec.
+        formatted_categories =
+          matcher_categories.join_map("\n") do |category, matchers|
+            "  #{category}: #{matchers.join(", ")}"
+          end
 
-        Valid strategies include: #{valid_strategies}
-      STRING
-      )
+        super(<<~STRING.chomp
+          Undefined matcher method "#{matcher_name}" is not available in RSpec matchers.
+
+          Common matchers you can use:
+          #{formatted_categories}
+
+          For the complete list of available matchers, check the RSpec documentation:
+          https://rspec.info/documentation/3.12/rspec-expectations/RSpec/Matchers.html
+        STRING
+        )
+      end
+    end
+
+    #
+    # Raised when a callback is referenced in config but hasn't been defined
+    #
+    class UndefinedCallbackError < Error
+      def initialize(callback_name, available_callbacks = [])
+        message = "The callback #{callback_name.in_quotes} was referenced but hasn't been defined."
+
+        message +=
+          if available_callbacks.any?
+            <<~STR.chomp
+
+              Available callbacks are: #{available_callbacks.join_map(", ", &:in_quotes)}
+            STR
+          else
+            <<~STR.chomp
+
+              No callbacks have been defined yet. Register callbacks with:
+
+                SpecForge.register_callback(:#{callback_name}) do |context|
+                  # Your callback code
+                end
+            STR
+          end
+
+        super(message)
+      end
+    end
+
+    #
+    # Raised when an OpenAPI specification fails validation
+    #
+    # This error indicates that the generated OpenAPI document contains
+    # validation errors according to the OpenAPI specification standards.
+    # It's typically raised after attempting to validate a generated specification.
+    #
+    # @example
+    #   begin
+    #     generator.validate!(openapi_spec)
+    #   rescue SpecForge::Error::InvalidOASDocument
+    #     puts "Generated specification has validation errors"
+    #   end
+    #
+    class InvalidOASDocument < Error
     end
   end
 end