rigortype 0.4.6 → 0.4.8

data/lib/rigor/inference/mutation_widening.rb

@@ -10,7 +10,10 @@ require_relative "mutation_rejoin"
 require_relative "deep_erasure"
 require_relative "receiver_alias"
 require_relative "refinement_mutation"
+# `RemoverNarrowing` is loaded with the engine (`scope.rb`), not here: the engine-free value layer requires this file
+# and must not pull in the remover narrowing and its holder scan (`spec/rigor/cli/effects_cache_probe_spec.rb`).
 require_relative "rewrite_mutation"
+require_relative "set_mutation"
 require_relative "string_mutation"
 
 module Rigor
@@ -19,8 +22,7 @@ module Rigor
     # AND whose method is a known in-place mutator.
     #
     # Closes the **G1 / G2** flow-folding gaps documented at
-    # `docs/notes/20260521-mastodon-cluster4-flow-folding-triage.md` and queued in
-    # [`docs/CURRENT_WORK.md`](../../../docs/CURRENT_WORK.md) § "Flow-folding". The user-visible
+    # `docs/notes/20260521-mastodon-cluster4-flow-folding-triage.md`. The user-visible
     # symptom they shared was a spurious `flow.always-truthy-condition` on a `arr.size == N` /
     # `arr.empty?` / `@arr.empty?` check that follows a loop body or sibling method that mutates
     # `arr` / `@arr` in place.
@@ -76,6 +78,7 @@ module Rigor
     #   ARE also handled** (ivars live in the method-body scope, not the block-local scope).
     #
     # The remaining three items above are demand-gated; see ADR-56.
+    # rubocop:disable-next Metrics/ModuleLength
     module MutationWidening
       # Array mutators that change either the size or the element set of a literal-shape carrier
       # (Tuple). Receiver-mutating methods only — non-mutating siblings (`map` vs `map!`,
@@ -107,7 +110,8 @@ module Rigor
       # 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 tables rather than spelled out, so the scan and the
-      # widening it predicts cannot drift apart.
+      # widening it predicts cannot drift apart. The Set-only names ({SetMutation::MUTATORS}) stay out: the scans read
+      # a name without its receiver, and `merge` on a Hash returns a new Hash (issue #2294).
       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
@@ -134,10 +138,61 @@ module Rigor
       # pre-join behaviour exactly.
       NO_ARG_TYPES = [].freeze
 
-      def widen_after_call(call_node:, current_scope:, arg_types: NO_ARG_TYPES)
+      # `rewritten_element` is the element a typed element rewriter stores ({RewriteMutation.typed}), or `nil`.
+      def widen_after_call(call_node:, current_scope:, arg_types: NO_ARG_TYPES, rewritten_element: nil)
         return current_scope if pure_self_returner?(call_node.name)
 
