rigortype 0.2.7 → 0.2.8

data/lib/rigor/inference/method_dispatcher/reduce_folding.rb

@@ -9,65 +9,51 @@ module Rigor
     module MethodDispatcher
       # Symbol-form `reduce` / `inject` return-type tier.
       #
-      # `IteratorDispatch.inject_block_params` deliberately declines the
-      # Symbol-call shapes (`(1..n).reduce(1, :*)`, `[1,2,3].reduce(:+)`)
-      # because they carry no block to bind parameters for — the decline
-      # of *block-param typing* is correct. What that decline leaves on
-      # the floor is the *return type*: with no block and no precise tier,
-      # the call falls to `Enumerable#reduce`'s RBS overload
-      # `(untyped, Symbol) -> untyped`, so the whole fold widens to
-      # `Dynamic[top]`.
+      # `IteratorDispatch.inject_block_params` deliberately declines the Symbol-call shapes
+      # (`(1..n).reduce(1, :*)`, `[1,2,3].reduce(:+)`) because they carry no block to bind parameters for —
+      # the decline of *block-param typing* is correct. What that decline leaves on the floor is the
+      # *return type*: with no block and no precise tier, the call falls to `Enumerable#reduce`'s RBS
+      # overload `(untyped, Symbol) -> untyped`, so the whole fold widens to `Dynamic[top]`.
       #
-      # This tier recovers a precise return type for the Symbol-operand
-      # forms by dispatching the named operator on the accumulated type:
+      # This tier recovers a precise return type for the Symbol-operand forms by dispatching the named
+      # operator on the accumulated type:
       #
-      # - `(seed, :op)` (2-arg) — operand starts at the seed type `S`;
-      #   the result type is `dispatch(:op, widen(S) ∪ widen(E), widen(E))`
-      #   joined with the seed (the seed is returned unchanged when the
-      #   collection is empty). `E` is the receiver's element type.
-      # - `(:op)` (1-arg) — no seed: the first element seeds the memo, so
-      #   the operand type is `E` and the result is
-      #   `dispatch(:op, widen(E), widen(E))`. RBS models this overload as
-      #   `() { (E, E) -> E } -> E` (no nil), so the tier returns the
-      #   operator result without manufacturing a nil — staying consistent
-      #   with the declared type and Rigor's false-positive discipline
-      #   (the empty-collection `nil` runtime case is not modelled by RBS
-      #   and adding it here would only pressure callers into defensive
-      #   nil-handling for code that works).
+      # - `(seed, :op)` (2-arg) — operand starts at the seed type `S`; the result type is
+      #   `dispatch(:op, widen(S) ∪ widen(E), widen(E))` joined with the seed (the seed is returned
+      #   unchanged when the collection is empty). `E` is the receiver's element type.
+      # - `(:op)` (1-arg) — no seed: the first element seeds the memo, so the operand type is `E` and the
+      #   result is `dispatch(:op, widen(E), widen(E))`. RBS models this overload as
+      #   `() { (E, E) -> E } -> E` (no nil), so the tier returns the operator result without manufacturing
+      #   a nil — staying consistent with the declared type and Rigor's false-positive discipline (the
+      #   empty-collection `nil` runtime case is not modelled by RBS and adding it here would only pressure
+      #   callers into defensive nil-handling for code that works).
       #
-      # The tier is precision-additive: it declines (returns nil, today's
-      # `Dynamic[top]` behaviour) for every shape it cannot prove —
-      # unknown element type, Dynamic / Top receiver, a non-`Constant`
-      # Symbol operand, or an operator the engine cannot dispatch on the
-      # widened operand types.
+      # The tier is precision-additive: it declines (returns nil, today's `Dynamic[top]` behaviour) for
+      # every shape it cannot prove — unknown element type, Dynamic / Top receiver, a non-`Constant` Symbol
+      # operand, or an operator the engine cannot dispatch on the widened operand types.
       #
