rigortype 0.0.3 → 0.0.5

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+# `Date` and `DateTime` live in CRuby's bundled `date` gem, which
+# is stdlib rather than core — so the constants are not visible
+# until `date` is required. The dispatcher's `CATALOG_BY_CLASS`
+# table references `Date` and `DateTime` at load time, so requiring
+# the gem here (alongside the loader file that exports the catalog)
+# keeps the wiring self-contained: a consumer that pulls in the
+# constant-folding rule book gets the Date constants for free.
+require "date"
+
+require_relative "method_catalog"
+
+module Rigor
+  module Inference
+    module Builtins
+      # `Date` / `DateTime` catalog. Singleton — load once, consult
+      # during dispatch.
+      #
+      # `Date` and `DateTime` both come from CRuby's bundled `date`
+      # gem (`references/ruby/ext/date/date_core.c`). A single
+      # `Init_date_core` function registers them, so the catalog
+      # carries both classes — `Date` plus the `DateTime` subclass
+      # whose own Init block extends with `hour` / `min` /
+      # `strftime` / `iso8601` etc. The Ruby-side prelude
+      # (`lib/date.rb`) only contributes `Date#infinite?` and the
+      # nested `Date::Infinity` class; the bulk of the surface is
+      # in C.
+      #
+      # Date / DateTime receivers are not lifted to a `Constant`
+      # carrier today (there is no Date literal node — the closest
+      # is `Date.today` / `Date.parse(...)`, which produce
+      # `Nominal[Date]`). The catalog wiring therefore mostly
+      # governs:
+      #
+      # 1. The Integer-typed reader surface (`#year`, `#month`,
+      #    `#day`, `#wday`, `#hour`, `#min`, `#sec`) — RBS-declared
+      #    `Integer` is preserved through dispatch.
+      # 2. The blocklist below, which keeps mutator-style methods
+      #    that the C-body classifier already flagged
+      #    (`mutates_self`) from being missed by a future
+      #    `Constant<Date>` carrier, plus a defensive
+      #    `:initialize_copy` entry for symmetry with the other
+      #    catalogs.
+      #
+      # The non-bang `#next_day` / `#prev_day` / `#next_month` /
+      # `#prev_month` / `#next_year` / `#prev_year` / `#>>` / `#<<`
+      # selectors all RETURN brand-new `Date` objects rather than
+      # mutating the receiver — they intentionally stay
+      # catalog-eligible. The two real mutators
+      # (`#initialize_copy`, `#marshal_load`) are already classified
+      # `:mutates_self` by the C-body regex, so they fall out of
+      # `MethodCatalog#safe_for_folding?` without an explicit
+      # blocklist entry; the entries below are defense-in-depth
+      # against indirect mutators the regex might miss in a future
+      # CRuby bump.
+      DATE_CATALOG = MethodCatalog.new(
+        path: File.expand_path(
+          "../../../../data/builtins/ruby_core/date.yml",
+          __dir__
+        ),
+        mutating_selectors: {
+          "Date" => Set[
+            # `d_lite_initialize_copy` is already classed
+            # `:mutates_self` by the regex (it calls
+            # `rb_check_frozen` and rewrites the receiver's
+            # internal `dat` slots). Listed here for symmetry with
+            # String / Array / Range / Set / Time and to keep the
+            # blocklist self-documenting.
+            :initialize_copy,
+            # `d_lite_fill` is a `#ifndef NDEBUG` debug method that
+            # warms the receiver's cached `simple` / `complex`
+            # fields via the `get_s_*` / `get_c_*` macros. The
+            # macros perform in-place writes on the receiver's
+            # internal `dat` struct but use no helper the C-body
+            # regex recognises, so the classifier mis-flags it
+            # `:leaf`. Blocked so a future `Constant<Date>` carrier
+            # never folds it.
+            :fill
+          ],
+          "DateTime" => Set[
+            # `DateTime` inherits the bulk of its surface from
+            # `Date`. The dedicated DateTime-side methods are all
+            # readers (`hour`, `min`, …) plus formatting
+            # converters (`strftime`, `iso8601`, …); none mutate
+            # the receiver. The single defensive entry mirrors the
+            # Date side so that the inherited
+            # `Date#initialize_copy` (registered against
+            # `cDateTime` through subclassing) cannot fold through
+            # the catalog if a future `Constant<DateTime>` carrier
+            # ever lands.
+            :initialize_copy
+          ]
+        }
+      )
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "method_catalog"
+
+module Rigor
+  module Inference
+    module Builtins
+      # `Enumerable` module catalog. Singleton — load once.
+      #
+      # `Enumerable` is a Ruby module, not a class, so the
+      # catalog is NOT routed through
+      # `MethodDispatcher::ConstantFolding::CATALOG_BY_CLASS`
+      # (which dispatches on the receiver's concrete class).
+      # The data is consumed by future include-aware lookup —
+      # see `docs/CURRENT_WORK.md` for the planned slice.
+      ENUMERABLE_CATALOG = MethodCatalog.new(
+        path: File.expand_path(
+          "../../../../data/builtins/ruby_core/enumerable.yml",
+          __dir__
+        ),
+        mutating_selectors: {
+          "Enumerable" => Set[]
+        }
+      )
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "method_catalog"
+
+module Rigor
+  module Inference
+    module Builtins
+      # `Hash` catalog. Singleton — load once, consult during dispatch.
+      #
+      # Hash mirrors Array's mutation pattern: nearly every iteration
+      # method yields through `rb_hash_foreach` plus a per-pair static
+      # callback (`each_value_i`, `keep_if_i`, …), and the C-body
+      # classifier does not follow into the callback so it lands as
+      # `:leaf` despite being block-dependent. The blocklist below
+      # captures every false-positive `:leaf` we have spotted in the
+      # generated YAML — bias toward conservatism so a missed fold is
+      # acceptable but a folded mutator/yielder is not.
+      HASH_CATALOG = MethodCatalog.new(
+        path: File.expand_path(
+          "../../../../data/builtins/ruby_core/hash.yml",
+          __dir__
+        ),
+        mutating_selectors: {
+          "Hash" => Set[
+            # Block-dependent iteration — yields via `rb_hash_foreach`
+            # plus a per-pair callback that the regex classifier does
+            # not follow:
+            :each, :each_pair, :each_key, :each_value,
+            :select, :filter, :reject,
+            :transform_values,
+            # Block-dependent merge — `rb_hash_merge` delegates into
+            # `rb_hash_update`, which yields per conflict when a block
+            # is given:
+            :merge
+          ]
+        }
+      )
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "method_catalog"
+
+module Rigor
+  module Inference
+    module Builtins
+      # `Range` catalog. Singleton — load once, consult during
+      # dispatch.
+      #
+      # Range is largely immutable: `begin`, `end`, and `excl` are
+      # set at construction by `range_initialize` and never mutated
+      # afterwards. The blocklist below therefore stays small. The
+      # entries we DO need are the iteration methods whose C body
+      # routes through a helper the block/yield regex does not
+      # recognise, so the classifier mis-flags them as `:leaf`
+      # despite yielding to a block.
+      RANGE_CATALOG = MethodCatalog.new(
+        path: File.expand_path(
+          "../../../../data/builtins/ruby_core/range.yml",
+          __dir__
+        ),
+        mutating_selectors: {
+          "Range" => Set[
+            # `range_initialize` / `range_initialize_copy` write
+            # `begin`/`end`/`excl` slots on the receiver; classed
+            # `:leaf` because the writes go through the struct
+            # accessor not `rb_check_frozen`. Blocked for symmetry
+            # with String / Array.
+            :initialize, :initialize_copy,
+            # `range_reverse_each` yields to its block via
+            # `range_each_func` -> caller's block; the regex
+            # classifier follows direct `rb_yield*` calls only.
+            :reverse_each,
+            # `range_percent_step` returns an Enumerator unless a
+            # block is supplied, in which case it yields. Treated
+            # as block-dependent so the fold tier never invokes it
+            # against a literal Range and tries to materialise an
+            # Enumerator into a Constant.
+            :%
+          ]
+        }
+      )
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "method_catalog"
+
+module Rigor
+  module Inference
+    module Builtins
+      # `Rational` catalog. Singleton — load once, consult during
+      # dispatch.
+      #
+      # Rational is fully immutable: numerator / denominator slots
+      # are written once during `nurat_s_new_internal` and the C
+      # body never reaches for `rb_check_frozen`. Every catalog
+      # entry classifies cleanly (`:leaf`, `:leaf_when_numeric`,
+      # or `:dispatch` for the two methods that delegate into
+      # user-redefinable `==` / `Float()` — `nurat_eqeq_p` and
+      # `nurat_fdiv`). Bang-suffixed mutators do not exist on
+      # Rational.
+      #
+      # The blocklist therefore stays minimal. `initialize_copy`
+      # is added defensively (mirrors Range / Set) so a
+      # hypothetical future `Constant<Rational>` carrier cannot
+      # fold an aliasing copy through the catalog and surface a
+      # shared mutable handle.
+      RATIONAL_CATALOG = MethodCatalog.new(
+        path: File.expand_path(
+          "../../../../data/builtins/ruby_core/rational.yml",
+          __dir__
+        ),
+        mutating_selectors: {
+          "Rational" => Set[
+            :initialize_copy
+          ]
+        }
+      )
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "method_catalog"
+
+module Rigor
+  module Inference
+    module Builtins
+      # `Set` catalog. Singleton — load once, consult during dispatch.
+      #
+      # Set was rewritten in C and folded into CRuby for Ruby 3.2+;
+      # the reference branch (`ruby_4_0`) ships the implementation in
+      # `references/ruby/set.c` with `Init_Set` registering every
+      # method directly. There is no `set.rb` prelude — the trailing
+      # `rb_provide("set.rb")` makes `require "set"` a no-op against
+      # the built-in.
+      #
+      # The blocklist below catches the catalog `:leaf` entries the
+      # C-body classifier mis-attributes. Set's iteration helpers
+      # (`set_iter`, `RETURN_SIZED_ENUMERATOR`) and its identity-
+      # mode and reset paths drive into helpers the regex classifier
+      # does not yet recognise as block-yielding or mutating.
+      SET_CATALOG = MethodCatalog.new(
+        path: File.expand_path(
+          "../../../../data/builtins/ruby_core/set.yml",
+          __dir__
+        ),
+        mutating_selectors: {
+          "Set" => Set[
+            # Indirect mutators classified `:leaf` because the C
+            # classifier did not follow the helper functions:
+            #
+            # - `initialize_copy` calls `set_copy` to overwrite the
+            #   receiver's table.
+            # - `compare_by_identity` swaps the internal hash type
+            #   via `set_reset_table_with_type`.
+            # - `reset` rebuilds the internal table to dedup after
+            #   element mutation.
+            :initialize_copy, :compare_by_identity, :reset,
+            # Block-dependent methods classified `:leaf` because the
+            # C body uses `set_iter` / `RETURN_SIZED_ENUMERATOR`
+            # rather than calling `rb_yield` directly:
+            :each, :classify, :divide,
+            # `disjoint?` delegates into `set_i_intersect`, which
+            # for non-Set enumerables uses `rb_funcall(other,
+            # :any?, ...)` — that is user-redefinable dispatch the
+            # classifier missed because the call site is in a
+            # sibling function.
+            :disjoint?
+          ]
+        }
+      )
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "method_catalog"
+
+module Rigor
+  module Inference
+    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 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.
+      #
+      # The blocklist captures the false-positive `:leaf` entries
+      # whose helper functions the regex classifier did not
+      # recognise as mutators.
+      TIME_CATALOG = MethodCatalog.new(
+        path: File.expand_path(
+          "../../../../data/builtins/ruby_core/time.yml",
+          __dir__
+        ),
+        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.
+            :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.
+            :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.
+            :gmtime, :utc
+          ]
+        }
+      )
+    end
+  end
+end

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

