rigortype 0.2.7 → 0.2.8

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

@@ -7,60 +7,44 @@ module Rigor
     module Builtins
       # `Time` catalog. Singleton — load once, consult during dispatch.
       #
-      # Time is a pure-C built-in: the Init block in
-      # `references/ruby/time.c` registers the bulk of the surface,
-      # and the Ruby-side prelude `references/ruby/timev.rb`
-      # contributes the class-side constructors (`Time.now`,
-      # `Time.at`, `Time.new`) through Primitive cexpr stubs.
+      # Time is a pure-C built-in: the Init block in `references/ruby/time.c` registers the bulk of the
+      # surface, and the Ruby-side prelude `references/ruby/timev.rb` contributes the class-side
+      # constructors (`Time.now`, `Time.at`, `Time.new`) through Primitive cexpr stubs.
       #
-      # Time receivers are not lifted to a `Constant` carrier today
-      # (there is no `Time` literal node — the closest is
-      # `Time.now` / `Time.new(...)`, which produce `Nominal[Time]`).
-      # The catalog wiring therefore mostly governs:
+      # Time receivers are not lifted to a `Constant` carrier today (there is no `Time` literal node — the
+      # closest is `Time.now` / `Time.new(...)`, which produce `Nominal[Time]`). The catalog wiring
+      # therefore mostly governs:
       #
-      # 1. The size-projection-equivalent reader surface (`#year`,
-      #    `#month`, `#hour`, `#sec`, `#wday`, …) — RBS-declared
-      #    `Integer` is preserved through dispatch.
-      # 2. The blocklist below, which keeps the indirect-mutator
-      #    methods that the C-body classifier mis-flagged as
-      #    `:leaf` from ever folding through a hypothetical future
-      #    `Constant<Time>` carrier.
+      # 1. The size-projection-equivalent reader surface (`#year`, `#month`, `#hour`, `#sec`, `#wday`, …)
+      #    — RBS-declared `Integer` is preserved through dispatch.
+      # 2. The blocklist below, which keeps the indirect-mutator methods that the C-body classifier
+      #    mis-flagged as `:leaf` from ever folding through a hypothetical future `Constant<Time>`
+      #    carrier.
       #
