grape 1.8.0 → 4.0.1

data/lib/grape/validations/params_scope.rb

@@ -1,22 +1,26 @@
 # frozen_string_literal: true
 
-require_relative 'attributes_doc'
-
 module Grape
   module Validations
     class ParamsScope
-      attr_accessor :element, :parent, :index
-      attr_reader :type
+      attr_reader :parent, :type, :nearest_array_ancestor, :array_depth, :full_path
+
+      def qualifying_params
+        ParamScopeTracker.current&.qualifying_params(self)
+      end
 
       include Grape::DSL::Parameters
+      include Grape::Validations::ParamsDocumentation
 
       # There are a number of documentation options on entities that don't have
       # corresponding validators. Since there is nowhere that enumerates them all,
       # we maintain a list of them here and skip looking up validators for them.
       RESERVED_DOCUMENTATION_KEYWORDS = %i[as required param_type is_array format example].freeze
 
+      SPECIAL_JSON = [JSON, Array[JSON]].freeze
+
       class Attr
-        attr_accessor :key, :scope
+        attr_reader :key, :scope
 
         # Open up a new ParamsScope::Attr
         # @param key [Hash, Symbol] key of attr
@@ -34,9 +38,10 @@ module Grape
         end
 
         def self.attr_key(declared_param_attr)
-          return attr_key(declared_param_attr.key) if declared_param_attr.is_a?(self)
-
-          if declared_param_attr.is_a?(Hash)
+          case declared_param_attr
+          when self
+            attr_key(declared_param_attr.key)
+          when Hash
             declared_param_attr.transform_values { |value| attrs_keys(value) }
           else
             declared_param_attr
@@ -46,39 +51,47 @@ module Grape
 
       # Open up a new ParamsScope, allowing parameter definitions per
       #   Grape::DSL::Params.
-      # @param opts [Hash] options for this scope
-      # @option opts :element [Symbol] the element that contains this scope; for
-      #   this to be relevant, @parent must be set
-      # @option opts :element_renamed [Symbol, nil] whenever this scope should
+      # @param api [API] the API endpoint to modify
+      # @param element [Symbol] the element that contains this scope; for
+      #   this to be relevant, parent must be set
+      # @param element_renamed [Symbol, nil] whenever this scope should
       #   be renamed and to what, given +nil+ no renaming is done
-      # @option opts :parent [ParamsScope] the scope containing this scope
-      # @option opts :api [API] the API endpoint to modify
-      # @option opts :optional [Boolean] whether or not this scope needs to have
+      # @param parent [ParamsScope] the scope containing this scope
+      # @param optional [Boolean] whether or not this scope needs to have
       #   any parameters set or not
-      # @option opts :type [Class] a type meant to govern this scope (deprecated)
-      # @option opts :type [Hash] group options for this scope
-      # @option opts :dependent_on [Symbol] if present, this scope should only
+      # @param type [Class] a type meant to govern this scope (deprecated)
+      # @param type [Hash] group options for this scope
+      # @param dependent_on [Symbol] if present, this scope should only
       #   validate if this param is present in the parent scope
       # @yield the instance context, open for parameter definitions
-      def initialize(opts, &block)
-        @element          = opts[:element]
-        @element_renamed  = opts[:element_renamed]
-        @parent           = opts[:parent]
-        @api              = opts[:api]
-        @optional         = opts[:optional] || false
-        @type             = opts[:type]
-        @group            = opts[:group]
-        @dependent_on     = opts[:dependent_on]
+      def initialize(api:, element: nil, element_renamed: nil, parent: nil, optional: false, type: nil, group: nil, dependent_on: nil, &block)
+        @element          = element
+        @element_renamed  = element_renamed
+        @parent           = parent
+        @api              = api
+        @optional         = optional
+        @type             = type
+        @group            = group
+        @dependent_on     = dependent_on
+        # Must be an ivar: push_declared_params is dispatched on self during
+        # instance_eval, so local variables from initialize are unreachable.
+        # configure_declared_params consumes it and clears @declared_params to nil.
         @declared_params = []
