rigortype 0.4.4 → 0.4.6

data/lib/rigor/inference/project_patched_scanner.rb

@@ -4,6 +4,8 @@ require "prism"
 
 require_relative "project_patched_methods"
 require_relative "project_patched_definedness_guard"
+require_relative "project_patched_visibility"
+require_relative "project_patched_mixins"
 require_relative "../analysis/dependency_source_inference/return_type_heuristic"
 require_relative "../source/alias_names"
 require_relative "../source/constant_path"
@@ -20,7 +22,7 @@ module Rigor
     # only needs `class C; def m; end; end` shape recognition, not full inference. Parse errors degrade
     # to a fail-soft `:warning` `pre-eval.parse-error` diagnostic accumulated alongside the registry;
     # per ADR-17 § "Failure modes" a parse failure in a pre-eval file MUST NOT abort the rest of the run.
-    module ProjectPatchedScanner
+    module ProjectPatchedScanner # rubocop:disable Metrics/ModuleLength
       # Frozen scan outcome carrying the populated registry and the per-file warnings the runner emits
       # at run start.
       class Result < Data.define(:registry, :diagnostics)
@@ -57,10 +59,13 @@ module Rigor
         diagnostics = []
         census = Set.new
         paths.each { |path| scan_file(path, collected, diagnostics, buffer, census) }
-        entries = resolve_aliases(collected)
+        pending_mixins, collected = collected.partition { |item| item.is_a?(Mixins::Pending) }
+        overrides = {}
+        entries = resolve_aliases(collected, overrides)
         diagnostics.concat(duplicate_declaration_diagnostics(entries))
         Result.new(
-          registry: ProjectPatchedMethods.new(entries: entries, write_census: census.freeze),
+          registry: ProjectPatchedMethods.new(entries: entries, write_census: census.freeze, overrides: overrides,
+                                              mixins: Mixins.resolve(pending_mixins, entries)),
           diagnostics: diagnostics
         )
       end
@@ -105,32 +110,50 @@ module Rigor
       # idiom (`def foo`, `alias_method :foo_without_x, :foo`, `alias_method :foo, :foo_with_x`) leaves `foo` the
       # alias. Bindings of one name in DIFFERENT files are what `pre-eval.duplicate-declaration` reports, and the
       # registry keeps the last of those, as Ruby does.
-      def resolve_aliases(collected)
+      #
+      # A {Visibility::Pending} (issue #1708) changes the visibility of the binding its name has when it runs, in the
+      # file that bound it, so it is not a second declaration; a name no earlier patch binds on the class is one it
+      # inherits, recorded in `overrides` ({Visibility.apply}). `module_function :x` also binds the public singleton
+      # copy.
+      def resolve_aliases(collected, overrides = {})
         bound = {}
+        homes = {}
         per_file = collected.group_by(&:source_path).values.map do |items|
           final = {}
           items.each do |item|
+            if item.is_a?(Visibility::Pending)
+              next Visibility.apply(item, bound, homes, overrides) { |copy| bind(copy, bound, homes, final) }
+            end
+
             entry = item.is_a?(PendingAlias) ? alias_entry(item, bound) : item
             entry = entry.entry if entry.is_a?(GuardedDef)
             key = [entry.class_name, entry.method_name, entry.kind]
             next if item.is_a?(GuardedDef) && bound.key?(key)
 
-            bound[key] = entry
-            final.delete(key)
-            final[key] = entry
+            bind(entry, bound, homes, final)
           end
-          final.values
+          final
         end
-        per_file.flatten(1)
+        per_file.flat_map(&:values)
       end
       private_class_method :resolve_aliases
 
+      def bind(entry, bound, homes, final)
+        key = [entry.class_name, entry.method_name, entry.kind]
+        bound[key] = entry
+        homes[key] = final
+        final.delete(key)
+        final[key] = entry
+      end
+      private_class_method :bind
+
       def alias_entry(item, bound)
         target = bound[[item.class_name, item.old_name, item.kind]]
         ProjectPatchedMethods::Entry.new(
           class_name: item.class_name, method_name: item.new_name, kind: item.kind,
           source_path: item.source_path, source_line: item.source_line,
-          return_type: target&.return_type, alias_of: target ? target.alias_of : item.old_name
+          return_type: target&.return_type, alias_of: target ? target.alias_of : item.old_name,
+          visibility: target ? target.visibility : :public
         )
       end
       private_class_method :alias_entry
