rigortype 0.4.6 → 0.4.7

data/lib/rigor/inference/block_run_count.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "block_call_timing"
+require_relative "closure_escape_analyzer"
+require_relative "project_method_ownership"
+
+module Rigor
+  module Inference
+    # Issue #2303 — whether a project method's body may run the block it is called with more than once ON ONE PATH,
+    # for the expression-position block-value pass (`ExpressionTyper#block_may_repeat?` through
+    # {ProjectYielder.block_value_may_repeat?}). That pass lays the #587 (b) captured binding under a repeating block,
+    # which adds values a single run never reads, so a callee read as repeating when it is not reports diagnostics on
+    # correct code (`s = "a"; r = either(f) { t = s; s = nil; t }; r.upcase`). The rule here therefore errs toward
+    # "runs once", unlike {ProjectYielder.may_run_block_repeatedly?}, whose only asker widens a return type.
+    #
+    # The walk counts block runs per path, saturating at {MANY}:
+    #
+    # - a `yield`, or `call` / `yield` / `===` / `[]` on the `&blk` parameter, is one run;
+    # - a sequence sums, and a branch (`if` / `unless` / ternary / `case` / `case ... in`) takes the largest arm,
+    #   so `f ? yield(1) : yield(2)` is one run;
+    # - a `return`, `break`, `next` or receiver-less `raise` / `fail` ends its path, so the `yield` after
+    #   `return yield(1) if k` is a different path from the one before it;
+    # - the body of `while` / `until` / `for`, of `Kernel#loop`, or the block of a catalogued core iterator
+    #   ({ClosureEscapeAnalyzer.iterator_name?}) is {MANY} when a run lies on a path that reaches the next
+    #   iteration (falling through the body, or a `next`); a run only on a path that leaves it (`return`, `break`,
+    #   `raise`) adds what that path holds, so `xs.each { |x| return yield(x) if x > 1 }` is one run;
+    # - a hand-off of the block (`g(&blk)`, `g(&)`, `...`) is {MANY};
+    # - a block under any other call runs its body once (`then { yield }`, `synchronize { yield }`,
+    #   `File.open(f) { yield f }`), a lambda body is not run at its definition, and a nested `def` is not this
+    #   method's body.
+    #
+    # Reading `&blk` other than calling it (`return unless blk`) is no run.
+    #
+    # A result is `[fall, total, nxt, brk]`: the most runs on a path that falls through the node, on any path
+    # through it, on a path that ends at a `next`, and on one that ends at a `break` (nil where no path does).
+    module BlockRunCount
+      module_function
+
+      MANY = 2
+      ZERO = [0, 0, nil, nil].freeze
+      ALWAYS = [MANY, MANY, nil, nil].freeze
+      BLOCK_RUN_CALLS = Set[:call, :yield, :===, :[]].freeze
+      LOOP_NODES = [Prism::WhileNode, Prism::UntilNode, Prism::ForNode].freeze
+      RAISING_CALLS = Set[:raise, :fail].freeze
+      private_constant :ZERO, :ALWAYS, :BLOCK_RUN_CALLS, :LOOP_NODES, :RAISING_CALLS
+
+      # Memoised per `def` node for the run ({ProjectMethodOwnership.memo}): every call site, and every pass over
+      # one, asks the same callee.
+      def may_repeat?(def_node, scope)
+        memo = ProjectMethodOwnership.memo(scope)[:block_runs]
+        return memo[def_node] if memo.key?(def_node)
+
+        memo[def_node] = runs(def_node.body, def_node.parameters&.block&.name)[1] >= MANY
+      end
+
+      def runs(node, block_name)
+        case node
+        when nil, Prism::DefNode, Prism::LambdaNode then ZERO
+        when Prism::YieldNode then run_after(sequence(node.compact_child_nodes, block_name))
+        when Prism::ForwardingArgumentsNode then ALWAYS
+        when Prism::BlockArgumentNode then block_argument_runs(node, block_name)
+        when Prism::IfNode then branch(runs(node.predicate, block_name), [node.statements, node.subsequent], block_name)
+        when Prism::UnlessNode
+          branch(runs(node.predicate, block_name), [node.statements, node.else_clause], block_name)
+        when Prism::CaseNode, Prism::CaseMatchNode then case_runs(node, block_name)
+        when Prism::CallNode then call_runs(node, block_name)
+        else other_runs(node, block_name)
+        end
+      end
+
+      def other_runs(node, block_name)
+        result = sequence(node.compact_child_nodes, block_name)
+        case node
+        when *LOOP_NODES then iterated(result)
+        when Prism::ReturnNode then [nil, result[1], result[2], result[3]]
+        when Prism::NextNode then [nil, result[1], larger(result[2], result[0]), result[3]]
+        when Prism::BreakNode then [nil, result[1], result[2], larger(result[3], result[0])]
+        else result
+        end
+      end
+
+      # A body run any number of times: {MANY} when a run reaches the next iteration, else the runs of the paths
+      # that leave it. It may run zero times or be left by a `break`, and the walk continues after it either way.
+      def iterated((fall, total, nxt, brk))
+        again = [fall, nxt].compact.max || 0
+        return ALWAYS if again.positive?
+
+        [[0, brk].compact.max, total, nil, nil]
+      end
+
+      # A body run once: a `next` or `break` in it ends the run, and the walk continues after the call.
+      def run_once((fall, total, nxt, brk))
+        [[fall, nxt, brk].compact.max, total, nil, nil]
+      end
+
+      def block_argument_runs(node, block_name)
+        expression = node.expression
+        forwards = expression.nil? || (expression.is_a?(Prism::LocalVariableReadNode) && expression.name == block_name)
+        forwards ? ALWAYS : runs(expression, block_name)
+      end
+
+      def sequence(nodes, block_name)
+        nodes.reduce(ZERO) do |acc, child|
+          break acc if acc[0].nil?
+
+          chain(acc, runs(child, block_name))
+        end
+      end
+
+      # `first` then `second`; nothing follows a path that does not fall through `first`.
+      def chain(first, second)
+        fall, total, nxt, brk = first
+        return first if fall.nil?
+
+        [second[0] && sum(fall, second[0]), [total, sum(fall, second[1])].max,
+         larger(nxt, second[2] && sum(fall, second[2])), larger(brk, second[3] && sum(fall, second[3]))]
+      end
+
+      def run_after(result)
+        chain(result, [1, 1, nil, nil])
+      end
+
+      # `head` runs first, then exactly one of `arms` (a nil arm is the path that takes none).
+      def branch(head, arms, block_name)
+        return head if head[0].nil?
+
+        arms.map { |arm| chain(head, runs(arm, block_name)) }.reduce do |a, b|
+          [larger(a[0], b[0]), [a[1], b[1]].max, larger(a[2], b[2]), larger(a[3], b[3])]
+        end
+      end
+
+      def case_runs(node, block_name)
+        clauses = node.conditions
+        tests = clauses.flat_map { |clause| clause.is_a?(Prism::WhenNode) ? clause.conditions : [clause.pattern] }
+        arms = clauses.map(&:statements) + [node.else_clause]
+        branch(sequence([node.predicate, *tests], block_name), arms, block_name)
+      end
+
+      def call_runs(node, block_name)
+        return run_after(runs(node.arguments, block_name)) if block_run_call?(node, block_name)
+
+        block = node.block
+        literal = block.is_a?(Prism::BlockNode)
+        head = sequence([node.receiver, node.arguments, (block unless literal)], block_name)
+        return [nil, head[1], head[2], head[3]] if raising_call?(node)
+        return head unless literal
+
+        body = runs(block.body, block_name)
+        chain(head, repeating_call?(node) ? iterated(body) : run_once(body))
+      end
+
+      def sum(left, right)
+        (left + right).clamp(0, MANY)
+      end
+
+      def larger(left, right)
+        [left, right].compact.max
+      end
+
+      def repeating_call?(node)
+        ClosureEscapeAnalyzer.iterator_name?(node.name) || BlockCallTiming.kernel_loop?(node)
+      end
+
+      def raising_call?(node)
+        node.receiver.nil? && RAISING_CALLS.include?(node.name)
+      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
+    end
+  end
+end