-        @index = nil
+        @full_path = build_full_path
+        # Read by the validators instantiated from the block below, so it has to
+        # be settled before the instance_eval.
+        @array_depth = find_array_depth
 
         instance_eval(&block) if block
 
         configure_declared_params
+        @nearest_array_ancestor = find_nearest_array_ancestor
+        freeze
       end
 
       def configuration
-        @api.configuration.respond_to?(:evaluate) ? @api.configuration.evaluate : @api.configuration
+        config = @api.configuration
+        config.is_a?(Grape::Util::Lazy::Base) ? config.evaluate : config
       end
 
       # @return [Boolean] whether or not this entire scope needs to be
@@ -88,24 +101,26 @@ module Grape
 
         return false if @optional && (scoped_params.blank? || all_element_blank?(scoped_params))
         return false unless meets_dependency?(scoped_params, parameters)
-        return true if parent.nil?
+        return true if @parent.nil?
 
-        parent.should_validate?(parameters)
+        @parent.should_validate?(parameters)
       end
 
       def meets_dependency?(params, request_params)
         return true unless @dependent_on
-
         return false if @parent.present? && !@parent.meets_dependency?(@parent.params(request_params), request_params)
 
-        return params.any? { |param| meets_dependency?(param, request_params) } if params.is_a?(Array)
+        if params.is_a?(Array)
+          filtered = params.flatten.filter { |param| meets_dependency?(param, request_params) }
+          ParamScopeTracker.current&.store_qualifying_params(self, filtered)
+          return filtered.present?
+        end
 
         meets_hash_dependency?(params)
       end
 
       def attr_meets_dependency?(params)
         return true unless @dependent_on
-
         return false if @parent.present? && !@parent.attr_meets_dependency?(params)
 
         meets_hash_dependency?(params)
@@ -115,28 +130,27 @@ module Grape
         # params might be anything what looks like a hash, so it must implement a `key?` method
         return false unless params.respond_to?(:key?)
 
-        @dependent_on.each do |dependency|
+        @dependent_on.all? do |dependency|
           if dependency.is_a?(Hash)
-            dependency_key = dependency.keys[0]
-            proc = dependency.values[0]
-            return false unless proc.call(params.try(:[], dependency_key))
-          elsif params.respond_to?(:key?) && params.try(:[], dependency).blank?
-            return false
+            key, callable = dependency.first
+            callable.call(params[key])
+          else
+            params[dependency].present?
           end
         end
-
-        true
       end
 
       # @return [String] the proper attribute name, with nesting considered.
       def full_name(name, index: nil)
+        tracker = ParamScopeTracker.current
         if nested?
           # Find our containing element's name, and append ours.
-          "#{@parent.full_name(@element)}#{brackets(@index || index)}#{brackets(name)}"
+          resolved_index = index || tracker&.index_for(self)
+          "#{@parent.full_name(@element)}#{brackets(resolved_index)}#{brackets(name)}"
         elsif lateral?
           # Find the name of the element as if it was at the same nesting level
           # as our parent. We need to forward our index upward to achieve this.
-          @parent.full_name(name, index: @index)
+          @parent.full_name(name, index: tracker&.index_for(self))
         else
           # We must be the root scope, so no prefix needed.
           name.to_s
@@ -158,6 +172,17 @@ module Grape
         @parent && @element
       end
 
+      # Whether this scope's params resolve to one entry per element, which is
+      # what makes both an element index and a nesting level meaningful.
+      #
+      # +type: Array[JSON]+ counts as much as +type: Array+ does. It is easy to
+      # miss because it evaluates to the Array *instance* +[JSON]+ rather than
+      # the Array class, so an +== Array+ test quietly excluded it.
+      # @return [Boolean]
+      def iterates_elements?
+        @type == Array || @type == SPECIAL_JSON.last
+      end
+
       # A lateral scope is subordinate to its parent, but its keys are at the
       # same level as its parent and thus is not contained within an element.
       # @return [Boolean] whether or not this scope is lateral
@@ -175,27 +200,27 @@ module Grape
 
       # Adds a parameter declaration to our list of validations.
       # @param attrs [Array] (see Grape::DSL::Parameters#requires)
