rigortype 0.2.9 → 0.3.0

data/lib/rigor/inference/budget_trace.rb

@@ -8,6 +8,14 @@ module Rigor
     # docs/type-specification/inference-budgets.md is not yet wired); counting how often each fires on a real
     # project is the only way to see where inference actually stops.
     #
+    # A second family of counters (the `MEMO_*` categories) profiles the ADR-57 user-method return memo
+    # (`ExpressionTyper#infer_user_method_return`) rather than a cutoff — inference entries, memo hits/misses,
+    # the split of non-stored results by reason, and body-evaluation (compute) entries — plus two
+    # per-signature distributions (body-eval count and distinct-memo-key count). This is the evidence for the
+    # next return-memo design slice: a finalization-aware taint gate (recover the `consult-tainted`
+    # 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:
     #
     # - {RECURSION_GUARD} — `ExpressionTyper#infer_user_method_return` detected a `(receiver, method)` cycle
@@ -44,9 +52,42 @@ module Rigor
       # `Dynamic[top]` (the escaping-block floor). Shared by slice B's loop-body fixpoint.
       BLOCK_WRITEBACK_CAP = :block_writeback_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`.
+      # - {MEMO_ENTRIES} — every `infer_user_method_return` entry (a user-method return inference).
+      # - {MEMO_HITS} / {MEMO_MISSES} — the memo was consulted (candidate frame) and the key was present /
+      #   absent. Consults = hits + misses.
+      # - {MEMO_BODY_EVALS} — every `compute_user_method_return` entry (a body-evaluation compute; some are
+      #   in-cycle re-entries that consult an ADR-55 summary rather than walk the body — those coincide with a
+      #   `RECURSION_GUARD` hit). Body evals = misses + on-stack refusals (ADR-84 WD3 reduced candidacy to the
+      #   on-stack check, so unroll-in-flight refusals are structurally gone).
+      # - {MEMO_REFUSE_ON_STACK} — the frame was not a memo candidate (bypassed the memo and computed): its
+      #   plain `(receiver, method)` signature was already on the recursion guard stack.
+      # - {MEMO_REFUSE_UNROLL} — pre-ADR-84 blanket refusal (constant-arg unroll in flight). Kept in the table
+      #   as the ADR-84 WD3 gate pin: structurally unreachable, must read ~0.
+      # - {MEMO_REFUSE_CONSULT_TAINTED} — a candidate frame computed a result but an ADR-55 fixpoint summary
+      #   was *consulted* during the compute, so the result is a transient Kleene iterate and was NOT stored.
+      # - {MEMO_REFUSE_TRANSIENT} — ADR-84 WD3: a candidate frame's compute bracket saw a
+      #   transient-machinery event (recursion-guard hit / unroll-fuel exhaustion / ADR-55 WD1 clamp /
+      #   fixpoint-cap collapse — `ExpressionTyper#note_transient_fallback`) that referenced a stack frame
+      #   BELOW the bracket's entry depth, so the ancestor context influenced the result and it was NOT
+      #   stored. Own-machinery events (a recursive method's own fixpoint) do not refuse; top-of-stack
+      #   computes are standalone by construction. Replaces the blanket unroll-in-flight exclusion.
+      MEMO_ENTRIES = :memo_entries
+      MEMO_HITS = :memo_hits
+      MEMO_MISSES = :memo_misses
+      MEMO_BODY_EVALS = :memo_body_evals
+      MEMO_REFUSE_ON_STACK = :memo_refuse_on_stack
+      MEMO_REFUSE_UNROLL = :memo_refuse_unroll
+      MEMO_REFUSE_CONSULT_TAINTED = :memo_refuse_consult_tainted
+      MEMO_REFUSE_TRANSIENT = :memo_refuse_transient
+
       CATEGORIES = [
         RECURSION_GUARD, ANCESTOR_WALK_LIMIT, HKT_FUEL_EXHAUSTED, RECURSION_UNROLL_FUEL,
-        RECURSION_FIXPOINT_CAP, BLOCK_WRITEBACK_CAP
+        RECURSION_FIXPOINT_CAP, BLOCK_WRITEBACK_CAP,
+        MEMO_ENTRIES, MEMO_HITS, MEMO_MISSES, MEMO_BODY_EVALS,
+        MEMO_REFUSE_ON_STACK, MEMO_REFUSE_UNROLL, MEMO_REFUSE_CONSULT_TAINTED,
+        MEMO_REFUSE_TRANSIENT
       ].freeze
 
       # Distribution (histogram) categories — read-only observations of a value's size at a site, used to
