rigortype 0.2.7 → 0.2.8

data/lib/rigor/inference/method_dispatcher/overload_selector.rb

@@ -8,66 +8,46 @@ require_relative "receiver_affinity"
 module Rigor
   module Inference
     module MethodDispatcher
-      # Picks the RBS overload that should answer a call given the
-      # caller's actual argument types. Slice 4 phase 2c shape (with
-      # the v0.1.2 interface-strictness preference layered on top):
+      # Picks the RBS overload that should answer a call given the caller's actual argument types. Slice 4
+      # phase 2c shape (with the v0.1.2 interface-strictness preference layered on top):
       #
-      # 1. Filter overloads by positional arity (required, optional and
-      #    rest_positionals are honored; required_keywords disqualify the
-      #    overload because we do not yet thread keyword args through
+      # 1. Filter overloads by positional arity (required, optional and rest_positionals are honored;
+      #    required_keywords disqualify the overload because we do not yet thread keyword args through
       #    `call_arg_types`).
-      # 2. **Pass 1 — strict matches first.** Among the arity-matching
-      #    overloads, prefer the first one whose every (param, arg)
-      #    pair returns a `yes` or `maybe` answer AND whose param
-      #    types do NOT translate through `RBS::Types::Alias` /
-      #    `Interface` / `Intersection`. The translator demotes those
-      #    to `Dynamic[Top]`, which gradually accepts any argument —
-      #    so without this preference, an alias-typed overload like
-      #    `Array#[](::int) -> Elem` would beat the strict
-      #    `Array#[](Range) -> Array[Elem]?` overload for a Range
-      #    argument.
-      # 3. **Pass 2 — gradual fall-back.** If no fully strict overload
-      #    matches, accept the first arity-and-gradual-accept match
-      #    (the v0.1.1 behaviour). Alias / Interface / Intersection
-      #    params still reach this pass, so call sites whose only
-      #    candidate IS an alias-typed overload keep working. One
-      #    exclusion: an `untyped` argument does NOT gradually match
-      #    a value-pinning param (`nil` / literal types — carriers
-      #    that admit only specific values). Those overloads carry
-      #    value-precise returns (`Kernel#Array: (nil) -> []`,
-      #    `Regexp#=~: (nil) -> nil`) that would otherwise win purely
-      #    by list position and inject false constants into the flow;
-      #    they remain selectable when the argument PROVES the value
-      #    (strict pass) or when no other overload matches (step 4's
-      #    fallback picks the first overload regardless).
-      # 4. If no overload matches at all, fall back to
-      #    `method_types.first` so existing call sites keep their
-      #    phase 1 / 2b behavior. This preserves the fail-soft
-      #    invariant of the dispatcher.
+      # 2. **Pass 1 — strict matches first.** Among the arity-matching overloads, prefer the first one
+      #    whose every (param, arg) pair returns a `yes` or `maybe` answer AND whose param types do NOT
+      #    translate through `RBS::Types::Alias` / `Interface` / `Intersection`. The translator demotes
+      #    those to `Dynamic[Top]`, which gradually accepts any argument — so without this preference, an
+      #    alias-typed overload like `Array#[](::int) -> Elem` would beat the strict
+      #    `Array#[](Range) -> Array[Elem]?` overload for a Range argument.
+      # 3. **Pass 2 — gradual fall-back.** If no fully strict overload matches, accept the first
+      #    arity-and-gradual-accept match (the v0.1.1 behaviour). Alias / Interface / Intersection params
+      #    still reach this pass, so call sites whose only candidate IS an alias-typed overload keep
+      #    working. One exclusion: an `untyped` argument does NOT gradually match a value-pinning param
+      #    (`nil` / literal types — carriers that admit only specific values). Those overloads carry
+      #    value-precise returns (`Kernel#Array: (nil) -> []`, `Regexp#=~: (nil) -> nil`) that would
+      #    otherwise win purely by list position and inject false constants into the flow; they remain
+      #    selectable when the argument PROVES the value (strict pass) or when no other overload matches
+      #    (step 4's fallback picks the first overload regardless).
+      # 4. If no overload matches at all, fall back to `method_types.first` so existing call sites keep
+      #    their phase 1 / 2b behavior. This preserves the fail-soft invariant of the dispatcher.
       #