@@ -4,6 +4,15 @@ require_relative "../../type"
 require_relative "../builtins/numeric_catalog"
 require_relative "../builtins/string_catalog"
 require_relative "../builtins/array_catalog"
+require_relative "../builtins/hash_catalog"
+require_relative "../builtins/range_catalog"
+require_relative "../builtins/set_catalog"
+require_relative "../builtins/time_catalog"
+require_relative "../builtins/date_catalog"
+require_relative "../builtins/comparable_catalog"
+require_relative "../builtins/enumerable_catalog"
+require_relative "../builtins/rational_catalog"
+require_relative "../builtins/complex_catalog"
 
 module Rigor
   module Inference
@@ -105,9 +114,14 @@ module Rigor
           arg_sets = args.map { |a| numeric_set_of(a) }
           return nil if arg_sets.any?(&:nil?)
 
-          case args.size
+          dispatch_by_arity(receiver_set, method_name, arg_sets)
+        end
+
+        def dispatch_by_arity(receiver_set, method_name, arg_sets)
+          case arg_sets.size
           when 0 then try_fold_unary(receiver_set, method_name)
           when 1 then try_fold_binary(receiver_set, method_name, arg_sets.first)
+          when 2 then try_fold_ternary(receiver_set, method_name, arg_sets)
           end
         end
 
