rigortype 0.3.6 → 0.3.7

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

@@ -51,7 +51,7 @@ module Rigor
       #   a rest positional (`*T`), or a keyword parameter is still unbound and degrades to `Dynamic[Top]`.
       #
       # See docs/adr/4-type-inference-engine.md for the broader plan.
-      # rubocop:disable Metrics/ModuleLength
+      # rubocop:disable-next Metrics/ModuleLength
       module RbsDispatch
         module_function
 
@@ -144,7 +144,7 @@ module Rigor
           )
         end
 
-        # rubocop:disable Metrics/ClassLength
+        # rubocop:disable-next Metrics/ClassLength
         class << self
           private
 
@@ -230,6 +230,13 @@ module Rigor
               # still resolve through Method's RBS contract. Routing here keeps reflective Method methods
               # working without forcing the carrier to collapse to a plain Nominal at construction.
               ["Method", :instance, []]
+            when Type::Refined, Type::Difference
+              # #533 — a refinement (`Refined`) or subtraction (`Difference` — `non-empty-string` is
+              # `String − ""`) is a precision layer over its base; RBS method lookup erases to the base
+              # carrier (`RUBY_VERSION != "1.0"` resolves through `String#!=` instead of declining the
+              # whole dispatch to Dynamic). The refinement-aware promotions (`String#upcase` →
+              # `uppercase-string`, …) run in their own catalog tier ABOVE this one, so they still win.
+              receiver_descriptor(receiver.base)
             when Type::Dynamic
               receiver_descriptor(receiver.static_facet)
             end
@@ -355,7 +362,7 @@ module Rigor
             # fallback returns the caller's type, not Object.
             self_type = self_type_override || resolved_self_type
 