-      # `widen_value_pinned` (ADR-55/56) collapses `Constant`/`IntegerRange`
-      # operands to their nominal base before dispatch so the result is the
-      # operator's nominal return (`Integer`) rather than a constant-folded
-      # `Constant[120]` — full constant folding of the reduction is out of
-      # scope, the precision target is the carrier (`Integer`), not the value.
+      # `widen_value_pinned` (ADR-55/56) collapses `Constant`/`IntegerRange` operands to their nominal base
+      # before dispatch so the result is the operator's nominal return (`Integer`) rather than a
+      # constant-folded `Constant[120]` — full constant folding of the reduction is out of scope, the
+      # precision target is the carrier (`Integer`), not the value.
       module ReduceFolding
         module_function
 
         REDUCE_METHODS = %i[reduce inject].freeze
         private_constant :REDUCE_METHODS
 
-        # Allow-listed pure, side-effect-free fold operators. Each is
-        # safe on the foldable constant operand classes (Integer / Float
-        # / Rational); division / modulo by zero is caught by the rescue
-        # harness in `execute_constant_reduce` and declines to the
-        # nominal fold. `:gcd` / `:lcm` are valid binary Integer methods
-        # (`acc.public_send(:gcd, elem)`); `:min` / `:max` are *not* (no
-        # `Integer#min`/`#max` — they would raise and decline), so they
-        # are deliberately omitted.
+        # Allow-listed pure, side-effect-free fold operators. Each is safe on the foldable constant operand
+        # classes (Integer / Float / Rational); division / modulo by zero is caught by the rescue harness
+        # in `execute_constant_reduce` and declines to the nominal fold. `:gcd` / `:lcm` are valid binary
+        # Integer methods (`acc.public_send(:gcd, elem)`); `:min` / `:max` are *not* (no
+        # `Integer#min`/`#max` — they would raise and decline), so they are deliberately omitted.
         CONSTANT_FOLD_OPERATORS = %i[+ * - / % & | ^ gcd lcm].freeze
         private_constant :CONSTANT_FOLD_OPERATORS
 
-        # Hard caps (ADR-41 WD4 style). The element count is checked
-        # BEFORE the receiver is enumerated, so a `(1..1_000_000)` range
-        # never materialises. The bit-length cap rejects factorial-style
-        # blow-up (`(1..64).reduce(:*)` is a ~296-bit Integer) so the
-        # folded value can never become an analyzer-heavy bignum.
+        # Hard caps (ADR-41 WD4 style). The element count is checked BEFORE the receiver is enumerated, so
+        # a `(1..1_000_000)` range never materialises. The bit-length cap rejects factorial-style blow-up
+        # (`(1..64).reduce(:*)` is a ~296-bit Integer) so the folded value can never become an
+        # analyzer-heavy bignum.
         CONSTANT_FOLD_ELEMENT_CAP = 64
         CONSTANT_FOLD_BIT_CAP = 256
         private_constant :CONSTANT_FOLD_ELEMENT_CAP, :CONSTANT_FOLD_BIT_CAP
@@ -81,14 +67,11 @@ module Rigor
           operator, seed = operator_and_seed(args)
           return nil if operator.nil?
 
-          # Precision pre-check: when the receiver is a fully-constant
-          # collection (a `Constant[Range]` with foldable endpoints or a
-          # `Tuple` of `Constant` elements) and the operator is an
-          # allow-listed pure op, treat the reduction as a pure function
-          # and execute it on the real values, capped. Any decline (size
-          # cap, non-constant member, magnitude, exception) falls through
-          # to the carrier-precise nominal fold below — byte-identical to
-          # pre-fold behaviour.
+          # Precision pre-check: when the receiver is a fully-constant collection (a `Constant[Range]` with
+          # foldable endpoints or a `Tuple` of `Constant` elements) and the operator is an allow-listed pure
+          # op, treat the reduction as a pure function and execute it on the real values, capped. Any
+          # decline (size cap, non-constant member, magnitude, exception) falls through to the
+          # carrier-precise nominal fold below — byte-identical to pre-fold behaviour.
           folded = try_constant_reduce(context.receiver, operator, seed)
           return folded if folded
 