data/lib/rigor/inference/budget_trace.rb

@@ -16,7 +16,7 @@ module Rigor
     # non-stores) vs memo-key normalization (collapse arg-granularity thrash — a signature whose distinct-key
     # count far exceeds its body-eval savings).
     #
-    # Three categories, one per guard site:
+    # The cutoff categories, one per guard site:
     #
     # - {RECURSION_GUARD} — `ExpressionTyper#infer_user_method_return` detected a `(receiver, method)` cycle
     #   and returned `Dynamic[top]` (the de-facto recursion-depth budget, effective depth 1).
@@ -27,6 +27,8 @@ module Rigor
     #   fuel and fell back to the plain `(receiver, method)` guard (in-cycle call → `Dynamic[top]`).
     # - {RECURSION_FIXPOINT_CAP} — the fixpoint return-summary iteration (ADR-55 slice 2) hit its 3-evaluation
     #   cap without converging and collapsed the summary to `untyped` (today's behaviour).
+    # - {BLOCK_WRITEBACK_CAP} — the block / loop write-back fixpoint ({BodyFixpoint.converge}) collapsed a
+    #   local that had not converged to `Dynamic[top]`.
     #
     # Enabled only when `RIGOR_BUDGET_TRACE` is set (to any non-empty value) in the environment, or via
     # {enable!} in tests. When disabled, {hit} is a single boolean check and returns immediately, so normal
