rigortype 0.0.1 → 0.0.3

data/lib/rigor/cli/type_scan_command.rb

@@ -3,6 +3,7 @@
 require "optionparser"
 require "prism"
 
+require_relative "../configuration"
 require_relative "../environment"
 require_relative "../inference/coverage_scanner"
 require_relative "../scope"
@@ -44,11 +45,13 @@ module Rigor
       private
 
       def parse_options
-        options = { format: "text", limit: 10, show_recognized: false, threshold: nil }
+        options = { format: "text", limit: 10, show_recognized: false, threshold: nil,
+                    config: Configuration::DEFAULT_PATH }
 
         parser = OptionParser.new do |opts|
           opts.banner = USAGE
           opts.on("--format=FORMAT", "Output format: text or json") { |value| options[:format] = value }
+          opts.on("--config=PATH", "Path to the Rigor configuration file") { |value| options[:config] = value }
           opts.on("--limit=N", Integer, "Max example events to print (text only)") do |value|
             options[:limit] = value
           end
@@ -86,7 +89,8 @@ module Rigor
       end
 
       def scan_paths(paths, options)
-        scope = Scope.empty(environment: project_environment)
+        configuration = Configuration.load(options.fetch(:config))
+        scope = Scope.empty(environment: project_environment(configuration))
         scanner = Inference::CoverageScanner.new(scope: scope)
         accumulator = ScanAccumulator.new
         paths.each { |path| scan_one(path, scanner, accumulator) }
@@ -94,12 +98,13 @@ module Rigor
       end
 
       # Builds a project-aware environment that auto-detects `<cwd>/sig`
-      # so calls scoped to the current project resolve through the
-      # local RBS tree. Phase 2a does not yet wire stdlib opt-in here;
-      # that lands when the configuration layer (`.rigor.yml`) gains an
-      # `rbs:` section.
-      def project_environment
-        Environment.for_project
+      # by default and honours the configuration's `libraries:` /
+      # `signature_paths:` keys when present.
+      def project_environment(configuration)
+        Environment.for_project(
+          libraries: configuration.libraries,
+          signature_paths: configuration.signature_paths
+        )
       end
 
       def scan_one(path, scanner, accumulator)

data/lib/rigor/cli.rb

@@ -68,19 +68,21 @@ module Rigor
 
       options = {
         config: Configuration::DEFAULT_PATH,
-        format: "text"
+        format: "text",
+        explain: false
       }
 
       parser = OptionParser.new do |opts|
         opts.banner = "Usage: rigor check [options] [paths]"
         opts.on("--config=PATH", "Path to the Rigor configuration file") { |value| options[:config] = value }
         opts.on("--format=FORMAT", "Output format: text or json") { |value| options[:format] = value }
+        opts.on("--explain", "Surface fail-soft fallback events as :info diagnostics") { options[:explain] = true }
       end
       parser.parse!(@argv)
 
       configuration = Configuration.load(options.fetch(:config))
       paths = @argv.empty? ? configuration.paths : @argv
-      result = Analysis::Runner.new(configuration: configuration).run(paths)
+      result = Analysis::Runner.new(configuration: configuration, explain: options.fetch(:explain)).run(paths)
 
       write_result(result, options.fetch(:format))
       result.success? ? 0 : 1
@@ -126,6 +128,23 @@ module Rigor
         #                `rigor type-scan` when no path is given.
         # - plugins:     reserved for future plugin contributions
         #                (no plugins are loaded today).
+        # - disable:     list of `rigor check` rule identifiers to
+        #                silence project-wide. The shipped rules are
+        #                undefined-method, wrong-arity,
+        #                argument-type-mismatch, possible-nil-receiver,
+        #                dump-type, assert-type. In-source
+        #                `# rigor:disable <rule>` comments at the end
+        #                of an offending line silence per-line; use
+        #                `# rigor:disable all` to suppress every rule.
+        # - libraries:   stdlib libraries to load on top of the
+        #                bundled defaults (e.g. ["csv", "set"]).
+        #                Each entry must be a name accepted by
+        #                `RBS::EnvironmentLoader#has_library?`.
+        # - signature_paths:
+        #                explicit list of `sig/`-style directories.
+        #                Leave unset (or `null`) to auto-detect
+        #                `<root>/sig`. Use `[]` to disable
+        #                project-RBS loading entirely.
         # - cache.path:  where Rigor will eventually persist
         #                analysis results across runs.
         #
@@ -167,15 +186,16 @@ module Rigor
     # the success and failure cases and reports the affected
     # file count for failures.
     def write_text_result(result)
+      result.diagnostics.each { |diagnostic| @out.puts(diagnostic) }
+
       if result.success?
-        @out.puts("No diagnostics")
+        @out.puts("No diagnostics") if result.diagnostics.empty?
         return
       end
 
-      result.diagnostics.each { |diagnostic| @out.puts(diagnostic) }
-      file_count = result.diagnostics.map(&:path).uniq.size
+      error_files = result.diagnostics.select(&:error?).map(&:path).uniq.size
       @out.puts("")
-      @out.puts("#{result.error_count} error(s) in #{file_count} file(s)")
+      @out.puts("#{result.error_count} error(s) in #{error_files} file(s)")
     end
 
     def help

