rigortype 0.3.6 → 0.3.8

data/lib/rigor/inference/fork_map.rb

@@ -42,11 +42,16 @@ module Rigor
       #
       # A child ends at {.run_worker}'s `exit!`, which skips `at_exit` AND object finalizers, so a `Tempfile`
       # a child creates is never reclaimed by the mechanism that reclaims the parent's (issue #330 —
-      # `Protection::ClosureKillOracle`'s per-process mutant file leaked one file per worker per
+      # `Protection::ClosureKillOracle`'s mutant file leaked one file per worker per
       # `rigor coverage --protection --mutation` run). Answering with the directory the parent already removes
       # once every child has been collected makes the child's scratch state the parent's problem, which is the
       # only place it can be solved: the names are random, so nothing outside the child could find them.
       #
+      # Still load-bearing after issue #572 gave that oracle a block-scoped temp file. The block unwinds on
+      # both paths a child can take on its own — a normal return and the `StandardError` {.run_worker}
+      # rescues — but a child killed by a signal unwinds nothing at all, and this directory is what reclaims
+      # what it left behind.
+      #
       # The directory check is the belt to {.run_worker}'s braces: the offer is only worth taking while the
       # parent still has the directory open, and answering `nil` once it is gone degrades to `Dir.tmpdir`
       # instead of raising `Errno::ENOENT` somewhere far from here.

data/lib/rigor/inference/hkt_reducer.rb

@@ -85,7 +85,7 @@ module Rigor
           Type::Combinator.union(*reduced)
         when HktBody::NominalApp
           reduced_args = node.args.map { |arg| walk(arg, bindings: bindings, state: state) }
-          Type::Combinator.nominal_of(node.class_name, type_args: reduced_args)
+          reduce_nominal_app(node, reduced_args)
         when HktBody::AppRef
           reduced_args = node.args.map { |arg| walk(arg, bindings: bindings, state: state) }
           reduce_app_ref(node.uri, reduced_args, state: state)
@@ -96,6 +96,17 @@ module Rigor
         end
       end
 
+      def reduce_nominal_app(node, reduced_args)
+        normalized_name = node.class_name.sub(/\A::/, "")
+        if %w[Result Dry::Monads::Result].include?(normalized_name) && reduced_args.size == 2
+          Type::Combinator.result_of(reduced_args[0], reduced_args[1])
+        elsif %w[Maybe Dry::Monads::Maybe].include?(normalized_name) && reduced_args.size == 1
+          Type::Combinator.maybe_of(reduced_args[0])
+        else
+          Type::Combinator.nominal_of(node.class_name, type_args: reduced_args)
+        end
+      end
+
       # ADR-20 § D3 conditional reduction. Resolves the test against the current bindings and
       # picks a branch:
       #

data/lib/rigor/inference/hkt_registry.rb

@@ -150,7 +150,9 @@ module Rigor
       # loaded RBS env, parse them via {Rigor::RbsExtended::HktDirectives}, and return a new
       # registry that is the union of `base` and every parsed entry. Last-write-wins on URI
       # collisions per {#merge}'s contract. Fail-soft on per-annotation parse errors (the reporter
-      # records an `:info` entry; the other annotations still apply).
+      # records an entry the run surfaces as one `dynamic.rbs-extended.hkt-directive-invalid` `:info`
+      # diagnostic; the other annotations still apply). That claim was false until issue #785: the
+      # production reporter has no `#record`, so every declined directive was dropped silently.
       #
       # @param rbs_loader [Rigor::Environment::RbsLoader]
       # @param base [HktRegistry] starting registry (typically the bundled
@@ -158,8 +160,11 @@ module Rigor
       # @param name_scope [Rigor::Environment::NameScope, nil] threaded through to the bound
       #   resolver for class-name lookups; safe to omit during scanning since hkt bounds are
       #   typically `untyped` or stdlib classes.
-      # @param reporter [#record, nil] same fail-soft reporter contract the other RBS-extended
-      #   parsers use.
+      # @param reporter [Rigor::RbsExtended::Reporter, #record, nil] same fail-soft reporter contract
+      #   the other RBS-extended parsers use; a collecting double that responds only to `#record` /
+      #   `#<<` still works (see {Rigor::RbsExtended::HktDirectives.record_hkt_error}).
+
+      # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity, Metrics/BlockLength
       def self.scan_rbs_loader(rbs_loader, base: EMPTY, name_scope: nil, reporter: nil)
         return base if rbs_loader.nil?
 