@@ -52,6 +54,10 @@ module Rigor
       # `Dynamic[top]` (the escaping-block floor). Shared by slice B's loop-body fixpoint and by slice C's
       # content-evidence fixpoint, where the collapsed name is one element / key / value slot of a collection join.
       BLOCK_WRITEBACK_CAP = :block_writeback_cap
+      # `CalleeMutationChain` discovered more than {CalleeMutationChain::MAX_NODES} nodes from one parameter and took
+      # the rest as mutating (the callee floor's FP-safe cut). A label: it may vary with the order, the floor does not
+      # (ADR-127).
+      CALLEE_CHAIN_CAP = :callee_chain_cap
 
       # ADR-57 return-memo profile counters (not cutoffs — see the module doc). All bumped by
       # `ExpressionTyper#infer_user_method_return` / `#compute_user_method_return`.
@@ -82,7 +88,7 @@ module Rigor
 
       CATEGORIES = [
         RECURSION_GUARD, ANCESTOR_WALK_LIMIT, HKT_FUEL_EXHAUSTED, RECURSION_UNROLL_FUEL,
-        RECURSION_FIXPOINT_CAP, BLOCK_WRITEBACK_CAP,
+        RECURSION_FIXPOINT_CAP, BLOCK_WRITEBACK_CAP, CALLEE_CHAIN_CAP,
         MEMO_ENTRIES, MEMO_HITS, MEMO_MISSES, MEMO_BODY_EVALS,
         MEMO_REFUSE_ON_STACK, MEMO_REFUSE_UNROLL, MEMO_REFUSE_TRANSIENT
       ].freeze

data/lib/rigor/inference/builtins/exception_catalog.rb

@@ -9,8 +9,8 @@ module Rigor
       #
       # Exception is the base of every Ruby error class (RuntimeError, StandardError, KeyError, …). The
       # Init_Exception block in `references/ruby/error.c` registers the entire hierarchy in one pass, so
-      # the YAML carries 27 classes — but only the base `Exception` row is wired into `CATALOG_BY_CLASS`
-      # for v0.0.5. A `RuntimeError` receiver hits the Exception arm via `is_a?(Exception)` and the
+      # the YAML carries 27 classes — but only the base `Exception` row is wired into `CATALOG_BY_CLASS`.
+      # A `RuntimeError` receiver hits the Exception arm via `is_a?(Exception)` and the
       # catalog answers with the base-class entries; subclass-specific methods (`KeyError#receiver`,
       # `NameError#name`, …) intentionally miss the lookup until a later slice routes per-subclass
       # class_names.