-      # The selector is intentionally agnostic about the dispatch kind
-      # (instance vs singleton). Both kinds share the same arity and
-      # acceptance shape; the difference is only in which `Definition`
-      # the caller fetched.
+      # The selector is intentionally agnostic about the dispatch kind (instance vs singleton). Both kinds
+      # share the same arity and acceptance shape; the difference is only in which `Definition` the caller
+      # fetched.
       module OverloadSelector
         module_function
 
-        # Canonical RBS-core aliases shipped by `core/builtin.rbs`
-        # whose body is `<Nominal> | _DuckType`. Matching an
-        # overload against an Integer literal should pick the
-        # `(int) -> Array[Elem]` body over the `(string) -> String`
-        # body because Integer satisfies `int`'s strict arm and
-        # not `string`'s. The translator collapses both aliases
-        # to `Dynamic[Top]` (interfaces are not structurally
-        # matched yet), so a dedicated pass 1.5 between strict
-        # and gradual consults this map to pick the alias whose
-        # strict arm matches.
+        # Canonical RBS-core aliases shipped by `core/builtin.rbs` whose body is `<Nominal> | _DuckType`.
+        # Matching an overload against an Integer literal should pick the `(int) -> Array[Elem]` body over
+        # the `(string) -> String` body because Integer satisfies `int`'s strict arm and not `string`'s.
+        # The translator collapses both aliases to `Dynamic[Top]` (interfaces are not structurally matched
+        # yet), so a dedicated pass 1.5 between strict and gradual consults this map to pick the alias
+        # whose strict arm matches.
         #