-      def push_declared_params(attrs, **opts)
-        opts = opts.merge(declared_params_scope: self) unless opts.key?(:declared_params_scope)
-        if lateral?
-          @parent.push_declared_params(attrs, **opts)
-        else
-          push_renamed_param(full_path + [attrs.first], opts[:as]) \
-            if opts && opts[:as]
+      # +declared_params_scope+ is the scope an attribute is recorded against.
+      # It defaults to the receiver and is forwarded unchanged when a lateral
+      # scope hands the push to its parent, so an attribute declared inside a
+      # +given+ block stays attributed to the lateral scope that declared it
+      # rather than to the parent that stores it.
+      def push_declared_params(attrs, as: nil, declared_params_scope: self)
+        return @parent.push_declared_params(attrs, as:, declared_params_scope:) if lateral?
 
-          @declared_params.concat(attrs.map { |attr| ::Grape::Validations::ParamsScope::Attr.new(attr, opts[:declared_params_scope]) })
-        end
-      end
-
-      # Get the full path of the parameter scope in the hierarchy.
-      #
-      # @return [Array<Symbol>] the nesting/path of the current parameter scope
-      def full_path
-        nested? ? @parent.full_path + [@element] : []
+        push_renamed_param(full_path + [attrs.first], as) if as
+        @declared_params.concat(attrs.map { |attr| ::Grape::Validations::ParamsScope::Attr.new(attr, declared_params_scope) })
       end
 
       private
 
+      def build_full_path
+        return @parent.full_path + [@element] if nested?
+        return @parent.full_path if lateral?
+
+        []
+      end
+
       # Add a new parameter which should be renamed when using the +#declared+
       # method.
       #
@@ -204,331 +229,223 @@ module Grape
       # @param new_name [String, Symbol] the new name of the parameter (the
       #   renamed name, with the +as: ...+ semantic)
       def push_renamed_param(path, new_name)
-        base = @api.route_setting(:renamed_params) || {}
-        base[Array(path).map(&:to_s)] = new_name.to_s
-        @api.route_setting(:renamed_params, base)
+        @api.inheritable_setting.add_route_renamed_param(Array(path).map(&:to_s), new_name.to_s)
       end
 
-      def require_required_and_optional_fields(context, opts)
+      def require_required_and_optional_fields(context, using:, except: nil)
+        except_fields = Array.wrap(except)
+        using_fields = using.keys.delete_if { |f| except_fields.include?(f) }
+
         if context == :all
-          optional_fields = Array(opts[:except])
-          required_fields = opts[:using].keys - optional_fields
+          optional_fields = except_fields
+          required_fields = using_fields
         else # context == :none
-          required_fields = Array(opts[:except])
-          optional_fields = opts[:using].keys - required_fields
+          required_fields = except_fields
+          optional_fields = using_fields
         end
         required_fields.each do |field|
-          field_opts = opts[:using][field]
-          raise ArgumentError, "required field not exist: #{field}" unless field_opts
+          field_opts = using[field]
+          raise ArgumentError, "required field not exist: `#{field}`" unless field_opts
 
-          requires(field, field_opts)
+          requires(field, **field_opts)
         end
         optional_fields.each do |field|
-          field_opts = opts[:using][field]
-          optional(field, field_opts) if field_opts
+          field_opts = using[field]
+          optional(field, **field_opts) if field_opts
         end
       end
 
-      def require_optional_fields(context, opts)
-        optional_fields = opts[:using].keys
-        optional_fields -= Array(opts[:except]) unless context == :all
+      def require_optional_fields(context, using:, except: nil)
+        optional_fields = using.keys
+        unless context == :all
+          except_fields = Array.wrap(except)
+          optional_fields.delete_if { |f| except_fields.include?(f) }
+        end
         optional_fields.each do |field|
-          field_opts = opts[:using][field]
-          optional(field, field_opts) if field_opts
+          field_opts = using[field]
+          optional(field, **field_opts) if field_opts
         end
       end
 
-      def validate_attributes(attrs, opts, &block)
-        validations = opts.clone
-        validations[:type] ||= Array if block
-        validates(attrs, validations)
-      end
-
       # Returns a new parameter scope, subordinate to the current one and nested
