rigortype 0.3.8 → 0.4.0

data/lib/rigor/inference/mutation_widening.rb

@@ -5,7 +5,12 @@ require "prism"
 require_relative "../type"
 require_relative "../source/node_children"
 require_relative "content_join"
+require_relative "hash_lookup_mutation"
+require_relative "mutation_rejoin"
 require_relative "receiver_alias"
+require_relative "refinement_mutation"
+require_relative "rewrite_mutation"
+require_relative "string_mutation"
 
 module Rigor
   module Inference
@@ -49,6 +54,8 @@ module Rigor
     #
     # - `arr.<mutator>(...)` where `arr` is a local variable.
     # - `@arr.<mutator>(...)` where `@arr` is an instance variable.
+    # - `@@arr.<mutator>(...)` / `$arr.<mutator>(...)` where the receiver is a class variable or global, and
+    #   `it.<mutator>(...)` on the Ruby 3.4 `it` parameter ({ReceiverAlias.mutated_reads}).
     # - a receiver that *selects* among such variables rather than naming one —
     #   `(kind == :required ? required : optional)[key] = info`, an `if`/`else`, `||` / `&&`. Every
     #   variable the expression can evaluate to is a possible mutation target, so every one widens
@@ -86,19 +93,21 @@ module Rigor
       ].to_set.freeze
 
       # Hash mutators that invalidate a `HashShape` carrier. Same principle as `ARRAY_MUTATORS`:
-      # only the receiver-mutating methods are listed.
+      # only the receiver-mutating methods are listed. A name both classes define is listed in
+      # both tables — being in `ARRAY_MUTATORS` does not put it here, and `shift`'s absence let
+      # `k = { a: 1 }; k.shift` keep the literal shape of a hash that is empty at runtime.
       HASH_MUTATORS = %i[
         []= store
-        delete delete_if reject! select! filter! keep_if
+        shift delete delete_if reject! select! filter! keep_if
         clear compact! merge! update transform_keys! transform_values!
         replace
       ].to_set.freeze
 
       # Every method name {#widen_for_mutator} responds to — the one set a body scan asks "could an
       # in-place call on this name change its binding?" against (issue #587: the block-return
-      # threading gate). Derived from the two tables above rather than spelled out, so the scan and
-      # the widening it predicts cannot drift apart.
-      SHAPE_MUTATORS = (ARRAY_MUTATORS | HASH_MUTATORS).freeze
+      # threading gate). Derived from the tables rather than spelled out, so the scan and the
+      # widening it predicts cannot drift apart.
+      SHAPE_MUTATORS = (ARRAY_MUTATORS | HASH_MUTATORS | HashLookupMutation::MUTATORS | StringMutation::MUTATORS).freeze
 
       # Methods that return the receiver (or a shallow copy) and cannot mutate it. They must not
       # trigger widening or any other receiver-fact invalidation. The list is intentionally
@@ -110,9 +119,7 @@ module Rigor
 
       # True when `method_name` is a pure self-returner that must
       # not invalidate the receiver's facts.
-      def pure_self_returner?(method_name)
-        PURE_SELF_RETURNERS.include?(method_name)
-      end
+      def pure_self_returner?(method_name) = PURE_SELF_RETURNERS.include?(method_name)
 
       # Returns a scope with the call's receiver widened, for every variable the receiver expression
       # can evaluate to ({ReceiverAlias.candidates}) whose current binding is a literal-shape carrier
@@ -126,10 +133,6 @@ module Rigor
       # pre-join behaviour exactly.
       NO_ARG_TYPES = [].freeze
 
-      # @param call_node     [Prism::CallNode]
-      # @param current_scope [Rigor::Scope]
-      # @param arg_types     [Array<Rigor::Type::Base>]
-      # @return              [Rigor::Scope]
       def widen_after_call(call_node:, current_scope:, arg_types: NO_ARG_TYPES)
         return current_scope if pure_self_returner?(call_node.name)
 
@@ -138,26 +141,43 @@ module Rigor
 
       # True when `receiver` names at least one variable whose CURRENT binding is a literal-shape
       # carrier — the only pre-state {#widen_for_mutator} joins into. Callers use it to skip typing a
-      # mutator's arguments when nothing will consume them: `buf << x` on a String and `arr << x` on an
-      # already-nominal Array are the common cases, and `Scope#type_of` memoizes nothing.
+      # mutator's arguments when nothing will consume them, and `Scope#type_of` memoizes nothing.
       def joinable_receiver?(receiver, scope)
         return false if receiver.nil?
 