@@ -55,12 +96,28 @@ module Rigor
       # `Combinator.union` produces — the distribution the `union_size` budget default should be set from.
       UNION_ARITY = :union_arity
 
-      DISTRIBUTION_CATEGORIES = [UNION_ARITY].freeze
+      # ADR-57 return-memo per-signature distributions — `{signature => count}` maps, NOT integer-size
+      # histograms, so `summarize` (percentiles over integer values) does not apply; read them with
+      # {distribution}. Both keyed by the `"Receiver#method"` plain signature.
+      # - {MEMO_BODY_EVAL_BY_SIGNATURE} — body-eval (compute) count per signature (via {observe}).
+      # - {MEMO_DISTINCT_KEY_BY_SIGNATURE} — distinct memo keys per signature (via {observe_distinct}), i.e.
+      #   how many `(receiver, arg-type)` variants a signature was memoised under. A count far above the
+      #   signature's body-eval savings is arg-granularity thrash — the key-normalization candidate.
+      MEMO_BODY_EVAL_BY_SIGNATURE = :memo_body_eval_by_signature
+      MEMO_DISTINCT_KEY_BY_SIGNATURE = :memo_distinct_key_by_signature
+
+      DISTRIBUTION_CATEGORIES = [
+        UNION_ARITY, MEMO_BODY_EVAL_BY_SIGNATURE, MEMO_DISTINCT_KEY_BY_SIGNATURE
+      ].freeze
 
       @enabled = !ENV["RIGOR_BUDGET_TRACE"].to_s.empty?
       @mutex = Mutex.new
       @counts = Hash.new(0)
       @distributions = Hash.new { |h, k| h[k] = Hash.new(0) }
+      # Auxiliary de-duplication state for {observe_distinct}: category → Set of the `[bucket, member]`
+      # pairs already counted, so a repeated `(signature, memo-key)` observation is counted once. Only ever
+      # written when tracing is enabled; not part of the reported surface.
+      @distinct_seen = Hash.new { |h, k| h[k] = Set.new }
 
       module_function
 
@@ -101,6 +158,23 @@ module Rigor
         @mutex.synchronize { @distributions[category][value] += 1 }
       end
 
+      # Records one observation of `member` into `category`'s `{bucket => count}` map, but only the FIRST time
+      # a given `(bucket, member)` pair is seen — so the resulting count per bucket is the number of DISTINCT
+      # members, not the number of observations. Used for the distinct-memo-key-per-signature distribution.
+      # No-op (one boolean check) when disabled.
+      def observe_distinct(category, bucket, member)
+        return unless @enabled
+
+        @mutex.synchronize do
+          seen = @distinct_seen[category]
+          pair = [bucket, member]
+          unless seen.include?(pair)
+            seen << pair
+            @distributions[category][bucket] += 1
+          end
+        end
+      end
+
       # Frozen `{value => count}` histogram for a distribution category.
       def distribution(category)
         @mutex.synchronize { @distributions[category].dup.freeze }
@@ -137,6 +211,7 @@ module Rigor
         @mutex.synchronize do
           @counts.clear
           @distributions.clear
+          @distinct_seen.clear
         end
       end
     end

data/lib/rigor/inference/closure_escape_analyzer.rb

@@ -144,6 +144,16 @@ module Rigor
       RANGE_EXTRA = %i[step].freeze
       INTEGER_EXTRA = %i[times upto downto].freeze
 
