rigortype 0.4.1 → 0.4.2

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

@@ -5,8 +5,11 @@ require_relative "../acceptance"
 require_relative "../rbs_type_translator"
 require_relative "alias_strict_nominals"
 require_relative "facet_distribution"
+require_relative "imprecise_argument"
+require_relative "keyword_arguments"
 require_relative "proven_overload"
 require_relative "receiver_affinity"
+require_relative "splat_arity"
 
 module Rigor
   module Inference
@@ -14,9 +17,14 @@ module Rigor
       # 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
-      #    `call_arg_types`).
+      # 1. Filter overloads by positional arity (required, optional and rest_positionals are honored).
+      #    Keyword arguments (#1727): when the call's last argument is a keyword hash (`keywords_last:`, which
+      #    only the caller can tell from the AST) and an overload declares keywords, that argument is matched
+      #    against the overload's keywords rather than as a positional `Hash` — every required keyword
+      #    present, every key declared, every value accepted. An overload that declares no keywords still
+      #    reads it as a trailing positional `Hash`, as Ruby passes it, but never in place of a keyword overload that
+      #    takes it (#1800, `KeywordArguments.prefer_takers`). A call without keywords skips an overload that requires
+      #    one.
       # 1a. **Pass 0 — proven, in declared order (#1344).** With only plain-value arguments, the first
       #    overload they do not rule out wins outright when each of its params names its argument's own
       #    class and accepts it with a `yes`; every later pass reads the receiver-affinity order instead.
@@ -44,7 +52,8 @@ module Rigor
       module OverloadSelector
         module_function
 
-        # `ALIAS_STRICT_NOMINALS`, the alias-strict pass's table, lives in `alias_strict_nominals.rb`.
+        # `ALIAS_STRICT_NOMINALS`, the alias-strict pass's table, lives in `alias_strict_nominals.rb`, with the pass's
+        # per-parameter test (`alias_param_accepts?`).
 
         # @param arg_types — caller-provided types in positional order. Empty when
         #   there are no arguments.
@@ -70,32 +79,48 @@ module Rigor
         # position, not by types — `[true] * n` with an untyped `n` pinned `Array#*(string) -> String`
         # and answered a wrong precise type the runtime can contradict. The caller unions the candidates'
         # returns, which contains the truth whichever overload the runtime takes. The member-wise reading of a
-        # two-member `Dynamic` facet (#1350, `FacetDistribution`) returns one candidate per member the same way.
+        # two-member `Dynamic` facet (#1350, `FacetDistribution`) returns one candidate per member the same way, and
+        # where that reading falls back to the arguments as given, every overload they gradually match (#1782).
         # Every other path (strict, alias-resolved, typed-gradual, arity fallback) yields exactly one candidate,
         # and `select` (`member_wise: false`) keeps its historical single answer.
         #
         # @return matching overloads; empty when the definition declares none.
         # rubocop:disable-next Metrics/ParameterLists -- the selection keywords plus the member-wise switch.
+        # @param keywords_last — the call's last argument is a keyword hash (`f(a, k: 1)`, not `f(a, { k: 1 })`).
+        # @param splats — the indices of `arg_types` that are splat arguments (`f(*xs)`), or nil (#1801).
         def select_candidates(definition, arg_types:, self_type:, instance_type:, type_vars: {},
-                              block_required: false, environment: nil, member_wise: true)
+                              block_required: false, environment: nil, member_wise: true, keywords_last: false,
+                              splats: nil)
           unless FacetDistribution.faceted?(arg_types)
             return select_declared(definition, arg_types, self_type, instance_type, type_vars, block_required,
-                                   environment, false)
+                                   environment, false, keywords_last, splats)
           end
 
           FacetDistribution.select(arg_types, definition, member_wise:, environment:) do |args, member|
-            select_declared(definition, args, self_type, instance_type, type_vars, block_required, environment, member)
+            # Issue #1782 — the fallback (`member` false) reads the arguments as given, where the bare `Dynamic`
+            # gradually matches every arm and the strict pass's pick is the first by position, so the member-wise answer
+            # is every gradual match (`:joined`), as the block probe reads it (#1750); the caller joins their returns.
+            select_declared(definition, args, self_type, instance_type, type_vars, block_required, environment,
+                            member || (member_wise && :joined), keywords_last, splats)
           end
         end
 
         # The selection proper, positional so the hot path forwards no keyword hash. A member-wise call (`member`, see