-        ReceiverAlias.candidates(receiver).any? do |read|
-          current =
-            case read
-            when Prism::LocalVariableReadNode then scope.local(read.name)
-            when Prism::InstanceVariableReadNode then scope.ivar(read.name)
-            end
-          current.is_a?(Type::Tuple) || current.is_a?(Type::HashShape)
+        ReceiverAlias.mutated_reads(receiver).any? do |read|
+          getter, = ALIAS_ACCESSORS[read.class]
+          getter && shape_carrier?(scope.public_send(getter, ReceiverAlias.read_name(read)))
         end
       end
 
-      # Widens every variable `receiver` can evaluate to, against `method_name`'s mutator table.
+      # A union carrying a shape member is joinable too (issue #645): {#widen_union} widens that
+      # member through the same join, so the arguments the caller would skip are the evidence it
+      # needs.
+      # A `Constant[String]` counts too since issue #617 residue (4): the gate exists to skip typing arguments
+      # nothing will consume, and this carrier IS consumed now — `buf << x` on a `+"ab"` rewrites the binding.
+      # An empty-witness `Difference` counts too (issue #936): the `non-empty-array[T]` arm joins the
+      # mutator's added element now, so its arguments are evidence this seam consumes rather than
+      # arguments nothing will read.
+      def shape_carrier?(type)
+        case type
+        when Type::Tuple, Type::HashShape then true
+        when Type::Constant then StringMutation.constant?(type)
+        # A re-openable nominal counts since issue #580: skipping it made the one-way door
+        # self-fulfilling, since the arm never saw the arg types it grows from.
+        when Type::Nominal then MutationRejoin.regrowable_carrier?(type)
+        when Type::Difference then type.removes_empty_witness?
+        when Type::Union then type.members.any? { |m| shape_carrier?(m) }
+        else false
+        end
+      end
+
+      # Widens every variable `receiver` can evaluate to ({ReceiverAlias.mutated_reads}), against `method_name`'s
+      # mutator table.
       def widen_receiver_aliases(receiver, method_name, current_scope, arg_types: NO_ARG_TYPES)
         return current_scope if receiver.nil?
 
-        ReceiverAlias.candidates(receiver).reduce(current_scope) do |acc, read|
+        ReceiverAlias.mutated_reads(receiver).reduce(current_scope) do |acc, read|
           widen_alias_read(method_name, read, acc, arg_types: arg_types)
         end
       end
@@ -212,9 +232,10 @@ module Rigor
         return scope if receiver.nil?
 
         ReceiverAlias.candidates(receiver).reduce(scope) do |acc, read|
-          # A block-local read (`depth == 0`) is not a capture of the outer scope, so widening its
-          # name against the OUTER scope would hit an unrelated same-named binding.
-          next acc if read.is_a?(Prism::LocalVariableReadNode) && read.depth.zero?
+          # A block-local read ({ReceiverAlias.block_local?}: a `depth == 0` local, or `it`) is not a
+          # capture of the outer scope, so widening its name against the OUTER scope would hit an
+          # unrelated same-named binding.
+          next acc if ReceiverAlias.block_local?(read)
 
           # `values: :keep` — this is the block-capture path, and the slice-C content join that runs
           # after it re-adds the appended values' types onto the widened seed, so the seed's own value
@@ -224,30 +245,30 @@ module Rigor
         end
       end
 
-      def widen_alias_read(method_name, read, scope, values: :widen, arg_types: NO_ARG_TYPES)
-        case read
-        when Prism::LocalVariableReadNode
-          widen_local(method_name, read.name, scope, values: values, arg_types: arg_types)
-        when Prism::InstanceVariableReadNode
-          widen_ivar(method_name, read.name, scope, values: values, arg_types: arg_types)
-        else scope
-        end
-      end
-
-      def widen_local(method_name, var_name, current_scope, values: :widen, arg_types: NO_ARG_TYPES)
-        current = current_scope.local(var_name)
-        widened = widen_for_mutator(current, method_name, values: values, arg_types: arg_types)
-        return current_scope if widened.nil?
+      # The arms per kind of binding differ only in which pair of `Scope` accessors they use, so they are read out
+      # of one table rather than written once per kind: a carrier the widening responds to must not be widened on
+      # one kind of binding and left on another. `$g << x; $g == "k"` folded always-truthy on a `$g` Ruby holds
+      # as `"kx"` while the table had only the local and ivar rows. A local rebinds through `with_mutated_local`: the
+      # mutated binding names the same object, so it keeps the marks a write drops (issue #1287).
+      ALIAS_ACCESSORS = Ractor.make_shareable({
+                                                Prism::LocalVariableReadNode => %i[local with_mutated_local],
+                                                Prism::ItLocalVariableReadNode => %i[local with_mutated_local],
+                                                Prism::InstanceVariableReadNode => %i[ivar with_ivar],
+                                                Prism::ClassVariableReadNode => %i[cvar with_cvar],
+                                                Prism::GlobalVariableReadNode => %i[global with_global]
+                                              })
+      private_constant :ALIAS_ACCESSORS
 