+      # IO / File / StringIO line- and byte-iteration methods invoke the block immediately, once per line /
+      # byte / char, and never retain it — the same immediate-invocation contract as `Array#each`. Both the
+      # singleton `File.foreach` / `IO.foreach` (receiver `singleton(File)` → class name "File") and the
+      # instance `io.each_line` / `each_char` … forms resolve through the same class-name key. Without these,
+      # `File.foreach(path) { case … when … then flag = true when … then return true if flag end }` classifies
+      # `:unknown` and misses the loop-body re-narrowing, so a local written in one `when` arm reads its
+      # pre-loop value in a sibling arm and a guarding condition folds to a spurious constant.
+      IO_ITERATION = %i[each_line each each_byte each_char each_codepoint].freeze
+      IO_SINGLETON_ITERATION = %i[foreach].freeze
+
       NON_ESCAPING = {
         "Array" => (ENUMERABLE_NON_ESCAPING + ARRAY_EXTRA).freeze,
         "Hash" => (ENUMERABLE_NON_ESCAPING + HASH_EXTRA).freeze,
@@ -151,7 +161,10 @@ module Rigor
         "Set" => ENUMERABLE_NON_ESCAPING,
         "Integer" => INTEGER_EXTRA,
         "Enumerator" => ENUMERABLE_NON_ESCAPING,
-        "Enumerator::Lazy" => ENUMERABLE_NON_ESCAPING
+        "Enumerator::Lazy" => ENUMERABLE_NON_ESCAPING,
+        "IO" => (IO_ITERATION + IO_SINGLETON_ITERATION).freeze,
+        "File" => (IO_ITERATION + IO_SINGLETON_ITERATION).freeze,
+        "StringIO" => IO_ITERATION
       }.freeze
 
       # Methods that are documented to **retain** the block past the call. The block is stored or scheduled,

data/lib/rigor/inference/def_handle.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Inference
+    # ADR-85 WD3 — a lazy reference to a `Prism::DefNode` stored in a cross-file discovery table, in place of
+    # the live node itself. When an incremental recheck rebuilds the discovery index from cached per-file seed
+    # bundles (ADR-85 WD2), the `def_nodes` / `singleton_def_nodes` tables carry handles for every unchanged
+    # file's methods: the file was never parsed this run, so there is no live node to store. A handle records
+    # the three things needed to resolve or fingerprint it without the node:
+    #
+    # - `path` + `node_id` — the resolution key. The per-run parse memo ({Scope#resolve_def_handle}) parses the
+    #   file once and returns the `Prism::DefNode` whose `node_id` matches (Prism `node_id` is stable across
+    #   repeated parses of identical bytes). `name` is the cross-check: a resolved node whose `name` differs
+    #   from the handle's forces a fresh walk (bundle/source skew that the digest gate should make impossible —
+    #   conservative, never silent).
+    # - `fingerprint` — the SHA-256 of the def's source slice, captured when the bundle was built. This lets
+    #   `Runner#symbol_fingerprints` read the change-detection fingerprint (ADR-46 slice 4) off the handle
+    #   without re-parsing the file — the one value-deref consumer besides the three accessor choke points.
+    #
+    # Marshal-clean by construction (Integer + Strings), so it rides the `IncrementalSnapshot` blob directly.
+    DefHandle = Data.define(:path, :node_id, :name, :fingerprint)
+  end
+end