data/lib/rigor/inference/builtins/numeric_catalog.rb

@@ -16,11 +16,8 @@ module Rigor
       #
       # No mutation blocklist is needed. The numeric classes expose no foldable bang or indirect-mutator
       # method that the static C classifier mis-attributes (every `:leaf` numeric method is a pure value
-      # computation), so the generic `MethodCatalog` loader — shared with the eighteen other per-class
-      # catalogs — covers it directly. This previously hand-rolled its own `safe_for_folding?` /
-      # `method_entry` / `load_catalog` copy of `MethodCatalog`; folding it onto the shared loader also
-      # picks up alias resolution (e.g. `Integer#magnitude` → `abs`, `Integer#inspect` → `to_s`), which the
-      # old bespoke loader silently dropped.
+      # computation), so the generic `MethodCatalog` loader covers it directly. Using the shared loader
+      # rather than a bespoke copy also gives it alias resolution (e.g. `Integer#magnitude` → `abs`).
       NUMERIC_CATALOG = MethodCatalog.for_topic("numeric")
     end
   end

data/lib/rigor/inference/builtins/random_catalog.rb

@@ -20,8 +20,8 @@ module Rigor
         mutating_selectors: {
           "Random" => Set[
             # `rand_random` -> `random_real` / `random_ulong_limited` advance the MT state on the receiver
-            # (instance #rand) and on `Random::DEFAULT` (singleton .rand). The classifier misses the
-            # indirect mutator.
+            # (instance #rand) and on the process-wide default generator (singleton .rand). The classifier
+            # misses the indirect mutator.
             :rand,
             # `random_bytes` / `random_s_bytes` consume MT output the same way #rand does — every call
             # mutates the underlying generator.

data/lib/rigor/inference/callee_mutation_chain.rb

@@ -8,107 +8,118 @@ module Rigor
     #
     # 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.
+    # {Edge}s along which a def hands one of its parameters to a resolved callee. A node is one parameter of one def
+    # under one owner context, 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.
     #
-    # 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.
+    # ADR-127 — the answer is a property of that graph, not of a walk. A parameter `r` is mutated iff an own-mutated
+    # node is reachable from `r` through nodes that are not themselves own-mutated, or more than {MAX_NODES} distinct
+    # nodes are reachable from `r` (a cut: the walk did not see them, and a literal shape kept on evidence it never saw
+    # reports a false positive on correct code). Nothing a walk concludes is kept, so what one walk did cannot change
+    # another's answer; only graph facts are persisted (the successor `store`). Which label an answer carries (an
+    # exact one, or a cut and its {BudgetTrace::CALLEE_CHAIN_CAP} hit) may vary with the order, the floor does not.
     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)
+      # the callee's parameters it may bind there. Issue #2515 — `owner` is the evaluator the callee's own census and
+      # hand-offs resolve in when the hand-off crosses classes (`Help.c(p, o)`, `Helper.new.c(p, o)`), nil for a
+      # self-call, which stays in the evaluator the hop started in. `approx` is true when the hand-off resolved to more
+      # than one candidate, or by name; the floor it implies is an over-approximation, not proof the callee writes.
+      Edge = Data.define(:name, :slot, :callee, :callee_names, :owner, :approx) do
+        def initialize(name:, slot:, callee:, callee_names:, owner: nil, approx: false) = super
+      end
+
+      # ADR-127 — the most distinct nodes one parameter may reach before the walk is cut and reads as mutated.
+      MAX_NODES = 64
 
-      MAX_NODES = 32
+      NO_TRIPLES = [].freeze
+      private_constant :NO_TRIPLES
 
       module_function
 
-      def close(root, own:, edges:)
-        census = own.call(root)
-        handed = edges.call(root).reject { |edge| census.key?(edge.name) }
+      # `own` and `edges` take the def and the owner evaluator its hop resolves in (nil: the closure's own). `store`
+      # (nil: none) is the run's successor store, `{ def => { owner_key => { name => triples } } }`, and `ctx` the key
+      # the nil owner is stored under (the side and class the closure runs in).
+      def close(root, own:, edges:, store: nil, ctx: nil)
+        census = own.call(root, nil)
+        handed = edges.call(root, nil)
         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)
