rigortype 0.0.2 → 0.0.3

data/lib/rigor/analysis/check_rules.rb

@@ -53,6 +53,7 @@ module Rigor
       RULE_NIL_RECEIVER = "possible-nil-receiver"
       RULE_DUMP_TYPE = "dump-type"
       RULE_ASSERT_TYPE = "assert-type"
+      RULE_ALWAYS_RAISES = "always-raises"
 
       ALL_RULES = [
         RULE_UNDEFINED_METHOD,
@@ -60,7 +61,8 @@ module Rigor
         RULE_ARGUMENT_TYPE,
         RULE_NIL_RECEIVER,
         RULE_DUMP_TYPE,
-        RULE_ASSERT_TYPE
+        RULE_ASSERT_TYPE,
+        RULE_ALWAYS_RAISES
       ].freeze
 
       module_function
@@ -97,6 +99,9 @@ module Rigor
 
           assert_diagnostic = assert_type_diagnostic(path, node, scope_index)
           diagnostics << assert_diagnostic if assert_diagnostic
+
+          raises_diagnostic = always_raises_diagnostic(path, node, scope_index)
+          diagnostics << raises_diagnostic if raises_diagnostic
         end
         filter_suppressed(diagnostics, comments: comments, disabled_rules: disabled_rules)
       end
@@ -333,6 +338,13 @@ module Rigor
         end
 
         def arity_eligible?(function)
+          # `RBS::Types::UntypedFunction` (used for `(?) ->`
+          # untyped sigs) does not expose the per-arity
+          # accessors. Treating it as ineligible is the
+          # correct conservative move: an untyped function
+          # has no static arity to enforce.
+          return false unless function.respond_to?(:required_keywords)
+
           function.required_keywords.empty? && function.trailing_positionals.empty?
         end
 
@@ -562,6 +574,74 @@ module Rigor
           )
         end
 
+        # Diagnoses calls that the analyzer can prove will always
+        # raise. Today the only triggering shape is integer
+        # division/modulo by a literal zero divisor:
+        #
+        #   5 / 0          # => ZeroDivisionError
+        #   x.modulo(0)    # => ZeroDivisionError when x: Integer
+        #   xs.size % 0    # same — non_negative_int / Constant[0]
+        #
+        # Float divmod by zero returns Infinity/NaN at runtime, so
+        # the rule restricts to Integer-rooted receivers (`Constant`,
+        # `IntegerRange`, `Nominal[Integer]`). The argument MUST be a
+        # `Constant<Integer>` whose value is exactly zero — a
+        # `Union[Constant[0], Constant[2]]` divisor "may" raise,
+        # which we surface separately (future slice).
+        INTEGER_RAISING_OPERATORS = %i[/ % div modulo divmod].freeze
+        private_constant :INTEGER_RAISING_OPERATORS
+
+        def always_raises_diagnostic(path, call_node, scope_index)
+          return nil unless integer_zero_division?(call_node, scope_index)
+
+          build_always_raises_diagnostic(path, call_node)
+        end
+
+        def integer_zero_division?(call_node, scope_index)
+          return false unless raising_call_shape?(call_node)
+
+          scope = scope_index[call_node]
+          return false if scope.nil?
+          return false unless integer_rooted_for_diagnostic?(scope.type_of(call_node.receiver))
+
+          arg = single_argument(call_node)
+          arg && integer_zero_constant?(scope.type_of(arg))
+        end
+
+        def raising_call_shape?(call_node)
+          !call_node.receiver.nil? && INTEGER_RAISING_OPERATORS.include?(call_node.name)
+        end
+
+        def single_argument(call_node)
+          args = call_node.arguments&.arguments || []
+          args.size == 1 ? args.first : nil
+        end
+
+        def integer_rooted_for_diagnostic?(type)
+          case type
+          when Type::Constant then type.value.is_a?(Integer)
+          when Type::IntegerRange then true
+          when Type::Nominal then type.class_name == "Integer" && type.type_args.empty?
+          else false
+          end
+        end
+
+        def integer_zero_constant?(type)
+          type.is_a?(Type::Constant) && type.value.is_a?(Integer) && type.value.zero?
+        end
+
+        def build_always_raises_diagnostic(path, call_node)
+          location = call_node.message_loc || call_node.location
+          Diagnostic.new(
+            rule: RULE_ALWAYS_RAISES,
+            path: path,
+            line: location.start_line,
+            column: location.start_column + 1,
+            message: "always raises ZeroDivisionError: `#{call_node.name}' by zero on Integer receiver",
+            severity: :error
+          )
+        end
+
         # v0.0.2 #4 — argument-type-mismatch diagnostic.
         # Walks a call's positional arguments and checks each
         # against the matching parameter's RBS type via