-      # under the parameter corresponding to `attrs.first`.
-      # @param attrs [Array] the attributes passed to the `requires` or
-      #   `optional` invocation that opened this scope.
-      # @param optional [Boolean] whether the parameter this are nested under
+      # under the given element.
+      # @param element [Symbol] the parameter name under which this scope is nested
+      # @param type [Class] the type governing this scope
+      # @param as [Symbol, nil] optional renamed name for the element
+      # @param optional [Boolean] whether the parameter this scope is nested under
       #   is optional or not (and hence, whether this block's params will be).
       # @yield parameter scope
-      def new_scope(attrs, optional = false, &block)
-        # if required params are grouped and no type or unsupported type is provided, raise an error
-        type = attrs[1] ? attrs[1][:type] : nil
-        if attrs.first && !optional
+      def new_scope(element, type:, as:, optional: false, &)
+        # A group needs a type: it says whether the nested params sit under one
+        # object or repeat in a list, and without it the `type || Array` below
+        # would quietly pick one. Checked here for `requires` and `optional`
+        # alike — `new_scope` is only reached from their block branch.
+        if element
           raise Grape::Exceptions::MissingGroupType if type.nil?
           raise Grape::Exceptions::UnsupportedGroupType unless Grape::Validations::Types.group?(type)
         end
 
         self.class.new(
           api: @api,
-          element: attrs.first,
-          element_renamed: attrs[1][:as],
+          element:,
+          element_renamed: as,
           parent: self,
-          optional: optional,
+          optional:,
           type: type || Array,
-          &block
+          group: @group,
+          &
         )
       end
 
       # Returns a new parameter scope, not nested under any current-level param
       # but instead at the same level as the current scope.
-      # @param options [Hash] options to control how this new scope behaves
-      # @option options :dependent_on [Symbol] if given, specifies that this
-      #   scope should only validate if this parameter from the above scope is
-      #   present
+      # @param dependent_on [Symbol] if given, specifies that this scope should
+      #   only validate if this parameter from the above scope is present
       # @yield parameter scope
-      def new_lateral_scope(options, &block)
+      def new_lateral_scope(dependent_on:, &)
         self.class.new(
           api: @api,
-          element: nil,
           parent: self,
-          options: @optional,
+          optional: @optional,
           type: type == Array ? Array : Hash,
-          dependent_on: options[:dependent_on],
-          &block
+          dependent_on:,
+          &
         )
       end
 
-      # Returns a new parameter scope, subordinate to the current one and nested
-      # under the parameter corresponding to `attrs.first`.
-      # @param attrs [Array] the attributes passed to the `requires` or
-      #   `optional` invocation that opened this scope.
+      # Returns a new parameter scope, subordinate to the current one, sharing
+      # the given group options with all parameters defined within.
+      # @param group [Hash] common options to merge into each parameter in the scope
       # @yield parameter scope
-      def new_group_scope(attrs, &block)
-        self.class.new(
-          api: @api,
-          parent: self,
-          group: attrs.first,
-          &block
-        )
+      def new_group_scope(group, &)
+        self.class.new(api: @api, parent: self, group:, &)
       end
 
-      # Pushes declared params to parent or settings
+      # Pushes declared params to parent or settings, then clears @declared_params.
+      # Clearing here (rather than in initialize) keeps the lifecycle ownership in
+      # one place: this method both consumes and invalidates the ivar so that
+      # push_declared_params cannot be called on the frozen scope later.
       def configure_declared_params
         push_renamed_param(full_path, @element_renamed) if @element_renamed
+        return @parent.push_declared_params [{ @element => @declared_params }] if nested?
 
-        if nested?
-          @parent.push_declared_params [element => @declared_params]
-        else
-          @api.namespace_stackable(:declared_params, @declared_params)
-        end
-
-        # params were stored in settings, it can be cleaned from the params scope
+        @api.inheritable_setting.add_declared_params(@declared_params)
+      ensure
         @declared_params = nil
       end
 
-      def validates(attrs, validations)
-        doc = AttributesDoc.new @api, self
-        doc.extract_details validations
-
-        coerce_type = infer_coercion(validations)
-
-        doc.type = coerce_type
+      def find_nearest_array_ancestor
+        scope = @parent
+        scope = scope.parent while scope && !scope.iterates_elements?
+        scope
+      end
 
