rigortype 0.1.16 → 0.1.17

data/lib/rigor/environment/rbs_loader.rb

@@ -501,6 +501,27 @@ module Rigor
         # registry rather than crashing.
       end
 
+      # Like {#each_class_decl_annotation}, but also yields the
+      # owning class / module's RBS name as the first block
+      # argument: `(class_name, annotation_string, location)`. Used
+      # by {Rigor::RbsExtended::ConformanceChecker} to resolve a
+      # `rigor:v1:conforms-to` directive back to the class it
+      # annotates. Same fail-soft policy as the un-named variant.
+      def each_class_decl_annotation_with_name
+        return enum_for(:each_class_decl_annotation_with_name) unless block_given?
+        return if env.nil?
+
+        env.class_decls.each do |rbs_name, entry|
+          entry.each_decl do |decl|
+            next unless decl.respond_to?(:annotations)
+
+            decl.annotations.each { |a| yield rbs_name.to_s, a.string, a.location }
+          end
+        end
+      rescue ::RBS::BaseError, ::Ractor::IsolationError
+        # fail-soft: see #each_class_decl_annotation.
+      end
+
       # Returns a frozen `Hash<String, String>` mapping each loaded
       # class / module name (top-level prefixed) to the file path of
       # its FIRST declaration's RBS source. Used by
@@ -571,6 +592,44 @@ module Rigor
         definition.methods[method_name.to_sym]
       end
 
+      # @return [Array<Symbol>, nil] every instance-method name on
+      #   `class_name` — own, inherited, and included — as resolved
+      #   by `RBS::DefinitionBuilder`. Returns `nil` (NOT `[]`) when
+      #   the class definition cannot be built so callers can tell
+      #   "no methods" apart from "unknown class". Used by the
+      #   `rigor:v1:conforms-to` presence check
+      #   ({Rigor::RbsExtended::ConformanceChecker}).
+      def instance_method_names(class_name)
+        definition = instance_definition(class_name)
+        return nil unless definition
+
+        definition.methods.keys
+      end
+
+      # @return [RBS::Definition, nil] the built definition for the RBS
+      #   interface `interface_name` (`_RewindableStream`), whose `.methods`
+      #   are the required members (including interface-ancestor members).
+      #   Returns `nil` when the name does not resolve to a loaded interface
+      #   (a typo, or the defining library / sig set is not on the load
+      #   path). Fail-soft on RBS build errors.
+      def interface_definition(interface_name)
+        rbs_name = parse_type_name(interface_name)
+        return nil unless rbs_name
+        return nil if env.nil?
+        return nil unless env.interface_decls.key?(rbs_name)
+
+        builder.build_interface(rbs_name)
+      rescue ::RBS::BaseError
+        nil
+      end
+
+      # @return [Array<Symbol>, nil] every method name required by the RBS
+      #   interface `interface_name`, or nil when it does not resolve. Thin
+      #   accessor over {#interface_definition} for the presence check.
+      def interface_method_names(interface_name)
+        interface_definition(interface_name)&.methods&.keys
+      end
+
       # @return [RBS::Definition, nil] the resolved singleton (class
       #   object) definition for `class_name`. The methods on this
       #   definition are the *class methods* of `class_name`, including
@@ -983,14 +1042,28 @@ module Rigor
         nil
       end
 
+      # Memoised on `@state` (the per-loader store also holding `:env` /
+      # `:builder`): `RBS::TypeName.parse` is a pure, deterministic
+      # function of the normalised string, and the `RBS::TypeName` it
+      # returns is a frozen value object safe to share across callers
+      # (every consumer only reads it — `env.class_decls.key?` /
+      # `builder.build_*`). The same handful of class names are parsed
+      # on nearly every call-site dispatch, so this was a top allocation
+      # site; caching the immutable result (nil included) removes it.
       def parse_type_name(name)
         s = name.to_s
         return nil if s.empty?
 
         s = "::#{s}" unless s.start_with?("::")