@@ -182,6 +187,59 @@ module Rigor
           definitions << defn if defn
         end
 
+        require_relative "hkt_sugar_translator"
+        if rbs_loader.respond_to?(:each_type_alias_decl)
+          rbs_loader.each_type_alias_decl do |type_name, decl_entry|
+            decl = decl_entry.decl
+            next if decl.type_params.empty?
+
+            uri_str = type_name.to_s.sub(/\A::/, "")
+            next unless uri_str.include?("::")
+
+            uri = uri_str.to_sym
+
+            params = decl.type_params.map(&:name)
+            params_set = params.to_set
+
+            # No rescue around this translate. HktSugarTranslator degrades every alias shape it
+            # cannot model (a non-recursive alias, a malformed self-reference) to a leaf, so a
+            # parseable `type` alias never raises here — that is the fix for issue #776, where an
+            # unknown keyword aborted this shared, memoised build and turned every file into an
+            # `internal analyzer error`. An exception that still reaches this point is an analyzer
+            # bug and MUST propagate rather than silently dropping the alias, matching
+            # RbsLoader#each_known_class_name's fail-soft contract. It propagates to the seam in
+            # `Environment#hkt_registry` (issue #784), which records it and degrades to the pre-scan
+            # registry so it surfaces once per run instead of reaching every file's analysis.
+            translator = HktSugarTranslator.new(uri: uri, params_set: params_set)
+            body_tree = translator.translate(decl.type)
+
+            next unless translator.recursive
+
+            variance = decl.type_params.map do |p|
+              case p.variance
+              when :covariant then :out
+              when :contravariant then :in
+              else :inv
+              end
+            end
+
+            registrations << Registration.new(
+              uri: uri,
+              arity: params.size,
+              variance: variance,
+              bound: Type::Combinator.untyped
+            )
+            definitions << Definition.new(
+              uri: uri,
+              params: params,
+              body: "",
+              body_tree: body_tree,
+              source_path: decl.location&.buffer&.name,
+              source_line: decl.location&.start_line
+            )
+          end
+        end
+
         return base if registrations.empty? && definitions.empty?
 
         overlay = new(registrations: registrations, definitions: definitions)

data/lib/rigor/inference/hkt_sugar_translator.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "rbs"
+require_relative "hkt_body"
+
+module Rigor
+  module Inference
+    class HktSugarTranslator
+      attr_reader :recursive
+
+      def initialize(uri:, params_set:)
+        @uri = uri
+        @params_set = params_set
+        @recursive = false
+      end
+
+      # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      def translate(type)
+        case type
+        when RBS::Types::Alias
+          if type.name.to_s.sub(/\A::/, "") == @uri.to_s && !type.args.empty?
+            @recursive = true
+            args = type.args.map { |a| translate(a) }
+            HktBody::AppRef.new(uri: @uri, args: args)
+          else
+            # Everything else degrades to a concrete leaf: HktBody has no AliasRef node and Rigor
+            # resolves non-HKT aliases through RbsLoader. A bare self-reference with no type
+            # arguments (`type Foo::x[T] = ... | Foo::x`) lands here too — it is malformed for a
+            # parameterized alias (`rbs validate` rejects it), so it must not build an empty-args
+            # `AppRef`, which `HktBody` rejects.
+            fallback_to_type_leaf(type)
+          end
+        when RBS::Types::ClassInstance
+          class_name = type.name.to_s.sub(/\A::/, "")
+          if type.args.empty?
+            HktBody::TypeLeaf.new(type: Rigor::Type::Nominal.new(class_name))
+          else
+            args = type.args.map { |a| translate(a) }
+            HktBody::NominalApp.new(class_name: class_name, args: args)
+          end
+        when RBS::Types::Variable
+          if @params_set.include?(type.name)
+            HktBody::Param.new(name: type.name)
+          else
+            fallback_to_type_leaf(type)
+          end
+        when RBS::Types::Union
+          HktBody::Union.new(arms: type.types.map { |t| translate(t) })
+        when RBS::Types::Optional
+          HktBody::Union.new(arms: [
+                               translate(type.type),
+                               HktBody::TypeLeaf.new(type: Rigor::Type::Constant.new(nil))
+                             ])
+        when RBS::Types::Bases::Nil
+          HktBody::TypeLeaf.new(type: Rigor::Type::Constant.new(nil))
+        when RBS::Types::Bases::Bool
+          HktBody::TypeLeaf.new(type: Rigor::Type::Combinator.union(Rigor::Type::Constant.new(true), Rigor::Type::Constant.new(false)))
+        when RBS::Types::Bases::Any
+          HktBody::TypeLeaf.new(type: Rigor::Type::Combinator.untyped)
+        else
+          fallback_to_type_leaf(type)
+        end
+      end
+
+      private
+
+      # The `else` arm and the unbound-variable / non-recursive-alias arms all degrade a subterm the
+      # HKT body grammar has no node for to a concrete `Rigor::Type` leaf. `RbsTypeTranslator` has no
+      # name-scope parameter — it never resolves relative names — and the alias decls this walk reads
+      # come off a `resolve_type_names`-d environment, so names arrive already absolute and there is
+      # nothing a scope would do here. `alias_expander: nil` is deliberate too: a nested alias reached
+      # in this fallback degrades to `Dynamic[Top]` rather than pulling a second alias body into an
+      # HKT definition.
+      def fallback_to_type_leaf(type)
+        require_relative "rbs_type_translator" unless defined?(RbsTypeTranslator)
+        rigor_type = RbsTypeTranslator.translate(
+          type,
+          alias_expander: nil,
+          type_vars: {},
+          self_type: Rigor::Type::Combinator.untyped,
+          instance_type: Rigor::Type::Combinator.untyped
+        )
+        HktBody::TypeLeaf.new(type: rigor_type)
+      end
+    end
+  end
+end