@@ -643,6 +723,11 @@ module Rigor
         end
 
         def argument_check_eligible?(function)
+          # See `arity_eligible?`: `UntypedFunction` lacks
+          # the per-arity accessors. Treat it as ineligible
+          # for argument-type-mismatch diagnostics.
+          return false unless function.respond_to?(:required_keywords)
+
           function.rest_positionals.nil? &&
             function.required_keywords.empty? &&
             function.optional_keywords.empty? &&

data/lib/rigor/analysis/runner.rb

@@ -6,6 +6,7 @@ require_relative "../environment"
 require_relative "../scope"
 require_relative "../inference/coverage_scanner"
 require_relative "../inference/scope_indexer"
+require_relative "../inference/method_dispatcher/file_folding"
 require_relative "check_rules"
 require_relative "diagnostic"
 require_relative "result"
@@ -29,6 +30,9 @@ module Rigor
       # is built once at run start through `Environment.for_project`
       # so all files share the same RBS load.
       def run(paths = @configuration.paths)
+        Inference::MethodDispatcher::FileFolding.fold_platform_specific_paths =
+          @configuration.fold_platform_specific_paths
+
         environment = Environment.for_project(
           libraries: @configuration.libraries,
           signature_paths: @configuration.signature_paths

data/lib/rigor/builtins/imported_refinements.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "../type"
+
+module Rigor
+  module Builtins
+    # Canonical-name registry for the imported-built-in
+    # refinement catalogue. See `imported-built-in-types.md`
+    # in `docs/type-specification/` for the full catalogue
+    # rationale and the kebab-case naming rule.
+    #
+    # Maps kebab-case names (`non-empty-string`, `positive-int`,
+    # `non-empty-array`, …) to the Rigor type each name denotes.
+    # The registry is the single integration point for:
+    #
+    # - The new `rigor:v1:return:` RBS::Extended directive
+    #   ([`Rigor::RbsExtended.read_return_type_override`](../rbs_extended.rb)),
+    #   which overrides a method's RBS-declared return type
+    #   with a refinement carrier.
+    # - Future `RBS::Extended` directives that accept a
+    #   refinement name in any type position (`param:`,
+    #   `assert: x is non-empty-string`, …).
+    # - The display side: `Type::Difference#describe` already
+    #   recognises the same shapes and prints the kebab-case
+    #   spelling without consulting the registry.
+    #
+    # Names not in the registry resolve to `nil`; callers
+    # decide whether to fall back to the RBS-declared type or
+    # raise a parse error.
+    #
+    # The current registry covers no-argument refinement
+    # names. Parameterised refinements like
+    # `non-empty-array[Integer]` will be parsed by a future
+    # tokeniser; today the no-arg form `non-empty-array` lands
+    # at `non_empty_array(top)` and downstream code projects
+    # to the underlying base nominal.
+    module ImportedRefinements
+      REGISTRY = {
+        "non-empty-string" => -> { Type::Combinator.non_empty_string },
+        "non-zero-int" => -> { Type::Combinator.non_zero_int },
+        "non-empty-array" => -> { Type::Combinator.non_empty_array },
+        "non-empty-hash" => -> { Type::Combinator.non_empty_hash },
+        "positive-int" => -> { Type::Combinator.positive_int },
+        "non-negative-int" => -> { Type::Combinator.non_negative_int },
+        "negative-int" => -> { Type::Combinator.negative_int },
+        "non-positive-int" => -> { Type::Combinator.non_positive_int }
+      }.freeze
+      private_constant :REGISTRY
+
+      module_function
+
+      # @param name [String] kebab-case refinement name.
+      # @return [Rigor::Type, nil] the matching refinement
+      #   carrier, or `nil` if the name is not registered.
+      def lookup(name)
+        builder = REGISTRY[name.to_s]
+        builder&.call
+      end
+
+      def known?(name)
+        REGISTRY.key?(name.to_s)
+      end
+
+      def known_names
+        REGISTRY.keys
+      end
+    end
+  end
+end

data/lib/rigor/configuration.rb

@@ -12,13 +12,14 @@ module Rigor
       "disable" => [],
       "libraries" => [],
       "signature_paths" => nil,
+      "fold_platform_specific_paths" => false,
       "cache" => {
         "path" => ".rigor/cache"
       }
     }.freeze
 
     attr_reader :target_ruby, :paths, :plugins, :cache_path, :disabled_rules,
