versponse 0.1.0 → 0.2.0

data/lib/versponse/validator/value_check.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Validator
+    # const and enum, compared with == as json_schemer does
+    #
+    # @api private
+    class ValueCheck
+      # @return [Array<String>] keywords this check owns
+      def self.keywords = %w[const enum]
+
+      # @param schema [Hash] schema
+      # @param _compiler [Versponse::Validator::Compiler] unused
+      # @return [ValueCheck, nil] the check, nil without const and enum
+      def self.build(schema, _compiler)
+        return unless schema.key?("const") || schema.key?("enum")
+
+        new(schema.key?("const") ? [schema["const"]] : nil, schema["enum"])
+      end
+
+      # @param const [Array, nil] the const wrapped in an Array, nil without const
+      # @param enum [Array, nil] allowed values, nil without enum
+      def initialize(const, enum)
+        @const = const
+        @enum = enum
+        freeze
+      end
+
+      # @param data [Object] value to check
+      # @return [Boolean] true when data equals the const and is in the enum
+      def valid?(data)
+        (@const.nil? || @const.first == data) && (@enum.nil? || @enum.include?(data))
+      end
+    end
+  end
+end

data/lib/versponse/validator.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Fast checks compiled from validation schemas. They only answer "valid?"; json_schemer stays
+  # the authority for errors and for schemas the compiler doesn't support.
+  #
+  # @api private
+  module Validator
+  end
+end

data/lib/versponse/variant_dispatcher.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Picks the plan of the first variant whose matchers === the value. Used for a single one_of
+  # and for every item of a polymorphic collection.
+  #
+  # @api private
+  class VariantDispatcher
+    # @param variants [Array<Array(Array<#===>, #call)>] matchers and plan pairs
+    # @param nullable [Boolean] render nil as nil instead of failing to match
+    def initialize(variants, nullable:)
+      @variants = variants.freeze
+      @nullable = nullable
+      freeze
+    end
+
+    # @param value [Object] value to render
+    # @param context [Hash] serialize context
+    # @param expansion [Versponse::Expansion] expand tree node for the value
+    # @return [Hash, nil] the value rendered by its variant
+    # @raise [KeyError] when no variant matches (the plan wraps it in an ExtractionError)
+    def call(value, context, expansion = Expansion::NONE)
+      return nil if value.nil? && @nullable
+
+      plan_for(value).call(value, context, expansion)
+    end
+
+    private
+
+    def plan_for(value)
+      @variants.each { |matchers, plan| return plan if matchers.any? { |matcher| matcher === value } }
+      raise KeyError, "no one_of variant matches #{value.class}"
+    end
+  end
+end

data/lib/versponse/version.rb

@@ -1,5 +1,183 @@
 # frozen_string_literal: true
 
 module Versponse