data/lib/rigor/inference/index_write_widening.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "mutation_widening"
+
+module Rigor
+  module Inference
+    # `h[k] ||= v`, `h[k] &&= v` and `h[k] += v` store through `[]=`, but Prism gives each its own node class rather
+    # than a `[]=` `CallNode`. None of them therefore reached {MutationWidening.widen_after_call}, and a literal-shape
+    # binding outlived its justification: an `@h = {}` written only through `@h[k] ||= {}` kept its empty `HashShape`,
+    # so `@h.empty?` folded to `Constant[true]` and `return nil if x.nil? || @h.empty?` drew a false
+    # `flow.always-truthy-condition` on a hash the class fills.
+    #
+    # Two consumers need the same recognition and neither had it: {StatementEvaluator} for the straight-line write, and
+    # {ScopeIndexer}'s class-ivar pre-pass for the cross-method one (an ivar written in `add` and read in `probe`).
+    # `||=` / `&&=` are conditional at runtime, but a widening may only LOSE precision, so answering on the branch that
+    # does not store is safe.
+    #
+    # `Prism::IndexTargetNode` is deliberately absent: it is a multi-assign TARGET, and the `MultiWriteNode` that owns
+    # it is where that write is observed.
+    module IndexWriteWidening
+      NODE_CLASSES = [Prism::IndexOrWriteNode, Prism::IndexAndWriteNode, Prism::IndexOperatorWriteNode].freeze
+
+      # The method these forms store through — the name the mutator tables are keyed on.
+      MUTATOR = :[]=
+
+      module_function
+
+      # @param node [Prism::Node]
+      def index_write?(node)
+        NODE_CLASSES.any? { |klass| node.is_a?(klass) }
+      end
+
+      # `arg_types` is the `[key, stored_value]` pair the caller typed, shaped like a `[]=` call's argument list so
+      # the widening joins the stored value into the carrier's content evidence exactly as a real `[]=` does
+      # (issue #560). Empty means "no evidence" and widens without joining.
+      #
+      # @param node          [Prism::Node] one of {NODE_CLASSES}
+      # @param current_scope [Rigor::Scope]
+      # @param arg_types     [Array<Rigor::Type::Base>]
+      # @return              [Rigor::Scope]
+      def widen(node:, current_scope:, arg_types: MutationWidening::NO_ARG_TYPES)
+        MutationWidening.widen_receiver_aliases(node.receiver, MUTATOR, current_scope, arg_types: arg_types)
+      end
+    end
+  end
+end

data/lib/rigor/inference/indexed_narrowing.rb

@@ -83,6 +83,20 @@ module Rigor
         [receiver.first, receiver.last, key]
       end
 