data/lib/rigor/inference/def_node_resolver.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "prism"
+require_relative "def_handle"
+require_relative "../source/node_children"
+
+module Rigor
+  module Inference
+    # ADR-85 WD3 — resolves a {DefHandle} (stored in a bundle-rebuilt discovery table) to a live
+    # `Prism::DefNode`, through a per-run parse memo that yields ONE stable node object per `(path, node_id)`
+    # per run. Identity stability is a correctness constraint, not an optimisation: the ADR-84 return memo keys
+    # on the resolved def-node's object identity, so a fresh parse per resolution would mint a new identity
+    # each time and fragment that memo. The memo parses each demanded file at most once (recon Q5: an
+    # incremental recheck demands 0–6 files' bodies), builds a `node_id → DefNode` index over its DefNodes, and
+    # returns the same object on every later lookup.
+    #
+    # `node_id` is the primary key; `name` is a cross-check. A miss (the node_id is absent, or its node's name
+    # differs — a bundle/source skew the digest gate should make impossible, since identical bytes under the
+    # same Prism yield identical node_ids) falls back to the first same-named DefNode in a fresh walk of the
+    # file, and finally nil — conservative (the accessor then reports no user def, losing precision but never
+    # firing a wrong diagnostic), never silent.
+    #
+    # The memo is a thread-local installed for the duration of a run (the {Cache::FileDigest} pattern:
+    # process-local, Ractor-safe, never crosses a fork boundary, reset per run). Outside a run scope every
+    # resolution parses directly — a correct if un-memoised fallback for runner-less probes.
+    module DefNodeResolver
+      MEMO_KEY = :rigor_def_node_resolver_memo
+      private_constant :MEMO_KEY
+
+      # Installs a fresh per-run resolution memo, restoring the previous one on exit (always, even on a raise).
+      # `nodes` caches the resolved node per `(path, node_id)`; `indexes` caches each file's parse index.
+      def self.with_run
+        previous = Thread.current[MEMO_KEY]
+        Thread.current[MEMO_KEY] = { nodes: {}, indexes: {} }
+        yield
+      ensure
+        Thread.current[MEMO_KEY] = previous
+      end
+
+      # Resolves `handle` to a `Prism::DefNode` (the same object across the run for a given (path, node_id)), or
+      # nil. A non-handle argument is returned unchanged, so callers can pass a table value that is either a live
+      # node (cold / re-walked file) or a handle (unchanged file) without branching.
+      def self.resolve(handle)
+        return handle unless handle.is_a?(DefHandle)
+
+        memo = Thread.current[MEMO_KEY]
+        return locate(handle, {}) if memo.nil?
+
+        key = [handle.path, handle.node_id].freeze
+        nodes = memo[:nodes]
+        return nodes[key] if nodes.key?(key)
+
+        nodes[key] = locate(handle, memo[:indexes])
+      end
+
+      # Finds the node for `handle` using a per-file `{node_id => DefNode}` + `{name => DefNode}` index cache.
+      def self.locate(handle, index_cache)
+        index = index_cache[handle.path] ||= build_file_index(handle.path)
+        node = index[:by_id][handle.node_id]
+        return node if node && node.name.to_s == handle.name
+
+        index[:by_name][handle.name]
+      rescue StandardError
+        nil
+      end
+      private_class_method :locate
+
+      def self.build_file_index(path)
+        root = Prism.parse(File.read(path)).value
+        by_id = {}
+        by_name = {}
+        collect_def_nodes(root, by_id, by_name)
+        { by_id: by_id, by_name: by_name }
+      end
+      private_class_method :build_file_index
+
+      # Walks the tree once, indexing every DefNode by node_id (primary) and by name (first-wins fallback).
+      def self.collect_def_nodes(node, by_id, by_name)
+        return unless node.is_a?(Prism::Node)
+
+        if node.is_a?(Prism::DefNode)
+          by_id[node.node_id] = node
+          by_name[node.name.to_s] ||= node
+        end
+        node.rigor_each_child { |child| collect_def_nodes(child, by_id, by_name) }
+      end
+      private_class_method :collect_def_nodes
+    end
+  end
+end

data/lib/rigor/inference/def_return_typer.rb

@@ -3,6 +3,7 @@
 require "prism"
 
 require_relative "../type"
+require_relative "../source/node_children"
 
 module Rigor
   module Inference
@@ -62,7 +63,7 @@ module Rigor
         return if RETURN_BARRIER_NODES.any? { |klass| node.is_a?(klass) }
 
         type_return_node(node, scope_index, out) if node.is_a?(Prism::ReturnNode)
-        node.compact_child_nodes.each { |c| collect_return_types(c, scope_index, out) }
+        node.rigor_each_child { |c| collect_return_types(c, scope_index, out) }
       end
 
       def type_return_node(return_node, scope_index, out)