-  VERSION = "0.1.0"
+  # One version of a response class: its properties, views and identifier. Frozen once the version block closes.
+  #
+  # @api private
+  class Version
+    # @return [String] version name
+    attr_reader :name
+    # @return [Hash{String => Versponse::Properties::Base}] properties of the default view
+    attr_reader :properties
+    # @return [Hash{Symbol => Versponse::View}] declared and inherited views
+    attr_reader :views
+    # @return [Hash{String => Versponse::Properties::Field}] identifier fields, the implicit :collapsed view
+    attr_reader :identifiers
+    # @return [#call, nil] identifier condition called with (object, context); when it returns false,
+    #   an expandable association that isn't expanded renders in full
+    attr_reader :collapse_if
+    # @return [String, nil] schema description
+    attr_accessor :description
+    # @return [Hash{String => Object}] camelized schema keywords of the version
+    attr_accessor :schema_options
+
+    # @param name [String] version name
+    # @param owner [String] response class name, for messages
+    def initialize(name:, owner:)
+      @name = name
+      @owner = owner
+      @properties = {}
+      @views = {}
+      @identifiers = {}
+      @collapse_if = nil
+      @schema_options = {}
+      @declared_keys = []
+    end
+
+    # @param property [Versponse::Properties::Base] property to add or replace
+    # @return [Versponse::Properties::Base] the property
+    # @raise [Versponse::DefinitionError] when an identifier declares the key
+    def add(property)
+      raise DefinitionError, "#{label}: #{property.key} is declared by identifier" if identifiers.key?(property.key)
+
+      @declared_keys << property.key
+      properties[property.key] = property
+    end
+
+    # The first identifier declared in a version replaces the inherited ones (and their collapse_if); later ones add to it
+    #
+    # @param property [Versponse::Properties::Field] identifier field
+    # @param property_in_full [Versponse::Properties::Field] the field in the full shape (conditional with collapse_if)
+    # @param collapse_if [#call, nil] normalized condition, at most one per version
+    # @return [Versponse::Properties::Field] the field
+    # @raise [Versponse::DefinitionError] when another identifier of the version already declares collapse_if
+    def add_identifier(property, property_in_full: property, collapse_if: nil)
+      if @inherited_identifiers
+        # The old identifiers' conditional copies (collapse_if) go back to plain fields
+        identifiers.each { |key, field| properties[key] = field if properties.key?(key) }
+        @identifiers = {}
+        @collapse_if = nil
+        @inherited_identifiers = false
+      end
+      if collapse_if
+        raise DefinitionError, "#{label}: collapse_if is already declared by another identifier" if @collapse_if
+
+        @collapse_if = collapse_if
+      end
+      @declared_keys << property.key
+      properties[property.key] = property_in_full
+      identifiers[property.key] = property
+    end
+
+    # @return [Boolean] true when the version declares or inherits an identifier
+    def identifiers?
+      !identifiers.empty?
+    end
+
+    # @param name [Symbol, String] property to remove
+    # @return [Versponse::Properties::Base] the removed property
+    # @raise [Versponse::DefinitionError] when the property does not exist or is an identifier
+    def remove(name)
+      check_not_identifier!(name.to_s)
+      properties.delete(name.to_s) || raise(DefinitionError, "Property #{name} not found in #{label}")
+    end
+
+    # @param view [Versponse::View] view to add or replace
+    # @return [Versponse::View] the view
+    # @raise [Versponse::DefinitionError] for the implicit default and collapsed views, or a view the version already declares
+    def add_view(view)
+      raise DefinitionError, "The #{view.name} view is implicit and can not be declared (#{label})" if %i[default collapsed].include?(view.name)
+      raise DefinitionError, "#{label} declares view #{view.name} twice" if views[view.name]&.declared?
+
+      views[view.name] = view
+    end
+
+    # @param other [Version] version to copy from
+    # @param exclude_properties [Array<Symbol, String>] properties left out of the copy
+    # @return [void]
+    # @raise [Versponse::DefinitionError] when an excluded property does not exist in other, or is an identifier
+    def copy_from(other, exclude_properties: [])
+      excluded = exclude_properties.map(&:to_s)
+      excluded.each { |key| raise DefinitionError, identifier_message(key) if other.identifiers.key?(key) }
+      unknown = excluded - other.properties.keys
+      raise DefinitionError, "#{label} excludes properties unknown in #{other.label}: #{unknown.join(", ")}" if unknown.any?
+
+      @properties = other.properties.except(*excluded)
+      @views = other.views.transform_values(&:for_next_version)
+      @identifiers = other.identifiers.dup
+      @collapse_if = other.collapse_if
+      @inherited_identifiers = true
+    end
+
+    # Checks the views and freezes the version
+    #
+    # @return [Version] self
+    # @raise [Versponse::DefinitionError] when a view excludes an unknown property, includes an unknown view
+    #   or is part of an include cycle
+    def finalize!
+      # A key declared in this version replaces inherited views' view-only definitions of it
+      views.each_value { |view| view.drop_inherited(@declared_keys) unless view.declared? }
+      known = properties.keys | views.each_value.flat_map { |view| view.properties.keys }
+      views.each_value do |view|
+        view.check_excludes!(known, label)
+        view.check_includes!(self)
+        view.freeze
+      end
+      properties.freeze
+      views.freeze
+      identifiers.freeze
+      schema_options.freeze
+      freeze
+    end
+
+    # @return [Array<Symbol>] :default, the declared views, and :collapsed when there is an identifier
+    def view_names
+      identifiers? ? [:default, *views.keys, :collapsed] : [:default, *views.keys]
+    end
+
+    # @param view_name [Symbol, String] view name
+    # @return [Array<Versponse::Properties::Base>] properties of the view in output order
+    # @raise [Versponse::ViewNotFoundError] for an unknown view, or :collapsed without an identifier
+    def properties_for(view_name)
+      FieldOrder.call(declared_properties_for(view_name.to_sym), identifiers: identifiers.keys)
+    end
+
+    # @param view_name [Symbol, String] declared view name
+    # @return [Versponse::View] the view
+    # @raise [Versponse::ViewNotFoundError] for an unknown view
+    def fetch_view(view_name)
+      views.fetch(view_name.to_sym) do
+        raise ViewNotFoundError, "View #{view_name} not found in #{label}. Available views: #{view_names.join(", ")}"
+      end
+    end
+
+    # @return [String] "<class name> <version name>"
+    def label
+      "#{@owner} #{name}"
+    end
+
+    private
+
+    # Excluding it would leave the collapsed shape rendering it
+    def check_not_identifier!(key)
+      raise DefinitionError, identifier_message(key) if identifiers.key?(key)
+    end
+
+    def identifier_message(key)
+      "#{label}: #{key} is an identifier; redeclare the identifiers instead of excluding it"
+    end
+
+    def declared_properties_for(view_name)
+      return properties.values if view_name == :default
+      return collapsed_properties if view_name == :collapsed
+
+      fetch_view(view_name).resolve(self)
+    end
+
+    def collapsed_properties
+      raise ViewNotFoundError, "#{label} has no identifier, so it has no collapsed view. Available views: #{view_names.join(", ")}" unless identifiers?
+
+      identifiers.values
+    end
+  end
 end