@@ -148,8 +171,7 @@ module Rigor
           return
         end
 
-        Thread.current[:rigor_guarded_defs] = DefinednessGuard.defs(parse_result.value)
-        walk_node(parse_result.value, [], false, path, entries)
+        walk_file(parse_result.value, path, entries)
         # Issue #1367 — the file's `global.*` write facts: a patch file may alias a special or give a class the
         # method a setter asks for, as any project file may.
         census.merge(GlobalWriteCensus.scan(parse_result.value))
@@ -164,9 +186,19 @@ module Rigor
         )
       ensure
         Thread.current[:rigor_guarded_defs] = nil
+        Thread.current[:rigor_def_visibilities] = nil
       end
       private_class_method :scan_file
 
+      # Walks one parsed file with its definedness guards and `def` visibilities (issue #1708) in reach of
+      # {record_def_node}.
+      def walk_file(root, path, entries)
+        Thread.current[:rigor_guarded_defs] = DefinednessGuard.defs(root)
+        Thread.current[:rigor_def_visibilities] = Visibility.defs(root)
+        walk_node(root, [], false, path, entries)
+      end
+      private_class_method :walk_file
+
       def parse_error_diagnostic(path, errors)
         first = errors.first
         line = first.respond_to?(:location) ? first.location&.start_line || 1 : 1
@@ -205,6 +237,11 @@ module Rigor
         when Prism::CallNode
           record_alias(node, Source::AliasNames.alias_method_call_names(node), qualified_prefix,
                        in_singleton_class, source_path, entries)
+          if Thread.current[:rigor_def_visibilities]&.[](node).equal?(Visibility::STATEMENT)
+            pending = Visibility.pending(node, qualified_prefix, in_singleton_class, source_path)
+            entries << pending if pending
+            entries.concat(Mixins.pending(node, qualified_prefix, in_singleton_class))
+          end
           walk_children(node, qualified_prefix, in_singleton_class, source_path, entries)
         else
           walk_children(node, qualified_prefix, in_singleton_class, source_path, entries)
@@ -251,7 +288,9 @@ module Rigor
           source_path: source_path, source_line: line,
           return_type: return_type
         )
+        entry, *copies = Visibility.applied(entry, Thread.current[:rigor_def_visibilities]&.[](node) || :public)
         entries << (Thread.current[:rigor_guarded_defs]&.key?(node) ? GuardedDef.new(entry: entry) : entry)
+        entries.concat(copies)
       end
       private_class_method :record_def_node
 

