rigortype 0.3.8 → 0.4.0

data/lib/rigor/inference/define_method_block_self.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "../type"
+
+module Rigor
+  module Inference
+    # Issue #963 — the lexical `self` of a `define_method(:name) { ... }` block.
+    #
+    # A block has no `self` of its own, so every block body enters with `Scope#entering_opaque_block`
+    # and the enclosing class body's `self_type` (`Singleton[C]`) rides along unchanged. For
+    # `define_method` that carrier is the wrong side of the class: `Module#define_method` turns the
+    # block into an INSTANCE method of the receiver, and Ruby runs its body with `self` bound to the
+    # receiving instance. A bare `text` inside the block therefore reaches `C`'s member / attr reader,
+    # while `Singleton[C]` answers only `C`'s class methods.
+    #
+    # The consequence #963 records is #618's veto going the wrong way: `ExpressionTyper#self_type_answers?`
+    # asked the singleton side, found nothing, and let a same-named top-level `def text` bind ahead of the
+    # reader — typing `text.upcase` inside `class Line < Struct.new(:text); define_method(:shout) { text.upcase }`
+    # as the top-level def's `nil`. Narrowing the block body's `self_type` to `Nominal[C]` makes the
+    # existing veto ask the instance side, which is the side Ruby dispatches on; nothing in the veto
+    # itself changes.
+    #
+    # The match is deliberately narrow — the receiver must be the class body's own `self`, and that `self`
+    # must be a known `Singleton[C]` on the instance side of the class. `Foo.define_method(...)` on some other
+    # receiver keeps the unmodelled-self answer, and so does a `class << ...` BODY, where `self` is the
+    # singleton class and the call defines a CLASS method: an instance reader is not in that MRO, MRI reaches
+    # the top-level `def` there, and Rigor must answer the same. The body is the exclusion, not the lexical
+    # singleton frame — a `def` reached from that body has the class object as its `self`, so the call defines
+    # an instance method and the narrowing applies. `Scope#singleton_class_body?` is what draws that line, and
+    # carrying it on the scope is what lets both block-entry paths apply it identically.
+    # A `module_function` module is the one shape where both answers are right at once: MRI makes the block
+    # BOTH an instance method, where the reader resolves, and a module function on the module object, where it
+    # does not. Narrowing silences the module-function half, which is the false-positive-averse direction
+    # AGENTS.md § Implementation Guidelines asks for.
+    module DefineMethodBlockSelf
+      module_function
+
+      # @return the block body's narrowed `self_type`, or `nil` when the call shape does not match.
+      def narrow_self_type_for(scope:, call_node:)
+        return nil if scope&.singleton_class_body?
+        return nil unless define_method_on_lexical_self?(call_node)
+
+        self_type = scope&.self_type
+        return nil unless self_type.is_a?(Type::Singleton)
+
+        class_name = self_type.class_name
+        return nil if class_name.nil?
+
+        instance_type_for(class_name, scope.environment)
+      end
+
+      def define_method_on_lexical_self?(call_node)
+        return false unless call_node.is_a?(Prism::CallNode)
+        return false unless call_node.name == :define_method
+
+        call_node.receiver.nil? || call_node.receiver.is_a?(Prism::SelfNode)
+      end
+
+      def instance_type_for(class_name, environment)
+        environment&.nominal_for_name(class_name) || Type::Nominal.new(class_name)
+      end
+    end
+  end
+end

data/lib/rigor/inference/dynamic_origin.rb

@@ -60,7 +60,7 @@ module Rigor
 
       module_function
 
-      # @return [Symbol, nil] the tractability category for a cause, or nil when the cause is unknown /
+      # @return the tractability category for a cause, or nil when the cause is unknown /
       #   absent.
       def tractability(cause)
         TRACTABILITY[cause]