-        current_scope.with_local(var_name, widened)
-      end
+      def widen_alias_read(method_name, read, scope, values: :widen, arg_types: NO_ARG_TYPES)
+        getter, builder = ALIAS_ACCESSORS[read.class]
+        return scope if getter.nil?
 
-      def widen_ivar(method_name, var_name, current_scope, values: :widen, arg_types: NO_ARG_TYPES)
-        current = current_scope.ivar(var_name)
+        name = ReceiverAlias.read_name(read)
+        current = scope.public_send(getter, name)
         widened = widen_for_mutator(current, method_name, values: values, arg_types: arg_types)
-        return current_scope if widened.nil?
+        return scope if widened.nil?
 
-        current_scope.with_ivar(var_name, widened)
+        MutationRejoin.rebind(scope, builder, name, widened, pre_state: current, kind: getter)
       end
 
       # Mutators that can land a NEW value in an EXISTING slot, falsifying that slot's value pinning
@@ -259,29 +280,74 @@ module Rigor
       private_constant :VALUE_REWRITING_MUTATORS
 
       # Returns the widened type for a binding whose receiver is about to be mutated by
-      # `method_name`, or `nil` when no widening applies (binding is not a literal-shape
-      # carrier, OR the method is not a mutator for that shape, OR the binding is already a
-      # nominal — no precision to lose).
+      # `method_name`, or `nil` when no widening applies (binding is not a carrier the mutation
+      # stands for, OR the method is not a mutator for that shape, OR the carrier is a PRECISE
+      # nominal, whose element set is a claim this seam may not grow — see {MutationRejoin.regrowable_carrier?}).
       def widen_for_mutator(type, method_name, values: :widen, arg_types: NO_ARG_TYPES)
         values = :keep unless VALUE_REWRITING_MUTATORS.include?(method_name)
+        values = RewriteMutation.values_mode(type, method_name, values)
 
         return nil if type.nil?
 
         case type
+        when Type::Nominal then MutationRejoin.widen_nominal(type, method_name, values:, arg_types:)
         when Type::Tuple
           return nil unless ARRAY_MUTATORS.include?(method_name)
 
           join_added_elements(widen_tuple(type, values: values), method_name, arg_types, type.elements)
         when Type::HashShape
-          return nil unless HASH_MUTATORS.include?(method_name)
+          return HashLookupMutation.widen_shape(type, method_name) unless HASH_MUTATORS.include?(method_name)
 
           join_added_pairs(widen_hash_shape(type, values: values), method_name, arg_types,
                            ContentJoin.hash_shape_key_values(type))
+        when Type::Constant then StringMutation.widen_constant(type, method_name)
         when Type::Difference
-          widen_difference(type, method_name)
+          widen_difference(type, method_name, arg_types: arg_types)
+        when Type::Union
+          widen_union(type, method_name, values: values, arg_types: arg_types)
         end
       end
 