data/lib/rigor/configuration.rb

@@ -9,12 +9,17 @@ module Rigor
       "target_ruby" => "4.0",
       "paths" => ["lib"],
       "plugins" => [],
+      "disable" => [],
+      "libraries" => [],
+      "signature_paths" => nil,
+      "fold_platform_specific_paths" => false,
       "cache" => {
         "path" => ".rigor/cache"
       }
     }.freeze
 
-    attr_reader :target_ruby, :paths, :plugins, :cache_path
+    attr_reader :target_ruby, :paths, :plugins, :cache_path, :disabled_rules,
+                :libraries, :signature_paths, :fold_platform_specific_paths
 
     def self.load(path = DEFAULT_PATH)
       data = if File.exist?(path)
@@ -26,12 +31,19 @@ module Rigor
       new(DEFAULTS.merge(data))
     end
 
-    def initialize(data = DEFAULTS)
+    def initialize(data = DEFAULTS) # rubocop:disable Metrics/AbcSize
       cache = DEFAULTS.fetch("cache").merge(data.fetch("cache", {}))
 
       @target_ruby = data.fetch("target_ruby", DEFAULTS.fetch("target_ruby")).to_s
       @paths = Array(data.fetch("paths", DEFAULTS.fetch("paths"))).map(&:to_s)
       @plugins = Array(data.fetch("plugins", DEFAULTS.fetch("plugins"))).map(&:to_s)
+      @disabled_rules = Array(data.fetch("disable", DEFAULTS.fetch("disable"))).map(&:to_s).freeze
+      @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
 
@@ -40,6 +52,10 @@ module Rigor
         "target_ruby" => target_ruby,
         "paths" => paths,
         "plugins" => plugins,
+        "disable" => disabled_rules,
+        "libraries" => libraries,
+        "signature_paths" => signature_paths,
+        "fold_platform_specific_paths" => fold_platform_specific_paths,
         "cache" => {
           "path" => cache_path
         }

data/lib/rigor/environment.rb

@@ -35,7 +35,9 @@ module Rigor
     # a strictly RBS-core view MUST construct an `RbsLoader`
     # directly instead of going through `for_project`.
     DEFAULT_LIBRARIES = %w[
-      pathname optparse json yaml fileutils tempfile uri logger date
+      pathname optparse json yaml fileutils tempfile tmpdir
+      stringio forwardable digest securerandom
+      uri logger date
       prism rbs
     ].freeze
 

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
@@ -188,6 +190,10 @@ module Rigor
             accepts_nominal_from_nominal(self_type, other_type, mode)
           when Type::Constant
             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]")
@@ -202,6 +208,62 @@ 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
+        # of `Module`. Without this rule a method whose
+        # parameter is typed `Class | Module` would reject
+        # every `is_a?(SomeClass)` call and similar
+        # introspection patterns. The rule conservatively
+        # answers `:yes` for `Module` (every singleton is at
+        # least a Module) and for `Class` / `Object` /
+        # `BasicObject` (the class object inherits from
+        # those). Other Nominals fall through to the default
+        # `:no`.
+        META_NOMINALS_FROM_SINGLETON = %w[Module Class Object BasicObject].freeze
+        private_constant :META_NOMINALS_FROM_SINGLETON
+
+        def accepts_nominal_from_singleton(self_type, other_type, mode)
+          if META_NOMINALS_FROM_SINGLETON.include?(self_type.class_name)
+            return Type::AcceptsResult.yes(
+              mode: mode,
+              reasons: "Singleton[#{other_type.class_name}] is-a #{self_type.class_name}"
+            )
+          end
+
+          Type::AcceptsResult.no(
+            mode: mode,
+            reasons: "Nominal[#{self_type.class_name}] rejects Singleton[#{other_type.class_name}]"
+          )
+        end
+
         def accepts_nominal_from_nominal(self_type, other_type, mode)
           class_result = class_subtype_result(
             target_name: self_type.class_name,
@@ -313,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

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "method_catalog"
+
+module Rigor
+  module Inference
+    module Builtins
+      # `String` and `Symbol` catalog. Singleton — load once,
+      # consult during dispatch.
+      #
+      # The blocklist below is the curated set of catalog `:leaf`
+      # entries the C-body classifier mis-attributes (the body of
+      # `rb_str_replace` calls `str_modifiable` / `str_discard`
+      # which the regex-based classifier does not recognise as
+      # 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__
+        ),
+        mutating_selectors: {
+          "String" => Set[
+            :replace, :initialize, :initialize_copy, :clear, :<<, :concat, :insert,
+            :prepend, :force_encoding, :encode, :scrub, :unicode_normalize, :"[]=",
+            :upto, :each_byte, :each_char, :each_codepoint,
+            :each_grapheme_cluster, :each_line, :bytesplice
+          ],
+          "Symbol" => Set[
+            # Symbol is immutable in Ruby; the classifier mis-flags
+            # `inspect` because `rb_sym_inspect` builds a temporary
+            # mutable buffer. Allow it.
+          ]
+        }
+      )
+    end
+  end
+end