data/lib/rigor/inference/element_read_widening.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../type"
+require_relative "mutation_widening"
+
+module Rigor
+  module Inference
+    # Widens the element a mutator call reaches THROUGH a read, when the container is a local's
+    # literal-shape carrier. {MutationWidening} widens the bindings a receiver expression NAMES;
+    # this module covers the case where it names none because the receiver is an rvalue temp.
+    module ElementReadWidening
+      # Element reads that name ONE element of a container: the only receiver shapes whose mutation
+      # is attributable to a single position inside a local's literal-shape carrier. `first` / `last`
+      # with an argument return a sub-ARRAY, not an element, so they are excluded by arity below.
+      ELEMENT_READERS = %i[[] first last dig].to_set.freeze
+
+      module_function
+
+      # Widens an element read through an index / `first` / `last` / `dig` chain rooted at a LOCAL,
+      # when that read is the RECEIVER of a content mutator (issue #643).
+      #
+      # `c = [flag ? [1] : [2]]; c[0] << 5` mutates the rvalue temp `c[0]`, so
+      # {MutationWidening.widen_after_call} — which widens exactly the bindings the receiver expression NAMES —
+      # sees no variable and records nothing. `c` keeps `Tuple[[1] | [2]]`, and the later
+      # `c[0].last == 5` folds always-falsey on a value the program does hold. The nested plain
+      # literal (`b = [[[]]]; b[0][0] << 1`) reads `b[0][0].first` as `nil` for the same reason.
+      #
+      # The fix widens the element's pin ONE STEP INSIDE the container and writes the rebuilt
+      # container back to the local: `Tuple[[1] | [2]]` becomes `Tuple[Array[Integer]]`. The outer
+      # arity survives — mutating an element cannot change how many elements the container has —
+      # so `c.size == 1` keeps folding. A non-literal index widens every position instead, since
+      # which one was mutated is not decidable.
+      #
+      # Rooted at a local only: a mutation through a method call's result (`foo[0] << 5`) has no
+      # binding to write back to, and inventing one would be unsound.
+      def widen_element_read(call_node:, current_scope:, arg_types: MutationWidening::NO_ARG_TYPES)
+        return current_scope if MutationWidening.pure_self_returner?(call_node.name)
+
+        path = element_read_path(call_node.receiver)
+        return current_scope if path.nil?
+
+        read, steps = path
+        widened = widen_through_path(current_scope.local(read.name), steps, call_node.name, arg_types)
+        return current_scope if widened.nil?
+
+        current_scope.with_mutated_local(read.name, widened)
+      end
+
+      # True when `receiver` is an element read whose target element is a literal-shape carrier —
+      # the {#joinable_receiver?} counterpart for the element path, gating whether the caller types
+      # the mutator's arguments at all.
+      def joinable_element_read?(receiver, scope)
+        path = element_read_path(receiver)
+        return false if path.nil?
+
+        read, steps = path
+        !element_at_path(scope.local(read.name), steps).nil?
+      end
+
+      # `[<local read>, [step, …]]` for a chain of element reads rooted at a local variable, or
+      # `nil` when the expression is anything else. A step is an Integer position (negative counts
+      # from the end, as Ruby's own indexing does) or `:all` when the index is not a literal.
+      #
+      # Every mutation site's receiver is asked, and nearly every one is a plain variable read, so a
+      # receiver that is no call answers before the step list is allocated.
+      def element_read_path(node)
+        return nil unless node.is_a?(Prism::CallNode)
+
+        steps = []
+        cursor = node
+        while cursor.is_a?(Prism::CallNode)
+          step = element_read_step(cursor)
+          return nil if step.nil?
+
+          steps.unshift(*step)
+          cursor = cursor.receiver
+        end
+        return nil unless cursor.is_a?(Prism::LocalVariableReadNode) && !steps.empty?
+
+        [cursor, steps]
+      end
+
+      # The positions one element-read call selects, or `nil` when the call is not an element read.
+      # A block makes the call something other than a plain read (`arr.first { … }` is not one), and
+      # `[]` with anything but a single argument is a slice.
+      def element_read_step(call_node)
+        return nil unless ELEMENT_READERS.include?(call_node.name)
+        return nil if call_node.receiver.nil? || call_node.block
+
+        positional_steps(call_node.name, call_node.arguments&.arguments || [])
+      end
+
+      def positional_steps(name, args)
+        case name
+        when :[] then args.size == 1 ? [index_step(args.first)] : nil
+        when :first then args.empty? ? [0] : nil
+        when :last then args.empty? ? [-1] : nil
+        when :dig then args.empty? ? nil : args.map { |arg| index_step(arg) }
+        end
+      end
+
+      # `:all` stands for "some position, not statically known" — every position is widened, which
+      # is the only answer that cannot under-approximate.
+      def index_step(node)
+        node.is_a?(Prism::IntegerNode) ? node.value : :all
+      end
+
+      # The type at `steps` inside `type`, or `nil` when the path does not resolve to a widenable
+      # literal-shape carrier.
+      def element_at_path(type, steps)
+        return MutationWidening.shape_carrier?(type) ? type : nil if steps.empty?
+
+        case type
+        when Type::Tuple
+          tuple_positions(type, steps.first).lazy
+                                            .filter_map { |i| element_at_path(type.elements[i], steps.drop(1)) }
+                                            .first
+        when Type::Union
+          type.members.lazy.filter_map { |member| element_at_path(member, steps) }.first
+        end
+      end
+
+      # Rebuilds `type` with the element at `steps` widened against `method_name`, or `nil` when
+      # nothing along the path widened. A block, when given, replaces the straight-line widening of the
+      # element itself: it receives the element's type and answers the widened one, or `nil` to decline.
+      # {UnknownStoreWidening} passes one so a site on an element takes the same unknown-store widening a
+      # site on a variable does.
+      def widen_through_path(type, steps, method_name, arg_types, &element_widening)
+        if steps.empty?
+          return element_widening.call(type) if element_widening
+
+          return MutationWidening.widen_for_mutator(type, method_name, arg_types: arg_types)
+        end
+
+        case type
+        when Type::Tuple then widen_tuple_path(type, steps, method_name, arg_types, &element_widening)
+        when Type::Union then widen_union_path(type, steps, method_name, arg_types, &element_widening)
+        end
+      end
+
+      def widen_tuple_path(tuple, steps, method_name, arg_types, &)
+        elements = tuple.elements.dup
+        rest = steps.drop(1)
+        widened_any = false
+        tuple_positions(tuple, steps.first).each do |position|
+          inner = widen_through_path(elements[position], rest, method_name, arg_types, &)
+          next if inner.nil?
+
+          elements[position] = inner
+          widened_any = true
+        end
+        widened_any ? Type::Tuple.new(elements) : nil
+      end
+
+      def widen_union_path(union, steps, method_name, arg_types, &)
+        widened_any = false
+        members = union.members.map do |member|
+          widened = widen_through_path(member, steps, method_name, arg_types, &)
+          next member if widened.nil?
+
+          widened_any = true
+          widened
+        end
+        widened_any ? Type::Combinator.union(*members) : nil
+      end
+
+      # An out-of-range literal index selects nothing: the mutation cannot be attributed to any
+      # position of THIS tuple, so no widening is justified.
+      def tuple_positions(tuple, step)
+        size = tuple.elements.size
+        return (0...size).to_a if step == :all
+
+        position = step.negative? ? step + size : step
+        position.between?(0, size - 1) ? [position] : []
+      end
+    end
+  end
+end