+      # A `Union` seed is widened MEMBERWISE (issue #645). Declining it outright left a straight-line
+      # mutation on a union binding recording nothing at all — `out = flag ? 5 : [2]; out << 2` kept
+      # the `[2]` Tuple's arity after the mutation falsified it, so a later `out.size == 1` folds on a
+      # value the program never holds.
+      #
+      # Which members the mutation stands for is {ContentJoin}'s residue partition read from this
+      # side, so the straight-line seam and the block seam (#631) agree about a union: a member the
+      # mutator's class carries widens through the ordinary non-union path above, every other member
+      # survives whole. The two tables are consulted per member rather than once for the union, which
+      # is what a name in BOTH of them (`clear`, `delete`, `replace`) needs on a mixed
+      # `Array | Hash` seed.
+      #
+      # `nil` when no member widened — a union with no carrier member, or one whose carriers are
+      # already nominal, is untouched exactly as the scalar path leaves them.
+      def widen_union(union, method_name, values: :widen, arg_types: NO_ARG_TYPES)
+        widened_any = false
+        members = union.members.map do |member|
+          next member unless mutation_carrier?(member, method_name)
+
+          widened = widen_for_mutator(member, method_name, values: values, arg_types: arg_types)
+          next member if widened.nil?
+
+          widened_any = true
+          widened
+        end
+        return nil unless widened_any
+
+        Type::Combinator.union(*members)
+      end
+
+      # True when the mutator's own class stands for `member` — the absorbed side of
+      # {ContentJoin.array_residue} / {ContentJoin.hash_residue}, whichever table names the call. A
+      # {HashLookupMutation} name stands for a Hash member as a Hash mutator does.
+      def mutation_carrier?(member, method_name)
+        (ARRAY_MUTATORS.include?(method_name) && ContentJoin.array_residue(member).empty?) ||
+          ((HASH_MUTATORS.include?(method_name) || HashLookupMutation::MUTATORS.include?(method_name)) &&
+            ContentJoin.hash_residue(member).empty?) ||
+          (StringMutation::MUTATORS.include?(method_name) && StringMutation.constant?(member))
+      end
+
       # Joins the element evidence the mutator's own ARGUMENTS introduce into the already-widened
       # Array carrier (issue #560). Without it the widening keeps only the SEED's elements, which
       # under-covers precisely the value the mutation added: `u = [1, 2]; u.push(6)` left
@@ -305,7 +371,11 @@ module Rigor
       # **The join records what it saw; it never CLOSES the parameter.** That is
       # {#gradual_floor}'s job, and the reason is the seam this method sits on rather than anything
       # about Array or Hash.
+      #
+      # A mutator whose arguments do not describe what it stores ({RewriteMutation}) takes that module's gradual
+      # arm first, on every path that reaches this join: the literal arms, the refinement arm, and the re-join.
       def join_added_elements(widened, method_name, arg_types, seed_elements)
+        widened = RewriteMutation.arm(widened, method_name)
         return widened unless ContentJoin::ARRAY_CONTENT_ADDERS.include?(method_name)
 
         added = value_pin_widened(ContentJoin.array_added_elements(method_name, arg_types))
@@ -340,7 +410,10 @@ module Rigor
       # BLOCK path (ADR-56 slice C) on the other side: `content_writeback_block_captures` scans the
       # whole body and joins every mutator call in it before writing back, so its evidence IS
       # complete for that body and its precise join stays justified — `acc = []; xs.each { |x|
-      # acc.push(x) }` keeps reading `Array[Integer]`.
+      # acc.push(x) }` keeps reading `Array[Integer]`. Seeing every store is only half of that
+      # claim: a store computed from the collection's own contents (`h[k] = h[k] + 1`) is
+      # complete evidence only once it holds past the first iteration, which is why that seam
+      # iterates such a store to a fixpoint instead of typing it once (ADR-56 WD2.13).
       #
       # `Array[Integer | Dynamic[top]]` still does everything issue #560 needs: a union carrying
       # `Dynamic` cannot constant-fold, so every stale always-falsey the join was written to remove
@@ -351,12 +424,17 @@ module Rigor
 
       # The Hash-side twin of {#join_added_elements}: `h[k] = v` / `h.store(k, v)` join the stored
       # key and value into the widened `Hash[K, V]` carrier, each admitted against its OWN side's
-      # seed evidence (a foreign key does not make the value gradual, or the reverse).
+      # seed evidence (a foreign key does not make the value gradual, or the reverse). {RewriteMutation}'s arm lands
+      # first, as it does in {#join_added_elements}.
       def join_added_pairs(widened, method_name, arg_types, seed_pairs)
+        widened = RewriteMutation.arm(widened, method_name)
         return widened unless ContentJoin::HASH_CONTENT_ADDERS.include?(method_name)
         return widened if arg_types.size < 2
 
-        added = value_pin_widened([arg_types.first, arg_types.last])
+        # A `nil` index marks a splat for the Array splice classifier; the pair seam reads
+        # `arg_types.first` as the KEY, where the splat's expansion is an unknown key rather
+        # than absent arity — it degrades to untyped, not `nil` (issue #1140).
+        added = value_pin_widened([arg_types.first || Type::Combinator.untyped, arg_types.last])
         return widened unless added.size == 2
 
         seed_keys, seed_values = seed_pairs
@@ -433,25 +511,19 @@ module Rigor
         end
       end
 