-        # Symbol keys are the alias names as they appear under
-        # `RBS::Types::Alias#name.to_s` (the `name` is a
-        # `TypeName` whose `to_s` includes the `::` prefix).
-        # Values are an Array of class names whose Nominal[..]
-        # form is the alias's strict-arm matcher.
+        # Symbol keys are the alias names as they appear under `RBS::Types::Alias#name.to_s` (the `name` is
+        # a `TypeName` whose `to_s` includes the `::` prefix). Values are an Array of class names whose
+        # Nominal[..] form is the alias's strict-arm matcher.
         ALIAS_STRICT_NOMINALS = {
           "::int" => ["Integer"],
           "::string" => ["String"],
@@ -80,46 +60,35 @@ module Rigor
         private_constant :ALIAS_STRICT_NOMINALS
 
         # @param method_definition [RBS::Definition::Method]
-        # @param arg_types [Array<Rigor::Type>] caller-provided types in
-        #   positional order. Empty when there are no arguments.
+        # @param arg_types [Array<Rigor::Type>] caller-provided types in positional order. Empty when
+        #   there are no arguments.
         # @param self_type [Rigor::Type] substitute for `Bases::Self`.
         # @param instance_type [Rigor::Type] substitute for `Bases::Instance`.
-        # @param type_vars [Hash{Symbol => Rigor::Type}] substitution map
-        #   for class-level type variables (Slice 4 phase 2d). The
-        #   selector threads it through to {RbsTypeTranslator} so
-        #   parameter types like `::Array[Elem]` substitute Elem before
-        #   the accepts check, instead of degrading the param to
-        #   `Array[Dynamic[Top]]`.
-        # @param block_required [Boolean] when `true`, only overloads
-        #   that declare a block clause are considered (Slice 6 phase C
-        #   sub-phase 1). The fallback also prefers a block-bearing
-        #   overload over `method_types.first`. When `false` (the
-        #   Slice 4 phase 2c default) the selector behaves exactly as
-        #   before: `find` over arity-compatible overloads, falling
-        #   back to the first declaration.
-        # @return [RBS::MethodType, nil] the chosen overload, or nil
-        #   when the definition has no method types at all.
+        # @param type_vars [Hash{Symbol => Rigor::Type}] substitution map for class-level type variables
+        #   (Slice 4 phase 2d). The selector threads it through to {RbsTypeTranslator} so parameter types
+        #   like `::Array[Elem]` substitute Elem before the accepts check, instead of degrading the param
+        #   to `Array[Dynamic[Top]]`.
+        # @param block_required [Boolean] when `true`, only overloads that declare a block clause are
+        #   considered (Slice 6 phase C sub-phase 1). The fallback also prefers a block-bearing overload
+        #   over `method_types.first`. When `false` (the Slice 4 phase 2c default) the selector behaves
+        #   exactly as before: `find` over arity-compatible overloads, falling back to the first
+        #   declaration.
+        # @return [RBS::MethodType, nil] the chosen overload, or nil when the definition has no method
+        #   types at all.
         def select(method_definition, arg_types:, self_type:, instance_type:, type_vars: {}, block_required: false,
                    environment: nil)
           overloads = method_definition.method_types
           return nil if overloads.empty?
 
-          # `rigor:v1:param: <name> <refinement>` annotations on
-          # this method override the RBS-declared parameter type
-          # at the matching name. The map is consumed inside
-          # `accepts_param?` so overload selection sees the
-          # tighter type when filtering candidates by argument
-          # compatibility.
+          # `rigor:v1:param: <name> <refinement>` annotations on this method override the RBS-declared
+          # parameter type at the matching name. The map is consumed inside `accepts_param?` so overload
+          # selection sees the tighter type when filtering candidates by argument compatibility.
           param_overrides = RbsExtended.param_type_override_map(method_definition, environment: environment)
 
-          # Pre-sort: demote overloads whose param class is a
-          # disjoint sibling of the receiver class (e.g.
-          # `Integer#+(BigDecimal) -> BigDecimal` from the
-          # `bigdecimal` RBS reopen). Honors the coerce
-          # convention so `5 + ?` for unknown `?` resolves to
-          # the receiver-class-preserving arm rather than an
-          # arbitrary sibling-class arm that only wins by
-          # overload-list position.
+          # Pre-sort: demote overloads whose param class is a disjoint sibling of the receiver class (e.g.
+          # `Integer#+(BigDecimal) -> BigDecimal` from the `bigdecimal` RBS reopen). Honors the coerce
+          # convention so `5 + ?` for unknown `?` resolves to the receiver-class-preserving arm rather than
+          # an arbitrary sibling-class arm that only wins by overload-list position.
           overloads = ReceiverAffinity.reorder(overloads, self_type: self_type, environment: environment)
 
           passes = lambda do |require_block|
@@ -132,28 +101,21 @@ module Rigor
           match = passes.call(block_required)
           return match if match
 
-          # A block at the call site that no block-declaring overload
-          # matched: Ruby ignores a block handed to a method that never
-          # yields it, so retry treating the block as ignorable rather
-          # than failing the dispatch. Without this, a block-bearing
-          # call to a method whose RBS declares no block (e.g.
-          # `define_command(:x) do … end` against
-          # `def define_command: (Symbol) -> Symbol`) degraded to
-          # `Dynamic[Top]` — and on a self-send suppressed the whole
-          # method's return type.
+          # A block at the call site that no block-declaring overload matched: Ruby ignores a block handed
+          # to a method that never yields it, so retry treating the block as ignorable rather than failing
+          # the dispatch. Without this, a block-bearing call to a method whose RBS declares no block (e.g.
+          # `define_command(:x) do … end` against `def define_command: (Symbol) -> Symbol`) degraded to
+          # `Dynamic[Top]` — and on a self-send suppressed the whole method's return type.
           if block_required
             match = passes.call(false)
             return match if match
           end
 
-          # No (usable) block at the call site: prefer an overload that does
-          # not REQUIRE a block over `overloads.first`. Methods like
-          # `Array#filter` / `Enumerable#map` declare the block-
-          # bearing overload first (`() { ... } -> Array[Elem]`) and
-          # the bare-call overload second (`() -> Enumerator[...]`).
-          # Without this, a no-block `[1, 2].filter` would adopt the
-          # block overload's `Array[Elem]` return when the call
-          # actually yields an `Enumerator`.
+          # No (usable) block at the call site: prefer an overload that does not REQUIRE a block over
+          # `overloads.first`. Methods like `Array#filter` / `Enumerable#map` declare the block-bearing
+          # overload first (`() { ... } -> Array[Elem]`) and the bare-call overload second
+          # (`() -> Enumerator[...]`). Without this, a no-block `[1, 2].filter` would adopt the block
+          # overload's `Array[Elem]` return when the call actually yields an `Enumerator`.
           overloads.find { |mt| !overload_requires_block?(mt) } || overloads.first
         end
 
@@ -161,10 +123,9 @@ module Rigor
           method_type.respond_to?(:block) && method_type.block
         end
 
-        # True when the overload declares a block that the caller
-        # MUST supply (`{ ... }` in RBS). An optional block
-        # (`?{ ... }`) does NOT count — that overload is a valid
-        # match for a block-less call.
+        # True when the overload declares a block that the caller MUST supply (`{ ... }` in RBS). An
+        # optional block (`?{ ... }`) does NOT count — that overload is a valid match for a block-less
+        # call.
         def overload_requires_block?(method_type)
           block = overload_has_block?(method_type)
           !!block && block.required
@@ -174,18 +135,13 @@ module Rigor
           private
 
           # Three-pass overload search:
-          # - Pass 1 (strict): skipped when any arg is
-          #   `Dynamic[Top]`, because gradual acceptance against
-          #   an untyped arg accepts every param indiscriminately
-          #   and would let pass 1 lock in an arbitrary strict
-          #   overload (e.g. `Regexp#=~(nil) -> nil` over the
-          #   `(::interned?) -> Integer?` overload).
-          # - Pass 1.5 (alias-resolved): consults each `RBS::Types::Alias`'s
-          #   strict arm so e.g. `Array#*(int)` wins over the
-          #   `Array#*(string) -> String` overload for Integer args.
-          # - Pass 2 (gradual): the original gradual matcher so
-          #   overloads that legitimately rely on duck-typed
-          #   params still resolve when nothing stricter applies.
+          # - Pass 1 (strict): skipped when any arg is `Dynamic[Top]`, because gradual acceptance against
+          #   an untyped arg accepts every param indiscriminately and would let pass 1 lock in an arbitrary
+          #   strict overload (e.g. `Regexp#=~(nil) -> nil` over the `(::interned?) -> Integer?` overload).
+          # - Pass 1.5 (alias-resolved): consults each `RBS::Types::Alias`'s strict arm so e.g.
+          #   `Array#*(int)` wins over the `Array#*(string) -> String` overload for Integer args.
+          # - Pass 2 (gradual): the original gradual matcher so overloads that legitimately rely on
+          #   duck-typed params still resolve when nothing stricter applies.
           def run_selection_passes(overloads, arg_types:, self_type:, instance_type:, type_vars:, block_required:,
                                    param_overrides:)
             shared = {
@@ -219,25 +175,19 @@ module Rigor
           end
           # rubocop:enable Metrics/ParameterLists
 
-          # Treats the literal `untyped` carrier (`Dynamic[Top]`)
-          # as too imprecise to drive a strict-pass match. Other
-          # `Dynamic`-wrapped types with a concrete static facet
-          # carry enough information to pick a sensible overload.
+          # Treats the literal `untyped` carrier (`Dynamic[Top]`) as too imprecise to drive a strict-pass
+          # match. Other `Dynamic`-wrapped types with a concrete static facet carry enough information to
+          # pick a sensible overload.
           def untyped_arg?(type)
             type.is_a?(Type::Dynamic) && type.static_facet.is_a?(Type::Top)
           end
 
-          # Pass 1.5: for arity-compatible overloads whose every
-          # positional param is either a strict nominal OR a
-          # well-known core alias (`int` / `string` / `interned`
-          # / etc.), check the arg against the alias's STRICT
-          # arm. An Integer literal arg matches `int` here but
-          # not `string`, so `Array#*(int)` wins over the
-          # `Array#*(string) -> String` overload — even though
-          # both translate to `Dynamic[Top]` at the param level.
-          # Only fires when EVERY positional param has a known
-          # alias-or-strict shape; otherwise gradual matching
-          # takes over.
+          # Pass 1.5: for arity-compatible overloads whose every positional param is either a strict
+          # nominal OR a well-known core alias (`int` / `string` / `interned` / etc.), check the arg
+          # against the alias's STRICT arm. An Integer literal arg matches `int` here but not `string`, so
+          # `Array#*(int)` wins over the `Array#*(string) -> String` overload — even though both translate
+          # to `Dynamic[Top]` at the param level. Only fires when EVERY positional param has a known
+          # alias-or-strict shape; otherwise gradual matching takes over.
           def find_matching_overload_via_aliases(overloads, arg_types:, block_required:)
             overloads.find do |method_type|
               next false if block_required && !OverloadSelector.overload_has_block?(method_type)
@@ -253,11 +203,9 @@ module Rigor
             end
           end
 
-          # Checks the param's RBS type against an arg using
-          # alias-strict-arm matching. Optional / Union wrappers
-          # are flattened; alias resolution is one level deep
-          # (the canonical core aliases all have non-alias
-          # strict arms).
+          # Checks the param's RBS type against an arg using alias-strict-arm matching. Optional / Union
+          # wrappers are flattened; alias resolution is one level deep (the canonical core aliases all have
+          # non-alias strict arms).
           def alias_param_accepts?(rbs_type, arg)
             nominal_names = strict_nominal_names_for(rbs_type)
             return false if nominal_names.nil? || nominal_names.empty?
@@ -268,10 +216,9 @@ module Rigor
             end
           end
 
-          # Returns the candidate class names a param's RBS type
-          # accepts under alias-resolved strict matching, or nil
-          # when the shape cannot be reduced to a closed set of
-          # nominals (e.g. an Interface or an unrecognised alias).
+          # Returns the candidate class names a param's RBS type accepts under alias-resolved strict
+          # matching, or nil when the shape cannot be reduced to a closed set of nominals (e.g. an
+          # Interface or an unrecognised alias).
           def strict_nominal_names_for(rbs_type)
             case rbs_type
             when RBS::Types::ClassInstance
@@ -288,13 +235,10 @@ module Rigor
             end
           end
 
-          # Returns true when every positional param the call
-          # site engages translates to a non-`Dynamic[Top]`
-          # carrier. Alias / Interface / Intersection RBS types
-          # all degrade to `Dynamic[Top]` per the translator's
-          # current shape — those gradually accept any arg, so
-          # an overload that includes one would beat strictly-
-          # typed alternatives in pass 2 of the selector.
+          # Returns true when every positional param the call site engages translates to a non-`Dynamic[Top]`
+          # carrier. Alias / Interface / Intersection RBS types all degrade to `Dynamic[Top]` per the
+          # translator's current shape — those gradually accept any arg, so an overload that includes one
+          # would beat strictly-typed alternatives in pass 2 of the selector.
           def strictly_typed_params?(method_type, actual_count)
             fun = method_type.type
             return false unless arity_compatible?(fun, actual_count)
@@ -303,20 +247,15 @@ module Rigor
             params.all? { |param| !alias_or_interface_param?(param.type) }
           end
 
-          # Recursive: an Optional / Union wrapper is strict iff
-          # every member is strict. Type args of a ClassInstance
-          # are NOT walked — `Range[::int]` is a Range carrier
-          # at the param level; the alias only colours the
-          # element type, which is checked separately when the
-          # element is actually accessed.
+          # Recursive: an Optional / Union wrapper is strict iff every member is strict. Type args of a
+          # ClassInstance are NOT walked — `Range[::int]` is a Range carrier at the param level; the alias
+          # only colours the element type, which is checked separately when the element is actually
+          # accessed.
           #
-          # `RBS::Types::Bases::Any` (the explicit `untyped`
-          # keyword) is treated like Alias / Interface /
-          # Intersection — both translate to `Dynamic[Top]`,
-          # both gradually accept anything. A `(untyped) -> T`
-          # catch-all overload that comes after the strictly-
-          # typed ones must lose pass 1 so the typed overloads
-          # win when their param actually fits the arg.
+          # `RBS::Types::Bases::Any` (the explicit `untyped` keyword) is treated like Alias / Interface /
+          # Intersection — both translate to `Dynamic[Top]`, both gradually accept anything. A
+          # `(untyped) -> T` catch-all overload that comes after the strictly-typed ones must lose pass 1
+          # so the typed overloads win when their param actually fits the arg.
           def alias_or_interface_param?(rbs_type)
             case rbs_type
             when RBS::Types::Alias, RBS::Types::Interface,
@@ -350,9 +289,8 @@ module Rigor
             end
           end
 
-          # Slice 4 phase 2c does not pass keyword arguments through the
-          # call site (caller passes only positional `arg_types`). An
-          # overload that requires keywords is therefore not a viable
+          # Slice 4 phase 2c does not pass keyword arguments through the call site (caller passes only
+          # positional `arg_types`). An overload that requires keywords is therefore not a viable
           # candidate; we skip it instead of forcing a fallback.
           def rejects_keyword_required?(method_type)
             fun = method_type.type
@@ -371,11 +309,10 @@ module Rigor
             actual_count <= max_arity
           end
 
-          # Builds the list of formal parameter declarations to compare
-          # against the actual arguments, in positional order: required
-          # first, then as many optionals as needed, then trailing
-          # required. Rest_positionals consumes the remainder; we
-          # repeat its single declaration for each absorbed argument.
+          # Builds the list of formal parameter declarations to compare against the actual arguments, in
+          # positional order: required first, then as many optionals as needed, then trailing required.
+          # Rest_positionals consumes the remainder; we repeat its single declaration for each absorbed
+          # argument.
           def positional_params_for(fun, actual_count)
             required = fun.required_positionals
             optional = fun.optional_positionals
@@ -400,25 +337,20 @@ module Rigor
               instance_type: instance_type,
               type_vars: type_vars
             )
-            # An `untyped` arg gradually accepts against every param,
-            # so a value-pinning param would be "matched" with zero
-            # evidence and its value-precise return (`(nil) -> []`)
-            # would beat broader overloads purely by list position.
-            # Decline the pair; only the strict pass (where the arg
-            # proves the value) or the final first-overload fallback
-            # may select such an overload. (Pass 1 already skips
-            # untyped args entirely, so this only engages pass 2.)
+            # An `untyped` arg gradually accepts against every param, so a value-pinning param would be
+            # "matched" with zero evidence and its value-precise return (`(nil) -> []`) would beat broader
+            # overloads purely by list position. Decline the pair; only the strict pass (where the arg
+            # proves the value) or the final first-overload fallback may select such an overload. (Pass 1
+            # already skips untyped args entirely, so this only engages pass 2.)
             return false if untyped_arg?(arg) && value_pinning?(param_type)
 
             result = param_type.accepts(arg, mode: :gradual)
             result.yes? || result.maybe?
           end
 
-          # A type that admits only specific VALUES rather than a
-          # class of values: a `Constant` carrier (RBS `nil` and
-          # literal types both translate to one) or a union made up
-          # entirely of them (`true | false`, `1 | 2`, `nil?`-style
-          # optionals of literals).
+          # A type that admits only specific VALUES rather than a class of values: a `Constant` carrier
+          # (RBS `nil` and literal types both translate to one) or a union made up entirely of them
+          # (`true | false`, `1 | 2`, `nil?`-style optionals of literals).
           def value_pinning?(type)
             case type
             when Type::Constant then true