versponse 0.1.0 → 0.2.0

data/lib/versponse/open_api/sources.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Versponse
+  module OpenAPI
+    # Finds the classes that responses and requests declarations name, and raises when they name nothing usable
+    #
+    # @api private
+    module Sources
+      # Checks an explicit list when it's declared
+      #
+      # @param keyword [Symbol] :responses or :requests
+      # @param classes [Array<Class>] listed classes
+      # @return [void]
+      # @raise [Versponse::DefinitionError] for a class of the wrong kind, or a request that isn't a body request
+      def self.check!(keyword, classes)
+        classes.each { |klass| (keyword == :responses) ? check_response!(klass) : check_request!(klass) }
+      end
+
+      # Resolves the namespace, eager-loads it through Zeitwerk, and selects its classes
+      #
+      # @param keyword [Symbol] :responses or :requests
+      # @param namespace [Module, String] declared namespace
+      # @param kind [String] what the namespace should contain, for the error message
+      # @yieldreturn [Array<Class>] loaded candidate classes, read after eager loading
+      # @return [Array<Class>] the namespace's classes, sorted by name
+      # @raise [Versponse::DefinitionError] when the namespace isn't defined, isn't a module, or contains no candidates
+      def self.in_namespace(keyword, namespace, kind)
+        mod = namespace_module(keyword, namespace)
+        Zeitwerk::Loader.eager_load_namespace(mod)
+        found = yield.select { |klass| klass.name&.start_with?("#{mod.name}::") }.sort_by(&:name)
+        raise DefinitionError, "#{keyword} namespace: #{mod.name} matched no #{kind}" if found.empty?
+
+        found
+      end
+
+      # @param klass [Class] verquest request
+      # @return [Boolean] true for a request the document lists as a component
+      def self.body?(klass)
+        !klass.respond_to?(:location) || klass.location == :body
+      end
+
+      def self.check_response!(klass)
+        raise DefinitionError, "responses takes Versponse::Base subclasses, got #{klass.inspect}" unless References.versponse?(klass)
+      end
+
+      def self.check_request!(klass)
+        raise DefinitionError, "requests takes Verquest::Base subclasses, got #{klass.inspect}" unless verquest?(klass)
+        raise DefinitionError, "requests: #{klass} is a :#{klass.location} request; only body requests are components" unless body?(klass)
+      end
+
+      def self.verquest?(klass)
+        defined?(::Verquest::Base) && klass.is_a?(Class) && klass < ::Verquest::Base
+      end
+
+      def self.namespace_module(keyword, namespace)
+        return namespace if namespace.is_a?(Module)
+
+        mod = Object.const_get(namespace)
+        raise DefinitionError, "#{keyword} namespace: #{namespace} is not a module" unless mod.is_a?(Module)
+
+        mod
+      rescue NameError => e
+        # Only a missing segment of the path itself; a NameError raised while autoloading it is a bug to surface
+        raise unless e.instance_of?(NameError) && namespace.to_s.split("::").include?(e.name.to_s)
+
+        raise DefinitionError, "#{keyword} namespace: #{namespace} is not defined"
+      end
+
+      private_class_method :check_response!, :check_request!, :verquest?, :namespace_module
+    end
+  end
+end

data/lib/versponse/open_api/values.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Versponse
+  module OpenAPI
+    # Resolves declared values: blocks are called (with the version when they take an argument)
+    # and Hash keys become Strings, never camelized
+    #
+    # @api private
+    module Values
+      # @param value [Object, Proc, nil] declared value or block
+      # @param version [String] version being built
+      # @return [Object, nil] the resolved, String-keyed value
+      def self.resolve(value, version)
+        value = value.arity.zero? ? value.call : value.call(version) if value.is_a?(Proc)
+        stringify(value)
+      end
+
+      # @param value [Object] Hash, Array or scalar
+      # @return [Object] the value with String Hash keys at every level
+      def self.stringify(value)
+        case value
+        when Hash then value.to_h { |key, item| [key.to_s, stringify(item)] }
+        when Array then value.map { |item| stringify(item) }
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/versponse/open_api.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Builds OpenAPI documents from response and request classes, for rswag and other tools
+  module OpenAPI
+    # @param documents [Array<Class>] Versponse::OpenAPI::Document subclasses
+    # @return [Versponse::OpenAPI::RswagSpecs] a drop-in value for rswag's config.openapi_specs
+    def self.rswag_specs(*documents)
+      RswagSpecs.new(documents)
+    end
+  end
+end

