rigortype 0.4.5 → 0.4.6

data/lib/rigor/environment/required_features.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../analysis/path_expansion"
+require_relative "../rooted_glob"
 
 module Rigor
   class Environment
@@ -42,6 +43,36 @@ module Rigor
       # anything.
       PATTERN = /(?:(?<![\w.$@])|(?<=Kernel\.))require[ \t]*\(?[ \t]*(["'])(#{FEATURE_ALTERNATION})\1/
 
+      # Issue #2174 — the gems Ruby 4.0 bundles (its `gems/bundled_gems` list, which an installation does not
+      # keep): installed beside the interpreter, but loaded only by an explicit `require`. Gems installed later
+      # into the same directory are deliberately not read from it.
+      BUNDLED_GEMS = %w[
+        abbrev base64 benchmark bigdecimal csv debug drb fiddle getoptlong irb logger matrix minitest mutex_m
+        net-ftp net-imap net-pop net-smtp nkf observer ostruct power_assert prime pstore racc rake rbs rdoc readline
+        reline repl_type_completor resolv-replace rexml rinda rss syslog test-unit typeprof win32ole
+      ].freeze
+
+      # Issue #2174 — the first path segments of the features Ruby ships: the `.rb` files and directories of the
+      # interpreter's library directory, the extensions and directories of its architecture directory, and the
+      # bundled gems' names (`net-ftp` → `net`). Read once, at load time and on the main Ractor, since
+      # `RbConfig::CONFIG` is not shareable; empty when the directories cannot be read.
+      SHIPPED_SEGMENTS = begin
+        require "rbconfig"
+        segments = Set.new
+        [RbConfig::CONFIG["rubylibdir"], RbConfig::CONFIG["archdir"]].compact.each do |dir|
+          next unless File.directory?(dir)
+
+          Dir.children(dir).each { |entry| segments << entry.sub(/\.(?:rb|so|bundle|dll)\z/, "") }
+        end
+        BUNDLED_GEMS.each { |name| segments << name.split("-").first }
+        segments.to_set(&:freeze).freeze
+      rescue StandardError
+        Set.new.freeze
+      end
+
+      # A `require` of any literal feature, read as {PATTERN} reads one; {.features_of} keeps those Ruby ships.
+      ANY_FEATURE = %r{(?:(?<![\w.$@])|(?<=Kernel\.))require[ \t]*\(?[ \t]*(["'])([\w-]+(?:/[\w-]+)*)\1}
+
       module_function
 
       # The features a run over `configuration` requires: every file under the configured paths, plus
@@ -53,37 +84,51 @@ module Rigor
       def for_configuration(configuration, extra_files = [], sources: {})
         files = Analysis::PathExpansion.ruby_files(configuration.paths, configuration.exclude_patterns,
                                                    base: configuration.exclude_base)
-        scan(files + Array(extra_files).map(&:to_s), sources: sources)
+        scan(files + Array(extra_files).map(&:to_s), sources: sources,
+                                                     sig_paths: configured_sig_paths(configuration))
       rescue StandardError
         []
       end
 
+      # The project signature roots the environment loads: the configured `signature_paths:`, else `./sig` when it
+      # exists (`Environment.project_signature_roots`, which this leaf file does not load).
+      def configured_sig_paths(configuration)
+        configured = configuration.signature_paths
+        return Array(configured).map(&:to_s) if configured
+
+        File.directory?("sig") ? ["sig"] : []
+      end
+
       # @param files — source paths (Strings or Pathnames); an unreadable one contributes nothing.
       # @param sources — path => source text, scanned instead of the file; its paths are scanned even when
       #   `files` does not list them.
-      # @return the sorted, frozen features some file requires.
-      def scan(files, sources: {})
+      # @param sig_paths — the project's signature roots, whose `.rbs` declaration headers count as the project's
+      #   own names ({.relevant}).
+      # @return the sorted, frozen features some file requires, a shipped one kept only when {.relevant}.
+      def scan(files, sources: {}, sig_paths: [])
         sources = sources.to_h { |path, text| [File.expand_path(path.to_s), text] }
         paths = (Array(files).map { |path| source_key(File.expand_path(path.to_s), sources) } + sources.keys).uniq
         found = Set.new
+        names = Set.new
         paths.each do |path|
-          break if found.size == VENDORED_DIRS.size
-
-          found.merge(sources.key?(path) ? features_of(sources[path]) : memoized_features_in(path))
+          features, declared = sources.key?(path) ? scan_source(sources[path]) : memoized_scan_in(path)
+          found.merge(features)
+          names.merge(declared)
         end
         prune_memo(paths)
-        found.to_a.sort.freeze
+        relevant(found, names.merge(sig_names(sig_paths))).sort.freeze
       end
 
-      # @return path (absolute) => the features that file requires, for every file under the configured paths
-      #   that requires any. A long-lived reader (the language server) keeps this and overlays its open buffers.
+      # @return path (absolute) => `[features, declared names]` ({.scan_source}) for every file under the
+      #   configured paths that has either. A long-lived reader (the language server) keeps this, overlays its open
+      #   buffers and passes the union to {.relevant}.
       def feature_files(configuration)
         listed = Analysis::PathExpansion.ruby_files(configuration.paths, configuration.exclude_patterns,
                                                     base: configuration.exclude_base)
         files = listed.map { |path| File.expand_path(path.to_s) }
         result = files.each_with_object({}) do |path, acc|
-          features = memoized_features_in(path)
-          acc[path] = features unless features.empty?
+          scanned = memoized_scan_in(path)
+          acc[path] = scanned unless scanned.all?(&:empty?)
         end
         prune_memo(files)
         result
@@ -91,6 +136,42 @@ module Rigor
         {}
       end
 
+      # Issue #2174 — `features` with each shipped feature kept only when one of `names` (constant names the
+      # project's source or signatures declare a class or module under) is a root the feature's library declares
+      # ({RubyLibraryRoots}). Only such a feature can open a class (`RbsLoader#ruby_library_reopen?` asks it of a
+      # class every declaration of which is the project's), so dropping the rest changes no diagnostic, and keeps a
+      # `require "json"` edit in a project that reopens no library class out of the incremental snapshot's
+      # fingerprint and the language server's environment key. The listed features ({VENDORED_DIRS}) are kept.
+      def relevant(features, names)
+        return features.to_a if features.all? { |feature| VENDORED_DIRS.key?(feature) }
+
+        segments = names.empty? ? EMPTY_SEGMENTS : library_segments(names)
+        features.select { |feature| VENDORED_DIRS.key?(feature) || segments.include?(feature.split("/").first) }
+      end
+
+      # The feature segments of the libraries that declare one of `names` as a root. Loaded lazily: the roots read
+      # the `rbs` stdlib tree, which a run with no shipped `require` never needs.
+      def library_segments(names)
+        require_relative "ruby_library_roots"
+        roots = RubyLibraryRoots.shared
+        names.each_with_object(Set.new) { |name, acc| acc.merge(roots.fetch(name, EMPTY_SEGMENTS)) }
+      end
+
+      EMPTY_SEGMENTS = [].freeze
+
+      # The constant names the `.rbs` files under `sig_paths` declare a class or module under.
+      def sig_names(sig_paths)
+        Array(sig_paths).each_with_object(Set.new) do |root, acc|
+          next unless File.directory?(root.to_s)
+
+          RootedGlob.glob(root.to_s, "**/*.rbs").each do |path|
+            acc.merge(declared_names(File.binread(path)))
+          rescue SystemCallError, IOError
+            next
+          end
+        end
+      end
+
       # Paths are compared expanded, so a relative `--instead-of=lib/a.rb` replaces the configured
       # `/project/lib/a.rb`; a source whose real path matches (a symlinked directory) replaces it too. The real
       # path is asked only for a file that shares a source's basename, so a scan does not resolve every path.
@@ -114,8 +195,8 @@ module Rigor
       # build; a long-lived language server on every rebuild), so on the main Ractor each file's answer is kept
       # against its stat and the file is re-read only when the stat moved. A non-main Ractor may not touch the
       # module's state and reads the file every time.
-      def memoized_features_in(path)
-        return features_in(path) unless Ractor.current == Ractor.main
+      def memoized_scan_in(path)
+        return scan_in(path) unless Ractor.current == Ractor.main
 
         stat = File.stat(path)
         stamp = [stat.mtime.to_r, stat.ctime.to_r, stat.size, stat.ino]
@@ -123,13 +204,15 @@ module Rigor
         cached = memo[path]
         return cached.last if cached && cached.first == stamp
 
-        features = features_in(path)
-        memo[path] = [stamp, features]
-        features
+        scanned = scan_in(path)
+        memo[path] = [stamp, scanned]
+        scanned
       rescue SystemCallError
-        []
+        NOTHING
       end
 
+      NOTHING = [[].freeze, [].freeze].freeze
+
       # Keeps the memo to the files the latest scan was asked about, so a long-lived language server holds one
       # entry per project file rather than one per file it ever saw.
       def prune_memo(paths)
@@ -139,28 +222,51 @@ module Rigor
         @memo.select! { |path, _| keep.include?(path) }
       end
 
-      # @return the features one file requires.
-      def features_in(path)
-        features_of(File.binread(path))
+      # @return `[features, declared names]` for one file ({.scan_source}).
+      def scan_in(path)
+        scan_source(File.binread(path))
       rescue SystemCallError, IOError
-        []
+        NOTHING
+      end
+
+      # @return `[features, declared names]`: what {.features_of} reads, and the constant names a `class` or
+      # `module` header in `source` spells, each segment on its own (`class Net::SMTP` gives `Net` and `SMTP`).
+      def scan_source(source)
+        [features_of(source), declared_names(source)].freeze
+      end
+
+      # A header on a line of its own, or inside a comment (an rbs-inline `# @rbs!` block declares
+      # `#   class Matrix`). Over-matching a comment only keeps more features.
+      HEADER = /^[ \t]*(?:#[ \t]*)?(?:class|module)[ \t]+(?:::)?([A-Z]\w*(?:::[A-Z]\w*)*)/
+
+      def declared_names(source)
+        bytes = source.b
+        return [] unless bytes.include?("class") || bytes.include?("module")
+
+        bytes.scan(HEADER).flat_map { |(name)| name.split("::") }
+             .uniq.map { |name| name.dup.force_encoding(Encoding::UTF_8).freeze }.freeze
       end
 
-      # @return the features `source` requires.
+      # @return the features `source` requires: the listed ones ({VENDORED_DIRS}), and, for issue #2174, every
+      # feature Ruby ships ({SHIPPED_SEGMENTS}), which `RbsLoader#ruby_library_reopen?` reads to tell a reopened
+      # library class from a project class of the same name. Only the listed ones become library tokens.
       def features_of(source)
-        # A plain substring test first: almost no file mentions any listed feature, and it is far cheaper than
-        # the regexp on a file that does not.
-        return [] unless VENDORED_DIRS.each_key.any? { |feature| source.include?(feature) }
+        # A plain substring test first: a file with no `require` at all is the common case, and it is far cheaper
+        # than the regexp on a file that has none.
+        return [] unless source.include?("require")
 
         bytes = source.b
         named = []
         position = 0
-        while (match = PATTERN.match(bytes, position))
+        while (match = ANY_FEATURE.match(bytes, position))
           named << match[2] unless commented?(bytes, match.begin(0))
           position = match.end(0)
         end
-        # The table's own frozen keys, so the result is shareable across Ractors whatever the source's encoding.
-        VENDORED_DIRS.each_key.select { |feature| named.include?(feature) }
+        # The table's own frozen keys, and frozen copies of the rest, so the result is shareable across Ractors
+        # whatever the source's encoding.
+        listed = VENDORED_DIRS.each_key.select { |feature| named.include?(feature) }
+        shipped = named.select { |feature| SHIPPED_SEGMENTS.include?(feature.split("/").first) }
+        (listed + shipped.map { |feature| feature.dup.force_encoding(Encoding::UTF_8).freeze }).uniq
       end
 
       # Whether the match at `offset` sits on a line whose first non-blank character is `#`: a whole-line comment.
@@ -176,7 +282,8 @@ module Rigor
       # The library tokens for `features` and for any listed feature the configuration's `libraries:` names.
       def tokens(features, configured_libraries)
         configured = Array(configured_libraries).map(&:to_s).select { |name| VENDORED_DIRS.key?(name) }
-        (Array(features) | configured).sort.map { |feature| token(feature) }
+        listed = Array(features).select { |feature| VENDORED_DIRS.key?(feature) }
+        (listed | configured).sort.map { |feature| token(feature) }
       end
 
       def token(feature)

data/lib/rigor/environment/ruby_library_roots.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "rbs"
+require "rbconfig"
+require_relative "missing_gem_constant_index"
+require_relative "required_features"
+require_relative "../rooted_glob"
+
+module Rigor
+  class Environment
+    # Issue #2174 — which library Ruby ships declares each root constant name. Three sources are read, and no others:
+    #
+    # - every library of the `rbs` gem's `stdlib/` tree, loaded into this run or not, read from its `.rbs` files
+    #   (`net-http` declares `Net`);
+    # - every top-level `.rb` file of the interpreter's library directory (`RbConfig::CONFIG["rubylibdir"]`), the
+    #   default gems' and the standard library's entry files, read from their top-level declarations;
+    # - the entry file of each gem Ruby bundles ({RequiredFeatures::BUNDLED_GEMS}), found under the interpreter's
+    #   gem directory. A gem installed there later is not one of them and is not read.
+    #
+    # Each root maps to the first path segments of the features that load it (`Matrix` → `matrix`, `Net` → `net`),
+    # which {RbsLoader#ruby_library_reopen?} intersects with the features the project's source requires
+    # ({RequiredFeatures.features_of}).
+    #
+    # Ownership is read, never guessed by camelizing a library name, for the reason {MissingGemConstantIndex}
+    # gives; that module's reader parses the `.rb` entry files. No library code runs. Everything fails open to
+    # "no library", which keeps the pre-#2174 reading. Core names (`Array`, `Kernel`) appear too, harmlessly:
+    # core signatures always load, so no project-only class carries one.
+    #
+    # The directories are resolved at load time, on the main Ractor: `RbConfig::CONFIG` and `Gem.default_dir`
+    # read non-shareable constants and raise `Ractor::IsolationError` inside a pool worker. The scan itself runs
+    # lazily (about 0.1 s), memoised per loader, and only for a class about to be reported.
+    module RubyLibraryRoots
+      STDLIB_ROOT = begin
+        ::RBS::Repository::DEFAULT_STDLIB_ROOT.to_s.dup.freeze
+      rescue StandardError
+        nil
+      end
+
+      RUBY_LIB_DIR = begin
+        RbConfig::CONFIG["rubylibdir"].to_s.dup.freeze
+      rescue StandardError
+        nil
+      end
+
+      RUBY_GEMS_DIR = begin
+        File.join(Gem.default_dir, "gems").freeze
+      rescue StandardError
+        nil
+      end
+
+      module_function
+
+      # {.build}, built once per process on the main Ractor, where the language server and the incremental
+      # snapshot fingerprint ask it repeatedly; a non-main Ractor may not keep module state and builds its own.
+      def shared
+        return build unless Ractor.current == Ractor.main
+
+        @shared ||= build
+      end
+
+      # The frozen map of root constant name to the frozen set of feature segments that load it.
+      def build
+        roots = Hash.new { |hash, key| hash[key] = Set.new }
+        stdlib_roots(roots)
+        ruby_lib_roots(roots)
+        bundled_gem_roots(roots)
+        roots.each_value(&:freeze)
+        roots.default_proc = nil
+        roots.freeze
+      end
+
+      def stdlib_roots(roots)
+        return if STDLIB_ROOT.nil? || !File.directory?(STDLIB_ROOT)
+
+        Dir.children(STDLIB_ROOT).each do |library|
+          segment = library.split("-").first
+          RootedGlob.glob(File.join(STDLIB_ROOT, library), "*/**/*.rbs").each do |path|
+            stdlib_file_roots(path).each { |root| roots[root] << segment }
+          end
+        end
+      end
+
+      def stdlib_file_roots(path)
+        _, _, decls = ::RBS::Parser.parse_signature(File.read(path))
+        decls.filter_map { |decl| root_of(decl) if named_declaration?(decl) }
+      rescue StandardError
+        []
+      end
+
+      def ruby_lib_roots(roots)
+        return if RUBY_LIB_DIR.nil? || !File.directory?(RUBY_LIB_DIR)
+
+        RootedGlob.glob(RUBY_LIB_DIR, "*.rb").each do |path|
+          segment = File.basename(path, ".rb")
+          MissingGemConstantIndex.top_level_root_constants(path).each { |root| roots[root] << segment }
+        end
+      end
+
+      def bundled_gem_roots(roots)
+        return if RUBY_GEMS_DIR.nil? || !File.directory?(RUBY_GEMS_DIR)
+
+        Dir.children(RUBY_GEMS_DIR).each do |basename|
+          gem_name = basename[/\A(.+?)-\d/, 1]
+          next if gem_name.nil? || !RequiredFeatures::BUNDLED_GEMS.include?(gem_name)
+
+          segment = gem_name.split("-").first
+          MissingGemConstantIndex.entry_files(File.join(RUBY_GEMS_DIR, basename), gem_name).each do |path|
+            MissingGemConstantIndex.top_level_root_constants(path).each { |root| roots[root] << segment }
+          end
+        end
+      end
+
+      def named_declaration?(decl)
+        decl.is_a?(::RBS::AST::Declarations::Class) || decl.is_a?(::RBS::AST::Declarations::Module)
+      end
+
+      def root_of(decl)
+        decl.name.to_s.delete_prefix("::").split("::").first
+      end
+    end
+  end
+end

data/lib/rigor/environment.rb

@@ -268,7 +268,7 @@ module Rigor
       #   {Environment::RbsLoader} so constant lookups (and, in later v0.0.9 slices, other reflection
       #   artefacts) consult the cache. Pass `nil` (the default) to skip caching for this environment.
       # rubocop:disable-next Metrics/MethodLength, Metrics/ParameterLists
-      def for_project(root: Dir.pwd, libraries: [], signature_paths: nil, cache_store: nil,
+      def for_project(root: Dir.pwd, libraries: [], signature_paths: nil, cache_store: nil, # rubocop:disable Metrics/AbcSize
                       plugin_registry: nil, dependency_source_index: nil,
                       rbs_extended_reporter: nil, boundary_cross_reporter: nil,
                       source_rbs_synthesis_reporter: nil,
@@ -364,7 +364,9 @@ module Rigor
           # Issue #610 — the plugin-contributed subset is loaded LAST and may stand down against a colliding
           # generic arity. Only the bundled plugins' own `sig/` is deferred: the user's `signature_paths:`,
           # the bundle walk and `rbs collection install` all stay authoritative.
-          deferred_signature_paths: plugin_sig_paths
+          deferred_signature_paths: plugin_sig_paths,
+          project_signature_paths: resolved_paths,
+          required_features: required_features || RequiredFeatures.scan(source_files, sig_paths: resolved_paths)
         )
         # Issues #824 / #1075 — the rows ADR-112 WD5's consistency rule reports for members the project's
         # own `sig/` and an inline source both declare: an error per contradiction (or per refinement that

data/lib/rigor/inference/callee_mutation_chain.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Inference
+    # Issue #2104 — the callee floor's census made transitive. A method that hands its parameter to another method
+    # which mutates it (`def stripes(acc) = poke(acc)`, `def poke(acc) = (acc[0] = "x")`) mutates that parameter as
+    # surely as one that writes it itself, so the caller's argument is floored after `stripes(acc)` too.
+    #
+    # This module is the closure over a parameter-flow graph, independent of how the graph is read. `own` answers a
+    # def's own census, `{ name => slot }` (a slot is a positional index or a keyword symbol); `edges` answers the
+    # {Edge}s along which a def hands one of its parameters to a resolved callee. A node is one parameter of one def,
+    # and the walk follows only the edges that hand on the parameter the node is, so a def's hand-offs of its OTHER
+    # parameters cost nothing. A node is mutated when its def mutates it or it hands itself to a mutated node: the
+    # least fixpoint, so a recursive or mutually recursive chain terminates and a cycle with no mutation on it mutates
+    # nothing.
+    #
+    # The walk reads at most {MAX_NODES} nodes per closure. A hand-off to a node past the cap is read as no hand-off,
+    # as the one-level floor reads a callee it cannot resolve: flooring there would drop a literal shape on evidence
+    # the walk never saw, and a floored `Array[Dynamic[top]]` then fails a declared tuple on correct code.
+    module CalleeMutationChain
+      # `name` and `slot` are the forwarding def's parameter, `callee` the def it is handed to, and `callee_names`
+      # the callee's parameters it may bind there.
+      Edge = Data.define(:name, :slot, :callee, :callee_names)
+
+      MAX_NODES = 32
+
+      module_function
+
+      def close(root, own:, edges:)
+        census = own.call(root)
+        handed = edges.call(root).reject { |edge| census.key?(edge.name) }
+        return census if handed.empty?
+
+        flow = Flow.new(own, edges)
+        handed.each { |edge| flow.visit(root, edge.name) }
+        flow.settle
+        handed.each_with_object(census.dup) do |edge, result|
+          result[edge.name] = edge.slot if flow.mutated?(root, edge.name)
+        end
+      end
+
+      # The parameter-flow graph one closure reads: per def, per parameter name, whether the node is mutated and the
+      # nodes it hands itself on to.
+      class Flow
+        Node = Struct.new(:mutated, :successors)
+
+        def initialize(own, edges)
+          @own = own
+          @edges = edges
+          @nodes = {}.compare_by_identity
+          @count = 0
+        end
+
+        def mutated?(def_node, name)
+          node = @nodes.dig(def_node, name)
+          !node.nil? && node.mutated
+        end
+
+        # Reads the nodes reachable from `def_node`'s `name`, breadth first, while fewer than {MAX_NODES} are read.
+        def visit(def_node, name)
+          queue = [[def_node, name]]
+          until queue.empty?
+            current, parameter = queue.shift
+            next if known?(current, parameter)
+            break if @count >= MAX_NODES
+
+            queue.concat(add(current, parameter))
+          end
+        end
+
+        def settle
+          changed = true
+          while changed
+            changed = false
+            each_node do |node|
+              next if node.mutated
+              next unless node.successors.any? { |callee, name| mutated?(callee, name) }
+
+              node.mutated = true
+              changed = true
+            end
+          end
+        end
+
+        private
+
+        def known?(def_node, name)
+          by_name = @nodes[def_node]
+          !by_name.nil? && by_name.key?(name)
+        end
+
+        # Records the node and answers its successors. A node its def mutates needs none.
+        def add(def_node, name)
+          @count += 1
+          mutated = @own.call(def_node).key?(name)
+          successors = mutated ? [] : successors_of(def_node, name)
+          (@nodes[def_node] ||= {})[name] = Node.new(mutated, successors)
+          successors
+        end
+
+        def successors_of(def_node, name)
+          @edges.call(def_node).each_with_object([]) do |edge, successors|
+            next unless edge.name == name
+
+            edge.callee_names.each { |callee_name| successors << [edge.callee, callee_name] }
+          end
+        end
+
+        def each_node(&)
+          @nodes.each_value { |by_name| by_name.each_value(&) }
+        end
+      end
+    end
+  end
+end

data/lib/rigor/inference/deep_erasure.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "prism"
+require_relative "../type"
+require_relative "../source/node_walker"
+require_relative "mutation_rejoin"
+require_relative "receiver_alias"
+
+module Rigor
+  module Inference
+    # A loop hands its collection's own elements to its body (issue #2262), so a body that mutates one in place
+    # changes a shape that the collection's binding still carries one level down. This module is the two halves of
+    # dropping that shape: whether the body mutates an element, and the type with every shape dropped at every depth.
+    module DeepErasure
+      module_function
+
+      # {MutationWidening.widen_tuple} / {MutationWidening.widen_hash_shape} applied at every depth: each `Tuple` /
+      # `HashShape` the type holds, as a union member or a type argument, drops to its nominal, so `[[1]]` reads
+      # `Array[Array[Integer]]`. A loop's element is the collection's own object, so a body that mutates it in place
+      # (`x << 2`) changes a shape one level down that the collection's binding still carries.
+      def widen(type)
+        case type
+        when Type::Tuple then widen_args(MutationWidening.widen_tuple(type))
+        when Type::HashShape then widen_args(MutationWidening.widen_hash_shape(type))
+        when Type::Nominal then widen_args(type)
+        when Type::Difference then widen(type.base)
+        when Type::Union then Type::Combinator.union(*type.members.map { |member| widen(member) })
+        else Type::Combinator.widen_value_pinned(type)
+        end
+      end
+
+      def widen_args(nominal)
+        return nominal unless nominal.is_a?(Type::Nominal) && !nominal.type_args.empty?
+
+        Type::Combinator.nominal_of(nominal.class_name, type_args: nominal.type_args.map { |arg| widen(arg) })
+      end
+
+      # The parameter nodes whose names a block (or a `for` index) binds to the collection's elements.
+      ELEMENT_PARAMETER_NODES = [
+        Prism::RequiredParameterNode, Prism::OptionalParameterNode, Prism::RestParameterNode,
+        Prism::KeywordRestParameterNode, Prism::LocalVariableTargetNode
+      ].freeze
+      ELEMENT_WRITE_NODES = [
+        Prism::IndexOperatorWriteNode, Prism::IndexOrWriteNode, Prism::IndexAndWriteNode,
+        Prism::CallOperatorWriteNode, Prism::CallOrWriteNode, Prism::CallAndWriteNode,
+        Prism::IndexTargetNode, Prism::CallTargetNode
+      ].freeze
+      private_constant :ELEMENT_PARAMETER_NODES, :ELEMENT_WRITE_NODES
+
+      # True when `body` mutates in place a value that a name in `names` (a loop's element) holds: a mutator
+      # (`MutationWidening::SHAPE_MUTATORS`) called on a read or an index chain rooted at it (`x << 1`,
+      # `x[0].push(1)`, `x[0] = 1`), or an operator write on one (`x[0] += 1`). Every name a block or a
+      # `for` inside the body binds counts as an element too (`x.each { |y| y << 1 }`, `for c in x; c << 1; end`),
+      # and so does `it` / `_1` wherever it is read, and an accumulator parameter (`inject([]) { |acc, e| acc << e }`):
+      # the rule is wider than "an element", which only loses precision. It does not follow an alias (`y = x`) or
+      # an element passed to a call (`add(x)`), which the straight-line widening does not either.
+      def element_mutation?(body, names)
+        return false if body.nil?
+
+        names |= nested_parameter_names(body)
+        Source::NodeWalker.each(body).any? { |node| element_mutation_site?(node, names) }
+      end
+
+      # The names `parameters` (a block's parameter list, or a `for` index) binds.
+      def parameter_names(parameters)
+        return [] if parameters.nil?
+
+        Source::NodeWalker.each(parameters).filter_map do |node|
+          node.name if ELEMENT_PARAMETER_NODES.include?(node.class)
+        end
+      end
+
+      def nested_parameter_names(body)
+        Source::NodeWalker.each(body).flat_map do |node|
+          case node
+          when Prism::BlockNode then parameter_names(node.parameters)
+          when Prism::ForNode then parameter_names(node.index)
+          else []
+          end
+        end
+      end
+
+      def element_mutation_site?(node, names)
+        if node.is_a?(Prism::CallNode)
+          MutationWidening::SHAPE_MUTATORS.include?(node.name) && element_rooted?(node.receiver, names)
+        else
+          ELEMENT_WRITE_NODES.include?(node.class) && element_rooted?(node.receiver, names)
+        end
+      end
+
+      def element_rooted?(node, names)
+        node = node.receiver while node.is_a?(Prism::CallNode) && node.receiver
+        node = node.body.body.last while node.is_a?(Prism::ParenthesesNode) && node.body.is_a?(Prism::StatementsNode)
+        case node
+        when Prism::LocalVariableReadNode then names.include?(node.name) || /\A_[1-9]\z/.match?(node.name)
+        when Prism::ItLocalVariableReadNode then true
+        else false
+        end
+      end
+
+      # A block call hands each of its receiver's elements to the block's parameters, and a body that mutates one in
+      # place (`a.each { |x| x << 2 }`) changes the shape the receiver's binding still carries one level down
+      # (`[[1]]`). The receiver's variables drop their shapes at every depth ({widen}), as a `for` loop's
+      # value does ({StatementEvaluator#for_collection_after}).
+      def widen_element_aliases(receiver, body, names, scope)
+        return scope unless element_mutation?(body, names)
+
+        widen_receiver(receiver, scope)
+      end
+
+      def widen_receiver(receiver, scope)
+        ReceiverAlias.candidates(receiver).reduce(scope) { |acc, read| widen_read(read, acc) }
+      end
+
+      # `a.each(&:strip!)`: a block argument naming a mutator mutates every element it is handed.
+      def symbol_proc_mutation?(block)
+        block.is_a?(Prism::BlockArgumentNode) && block.expression.is_a?(Prism::SymbolNode) &&
+          MutationWidening::SHAPE_MUTATORS.include?(block.expression.unescaped.to_sym)
+      end
+
+      def widen_symbol_proc(call_node, scope) = widen_receiver(call_node.receiver, scope)
+
+      def widen_read(read, scope)
+        getter, builder = MutationWidening::ALIAS_ACCESSORS[read.class]
+        return scope if getter.nil?
+
+        name = ReceiverAlias.read_name(read)
+        current = scope.public_send(getter, name)
+        return scope if current.nil?
+
+        widened = widen(current)
+        return scope if widened == current
+
+        MutationRejoin.rebind(scope, builder, name, widened, pre_state: current, kind: getter)
+      end
+    end
+  end
+end