+        result = nil
+        handed.each do |edge|
+          name = edge.name
+          next if census.key?(name) || result&.key?(name)
+          next unless reaches_mutation?(root, name, own, edges, store, ctx)
 
-        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
+          (result ||= census.dup)[name] = edge.slot
         end
+        result || census
+      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
+      # Breadth first from `root`'s `name`, over a walk-local `seen`. A node counts when it is first discovered and its
+      # own mutation is checked then, so more than {MAX_NODES} discovered nodes is decided without computing the
+      # frontier's edges. The first own-mutated node proves the parameter mutated; it is reachable through nodes that
+      # are not own-mutated by construction, since those are the only ones expanded.
+      def reaches_mutation?(root, name, own, edges, store, ctx)
+        seen = {}.compare_by_identity
+        mark(seen, root, name, nil)
+        queue = [root, name, nil]
+        discovered = 1
+        i = 0
+        while i < queue.size
+          triples = successors(queue[i], queue[i + 1], queue[i + 2], edges, store, ctx)
+          i += 3
+          j = 0
+          while j < triples.size
+            callee = triples[j]
+            callee_name = triples[j + 1]
+            owner = triples[j + 2]
+            j += 3
+            next unless mark(seen, callee, callee_name, owner)
+
+            discovered += 1
+            if discovered > MAX_NODES
+              BudgetTrace.hit(BudgetTrace::CALLEE_CHAIN_CAP)
+              return true
+            end
+            return true if own.call(callee, owner).key?(callee_name)
 
-            queue.concat(add(current, parameter))
+            queue.push(callee, callee_name, owner)
           end
         end
+        false
+      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
+      # True when the node was not yet in the walk-local `seen`, which now holds it.
+      def mark(seen, def_node, name, owner)
+        by_name = ((seen[def_node] ||= {})[owner] ||= {})
+        return false if by_name.key?(name)
 
-        private
+        by_name[name] = true
+      end
 
-        def known?(def_node, name)
-          by_name = @nodes[def_node]
-          !by_name.nil? && by_name.key?(name)
-        end
+      # The flat `[callee, name, owner, ...]` triples the node `(def_node, name, owner)` hands itself to: a graph fact,
+      # persisted in `store` when there is one. A node its def mutates is never asked.
+      def successors(def_node, name, owner, edges, store, ctx)
+        return compute_successors(def_node, name, owner, edges) if store.nil?
 
-        # 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
+        by_name = ((store[def_node] ||= {})[owner.nil? ? ctx : owner] ||= {})
+        if by_name.key?(name)
+          return MemoAudit.check("successor", by_name[name], name, owner) do
+            compute_successors(def_node, name, owner, edges)
+          end
         end
 
-        def successors_of(def_node, name)
-          @edges.call(def_node).each_with_object([]) do |edge, successors|
-            next unless edge.name == name
+        by_name[name] = compute_successors(def_node, name, owner, edges)
+      end
 
-            edge.callee_names.each { |callee_name| successors << [edge.callee, callee_name] }
-          end
-        end
+      def compute_successors(def_node, name, owner, edges)
+        triples = nil
+        edges.call(def_node, owner).each do |edge|
+          next unless edge.name == name
 
-        def each_node(&)
-          @nodes.each_value { |by_name| by_name.each_value(&) }
+          edge.callee_names.each { |callee_name| (triples ||= []).push(edge.callee, callee_name, edge.owner || owner) }
         end
+        triples.nil? ? NO_TRIPLES : triples.freeze
       end
     end
   end