-                :libraries, :signature_paths
+                :libraries, :signature_paths, :fold_platform_specific_paths
 
     def self.load(path = DEFAULT_PATH)
       data = if File.exist?(path)
@@ -40,6 +41,9 @@ module Rigor
       @libraries = Array(data.fetch("libraries", DEFAULTS.fetch("libraries"))).map(&:to_s).freeze
       sig_paths = data.fetch("signature_paths", DEFAULTS.fetch("signature_paths"))
       @signature_paths = sig_paths.nil? ? nil : Array(sig_paths).map(&:to_s).freeze
+      @fold_platform_specific_paths = data.fetch(
+        "fold_platform_specific_paths", DEFAULTS.fetch("fold_platform_specific_paths")
+      ) == true
       @cache_path = cache.fetch("path").to_s
     end
 
@@ -51,6 +55,7 @@ module Rigor
         "disable" => disabled_rules,
         "libraries" => libraries,
         "signature_paths" => signature_paths,
+        "fold_platform_specific_paths" => fold_platform_specific_paths,
         "cache" => {
           "path" => cache_path
         }

data/lib/rigor/inference/acceptance.rb

@@ -64,6 +64,8 @@ module Rigor
         Type::Singleton => :accepts_singleton,
         Type::Nominal => :accepts_nominal,
         Type::Constant => :accepts_constant,
+        Type::IntegerRange => :accepts_integer_range,
+        Type::Difference => :accepts_difference,
         Type::Tuple => :accepts_tuple,
         Type::HashShape => :accepts_hash_shape
       }.freeze
@@ -190,6 +192,8 @@ module Rigor
             accepts_nominal_from_constant(self_type, other_type, mode)
           when Type::Singleton
             accepts_nominal_from_singleton(self_type, other_type, mode)
+          when Type::IntegerRange
+            accepts_nominal_from_integer_range(self_type, other_type, mode)
           when Type::Tuple
             accepts(self_type, project_tuple_to_nominal(other_type), mode: mode)
               .with_reason("projected Tuple to Nominal[Array]")
@@ -204,6 +208,33 @@ module Rigor
           end
         end
 
+        # `Nominal[Integer]` (and anything Integer is-a, like Numeric) accepts
+        # any `IntegerRange`; nothing else does. Argument-bearing `Nominal`s
+        # never accept `IntegerRange` because IntegerRange has no type args.
+        INTEGER_NOMINAL_ANCESTORS = %w[Integer Numeric Comparable Object BasicObject].freeze
+        private_constant :INTEGER_NOMINAL_ANCESTORS
+
+        def accepts_nominal_from_integer_range(self_type, _other_type, mode)
+          unless self_type.type_args.empty?
+            return Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "Nominal[#{self_type.class_name}] with type args rejects IntegerRange"
+            )
+          end
+
+          if INTEGER_NOMINAL_ANCESTORS.include?(self_type.class_name)
+            Type::AcceptsResult.yes(
+              mode: mode,
+              reasons: "IntegerRange is-a #{self_type.class_name}"
+            )
+          else
+            Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "Nominal[#{self_type.class_name}] rejects IntegerRange"
+            )
+          end
+        end
+
         # v0.0.2 — meta-type rule. A `Singleton[T]` is the
         # class object for `T`, so it is an instance of
         # `Class` (when `T` is a class) and always an instance
@@ -344,6 +375,124 @@ module Rigor
           end
         end
 