-        # `FacetDistribution.select`) answers only a genuine match, never the first-overload fallback.
+        # `FacetDistribution.select`) answers only a genuine match, never the first-overload fallback. `member` set to
+        # `:gradual` answers every overload the arguments gradually match instead (#1750): where
+        # `FacetDistribution.select` falls back to the arguments as given, a bare `Dynamic` positional gradually
+        # matches every arm and the strict pass's single pick is decided by position, so the block-parameter probe
+        # binds only what all of them agree on. `:joined` answers the same matches, but where none matches it keeps the
+        # first-overload fallback, as the return path's reading of the arguments as given always has (#1782).
         # rubocop:disable-next Metrics/ParameterLists -- the selection inputs plus the member-wise flag.
         def select_declared(method_definition, arg_types, self_type, instance_type, type_vars, block_required,
-                            environment, member)
+                            environment, member, keywords_last, splats = nil)
           declared = method_definition.method_types
           return [] if declared.empty?
 
+          # A keyword hash only some overload takes as keywords is a plain positional `Hash` otherwise (#1737).
+          keywords_last &&= KeywordArguments.any_declares?(declared)
+
           # `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.
@@ -110,12 +135,17 @@ module Rigor
 
           # One keyword bundle for the pass pipeline (see `run_selection_passes`); a block retry rebuilds it
           # with the block flag cleared. Built once and passed positionally -- the previous lambda plus a
-          # `**shared` splat per pass allocated three objects per selection (#775).
+          # `**shared` splat per pass allocated three objects per selection (#775). Keep it at eight keys or fewer:
+          # CRuby embeds a Hash that small, and a ninth key allocates a table on every selection (the RBS loader is
+          # read from `environment` rather than carried as a key of its own, #1727).
           shared = { arg_types: arg_types, self_type: self_type, instance_type: instance_type,
                      type_vars: type_vars, block_required: block_required, param_overrides: param_overrides,
-                     alias_expander: environment&.rbs_loader, environment: environment }
+                     environment: environment, keywords_last: keywords_last }
+          # Only a call with a splat pays for a ninth key (#1801).
+          shared[:splats] = splats if splats
 
-          matches = run_selection_passes(declared, overloads, shared)
+          gradual = member.is_a?(Symbol) # `:gradual` or `:joined`
+          matches = run_selection_passes(declared, overloads, shared, gradual)
           return matches unless matches.empty?
 
           # A block at the call site that no block-declaring overload matched: Ruby ignores a block handed
@@ -124,10 +154,10 @@ module Rigor
           # `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
-            matches = run_selection_passes(declared, overloads, shared.merge(block_required: false))
+            matches = run_selection_passes(declared, overloads, shared.merge(block_required: false), gradual)
             return matches unless matches.empty?
           end
-          return [] if member
+          return [] if member && member != :joined
 
           # 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
@@ -153,7 +183,7 @@ module Rigor
           private
 
           # Overload search after pass 0 (`find_proven_overload`):
-          # - Pass 1 (strict): skipped when any arg is imprecise (`imprecise_arg?`), because gradual
+          # - Pass 1 (strict): skipped when any arg is imprecise (`ImpreciseArgument.imprecise?`), 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).
@@ -172,25 +202,39 @@ module Rigor
           # order, the strict pass let the `bigdecimal` reopen's `(BigDecimal) -> BigDecimal` arm, which it
           # matches on a `maybe`, take `Integer#+` of a `bot`, a `Dynamic[Integer | Float | …]` or an
           # unloadable class (612 call sites across the survey corpus).