data/lib/versponse/version_resolver.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Resolves a requested version to the closest declared version at or before it
+  # Versions are compared as Strings, so they must sort lexicographically (dates like YYYY-MM do).
+  # A custom resolver must keep this closest-earlier behaviour, because requested versions are
+  # canonicalized against every declared name before caching.
+  #
+  # @example
+  #   Versponse::VersionResolver.call("2025-04", %w[2025-01 2025-06]) # => "2025-01"
+  class VersionResolver
+    # @param requested_version [String] version asked for
+    # @param versions [Array<String>] declared versions, oldest first
+    # @return [String, nil] the resolved version, or nil when the request is older than every version
+    def self.call(requested_version, versions)
+      # An index loop: reverse_each.find would allocate an Enumerator on every request
+      index = versions.size - 1
+      while index >= 0
+        version = versions[index]
+        return version if version <= requested_version
+
+        index -= 1
+      end
+      nil
+    end
+  end
+end

data/lib/versponse/versions.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Versions of one response class, plus class-level description and schema options
+  #
+  # @api private
+  class Versions
+    include Enumerable
+
+    # @return [String, nil] description used by versions that set none
+    attr_accessor :description
+    # @return [Hash{String => Object}] schema options merged into every version
+    attr_accessor :schema_options
+    # @return [Array<String>] declared version names, oldest first
+    attr_reader :sorted_names
+
+    # @param owner [String] response class name, for messages
+    # @return [Versions] an empty collection
+    def initialize(owner: "AnonymousResponse")
+      @owner = owner
+      @versions = {}
+      @sorted_names = [].freeze
+      @schema_options = {}
+      @resolved = Cache.new
+    end
+
+    # @param version [Versponse::Version] finalized version
+    # @return [void]
+    # @raise [Versponse::DefinitionError] when the class already declares the version
+    def add(version)
+      raise DefinitionError, "#{@owner} declares version #{version.name} twice" if @versions.key?(version.name)
+
+      @versions[version.name] = version
+      @sorted_names = @versions.keys.sort.freeze
+      Registry.add_version_name(version.name)
+      clear_resolved
+    end
+
+    # @param name [String] exact declared version name
+    # @return [Versponse::Version] the version
+    # @raise [Versponse::VersionNotFoundError] when no version has that exact name
+    def fetch(name)
+      @versions.fetch(name) { raise VersionNotFoundError, "Version #{name} not declared. Declared versions: #{sorted_names.join(", ")}" }
+    end
+
+    # @yieldparam version [Versponse::Version]
+    # @return [void]
+    def each(&)
+      @versions.each_value(&)
+    end
+
+    # @return [Boolean] true when no version is declared
+    def empty?
+      @versions.empty?
+    end
+
+    # Resolutions are memoized by name, so pass the class's own range on every call
+    # (supported_versions clears the memo through Versponse.reset_caches!). Raising stores nothing.
+    #
+    # @param name [String] requested version
+    # @param supported [Versponse::SupportedVersions, nil] range declared with supported_versions
+    # @return [Versponse::Version] closest declared version at or before the request
+    # @raise [Versponse::VersionNotFoundError] when there is none, or the range leaves the request out
+    # @raise [Versponse::DefinitionError] when the range's max sorts before every declared version
+    def resolve(name, supported: nil)
+      name = name.to_s
+      @resolved.fetch(name) do
+        raise VersionNotFoundError, "Version #{name} is outside supported_versions (#{supported}) of #{@owner}" if supported && !supported?(canonical_name(name), supported)
+
+        @versions[Versponse.configuration.version_resolver.call(name, sorted_names)] ||
+          raise(VersionNotFoundError, "Version #{name} not found. Available versions: #{sorted_names.join(", ")}")
+      end
+    end
+
+    # Checks the requested name only; declared blocks may lie outside the range
+    #
+    # @param name [String] requested version name
+    # @param supported [Versponse::SupportedVersions, nil] range declared with supported_versions
+    # @return [Boolean] true without a range or declared versions, otherwise whether the range includes name
+    # @raise [Versponse::DefinitionError] when the range's max sorts before every declared version
+    def supported?(name, supported)
+      return true if supported.nil? || empty?
+
+      supported.check!(sorted_names, @owner)
+      supported.covers?(name)
+    end
+
+    # Names eager_load! compiles: the declared versions inside the range plus min (so a min: "preview"
+    # class whose only block is 2025-09 compiles that block as "preview"), canonicalized like serialize
+    # does, keeping those that resolve to a declared version
+    #
+    # @param supported [Versponse::SupportedVersions, nil] range declared with supported_versions
+    # @return [Array<String>] canonical version names
+    # @raise [Versponse::DefinitionError] when the range's max sorts before every declared version
+    def supported_names(supported)
+      return sorted_names if supported.nil? || empty?
+
+      supported.check!(sorted_names, @owner)
+      candidates = [*sorted_names, supported.min].compact.map { |name| canonical_name(name) }.uniq
+      candidates.select { |name| supported.covers?(name) && Versponse.configuration.version_resolver.call(name, sorted_names) }
+    end
+
+    # @return [void]
+    def clear_resolved
+      # A new object, not clear: the caller may be inside a resolution holding the old cache's lock
+      @resolved = Cache.new
+    end
+
+    private
+
+    # The name serialize and to_schema cache under, so resolve("2026-04") and serialize(version: "2026-04") agree
+    def canonical_name(name)
+      Registry.canonical(name)
+    end
+  end
+end