data/lib/versponse/output_validator.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Validates rendered output against its validation schema (config.validate_output)
+  #
+  # @api private
+  module OutputValidator
+    # Errors the message names; the rest are counted
+    MESSAGE_ERRORS = 2
+
+    # @param klass [Class] response class
+    # @param data [Hash, Array<Hash>] rendered output, before root/meta wrapping
+    # @param version [String] requested version name
+    # @param view [Symbol] view name
+    # @param selection [Versponse::Selection] the render's selection; a selected render is checked against the
+    #   pruned validation schema
+    # @return [void]
+    # @raise [Versponse::InvalidOutputError] when the output does not match
+    def self.call(klass, data, version:, view:, selection: Selection::ALL)
+      checker, schemer = selection.all? ? [klass.versponse.checker(version:, view:), nil] : klass.versponse.selected_validators(version:, view:, selection:)
+      return if valid?(checker, data)
+
+      schemer ||= klass.versponse.schemer(version:, view:)
+      errors = if data.is_a?(Array)
+        data.each_with_index.flat_map { |item, index| errors_for(schemer, item, "/#{index}") }
+      else
+        errors_for(schemer, data, "")
+      end
+      return if errors.empty?
+
+      raise InvalidOutputError.new(error_message(klass, version, view, errors), errors:)
+    end
+
+    # Whether this render is validated: validate_output must allow it (true, or a callable returning truthy for
+    # the class), and the render must be sampled; the cheap checks run first, so a callable runs only on sampled renders
+    #
+    # @param klass [Class] response class serialize was called on
+    # @return [Boolean] true when the render is validated
+    def self.enabled?(klass)
+      config = Versponse.configuration
+      setting = config.validate_output
+      return false unless setting
+
+      rate = config.validate_output_sample_rate
+      return false if rate < 1 && Random.rand >= rate
+
+      setting == true || !!setting.call(klass)
+    end
+
+    # The compiled checker is the fast path; json_schemer runs only when it fails or is missing
+    #
+    # @param checker [#valid?, nil] compiled checker of the schema
+    # @param data [Hash, Array<Hash>] rendered output
+    # @return [Boolean] true when the checker accepts every item
+    def self.valid?(checker, data)
+      return false unless checker
+
+      data.is_a?(Array) ? data.all? { |item| checker.valid?(item) } : checker.valid?(data)
+    end
+
+    # @param schemer [JSONSchemer::Schema] compiled schema
+    # @param data [Hash] one rendered object
+    # @param prefix [String] pointer prefix for collection items
+    # @return [Array<Hash>] errors with :pointer, :type, :message and :details; messages point into the collection
+    def self.errors_for(schemer, data, prefix)
+      schemer.validate(data).map do |error|
+        pointer = prefix + error["data_pointer"]
+        # An item is validated on its own, so its message points inside the item
+        message = prefix.empty? ? error["error"] : error["error"].sub("`#{error["data_pointer"]}`", "`#{pointer}`")
+        {pointer:, type: error["type"], message:, details: error["details"]}
+      end
+    end
+
+    # json_schemer's messages name their pointer
+    def self.error_message(klass, version, view, errors)
+      details = errors.first(MESSAGE_ERRORS).map { |error| error[:message] }
+      details << "and #{errors.size - MESSAGE_ERRORS} more" if errors.size > MESSAGE_ERRORS
+      "#{klass.name || "AnonymousResponse"} output does not match its #{version}/#{view} schema: #{details.join("; ")}"
+    end
+    private_class_method :error_message
+  end
+end