+      # Issue #544 — whether the RECEIVER's type is precise enough for a recorded slot value to be a
+      # fact. A `Dynamic` / `Top` constituent means the collection can hold a caller-supplied value at
+      # the slot that `||=` keeps, so recording the default alone would invent a fact (mail's
+      # `options[:count] ||= :all` folded a reachable `count: 1` path away). Unions walk their members;
+      # everything else — the tracked `HashShape` / `Tuple` carriers this feature was built for, and
+      # plain nominals whose RBS read already answers honestly — passes.
+      def fully_tracked_receiver_type?(type)
+        case type
+        when Type::Dynamic, Type::Top then false
+        when Type::Union then type.members.all? { |m| fully_tracked_receiver_type?(m) }
+        else true
+        end
+      end
+
       # Looks up a recorded narrowing for `receiver[key]` against `scope`, returning the narrowed
       # type or nil when no entry applies. Used by ExpressionTyper's `[]` dispatch to refine the
       # result of a stable indexed read.

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

@@ -136,7 +136,7 @@ module Rigor
         end
 
         # @return [:always_true, :always_false, :bool, nil]
-        # rubocop:disable Metrics/CyclomaticComplexity
+        # rubocop:disable-next Metrics/CyclomaticComplexity
         def predicate_decision(method_name, truthiness, emptiness)
           case method_name
           when :all?
@@ -159,7 +159,6 @@ module Rigor
             :bool
           end
         end