-        widen_receiver_aliases(call_node.receiver, call_node.name, current_scope, arg_types: arg_types)
+        if RemoverNarrowing.candidate?(call_node)
+          narrowed = narrow_remover_receiver(call_node, current_scope, arg_types)
+          return narrowed if narrowed
+        end
+
+        widen_receiver_aliases(call_node.receiver, call_node.name, current_scope, arg_types:, rewritten_element:,
+                                                                                  removes_nil: removes_nil?(call_node))
+      end
+
+      # Issue #2608 — a remover that narrows its receiver by what it removes ({RemoverNarrowing}): the receiver's
+      # binding widens as any mutator's does, then loses what the call provably took out. This answers before the
+      # #2555 remover floor, so a synthesised carrier a store grew keeps its precise reading (`parts << maybe_nil;
+      # parts.compact!` reads `Array[String]`). `nil` when the call narrows nothing; the caller then takes the
+      # ordinary path, the floor included.
+      def narrow_remover_receiver(call_node, scope, arg_types)
+        read = call_node.receiver
+        getter, builder = ALIAS_ACCESSORS[read.class]
+        name = ReceiverAlias.read_name(read)
+        current = scope.public_send(getter, name)
+        return nil if current.nil? || RemoverHolderScan.unsafe_receiver?(scope, name)
+
+        narrowed = RemoverNarrowing.narrow_shape(current, call_node)
+        if narrowed.nil?
+          synthesised = synthesised_binding?(scope, getter, name)
+          base = widen_for_mutator(current, call_node.name, arg_types:, synthesised:)
+          narrowed = RemoverNarrowing.narrow(base || current, call_node, scope)
+        end
+        return nil if narrowed.nil?
+        return scope if narrowed == current
+
+        MutationRejoin.rebind(scope, builder, name, narrowed, pre_state: current, kind: getter)
+      end
+
+      # Issue #2555 — the removers that may take a `nil` out, which is every one but a `delete` / `delete?` given a
+      # non-nil literal: false positives outrank, so a positional remover (`pop`, `shift`, `slice!`), `subtract`
+      # (whose argument may hold `nil`) and a `delete` of an unknown value count. `Hash#delete` removes by key, so
+      # whatever value the key held may go ({.floor_grown_carrier} reads the receiver for it).
+      NIL_REMOVERS = %i[compact! reject! select! filter! delete_if keep_if clear pop shift slice!
+                        subtract].to_set.freeze
+      NON_NIL_LITERALS = [
+        Prism::IntegerNode, Prism::FloatNode, Prism::RationalNode, Prism::ImaginaryNode, Prism::StringNode,
+        Prism::SymbolNode, Prism::TrueNode, Prism::FalseNode
+      ].freeze
+      private_constant :NON_NIL_LITERALS
+
+      def removes_nil?(call_node)
+        return true if NIL_REMOVERS.include?(call_node.name)
+        return false unless %i[delete delete?].include?(call_node.name)
+
+        argument = call_node.arguments&.arguments&.first
+        NON_NIL_LITERALS.none? { |klass| argument.is_a?(klass) }
       end
 
       # True when `receiver` names at least one variable whose CURRENT binding is a literal-shape
@@ -148,10 +203,19 @@ module Rigor
 
         ReceiverAlias.mutated_reads(receiver).any? do |read|
           getter, = ALIAS_ACCESSORS[read.class]
-          getter && shape_carrier?(scope.public_send(getter, ReceiverAlias.read_name(read)))
+          next false if getter.nil?
+
+          name = ReceiverAlias.read_name(read)
+          shape_carrier?(scope.public_send(getter, name), synthesised: synthesised_binding?(scope, getter, name))
         end
       end
 
+      # Issue #2555 L3 — whether the binding `getter` / `name` reads carries the `:synthesised` construction fact
+      # ({Scope#construction_fact?}). Only a local can: an instance, class or global variable never carries one.
+      def synthesised_binding?(scope, getter, name)
+        getter == :local && scope.construction_fact?(name)
+      end
+
       # 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.
@@ -160,26 +224,34 @@ module Rigor
       # 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)
+      # A precise `Hash` counts too when its binding carries the `:synthesised` construction fact (issue #2555): the
+      # re-join grows it from these arguments.
+      # An intersection counts when a member does: `non-empty-lowercase-string`'s witness half reads `tr!`'s
+      # replacement ({#widen_string_intersection}).
+      def shape_carrier?(type, synthesised: false)
         case type
         when Type::Tuple, Type::HashShape then true
-        when Type::Constant then StringMutation.constant?(type)
+        when Type::Constant then StringMutation.constant?(type) || SetMutation.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)
+        # A precise `Array[E]` / `Set[E]` counts since issue #2361, which re-grows it from these arguments.
+        when Type::Nominal
+          MutationRejoin.regrowable_carrier?(type) || MutationRejoin.precise_array?(type) ||
+            SetMutation.regrowable?(type) || (synthesised && MutationRejoin.synthesised_carrier?(type))
         when Type::Difference then type.removes_empty_witness?