@@ -98,12 +81,11 @@ module Rigor
           fold_result(operator, seed, element, context.environment)
         end
 
-        # Executes the reduction on real constant values, or returns nil
-        # to decline. The caller falls through to the nominal fold on a
-        # nil return, so every guard here is precision-additive only.
+        # Executes the reduction on real constant values, or returns nil to decline. The caller falls
+        # through to the nominal fold on a nil return, so every guard here is precision-additive only.
         #
-        # @param seed [Rigor::Type, nil] the optional seed type; only a
-        #   foldable `Constant` seed is honoured, any other seed declines.
+        # @param seed [Rigor::Type, nil] the optional seed type; only a foldable `Constant` seed is
+        #   honoured, any other seed declines.
         # @return [Rigor::Type::Constant, nil]
         def try_constant_reduce(receiver, operator, seed)
           return nil unless CONSTANT_FOLD_OPERATORS.include?(operator)
@@ -117,9 +99,8 @@ module Rigor
           execute_constant_reduce(members, operator, seed_value, seed_present)
         end
 
-        # Extracts the receiver's elements as a Ruby Array of foldable
-        # constant values, or nil to decline. Checks the size cap BEFORE
-        # enumerating so an unbounded / huge `Constant[Range]` (e.g.
+        # Extracts the receiver's elements as a Ruby Array of foldable constant values, or nil to decline.
+        # Checks the size cap BEFORE enumerating so an unbounded / huge `Constant[Range]` (e.g.
         # `(1..1_000_000)`) never calls `to_a`.
         #
         # @return [Array, nil]
@@ -141,8 +122,8 @@ module Rigor
           # Reject endless / beginless ranges (`(1..)`, `(..5)`).
           return nil if first.nil? || last.nil?
 
-          # Size BEFORE enumeration — `Range#size` is O(1) for numeric
-          # ranges and never materialises the elements.
+          # Size BEFORE enumeration — `Range#size` is O(1) for numeric ranges and never materialises the
+          # elements.
           size = value.size
           return nil unless size.is_a?(Integer)
           return nil if size > CONSTANT_FOLD_ELEMENT_CAP
@@ -159,9 +140,8 @@ module Rigor
           elements.map(&:value)
         end
 
-        # @return [Array(Object, Boolean)] `[seed_value, present?]`. A nil
-        #   seed type yields `[nil, false]` (no-seed form). A foldable
-        #   `Constant` seed yields `[value, true]`. Any other seed yields
+        # @return [Array(Object, Boolean)] `[seed_value, present?]`. A nil seed type yields `[nil, false]`
+        #   (no-seed form). A foldable `Constant` seed yields `[value, true]`. Any other seed yields
         #   `[nil, false]` so the caller can decline.
         def constant_seed(seed)
           return [nil, false] if seed.nil?
@@ -170,11 +150,9 @@ module Rigor
           [seed.value, true]
         end
 
-        # Runs the actual reduction, guarded by the rescue harness and
-        # the magnitude cap. Empty-collection semantics match Ruby:
-        # `[].reduce(s, :op) == s` (seed form) and `[].reduce(:op) == nil`
-        # (no-seed form → declines so the nominal fold's no-nil contract
-        # stands; see `fold_result`).
+        # Runs the actual reduction, guarded by the rescue harness and the magnitude cap. Empty-collection
+        # semantics match Ruby: `[].reduce(s, :op) == s` (seed form) and `[].reduce(:op) == nil` (no-seed
+        # form → declines so the nominal fold's no-nil contract stands; see `fold_result`).
         #
         # @return [Rigor::Type::Constant, nil]
         def execute_constant_reduce(members, operator, seed_value, seed_present)
