versponse 0.1.0 → 0.2.0

data/lib/versponse/condition.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Compiled if:/unless: pair, called with (object, context)
+  #
+  # @api private
+  class Condition
+    # @param if_callable [Proc, nil] emit the key only when this returns truthy
+    # @param unless_callable [Proc, nil] emit the key only when this returns falsy
+    # @return [Condition, nil] nil when neither is given
+    def self.build(if_callable, unless_callable)
+      return if if_callable.nil? && unless_callable.nil?
+
+      new(Callable.normalize(if_callable), Callable.normalize(unless_callable))
+    end
+
+    # @param if_callable [Proc, nil] normalized if: callable
+    # @param unless_callable [Proc, nil] normalized unless: callable
+    def initialize(if_callable, unless_callable)
+      @if_callable = if_callable
+      @unless_callable = unless_callable
+      freeze
+    end
+
+    # @param object [Object] serialized object
+    # @param context [Hash] serialize context
+    # @return [Boolean] whether the key is emitted
+    def call(object, context)
+      (@if_callable.nil? || @if_callable.call(object, context)) &&
+        (@unless_callable.nil? || !@unless_callable.call(object, context))
+    end
+  end
+end

data/lib/versponse/configuration.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Settings for Versponse, changed with {Versponse.configure}
+  #
+  # Plans and schemas are cached. Setting json_schema_version, formatters, version_resolver, field_order,
+  # default_additional_properties, on_error or recoverable_errors on {Versponse.configuration} resets them;
+  # custom_field_types resolve when properties are defined, so set them before response classes load.
+  #
+  # @example
+  #   Versponse.configure do |config|
+  #     config.current_version = -> { Current.api_version }
+  #     config.validate_output = Rails.env.local?
+  #   end
+  class Configuration
+    # Supported JSON Schema versions and their json_schemer modules, the same as verquest's
+    SCHEMAS = {
+      draft4: :Draft4,
+      draft6: :Draft6,
+      draft7: :Draft7,
+      draft2019_09: :Draft201909,
+      draft2020_12: :Draft202012,
+      openapi30: :OpenAPI30,
+      openapi31: :OpenAPI31
+    }.freeze
+
+    # JSON Schema versions without the `const` keyword, as in verquest
+    VERSIONS_WITHOUT_CONST = %i[draft4 openapi30].freeze
+
+    # How each JSON Schema version names a schema for "#Name" references: $anchor from 2019-09,
+    # a plain-name $id in drafts 6 and 7, and id in draft 4 (which OpenAPI 3.0 is based on)
+    ANCHOR_KEYWORDS = {draft4: "id", openapi30: "id", draft6: "$id", draft7: "$id"}.freeze
+
+    # @return [Boolean, #call] validate every rendered response against its schema, none (default false), or those
+    #   for which the callable, called with the response class, returns a truthy value
+    attr_reader :validate_output
+    # @return [Numeric] share of renders validated when validate_output allows it, from 0 to 1 (default 1.0)
+    attr_reader :validate_output_sample_rate
+    # @return [Boolean] additionalProperties of generated object schemas (default false)
+    attr_reader :default_additional_properties
+    # @return [#call, nil] returns the version used when serialize gets no version:
+    attr_reader :current_version
+    # @return [#call] resolves a requested version from the declared ones; it must return the closest
+    #   declared version at or before the request (it may add rules, e.g. preview sorting highest),
+    #   because requested versions are canonicalized against all declared names before caching
+    attr_reader :version_resolver
+    # @return [#call] turns a Hash into a JSON String
+    attr_reader :json_generator
+    # @return [Hash{String => #call}] formatters keyed by JSON Schema format
+    attr_reader :formatters
+    # @return [Symbol] JSON Schema version of generated schemas (default :openapi31)
+    attr_reader :json_schema_version
+    # @return [Symbol] :raise (default) or :ignore for expand paths that match no expandable association
+    attr_reader :unknown_expand
+    # @return [Symbol] :raise (default) or :ignore for fields: paths that are unknown or below unexpanded associations
+    attr_reader :unknown_fields
+    # @return [Symbol] :declaration (default) or :alphabetical (identifiers first, then by output key,
+    #   like blueprinter's sort_fields_by :name_asc)
+    attr_reader :field_order
+    # @return [Hash{String => Hash}] custom field types, normalized by {FieldType.normalize} (default {})
+    attr_reader :custom_field_types
+    # @return [Symbol, #call] policy for failing properties without their own or their class's (default :raise)
+    attr_reader :on_error
+    # @return [Array<Class>] StandardError subclasses a policy recovers (default [StandardError])
+    attr_reader :recoverable_errors
+    # @return [#call, nil] called with (error, response:, key:, object:) for each error a policy recovers
+    attr_reader :on_recovered_error
+
+    # @return [Configuration] configuration with default settings
+    def initialize
+      @validate_output = false
+      @validate_output_sample_rate = 1.0
+      @default_additional_properties = false
+      @json_schema_version = :openapi31
+      @unknown_expand = :raise
+      @unknown_fields = :raise
+      @field_order = :declaration
+      @version_resolver = VersionResolver
+      @json_generator = JSON.method(:generate)
+      @formatters = Formatters::DEFAULTS
+      @custom_field_types = {}.freeze
+      @on_error = :raise
+      @recoverable_errors = [StandardError].freeze
+      @on_recovered_error = nil
+    end
+
+    # @param value [Boolean, #call] validate every render, none, or those for which value.call(response_class) is
+    #   truthy (called per render, e.g. to read Rails' Current)
+    # @raise [ArgumentError] for anything else, or a lambda or Method that can't take the response class
+    def validate_output=(value)
+      @validate_output = (value == true || value == false) ? value : class_callable!(value, :validate_output, "true, false")
+    end
+
+    # @param value [Numeric] share of renders validated when validate_output allows it, from 0 to 1
+    # @raise [ArgumentError] for anything but a real number from 0 to 1
+    def validate_output_sample_rate=(value)
+      unless value.is_a?(Numeric) && value.real? && (0..1).cover?(value)
+        raise ArgumentError, "validate_output_sample_rate must be a number from 0 to 1"
+      end
+
+      @validate_output_sample_rate = value
+    end
+
+    # @param value [Boolean] additionalProperties of generated object schemas
+    # @raise [ArgumentError] for a value that isn't true or false
+    def default_additional_properties=(value)
+      @default_additional_properties = boolean!(value, :default_additional_properties)
+      changed!
+    end
+
+    # @param value [#call, nil] returns the current version, or nil to clear it
+    # @raise [ArgumentError] when value does not respond to call
+    def current_version=(value)
+      @current_version = value.nil? ? nil : callable!(value, :current_version)
+    end
+
+    # @param value [#call] called with (requested_version, sorted_versions); must return the closest
+    #   declared version at or before the request, since requests are canonicalized against all declared names
+    # @raise [ArgumentError] when value does not respond to call
+    def version_resolver=(value)
+      @version_resolver = callable!(value, :version_resolver)
+      changed!
+    end
+
+    # @param value [#call] called with the rendered Hash, returns a String
+    # @raise [ArgumentError] when value does not respond to call
+    def json_generator=(value)
+      @json_generator = callable!(value, :json_generator)
+    end
+
+    # @param value [Symbol] one of {SCHEMAS}
+    # @raise [ArgumentError] when the version is not supported
+    def json_schema_version=(value)
+      raise ArgumentError, "Unsupported JSON Schema version: #{value}. Use one of #{SCHEMAS.keys.join(", ")}" unless SCHEMAS.key?(value)
+
+      @json_schema_version = value
+      changed!
+    end
+
+    # @param value [Symbol] :raise or :ignore
+    # @raise [ArgumentError] for any other value
+    def unknown_expand=(value)
+      raise ArgumentError, "unknown_expand must be :raise or :ignore" unless %i[raise ignore].include?(value)
+
+      @unknown_expand = value
+    end
+
+    # @param value [Symbol] :raise or :ignore
+    # @raise [ArgumentError] for any other value
+    def unknown_fields=(value)
+      raise ArgumentError, "unknown_fields must be :raise or :ignore" unless %i[raise ignore].include?(value)
+
+      @unknown_fields = value
+    end
+
+    # @param value [Symbol] :declaration or :alphabetical
+    # @raise [ArgumentError] for any other value
+    def field_order=(value)
+      raise ArgumentError, "field_order must be one of #{FieldOrder::VALUES.join(", ")}" unless FieldOrder::VALUES.include?(value)
+
+      @field_order = value
+      changed!
+    end
+
+    # @param value [Hash{String, Symbol => #call}] formatters keyed by JSON Schema format
+    # @raise [ArgumentError] when a formatter does not respond to call
+    def formatters=(value)
+      raise ArgumentError, "formatters must be a Hash of callables" unless value.is_a?(Hash) && value.each_value.all? { |formatter| formatter.respond_to?(:call) }
+
+      @formatters = value.transform_keys(&:to_s).freeze
+      changed!
+    end
+
+    # Types resolve when a field is defined, so set them before response classes load
+    #
+    # @param value [Hash{Symbol, String => Hash}] verquest-shaped types, e.g. {site_id: {type: "string", schema_options: {pattern: "^site_"}}}
+    # @raise [ArgumentError] when value is not a Hash or a type is invalid
+    # @raise [Versponse::DefinitionError] for a Regexp pattern ECMA-262 can't express
+    def custom_field_types=(value)
+      raise ArgumentError, "custom_field_types must be a Hash" unless value.is_a?(Hash)
+
+      @custom_field_types = value.to_h { |name, definition| [name.to_s, FieldType.normalize(name, definition)] }.freeze
+    end
+
+    # @param value [Symbol, #call] :raise, :nullify, :omit, or a handler called with (error, object, key, context)
+    # @raise [ArgumentError] for anything else, or a lambda or Method that can't take those four arguments
+    def on_error=(value)
+      raise ArgumentError, "on_error must be :raise, :nullify, :omit or a callable taking (error, object, key, context)" unless ErrorPolicy.valid?(value)
+
+      @on_error = value
+      changed!
+    end
+
+    # @param value [Array<Class>] StandardError subclasses a policy recovers
+    # @raise [ArgumentError] for anything but an Array of StandardError subclasses
+    def recoverable_errors=(value)
+      valid = value.is_a?(::Array) && value.all? { |klass| klass.is_a?(Class) && klass <= StandardError }
+      raise ArgumentError, "recoverable_errors must be an Array of StandardError subclasses" unless valid
+
+      @recoverable_errors = value.dup.freeze
+      changed!
+    end
+
+    # @param value [#call, nil] called with (error, response:, key:, object:) for each recovered error, nil for none
+    # @raise [ArgumentError] when value does not respond to call
+    def on_recovered_error=(value)
+      @on_recovered_error = value.nil? ? nil : callable!(value, :on_recovered_error)
+    end
+
+    # @return [Boolean] true when nullable is written as `nullable: true` (OpenAPI 3.0)
+    def nullable_keyword?
+      json_schema_version == :openapi30
+    end
+
+    # @return [Boolean] false when constants are written as a one-value enum (draft 4 and OpenAPI 3.0)
+    def const_keyword?
+      !VERSIONS_WITHOUT_CONST.include?(json_schema_version)
+    end
+
+    # @param name [String] anchor name
+    # @return [Hash{String => String}] the keyword naming a schema so "#<name>" references it
+    def anchor(name)
+      keyword = ANCHOR_KEYWORDS[json_schema_version]
+      keyword ? {keyword => "##{name}"} : {"$anchor" => name}
+    end
+
+    # @return [String] meta-schema URI of the configured JSON Schema version
+    def json_schema_uri
+      require "json_schemer"
+
+      JSONSchemer.const_get(SCHEMAS.fetch(json_schema_version))::BASE_URI.to_s
+    end
+
+    private
+
+    # Only the global configuration feeds the caches
+    def changed!
+      Versponse.reset_caches! if Versponse.configuration.equal?(self)
+    end
+
+    def boolean!(value, name)
+      raise ArgumentError, "#{name} must be true or false" unless [true, false].include?(value)
+
+      value
+    end
+
+    # Lambdas and Methods check their arity, so one that can't take the response class fails here, not on a render
+    def class_callable!(value, name, alternatives)
+      raise ArgumentError, "#{name} must be #{alternatives} or respond to call" unless value.respond_to?(:call)
+      raise ArgumentError, "#{name} must accept the response class" unless Callable.accepts?(value, 1)
+
+      value
+    end
+
+    def callable!(value, name)
+      raise ArgumentError, "#{name} must respond to call" unless value.respond_to?(:call)
+
+      value
+    end
+  end
+end