data/lib/versponse/pattern.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Writes a Regexp pattern: as an ECMA-262 String, the dialect JSON Schema patterns use
+  #
+  # @api private
+  module Pattern
+    # Regexp options ECMA-262 patterns have no inline form for
+    OPTIONS = Regexp::IGNORECASE | Regexp::EXTENDED | Regexp::MULTILINE
+
+    # An escape, a bracket expression (kept whole: \A inside one is a literal A), or an inline option group
+    TOKEN = /\\.|\[(?:\\.|[^\\\]])*\]|\(\?-?[imx]+(?:-[imx]*)?[:)]/m
+
+    # @param pattern [Regexp, String] pattern as declared
+    # @return [String] the String as given, or the Regexp's source with \A and \z written as ^ and $
+    # @raise [Versponse::DefinitionError] for a Regexp with options (flags or inline groups), or one using \Z
+    def self.source(pattern)
+      return pattern unless pattern.is_a?(Regexp)
+      raise options_error(pattern) unless (pattern.options & OPTIONS).zero?
+
+      # Tokens are matched from the left, so an escaped backslash before an A stays a literal
+      pattern.source.gsub(TOKEN) do |token|
+        case token
+        when "\\A" then "^"
+        when "\\z" then "$"
+        when "\\Z" then raise DefinitionError, "pattern: #{pattern.inspect} uses \\Z, which ECMA-262 has no equivalent for; use \\z"
+        when /\A\(\?/ then raise options_error(pattern)
+        else token
+        end
+      end
+    end
+
+    def self.options_error(pattern)
+      DefinitionError.new("pattern: #{pattern.inspect} has options, which ECMA-262 patterns can't carry; use a String pattern")
+    end
+    private_class_method :options_error
+  end
+end

data/lib/versponse/plan.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Compiled, frozen list of steps that turns one object into a Hash
+  #
+  # @api private
+  class Plan
+    # @return [String] label used in extraction errors, like "UserResponse[2025-09/default]"
+    attr_reader :label
+    # @return [Array<#call>] compiled steps
+    attr_reader :steps
+    # @return [Array<Versponse::ErrorPolicy::Recovery, nil>, nil] recovery per step, nil when every step raises
+    attr_reader :recoveries
+    # @return [Array<String>] keys rendered whatever a selection says: identifiers and consts
+    attr_reader :always
+
+    # @param label [String] plan label
+    # @param steps [Array<#call>] compiled steps
+    # @param recoveries [Array<Versponse::ErrorPolicy::Recovery, nil>, nil] recovery per step
+    # @param always [Array<String>] identifier keys (consts are found among the steps)
+    def initialize(label:, steps:, recoveries: nil, always: [])
+      @label = label
+      @steps = steps.dup.freeze
+      @recoveries = recoveries
+      @always = (always + @steps.grep(Steps::Const).map(&:key)).uniq.freeze
+      freeze
+    end
+
+    # A step whose recovery accepts its error is recovered and the loop goes on with the next step (retry restarts
+    # the begin block only, so output and index keep their values). An error from the recovery itself (a handler or
+    # the hook) is raised from the rescue clause, outside the begin block, so it propagates.
+    #
+    # @param object [Object] source object or Hash
+    # @param context [Hash] frozen serialize context
+    # @param expansion [Versponse::Expansion, Versponse::Selection::Scope] expand tree node for this object, paired with
+    #   its selection in a selected render
+    # @return [Hash{String => Object}] rendered object
+    # @raise [Versponse::ExtractionError] when a step raises NoMethodError or KeyError that no policy recovers (the
+    #   original error is kept as `cause`), unless an on_recovered_error hook raised it, which propagates as raised;
+    #   other errors no policy recovers propagate unchanged
+    def call(object, context, expansion = Expansion::NONE)
+      return call_selected(object, context, expansion) if Selection::Scope === expansion
+
+      output = {}
+      steps = @steps
+      index = 0
+      hash = Hash === object
+      begin
+        while index < steps.size
+          steps[index].call(object, hash, context, output, expansion)
+          index += 1
+        end
+      rescue => e
+        recover!(e, steps[index], index, object, context, output)
+        index += 1
+        retry
+      end
+      output
+    end
+
+    private
+
+    # A selected render walks the step indexes its selection memoizes for this plan
+    def call_selected(object, context, scope)
+      output = {}
+      steps = @steps
+      indexes = scope.selection.indexes_for(self)
+      position = 0
+      hash = Hash === object
+      begin
+        while position < indexes.size
+          steps[indexes[position]].call(object, hash, context, output, scope)
+          position += 1
+        end
+      rescue => e
+        index = indexes[position]
+        recover!(e, steps[index], index, object, context, output)
+        position += 1
+        retry
+      end
+      output
+    end
+
+    # Recovers the step's error with its policy, or raises it (as an ExtractionError for NoMethodError and KeyError,
+    # except a hook's error)
+    def recover!(error, step, index, object, context, output)
+      recovery = @recoveries&.[](index)
+      raise extraction_error(error, step) unless recovery&.recovers?(error)
+
+      recovery.recover(error, object, context, output)
+    end
+
+    # An error the on_recovered_error hook raised keeps its class and mark, so no parent policy recovers it
+    def extraction_error(error, step)
+      return error if ErrorPolicy.unrecoverable?(error)
+
+      case error
+      when ExtractionError then ExtractionError.new(label:, keys: [step&.key, *error.keys].compact, detail: error.detail)
+      when NoMethodError, KeyError then ExtractionError.new(label:, keys: [step&.key].compact, detail: error.message)
+      else error
+      end
+    end
+  end
+end

data/lib/versponse/properties/array.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Properties
+    # An array of scalar values
+    #
+    # @api private
+    class Array < Base
+      # @return [Array<String>] keywords this property type writes itself
+      def self.written_keywords = %w[items].freeze
+
+      # @return [Boolean] true: nil values can be replaced
+      def self.default_option? = true
+
+      # @param type [Symbol, String, Array<Symbol, String>] item type: built-in ({FieldType::BUILT_IN}), custom, or a union of built-in types
+      # @param item_schema_options [Hash] JSON Schema keywords of each item; they win over the custom type's
+      # @param options [Hash] see {Base#initialize}
+      # @raise [Versponse::DefinitionError] for an unknown item type or an invalid union
+      def initialize(type:, item_schema_options: {}, **options)
+        super(**options)
+        check_keywords!(item_schema_options, label: "#{key} item_schema_options", written_keywords: [])
+        @item_type, type_options = FieldType.resolve(type, key)
+        @item_schema_options = type_options.merge(Naming.camelize_keys(item_schema_options))
+        check_default!
+      end
+
+      # @param context [Versponse::SchemaContext, nil] schema generation context
+      # @return [Hash] JSON Schema of the array; a union item type is an anyOf in OpenAPI 3.0 documents
+      #   (an allOf with the items' own anyOf, when item_schema_options declare one)
+      def schema(context)
+        nullable_type({"type" => "array", "items" => items_schema(context)}.merge(schema_options), context)
+      end
+
+      # @param version [String] unused by scalars
+      # @param formatters [Hash{String => #call}] formatters by JSON Schema format, for the compiling class and version
+      # @param policies [Versponse::ClassPolicies] class-level on_nil and on_error of the compiling class
+      # @return [Versponse::Steps::Value] compiled step; like a collection, the value is read with {Collections.items}
+      #   (to_ary values and Sets; anything else raises) into a new Array, and items are formatted by their format
+      def step(version:, formatters:, policies: ClassPolicies::NONE)
+        formatter = formatters[@item_schema_options["format"]]
+        # The source's Array (or a relation's loaded records) is copied, so changing the output leaves it alone
+        return value_step(formatter: ->(items) { Collections.items(items).dup }, policies:) unless formatter
+
+        value_step(formatter: ->(items) { Collections.items(items).map { |item| item.nil? ? nil : formatter.call(item) } }, policies:)
+      end
+
+      private
+
+      def items_schema(context)
+        return FieldType.openapi30_union(@item_type, @item_schema_options) if openapi30_union?(@item_type, context)
+
+        {"type" => @item_type}.merge(@item_schema_options)
+      end
+    end
+  end
+end