@@ -182,9 +160,8 @@ module Rigor
             if seed_present
               members.reduce(seed_value) { |acc, e| acc.public_send(operator, e) }
             else
-              # No-seed empty collection reduces to nil; decline so the
-              # nominal no-nil contract is preserved rather than folding
-              # to `Constant[nil]`.
+              # No-seed empty collection reduces to nil; decline so the nominal no-nil contract is preserved
+              # rather than folding to `Constant[nil]`.
               return nil if members.empty?
 
               members.reduce { |acc, e| acc.public_send(operator, e) }
@@ -206,17 +183,15 @@ module Rigor
           FOLDABLE_FOLD_CLASSES.any? { |klass| value.is_a?(klass) }
         end
 
-        # Rejects bignum blow-up. A folded Integer wider than the bit cap
-        # (factorial, repeated multiplication) declines to the nominal
-        # `Integer` carrier rather than parking a heavy literal in the
-        # type graph. Float / Rational carry no comparable blow-up risk.
+        # Rejects bignum blow-up. A folded Integer wider than the bit cap (factorial, repeated
+        # multiplication) declines to the nominal `Integer` carrier rather than parking a heavy literal in
+        # the type graph. Float / Rational carry no comparable blow-up risk.
         def magnitude_too_large?(result)
           result.is_a?(Integer) && result.bit_length > CONSTANT_FOLD_BIT_CAP
         end
 
-        # Splits the call's positional arguments into the operator Symbol
-        # and the optional seed. Returns `[nil, nil]` for any non-Symbol-
-        # operand shape so `try_dispatch` declines.
+        # Splits the call's positional arguments into the operator Symbol and the optional seed. Returns
+        # `[nil, nil]` for any non-Symbol-operand shape so `try_dispatch` declines.
         #
         # - `[:op]`          -> operator `:op`, no seed
         # - `[seed, :op]`    -> operator `:op`, seed `seed`
@@ -239,11 +214,9 @@ module Rigor
           type.value.is_a?(Symbol) ? type.value : nil
         end
 
-        # Dispatches the operator on the widened operand types. With a
-        # seed the memo type spans `seed | element` (the first iteration's
-        # memo is the seed, every later iteration's memo is a previous
-        # operator result); without a seed the memo and operand are both
-        # the element type.
+        # Dispatches the operator on the widened operand types. With a seed the memo type spans
+        # `seed | element` (the first iteration's memo is the seed, every later iteration's memo is a
+        # previous operator result); without a seed the memo and operand are both the element type.
         def fold_result(operator, seed, element, environment)
           widened_element = Type::Combinator.widen_value_pinned(element)
           memo = if seed.nil?
@@ -257,12 +230,10 @@ module Rigor
           result = dispatch_operator(memo, operator, widened_element, environment)
           return nil if result.nil?
 
-          # The seed itself is the result when the collection is empty
-          # (`[].reduce(s, :op) == s`), so a 2-arg fold's static type is
-          # the operator result joined with the seed. The seed is widened
-          # (`Constant[0]` -> `Integer`) for the join so the carrier stays
-          # the precision target rather than leaking a value-pinned member
-          # (`0 | Integer`) — full constant folding of the fold is out of
+          # The seed itself is the result when the collection is empty (`[].reduce(s, :op) == s`), so a
+          # 2-arg fold's static type is the operator result joined with the seed. The seed is widened
+          # (`Constant[0]` -> `Integer`) for the join so the carrier stays the precision target rather than
+          # leaking a value-pinned member (`0 | Integer`) — full constant folding of the fold is out of
           # scope.
           return result if seed.nil?
 

data/lib/rigor/inference/method_dispatcher/regexp_folding.rb

@@ -10,13 +10,10 @@ module Rigor
       #
       # === Supported methods
       #