-        RBS::TypeName.parse(s)
-      rescue ::RBS::BaseError
-        nil
+        cache = (@state[:type_name_cache] ||= {})
+        return cache[s] if cache.key?(s)
+
+        cache[s] =
+          begin
+            RBS::TypeName.parse(s)
+          rescue ::RBS::BaseError
+            nil
+          end
       end
 
       def compute_class_known(name)

data/lib/rigor/inference/block_parameter_binder.rb

@@ -174,8 +174,7 @@ module Rigor
 
       def bind_trailing_positionals(params_node, bindings, cursor)
         params_node.posts.each do |param|
-          name = required_name(param)
-          bindings[name] = positional_type_at(cursor) if name
+          bind_required_param(param, cursor, bindings)
           cursor += 1
         end
         cursor

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

@@ -13,11 +13,8 @@ module Rigor
       # `ary_push_internal`, …) that the classifier does not yet
       # recognise. The blocklist captures the methods we have
       # specifically observed flowing as `:leaf` despite mutating.
-      ARRAY_CATALOG = MethodCatalog.new(
-        path: File.expand_path(
-          "../../../../data/builtins/ruby_core/array.yml",
-          __dir__
-        ),
+      ARRAY_CATALOG = MethodCatalog.for_topic(
+        "array",
         mutating_selectors: {
           "Array" => Set[
             # Mutators classified `:leaf` by the C-body heuristic

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

@@ -13,11 +13,8 @@ module Rigor
       # (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.
-      COMPARABLE_CATALOG = MethodCatalog.new(
-        path: File.expand_path(
-          "../../../../data/builtins/ruby_core/comparable.yml",
-          __dir__
-        ),
+      COMPARABLE_CATALOG = MethodCatalog.for_topic(
+        "comparable",
         mutating_selectors: {
           "Comparable" => Set[]
         }

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

@@ -21,11 +21,8 @@ module Rigor
       # so a hypothetical future `Constant<Complex>` carrier cannot
       # fold an aliasing copy through the catalog (mirrors
       # `range_catalog.rb`, `time_catalog.rb`, `date_catalog.rb`).
-      COMPLEX_CATALOG = MethodCatalog.new(
-        path: File.expand_path(
-          "../../../../data/builtins/ruby_core/complex.yml",
-          __dir__
-        ),
+      COMPLEX_CATALOG = MethodCatalog.for_topic(
+        "complex",
         mutating_selectors: {
           "Complex" => Set[
             # Defence in depth: `Complex` does not currently expose

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

@@ -54,11 +54,8 @@ module Rigor
       # 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__
-        ),
+      DATE_CATALOG = MethodCatalog.for_topic(
+        "date",
         mutating_selectors: {
           "Date" => Set[
             # `d_lite_initialize_copy` is already classed

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

@@ -22,11 +22,8 @@ module Rigor
       # against the analyzer process's registry — what UTF-8's
       # alias list is in the analyzer is not necessarily what it
       # is in the analysed program.
-      ENCODING_CATALOG = MethodCatalog.new(
-        path: File.expand_path(
-          "../../../../data/builtins/ruby_core/encoding.yml",
-          __dir__
-        ),
+      ENCODING_CATALOG = MethodCatalog.for_topic(
+        "encoding",
         mutating_selectors: {
           "Encoding" => Set[
             # Defence-in-depth: mirrors range_catalog.rb /

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

@@ -13,11 +13,8 @@ module Rigor
       # (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__
-        ),
+      ENUMERABLE_CATALOG = MethodCatalog.for_topic(
+        "enumerable",
         mutating_selectors: {
           "Enumerable" => Set[]
         }

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

@@ -26,11 +26,8 @@ module Rigor
       # already declines) or blocklisted because the static classifier
       # missed an indirect side effect. The remaining `:leaf` method
       # that DOES fold is `#cause`, a pure accessor.
-      EXCEPTION_CATALOG = MethodCatalog.new(
-        path: File.expand_path(
-          "../../../../data/builtins/ruby_core/exception.yml",
-          __dir__
-        ),
+      EXCEPTION_CATALOG = MethodCatalog.for_topic(
+        "exception",
         mutating_selectors: {
           "Exception" => Set[
             # `exc_initialize` writes `mesg` / `backtrace` ivars on

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

@@ -15,11 +15,8 @@ module Rigor
       # 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__
-        ),
+      HASH_CATALOG = MethodCatalog.for_topic(
+        "hash",
         mutating_selectors: {
           "Hash" => Set[
             # Block-dependent iteration — yields via `rb_hash_foreach`

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

@@ -27,6 +27,21 @@ module Rigor
         FOLDABLE_PURITIES = Set["leaf", "trivial", "leaf_when_numeric"].freeze
         EMPTY_CATALOG = { "classes" => {} }.freeze
 
+        # Shared root for the offline-generated catalogues. Resolving it
+        # here keeps the repo-relative `../../../../` hop in one place
+        # instead of copying it into every per-topic loader.
+        DATA_ROOT = File.expand_path("../../../../data/builtins/ruby_core", __dir__)
+        private_constant :DATA_ROOT
+
+        # Build a catalog for a named topic, resolving its YAML path
+        # under {DATA_ROOT}. Equivalent to `new(path: …)` for the common
+        # case where the file is `<topic>.yml`; prefer this over passing
+        # an explicit `File.expand_path` so the data-root hop stays
+        # centralised.
+        def self.for_topic(topic, mutating_selectors: {})
+          new(path: File.join(DATA_ROOT, "#{topic}.yml"), mutating_selectors: mutating_selectors)
+        end
+
         def initialize(path:, mutating_selectors: {})
           @path = path
           @mutating_selectors = mutating_selectors.transform_values(&:freeze).freeze

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

@@ -1,104 +1,32 @@
 # frozen_string_literal: true
 
-require "yaml"
+require_relative "method_catalog"
 
 module Rigor
   module Inference
     module Builtins
-      # Read-only loader for the Numeric/Integer/Float built-in method
-      # catalog at `data/builtins/ruby_core/numeric.yml`. The catalog is
-      # produced offline by `tool/extract_numeric_catalog.rb` from the
-      # CRuby reference checkout under `references/ruby` plus the RBS
-      # core signatures under `references/rbs`.
+      # `Numeric` family catalog (Integer, Float, Rational, Complex,
+      # Numeric). Singleton — load once, consult during dispatch.
       #
-      # The loader is the runtime bridge: callers ask "is `Integer#+`
-      # safe to invoke during constant folding?" and the answer comes
-      # straight from the offline classification (`leaf`, `trivial`,
-      # `leaf_when_numeric` are foldable; everything else is not).
+      # The catalog is produced offline by `tool/extract_builtin_catalog.rb`
+      # from the CRuby reference checkout under `references/ruby` plus the
+      # RBS core signatures under `references/rbs`. The loader is the
+      # runtime bridge: callers ask "is `Integer#+` safe to invoke during
+      # constant folding?" and the answer comes straight from the offline
+      # classification (`leaf` / `trivial` / `leaf_when_numeric` are
+      # foldable; everything else is not).
       #
-      # The catalog is loaded lazily on first access and memoised for
-      # the lifetime of the process. If the file is missing (e.g. in a
-      # bare gem install where the consumer opted out of shipping data
-      # files, or in a development checkout that has not yet generated
-      # the catalog) the loader degrades to an empty catalog so calls
-      # uniformly return `false` and the rest of the dispatcher
-      # continues with its hand-rolled allow lists.
-      module NumericCatalog
-        # Purity tags from the catalog that are safe for the analyzer
-        # to invoke against concrete literal receivers/arguments.
-        # `leaf_when_numeric` is included because `ConstantFolding`
-        # only lets it through when every argument is itself a
-        # `Constant<Numeric>` or `IntegerRange` — exactly the gate
-        # the catalog tag is named for.
-        FOLDABLE_PURITIES = Set["leaf", "trivial", "leaf_when_numeric"].freeze
-
-        EMPTY_CATALOG = { "classes" => {} }.freeze
-        private_constant :EMPTY_CATALOG
-
-        # Path resolved relative to this file. The catalog ships under
-        # `data/builtins/ruby_core/numeric.yml` at the gem root.
-        CATALOG_PATH = File.expand_path(
-          "../../../../data/builtins/ruby_core/numeric.yml",
-          __dir__
-        )
-        private_constant :CATALOG_PATH
-
-        class << self
-          # @param class_name [String] e.g. "Integer", "Float"
-          # @param selector [Symbol, String]
-          # @param kind [Symbol] :instance (default) or :singleton
-          # @return [Boolean]
-          def safe_for_folding?(class_name, selector, kind: :instance)
-            entry = method_entry(class_name, selector, kind: kind)
-            return false unless entry
-
-            FOLDABLE_PURITIES.include?(entry["purity"])
-          end
-
-          # @return [Hash, nil] catalog entry for the given method, or
-          #   nil when the method is not registered.
-          def method_entry(class_name, selector, kind: :instance)
-            klass = catalog.dig("classes", class_name.to_s)
-            return nil unless klass
-
-            bucket_key = kind == :singleton ? "singleton_methods" : "instance_methods"
-            klass.dig(bucket_key, selector.to_s)
-          end
-
-          # Used by tests to drop the cached catalog so a different
-          # path or content can be exercised. Production code MUST
-          # NOT call this during normal operation.
-          #
-          # ADR-15 Phase 4b.x — reset re-loads eagerly so the
-          # singleton-class `@catalog` ivar stays populated, and
-          # the loaded Hash is deep-shared via `Ractor.make_shareable`
-          # so a worker Ractor reading the ivar via `catalog.dig(...)`
-          # does not trip `Ractor::IsolationError`. Plain `.freeze`
-          # is insufficient: YAML parses to a nested Hash/Array/String
-          # graph and only the outer Hash would be frozen.
-          def reset!
-            @catalog = Ractor.make_shareable(load_catalog)
-          end
-
-          private
-
-          attr_reader :catalog
-
-          def load_catalog
-            return EMPTY_CATALOG unless File.exist?(CATALOG_PATH)
-
-            data = YAML.safe_load_file(CATALOG_PATH, permitted_classes: [Symbol])
-            data.is_a?(Hash) ? data : EMPTY_CATALOG
-          rescue Psych::SyntaxError
-            EMPTY_CATALOG
-          end
-        end
-
-        # ADR-15 Phase 4b.x — eager-load on the main Ractor at
-        # module-load time so worker Ractors only READ the
-        # populated singleton-class `@catalog` ivar.
-        reset!
-      end
+      # No mutation blocklist is needed. The numeric classes expose no
+      # foldable bang or indirect-mutator method that the static C
+      # classifier mis-attributes (every `:leaf` numeric method is a pure
+      # value computation), so the generic `MethodCatalog` loader — shared
+      # with the eighteen other per-class catalogs — covers it directly.
+      # This previously hand-rolled its own `safe_for_folding?` /
+      # `method_entry` / `load_catalog` copy of `MethodCatalog`; folding
+      # it onto the shared loader also picks up alias resolution (e.g.
+      # `Integer#magnitude` → `abs`, `Integer#inspect` → `to_s`), which the
+      # old bespoke loader silently dropped.
+      NUMERIC_CATALOG = MethodCatalog.for_topic("numeric")
     end
   end
 end

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

@@ -16,11 +16,8 @@ module Rigor
       # helper that triggered the false positive (see
       # `string_catalog.rb`, `array_catalog.rb`, `time_catalog.rb`
       # for the canonical shape).
-      PATHNAME_CATALOG = MethodCatalog.new(
-        path: File.expand_path(
-          "../../../../data/builtins/ruby_core/pathname.yml",
-          __dir__
-        ),
+      PATHNAME_CATALOG = MethodCatalog.for_topic(
+        "pathname",
         mutating_selectors: {
           "Pathname" => Set[
           # initialize_copy is blocklisted by convention so a

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

@@ -31,11 +31,8 @@ module Rigor
       # `#source_location`, `#name`, `#owner`, `#receiver`) remain
       # foldable; the RBS tier still resolves return types for
       # the blocklisted methods so callers do not lose precision.
-      PROC_CATALOG = MethodCatalog.new(
-        path: File.expand_path(
-          "../../../../data/builtins/ruby_core/proc.yml",
-          __dir__
-        ),
+      PROC_CATALOG = MethodCatalog.for_topic(
+        "proc",
         mutating_selectors: {
           "Proc" => Set[
             # `#call` / `#[]` / `#===` / `#yield` invoke the proc

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

@@ -21,11 +21,8 @@ module Rigor
       # functionally pure they would produce a misleading constant
       # at fold time. The whole class is conservative-by-default
       # at the catalog tier; precision flows through the RBS layer.
-      RANDOM_CATALOG = MethodCatalog.new(
-        path: File.expand_path(
-          "../../../../data/builtins/ruby_core/random.yml",
-          __dir__
-        ),
+      RANDOM_CATALOG = MethodCatalog.for_topic(
+        "random",
         mutating_selectors: {
           "Random" => Set[
             # `rand_random` -> `random_real` / `random_ulong_limited`

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

@@ -15,11 +15,8 @@ module Rigor
       # 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__
-        ),
+      RANGE_CATALOG = MethodCatalog.for_topic(
+        "range",
         mutating_selectors: {
           "Range" => Set[
             # `range_initialize` / `range_initialize_copy` write

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

@@ -22,11 +22,8 @@ module Rigor
       # 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__
-        ),
+      RATIONAL_CATALOG = MethodCatalog.for_topic(
+        "rational",
         mutating_selectors: {
           "Rational" => Set[
             :initialize_copy

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

@@ -38,11 +38,8 @@ module Rigor
       # signatures already widen the answer enough to keep the
       # behaviour sound; revisit if the dispatcher ever grows a
       # singleton-aware catalog path.
-      REGEXP_CATALOG = MethodCatalog.new(
-        path: File.expand_path(
-          "../../../../data/builtins/ruby_core/re.yml",
-          __dir__
-        ),
+      REGEXP_CATALOG = MethodCatalog.for_topic(
+        "re",
         mutating_selectors: {
           "Regexp" => Set[
             # Defensive: aliasing-copy semantics already covered

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

@@ -19,11 +19,8 @@ module Rigor
       # (`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__
-        ),
+      SET_CATALOG = MethodCatalog.for_topic(
+        "set",
         mutating_selectors: {
           "Set" => Set[
             # Indirect mutators classified `:leaf` because the C

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

@@ -15,11 +15,8 @@ module Rigor
       # mutation primitives). Adding to the blocklist is the
       # corrective surface for false positives until the
       # classifier learns the helper functions.
-      STRING_CATALOG = MethodCatalog.new(
-        path: File.expand_path(
-          "../../../../data/builtins/ruby_core/string.yml",
-          __dir__
-        ),
+      STRING_CATALOG = MethodCatalog.for_topic(
+        "string",
         mutating_selectors: {
           "String" => Set[
             :replace, :initialize, :initialize_copy, :clear, :<<, :concat, :insert,

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

@@ -23,11 +23,8 @@ module Rigor
       # member but the answer depends on the subclass's member
       # definition, which the catalog does not see, so we blocklist
       # it defensively.
-      STRUCT_CATALOG = MethodCatalog.new(
-        path: File.expand_path(
-          "../../../../data/builtins/ruby_core/struct.yml",
-          __dir__
-        ),
+      STRUCT_CATALOG = MethodCatalog.for_topic(
+        "struct",
         mutating_selectors: {
           "Struct" => Set[
             # Defensive: aliasing-copy semantics on a hypothetical

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

@@ -29,11 +29,8 @@ module Rigor
       # 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__
-        ),
+      TIME_CATALOG = MethodCatalog.for_topic(
+        "time",
         mutating_selectors: {
           "Time" => Set[
             # `time_init_copy` writes the `timew` and `vtm` slots on