data/lib/rigor/inference/project_patched_visibility.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../source/literals"
+require_relative "../source/node_children"
+require_relative "module_function_state"
+require_relative "project_patched_mixins"
+
+module Rigor
+  module Inference
+    module ProjectPatchedScanner
+      # Issue #1708 — the visibility a `pre_eval:` file gives each `def` it writes in a class, module or `class <<`
+      # body, so a private patch does not answer a call with an explicit receiver. Ruby 4.0.5:
+      # `module Kernel; private def kp = 1; end; 1.kp` raises NoMethodError (private method 'kp' called for an
+      # instance of Integer), while a bare `kp` runs.
+      #
+      # The readings, over each body's direct statements in order:
+      #
+      # - a bare `private`, `protected`, `public` or `module_function` (receiverless or on `self`) sets the default
+      #   for the `def`s after it in that body;
+      # - `private def x`, `protected def x`, `public def x`, `module_function def x` set that `def`'s, and
+      #   `private_class_method def self.x` / `public_class_method def self.x` a singleton `def`'s;
+      # - a `def self.x` is public whatever the default says, as in Ruby;
+      # - a `def` nested in a statement (an `if`, a `begin`) takes the default, unless the statement holds a bare
+      #   call of its own, which may or may not run: then it and every `def` after it are public, the reading that
+      #   answers more calls.
+      #
+      # A `def` this does not reach (one in a block, a `rescue` clause, or a body nested in a conditional, a block or a
+      # method, which may not run) is public. A named call with Symbol arguments (`private :x`) is the scanner's to
+      # apply, since it may name a `def` of an earlier file ({.pending}).
+      module Visibility
+        # The receiverless calls that set an instance `def`'s visibility, and what they set. `module_function` makes
+        # the instance method private and adds a public singleton copy.
+        INSTANCE_CALLS = {
+          private: :private, protected: :protected, public: :public, module_function: :module_function
+        }.freeze
+        # The calls that set a singleton `def`'s visibility.
+        SINGLETON_CALLS = { private_class_method: :private, public_class_method: :public }.freeze
+
+        # The nodes a nested `def` does not take the body's default under: another body, or a block.
+        OPAQUE = [
+          Prism::ClassNode, Prism::ModuleNode, Prism::SingletonClassNode, Prism::DefNode, Prism::BlockNode,
+          Prism::LambdaNode
+        ].freeze
+        private_constant :OPAQUE
+
+        # The bodies {.read_body} reads when they are a direct statement of a body it reads.
+        BODIES = [Prism::ClassNode, Prism::ModuleNode, Prism::SingletonClassNode].freeze
+        private_constant :BODIES
+
+        # A named visibility call (`private :x`, `module_function :x`, `private_class_method :x`) in a body, which
+        # {ProjectPatchedScanner.resolve_aliases} applies to the binding its name has when it runs. `visibility` is
+        # `:private`, `:protected`, `:public` or `:module_function`.
+        Pending = Data.define(:class_name, :names, :kind, :visibility, :source_path, :source_line)
+
+        module_function
+
+        # The {Pending} change a named visibility call in a body makes, or nil. The `def`-argument form
+        # (`private def x`) is {.defs}'s; a computed name is skipped, leaving the method public.
+        def pending(node, qualified_prefix, in_singleton_class, source_path)
+          return nil if qualified_prefix.empty?
+
+          visibility, side = call(node)
+          return nil if visibility.nil? || node.arguments.nil?
+
+          names = node.arguments.arguments.filter_map { |arg| Source::Literals.symbol_or_string(arg) }
+          return nil if names.empty?
+
+          Pending.new(
+            class_name: qualified_prefix.join("::"), names: names,
+            kind: side == :singleton || in_singleton_class ? :singleton : :instance, visibility: visibility,
+            source_path: source_path, source_line: node.location&.start_line || 1
+          )
+        end
+
+        # The value {.defs} records for a call written as a direct statement of a body or of the file's top level, the
+        # only calls whose named visibility change ({.pending}) or mixin edge ({Mixins.pending}) the scanner applies to
+        # the body's class. A call nested in a conditional, a block, a method body or a `Class.new` may not run, or
+        # runs on another class, so it changes nothing: the reading that answers more calls.
+        STATEMENT = Object.new.freeze
+
+        # @return the visibility of each `def` (by identity) the file's bodies give one other than public:
+        #   `:private`, `:protected` or `:module_function`; and {STATEMENT} for each call that is a direct statement,
+        #   and for the include an idempotence guard runs ({Mixins.guarded}).
+        def defs(root)
+          found = {}.compare_by_identity
+          # The file's top level, and through {.read_body} every class, module or `class <<` body written as a direct
+          # statement of it or of another body so read: the bodies that run whenever the file loads. A body nested in
+          # a conditional, a block or a method may not run, so none of its calls or toggles is read and its `def`s
+          # are public.
+          read_body(root.statements, found, top_level: true) if root.is_a?(Prism::ProgramNode)
+          found
+        end
+
+        # Applies a {Pending} change to the binding each of its names has: `bound` maps `[class_name, name, kind]` to
+        # that binding and `homes` to the per-file table holding it, which is updated in place, so the change is not a
+        # second declaration. A name the class does not bind is one it inherits (`public :kp` in `class Integer` over
+        # `module Kernel; private def kp`), which Ruby copies onto the class with the new visibility: `overrides` gets
+        # `key => visibility` for {ProjectPatchedMethods#lookup_through_ancestors} to apply to the body it finds farther
+        # on. Yields each copy that binds (`module_function :x`'s singleton), at the call's line, for the caller to
+        # bind.
+        def apply(pending, bound, homes, overrides)
+          pending.names.each do |name|
+            key = [pending.class_name, name, pending.kind]
+            entry = bound[key]
+            next overrides[key] = pending.visibility if entry.nil?
+
+            changed, *copies = applied(entry, pending.visibility)
+            bound[key] = homes[key][key] = changed
+            copies.each { |copy| yield copy.with(source_path: pending.source_path, source_line: pending.source_line) }
+          end
+        end
+
+        # `entry` as `visibility` leaves it, then any copy that binds: `module_function` makes an instance method
+        # private and binds a public singleton copy, as Ruby does.
+        def applied(entry, visibility)
+          return [entry.with(visibility: visibility)] unless visibility == :module_function
+
+          copies = [entry.with(visibility: :private)]
+          copies << entry.with(kind: :singleton, visibility: :public) if entry.kind == :instance
+          copies
+        end
+
+        # The visibility call `node` is, as `[visibility, side]`, or nil: `side` is `:instance` for the
+        # {INSTANCE_CALLS} and `:singleton` for the {SINGLETON_CALLS}.
+        def call(node)
+          return nil unless node.is_a?(Prism::CallNode)
+          return nil unless node.receiver.nil? || node.receiver.is_a?(Prism::SelfNode)
+
+          if (visibility = INSTANCE_CALLS[node.name])
+            [visibility, :instance]
+          elsif (visibility = SINGLETON_CALLS[node.name])
+            [visibility, :singleton]
+          end
+        end
+
+        # The include an idempotence guard runs (`X.include(M) unless X.include?(M)`) is read as a direct statement.
+        def mark_guarded(stmt, found, top_level)
+          guarded = Mixins.guarded(stmt, top_level)
+          found[guarded] = STATEMENT if guarded
+        end
+        private_class_method :mark_guarded
+
+        # `top_level` is true for the file's own statements only; a body it reads is a class or module body.
+        def read_body(body, found, top_level: false) # rubocop:disable Metrics/PerceivedComplexity
+          default = :public
+          direct_statements(body).each do |stmt|
+            found[stmt] = STATEMENT if stmt.is_a?(Prism::CallNode)
+            visibility, side = call(stmt)
+            if visibility && ModuleFunctionState.bare?(stmt)
+              default = visibility if side == :instance
+            elsif visibility
+              mark_arguments(stmt, visibility, side, found)
+            elsif stmt.is_a?(Prism::DefNode)
+              mark(stmt, default, found) if stmt.receiver.nil?
+            elsif BODIES.any? { |kind| stmt.is_a?(kind) }
+              read_body(stmt.body, found)
+            else
+              mark_guarded(stmt, found, top_level)
+              default = :public if bare_call_nested?(stmt)
+              mark_nested(stmt, default, found)
+            end
+          end
+        end
+        private_class_method :read_body
+
+        def direct_statements(body)
+          body = body.statements if body.is_a?(Prism::BeginNode)
+          body.is_a?(Prism::StatementsNode) ? body.body : []
+        end
+        private_class_method :direct_statements
+
+        def mark_arguments(call, visibility, side, found)
+          call.arguments&.arguments&.each do |arg|
+            next unless arg.is_a?(Prism::DefNode)
+            next unless (side == :singleton) == arg.receiver.is_a?(Prism::SelfNode)
+
+            mark(arg, visibility, found)
+          end
+        end
+        private_class_method :mark_arguments
+
+        def mark(def_node, visibility, found)
+          found[def_node] = visibility unless visibility == :public
+        end
+        private_class_method :mark
+
+        def mark_nested(node, default, found)
+          return unless node.is_a?(Prism::Node)
+          return if OPAQUE.any? { |kind| node.is_a?(kind) } && !node.is_a?(Prism::DefNode)
+
+          if node.is_a?(Prism::DefNode)
+            mark(node, default, found) if node.receiver.nil?
+            return
+          end
+          node.rigor_each_child { |child| mark_nested(child, default, found) }
+        end
+        private_class_method :mark_nested
+
+        def bare_call_nested?(node)
+          return false unless node.is_a?(Prism::Node)
+          return false if OPAQUE.any? { |kind| node.is_a?(kind) }
+
+          visibility, = call(node)
+          return true if visibility && ModuleFunctionState.bare?(node)
+
+          node.compact_child_nodes.any? { |child| bare_call_nested?(child) }
+        end
+        private_class_method :bare_call_nested?
+      end
+    end
+  end
+end