data/lib/versponse/view.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Versponse
+  # A named selection of a version's properties: include_view, exclude_properties and view-only properties
+  #
+  # @api private
+  class View
+    # @return [Symbol] view name
+    attr_reader :name
+    # @return [Hash{String => Versponse::Properties::Base}] properties declared only in this view
+    attr_reader :properties
+
+    # @param name [Symbol, String] view name
+    # @param operations [Array<Array>] [type, argument] pairs in declaration order
+    # @param properties [Hash] view-only properties
+    # @param inherited [Boolean] true when copied from an earlier version
+    def initialize(name:, operations: [], properties: {}, inherited: false)
+      @name = name.to_sym
+      @operations = operations
+      @properties = properties
+      @inherited = inherited
+    end
+
+    # @param property [Versponse::Properties::Base] view-only property
+    # @return [void]
+    def add(property)
+      properties[property.key] = property
+      @operations << [:add, property.key]
+    end
+
+    # @param name [Symbol, String] view whose operations are applied here
+    # @return [void]
+    # @raise [Versponse::DefinitionError] for :default, which every view already starts from
+    def include_view(name)
+      raise DefinitionError, "include_view :default is implicit, every view starts from default" if name.to_sym == :default
+
+      @operations << [:include, name.to_sym]
+    end
+
+    # @param names [Array<Symbol, String>] properties to remove
+    # @return [void]
+    def exclude(names)
+      @operations << [:exclude, names.map(&:to_s)]
+    end
+
+    # @param keys [Array<String>] keys the version declares itself
+    # @return [void]
+    def drop_inherited(keys)
+      @operations = @operations.reject { |type, argument| type == :add && keys.include?(argument) }
+      @properties = @properties.except(*keys)
+    end
+
+    # @return [Boolean] true when declared in its version, false when inherited from an earlier one
+    def declared?
+      !@inherited
+    end
+
+    # @return [View] a copy for a later version, whose unknown excludes are ignored
+    def for_next_version
+      View.new(name:, operations: @operations.dup, properties: @properties.dup, inherited: true)
+    end
+
+    # @param known [Array<String>] property keys known in the declaring version
+    # @param label [String] version label for the error message
+    # @return [nil]
+    # @raise [Versponse::DefinitionError] when a declared (not inherited) view excludes an unknown property
+    def check_excludes!(known, label)
+      return if @inherited
+
+      @operations.each do |type, argument|
+        next unless type == :exclude
+
+        unknown = argument - known
+        raise DefinitionError, "View #{name} in #{label} excludes unknown properties: #{unknown.join(", ")}" if unknown.any?
+      end
+      nil
+    end
+
+    # @param version [Versponse::Version] version the view belongs to
+    # @param chain [Array<Symbol>] views being checked, for cycle detection
+    # @return [nil]
+    # @raise [Versponse::DefinitionError] when the view includes an unknown view or is part of an include cycle
+    def check_includes!(version, chain = [])
+      raise DefinitionError, "include_view cycle in #{version.label}: #{[*chain, name].join(" -> ")}" if chain.include?(name)
+
+      @operations.each do |type, argument|
+        next unless type == :include
+
+        included = version.views.fetch(argument) { raise DefinitionError, "View #{name} in #{version.label} includes unknown view #{argument}" }
+        included.check_includes!(version, [*chain, name])
+      end
+      nil
+    end
+
+    # Includes are checked by {#check_includes!} when the version is finalized
+    #
+    # @param version [Versponse::Version] version the view belongs to
+    # @return [Array<Versponse::Properties::Base>] resolved properties in output order
+    def resolve(version)
+      apply(version, version.properties.dup).values
+    end
+
+    # @return [View] self, with operations and properties frozen
+    def freeze
+      @operations.freeze
+      @properties.freeze
+      super
+    end
+
+    protected
+
+    # @param version [Versponse::Version] version the view belongs to
+    # @param result [Hash] properties being built
+    # @return [Hash] result
+    def apply(version, result)
+      @operations.each do |type, argument|
+        case type
+        when :add then result[argument] = properties.fetch(argument)
+        when :include then version.fetch_view(argument).apply(version, result)
+        when :exclude then argument.each { |key| result.delete(key) }
+        end
+      end
+      result
+    end
+  end
+end