@@ -216,6 +230,38 @@ module Rigor
           build_constant_type(results, source: receiver_values + arg_values)
         end
 
+        # 2-arg fold dispatch. Used by `Comparable#between?(min, max)`,
+        # `Comparable#clamp(min, max)`, and `Integer#pow(exp, mod)` —
+        # methods the catalog classifies `:leaf` but that the prior
+        # 0/1-arg switch could not reach. Range receivers/args are
+        # held back: a precise 2-arg range fold (e.g.
+        # `int<0,10>.between?(0, 10)` → `Constant[true]`) is a
+        # follow-up; for now any IntegerRange operand bails to the
+        # RBS tier.
+        def try_fold_ternary(receiver_set, method_name, arg_sets)
+          return nil if receiver_set.is_a?(Type::IntegerRange)
+          return nil if arg_sets.any?(Type::IntegerRange)
+
+          try_fold_ternary_set(receiver_set, method_name, arg_sets)
+        end
+
+        def try_fold_ternary_set(receiver_values, method_name, arg_sets)
+          total = receiver_values.size * arg_sets[0].size * arg_sets[1].size
+          return nil if total > UNION_FOLD_INPUT_LIMIT
+          return nil unless receiver_values.all? { |rv| ternary_method_allowed?(rv, method_name) }
+
+          results = ternary_cartesian(receiver_values, method_name, arg_sets)
+          build_constant_type(results, source: receiver_values + arg_sets.flatten)
+        end
+
+        def ternary_cartesian(receiver_values, method_name, arg_sets)
+          receiver_values.flat_map do |rv|
+            arg_sets[0].flat_map do |av0|
+              arg_sets[1].flat_map { |av1| invoke_ternary(rv, method_name, av0, av1) || [] }
+            end
+          end
+        end
+
         def unary_method_allowed?(receiver_value, method_name)
           unary_ops_for(receiver_value).include?(method_name) ||
             catalog_allows?(receiver_value, method_name)