+        # IntegerRange[a..b] accepts:
+        # - Constant[n] where n is an Integer covered by [a..b];
+        # - IntegerRange[c..d] where [c..d] ⊆ [a..b];
+        # - Nominal[Integer] only when self is the universal range
+        #   (`int<min, max>`), since otherwise an arbitrary Integer
+        #   could fall outside the bound.
+        # Anything else is rejected.
+        def accepts_integer_range(self_type, other_type, mode)
+          case other_type
+          when Type::Constant
+            accepts_integer_range_from_constant(self_type, other_type, mode)
+          when Type::IntegerRange
+            accepts_integer_range_from_integer_range(self_type, other_type, mode)
+          when Type::Nominal
+            accepts_integer_range_from_nominal(self_type, other_type, mode)
+          else
+            Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "IntegerRange rejects #{other_type.class}"
+            )
+          end
+        end
+
+        def accepts_integer_range_from_constant(self_type, constant, mode)
+          unless constant.value.is_a?(Integer)
+            return Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "IntegerRange rejects non-Integer Constant"
+            )
+          end
+
+          if self_type.covers?(constant.value)
+            Type::AcceptsResult.yes(
+              mode: mode,
+              reasons: "Constant[#{constant.value}] is in #{self_type.describe}"
+            )
+          else
+            Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "Constant[#{constant.value}] outside #{self_type.describe}"
+            )
+          end
+        end
+
+        def accepts_integer_range_from_integer_range(self_type, other_range, mode)
+          if self_type.lower <= other_range.lower && other_range.upper <= self_type.upper
+            Type::AcceptsResult.yes(
+              mode: mode,
+              reasons: "#{other_range.describe} ⊆ #{self_type.describe}"
+            )
+          else
+            Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "#{other_range.describe} not contained in #{self_type.describe}"
+            )
+          end
+        end
+
+        def accepts_integer_range_from_nominal(self_type, nominal, mode)
+          unless nominal.class_name == "Integer"
+            return Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "IntegerRange rejects Nominal[#{nominal.class_name}]"
+            )
+          end
+
+          if self_type.universal?
+            Type::AcceptsResult.yes(
+              mode: mode,
+              reasons: "universal IntegerRange accepts Nominal[Integer]"
+            )
+          else
+            Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "non-universal IntegerRange rejects Nominal[Integer] (could fall outside #{self_type.describe})"
+            )
+          end
+        end
+
+        # `Difference[base, removed]` accepts another type X when
+        # the base accepts X *and* X's value set is provably
+        # disjoint from `removed`. The disjointness test is the
+        # subtle part — it is NOT the same as `removed.accepts(X)`,
+        # because `Nominal[String]` includes `""` even though
+        # `Constant[""]` does not "accept" `Nominal[String]`.
+        # The conservative rule here: we can prove disjointness
+        # only when X is itself a `Constant` carrier (compare
+        # values directly) or another `Difference` with the same
+        # removed value (already exhibits the disjointness). Any
+        # other shape — Nominal, Union, IntegerRange — could
+        # overlap the removed value, so the difference rejects
+        # it under gradual mode.
+        def accepts_difference(self_type, other_type, mode)
+          base_result = accepts(self_type.base, other_type, mode: mode)
+          return base_result if base_result.no?
+
+          unless provably_disjoint_from_removed?(other_type, self_type.removed)
+            return Type::AcceptsResult.no(
+              mode: mode,
+              reasons: "#{self_type.describe} cannot prove #{other_type.class} excludes the removed value"
+            )
+          end
+
+          base_result.with_reason("#{self_type.describe}: base accepts and removed is disjoint")
+        end
+
+        def provably_disjoint_from_removed?(other_type, removed)
+          case other_type
+          when Type::Constant
+            !(removed.is_a?(Type::Constant) && removed.value == other_type.value)
+          when Type::Difference
+            # `Difference[A, removed_R].accepts(Difference[B, R])` —
+            # the inner difference exhibits the same disjointness;
+            # forward to the base.
+            other_type.removed == removed && provably_disjoint_from_removed?(other_type.base, removed)
+          end
+        end
+
         # Constant[v] accepts only Constant[v'] with structurally equal
         # value. Any other type is rejected (modulo the universal
         # Bot/Dynamic short-circuits already applied upstream).

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "method_catalog"
+
+module Rigor
+  module Inference
+    module Builtins
+      # `Array` catalog. Singleton — load once, consult during dispatch.
+      #
+      # Array has more mutation surface than String: every method that
+      # logically reshapes the array tends to call `rb_ary_modify` or
+      # an internal helper (`ary_replace`, `ary_resize`, `ary_pop`,
+      # `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__
+        ),
+        mutating_selectors: {
+          "Array" => Set[
+            # Mutators classified `:leaf` by the C-body heuristic
+            :<<, :push, :replace, :clear, :concat, :insert, :"[]=",
+            :unshift, :prepend, :pop, :shift, :delete_at, :slice!,
+            :compact!, :flatten!, :uniq!, :sort!, :reverse!,
+            :rotate!, :keep_if, :delete_if, :select!, :filter!,
+            :reject!, :collect!, :map!, :assoc, :rassoc,
+            :fill, :delete, :transpose,
+            # Methods that yield (block-dependent) — classifier
+            # may mark them leaf when the block call is gated:
+            :each, :each_with_index, :each_index, :each_slice,
+            :each_cons, :each_with_object,
+            # Identity/comparison methods that take a block too
+            :max, :min, :max_by, :min_by, :minmax, :minmax_by,
+            :sort_by, :group_by, :partition, :all?, :any?, :none?,
+            :one?, :find, :detect, :find_all, :find_index,
+            :reduce, :inject, :flat_map, :collect_concat,
+            :zip, :product, :combination, :permutation,
+            :chunk_while, :slice_when, :tally
+          ]
+        }
+      )
+    end
+  end
+end

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Rigor
+  module Inference
+    module Builtins
+      # Generic loader for offline-generated catalogs under
+      # `data/builtins/ruby_core/<topic>.yml`. One instance per topic
+      # (numeric, string, array, …); each owns the path to its own
+      # YAML and the per-class blocklist of selectors the static
+      # classifier marked `:leaf` but that actually mutate the
+      # receiver (false positives the C-body heuristic does not
+      # catch).
+      #
+      # `safe_for_folding?(class_name, selector, kind:)` returns true
+      # when:
+      # 1. The catalog has an entry for `(class_name, selector, kind)`,
+      # 2. The entry's `purity` is one of `leaf` / `trivial` /
+      #    `leaf_when_numeric`,
+      # 3. The selector is NOT in the per-class mutation blocklist.
+      #
+      # Missing catalog files (e.g. in a bare gem install where data
+      # was opted out) degrade to `false` so the dispatcher falls
+      # back to its hand-rolled allow lists.
+      class MethodCatalog
+        FOLDABLE_PURITIES = Set["leaf", "trivial", "leaf_when_numeric"].freeze
+        EMPTY_CATALOG = { "classes" => {} }.freeze
+
+        def initialize(path:, mutating_selectors: {})
+          @path = path
+          @mutating_selectors = mutating_selectors.transform_values(&:freeze).freeze
+          @catalog = nil
+        end
+
+        def safe_for_folding?(class_name, selector, kind: :instance)
+          class_name_str = class_name.to_s
+          return false if blocked?(class_name_str, selector)
+
+          entry = method_entry(class_name_str, selector, kind: kind)
+          return false unless entry
+
+          FOLDABLE_PURITIES.include?(entry["purity"])
+        end
+
+        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
+
+        def reset!
+          @catalog = nil
+        end
+
+        private
+
+        def blocked?(class_name, selector)
+          # Bang-suffixed selectors are mutating by Ruby convention
+          # (`upcase!`, `concat`, etc. are listed explicitly below;
+          # this catches the rest). We bias toward false negatives:
+          # losing a fold opportunity is acceptable; folding a
+          # mutator is not.
+          selector_str = selector.to_s
+          return true if selector_str.end_with?("!")
+
+          per_class = @mutating_selectors[class_name]
+          return false if per_class.nil?
+
+          per_class.include?(selector.to_sym) || per_class.include?(selector_str.to_sym)
+        end
+
+        def catalog
+          @catalog ||= load_catalog
+        end
+
+        def load_catalog
+          return EMPTY_CATALOG unless File.exist?(@path)
+
+          data = YAML.safe_load_file(@path, permitted_classes: [Symbol])
+          data.is_a?(Hash) ? data : EMPTY_CATALOG
+        rescue Psych::SyntaxError
+          EMPTY_CATALOG
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+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`.
+      #
+      # 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.
+          def reset!
+            @catalog = nil
+          end
+
+          private
+
+          def catalog
+            @catalog ||= load_catalog
+          end
+
+          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
+      end
+    end
+  end
+end