-      # * `escape(str)` / `quote(str)` — escapes regexp meta-characters.
-      #   Returns `Constant[String]`.
-      # * `new(str)` / `new(str, opts)` — constructs a Regexp at fold time
-      #   when the pattern argument is a `Constant[String]`. The optional
-      #   second argument may be a `Constant[Integer]` (flag bits), a
-      #   `Constant[true/false]` (IGNORECASE shorthand), or absent.
-      #   Returns `Constant[Regexp]`.
+      # * `escape(str)` / `quote(str)` — escapes regexp meta-characters. Returns `Constant[String]`.
+      # * `new(str)` / `new(str, opts)` — constructs a Regexp at fold time when the pattern argument is a
+      #   `Constant[String]`. The optional second argument may be a `Constant[Integer]` (flag bits), a
+      #   `Constant[true/false]` (IGNORECASE shorthand), or absent. Returns `Constant[Regexp]`.
       #
       # === Non-constant / unsupported cases
       #
@@ -43,37 +40,29 @@ module Rigor
           nil
         end
 
-        # `Regexp.last_match` reads the same match-data slot the perlish
-        # `$~` global tracks. On a proven-match edge — the truthy branch
-        # of `if str =~ /re/`, the surviving path of `unless /re/ =~ s;
-        # raise; end`, a `case`/`when` regex arm — the flow engine has
-        # already narrowed `$~` to a non-nil `MatchData` (see
-        # `Narrowing#regex_match_predicate_scopes`). Upstream RBS types
-        # `Regexp.last_match` as `() -> MatchData?` / `(int) -> String?`,
-        # so without this consult the call drops back to the nilable
-        # return even where the surrounding flow has *proven* the match
-        # succeeded — re-introducing the `possible nil receiver` the `$~`
-        # narrowing exists to remove the moment the code reaches for the
-        # match through the method rather than the global.
+        # `Regexp.last_match` reads the same match-data slot the perlish `$~` global tracks. On a
+        # proven-match edge — the truthy branch of `if str =~ /re/`, the surviving path of `unless /re/ =~
+        # s; raise; end`, a `case`/`when` regex arm — the flow engine has already narrowed `$~` to a
+        # non-nil `MatchData` (see `Narrowing#regex_match_predicate_scopes`). Upstream RBS types
+        # `Regexp.last_match` as `() -> MatchData?` / `(int) -> String?`, so without this consult the call
+        # drops back to the nilable return even where the surrounding flow has *proven* the match
+        # succeeded — re-introducing the `possible nil receiver` the `$~` narrowing exists to remove the
+        # moment the code reaches for the match through the method rather than the global.
         #
-        # Mirrors the global's narrowing exactly, so it rides the same
-        # `Scope#forget_match_globals` invalidation (an intervening call
-        # that can re-run a match clears `$~`, and this consult clears
+        # Mirrors the global's narrowing exactly, so it rides the same `Scope#forget_match_globals`
+        # invalidation (an intervening call that can re-run a match clears `$~`, and this consult clears
         # with it):
         #
         # * 0-arg  -> `MatchData` (the narrowed `$~`)
-        # * `(N)`  -> `String` when capture group N is unconditional on
-        #             every successful match (the same set the `$N`
-        #             globals narrow), else `String?` (an optional /
-        #             alternation-reachable group is nil at runtime even
-        #             on a successful match).
+        # * `(N)`  -> `String` when capture group N is unconditional on every successful match (the same
+        #             set the `$N` globals narrow), else `String?` (an optional / alternation-reachable
+        #             group is nil at runtime even on a successful match).
         # * `(:name)` / `(0)` and other forms defer to RBS.
         #
-        # Declines (returns nil -> RBS) whenever `$~` is NOT proven
-        # non-nil: no match edge established it, or a falsey edge bound it
-        # to `Constant[nil]`. Narrowing only on the proven edge keeps the
-        # bare `m = Regexp.last_match; m[...]` (no preceding match) firing
-        # exactly as today — this never invents a match.
+        # Declines (returns nil -> RBS) whenever `$~` is NOT proven non-nil: no match edge established it,
+        # or a falsey edge bound it to `Constant[nil]`. Narrowing only on the proven edge keeps the bare
+        # `m = Regexp.last_match; m[...]` (no preceding match) firing exactly as today — this never invents
+        # a match.
         def fold_last_match(context)
           scope = context.scope
           return nil if scope.nil?