data/lib/versponse/const_as_enum.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Draft 4 and OpenAPI 3.0 have no const keyword, so every generated const (property options and nested
+  # schemas included) becomes a one-value enum. Data keywords keep their values, and name maps keep their names.
+  #
+  # @api private
+  module ConstAsEnum
+    # Keywords whose values are data, not schemas
+    DATA_KEYWORDS = %w[example examples default enum const].freeze
+
+    # Keywords whose keys are names, with a schema for each
+    NAME_MAPS = %w[properties patternProperties $defs definitions dependentSchemas].freeze
+
+    # @param schema [Object] generated schema
+    # @return [Object] a copy with every const as a one-value enum (an existing enum keeps only that value)
+    def self.call(schema)
+      case schema
+      when Hash then convert(schema)
+      when Array then schema.map { |item| call(item) }
+      else schema
+      end
+    end
+
+    def self.convert(schema)
+      converted = schema.to_h do |key, item|
+        next [key, item] if DATA_KEYWORDS.include?(key)
+        next [key, item.transform_values { |child| call(child) }] if NAME_MAPS.include?(key) && item.is_a?(Hash)
+
+        [key, call(item)]
+      end
+      return converted unless converted.key?("const")
+
+      value = converted.delete("const")
+      converted.merge("enum" => converted.key?("enum") ? converted["enum"].select { |allowed| allowed == value } : [value])
+    end
+    private_class_method :convert
+  end
+end

data/lib/versponse/context_override/call.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Versponse
+  module ContextOverride
+    # Calls a callable with the parent object and context
+    #
+    # @api private
+    class Call
+      # @param callable [#call] normalized to (object, context)
+      def initialize(callable)
+        @callable = callable
+        freeze
+      end
+
+      # @param object [Object] the object owning the property
+      # @param context [Hash] parent context
+      # @return [Hash] frozen child context
+      # @raise [Versponse::ExtractionError] when the callable returns anything but a Hash (the plan adds the keys)
+      def call(object, context)
+        child = @callable.call(object, context)
+        raise ExtractionError.new(label: "context", keys: [], detail: "context: must return a Hash, got #{child.class}") unless child.is_a?(Hash)
+
+        child.frozen? ? child : child.dup.freeze
+      end
+    end
+  end
+end

data/lib/versponse/context_override/merge.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Versponse
+  module ContextOverride
+    # Merges a frozen Hash over the parent context
+    #
+    # @api private
+    class Merge
+      # @param hash [Hash] deep-frozen values to merge
+      def initialize(hash)
+        @hash = hash
+        freeze
+      end
+
+      # @param _object [Object] unused
+      # @param context [Hash] parent context
+      # @return [Hash] frozen child context; the built Hash itself over an empty context
+      def call(_object, context)
+        context.empty? ? @hash : context.merge(@hash).freeze
+      end
+    end
+  end
+end

data/lib/versponse/context_override.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Versponse
+  # The context a nested property's subtree renders with: a Hash merged over the parent context, or a callable
+  # returning the child context
+  #
+  # @api private
+  module ContextOverride
+    # @param option [Hash, #call, nil] the property's context: option
+    # @param key [String] property key, for error messages
+    # @return [Merge, Call, nil] the override, nil without the option
+    # @raise [Versponse::DefinitionError] for any other value, or a callable taking neither (object) nor (object, context)
+    def self.build(option, key:)
+      return if option.nil?
+      return Merge.new(DeepFreeze.call(option)) if option.is_a?(Hash)
+      raise DefinitionError, "#{key}: context: must be a Hash or respond to call" unless option.respond_to?(:call)
+
+      begin
+        Call.new(Callable.normalize(option))
+      rescue DefinitionError => e
+        raise DefinitionError, "#{key}: context: #{e.message}"
+      end
+    end
+  end
+end

data/lib/versponse/context_plan.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Versponse
+  # A one_of variant's plan rendered with the variant's context: (called with the matched value)
+  #
+  # @api private
+  class ContextPlan
+    # @param plan [#call] the variant's plan (full or collapsed)
+    # @param override [#call] the variant's context override
+    def initialize(plan, override)
+      @plan = plan
+      @override = override
+      freeze
+    end
+
+    # @param object [Object] the matched value
+    # @param context [Hash] context of the one_of
+    # @param expansion [Versponse::Expansion] expand tree node
+    # @return [Hash] rendered object
+    def call(object, context, expansion = Expansion::NONE)
+      @plan.call(object, @override.call(object, context), expansion)
+    end
+  end
+end

data/lib/versponse/deep_copy.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Unfrozen deep copy of a value handed to a caller who may change it
+  #
+  # @api private
+  module DeepCopy
+    # @param value [Object] value, usually frozen
+    # @return [Object] a copy whose Hashes, Arrays and Strings are new, unfrozen objects; other values as they are
+    def self.call(value)
+      case value
+      when ::Hash then value.to_h { |key, item| [key, call(item)] }
+      when ::Array then value.map { |item| call(item) }
+      when ::String then value.dup
+      else value
+      end
+    end
+
+    # Scalars render as they are; copying them on every render would only cost
+    #
+    # @param value [Object] value
+    # @return [Boolean] true for a Hash or Array, which renders as a copy
+    def self.container?(value)
+      value.is_a?(::Hash) || value.is_a?(::Array)
+    end
+  end
+end

data/lib/versponse/deep_freeze.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Deeply frozen copy of a schema. Copies instead of freezing in place, so schemas returned by
+  # other gems (verquest's internal hashes) are never frozen behind their back.
+  #
+  # @api private
+  module DeepFreeze
+    # @param value [Object] Hash, Array, String or another value
+    # @return [Object] a frozen copy
+    def self.call(value)
+      case value
+      when Hash then value.to_h { |key, item| [call(key), call(item)] }.freeze
+      when Array then value.map { |item| call(item) }.freeze
+      when String then value.frozen? ? value : value.dup.freeze
+      else value
+      end
+    end
+  end
+end

data/lib/versponse/discriminated_plan.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Collapsed one_of variant: the discriminator const followed by the class's identifier
+  #
+  # @api private
+  class DiscriminatedPlan
+    # @param plan [#call] the variant class's collapsed plan
+    # @param key [String] discriminator property
+    # @param value [Object] the variant's discriminator value
+    def initialize(plan, key:, value:)
+      @plan = plan
+      @key = key
+      @value = value
+      freeze
+    end
+
+    # @param object [Object] source
+    # @param context [Hash] serialize context
+    # @param expansion [Versponse::Expansion] expand tree node
+    # @return [Hash] discriminator and identifier
+    def call(object, context, expansion = Expansion::NONE)
+      {@key => @value}.merge!(@plan.call(object, context, expansion))
+    end
+  end
+end

data/lib/versponse/error_policy/recovery.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Versponse
+  module ErrorPolicy
+    # Applies one property's policy when its step fails, then reports the error
+    #
+    # @api private
+    class Recovery
+      # @param policy [Symbol, #call] :nullify, :omit or a handler
+      # @param key [String] the property's key
+      # @param response [Class, nil] the class whose plan holds the property
+      # @param explicit [Boolean] declared on the property itself, so it also recovers nested failures
+      def initialize(policy, key:, response:, explicit:)
+        @policy = policy
+        @key = key
+        @response = response
+        @explicit = explicit
+        @errors = Versponse.configuration.recoverable_errors
+        freeze
+      end
+
+      # A failure from a child plan is recovered only by an explicit policy (an ExtractionError then too). Other
+      # Versponse errors, and errors raised by the on_recovered_error hook, are never recovered.
+      #
+      # @param error [StandardError] what the step raised
+      # @return [Boolean] true when this policy handles it
+      def recovers?(error)
+        return false if ErrorPolicy.unrecoverable?(error)
+        return @explicit && (error.is_a?(ExtractionError) || (!error.is_a?(Error) && recoverable?(error))) if ErrorPolicy.nested?(error)
+
+        !error.is_a?(Error) && recoverable?(error)
+      end
+
+      # Writes nil, leaves the key out, or writes the handler's value. Each skips the step's inline check, so it
+      # forces full output validation (a nullable property's declared any_of may still reject nil, a left-out key may
+      # be required).
+      #
+      # @param error [StandardError] what the step raised
+      # @param object [Object] the object being rendered
+      # @param context [Hash] serialize context
+      # @param output [Hash] Hash being built
+      # @return [void]
+      def recover(error, object, context, output)
+        if @policy == :omit
+          output.delete(@key)
+        else
+          output[@key] = (@policy == :nullify) ? nil : @policy.call(error, object, @key, context)
+        end
+        InlineValidation.failed!
+        report(error, object)
+      end
+
+      private
+
+      # A hook error is marked, so a parent's policy doesn't recover it either
+      def report(error, object)
+        Versponse.configuration.on_recovered_error&.call(error, response: @response, key: @key, object:)
+      rescue => e
+        ErrorPolicy.mark_unrecoverable!(e)
+        raise
+      end
+
+      def recoverable?(error)
+        @errors.any? { |klass| error.is_a?(klass) }
+      end
+    end
+  end
+end

data/lib/versponse/error_policy.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Versponse
+  # What happens when a property fails to render: :raise, :nullify, :omit, or a handler called with
+  # (error, object, key, context) whose return value is written
+  #
+  # @api private
+  module ErrorPolicy
+    # Policies given as Symbols
+    POLICIES = %i[raise nullify omit].freeze
+
+    # Arguments a handler is called with
+    HANDLER_ARGUMENTS = 4
+
+    # Instance variable marking an error raised inside a child plan
+    NESTED = :@versponse_nested_failure
+
+    # Instance variable marking an error no policy recovers (one raised by the on_recovered_error hook)
+    UNRECOVERABLE = :@versponse_unrecoverable
+
+    # @param policy [Object] a policy as given
+    # @return [Boolean] true for one of {POLICIES} or a callable taking (error, object, key, context)
+    def self.valid?(policy)
+      POLICIES.include?(policy) || Callable.accepts?(policy, HANDLER_ARGUMENTS)
+    end
+
+    # A frozen error can't be marked, so a class-level or config-level policy may recover it when it comes from a
+    # child plan
+    #
+    # @param error [StandardError] error leaving a child plan
+    # @return [void]
+    def self.mark_nested!(error)
+      error.instance_variable_set(NESTED, true) unless error.frozen?
+    end
+
+    # @param error [StandardError] error
+    # @return [Boolean] true when it was raised inside a child plan
+    def self.nested?(error)
+      error.instance_variable_defined?(NESTED)
+    end
+
+    # @param error [StandardError] error raised by the on_recovered_error hook
+    # @return [void]
+    def self.mark_unrecoverable!(error)
+      error.instance_variable_set(UNRECOVERABLE, true) unless error.frozen?
+    end
+
+    # @param error [StandardError] error
+    # @return [Boolean] true when no policy may recover it
+    def self.unrecoverable?(error)
+      error.instance_variable_defined?(UNRECOVERABLE)
+    end
+
+    # @param properties [Array<Versponse::Properties::Base>] a plan's properties, in step order
+    # @param policies [Versponse::ClassPolicies] the compiling class's settings
+    # @param version [String] canonical version name, to find what a reference property: reuses
+    # @return [Array<Recovery, nil>, nil] a recovery per step, nil when no step has one
+    def self.recoveries(properties, policies, version)
+      list = properties.map { |property| resolve(property, property.path_target(version), policies) }
+      list.any? ? list.freeze : nil
+    end
+
+    # The property's own policy, or the reused property's when it fits the copy (which has the reusing property's
+    # condition), else the first of the class's and config.on_error that fits what it renders (a :nullify only fits
+    # nullable properties, an :omit only conditional ones); :raise stops the search
+    #
+    # @param property [Versponse::Properties::Base] property as declared in the plan
+    # @param target [Versponse::Properties::Base] what it renders: itself, or the copy a reference property: reuses
+    # @param policies [Versponse::ClassPolicies] the compiling class's settings
+    # @return [Recovery, nil] nil when the property raises
+    def self.resolve(property, target, policies)
+      reused = target.on_error unless target.equal?(property)
+      own = property.on_error || (reused if reused && fits?(reused, target))
+      if own
+        return (own == :raise) ? nil : Recovery.new(own, key: property.key, response: policies.response, explicit: true)
+      end
+
+      [policies.on_error, Versponse.configuration.on_error].each do |level|
+        next if level.nil?
+        return nil if level == :raise
+        return Recovery.new(level, key: property.key, response: policies.response, explicit: false) if fits?(level, target)
+      end
+      nil
+    end
+
+    # @param policy [Symbol, #call] policy
+    # @param property [Versponse::Properties::Base] property
+    # @return [Boolean] true when the policy keeps the property's output within its schema
+    def self.fits?(policy, property)
+      case policy
+      when :nullify then property.nullable?
+      when :omit then property.conditional?
+      else true
+      end
+    end
+  end
+end