-            method_type = OverloadSelector.select(
+            candidates = OverloadSelector.select_candidates(
               method_definition,
               arg_types: args,
               self_type: self_type,
@@ -364,17 +371,15 @@ module Rigor
               block_required: !block_type.nil?,
               environment: environment
             )
-            return nil unless method_type
+            return nil if candidates.empty?
 
             call_site = [class_name, method_name, kind]
-            record_dispatch_provenance(method_definition, method_type, scope, call_node, call_site)
-            full_type_vars = compose_type_vars(method_type, type_vars, args, block_type, scope, call_node, call_site)
-
-            RbsTypeTranslator.translate(
-              method_type.type.return_type,
-              self_type: self_type,
-              instance_type: instance_type,
-              type_vars: full_type_vars
+            record_dispatch_provenance(method_definition, candidates.first, scope, call_node, call_site)
+            join_candidate_returns(
+              candidates,
+              self_type: self_type, instance_type: instance_type, type_vars: type_vars,
+              args: args, block_type: block_type, scope: scope, call_node: call_node, call_site: call_site,
+              alias_expander: environment.rbs_loader
             )
           end
 
@@ -400,6 +405,38 @@ module Rigor
           # The two method-level type-parameter binding positions, layered in precedence order over the
           # receiver-derived `type_vars`: the block return type first, then the argument positions (which
           # never displace an existing key). See {#compose_arg_type_vars} for the argument envelope.
+          # Issue #521 — more than one candidate means a `Dynamic[Top]` argument made the overloads
+          # indistinguishable; pinning the first answered a wrong precise type the runtime can contradict
+          # (`[true] * n` read as String). The join is the candidates' return union wrapped in `Dynamic`,
+          # not the bare union: the untyped argument may satisfy constraints (kwarg shapes, value pins)
+          # that exclude arms statically-indistinguishable here, so a bare union licenses the negative
+          # rules to fire on arms the runtime never takes — measured immediately as three false positives
+          # on this repository's own `lib` (`Integer(v)` joining the `exception: bool` nil arm). The
+          # `Dynamic[T]` carrier keeps the candidate set visible without that license (ADR-5).
+          # A candidate whose return does not translate leaves the join incomplete — decline (fail-soft
+          # to Dynamic downstream) rather than answer a join missing an arm the runtime can take.
+          # rubocop:disable-next Metrics/ParameterLists
+          def join_candidate_returns(candidates, self_type:, instance_type:, type_vars:, args:, block_type:,
+                                     scope:, call_node:, call_site:, alias_expander: nil)
+            returns = candidates.map do |method_type|
+              full_type_vars = compose_type_vars(method_type, type_vars, args, block_type, scope, call_node, call_site)
+              RbsTypeTranslator.translate(
+                method_type.type.return_type,
+                self_type: self_type,
+                instance_type: instance_type,
+                type_vars: full_type_vars,
+                alias_expander: alias_expander
+              )
+            end
+            return returns.first if returns.size == 1
+            return nil if returns.any?(&:nil?)
+
+            distinct = returns.uniq
+            return distinct.first if distinct.size == 1
+
+            Type::Combinator.dynamic(Type::Combinator.union(*distinct))
+          end
+
           def compose_type_vars(method_type, type_vars, args, block_type, scope, call_node, call_site)
             vars = compose_block_type_vars(method_type, type_vars, block_type)
             compose_arg_type_vars(method_type, vars, args, scope: scope, call_node: call_node,
@@ -658,7 +695,8 @@ module Rigor
               block,
               self_type: self_type,
               instance_type: instance_type,
-              type_vars: type_vars
+              type_vars: type_vars,
+              alias_expander: environment.rbs_loader
             )
           end
 
@@ -666,7 +704,7 @@ module Rigor
           # list; some signatures use `RBS::Types::UntypedFunction` (a `(?)` block) which exposes no
           # parameter types -- we treat it as "no information" and return an empty array so the binder
           # defaults every slot.
-          def translate_block_positional_params(block, self_type:, instance_type:, type_vars:)
+          def translate_block_positional_params(block, self_type:, instance_type:, type_vars:, alias_expander: nil)
             fun = block.type
             return [] unless fun.respond_to?(:required_positionals)
 
@@ -676,14 +714,13 @@ module Rigor
                 param.type,
                 self_type: self_type,
                 instance_type: instance_type,
-                type_vars: type_vars
+                type_vars: type_vars,
+                alias_expander: alias_expander
               )
             end
           end
         end
-        # rubocop:enable Metrics/ClassLength
       end
-      # rubocop:enable Metrics/ModuleLength
     end
   end
 end

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

@@ -48,7 +48,7 @@ module Rigor
       #
       # See docs/internal-spec/inference-engine.md (Slice 5 phase 2) and docs/adr/4-type-inference-engine.md
       # for the slice rationale.
-      # rubocop:disable Metrics/ClassLength, Metrics/ModuleLength
+      # rubocop:disable-next Metrics/ClassLength, Metrics/ModuleLength
       module ShapeDispatch
         module_function
 
@@ -1920,7 +1920,6 @@ module Rigor
           end
         end
       end
-      # rubocop:enable Metrics/ClassLength, Metrics/ModuleLength
     end
   end
 end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative "../../type"
+
+module Rigor
+  module Inference
+    module MethodDispatcher
+      # `Foo.instance`, where `Foo` includes the stdlib `Singleton` mixin.
+      #
+      # Ruby grows that class method through a hook — `Singleton.included(klass)` extends the class with
+      # `Singleton::SingletonClassMethods` — so nothing static declares it, and the upstream RBS does not close
+      # the gap either: `stdlib/singleton/0/singleton.rbs` declares `def self.instance: () -> instance` on the
+      # module itself and leaves `module SingletonClassMethods` **empty**. `Singleton.instance` is not a call
+      # anyone makes; `Foo.instance` is the entire point of the mixin, and it typed `Dynamic[Top]`.
+      #
+      # That is expensive out of proportion to its site count, because the value is a whole object: every
+      # method called on the returned instance is then dispatched on `Dynamic` too. Mastodon has 365 such
+      # calls (`ActivityPub::TagManager.instance`, `FeedManager.instance`, `TagManager.instance`).
+      #
+      # The rule is exact rather than heuristic — the receiver must be a `Singleton[C]` whose `C` the project
+      # pre-pass recorded as including `Singleton` — so a class that does not include the mixin is untouched,
+      # and a project that defines its own `Singleton` module is the one case that would misfire. Guarded by
+      # {project_singleton_shadow?}: a project-declared `Singleton` class or module wins and the tier declines,
+      # because then the name means something else entirely.
+      module SingletonMixinDispatch
+        MIXIN_NAMES = Ractor.make_shareable(Set["Singleton", "::Singleton"])
+        private_constant :MIXIN_NAMES
+
+        SELECTOR = :instance
+        private_constant :SELECTOR
+
+        module_function
+
+        # @param context [CallContext]
+        # @return [Rigor::Type, nil] `Nominal[C]` for `C.instance`, or nil to decline.
+        def try_dispatch(context)
+          return nil unless context.method_name == SELECTOR
+          return nil unless context.args.empty?
+
+          receiver = context.receiver
+          return nil unless receiver.is_a?(Type::Singleton)
+
+          scope = context.scope
+          return nil if scope.nil?
+          return nil unless includes_singleton_mixin?(scope, receiver.class_name)
+          return nil if project_singleton_shadow?(scope)
+
+          Type::Combinator.nominal_of(receiver.class_name)
+        end
+
+        def includes_singleton_mixin?(scope, class_name)
+          scope.includes_of(class_name).any? { |name| MIXIN_NAMES.include?(name.to_s) }
+        end
+
+        # True when the project declares its OWN `Singleton` class / module, in which case `include Singleton`
+        # names that one and the stdlib rule does not apply.
+        def project_singleton_shadow?(scope)
+          MIXIN_NAMES.any? { |name| scope.discovery.discovered_classes.key?(name.to_s.delete_prefix("::")) }
+        end
+      end
+    end
+  end
+end

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

@@ -2,6 +2,7 @@
 
 require_relative "../../type"
 require_relative "singleton_folding"
+require_relative "struct_materialization"
 require_relative "member_shape_projection"
 
 module Rigor
@@ -41,6 +42,9 @@ module Rigor
         # and the reader-redefinition guard are shared with {DataFolding}.
         extend MemberShapeProjection
 
+        # Issue #595 / #525 — the shared materialisation test; see {StructMaterialization}.
+        extend StructMaterialization
+
         # @return [Rigor::Type, nil] the folded result, or nil to defer.
         def try_dispatch(context)
           receiver = context.receiver
@@ -258,16 +262,8 @@ module Rigor
         # read) or a FOLD-SAFE stored local (ADR-48 slice 3 — `StructFoldSafety` proved the binding is
         # never mutated / aliased / escaped in its scope).
         def foldable_receiver?(context)
-          fresh_receiver?(context) || fold_safe_local_receiver?(context)
-        end
-
-        # A fresh receiver is the transient result of a chained call (`Point.new(1, 2).x`,
-        # `inst.with(x: 9).y`).
-        def fresh_receiver?(context)
-          node = context.call_node
-          return false if node.nil?
-
-          node.receiver.is_a?(Prism::CallNode)
+          fresh_receiver?(context) || fold_safe_local_receiver?(context) ||
+            fold_safe_self_receiver?(context)
         end
 
         # A fold-safe stored receiver is a local-variable read whose name the body's fold-safe set (on the
@@ -282,6 +278,63 @@ module Rigor
           scope.struct_fold_safe?(receiver.name)
         end
 
+        # Issue #525 — the in-body half. A member read written with no receiver (or `self.member`) inside a
+        # method the CALLER resolved on a fold-safe struct receiver: `Line.new("a", 2).shout` re-types
+        # `shout`'s body with `self_type` = the caller's `StructInstance`, and the implicit-self `text` read
+        # arrives here with the right carrier but no receiver node, so neither of the two arms above can see
+        # that the caller's receiver was foldable.
+        #
+        # The caller records that grant as the `:self` sentinel in the body scope's fold-safe set — a
+        # `Set[Symbol]` no Ruby local can collide with, since `self` is a keyword. The grant is issued only
+        # for a `StructInstance` carrier whose body {Inference::StructFoldSafety.self_fold_safe_body?}
+        # cleared, and it is tied HERE to the exact carrier it was issued for: a body scope reached by any
+        # other route types its `self` differently, and the read declines rather than fold a map that
+        # belongs to a different instance.
+        def fold_safe_self_receiver?(context)
+          node = context.call_node
+          return false if node.nil?
+
+          receiver_node = node.receiver
+          return false unless receiver_node.nil? || receiver_node.is_a?(Prism::SelfNode)
+
+          scope = context.scope
+          return false unless scope&.struct_fold_safe?(:self)
+
+          same_carrier?(context.receiver, scope.self_type)
+        end
+
+        # Carrier identity for the `:self` grant. `StructInstance` carries structural equality over exactly
+        # the two fields that matter here (`value_fields :members, :class_name`), so `==` is both the tighter
+        # comparison and allocation-free — no display string is built.
+        def same_carrier?(receiver, self_type)
+          receiver.is_a?(Type::StructInstance) && receiver == self_type
+        end
+
+        # A fresh receiver is the result of a chained call that MATERIALISED the struct — `Point.new(1, 2).x`,
+        # `Point[1, 2].x`, `inst.with(x: 9).y`. Not merely a chained call: slices 1-2 read "chained" as
+        # "cannot have been mutated between materialisation and the read", and a method that hands back its
+        # own receiver falsifies that (issue #595):
+        #
+        #     Line = Struct.new(:text) do
+        #       def with_text(v) = (self.text = v; self)
+        #       def dup_self    = self
+        #     end
+        #     x = Line.new("a"); x.text = "z"
+        #     x.dup_self.text                    # the chain returns the SAME, mutated object
+        #     Line.new("a").with_text("z").text  # so does the fluent spelling
+        #
+        # Both folded the construction-time `"a"` against a runtime `"z"` — a wrong precise value on
+        # ordinary fluent-builder Ruby. `infer_user_method_return` types a body under a fixed `self_type`,
+        # so the setter never poisons the returned `self`, and the freshness test never asked the callee
+        # what it returns. Restricting the test to the shapes this module itself materialises closes the
+        # family in one place: any other callee refuses, whatever it does internally.
+        def fresh_receiver?(context)
+          node = context.call_node
+          return false if node.nil?
+
+          materialization_call?(node.receiver, context.receiver, context.scope)
+        end
+
         # ADR-48 slice 4 — precise mutated-member re-typing. After a `local.member = v` setter on a
         # fold-safe `StructInstance` local, rebind the local to a `StructInstance` with that member replaced
         # by the assigned type, so a later `local.member` read folds to the assigned value (and a sibling

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../../type"
+require_relative "../../source/constant_path"
+
+module Rigor
+  module Inference
+    module MethodDispatcher
+      # Issue #595 / #525 — the ONE answer to "did this receiver expression just BUILD the struct?", shared by
+      # the two gates that must not disagree about it: {StructFolding#fresh_receiver?}, which decides whether a
+      # direct member read folds, and `ExpressionTyper`'s caller-side `:self`-grant arm, which decides whether a
+      # whole method body may fold its receiverless member reads.
+      #
+      # They had forked answers once — the grant arm was tightened for #591 while the read gate still trusted
+      # any chained call — and that is exactly how the composed `x.dup_self.with(indent: 9).shout` shape
+      # survived: a correctly whitelisted `.with` fold firing off a receiver the other gate wrongly called
+      # fresh. One implementation is the fix for the class of divergence, not just for that shape — and the
+      # module takes NO resolver parameter for the same reason: a lookup each consumer supplies is a fork
+      # waiting to happen, so the `.with` guard resolves through `Scope` itself (#598 review).
+      #
+      # Scope is this module's only entry: `StructFolding` `extend`s it, and since `module_function` copies
+      # arrive private through `extend`, the predicate stays callable under this module's own name.
+      module StructMaterialization
+        module_function
+
+        # Issue #595 / #525 — the ONE materialisation test. Both places that must answer "was this receiver
+        # expression's struct newly built?" go through it: this module's direct member-read gate above, and
+        # `ExpressionTyper`'s caller-side `:self`-grant arm. They had forked answers once (the grant arm was
+        # tightened for #591 while this one still trusted any chained call), which is exactly how the
+        # composed `x.dup_self.with(indent: 9).shout` shape survived — a correctly whitelisted `.with` fold
+        # firing off a receiver the other gate should never have called fresh.
+        #
+        #
+        # @param node [Prism::Node, nil] the receiver EXPRESSION.
+        # @param receiver [Rigor::Type, nil] the carrier the expression produced.
+        # @param scope [Rigor::Scope, nil]
+        def materialization_call?(node, receiver, scope)
+          return false unless node.is_a?(Prism::CallNode)
+
+          case node.name
+          when :new, :[] then struct_class_expression?(node.receiver, scope)
+          when :with then !hand_written_with?(receiver, scope)
+          else false
+          end
+        end
+
+        # `.with` copies the receiver into a new instance — unless the struct wrote its own, which is free to
+        # return `self` and would reopen the very hole above.
+        #
+        # An ANONYMOUS carrier cannot have one: a `StructInstance` with no class name came from a blockless
+        # `Struct.new(…)` (the block form defers in {fold_struct_new} before any instance exists), and a
+        # blockless factory defines nothing but the generated accessors. So it is the NAMED carriers that
+        # need the lookup — and a named one with no scope to ask refuses, since unproven is not fresh.
+        def hand_written_with?(receiver, scope)
+          return true unless receiver.is_a?(Type::StructInstance)
+
+          class_name = receiver.class_name
+          return false if class_name.nil?
+          return true if scope.nil?
+
+          # The ANCESTOR walk, not the own-class table: a `with` contributed by an included module is just as
+          # free to return `self`. Both consumers reach the identical answer because there is one lookup here
+          # rather than a parameter each of them supplies (#598 review).
+          !scope.user_def_through_ancestors(class_name, :with).first.nil?
+        end
+
+        # An expression naming the struct class itself. All three definition forms ADR-48 supports qualify,
+        # because each of them really does construct: a constant whose member layout the project side-table
+        # recorded (`Point.new(…)`), a local holding a `StructClass` carrier (`c = Struct.new(:x, :y)` then
+        # `c.new(…)`), and the inline factory chain (`Struct.new(:x, :y).new(…)`). The local arm reads the
+        # binding rather than re-typing the node, so it costs one hash read and cannot re-enter dispatch.
+        def struct_class_expression?(node, scope)
+          return false if scope.nil?
+
+          case node
+          when Prism::ConstantReadNode, Prism::ConstantPathNode
+            name = Source::ConstantPath.qualified_name_or_nil(node)
+            !name.nil? && !scope.struct_member_layout(name).nil?
+          when Prism::LocalVariableReadNode
+            scope.local(node.name).is_a?(Type::StructClass)
+          when Prism::CallNode
+            inline_struct_factory?(node)
+          else false
+          end
+        end
+
+        # `Struct.new(:a, :b)` / `Data.define(:a, :b)` written inline as the receiver of the `.new` that
+        # materialises the instance.
+        def inline_struct_factory?(node)
+          return false unless %i[new define].include?(node.name)
+
+          receiver = node.receiver
+          case receiver
+          when Prism::ConstantReadNode then %i[Struct Data].include?(receiver.name)
+          when Prism::ConstantPathNode then receiver.parent.nil? && %i[Struct Data].include?(receiver.name)
+          else false
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "../../type"
+
+module Rigor
+  module Inference
+    module MethodDispatcher
+      # The last resolution tier for a `Dynamic` receiver: the handful of `BasicObject` / `Object` / `Kernel`
+      # methods whose return type does not depend on who the receiver is.
+      #
+      # `x.nil?` is `bool` whatever `x` is. Until this tier existed it was `Dynamic[Top]`, because every
+      # preceding tier needs a receiver it can name and the typer then fell through to the Dynamic-origin
+      # propagation. The same held for `is_a?`, `respond_to?`, `!` and the rest of the set below — a
+      # measurable share of the opaque expressions on a real codebase, closed by a fixed table rather than
+      # by knowing anything about the receiver
+      # (`docs/notes/20260831-self-check-type-coverage-audit.md` § Finding 2: +2.27 points of precision on this
+      # repository's own `lib`, with zero new diagnostics).
+      #
+      # **Where it sits.** After every real tier has declined, so a receiver Rigor can name always resolves
+      # through RBS first — `"".frozen?` is answered by `String`'s signature, not by this table. It only ever
+      # replaces a `Dynamic[Top]` that the engine was about to produce anyway.
+      #
+      # **What is deliberately NOT here**, each measured rather than argued (same note):
+      #
+      # - `class` — `Nominal[Class]` erases the singleton. `p.class.dynamic_returns` on a plugin instance is
+      #   real code in this repository; folding the receiver's class to the bare `Class` nominal produced 13
+      #   `call.undefined-method` false positives on `lib` alone. An ADR-5 violation bought for +0.14 points.
+      # - `==` / `!=` / `eql?` — the same failure at a much larger blast radius. `==` is the most commonly
+      #   overridden method in Ruby, and an overridden one is free to return anything.
+      # - `to_s` — receiver-independent in principle, but enabling it surfaces the RBS
+      #   `Array#[](Range) -> Array[T]?` optional-return noise on `x.to_s.split("::")[0...-1]` (7
+      #   `call.possible-nil-receiver` on `lib`). Not this tier's defect, but not this tier's to ship either:
+      #   it goes in once that noise has an answer.
+      # - `freeze` / `dup` / `clone` / `itself` / `tap` — receiver-independent in a different way (they
+      #   return the receiver), so on a `Dynamic` receiver they gain nothing.
+      module UniversalObjectDispatch
+        # `bool` as the engine spells it — `Constant[true] | Constant[false]`, the union
+        # `RbsTypeTranslator` folds RBS's `bool` to. Spelling it `Nominal[TrueClass] | Nominal[FalseClass]`
+        # instead type-checks but is not the same value: it fails to match a `-> bool` declaration and
+        # produced 17 spurious `def.return-type-mismatch` warnings when this tier was first prototyped.
+        BOOL = Type::Combinator.union(
+          Type::Combinator.constant_of(true),
+          Type::Combinator.constant_of(false)
+        ).freeze
+        private_constant :BOOL
+
+        # Selector => return type, for selectors defined on `BasicObject` / `Object` / `Kernel` whose result
+        # is a function of the language, not of the receiver's class:
+        #
+        # - the type predicates (`nil?`, `is_a?` and its aliases, `respond_to?`, `frozen?`) and the identity
+        #   comparison `equal?`, which `BasicObject` defines as object identity;
+        # - `!`, which Ruby's own semantics constrain to `true` / `false`;
+        # - `inspect`, whose `Object` contract is a `String` representation;
+        # - `hash` and `object_id`, both `Integer` by contract — `hash` because `Hash` requires it.
+        RETURN_TYPES = Ractor.make_shareable({
+                                               :nil? => BOOL,
+                                               :is_a? => BOOL,
+                                               :kind_of? => BOOL,
+                                               :instance_of? => BOOL,
+                                               :respond_to? => BOOL,
+                                               :equal? => BOOL,
+                                               :frozen? => BOOL,
+                                               :! => BOOL,
+                                               :inspect => Type::Combinator.nominal_of("String"),
+                                               :hash => Type::Combinator.nominal_of("Integer"),
+                                               :object_id => Type::Combinator.nominal_of("Integer")
+                                             })
+
+        module_function
+
+        # @param context [CallContext]
+        # @return [Rigor::Type, nil] the receiver-independent return type, or nil to decline.
+        def try_dispatch(context)
+          return nil unless context.receiver.is_a?(Type::Dynamic)
+
+          RETURN_TYPES[context.method_name]
+        end
+      end
+    end
+  end
+end