-        default = validations[:default]
+      # Every element-iterating scope on the chain adds one level of nesting to
+      # what {#params} returns, because +map_params+ maps over the array it
+      # resolved from the parent. Counting them tells {AttributesIterator} how
+      # deep the declaration says the params for this scope may legitimately be.
+      def find_array_depth
+        (iterates_elements? ? 1 : 0) + (@parent&.array_depth || 0)
+      end
 
-        if (values_hash = validations[:values]).is_a? Hash
-          values = values_hash[:value]
-          # NB: excepts is deprecated
-          excepts = values_hash[:except]
-        else
-          values = validations[:values]
+      # +required+ is the DSL's own signal — +requires+ passes true, +optional+
+      # false. It used to travel as a +:presence+ key that +requires+ wrote into
+      # the caller's option Hash, which is why a user-supplied +presence:+ was
+      # silently overwritten there and silently honoured by +optional+, where
+      # nothing overwrote it. The key is built here from the flag instead, after
+      # the caller has merged in any enclosing +with+ attributes, so a
+      # group-level +message:+ reaches the presence validator.
+      #
+      # A +presence:+ supplied by an API still decides the outcome exactly as it
+      # used to — deprecated rather than dropped, so nothing changes under an
+      # API that relies on it until the key is ignored outright.
+      def validates(attrs, validations, required: false)
+        if validations.key?(:presence)
+          Grape.deprecator.warn('Passing a `presence` option is deprecated and it will be ignored in a future release. Declare the parameter with `requires` to make it required, `optional` to make it optional.')
         end
 
-        doc.values = values
-
-        except_values = options_key?(:except_values, :value, validations) ? validations[:except_values][:value] : validations[:except_values]
-
-        # NB. values and excepts should be nil, Proc, Array, or Range.
-        # Specifically, values should NOT be a Hash
-
-        # use values or excepts to guess coerce type when stated type is Array
-        coerce_type = guess_coerce_type(coerce_type, values, except_values, excepts)
+        declared = required ? validations.merge(presence: { value: true, message: validations[:message] }) : validations
+        declared = declared.merge(oneof: collected_oneof(declared)) if declared.key?(:oneof)
+        spec = ValidationsSpec.from(declared)
 
-        # default value should be present in values array, if both exist and are not procs
-        check_incompatible_option_values(default, values, except_values, excepts)
+        document_params(attrs, spec)
 
-        # type should be compatible with values array, if both exist
-        validate_value_coercion(coerce_type, values, except_values, excepts)
+        # Presence runs first — `required` is forwarded to every subsequent
+        # validator (some short-circuit on it).
+        validate_presence(spec, attrs)
 
-        doc.document attrs
+        # Coerce runs second — later validators see the typed value.
+        validate_coerce(spec, attrs)
 
-        opts = derive_validator_options(validations)
-
-        # Validate for presence before any other validators
-        validates_presence(validations, attrs, doc, opts)
-
-        # Before we run the rest of the validators, let's handle
-        # whatever coercion so that we are working with correctly
-        # type casted values
-        coerce_type validations, attrs, doc, opts
-
-        validations.each do |type, options|
-          # Don't try to look up validators for documentation params that don't have one.
-          next if RESERVED_DOCUMENTATION_KEYWORDS.include?(type)
-
-          validate(type, options, attrs, doc, opts)
+        spec.validator_entries.each do |type, options|
+          validate(type, options, attrs, spec.required?, spec.shared_opts)
         end
       end
 