-      # `non-empty-array[T]` / `non-empty-hash[K, V]` → the bare base nominal. These refinement
-      # carriers are what `empty?` / `any?` narrowing writes (ADR-47 §4-4), and they are just as
-      # invalidated by an in-place mutator as a `Tuple` is: `arr.clear` makes `arr` empty, so a
-      # surviving `Difference[Array[T], Tuple[]]` would project `arr.size` to `positive-int` and
-      # fold `arr.size == 0` to `Constant[false]` — a false `flow.always-falsey-condition` on
-      # correct code.
-      #
-      # Only the EMPTY-witness differences over Array / Hash are widened, and only for that
-      # base's mutator table. The other catalogued refinements are unreachable from these tables
-      # by construction: `non-empty-string` and `non-zero-int` bind String / Integer receivers,
-      # whose mutators (`String#<<` and friends) appear in neither `ARRAY_MUTATORS` nor
-      # `HASH_MUTATORS` — and none of them can empty a non-empty string anyway.
-      def widen_difference(difference, method_name)
-        return nil unless difference.removes_empty_witness?
-
-        base = difference.base
-        case base.class_name
-        when "Array" then ARRAY_MUTATORS.include?(method_name) ? base : nil
-        when "Hash" then HASH_MUTATORS.include?(method_name) ? base : nil
+      # The empty-witness refinement arm. {RefinementMutation} owns the witness half — whether
+      # `xs` is still provably non-empty after `method_name` — and takes the content half from
+      # here, so a refinement joins the mutator's added content on exactly the terms the `Tuple` /
+      # `HashShape` arms above do (issue #936, ADR-56 WD2.9's deferred branch).
+      def widen_difference(difference, method_name, arg_types: NO_ARG_TYPES)
+        RefinementMutation.widen(difference, method_name, arg_types) do |base|
+          if base.class_name == "Array"
+            ARRAY_MUTATORS.include?(method_name) &&
+              join_added_elements(base, method_name, arg_types, ContentJoin.collection_element_types(base))
+          else
+            HASH_MUTATORS.include?(method_name) &&
+              join_added_pairs(base, method_name, arg_types, ContentJoin.hash_shape_key_values(base))
+          end
         end
       end
 
@@ -473,16 +545,17 @@ module Rigor
         Type::Combinator.nominal_of("Array", type_args: [element_type])
       end
 
-      # `HashShape` (closed or open) → `Nominal[Hash, [Kunion, Vunion]]`. Empty / extra-keys-only
-      # shapes degrade to a fully-untyped Hash. Values widen their pinning the same way
-      # {#widen_tuple}'s elements do (issue #560): `opts = {headers: false}` then
-      # `opts[:encoding] = v` must not keep `false` as the whole value bound — redmine's
-      # `import.rb:274` read the stored key back through it and drew a false always-falsey.
+      # Closed `HashShape` → `Nominal[Hash, [Kunion, Vunion]]`. An empty or an open shape degrades to
+      # a fully-untyped Hash: an open shape's unseen keys may hold any value, and one {HashLookupMutation}
+      # opened reads its DEFAULT for a missing key, so a bound built from the known values alone would
+      # pin that read to one of them (`{ a: 1 }` under `default = 0` then `delete(:a)` read `h[:b]` as
+      # `1`). Values widen their pinning the same way {#widen_tuple}'s elements do (issue #560):
+      # `opts = {headers: false}` then `opts[:encoding] = v` must not keep `false` as the whole value
+      # bound — redmine's `import.rb:274` read the stored key back through it and drew a false
+      # always-falsey.
       def widen_hash_shape(shape, values: :widen)
-        if shape.pairs.empty?
-          return Type::Combinator.nominal_of("Hash",
-                                             type_args: [Type::Combinator.untyped,
-                                                         Type::Combinator.untyped])
+        if shape.pairs.empty? || shape.open?
+          return Type::Combinator.nominal_of("Hash", type_args: [Type::Combinator.untyped, Type::Combinator.untyped])
         end
 
         key_type = key_union_for(shape.pairs.keys)
@@ -497,9 +570,7 @@ module Rigor
       # `key_union_for` is delegated rather than duplicated: {#widen_hash_shape} and
       # `ContentJoin.hash_shape_key_values` must map a literal key set the SAME way, or a widened
       # carrier and the join that reads it back disagree about the key parameter.
-      def key_union_for(keys)
-        ContentJoin.key_union_for(keys)
-      end
+      def key_union_for(keys) = ContentJoin.key_union_for(keys)
     end
   end
 end