-        when Type::Union then type.members.any? { |m| shape_carrier?(m) }
+        when Type::Union, Type::Intersection then type.members.any? { |m| shape_carrier?(m, synthesised:) }
         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)
+      def widen_receiver_aliases(receiver, method_name, current_scope, arg_types: NO_ARG_TYPES, rewritten_element: nil,
+                                 removes_nil: false)
         return current_scope if receiver.nil?
 
         ReceiverAlias.mutated_reads(receiver).reduce(current_scope) do |acc, read|
-          widen_alias_read(method_name, read, acc, arg_types: arg_types)
+          widen_alias_read(method_name, read, acc, arg_types:, rewritten_element:, removes_nil:)
         end
       end
 
@@ -196,9 +268,8 @@ module Rigor
       # always safe — it can only LOSE precision — so blindly propagating is sound regardless of
       # whether the block actually runs.
       #
-      # Recurses into nested expression nodes so chained / nested forms (`arr << f(x); arr <<
-      # g(y)`, `arr.push(x) if cond`) are all caught. Does NOT recurse into nested
-      # `Prism::BlockNode`s — each block is processed by its own `eval_call`.
+      # Recurses into every nested node, blocks included, so chained / nested forms (`arr << f(x); arr <<
+      # g(y)`, `arr.push(x) if cond`) are all caught.
       def widen_after_block(call_node:, outer_scope:)
         block = call_node.block
         return DeepErasure.widen_symbol_proc(call_node, outer_scope) if DeepErasure.symbol_proc_mutation?(block)
@@ -235,6 +306,13 @@ module Rigor
         receiver = call_node.receiver
         return scope if receiver.nil?
 
+        # Issue #2335 — a block parameter, an element read or any other receiver that may be an outer local's object.
+        if AliasMutationFloor.candidate?(call_node)
+          scope = AliasMutationFloor.floor_after_call(call_node, scope) { captured_element_root(receiver) }
+        end
+        widened = widen_outer_element_read(call_node, scope)
+        return widened if widened
+
         ReceiverAlias.candidates(receiver).reduce(scope) do |acc, read|
           # 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
@@ -245,10 +323,35 @@ module Rigor
           # after it re-adds the appended values' types onto the widened seed, so the seed's own value
           # pinning is still justified (`out = [0]; arr.each { out << x }` never rewrites slot 0). The
           # straight-line paths have no such join, which is why their default is `:widen` (issue #560).
-          widen_alias_read(call_node.name, read, acc, values: :keep)
+          widen_alias_read(call_node.name, read, acc, values: :keep, unread_arguments: !call_node.arguments.nil?)
         end
       end
 
+      # The outer root of an element read in a block body, whose element {#widen_outer_element_read} widens. (A captured
+      # local the receiver names takes the capture path's widening and the block content join after it, which a floor
+      # here would not change.)
+      def captured_element_root(receiver)
+        root = ElementReadWidening.element_read_path(receiver)&.first
+        root && !ReceiverAlias.block_local?(root) ? [root.name] : nil
+      end
+
+      # Issue #2287 — a mutator on an element read rooted at a captured local (`[0].each { |i| a[i] << 2 }`,
+      # `loop { a[0] << 2; break }`) mutates an element the outer binding still carries, and names no variable
+      # {ReceiverAlias.candidates} could widen. The element at that path widens in the outer scope as the
+      # straight-line {ElementReadWidening.widen_element_read} widens it; a block-local root is skipped as a
+      # block-local read is. Answers the widened scope, or `nil` when the receiver is no such read or nothing widened.
+      def widen_outer_element_read(call_node, scope)
+        path = ElementReadWidening.element_read_path(call_node.receiver)
+        return nil if path.nil?
+
+        read, steps = path
+        return nil if ReceiverAlias.block_local?(read)
+
+        current = scope.local(read.name)
+        widened = current && ElementReadWidening.widen_through_path(current, steps, call_node.name, NO_ARG_TYPES)
+        widened && scope.with_mutated_local(read.name, widened)
+      end
+
       # 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