data/lib/rigor/inference/project_seed_tables.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative "scope_indexer"
+
+module Rigor
+  module Inference
+    # Issue #1614 — the cross-file discovery seed the paths that type a project WITHOUT a `check` run hand their
+    # per-file scopes: {Protection::DiscoverySeed} (the protection scan, `rigor coverage`) and
+    # {ParameterInferenceCollector} (the ADR-67 call-site pre-pass, which `check` itself runs under
+    # `parameter_inference:`). Each used to keep its own list of tables, and each dropped some that
+    # `Analysis::Runner#project_scope_seed_tables` carries, so a cross-file constant read `30` under `check` and
+    # `Dynamic` under coverage, and a parameter whose call sites pass it went uninferred.
+    #
+    # This module is the one list both paths read. {Analysis::Runner#project_scope_seed_tables} stays the
+    # reference; `spec/rigor/inference/project_seed_tables_spec.rb` compares the two over a project that fills
+    # every table, and requires each table the runner seeds and this one does not to be in {NOT_SEEDED}, with its
+    # reason.
+    module ProjectSeedTables
+      module_function
+
+      # The def-index slots that seed a per-file scope as they are, each with the {Scope::DiscoveryIndex} member it
+      # fills.
+      SLOTS = {
+        def_nodes: :discovered_def_nodes, def_nestings: :discovered_def_nestings,
+        singleton_def_nodes: :discovered_singleton_def_nodes, def_sources: :discovered_def_sources,
+        singleton_def_sources: :discovered_singleton_def_sources, superclasses: :discovered_superclasses,
+        header_nestings: :discovered_header_nestings, includes: :discovered_includes,
+        prepends: :discovered_prepends, extends: :discovered_extends, unpositioned_mixins: :unpositioned_mixins,
+        class_sources: :discovered_class_sources, method_visibilities: :discovered_method_visibilities,
+        methods: :discovered_methods, parameter_envelopes: :discovered_parameter_envelopes,
+        data_member_layouts: :data_member_layouts, struct_member_layouts: :struct_member_layouts,
+        deferred_ranges: :discovered_deferred_ranges, refinements: :discovered_refinements,
+        global_write_census: :discovered_global_write_census
+      }.freeze
+
+      # The tables `Runner#project_scope_seed_tables` can seed that {.from_index} leaves out, and why. Parity is over
+      # the table LIST: the runner's opt-in additions to a table's content are not reproduced here.
+      # `discovered_refinements` is the project's alone (the runner unions in the refinements of gems under
+      # `dependencies.source_inference:`), and no `discovery_seed:` base is merged in (the runner can start from one).
+      NOT_SEEDED = {
+        run_generation: "the identity token of a check run's return memo; these paths run no check",
+        constant_sources: "read by dependency recording and the #663 pre_eval retraction; a seed carries it only " \
+                          "when asked (DiscoverySeed.tables_for_buffer(constant_sources: true), the editor publish)",
+        param_inferred_types: "the parameter-inference output itself; each caller adds its own " \
+                              "(DiscoverySeed.build, coverage under parameter_inference:, the collector's last round)"
+      }.freeze
+
+      # The seed tables over `paths`, from one parse of each file.
+      def for_paths(paths)
+        from_index(ScopeIndexer.discovered_project_index_for_paths(paths))
+      end
+
+      # Maps a `{ classes:, def_index: }` discovery index onto {Scope::DiscoveryIndex} member names. Empty tables are
+      # dropped so an empty seed stays `{}`; a paired member and its sibling are dropped only together.
+      #
+      # `in_source_constants` is the project's literal constant table alone: the `pre_eval:` publication a `check` run
+      # joins to it types each listed file's writes against the RBS environment, which these paths do not build first.
+      def from_index(index)
+        def_index = index.fetch(:def_index)
+        tables = { discovered_classes: index.fetch(:classes) }
+        SLOTS.each { |slot, member| tables[member] = def_index.fetch(slot) }
+        tables.merge!(constant_tables(def_index.fetch(:constant_values), def_index.fetch(:constant_writes)))
+        tables.merge!(def_index.fetch(:siblings))
+        Scope::DiscoveryIndex.compact_pairs(
+          tables.reject { |name, table| !Scope::DiscoveryIndex.paired?(name) && (table.nil? || table.empty?) }
+        )
+      end
+
+      def constant_tables(values, writes)
+        {
+          in_source_constants: values,
+          published_constant_names: published_constant_names(values),
+          constant_writers: constant_writers(writes),
+          constant_shadowers: constant_shadowers(writes)
+        }
+      end
+
+      # Issue #644 — the last segments of the published constant table, the run-wide half of
+      # `Scope#published_constant?`.
+      def published_constant_names(values)
+        values.keys.to_set { |name| name.split("::").last }.freeze
+      end
+
+      # Issue #617 — the censused names that bind, grouped by last segment (`Scope#bound_constant_names`). A name some
+      # write other than a memo `||=` touches always binds. A memo-only name binds once memos of its segment span two
+      # files: either may load first and set the constant the other then reads, so only a memo no other file shares
+      # keeps the idiom's reading. Files are counted expanded, because discovery can walk one file under two
+      # spellings (`lib/b.rb`, `./lib/b.rb`).
+      def constant_writers(writes)
+        memo_files = memo_files_by_segment(writes)
+        writes.each_with_object({}) do |(name, by_path), index|
+          segment = name.split("::").last
+          next if memo_only?(by_path) && memo_files.fetch(segment).size < 2
+
+          (index[segment] ||= []) << name
+        end.each_value(&:freeze).freeze
+      end
+
+      # Issue #1290 — the censused names some write other than a memo `||=` assigns, grouped by last segment
+      # (`Scope#shadowing_constant_names`): the ones that exist whether or not an outer constant of the name does, and
+      # so stop the lexical ladder above it. A memo-only name is left out however many files memoize it, unlike in
+      # {.constant_writers}: `X ||= v` resolves `X` through the very lookup whose lower rung the stop would replace,
+      # so wherever that rung answers, the memo finds it and never creates the name.
+      def constant_shadowers(writes)
+        writes.each_with_object({}) do |(name, by_path), index|
+          (index[name.split("::").last] ||= []) << name unless memo_only?(by_path)
+        end.each_value(&:freeze).freeze
+      end
+
+      def memo_files_by_segment(writes)
+        writes.each_with_object({}) do |(name, by_path), files|
+          set = (files[name.split("::").last] ||= Set.new)
+          by_path.each { |path, descriptor| set << File.absolute_path(path) if memo_descriptor?(descriptor) }
+        end
+      end
+
+      def memo_only?(by_path) = by_path.each_value.all? { |descriptor| memo_descriptor?(descriptor) }
+      def memo_descriptor?(descriptor) = descriptor == ScopeIndexer::CONSTANT_MEMO
+    end
+  end
+end