@@ -226,6 +272,13 @@ module Rigor
             catalog_allows?(receiver_value, method_name)
         end
 
+        # 2-arg methods have no hand-rolled allow list; the catalog
+        # is the sole gate. Adding a per-class arity-2 set is reserved
+        # for future cases that need it.
+        def ternary_method_allowed?(receiver_value, method_name)
+          catalog_allows?(receiver_value, method_name)
+        end
+
         # Builds a Constant or Union[Constant…] from a flat list of
         # Ruby values. When the deduped set exceeds
         # `UNION_FOLD_OUTPUT_LIMIT` and every result is an Integer,
@@ -594,6 +647,19 @@ module Rigor
           nil
         end
 
+        # Returns `[value]` on success, `nil` to signal "skip this triple".
+        # Mirrors `invoke_binary` but for the 2-argument shape; the wrap
+        # convention lets callers `flat_map` without losing
+        # legitimate `false`/`nil` folds.
+        def invoke_ternary(receiver_value, method_name, av0, av1)
+          return nil unless ternary_method_allowed?(receiver_value, method_name)
+
+          result = receiver_value.public_send(method_name, av0, av1)
+          foldable_constant_value?(result) ? [result] : nil
+        rescue StandardError
+          nil
+        end
+
         # Returns `[value]` on success, `nil` to signal "skip". See
         # `invoke_binary` for why we wrap.
         def invoke_unary(receiver_value, method_name)
@@ -619,24 +685,92 @@ module Rigor
         # implementation does not call back into user-redefinable
         # Ruby methods, so executing them on a literal Integer/Float
         # is safe regardless of monkey-patching.
+        #
+        # Resolution order:
+        #
+        # 1. Primary class catalog (e.g. NumericCatalog for an
+        #    Integer receiver). When the catalog has an entry —
+        #    even one classified `:dispatch` — that answer wins.
+        #    The class's direct `rb_define_method` registration is
+        #    authoritative; we MUST NOT fall through to a module
+        #    catalog and risk over-folding.
+        # 2. Module catalogs (Comparable, Enumerable, …) that the
+        #    receiver's class includes by ancestry. Reached only
+        #    when the primary catalog has NO entry for the method
+        #    — typically because the method is inherited purely
+        #    through `include Comparable` / `include Enumerable`
+        #    (e.g. `Integer#between?` / `Integer#clamp` are not in
+        #    numeric.yml because the Init block does not
+        #    `rb_define_method` them on Integer).
         def catalog_allows?(receiver_value, method_name)
           catalog, class_name = catalog_for(receiver_value)
