rigortype 0.1.17 → 0.1.19

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

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+
+require_relative "../../type"
+require_relative "call_context"
+require_relative "iterator_dispatch"
+
+module Rigor
+  module Inference
+    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]`.
+      #
+      # 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).
+      #
+      # 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.
+      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.
+        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.
+        CONSTANT_FOLD_ELEMENT_CAP = 64
+        CONSTANT_FOLD_BIT_CAP = 256
+        private_constant :CONSTANT_FOLD_ELEMENT_CAP, :CONSTANT_FOLD_BIT_CAP
+
+        # @return [Rigor::Type, nil]
+        def try_dispatch(context)
+          return nil unless REDUCE_METHODS.include?(context.method_name)
+          return nil if context.block_type
+
+          args = context.args
+          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.
+          folded = try_constant_reduce(context.receiver, operator, seed)
+          return folded if folded
+
+          element = IteratorDispatch.element_type_of(context.receiver)
+          return nil if element.nil?
+
+          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.
+        #
+        # @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)
+
+          members = constant_members(receiver)
+          return nil if members.nil?
+
+          seed_value, seed_present = constant_seed(seed)
+          return nil if !seed.nil? && !seed_present
+
+          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.
+        # `(1..1_000_000)`) never calls `to_a`.
+        #
+        # @return [Array, nil]
+        def constant_members(receiver)
+          case receiver
+          when Type::Constant
+            constant_range_members(receiver.value)
+          when Type::Tuple
+            tuple_members(receiver.elements)
+          end
+        end
+
+        def constant_range_members(value)
+          return nil unless value.is_a?(Range)
+
+          first = value.begin
+          last = value.end
+          return nil unless foldable?(first) && foldable?(last)
+          # 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 = value.size
+          return nil unless size.is_a?(Integer)
+          return nil if size > CONSTANT_FOLD_ELEMENT_CAP
+
+          value.to_a
+        rescue StandardError
+          nil
+        end
+
+        def tuple_members(elements)
+          return nil if elements.size > CONSTANT_FOLD_ELEMENT_CAP
+          return nil unless elements.all? { |e| e.is_a?(Type::Constant) && foldable?(e.value) }
+
+          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
+        #   `[nil, false]` so the caller can decline.
+        def constant_seed(seed)
+          return [nil, false] if seed.nil?
+          return [nil, false] unless seed.is_a?(Type::Constant) && foldable?(seed.value)
+
+          [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`).
+        #
+        # @return [Rigor::Type::Constant, nil]
+        def execute_constant_reduce(members, operator, seed_value, seed_present)
+          result =
+            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]`.
+              return nil if members.empty?
+
+              members.reduce { |acc, e| acc.public_send(operator, e) }
+            end
+
+          return nil unless foldable?(result)
+          return nil if magnitude_too_large?(result)
+
+          Type::Combinator.constant_of(result)
+        rescue StandardError
+          # Division by zero, type mismatch, or any operator error: decline.
+          nil
+        end
+
+        FOLDABLE_FOLD_CLASSES = [Integer, Float, Rational].freeze
+        private_constant :FOLDABLE_FOLD_CLASSES
+
+        def foldable?(value)
+          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.
+        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.
+        #
+        # - `[:op]`          -> operator `:op`, no seed
+        # - `[seed, :op]`    -> operator `:op`, seed `seed`
+        def operator_and_seed(args)
+          case args.size
+          when 1
+            sym = symbol_value(args[0])
+            sym ? [sym, nil] : [nil, nil]
+          when 2
+            sym = symbol_value(args[1])
+            sym ? [sym, args[0]] : [nil, nil]
+          else
+            [nil, nil]
+          end
+        end
+
+        def symbol_value(type)
+          return nil unless type.is_a?(Type::Constant)
+
+          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.
+        def fold_result(operator, seed, element, environment)
+          widened_element = Type::Combinator.widen_value_pinned(element)
+          memo = if seed.nil?
+                   widened_element
+                 else
+                   Type::Combinator.union(
+                     Type::Combinator.widen_value_pinned(seed), widened_element
+                   )
+                 end
+
+          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
+          # scope.
+          return result if seed.nil?
+
+          Type::Combinator.union(Type::Combinator.widen_value_pinned(seed), result)
+        end
+
+        def dispatch_operator(memo, operator, operand, environment)
+          MethodDispatcher.dispatch(
+            receiver_type: memo, method_name: operator,
+            arg_types: [operand], environment: environment
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -38,10 +38,81 @@ module Rigor
           return nil unless SingletonFolding.receiver?(receiver, "Regexp")
           return fold_escape(args) if REGEXP_ESCAPE_METHODS.include?(method_name)
           return fold_new(args) if method_name == :new
+          return fold_last_match(context) if method_name == :last_match
 
           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.
+        #
+        # 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).
+        # * `(: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.
+        def fold_last_match(context)
+          scope = context.scope
+          return nil if scope.nil?
+
+          match_data = scope.global(:$~)
+          return nil unless proven_match?(match_data)
+
+          args = context.args
+          return Type::Combinator.nominal_of("MatchData") if args.empty?
+          return nil unless args.size == 1
+
+          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.
+        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.
+        def fold_last_match_group(arg, scope)
+          return nil unless arg.is_a?(Type::Constant)
+
+          index = arg.value
+          return nil unless index.is_a?(Integer) && index.positive?
+
+          string_t = Type::Combinator.nominal_of("String")
+          group_global = scope.global(:"$#{index}")
+          return string_t if group_global.is_a?(Type::Nominal) && group_global.class_name == "String"
+
+          Type::Combinator.union(string_t, Type::Combinator.constant_of(nil))
+        end
+
         # `Regexp.escape(str)` / `.quote(str)` — one String arg.
         def fold_escape(args)
           return nil unless args.size == 1

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

@@ -98,7 +98,8 @@ module Rigor
           uniq: :tuple_uniq,
           index: :tuple_find_index,
           find_index: :tuple_find_index,
-          rindex: :tuple_rindex
+          rindex: :tuple_rindex,
+          flatten: :tuple_flatten
         }.freeze
 
         HASH_SHAPE_HANDLERS = {
@@ -228,15 +229,8 @@ module Rigor
           end
 
           def dispatch_nominal_size(nominal, method_name, args)
-            if nominal.class_name == "String" && args.size == 1
-              string_binary = dispatch_string_binary_from_arg(method_name, args.first)
-              return string_binary if string_binary
-            end
-
-            if nominal.class_name == "Integer" && args.size == 1
-              integer_binary = dispatch_integer_binary_from_arg(method_name, args.first)
-              return integer_binary if integer_binary
-            end
+            projection = nominal_projection(nominal, method_name, args)
+            return projection if projection
 
             return nil unless args.empty?
 
@@ -246,6 +240,106 @@ module Rigor
             Type::Combinator.non_negative_int
           end
 
+          # Arg-/method-driven precision projections for a `Nominal`
+          # receiver, consulted ahead of the no-arg size tier. Each
+          # branch gates on the class name first so unrelated nominals
+          # skip the work. Returns nil when no projection applies.
+          def nominal_projection(nominal, method_name, args)
+            case nominal.class_name
+            when "String"
+              dispatch_string_binary_from_arg(method_name, args.first) if args.size == 1
+            when "Integer"
+              dispatch_integer_binary_from_arg(method_name, args.first) if args.size == 1
+            when "Array"
+              case method_name
+              when :flatten then array_nominal_flatten(nominal, args)
+              when :compact then array_nominal_compact(nominal, args)
+              end
+            end
+          end
+
+          # `Array[T]#compact` — `compact` removes every `nil` element,
+          # so the result element type is `T` with its `nil` constituent
+          # stripped (`Array[Node?]#compact` → `Array[Node]`). Mirrors
+          # the `Tuple#compact` constant fold for the generic element
+          # case. Declines when the receiver carries no type argument
+          # (the RBS `Array[untyped]` answer is already maximal) or when
+          # `T` has no `nil` constituent to remove (the result equals the
+          # receiver, so the RBS tier's answer is already precise).
+          def array_nominal_compact(nominal, args)
+            return nil unless args.empty?
+
+            element = nominal.type_args&.first
+            return nil if element.nil?
+
+            stripped = strip_nil_constituent(element)
+            return nil if stripped.equal?(element)
+
+            Type::Combinator.nominal_of("Array", type_args: [stripped])
+          end
+
+          # Removes the `nil` constituent from a (possibly union) type,
+          # returning the same object when there is nothing to remove so
+          # callers can detect the no-op cheaply. Kept local to the
+          # dispatch tier to avoid a dependency on the narrowing module.
+          def strip_nil_constituent(type)
+            case type
+            when Type::Constant
+              type.value.nil? ? Type::Combinator.bot : type
+            when Type::Nominal
+              type.class_name == "NilClass" ? Type::Combinator.bot : type
+            when Type::Union
+              kept = type.members.map { |m| strip_nil_constituent(m) }
+              return type if kept.zip(type.members).all? { |k, m| k.equal?(m) }
+
+              Type::Combinator.union(*kept)
+            else
+              type
+            end
+          end
+
+          # `Array[T]#flatten` (and `flatten(depth)`). When `T` is a
+          # nested `Array[U]` nominal, one flatten level yields the
+          # joined inner element type — `Array[Array[U]]#flatten` →
+          # `Array[U]`. When `T` is non-nested the result is `Array[T]`
+          # unchanged (Ruby returns a copy with the same element type).
+          # Multi-level nesting is handled conservatively: each level
+          # joins its element types, and a `depth` argument that does
+          # not fully resolve the nesting still produces a sound
+          # superset. Declines on an `Array` with no type argument
+          # (the RBS `Array[untyped]` answer is already as precise as
+          # we can be) and on a non-static depth argument.
+          def array_nominal_flatten(nominal, args)
+            element = nominal.type_args&.first
+            return nil if element.nil?
+
+            depth = tuple_flatten_depth(args)
+            return nil if depth == :decline
+
+            flattened = flatten_nominal_element(element, depth)
+            Type::Combinator.nominal_of("Array", type_args: [flattened])
+          end
+
+          # Resolves the element type of a flattened `Array[element]`.
+          # Each `Array[U]` nesting level contributes `U`; the per-level
+          # element types are unioned. `depth < 0` recurses without
+          # bound; `depth == 0` stops (Ruby's `flatten(0)` is a no-op
+          # copy and returns the element unchanged).
+          def flatten_nominal_element(element, depth)
+            return element if depth.zero?
+            return element unless array_nominal?(element)
+
+            inner = element.type_args.first
+            return element if inner.nil?
+
+            flatten_nominal_element(inner, depth - 1)
+          end
+
+          def array_nominal?(type)
+            type.is_a?(Type::Nominal) && type.class_name == "Array" && !type.type_args.nil? &&
+              !type.type_args.empty?
+          end
+
           # Arg-type-driven String binary projections for any String-typed
           # receiver (including Nominal, Refined, and Difference fallbacks).
           # Called before the no-arg size guard so binary operators are seen.
@@ -875,6 +969,50 @@ module Rigor
             constant_index(tuple, args) { |elements, value| elements.index { |e| e.value == value } }
           end
 
+          # `tuple.flatten` / `tuple.flatten(depth)` — recursively
+          # flattens nested Tuple elements into a single Tuple. With
+          # no argument the flatten is unbounded (matching Ruby's
+          # `Array#flatten`); a `Constant[Integer]` depth bounds it.
+          # Non-Tuple elements (scalars, `Array[T]` nominals, …) pass
+          # through unchanged at their level. A non-static depth
+          # argument (or a non-Integer one) declines so RBS answers.
+          def tuple_flatten(tuple, _method_name, args)
+            depth = tuple_flatten_depth(args)
+            return nil if depth == :decline
+
+            Type::Combinator.tuple_of(*flatten_elements(tuple.elements, depth))
+          end
+
+          # Returns the requested flatten depth: `-1` for the no-arg
+          # (unbounded) form, the Integer for a `Constant[Integer]`
+          # argument, or `:decline` for any non-static / wrong-arity
+          # argument shape.
+          def tuple_flatten_depth(args)
+            return -1 if args.empty?
+            return :decline unless args.size == 1
+
+            arg = args.first
+            return arg.value if arg.is_a?(Type::Constant) && arg.value.is_a?(Integer)
+
+            :decline
+          end
+
+          # Flattens a list of element types to `depth` levels.
+          # `depth < 0` means unbounded. A Tuple element is spliced
+          # in (recursing with `depth - 1`); everything else passes
+          # through at this level.
+          def flatten_elements(elements, depth)
+            return elements if depth.zero?
+
+            elements.flat_map do |element|
+              if element.is_a?(Type::Tuple)
+                flatten_elements(element.elements, depth - 1)
+              else
+                [element]
+              end
+            end
+          end
+
           # `rindex(obj)` → the LAST matching index, same decidability gate.
           def tuple_rindex(tuple, _method_name, args)
             constant_index(tuple, args) { |elements, value| elements.rindex { |e| e.value == value } }