-      # The blocklist captures the false-positive `:leaf` entries
-      # whose helper functions the regex classifier did not
-      # recognise as mutators.
+      # The blocklist captures the false-positive `:leaf` entries whose helper functions the regex
+      # classifier did not recognise as mutators.
       TIME_CATALOG = MethodCatalog.for_topic(
         "time",
         mutating_selectors: {
           "Time" => Set[
-            # `time_init_copy` writes the `timew` and `vtm` slots on
-            # the receiver via `time_set_timew` / `time_set_vtm`.
-            # Classed `:leaf` because those setters are not in the
-            # mutator regex's helper list. Blocked for symmetry with
-            # String / Array / Range / Set initialize_copy entries.
+            # `time_init_copy` writes the `timew` and `vtm` slots on the receiver via `time_set_timew` /
+            # `time_set_vtm`. Classed `:leaf` because those setters are not in the mutator regex's helper
+            # list. Blocked for symmetry with String / Array / Range / Set initialize_copy entries.
             :initialize_copy,
-            # `time_localtime_m` -> `time_localtime` calls
-            # `time_modify(time)` to mark the receiver mutable
-            # before rewriting its `vtm` cache and `tzmode`. The
-            # docstring is explicit ("converts time to local time
-            # in place"). The C-body classifier mis-flagged it as
-            # `:leaf` because `time_modify` is not in its mutator
-            # regex.
+            # `time_localtime_m` -> `time_localtime` calls `time_modify(time)` to mark the receiver
+            # mutable before rewriting its `vtm` cache and `tzmode`. The docstring is explicit ("converts
+            # time to local time in place"). The C-body classifier mis-flagged it as `:leaf` because
+            # `time_modify` is not in its mutator regex.
             :localtime,
-            # `time_gmtime` (registered as both `gmtime` and `utc`
-            # against `rb_cTime`) follows the same in-place pattern
-            # as `time_localtime`: `time_modify(time)` then a
-            # `time_set_vtm` write and `TZMODE_SET_UTC`. Both
-            # selectors share the cfunc, so both must be blocked.
+            # `time_gmtime` (registered as both `gmtime` and `utc` against `rb_cTime`) follows the same
+            # in-place pattern as `time_localtime`: `time_modify(time)` then a `time_set_vtm` write and
+            # `TZMODE_SET_UTC`. Both selectors share the cfunc, so both must be blocked.
             :gmtime, :utc,
-            # `getlocal` is not a mutator — it returns a fresh Time —
-            # but the fresh Time is pinned to the *analysis machine's*
-            # timezone. Folding it through a `Constant[Time]` carrier
-            # (which only ever holds a UTC literal from `Time.utc`)
-            # would bake a host-dependent wall clock / `utc_offset`
-            # into the inferred type. Blocked so the fold stays
-            # machine-independent; the RBS tier answers `Nominal[Time]`.
-            # `getutc` / `getgm` stay foldable — their result is UTC.
+            # `getlocal` is not a mutator — it returns a fresh Time — but the fresh Time is pinned to the
+            # *analysis machine's* timezone. Folding it through a `Constant[Time]` carrier (which only
+            # ever holds a UTC literal from `Time.utc`) would bake a host-dependent wall clock /
+            # `utc_offset` into the inferred type. Blocked so the fold stays machine-independent; the RBS
+            # tier answers `Nominal[Time]`. `getutc` / `getgm` stay foldable — their result is UTC.
             :getlocal
           ]
         }

data/lib/rigor/inference/closure_escape_analyzer.rb

@@ -6,73 +6,55 @@ module Rigor
   module Inference
     # Slice 6 phase C sub-phase 3a — closure-escape classification.
     #
-    # Given a `(receiver_type, method_name)` pair representing a
-    # block-accepting call, this analyzer answers one question:
-    # does the receiver's method invoke its block **immediately and
-    # synchronously**, without retaining the block past the call?
+    # Given a `(receiver_type, method_name)` pair representing a block-accepting call, this analyzer answers
+    # one question: does the receiver's method invoke its block **immediately and synchronously**, without
+    # retaining the block past the call?
     #
     # The answer is one of three outcomes:
     #
-    # - `:non_escaping` — the block is proven to be invoked
-    #   immediately, zero or more times, and is NOT retained past
-    #   the call. The receiver does not store the block in an
-    #   instance variable, return it as a value, or schedule it for
-    #   later invocation. Outer-local narrowing facts that survive
-    #   the block body MAY safely survive the call.
-    # - `:escaping` — the block is proven to be retained past the
-    #   call (stored, returned, or invoked asynchronously). Outer
-    #   narrowing facts on locals the block can rebind MUST be
-    #   dropped at the call boundary.
-    # - `:unknown` — the analyzer cannot prove either edge. Callers
-    #   MUST treat `:unknown` as conservatively as `:escaping` for
-    #   the purposes of fact retention; the distinction exists so
-    #   diagnostics and later RBS-Extended effect plumbing can
-    #   tell "deliberately conservative" apart from "declared
-    #   escape".
+    # - `:non_escaping` — the block is proven to be invoked immediately, zero or more times, and is NOT
+    #   retained past the call. The receiver does not store the block in an instance variable, return it as a
+    #   value, or schedule it for later invocation. Outer-local narrowing facts that survive the block body
+    #   MAY safely survive the call.
+    # - `:escaping` — the block is proven to be retained past the call (stored, returned, or invoked
+    #   asynchronously). Outer narrowing facts on locals the block can rebind MUST be dropped at the call
+    #   boundary.
+    # - `:unknown` — the analyzer cannot prove either edge. Callers MUST treat `:unknown` as conservatively as
+    #   `:escaping` for the purposes of fact retention; the distinction exists so diagnostics and later
+    #   RBS-Extended effect plumbing can tell "deliberately conservative" apart from "declared escape".
     #
     # ## Catalogue
     #
-    # Sub-phase 3a is RBS-blind: it ships a hardcoded catalogue
-    # keyed by Ruby class name. A future sub-phase will replace
-    # this with an `RBS::Extended` call-timing effect read from
-    # method signatures. The catalogue therefore covers ONLY the
-    # core-and-stdlib surface where immediate invocation is part of
-    # the documented contract:
+    # Sub-phase 3a is RBS-blind: it ships a hardcoded catalogue keyed by Ruby class name. A future sub-phase
+    # will replace this with an `RBS::Extended` call-timing effect read from method signatures. The catalogue
+    # therefore covers ONLY the core-and-stdlib surface where immediate invocation is part of the documented
+    # contract:
     #
-    # - `Array`, `Hash`, `Range`, `Integer`, `Enumerator::Lazy`
-    #   iteration methods (`each`, `map`, `select`, `reject`,
-    #   `flat_map`, `find`/`detect`, `any?`, `all?`, `none?`,
-    #   `one?`, `count`, `inject`/`reduce`, `each_with_index`,
-    #   `each_with_object`, `min_by`, `max_by`, `sort_by`,
-    #   `partition`, `group_by`, `tally`, `sum`, `take_while`,
-    #   `drop_while`, `chunk_while`, `slice_when`, `zip`,
-    #   `collect`, `collect_concat`, `filter`, `filter_map`).
-    # - `Hash`-only iteration: `each_pair`, `each_key`, `each_value`,
-    #   `transform_keys`, `transform_values`.
-    # - `Integer#times`, `Integer#upto`, `Integer#downto`,
-    #   `Range#each`, `Range#step`.
+    # - `Array`, `Hash`, `Range`, `Integer`, `Enumerator::Lazy` iteration methods (`each`, `map`, `select`,
+    #   `reject`, `flat_map`, `find`/`detect`, `any?`, `all?`, `none?`, `one?`, `count`, `inject`/`reduce`,
+    #   `each_with_index`, `each_with_object`, `min_by`, `max_by`, `sort_by`, `partition`, `group_by`,
+    #   `tally`, `sum`, `take_while`, `drop_while`, `chunk_while`, `slice_when`, `zip`, `collect`,
+    #   `collect_concat`, `filter`, `filter_map`).
+    # - `Hash`-only iteration: `each_pair`, `each_key`, `each_value`, `transform_keys`, `transform_values`.
+    # - `Integer#times`, `Integer#upto`, `Integer#downto`, `Range#each`, `Range#step`.
     # - `Object#tap`, `Object#then`, `Object#yield_self`.
-    # - Tuple/HashShape carriers map to Array/Hash for catalogue
-    #   lookup so a literal `[1, 2, 3].each { ... }` is recognised.
+    # - Tuple/HashShape carriers map to Array/Hash for catalogue lookup so a literal `[1, 2, 3].each { ... }`
+    #   is recognised.
     #
-    # Anything outside the catalogue resolves to `:unknown`. The
-    # catalogue is intentionally narrow: adding entries requires
-    # confirming, by reading the method's stdlib documentation,
-    # that the block is not retained. False positives in this
-    # catalogue would silently weaken the soundness of fact
-    # retention in later sub-phases.
+    # Anything outside the catalogue resolves to `:unknown`. The catalogue is intentionally narrow: adding
+    # entries requires confirming, by reading the method's stdlib documentation, that the block is not
+    # retained. False positives in this catalogue would silently weaken the soundness of fact retention in
+    # later sub-phases.
     #
-    # The analyzer is a pure query. It MUST NOT mutate the
-    # receiver type or scope, MUST NOT raise on unrecognised
-    # inputs, and MUST be deterministic for a given input.
+    # The analyzer is a pure query. It MUST NOT mutate the receiver type or scope, MUST NOT raise on
+    # unrecognised inputs, and MUST be deterministic for a given input.
     module ClosureEscapeAnalyzer
       module_function
 
       # @param receiver_type [Rigor::Type, nil]
       # @param method_name [Symbol]
-      # @param environment [Rigor::Environment, nil] reserved for the
-      #   future sub-phase that consults `RBS::Extended` call-timing
-      #   effects; sub-phase 3a ignores it.
+      # @param environment [Rigor::Environment, nil] reserved for the future sub-phase that consults
+      #   `RBS::Extended` call-timing effects; sub-phase 3a ignores it.
       # @return [Symbol] one of `:non_escaping`, `:escaping`, `:unknown`.
       def classify(receiver_type:, method_name:, environment: nil) # rubocop:disable Lint/UnusedMethodArgument
         return :unknown if receiver_type.nil?
@@ -90,14 +72,11 @@ module Rigor
       class << self
         private
 
-        # Resolve a single concrete class name for catalogue lookup.
-        # Returns `nil` when the receiver carrier does not name a
-        # single class (e.g. `Top`, `Dynamic[Top]`, `Union[...]`,
-        # `Bot`). `Tuple` projects to `Array`; `HashShape` to `Hash`;
-        # `Singleton[C]` to `C` (so `Integer.times` would resolve as
-        # a singleton call, but the catalogue today only lists
-        # instance-side methods on `Integer`, so a hit there would
-        # be unsurprising — kept for forward consistency).
+        # Resolve a single concrete class name for catalogue lookup. Returns `nil` when the receiver carrier
+        # does not name a single class (e.g. `Top`, `Dynamic[Top]`, `Union[...]`, `Bot`). `Tuple` projects to
+        # `Array`; `HashShape` to `Hash`; `Singleton[C]` to `C` (so `Integer.times` would resolve as a
+        # singleton call, but the catalogue today only lists instance-side methods on `Integer`, so a hit
+        # there would be unsurprising — kept for forward consistency).
         def receiver_class_name(receiver_type)
           case receiver_type
           when Type::Nominal, Type::Singleton then receiver_type.class_name
@@ -107,10 +86,9 @@ module Rigor
           end
         end
 
-        # `Rigor::Type::Constant` only carries scalar literals
-        # (`Integer`, `Float`, `String`, `Symbol`, `Range`, booleans,
-        # `nil`); the carrier explicitly rejects mutable container
-        # values, so we only project from those scalar shapes here.
+        # `Rigor::Type::Constant` only carries scalar literals (`Integer`, `Float`, `String`, `Symbol`,
+        # `Range`, booleans, `nil`); the carrier explicitly rejects mutable container values, so we only
+        # project from those scalar shapes here.
         CONSTANT_CLASS_NAMES = {
           Integer => "Integer",
           String => "String",
@@ -176,9 +154,8 @@ module Rigor
         "Enumerator::Lazy" => ENUMERABLE_NON_ESCAPING
       }.freeze
 
-      # Methods that are documented to **retain** the block past the
-      # call. The block is stored or scheduled, so outer narrowing
-      # facts on writeable captured locals cannot survive.
+      # Methods that are documented to **retain** the block past the call. The block is stored or scheduled,
+      # so outer narrowing facts on writeable captured locals cannot survive.
       ESCAPING = {
         "Module" => %i[define_method].freeze,
         "Class" => %i[define_method].freeze,

data/lib/rigor/inference/coverage_scanner.rb

@@ -9,20 +9,17 @@ module Rigor
   module Inference
     # Walks an AST and reports per-node-class coverage of `Rigor::Scope#type_of`.
     #
-    # For every visited node the scanner runs `type_of` with a fresh
-    # `FallbackTracer` and inspects the first recorded event:
+    # For every visited node the scanner runs `type_of` with a fresh `FallbackTracer` and inspects the first
+    # recorded event:
     #
-    # * If the first event's `node_class` matches the visited node's class,
-    #   the engine entered the fallback (else) branch *for this very node* —
-    #   the node is counted as **directly unrecognized**.
-    # * Otherwise the typer either succeeded outright or recursed into a child
-    #   that itself was unrecognized; the visited node is counted as
-    #   recognized so pass-through wrappers (`ProgramNode`, `StatementsNode`,
+    # * If the first event's `node_class` matches the visited node's class, the engine entered the fallback
+    #   (else) branch *for this very node* — the node is counted as **directly unrecognized**.
+    # * Otherwise the typer either succeeded outright or recursed into a child that itself was unrecognized;
+    #   the visited node is counted as recognized so pass-through wrappers (`ProgramNode`, `StatementsNode`,
     #   `ParenthesesNode`, ...) are not double-counted along with their leaves.
     #
-    # This class is intended for tooling probes and CI gates rather than the
-    # hot inference path: it allocates a tracer per visited node and discards
-    # the inferred type values.
+    # This class is intended for tooling probes and CI gates rather than the hot inference path: it allocates
+    # a tracer per visited node and discards the inferred type values.
     class CoverageScanner
       class Result < Data.define(:visits, :unrecognized, :events)
         # @return [Integer] sum of all visits across node classes.
@@ -56,13 +53,11 @@ module Rigor
         unrecognized = Hash.new(0)
         events = []
 
-        # Build the per-node scope index once per scan so locals bound
-        # earlier in the program flow into the scope used to type every
-        # later node. The indexer walks the program with a tracer-less
-        # StatementEvaluator and propagates the recorded scope down to
-        # expression-interior nodes the evaluator does not visit. The
-        # second pass below re-types each node with its own tracer so
-        # the per-class fallback statistics stay attributable.
+        # Build the per-node scope index once per scan so locals bound earlier in the program flow into the
+        # scope used to type every later node. The indexer walks the program with a tracer-less
+        # StatementEvaluator and propagates the recorded scope down to expression-interior nodes the evaluator
+        # does not visit. The second pass below re-types each node with its own tracer so the per-class
+        # fallback statistics stay attributable.
         scope_index = ScopeIndexer.index(root, default_scope: @scope)
 
         Source::NodeWalker.each(root) do |node|

data/lib/rigor/inference/def_return_typer.rb

@@ -6,22 +6,17 @@ require_relative "../type"
 
 module Rigor
   module Inference
-    # Returns the inferred return type of a `Prism::DefNode`, or nil
-    # when no type can be derived (empty body, scope-lookup miss,
-    # or any failure during inference — caller surfaces "no
-    # annotation" on a nil).
+    # Returns the inferred return type of a `Prism::DefNode`, or nil when no type can be derived (empty body,
+    # scope-lookup miss, or any failure during inference — caller surfaces "no annotation" on a nil).
     #
     # The inferred type is the union of:
     #
     # - the body's last-statement type, and
-    # - the type of every explicit `return value` reachable in the
-    #   body. Nested `def` / lambda / block bodies are return
-    #   barriers — their `return`s do not bubble up to the enclosing
-    #   method.
+    # - the type of every explicit `return value` reachable in the body. Nested `def` / lambda / block bodies
+    #   are return barriers — their `return`s do not bubble up to the enclosing method.
     #
-    # Extracted from `Rigor::SigGen::Generator#infer_return_type` so
-    # `LineTypeCollector` (`rigor annotate`'s def-line annotator)
-    # and the sig-generator share one source of truth.
+    # Extracted from `Rigor::SigGen::Generator#infer_return_type` so `LineTypeCollector` (`rigor annotate`'s
+    # def-line annotator) and the sig-generator share one source of truth.
     module DefReturnTyper
       RETURN_BARRIER_NODES = [Prism::DefNode, Prism::LambdaNode, Prism::BlockNode].freeze
       private_constant :RETURN_BARRIER_NODES
@@ -79,9 +74,8 @@ module Rigor
 
         scope = scope_index[return_node] || scope_index[args.first]
         return if scope.nil?
-        # `return a, b` packs into a Tuple at runtime; the MVP only
-        # handles the single-value form. Multi-arg returns
-        # contribute no type to keep the implementation focused.
+        # `return a, b` packs into a Tuple at runtime; the MVP only handles the single-value form. Multi-arg
+        # returns contribute no type to keep the implementation focused.
         return unless args.size == 1
 
         type = safe_type_of(scope, args.first)

data/lib/rigor/inference/dynamic_origin.rb

@@ -2,16 +2,13 @@
 
 module Rigor
   module Inference
-    # ADR-75 v1 cause set — precision-additive provenance for Dynamic[T]
-    # introduction sites.  Each symbol identifies a distinct family of
-    # reason that an expression widened to Dynamic, surfaced by
-    # `rigor coverage --protection` so users can distinguish tractable
-    # holes (e.g. an explicit `untyped` RBS signature) from intractable
-    # ones (e.g. unsupported syntax).
+    # ADR-75 v1 cause set — precision-additive provenance for Dynamic[T] introduction sites. Each symbol
+    # identifies a distinct family of reason that an expression widened to Dynamic, surfaced by
+    # `rigor coverage --protection` so users can distinguish tractable holes (e.g. an explicit `untyped` RBS
+    # signature) from intractable ones (e.g. unsupported syntax).
     #
-    # Provenance is a side-channel: it never participates in subtyping,
-    # consistency, normalization, or erasure, and no diagnostic fires
-    # from it.
+    # Provenance is a side-channel: it never participates in subtyping, consistency, normalization, or
+    # erasure, and no diagnostic fires from it.
     module DynamicOrigin
       # A gem with no resolvable RBS.
       EXTERNAL_GEM_WITHOUT_RBS = :external_gem_without_rbs
@@ -21,6 +18,13 @@ module Rigor
       ANALYZER_BUDGET_CUTOFF  = :analyzer_budget_cutoff
       # Authored `untyped` contract.
       EXPLICIT_UNTYPED        = :explicit_untyped
+      # The engine cannot yet infer a value's type although it is not unmodeled syntax and no RBS declared
+      # it `untyped`: a resolved user/ancestor method whose return body it cannot fold, or an undeclared
+      # method *parameter* with no call-site type flowing in (`def f(x); x.foo`). The lever is inference —
+      # parameter inference (ADR-67) or ivar-field typing (ADR-58) — not a hand-written type, so it is an
+      # engine gap that routes to that roadmap rather than to "add RBS". (The `_return_` in the name is
+      # historical; it now covers the parameter case too.)
+      INFERRED_RETURN_UNTYPED = :inferred_return_untyped
       # Inference fallback on unmodeled construct.
       UNSUPPORTED_SYNTAX      = :unsupported_syntax
 
@@ -29,20 +33,18 @@ module Rigor
         FRAMEWORK_DSL_BOUNDARY,
         ANALYZER_BUDGET_CUTOFF,
         EXPLICIT_UNTYPED,
+        INFERRED_RETURN_UNTYPED,
         UNSUPPORTED_SYNTAX
       ].freeze
 
-      # ADR-73 P6 / ADR-75 WD2 — tractability: given the cause, can a user
-      # close this `Dynamic` hole, and on which axis. `coverage --protection`
-      # surfaces it so a user does not chase a hole a hand-written type
+      # ADR-73 P6 / ADR-75 WD2 — tractability: given the cause, can a user close this `Dynamic` hole, and on
+      # which axis. `coverage --protection` surfaces it so a user does not chase a hole a hand-written type
       # cannot fix. Three coarse, action-oriented categories:
       #
-      # - `:add_rbs`      — write or install RBS (a missing gem signature,
-      #                     or an authored `untyped` to tighten).
-      # - `:enable_plugin`— a framework / DSL boundary; needs a plugin or
-      #                     `pre_eval:`, not a hand-written type.
-      # - `:engine_gap`   — not user-closable (a budget cutoff or unmodeled
-      #                     syntax); report it.
+      # - `:add_rbs`      — write or install RBS (a missing gem signature, or an authored `untyped` to
+      #                     tighten).
+      # - `:enable_plugin`— a framework / DSL boundary; needs a plugin or `pre_eval:`, not a hand-written type.
+      # - `:engine_gap`   — not user-closable (a budget cutoff or unmodeled syntax); report it.
       ADD_RBS       = :add_rbs
       ENABLE_PLUGIN = :enable_plugin
       ENGINE_GAP    = :engine_gap
@@ -52,13 +54,14 @@ module Rigor
         EXPLICIT_UNTYPED => ADD_RBS,
         FRAMEWORK_DSL_BOUNDARY => ENABLE_PLUGIN,
         ANALYZER_BUDGET_CUTOFF => ENGINE_GAP,
+        INFERRED_RETURN_UNTYPED => ENGINE_GAP,
         UNSUPPORTED_SYNTAX => ENGINE_GAP
       }.freeze
 
       module_function
 
-      # @return [Symbol, nil] the tractability category for a cause, or nil
-      #   when the cause is unknown / absent.
+      # @return [Symbol, nil] the tractability category for a cause, or nil when the cause is unknown /
+      #   absent.
       def tractability(cause)
         TRACTABILITY[cause]
       end