@@ -88,18 +77,16 @@ module Rigor
           fold_last_match_group(args.first, scope)
         end
 
-        # Narrowed `$~` is a non-nil `Nominal[MatchData]`. A bare
-        # `MatchData?` / `nil` / Dynamic binding is NOT a proven match.
+        # Narrowed `$~` is a non-nil `Nominal[MatchData]`. A bare `MatchData?` / `nil` / Dynamic binding is
+        # NOT a proven match.
         def proven_match?(match_data)
           match_data.is_a?(Type::Nominal) && match_data.class_name == "MatchData"
         end
 
-        # `Regexp.last_match(N)` for a value-pinned positive Integer N.
-        # Track the matching `$N` global the predicate edge already
-        # narrowed: present (`String`) means the group is unconditional,
-        # absent means it is optional / alternation-reachable (nil at
-        # runtime on a success), so we surface `String?`. A non-constant
-        # or non-positive index defers to RBS.
+        # `Regexp.last_match(N)` for a value-pinned positive Integer N. Track the matching `$N` global the
+        # predicate edge already narrowed: present (`String`) means the group is unconditional, absent
+        # means it is optional / alternation-reachable (nil at runtime on a success), so we surface
+        # `String?`. A non-constant or non-positive index defers to RBS.
         def fold_last_match_group(arg, scope)
           return nil unless arg.is_a?(Type::Constant)
 
@@ -123,11 +110,10 @@ module Rigor
           Type::Combinator.constant_of(Regexp.escape(str))
         end
 
-        # `Regexp.new(pattern)` / `Regexp.new(pattern, opts)` — constructs
-        # the pattern at inference time. Delegates to Ruby's real
-        # `Regexp.new` so all option forms (Integer flags, `true`/`false`,
-        # option strings) are handled without case-analysis; non-constant or
-        # invalid arguments decline through to the RBS tier.
+        # `Regexp.new(pattern)` / `Regexp.new(pattern, opts)` — constructs the pattern at inference time.
+        # Delegates to Ruby's real `Regexp.new` so all option forms (Integer flags, `true`/`false`, option
+        # strings) are handled without case-analysis; non-constant or invalid arguments decline through to
+        # the RBS tier.
         def fold_new(args)
           return nil if args.empty? || args.size > 2
 

data/lib/rigor/inference/method_dispatcher/set_folding.rb

@@ -6,20 +6,17 @@ require_relative "singleton_folding"
 module Rigor
   module Inference
     module MethodDispatcher
-      # Folds `Set` constructor calls into `Constant[Set]` when all
-      # arguments are statically known.
+      # Folds `Set` constructor calls into `Constant[Set]` when all arguments are statically known.
       #
-      # Ruby 3.2+ implements Set in C (`set.c`). The constructor is
-      # deterministic — it reads only its arguments and writes nothing
-      # to global state.
+      # Ruby 3.2+ implements Set in C (`set.c`). The constructor is deterministic — it reads only its
+      # arguments and writes nothing to global state.
       #
       # === Supported methods
       #
-      # * `Set[]` — variadic constructor; each argument must be a
-      #   `Constant[T]`. Returns `Constant[Set]`.
+      # * `Set[]` — variadic constructor; each argument must be a `Constant[T]`. Returns `Constant[Set]`.
       # * `Set.new` — zero-argument form; returns `Constant[Set.new]`.
-      # * `Set.new(tuple)` — the argument must be a `Tuple` whose
-      #   every element is a `Constant[T]`. Returns `Constant[Set]`.
+      # * `Set.new(tuple)` — the argument must be a `Tuple` whose every element is a `Constant[T]`. Returns
+      #   `Constant[Set]`.
       #
       # === Non-constant / unsupported cases
       #