-          def run_selection_passes(declared, overloads, shared)
-            # Unreordered, pass 0 can only pick what the strict pass picks, so it is skipped (#1344's allocations).
-            proven = find_proven_overload(declared, shared) unless overloads.equal?(declared)
-            strict = proven || find_matching_overload(overloads, shared, strict: true)
-            return strict unless strict.empty?
-
-            alias_hit = find_matching_overload_via_aliases(
-              overloads, arg_types: shared[:arg_types], block_required: shared[:block_required]
-            )
-            return [alias_hit] if alias_hit
+          def run_selection_passes(declared, overloads, shared, gradual = false) # rubocop:disable Style/OptionalBooleanParameter
+            matches = run_passes(declared, overloads, shared, gradual)
+            return matches unless shared[:keywords_last]
+
+            # Issue #1800 — never a positional reader of the keyword hash in place of a keyword overload that takes it.
+            KeywordArguments.prefer_takers(declared, matches) do |takers, strict|
+              find_matching_overload(takers, shared, strict:)
+            end
+          end
+
+          def run_passes(declared, overloads, shared, gradual)
+            # The `:gradual` list (#1750) skips straight to pass 2's every-match answer, stand-ins included.
+            unless gradual
+              # Unreordered, pass 0 can only pick what the strict pass picks, so it is skipped (#1344's allocations).
+              proven = find_proven_overload(declared, shared) unless overloads.equal?(declared)
+              strict = proven || find_matching_overload(overloads, shared, strict: true)
+              return strict unless strict.empty?
+
+              alias_hit = find_matching_overload_via_aliases(overloads, shared)
+              return [alias_hit] if alias_hit
+            end
 
             # Pass 2, array-valued. With every argument carrying real type information the first gradual
             # match keeps its historical single-winner contract. With an imprecise argument in play the
             # matches are indistinguishable by types — position alone would pick — so ALL of them come back
             # and the dispatch layer unions their returns (#521).
             matches = find_matching_overload(overloads, shared, strict: false)
-            return matches.first(1) unless shared[:arg_types].any? { |t| imprecise_arg?(t) }
+            every_match = gradual || ImpreciseArgument.any_in?(shared[:arg_types], shared[:keywords_last])
+            return matches.first(1) unless every_match
 
-            matches
+            # Issue #1675 — and every overload the arguments' untyped parts reach on their own, after the
+            # whole-argument matches so the singular `select` keeps its answer.
+            ImpreciseArgument.with_stand_ins(matches, shared) { find_matching_overload(overloads, it, strict: false) }
           end
 
           # Pass 0. With every argument a plain value (a `Constant`, or a `Nominal` with no type arguments), the
@@ -207,7 +251,7 @@ module Rigor
 
             index = declared.index { |mt| engages_block_shape?(mt, shared[:block_required]) && matches?(mt, shared) }
             first = index && declared[index]
-            proven = first && strictly_typed_params?(first, args.size) && matches?(first, shared, strict: :proven)
+            proven = first && strictly_typed_params?(first, shared) && matches?(first, shared, strict: :proven)
             [first] if proven && !ProvenOverload.contested?(declared, index, args, shared[:environment])
           end
 
@@ -216,10 +260,10 @@ module Rigor
           private_constant :NO_MATCH
 
           # `shared` is the keyword bundle `select_candidates` assembled (arg_types, self_type, instance_type,
-          # type_vars, block_required, param_overrides, alias_expander).
+          # type_vars, block_required, param_overrides, environment, keywords_last).
           def find_matching_overload(overloads, shared, strict:)
             arg_types = shared[:arg_types]
-            return NO_MATCH if strict && arg_types.any? { |t| imprecise_arg?(t) }
+            return NO_MATCH if strict && ImpreciseArgument.any_in?(arg_types, shared[:keywords_last])
 
             block_required = shared[:block_required]
             # Strict keeps its historical first-match short-circuit (a dispatch hot path); the gradual
@@ -227,8 +271,8 @@ module Rigor
             if strict
               found = overloads.find do |method_type|
                 engages_block_shape?(method_type, block_required) &&
-                  strictly_typed_params?(method_type, arg_types.size) &&
-                  matches?(method_type, shared, strict: true)
+                  strictly_typed_params?(method_type, shared) &&
+                  matches?(method_type, shared, strict: strict)
               end
               return found ? [found] : NO_MATCH
             end
@@ -247,38 +291,26 @@ module Rigor
             !OverloadSelector.overload_requires_block?(method_type)
           end
 