data/lib/rigor/inference/project_yielder.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../type"
+
+module Rigor
+  module Inference
+    # Issue #2127 — whether a call to a PROJECT method may run the block it passes more than once, read off the
+    # callee's body. {BlockRepetition.may_repeat?} answers only for the core iterators {ClosureEscapeAnalyzer}
+    # catalogues, so `def yielder = (yield; yield)` or the idiomatic wrapper `def each = @items.each { |i| yield i }`
+    # counted as running the block once, and a `return` in the block that only a later run reaches (`each { return
+    # false if (seen += 1) > 3 }`) never joined the method's return type.
+    #
+    # Only the later-run `return` pass asks this (`StatementEvaluator#collect_repeated_block_returns`); the block's
+    # entry scopes and the ADR-56 write-back keep {BlockRepetition}'s rule. That pass only widens the method's
+    # return type, so the rule here errs toward "repeats". The callee repeats when its body, outside a nested `def`
+    # (a `yield` in a class body is a syntax error inside a method):
+    #
+    # - holds two or more sites that run the block (`yield`, or `call` / `yield` / `===` / `[]` on the `&blk`
+    #   parameter), or one inside a loop, a block or a lambda, which may run it many times; or
+    # - hands the block on (`each(&blk)`, `each(&)`, `...` forwarding) or reads the `&blk` parameter any other way
+    #   (stores it, passes it as an argument), so code the walk does not see may run it any number of times.
+    #
+    # A callee the analysis cannot resolve to a project `def` (an unknown receiver, a method defined by
+    # metaprogramming) answers false, as before.
+    module ProjectYielder
+      module_function
+
+      BLOCK_RUN_CALLS = Set[:call, :yield, :===, :[]].freeze
+      REPEATING_NODES = Set[Prism::WhileNode, Prism::UntilNode, Prism::ForNode, Prism::BlockNode,
+                            Prism::LambdaNode].freeze
+      private_constant :BLOCK_RUN_CALLS, :REPEATING_NODES
+
+      def may_run_block_repeatedly?(call_node, receiver_type, scope)
+        def_node = callee_def(call_node, receiver_type, scope)
+        return false unless def_node.is_a?(Prism::DefNode) && def_node.body
+
+        repeats?(def_node)
+      rescue StandardError
+        false
+      end
+
+      # Issue #2301 — whether the callee hands the block it is called with on to another call (`g(x, &)`,
+      # `g(x, &blk)`), outside a nested `def`. The block-return pass types such a forward's target `yield` as the
+      # caller's block ({ExpressionTyper#forwarded_block_return_type}), and the target may run it any number of
+      # times, so the caller's block is typed as one that may repeat. Answers false where the callee does not resolve.
+      def hands_block_on?(call_node, receiver_type, scope)
+        def_node = callee_def(call_node, receiver_type, scope)
+        return false unless def_node.is_a?(Prism::DefNode) && def_node.body
+
+        hand_off_in?(def_node.body, def_node.parameters&.block&.name)
+      rescue StandardError
+        false
+      end
+
+      def hand_off_in?(node, block_name)
+        return false if node.is_a?(Prism::DefNode)
+        return true if node.is_a?(Prism::BlockArgumentNode) && forwards_block?(node, block_name)
+
+        node.compact_child_nodes.any? { |child| hand_off_in?(child, block_name) }
+      end
+
+      # The `def` an instance call on a project class, a singleton call on one, or an implicit-self call to a
+      # top-level method resolves to.
+      def callee_def(call_node, receiver_type, scope)
+        name = call_node.name
+        found =
+          case receiver_type
+          when Type::Nominal then scope.user_def_through_ancestors(receiver_type.class_name, name).first
+          when Type::Singleton then scope.singleton_def_for(receiver_type.class_name, name)
+          end
+        found || (call_node.receiver.nil? ? scope.top_level_def_for(name) : nil)
+      end
+
+      def repeats?(def_node)
+        block_param = def_node.parameters&.block
+        counter = { sites: 0, repeats: false }
+        walk(def_node.body, block_param&.name, false, counter)
+        counter[:repeats] || counter[:sites] >= 2
+      end
+
+      def walk(node, block_name, repeating, counter)
+        return if counter[:repeats] || node.is_a?(Prism::DefNode)
+
+        skipped = visit(node, block_name, repeating, counter)
+        inner = repeating || REPEATING_NODES.include?(node.class)
+        node.compact_child_nodes.each do |child|
+          walk(child, block_name, inner, counter) unless child.equal?(skipped)
+        end
+      end
+
+      # Counts `node` and answers the child the walk must not visit: the `blk` receiver of a `blk.call`, which is a
+      # run, not a hand-off.
+      def visit(node, block_name, repeating, counter)
+        case node
+        when Prism::YieldNode then run_site(repeating, counter)
+        when Prism::ForwardingArgumentsNode then counter[:repeats] = true
+        when Prism::BlockArgumentNode then counter[:repeats] = true if forwards_block?(node, block_name)
+        when Prism::CallNode
+          return unless block_run_call?(node, block_name)
+
+          run_site(repeating, counter)
+          node.receiver
+        when Prism::LocalVariableReadNode then counter[:repeats] = true if block_name && node.name == block_name
+        end
+      end
+
+      def run_site(repeating, counter)
+        counter[:sites] += 1
+        counter[:repeats] = true if repeating
+      end
+
+      # `blk.call` and its spellings.
+      def block_run_call?(node, block_name)
+        receiver = node.receiver
+        !block_name.nil? && receiver.is_a?(Prism::LocalVariableReadNode) && receiver.name == block_name &&
+          BLOCK_RUN_CALLS.include?(node.name)
+      end
+
+      # `&blk` or an anonymous `&` handed to another call.
+      def forwards_block?(node, block_name)
+        expression = node.expression
+        expression.nil? || (expression.is_a?(Prism::LocalVariableReadNode) && expression.name == block_name)
+      end
+    end
+  end
+end