-      # Validate and comprehend the +:type+, +:types+, and +:coerce_with+
-      # options that have been supplied to the parameter declaration.
-      # The +:type+ and +:types+ options will be removed from the
-      # validations list, replaced appropriately with +:coerce+ and
-      # +:coerce_with+ options that will later be passed to
-      # {Validators::CoerceValidator}. The type that is returned may be
-      # used for documentation and further validation of parameter
-      # options.
-      #
-      # @param validations [Hash] list of validations supplied to the
-      #   parameter declaration
-      # @return [class-like] type to which the parameter will be coerced
-      # @raise [ArgumentError] if the given type options are invalid
-      def infer_coercion(validations)
-        raise ArgumentError, ':type may not be supplied with :types' if validations.key?(:type) && validations.key?(:types)
-
-        validations[:coerce] = (options_key?(:type, :value, validations) ? validations[:type][:value] : validations[:type]) if validations.key?(:type)
-        validations[:coerce_message] = (options_key?(:type, :message, validations) ? validations[:type][:message] : nil) if validations.key?(:type)
-        validations[:coerce] = (options_key?(:types, :value, validations) ? validations[:types][:value] : validations[:types]) if validations.key?(:types)
-        validations[:coerce_message] = (options_key?(:types, :message, validations) ? validations[:types][:message] : nil) if validations.key?(:types)
-
-        validations.delete(:types) if validations.key?(:types)
-
-        coerce_type = validations[:coerce]
-
-        # Special case - when the argument is a single type that is a
-        # variant-type collection.
-        if Types.multiple?(coerce_type) && validations.key?(:type)
-          validations[:coerce] = Types::VariantCollectionCoercer.new(
-            coerce_type,
-            validations.delete(:coerce_with)
-          )
-        end
-        validations.delete(:type)
-
-        coerce_type
-      end
-
-      # Enforce correct usage of :coerce_with parameter.
-      # We do not allow coercion without a type, nor with
-      # +JSON+ as a type since this defines its own coercion
-      # method.
-      def check_coerce_with(validations)
-        return unless validations.key?(:coerce_with)
-        # type must be supplied for coerce_with..
-        raise ArgumentError, 'must supply type for coerce_with' unless validations.key?(:coerce)
-
-        # but not special JSON types, which
-        # already imply coercion method
-        return if [JSON, Array[JSON]].exclude? validations[:coerce]
+      # Enforce correct usage of :coerce_with on a CoerceOptions.
+      # We do not allow coercion without a type, nor with +JSON+ as a type
+      # since that defines its own coercion method.
+      def check_coerce_with(coerce_options)
+        return unless coerce_options.coerce_method
+        raise ArgumentError, 'must supply type for coerce_with' unless coerce_options.type
+        return unless SPECIAL_JSON.include?(coerce_options.type)
 
         raise ArgumentError, 'coerce_with disallowed for type: JSON'
       end
 
-      # Add type coercion validation to this scope,
-      # if any has been specified.
-      # This validation has special handling since it is
-      # composited from more than one +requires+/+optional+
-      # parameter, and needs to be run before most other
-      # validations.
-      def coerce_type(validations, attrs, doc, opts)
-        check_coerce_with(validations)
-
-        return unless validations.key?(:coerce)
-
-        coerce_options = {
-          type: validations[:coerce],
-          method: validations[:coerce_with],
-          message: validations[:coerce_message]
-        }
-        validate('coerce', coerce_options, attrs, doc, opts)
-        validations.delete(:coerce_with)
-        validations.delete(:coerce)
-        validations.delete(:coerce_message)
-      end
-
-      def guess_coerce_type(coerce_type, *values_list)
-        return coerce_type unless coerce_type == Array
+      def validate_presence(spec, attrs)
+        return unless spec.required?
 
-        values_list.each do |values|
-          next if !values || values.is_a?(Proc)
-          return values.first.class if values.is_a?(Range) || !values.empty?
-        end
-        coerce_type
+        validate('presence', spec.presence_options, attrs, true, spec.shared_opts)
       end
 