-          # 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)
-
-          # Issue #1021 — the strict and alias passes must not discriminate on an argument whose type
-          # cannot rule an overload out: the bare untyped carrier, or a union with an untyped member. That
-          # member may reach any overload at runtime, so a strict match is decided by the union's other
-          # members alone — `Dynamic[top] | nil` pinned `Regexp#match?(nil) -> false` and typed a live
-          # predicate as the literal `false`. The gradual pass still accepts against the whole union, so
-          # `Dynamic[top] | nil` keeps both `match?` overloads and the #521 join answers `Dynamic[bool]`.
-          # A `Dynamic` with a concrete static facet stays out: its facet discriminates.
-          def imprecise_arg?(type)
-            untyped_arg?(type) || (type.is_a?(Type::Union) && type.members.any? { |member| untyped_arg?(member) })
-          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.
-          def find_matching_overload_via_aliases(overloads, arg_types:, block_required:)
+          def find_matching_overload_via_aliases(overloads, shared)
             # Issue #521 — an untyped argument "maybe"-accepts EVERY alias's strict arm, so it cannot
             # discriminate between overloads here any more than in the strict pass; without this guard a
             # Dynamic arg pinned `Array#*(string) -> String` purely by declaration order.
-            return nil if arg_types.any? { |t| imprecise_arg?(t) }
+            return nil if ImpreciseArgument.any_in?(shared[:arg_types], shared[:keywords_last])
 
             overloads.find do |method_type|
-              next false unless engages_block_shape?(method_type, block_required)
+              next false unless engages_block_shape?(method_type, shared[:block_required])
 
               fun = method_type.type
+              ok = KeywordArguments.accepted_by?(fun, shared, false) { |*kv| accepts_param?(*kv, shared, false, true) }
+              next false unless ok
+
+              arg_types = KeywordArguments.selection_positional(method_type, shared)
               next false unless arity_compatible?(fun, arg_types.size)
 
               params = positional_params_for(fun, arg_types.size)
@@ -297,51 +329,22 @@ module Rigor
             params.all? { |param| yield(param, arg_types[index += 1]) }
           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).
-          def alias_param_accepts?(rbs_type, arg)
-            nominal_names = strict_nominal_names_for(rbs_type)
-            return false if nominal_names.nil? || nominal_names.empty?
-
-            nominal_names.any? do |class_name|
-              result = Type::Combinator.nominal_of(class_name).accepts(arg, mode: :gradual)
-              result.yes? || result.maybe?
-            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).
-          def strict_nominal_names_for(rbs_type)
-            case rbs_type
-            when RBS::Types::ClassInstance
-              [rbs_type.name.to_s.delete_prefix("::")]
-            when RBS::Types::Alias
-              ALIAS_STRICT_NOMINALS[rbs_type.name.to_s]
-            when RBS::Types::Optional
-              strict_nominal_names_for(rbs_type.type)
-            when RBS::Types::Union
-              parts = rbs_type.types.map { |t| strict_nominal_names_for(t) }
-              return nil if parts.any?(&:nil?)
-
-              parts.flatten
-            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.
-          def strictly_typed_params?(method_type, actual_count)
+          def strictly_typed_params?(method_type, shared)
+            actual_count = KeywordArguments.selection_positional(method_type, shared).size
             fun = method_type.type
             # A `(?)` method type declares no params at all: it is the gradual case by construction, so it
             # must never win the strict pass over a genuinely typed sibling overload.
             return false unless fun.respond_to?(:required_positionals)
             return false unless arity_compatible?(fun, actual_count)
 
-            params = positional_params_for(fun, actual_count)
-            params.all? { |param| !alias_or_interface_param?(param.type) }
+            # #1737 — the keywords the call passes count too, so an `untyped` keyword cannot win the strict pass over
+            # a typed one.
+            positional_params_for(fun, actual_count).all? { |param| !alias_or_interface_param?(param.type) } &&
+              KeywordArguments.passed_params(fun, shared).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
@@ -368,26 +371,33 @@ module Rigor
           end
 
           # `shared` is the keyword bundle `select_candidates` assembled (see `find_matching_overload`).