data/lib/versponse/wrapper.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Versponse
+  # root:/meta: wrapping of rendered output and its schema
+  #
+  # @api private
+  module Wrapper
+    # @param meta [Object, nil] meta: given for a wrapper schema
+    # @return [void]
+    # @raise [Versponse::DefinitionError] when meta isn't a class with a $ref, such as the Hash serialize takes
+    def self.check_meta!(meta)
+      return if meta.nil? || meta.respond_to?(:to_ref)
+
+      raise DefinitionError, %(meta: takes a response class, whose $ref describes "meta"; serialize(meta:) takes the Hash)
+    end
+
+    # The envelope is strict (additionalProperties: false) whatever config.default_additional_properties says
+    #
+    # @param klass [Class] response class
+    # @param view [Symbol] view name
+    # @param root [String, Symbol] key holding the response
+    # @param meta [Class, nil] class whose $ref describes "meta"
+    # @param collection [Boolean] the root key holds an array
+    # @return [Hash] wrapper schema
+    def self.schema(klass, view:, root:, meta:, collection:)
+      item = {"$ref" => klass.to_ref(view:)}
+      properties = {root.to_s => collection ? {"type" => "array", "items" => item} : item}
+      properties["meta"] = {"$ref" => meta.to_ref} if meta
+      {"type" => "object", "required" => properties.keys, "properties" => properties, "additionalProperties" => false}
+    end
+
+    # @param data [Hash, Array<Hash>] rendered output
+    # @param root [String, Symbol, nil] wraps data under this key
+    # @param meta [Hash, nil] added under "meta" with String keys
+    # @return [Hash, Array<Hash>] data, or the wrapper Hash
+    def self.wrap(data, root:, meta:)
+      return data if root.nil?
+
+      wrapped = {root.to_s => data}
+      wrapped["meta"] = string_keys(meta) if meta
+      wrapped
+    end
+
+    def self.string_keys(value)
+      case value
+      when Hash then value.to_h { |key, item| [key.to_s, string_keys(item)] }
+      when Array then value.map { |item| string_keys(item) }
+      else value
+      end
+    end
+    private_class_method :string_keys
+  end
+end