-      def check_incompatible_option_values(default, values, except_values, excepts)
-        return unless default && !default.is_a?(Proc)
-
-        raise Grape::Exceptions::IncompatibleOptionValues.new(:default, default, :values, values) if values && !values.is_a?(Proc) && !Array(default).all? { |def_val| values.include?(def_val) }
-
-        if except_values && !except_values.is_a?(Proc) && Array(default).any? { |def_val| except_values.include?(def_val) }
-          raise Grape::Exceptions::IncompatibleOptionValues.new(:default, default, :except, except_values) \
-
-        end
-
-        return unless excepts && !excepts.is_a?(Proc)
-        raise Grape::Exceptions::IncompatibleOptionValues.new(:default, default, :except, excepts) \
-          unless Array(default).none? { |def_val| excepts.include?(def_val) }
-      end
+      def validate_coerce(spec, attrs)
+        coerce_options = spec.coerce_options
+        check_coerce_with(coerce_options)
+        # Falsy check is intentional: when a remountable API is first evaluated
+        # on its base instance (no configuration supplied yet),
+        # configuration[:some_type] evaluates to nil. Skipping instantiation
+        # here is correct — the real mounted instance will replay this step
+        # with the actual type value.
+        return unless coerce_options.type
 
-      def validate(type, options, attrs, doc, opts)
-        validator_options = {
-          attributes: attrs,
-          options: options,
-          required: doc.required,
-          params_scope: self,
-          opts: opts,
-          validator_class: Validations.require_validator(type)
-        }
-        @api.namespace_stackable(:validations, validator_options)
+        validate('coerce', coerce_options, attrs, spec.required?, spec.shared_opts)
       end
 
-      def validate_value_coercion(coerce_type, *values_list)
-        return unless coerce_type
+      # Translate a `oneof: [proc, proc, ...]` declaration into a list of
+      # captured validator arrays — one array per variant. Each variant's
+      # block is evaluated in its own +ParamsScope+ backed by an
+      # {OneofCollector} so the full params DSL is available inside variants
+      # and the resulting validators are kept out of the real API's
+      # registration list.
+      # Returns the collected variants rather than writing them back into
+      # +validations+, which is the options Hash the +requires+/+optional+ call
+      # site built.
+      def collected_oneof(validations)
+        raise ArgumentError, 'oneof: requires type: Hash' unless validations[:type] == Hash
 
-        coerce_type = coerce_type.first if coerce_type.is_a?(Array)
-        values_list.each do |values|
-          next if !values || values.is_a?(Proc)
+        variants = validations[:oneof]
+        raise ArgumentError, 'oneof: must be a non-empty Array of blocks' unless variants.is_a?(Array) && variants.any?
+        raise ArgumentError, 'oneof: each variant must be a Proc' unless variants.all?(Proc)
 
-          value_types = values.is_a?(Range) ? [values.begin, values.end].compact : values
-          value_types = value_types.map { |type| Grape::API::Boolean.build(type) } if coerce_type == Grape::API::Boolean
-          raise Grape::Exceptions::IncompatibleOptionValues.new(:type, coerce_type, :values, values) unless value_types.all?(coerce_type)
-        end
+        variants.map { |block| OneofCollector.collect(block) }
       end
 
-      def extract_message_option(attrs)
-        return nil unless attrs.is_a?(Array)
-
-        opts = attrs.last.is_a?(Hash) ? attrs.pop : {}
-        opts.key?(:message) && !opts[:message].nil? ? opts.delete(:message) : nil
-      end
-
-      def options_key?(type, key, validations)
-        validations[type].respond_to?(:key?) && validations[type].key?(key) && !validations[type][key].nil?
+      def validate(type, options, attrs, required, opts)
+        validator_class = Validations.require_validator(type)
+        validator_instance = validator_class.new(
+          attrs,
+          options,
+          required,
+          self,
+          opts
+        )
+        @api.inheritable_setting.add_validation(validator_instance)
       end
 
       def all_element_blank?(scoped_params)
         scoped_params.respond_to?(:all?) && scoped_params.all?(&:blank?)
       end
-
-      # Validators don't have access to each other and they don't need, however,
-      # some validators might influence others, so their options should be shared
-      def derive_validator_options(validations)
-        allow_blank = validations[:allow_blank]
-
-        {
-          allow_blank: allow_blank.is_a?(Hash) ? allow_blank[:value] : allow_blank,
-          fail_fast: validations.delete(:fail_fast) || false
-        }
-      end
-
-      def validates_presence(validations, attrs, doc, opts)
-        return unless validations.key?(:presence) && validations[:presence]
-
-        validate(:presence, validations.delete(:presence), attrs, doc, opts)
-        validations.delete(:message) if validations.key?(:message)
-      end
     end
   end
 end