@@ -262,16 +365,37 @@ module Rigor
                                                 Prism::GlobalVariableReadNode => %i[global with_global]
                                               })
 
-      def widen_alias_read(method_name, read, scope, values: :widen, arg_types: NO_ARG_TYPES)
+      # `unread_arguments` says the call passes arguments this seam did not type (the block-capture path): a Set,
+      # which has no block content join, takes one unknown store for it ({SetMutation.widen}).
+      def widen_alias_read(method_name, read, scope, values: :widen, arg_types: NO_ARG_TYPES, unread_arguments: false, # rubocop:disable Metrics/ParameterLists
+                           rewritten_element: nil, removes_nil: false)
         getter, builder = ALIAS_ACCESSORS[read.class]
         return scope if getter.nil?
 
         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 scope if widened.nil?
+        synthesised = synthesised_binding?(scope, getter, name)
+        if synthesised && MutationRejoin.floors_grown_carrier?(scope, name, method_name)
+          return floor_grown_carrier(scope, builder, name, current, method_name, getter, removes_nil)
+        end
 
-        MutationRejoin.rebind(scope, builder, name, widened, pre_state: current, kind: getter)
+        widened = widen_for_mutator(current, method_name, values:, arg_types:, unread_arguments:, rewritten_element:,
+                                                          synthesised:)
+        scope = MutationRejoin.rebind(scope, builder, name, widened, pre_state: current, kind: getter) if widened
+        return scope unless synthesised && MutationRejoin.content_adder?(method_name)
+
+        MutationRejoin.grew_unfloored?(current, widened) ? scope.with_construction_fact(name, :grown) : scope
+      end
+
+      # Issue #2555 — a remover or filter on a synthesised carrier a store has grown. Nothing narrows the carrier back,
+      # so the stored arm would outlive the values the call removes (`parts << nil; parts.compact!`); the carrier takes
+      # the `Dynamic[top]` floor it would have carried without the fact. The binding keeps its facts: the floored
+      # carrier is gradual, so the synthesised re-join no longer applies to it, and a later remover floors it again.
+      def floor_grown_carrier(scope, builder, name, current, method_name, getter, removes_nil)
+        drop_nil = removes_nil || (method_name == :delete && MutationRejoin.hash_carrier?(current))
+        floored = MutationRejoin.floor_parameters(current, drop_nil:)
+        floored = widen_for_mutator(floored, method_name) || floored
+        MutationRejoin.rebind(scope, builder, name, floored, pre_state: current, kind: getter)
       end
 
       # Mutators that can land a NEW value in an EXISTING slot, falsifying that slot's value pinning
@@ -285,15 +409,32 @@ module Rigor
       # 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 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)
+      # nominal the call stores nothing into — see {MutationRejoin.widen_precise_array}).
+      # A `rewritten_element` answers first for the carriers {RewriteMutation.typed} types (issue #2427).
+      # `synthesised` says the binding carries the `:synthesised` construction fact (issue #2555,
+      # {Scope#construction_fact?}): a precise nominal or Set it holds re-grows without the `Dynamic[top]` floor
+      # ({MutationRejoin.widen_synthesised}, {SetMutation.widen}).
+      def widen_for_mutator(type, method_name, values: :widen, arg_types: NO_ARG_TYPES, unread_arguments: false,
+                            rewritten_element: nil, synthesised: false)
+        typed = rewritten_element && type && RewriteMutation.typed(type, method_name, rewritten_element)
+        return typed == type ? nil : typed if typed
+
+        widen_carrier(type, method_name, values:, arg_types:, unread_arguments:, rewritten_element:, synthesised:)
+      end
+
+      # {#widen_for_mutator} for a carrier no typed element rewrite answered.
+      def widen_carrier(type, method_name, values:, arg_types:, unread_arguments:, rewritten_element:,
+                        synthesised: false)
         values = :keep unless VALUE_REWRITING_MUTATORS.include?(method_name)
         values = RewriteMutation.values_mode(type, method_name, values)
 
         return nil if type.nil?