-          # `strict:` is `false` (gradual), `true` (strict pass) or `:proven` (pass 0; see `find_proven_overload`).
+          # `strict:` is `false` (gradual), `true` (strict pass), `:proven` (pass 0; see `find_proven_overload`) or
+          # `:yes` (the strict pass with a `yes` at every pair, #1800's proof; see `KeywordArguments.prefer_takers`).
           def matches?(method_type, shared, strict: false)
-            return false if method_type.respond_to?(:type_params) && rejects_keyword_required?(method_type)
-
-            arg_types = shared[:arg_types]
             fun = method_type.type
-            return false unless arity_compatible?(fun, arg_types.size)
+            ok = KeywordArguments.accepted_by?(fun, shared, strict) { |*kv| accepts_param?(*kv, shared, strict, true) }
+            return false unless ok
 
-            params = positional_params_for(fun, arg_types.size)
-            each_param_accepts?(params, arg_types) { |param, arg| accepts_param?(param, arg, shared, strict) }
+            arg_types = KeywordArguments.selection_positional(method_type, shared)
+            splats = shared[:splats]
+            return positionals_accept?(fun, arg_types, shared, strict) unless splats
+
+            # #1801 — a splat stands for any number of arguments: some count of its elements must fit.
+            lists = SplatArity.expansions(fun, arg_types, splats)
+            return lists.any? { |list| positionals_accept?(fun, list, shared, strict) } if lists
+
+            # Past the cap the position each other argument lands at is not spelled out, but it lands at one.
+            params = KeywordArguments.positional_params(fun)
+            arg_types.each_with_index.all? do |arg, index|
+              splats.include?(index) || params.any? { |param| accepts_param?(param, arg, shared, strict) }
+            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
-          # candidate; we skip it instead of forcing a fallback.
-          def rejects_keyword_required?(method_type)
-            fun = method_type.type
-            return false unless fun.respond_to?(:required_keywords)
+          def positionals_accept?(fun, arg_types, shared, strict)
+            return false unless arity_compatible?(fun, arg_types.size)
 
-            !fun.required_keywords.empty?
+            params = positional_params_for(fun, arg_types.size)
+            each_param_accepts?(params, arg_types) { |kw, arg| accepts_param?(kw, arg, shared, strict) }
           end
 
           # `RBS::Types::UntypedFunction` (`(?)`) declares no arity to enforce, so every call site is
@@ -434,23 +444,25 @@ module Rigor
           end
 
           # `shared` is the keyword bundle `select_candidates` assembled (see `find_matching_overload`).
-          def accepts_param?(param, arg, shared, strict)
+          def accepts_param?(param, arg, shared, strict, keyword = false) # rubocop:disable Style/OptionalBooleanParameter
             param_type = shared[:param_overrides][param.name] || RbsTypeTranslator.translate(
               param.type,
               self_type: shared[:self_type],
               instance_type: shared[:instance_type],
               type_vars: shared[:type_vars],
-              alias_expander: shared[:alias_expander]
+              alias_expander: shared[:environment]&.rbs_loader
             )
             # 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)
+            # A keyword value is exempt (#1737): an untyped one marks the call imprecise (`ImpreciseArgument.any_in?`),
+            # so every arm it reaches joins the #521 union instead of one winning by position.
+            return false if !keyword && ImpreciseArgument.untyped?(arg) && value_pinning?(param_type)
 
             result = param_type.accepts(arg, mode: :gradual)
-            return result.yes? && ProvenOverload.names_arg_class?(param_type, arg) if strict == :proven
+            return proof?(result, param_type, arg, strict) if strict.is_a?(Symbol)
 
             # A record's `maybe` for a `Hash` with a gradual arm or an open shape is no evidence for the overload:
             # with `({ a: Integer }) -> Integer | (Hash[Symbol, untyped]) -> String`, `{ **o, b: 2 }` has a key the
@@ -461,6 +473,11 @@ module Rigor
             result.yes? || result.maybe?
           end
 
+          # Pass 0 (`:proven`) takes a `yes` naming the argument's own class; #1800's keyword proof (`:yes`) any `yes`.
+          def proof?(result, param_type, arg, strict)
+            result.yes? && (strict == :yes || ProvenOverload.names_arg_class?(param_type, arg))
+          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).