-        # rubocop:enable Metrics/CyclomaticComplexity
 
         def bool_union
           Type::Combinator.union(
@@ -185,10 +184,13 @@ module Rigor
         end
 
         def constant_emptiness(value)
-          # Only `Range` constants reach these folds: `Type::Constant` rejects Array / Hash literals (they
-          # become `Tuple` / `HashShape` carriers), and the remaining scalar constants (Integer / Float /
-          # Symbol / String / …) are not Enumerable receivers for the filter or predicate methods folded here.
+          # `Range` constants and folded `Set` values (SetFolding wraps a real frozen ::Set) are the
+          # Enumerable receivers that reach these folds: `Type::Constant` rejects Array / Hash literals
+          # (they become `Tuple` / `HashShape` carriers), and the remaining scalar constants (Integer /
+          # Float / Symbol / String / …) are not Enumerable receivers for the filter or predicate methods
+          # folded here.
           return range_emptiness(value) if value.is_a?(Range)
+          return (value.empty? ? :empty : :non_empty) if value.is_a?(::Set)
 
           :unknown
         end

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

@@ -220,6 +220,16 @@ module Rigor
           method_name = context.method_name
           args = context.args
 
+          # Issue #539 — every fold in this tier executes the BLOCKLESS form of the method against the
+          # constant value. A call site that passes a block (literal or `&arg`) has different semantics —
+          # `SET.any? { |n| lookup(n) }` folded to the blockless `Set#any?`'s `true` on any non-empty set,
+          # a wrong type the flow rules then amplified (`flow.always-truthy-condition` on our own lib).
+          # The catalog's `block_dependent` classification covers the C body's own iterator, not the call
+          # site's block, so the guard belongs here. Internal per-element dispatches hand a non-CallNode
+          # (e.g. the `&:sym` BlockArgumentNode) as `call_node` — those carry no call-site block.
+          call_node = context.call_node
+          return nil if call_node.is_a?(Prism::CallNode) && call_node.block
+
           if REFLECTIVE_SEND_METHODS.include?(method_name)
             first_arg = args.first
             return nil unless first_arg.is_a?(Type::Constant) && first_arg.value.is_a?(Symbol)

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "../../type"
+require_relative "singleton_folding"
+
+module Rigor
+  module Inference
+    module MethodDispatcher
+      # Folds `JSON.generate` / `JSON.pretty_generate` to their precise return type.
+      #
+      # Both methods always return a `String` or raise (`JSON::GeneratorError`, `JSON::NestingError`, …) —
+      # never `nil`, never a non-`String` value. Upstream RBS (`stdlib/json/0/json.rbs`) already declares
+      # `generate` as `-> String`, but `pretty_generate` is declared `-> untyped`, so every
+      # `JSON.pretty_generate` call widens to `Dynamic[top]` and every downstream method call on the result
+      # loses precision with it. This tier closes that gap by construction rather than waiting on an
+      # upstream RBS fix, and folds `generate` alongside it for symmetry — a `Nominal[String]` answer here
+      # is monotone over both today's `untyped` (`pretty_generate`) and today's already-precise `String`
+      # (`generate`).
+      #
+      # Unlike `CGIFolding` / `ShellwordsFolding`, this tier does NOT evaluate the argument. `JSON.generate`
+      # is not a pure function whose *result* can be computed at analysis time in general — the object graph
+      # can be arbitrarily large, cyclic, or rely on a user-defined `#to_json` — so only the *return type* is
+      # folded here, never the *return value*. A future literal-argument constant fold (mirroring
+      # `ConstantFolding`'s treatment of other pure stdlib calls) can layer on top of this tier without
+      # changing it.
+      #
+      # === Supported methods
+      #
+      # * `generate(obj)` / `generate(obj, opts)` — returns `Nominal[String]`.
+      # * `pretty_generate(obj)` / `pretty_generate(obj, opts)` — returns `Nominal[String]`.
+      #
+      # === Unsupported cases
+      #
+      # Returns `nil` (deferring to the next dispatcher tier) when:
+      # - the receiver is not `Singleton[JSON]`,
+      # - the method is not `generate` / `pretty_generate` (e.g. `JSON.parse`, `JSON.dump`),
+      # - the call has the wrong arity (not 1 or 2 positional arguments).
+      module JSONFolding
+        JSON_GENERATE_METHODS = Set[:generate, :pretty_generate].freeze
+        private_constant :JSON_GENERATE_METHODS
+
+        module_function
+
+        # @return [Rigor::Type, nil] folded result, or nil to defer.
+        def try_dispatch(context)
+          receiver = context.receiver
+          method_name = context.method_name
+          args = context.args
+          return nil unless SingletonFolding.receiver?(receiver, "JSON")
+          return nil unless JSON_GENERATE_METHODS.include?(method_name)
+          return nil unless args.size.between?(1, 2)
+
+          Type::Combinator.nominal_of("String")
+        end
+      end
+    end
+  end
+end

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

@@ -80,10 +80,22 @@ module Rigor
         #   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)
+        def select(method_definition, **) = select_candidates(method_definition, **).first
+
+        # Issue #521 — like {.select}, but when a `Dynamic[Top]` argument reaches the gradual pass it
+        # returns EVERY gradually-matching overload instead of pinning the first. An untyped argument
+        # accepts every param indiscriminately, so "first gradual match" is decided by overload-list
+        # 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. Every other path (strict,
+        # alias-resolved, typed-gradual, arity fallback) still yields exactly one candidate, so `select`
+        # keeps its historical single answer.
+        #
+        # @return [Array<RBS::MethodType>] matching overloads; empty when the definition declares none.
+        def select_candidates(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?
+          return [] 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
@@ -96,15 +108,18 @@ module Rigor
           # an arbitrary sibling-class arm that only wins by overload-list position.
           overloads = ReceiverAffinity.reorder(overloads, self_type: self_type, environment: environment)
 
+          alias_expander = environment&.rbs_loader
           passes = lambda do |require_block|
             run_selection_passes(
-              overloads, arg_types: arg_types, self_type: self_type, instance_type: instance_type,
-                         type_vars: type_vars, block_required: require_block, param_overrides: param_overrides
+              overloads,
+              { arg_types: arg_types, self_type: self_type, instance_type: instance_type,
+                type_vars: type_vars, block_required: require_block, param_overrides: param_overrides,
+                alias_expander: alias_expander }
             )
           end
 
-          match = passes.call(block_required)
-          return match if match
+          matches = passes.call(block_required)
+          return matches unless matches.empty?
 
           # 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
@@ -112,8 +127,8 @@ 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
-            match = passes.call(false)
-            return match if match
+            matches = passes.call(false)
+            return matches unless matches.empty?
           end
 
           # No (usable) block at the call site: prefer an overload that does not REQUIRE a block over
@@ -121,7 +136,7 @@ module Rigor
           # 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
+          [overloads.find { |mt| !overload_requires_block?(mt) } || overloads.first]
         end
 
         def overload_has_block?(method_type)
@@ -147,38 +162,58 @@ module Rigor
           #   `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 = {
-              arg_types: arg_types, self_type: self_type, instance_type: instance_type,
-              type_vars: type_vars, block_required: block_required, param_overrides: param_overrides
-            }
-            find_matching_overload(overloads, **shared, strict: true) ||
-              find_matching_overload_via_aliases(overloads, arg_types: arg_types, block_required: block_required) ||
-              find_matching_overload(overloads, **shared, strict: false)
+          # `shared` is the caller-assembled keyword bundle for `find_matching_overload` — hash-shaped
+          # because the pass pipeline forwards it twice and RuboCop's parameter-list budget is real.
+          def run_selection_passes(overloads, shared)
+            strict = 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
+
+            # Pass 2, array-valued. With every argument carrying real type information the first gradual
+            # match keeps its historical single-winner contract. With a `Dynamic[Top]` 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| untyped_arg?(t) }
+
+            matches
           end
 
-          # rubocop:disable Metrics/ParameterLists
+          # rubocop:disable-next Metrics/ParameterLists
           def find_matching_overload(overloads, arg_types:, self_type:, instance_type:, type_vars:, block_required:,
-                                     param_overrides:, strict:)
-            return nil if strict && arg_types.any? { |t| untyped_arg?(t) }
+                                     param_overrides:, strict:, alias_expander: nil)
+            return [] if strict && arg_types.any? { |t| untyped_arg?(t) }
 