+        if SetMutation.set?(type)
+          return SetMutation.widen(type, method_name, arg_types, unread_arguments:, synthesised:)
+        end
 
         case type
-        when Type::Nominal then MutationRejoin.widen_nominal(type, method_name, values:, arg_types:)
+        when Type::Nominal then MutationRejoin.widen_nominal(type, method_name, values:, arg_types:, synthesised:)
         when Type::Tuple
           return nil unless ARRAY_MUTATORS.include?(method_name)
 
@@ -304,10 +445,9 @@ module Rigor
           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, arg_types: arg_types)
+        when Type::Difference, Type::Refined, Type::Intersection then widen_refinement(type, method_name, arg_types)
         when Type::Union
-          widen_union(type, method_name, values: values, arg_types: arg_types)
+          widen_union(type, method_name, values:, arg_types:, unread_arguments:, rewritten_element:, synthesised:)
         end
       end
 
@@ -325,12 +465,14 @@ module Rigor
       #
       # `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)
+      def widen_union(union, method_name, values: :widen, arg_types: NO_ARG_TYPES, unread_arguments: false,
+                      rewritten_element: nil, synthesised: false)
         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)
+          widened = widen_for_mutator(member, method_name, values:, arg_types:, unread_arguments:, rewritten_element:,
+                                                           synthesised:)
           next member if widened.nil?
 
           widened_any = true
@@ -348,7 +490,9 @@ module Rigor
         (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))
+          (StringMutation::MUTATORS.include?(method_name) &&
+            (StringMutation.constant?(member) || StringMutation.refined?(member))) ||
+          (SetMutation::MUTATORS.include?(method_name) && SetMutation.carrier?(member))
       end
 
       # Joins the element evidence the mutator's own ARGUMENTS introduce into the already-widened
@@ -530,6 +674,32 @@ module Rigor
         end
       end
 
+      # An intersection of String refinements carrying a predicate one (`non-empty-lowercase-string`) widens member
+      # by member: the `Refined` member to `String` ({StringMutation.widen_refined}), a `non-empty-string` member on
+      # {#widen_difference}'s witness terms. A member that widened to the bare `String` is implied by the others and
+      # drops out, so `s.upcase!` reads `non-empty-string` rather than `non-empty-string & String`. `nil` when the
+      # intersection carries no String predicate refinement, or nothing widened.
+      def widen_string_intersection(intersection, method_name, arg_types)
+        return nil unless intersection.members.any? { |m| StringMutation.refined?(m) }
+
+        members = intersection.members.map { |m| widen_refinement(m, method_name, arg_types) || m }
+        base = Type::Combinator.nominal_of("String")
+        kept = members.reject { |m| m == base }
+        widened = kept.empty? ? base : Type::Combinator.intersection(*kept)
+        widened == intersection ? nil : widened
+      end
+
+      # The refinement carriers {#widen_carrier} hands on: the empty witness ({#widen_difference}), a String predicate
+      # ({StringMutation.widen_refined}) and an intersection of them ({#widen_string_intersection}). `nil` when nothing
+      # widened.
+      def widen_refinement(type, method_name, arg_types)
+        case type
+        when Type::Difference then widen_difference(type, method_name, arg_types:)
+        when Type::Refined then StringMutation.widen_refined(type, method_name)
+        when Type::Intersection then widen_string_intersection(type, method_name, arg_types)
+        end
+      end
+
       # `Tuple[A, B, C]` → `Nominal[Array, [union(A, B, C)]]`; under `values: :widen`, each element's
       # VALUE pinning widens to its class nominal (`1 | 2` → `Integer`): a slot-rewriting mutator
       # falsifies values along with the shape — `t = [1, 2]; t[0] += 5` holds `6` at slot 0, so a