-          return false unless catalog
+          return catalog.safe_for_folding?(class_name, method_name) if catalog&.method_entry(class_name, method_name)
+
+          module_catalogs_for(receiver_value).any? do |mod_catalog, mod_name|
+            mod_catalog.method_entry(mod_name, method_name) &&
+              mod_catalog.safe_for_folding?(mod_name, method_name)
+          end
+        end
 
-          catalog.safe_for_folding?(class_name, method_name)
+        # `(Module, catalog, class_name)` triples consulted as a
+        # fallthrough when the primary class catalog has no entry.
+        # Each triple's Module is matched against the receiver
+        # class's ancestor chain at lookup time; the catalog
+        # corresponds to the module-mode YAML at
+        # `data/builtins/ruby_core/<topic>.yml`.
+        MODULE_CATALOGS = [
+          [Comparable, Builtins::COMPARABLE_CATALOG, "Comparable"],
+          [Enumerable, Builtins::ENUMERABLE_CATALOG, "Enumerable"]
+        ].freeze
+        private_constant :MODULE_CATALOGS
+
+        # Returns the `(catalog, class_name)` pairs for every
+        # registered module that is in the receiver's ancestor
+        # chain. The receiver's class's `Module#ancestors` is
+        # cached by Ruby; the `Set` membership check is cheap.
+        def module_catalogs_for(receiver_value)
+          ancestors = Set.new(receiver_value.class.ancestors)
+          MODULE_CATALOGS.filter_map do |mod, catalog, class_name|
+            [catalog, class_name] if ancestors.include?(mod)
+          end
         end
 
+        # `(catalog, class_name)` per receiver class. The class_name
+        # is what each catalog's RBS-rooted entries are keyed by.
+        # `catalog_for` walks this table in declaration order so
+        # subclasses (Symbol < String) hit their dedicated entry
+        # before any base-class fallback would, and adding a new
+        # class is a one-line addition rather than another `when`
+        # arm on a growing case statement.
+        # Subclass-before-superclass ordering: `DateTime < Date`,
+        # so the `DateTime` row MUST come before the `Date` row.
+        # Otherwise a `DateTime` receiver would match the `Date`
+        # arm first and the catalog would consult the Date entry
+        # in `DATE_CATALOG` for the wrong class.
+        CATALOG_BY_CLASS = [
+          [Integer,  [Builtins::NumericCatalog, "Integer"]],
+          [Float,    [Builtins::NumericCatalog, "Float"]],
+          [String,   [Builtins::STRING_CATALOG, "String"]],
+          [Symbol,   [Builtins::STRING_CATALOG, "Symbol"]],
+          [Array,    [Builtins::ARRAY_CATALOG,  "Array"]],
+          [Hash,     [Builtins::HASH_CATALOG,   "Hash"]],
+          [Range,    [Builtins::RANGE_CATALOG,  "Range"]],
+          [::Set,    [Builtins::SET_CATALOG,    "Set"]],
+          [Time,     [Builtins::TIME_CATALOG,   "Time"]],
+          [DateTime, [Builtins::DATE_CATALOG,   "DateTime"]],
+          [Date,     [Builtins::DATE_CATALOG,   "Date"]],
+          [Rational, [Builtins::RATIONAL_CATALOG, "Rational"]],
+          [Complex,  [Builtins::COMPLEX_CATALOG,  "Complex"]]
+        ].freeze
+        private_constant :CATALOG_BY_CLASS
+
         # Returns `[catalog, class_name]` for receivers we have a
-        # catalog for; nil otherwise. The class_name is what the
-        # catalog's RBS-rooted entries are keyed by.
+        # catalog for; nil otherwise.
         def catalog_for(receiver_value)
-          case receiver_value
-          when Integer then [Builtins::NumericCatalog, "Integer"]
-          when Float   then [Builtins::NumericCatalog, "Float"]
-          when String  then [Builtins::STRING_CATALOG, "String"]
-          when Symbol  then [Builtins::STRING_CATALOG, "Symbol"]
-          when Array   then [Builtins::ARRAY_CATALOG,  "Array"]
+          CATALOG_BY_CLASS.each do |klass, entry|
+            return entry if receiver_value.is_a?(klass)
           end
+          nil
         end
 
         def unary_ops_for(receiver_value)