data/lib/rigor/inference/error_info.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../reflection"
+require_relative "../source/node_children"
+require_relative "../type"
+require_relative "block_call_timing"
+
+module Rigor
+  module Inference
+    # Issue #1360 — `$!`, the exception being rescued, and `$@`, its backtrace. Ruby does not keep them in the method
+    # frame's special-variable slot, as it keeps `$~` and `$_`: a read of `$!` walks the running execution context's
+    # frames to the nearest rescue frame. So:
+    #
+    # - inside a `rescue` clause, and inside a rescue modifier's fallback, `$!` is the exception that clause rescued,
+    #   in every block the clause runs and every method it calls;
+    # - once the `begin` or the modifier exits, however it exits, `$!` is what it was before it started: `nil` at the
+    #   top of a method called from nowhere special, the outer exception after a nested `begin` in a rescue clause;
+    # - an `else` clause and the body read that earlier value too, and an `ensure` clause reads it when the body or a
+    #   rescue clause finished, but the exception in flight when one raised.
+    #
+    # A method body cannot know what its caller is rescuing, so it starts unbound; a thread's or fiber's root block
+    # runs in an execution context of its own, where `$!` is `nil` ({FreshFrameBlocks.entry}); and a closure's body
+    # runs whenever it is called, usually after the clause it is written in exited ({FreshFrameBlocks.closure_entry}).
+    module ErrorInfo
+      ERROR_INFO = :$!
+      BACKTRACE = :$@
+      NAMES = [ERROR_INFO, BACKTRACE].freeze
+      # The globals a rescue modifier's fallback reads differently from the modifier's entry ({.modifier_entry}).
+      MODIFIER_NAMES = [ERROR_INFO, BACKTRACE, :$?].freeze
+      EXCEPTION_ORDERINGS = Set[:equal, :subclass].freeze
+      DEFINERS = Set[:define_method, :define_singleton_method].freeze
+      # The class guards a clause may put on `$!` ({.guarded?}).
+      GUARDS = Set[:is_a?, :kind_of?, :instance_of?, :respond_to?].freeze
+      private_constant :ERROR_INFO, :BACKTRACE, :NAMES, :MODIFIER_NAMES, :EXCEPTION_ORDERINGS, :GUARDS, :DEFINERS
+
+      module_function
+
+      # The scope a `rescue` clause, or a rescue modifier's fallback, runs from: `$!` bound to the exception it rescued
+      # and `$@` to that exception's backtrace, with `$?` unbound. `exception_type` is what `rescue … => e` binds `e` to
+      # (`StatementEvaluator#rescue_exception_type`): the union of the named classes' instances, `StandardError` for a
+      # bare `rescue`. A member that is not a class RBS or the program places below `Exception` reads `Dynamic[top]`
+      # instead: a rescue list may name a module with its own `===` (`rescue NetworkErrors`), which matches exceptions
+      # that are not instances of it, and a class the analyzer cannot place may be such an object too. So does a class
+      # that it or a project ancestor gives its own singleton `===` (`class Matchy < StandardError; def self.===(o) =
+      # true`).
+      #
+      # `body` is the clause's statements or the fallback, and `reference` the name of the local a `rescue … => e`
+      # clause binds. When the body guards `$!`, or that local, which is the same object, by its class ({.guarded?}),
+      # the clause reads `$!` and `$@` unbound, as it did before issue #1360: `$!.key if e.is_a?(KeyError)` would report
+      # the bound `StandardError` against the guard (ADR-117, point 3), since narrowing `e` does not narrow `$!`. #1429
+      # made a class guard on `$!` itself narrow it; #1447 narrows this decline to the guards that still do not.
+      #
+      # `$@` calls the exception's `backtrace`, which is an `Array[String]` for a raised exception. It is left unbound
+      # in a program that defines a method named `backtrace` anywhere, which may return anything, and in a clause
+      # whose body calls `set_backtrace`, which may set it to nil.
+      #
+      # `$?` is unbound because the exception may have been raised while a subprocess waited: a backtick, `%x` or
+      # `system` sets `$?` to nil before it runs the child, so a `Timeout::Error`, an `Interrupt` or a `Thread#raise`
+      # there leaves it nil.
+      def rescue_entry(scope, exception_type, body = nil, reference = nil)
+        entered = scope.forget_error_info.forget_last_status
+        # Narrowed to the guards #1429 does not narrow in #1447.
+        return entered if guarded?(body, reference)
+
+        entered = entered.with_global(ERROR_INFO, rescued_type(exception_type, scope))
+        return entered if calls_set_backtrace?(body) || BlockCallTiming.project_defines_anywhere?(:backtrace, scope)
+
+        entered.with_global(BACKTRACE, backtrace_type)
+      end
+
+      # The scope a rescue modifier's fallback (`expr rescue fallback`) runs from, which rescues a `StandardError`.
+      def modifier_entry(scope, fallback = nil)
+        rescue_entry(scope, Type::Combinator.nominal_of("StandardError"), fallback)
+      end
+
+      # The class guards on `$!` that {.rescue_entry} declines on, anywhere in `node`: `$!.is_a?`, `kind_of?`,
+      # `instance_of?` or `respond_to?`, a `===` whose argument is `$!` (`KeyError === $!`), and `case $!`, and the
+      # same on a read of the local named `reference`.
+      def guarded?(node, reference = nil)
+        return false unless node.is_a?(Prism::Node)
+        return true if guard?(node, reference)
+
+        found = false
+        node.rigor_each_child { |child| found ||= guarded?(child, reference) }
+        found
+      end
+
+      def guard?(node, reference)
+        case node
+        when Prism::CallNode
+          (GUARDS.include?(node.name) && error_info_read?(node.receiver, reference)) ||
+            (node.name == :=== && error_info_read?(node.arguments&.arguments&.first, reference))
+        when Prism::CaseNode, Prism::CaseMatchNode then error_info_read?(node.predicate, reference)
+        else false
+        end
+      end
+
+      def error_info_read?(node, reference)
+        case node
+        when Prism::GlobalVariableReadNode then node.name == ERROR_INFO
+        when Prism::LocalVariableReadNode then !reference.nil? && node.name == reference
+        else false
+        end
+      end
+
+      # True when `node` calls `set_backtrace` anywhere, on any receiver: `$!.set_backtrace(nil)` makes `$@` nil.
+      def calls_set_backtrace?(node)
+        return false unless node.is_a?(Prism::Node)
+        return true if node.is_a?(Prism::CallNode) && node.name == :set_backtrace
+
+        found = false
+        node.rigor_each_child { |child| found ||= calls_set_backtrace?(child) }
+        found
+      end
+      private_class_method :guard?, :error_info_read?, :calls_set_backtrace?
+
+      # True when `node` reads `$!`, `$@` or `$?` anywhere in it: the gate on typing a rescue modifier's fallback
+      # under {.modifier_entry}, which most fallbacks (`rescue nil`) never need.
+      def read_in?(node)
+        return false unless node.is_a?(Prism::Node)
+        return MODIFIER_NAMES.include?(node.name) if node.is_a?(Prism::GlobalVariableReadNode)
+
+        found = false
+        node.rigor_each_child { |child| found ||= read_in?(child) }
+        found
+      end
+
+      # `scope` with `$!` and `$@` as `entry` binds them, and unbound where `entry` leaves them unbound: the scope past
+      # a `begin` or a rescue modifier that started from `entry`, whichever way it left.
+      def restore(scope, entry)
+        return scope if NAMES.all? { |name| scope.global(name).equal?(entry.global(name)) }
+
+        NAMES.reduce(scope.forget_error_info) do |acc, name|
+          bound = entry.global(name)
+          bound ? acc.with_global(name, bound) : acc
+        end
+      end
+
+      def rescued_type(exception_type, scope)
+        members = exception_type.is_a?(Type::Union) ? exception_type.members : [exception_type]
+        return exception_type if members.all? { |member| exception_instance?(member, scope) }
+
+        Type::Combinator.union(
+          *members.map { |member| exception_instance?(member, scope) ? member : Type::Combinator.untyped }
+        )
+      end
+
+      # True when `type` is an instance of a class below `Exception`: one RBS places there, or a project class whose
+      # superclass chain reaches one (`class MyError < StandardError`), which the RBS environment does not know.
+      def exception_instance?(type, scope)
+        return false unless type.is_a?(Type::Nominal)
+
+        class_name = type.class_name
+        return false if own_case_equality?(class_name, scope)
+        return true if exception_class?(class_name, scope)
+        return false unless scope.known_user_class?(class_name)
+
+        scope.external_ancestor_name_candidates(class_name, mixins: false).any? do |candidates|
+          known = candidates.find { |candidate| Reflection.rbs_class_known?(candidate, scope: scope) }
+          !known.nil? && exception_class?(known, scope)
+        end
+      rescue StandardError
+        false
+      end
+
+      # True when the program gives `class_name`, or a project ancestor of it, a singleton `===`, which `rescue` calls
+      # to match and which may accept an exception that is not an instance of it: a `def self.===` or `class << self`
+      # `def ===`, or, anywhere in the file being read, a `define_method` or `define_singleton_method` naming `===`
+      # ({.defines_case_equality?}), which the discovery tables do not place on a class, so it counts for every class.
+      def own_case_equality?(class_name, scope)
+        scope.discovery.defines_case_equality ||
+          !scope.singleton_def_through_ancestors(class_name, :===).first.nil?
+      end
+
+      # True when `node` is a `define_method` or `define_singleton_method` call whose literal name is `===`.
+      # `Inference::ScopeIndexer` records whether a file holds one ({Scope::DiscoveryIndex#defines_case_equality}).
+      def defines_case_equality?(node)
+        return false unless node.is_a?(Prism::CallNode) && DEFINERS.include?(node.name)
+
+        name = node.arguments&.arguments&.first
+        (name.is_a?(Prism::SymbolNode) || name.is_a?(Prism::StringNode)) && name.unescaped == "==="
+      end
+
+      def exception_class?(class_name, scope)
+        EXCEPTION_ORDERINGS.include?(scope.environment.class_ordering(class_name, "Exception"))
+      end
+
+      def backtrace_type
+        Type::Combinator.nominal_of("Array", type_args: [Type::Combinator.nominal_of("String")])
+      end
+      private_class_method :rescued_type, :exception_instance?, :own_case_equality?, :exception_class?, :backtrace_type
+    end
+  end
+end