-            overloads.find do |method_type|
-              next false if block_required && !OverloadSelector.overload_has_block?(method_type)
-              next false if !block_required && OverloadSelector.overload_requires_block?(method_type)
+            predicate = lambda do |method_type|
+              next false unless engages_block_shape?(method_type, block_required)
               next false if strict && !strictly_typed_params?(method_type, arg_types.size)
 
               matches?(
-                method_type,
-                arg_types,
-                self_type: self_type,
-                instance_type: instance_type,
-                type_vars: type_vars,
-                param_overrides: param_overrides
+                method_type, arg_types,
+                self_type: self_type, instance_type: instance_type,
+                type_vars: type_vars, param_overrides: param_overrides,
+                alias_expander: alias_expander
               )
             end
+            # Strict keeps its historical first-match short-circuit (a dispatch hot path); the gradual
+            # pass needs the full candidate list for the #521 union.
+            return [overloads.find(&predicate)].compact if strict
+
+            overloads.select(&predicate)
+          end
+
+          # Whether the overload's block clause is compatible with the call site's block shape: a
+          # block-bearing call engages only block-declaring overloads; a block-less call skips overloads
+          # that REQUIRE one.
+          def engages_block_shape?(method_type, block_required)
+            return OverloadSelector.overload_has_block?(method_type) if block_required
+
+            !OverloadSelector.overload_requires_block?(method_type)
           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
@@ -194,9 +229,13 @@ module Rigor
           # 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:)
+            # 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| untyped_arg?(t) }
+
             overloads.find do |method_type|
-              next false if block_required && !OverloadSelector.overload_has_block?(method_type)
-              next false if !block_required && OverloadSelector.overload_requires_block?(method_type)
+              next false unless engages_block_shape?(method_type, block_required)
 
               fun = method_type.type
               next false unless arity_compatible?(fun, arg_types.size)
@@ -278,7 +317,8 @@ module Rigor
             end
           end
 
-          def matches?(method_type, arg_types, self_type:, instance_type:, type_vars:, param_overrides:)
+          def matches?(method_type, arg_types, self_type:, instance_type:, type_vars:, param_overrides:,
+                       alias_expander: nil)
             return false if method_type.respond_to?(:type_params) && rejects_keyword_required?(method_type)
 
             fun = method_type.type
@@ -292,7 +332,8 @@ module Rigor
                 self_type: self_type,
                 instance_type: instance_type,
                 type_vars: type_vars,
-                param_overrides: param_overrides
+                param_overrides: param_overrides,
+                alias_expander: alias_expander
               )
             end
           end
@@ -346,12 +387,14 @@ module Rigor
             head
           end
 
-          def accepts_param?(param, arg, self_type:, instance_type:, type_vars:, param_overrides:)
+          def accepts_param?(param, arg, self_type:, instance_type:, type_vars:, param_overrides:,
+                             alias_expander: nil)
             param_type = param_overrides[param.name] || RbsTypeTranslator.translate(
               param.type,
               self_type: self_type,
               instance_type: instance_type,
-              type_vars: type_vars
+              type_vars: type_vars,
+              alias_expander: alias_expander
             )
             # 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