rigortype 0.1.0 → 0.1.2

data/lib/rigor/configuration.rb

@@ -6,10 +6,44 @@ require_relative "configuration/severity_profile"
 
 module Rigor
   class Configuration # rubocop:disable Metrics/ClassLength
-    DEFAULT_PATH = ".rigor.yml"
+    # File-discovery order for `Configuration.load(nil)`.
+    #
+    # The first file present is loaded; the others are NOT
+    # implicitly merged. To extend a base config explicitly the
+    # winning file MUST list the base via `includes:`.
+    #
+    # `.rigor.yml` is a developer-local override (typically
+    # gitignored); `.rigor.dist.yml` is the project default
+    # (committed to the repo). When both are present the
+    # developer's local override wins outright — there is no
+    # implicit auto-merge.
+    DISCOVERY_ORDER = %w[.rigor.yml .rigor.dist.yml].freeze
+    # Back-compat alias. Keep here so external callers that read
+    # `Configuration::DEFAULT_PATH` for help text / fixture paths
+    # still work; the discovery list is the canonical source.
+    DEFAULT_PATH = DISCOVERY_ORDER.first
+
+    # Built-in exclusion patterns appended to `exclude:` so vendored
+    # dependencies, Bundler artefacts, and JavaScript node_modules are
+    # never analysed by accident when a directory glob expands. Users
+    # cannot disable these defaults; the trade-off is that analysing
+    # any of these paths is essentially never what the user wants
+    # (they're build outputs / external dependencies, not source).
+    #
+    # We deliberately keep this list narrow. `tmp/` and similar
+    # directories vary across project layouts (Rails has `tmp/`,
+    # libraries usually don't); user-supplied `exclude:` entries
+    # in `.rigor.yml` cover the project-specific cases.
+    BUILTIN_EXCLUDES = %w[
+      **/vendor/bundle/**
+      **/.bundle/**
+      **/node_modules/**
+    ].freeze
+
     DEFAULTS = {
       "target_ruby" => "4.0",
       "paths" => ["lib"],
+      "exclude" => [],
       "plugins" => [],
       "disable" => [],
       "libraries" => [],
@@ -20,33 +54,145 @@ module Rigor
       },
       "plugins_io" => {
         "network" => "disabled",
-        "allowed_paths" => []
+        "allowed_paths" => [],
+        "allowed_url_hosts" => []
       },
       "severity_profile" => "balanced",
       "severity_overrides" => {}
     }.freeze
 
-    attr_reader :target_ruby, :paths, :plugins, :cache_path, :disabled_rules,
+    # Top-level keys whose values are file/directory paths that
+    # MUST be resolved relative to the config file's directory.
+    # `exclude:` is intentionally NOT in this list — its entries
+    # are glob patterns (`**/vendor/**`), not paths.
+    PATH_KEYS = %w[paths signature_paths].freeze
+    private_constant :PATH_KEYS
+
+    attr_reader :target_ruby, :paths, :exclude_patterns, :plugins, :cache_path, :disabled_rules,
                 :libraries, :signature_paths, :fold_platform_specific_paths,
                 :plugins_io_network, :plugins_io_allowed_paths,
+                :plugins_io_allowed_url_hosts,
                 :severity_profile, :severity_overrides
 
-    def self.load(path = DEFAULT_PATH)
-      data = if File.exist?(path)
-               YAML.safe_load_file(path, aliases: false) || {}
-             else
-               {}
-             end
+    # Loads a configuration file.
+    #
+    # `path == nil` triggers auto-discovery against
+    # {DISCOVERY_ORDER}. The first present file in that list is
+    # loaded; if none exist the built-in {DEFAULTS} are used.
+    #
+    # When a path is supplied (whether by auto-discovery or by
+    # the caller) the YAML body is processed for `includes:`
+    # recursively, and every relative path inside path-bearing
+    # keys (`paths:`, `signature_paths:`, `plugins_io.allowed_paths:`,
+    # `includes:`) is resolved against THAT file's directory.
+    # The resolution is per-file: an included file's relative
+    # paths resolve against the included file's directory, not
+    # the top-level file. Path resolution mirrors
+    # [PHPStan](https://phpstan.org/config-reference#paths).
+    def self.load(path = nil)
+      resolved = path || discover
+      return new(DEFAULTS) if resolved.nil? || !File.exist?(resolved)
 
+      data = load_with_includes(resolved)
       new(DEFAULTS.merge(data))
     end
 
-    def initialize(data = DEFAULTS) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity
+    # Returns the path to the config file Rigor would load
+    # under auto-discovery, or `nil` when neither candidate
+    # exists. Public so the CLI / spec drift checks can
+    # introspect the resolved file.
+    def self.discover
+      DISCOVERY_ORDER.find { |candidate| File.exist?(candidate) }
+    end
+
+    # Reads `path` (which MUST exist) plus every file listed in
+    # its `includes:` chain, merging them under the order:
+    # included files first (in declaration order), then the
+    # current file's own keys override. Relative paths inside
+    # each file are resolved against that file's directory.
+    def self.load_with_includes(path, visited: Set.new)
+      absolute = File.expand_path(path)
+      raise ArgumentError, "circular include: #{absolute}" if visited.include?(absolute)
+
+      raw = YAML.safe_load_file(absolute, aliases: false) || {}
+      raise ArgumentError, "config file must be a YAML mapping: #{absolute}" unless raw.is_a?(Hash)
+
+      base_dir = File.dirname(absolute)
+      includes = Array(raw.delete("includes") || [])
+      data = resolve_paths_in(raw, base_dir)
+      next_visited = visited + [absolute]
+      merge_includes(data, includes, base_dir, next_visited)
+    end
+
+    def self.merge_includes(data, includes, base_dir, visited)
+      return data if includes.empty?
+
+      accumulated = {}
+      includes.each do |inc|
+        inc_path = File.expand_path(inc.to_s, base_dir)
+        unless File.exist?(inc_path)
+          raise ArgumentError, "include not found: #{inc.inspect} (referenced from #{base_dir})"
+        end
+
+        accumulated = deep_merge(accumulated, load_with_includes(inc_path, visited: visited))
+      end
+      deep_merge(accumulated, data)
+    end
+
+    # Per-file path resolution. Each path-bearing key listed in
+    # {PATH_KEYS} plus the nested `plugins_io.allowed_paths:`
+    # entries get their relative paths expanded against the
+    # config file's directory. `cache.path:` is intentionally
+    # left as-is so end-user messages (e.g. `--cache-stats`
+    # output) keep the project-relative form the user wrote.
+    def self.resolve_paths_in(data, base_dir)
+      return data unless data.is_a?(Hash)
+
+      out = data.dup
+      PATH_KEYS.each { |key| resolve_path_key!(out, key, base_dir) }
+      resolve_plugins_io_paths!(out, base_dir)
+      out
+    end
+
+    def self.resolve_path_key!(out, key, base_dir)
+      return unless out.key?(key) && !out[key].nil?
+
+      out[key] = Array(out[key]).map { |p| File.expand_path(p.to_s, base_dir) }
+    end
+
+    def self.resolve_plugins_io_paths!(out, base_dir)
+      plugins_io = out["plugins_io"]
+      return unless plugins_io.is_a?(Hash) && plugins_io["allowed_paths"]
+
+      duped = plugins_io.dup
+      duped["allowed_paths"] = Array(plugins_io["allowed_paths"]).map { |p| File.expand_path(p.to_s, base_dir) }
+      out["plugins_io"] = duped
+    end
+
+    def self.deep_merge(left, right)
+      return right unless left.is_a?(Hash) && right.is_a?(Hash)
+
+      merged = left.dup
+      right.each do |key, value|
+        merged[key] = if merged.key?(key) && merged[key].is_a?(Hash) && value.is_a?(Hash)
+                        deep_merge(merged[key], value)
+                      else
+                        value
+                      end
+      end
+      merged
+    end
+    private_class_method :load_with_includes, :merge_includes, :resolve_paths_in, :deep_merge
+
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/MethodLength
+    def initialize(data = DEFAULTS)
       cache = DEFAULTS.fetch("cache").merge(data.fetch("cache", {}))
       plugins_io = DEFAULTS.fetch("plugins_io").merge(data.fetch("plugins_io", {}))
 
-      @target_ruby = data.fetch("target_ruby", DEFAULTS.fetch("target_ruby")).to_s
+      @target_ruby = coerce_target_ruby(data.fetch("target_ruby", DEFAULTS.fetch("target_ruby")))
       @paths = Array(data.fetch("paths", DEFAULTS.fetch("paths"))).map(&:to_s)
+      user_excludes = Array(data.fetch("exclude", DEFAULTS.fetch("exclude"))).map(&:to_s)
+      @exclude_patterns = (BUILTIN_EXCLUDES + user_excludes).uniq.freeze
       @plugins = Array(data.fetch("plugins", DEFAULTS.fetch("plugins"))).map do |entry|
         coerce_plugin_entry(entry)
       end.freeze
@@ -60,6 +206,7 @@ module Rigor
       @cache_path = cache.fetch("path").to_s
       @plugins_io_network = coerce_network_policy(plugins_io.fetch("network"))
       @plugins_io_allowed_paths = Array(plugins_io.fetch("allowed_paths")).map(&:to_s).freeze
+      @plugins_io_allowed_url_hosts = Array(plugins_io.fetch("allowed_url_hosts")).map(&:to_s).freeze
       @severity_profile = coerce_severity_profile(
         data.fetch("severity_profile", DEFAULTS.fetch("severity_profile"))
       )
@@ -67,11 +214,13 @@ module Rigor
         data.fetch("severity_overrides", DEFAULTS.fetch("severity_overrides"))
       )
     end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/MethodLength
 
     def to_h
       {
         "target_ruby" => target_ruby,
         "paths" => paths,
+        "exclude" => exclude_patterns - BUILTIN_EXCLUDES,
         "plugins" => plugins,
         "disable" => disabled_rules,
         "libraries" => libraries,
@@ -82,7 +231,8 @@ module Rigor
         },
         "plugins_io" => {
           "network" => plugins_io_network.to_s,
-          "allowed_paths" => plugins_io_allowed_paths
+          "allowed_paths" => plugins_io_allowed_paths,
+          "allowed_url_hosts" => plugins_io_allowed_url_hosts
         },
         "severity_profile" => severity_profile.to_s,
         "severity_overrides" => severity_overrides.to_h { |k, v| [k, v.to_s] }
@@ -107,6 +257,29 @@ module Rigor
       end
     end
 
+    # `target_ruby` is passed to `Prism.parse_file(path, version:)` at
+    # the analyser's three parse sites (`Analysis::Runner`,
+    # `CLI::TypeOfCommand`, `CLI::TypeScanCommand`) so projects that
+    # target an older Ruby get parse errors for syntax their target
+    # doesn't support. Format validation here is loose — accepts
+    # any `<major>.<minor>` or `<major>.<minor>.<patch>` form, plus
+    # the literal `"latest"`. Prism itself enforces the supported
+    # set and raises `ArgumentError` for versions it does not
+    # recognise (e.g. `"1.0"`); the parse-time error message names
+    # the version, so the user can correct the setting.
+    TARGET_RUBY_FORMAT = /\A(?:\d+\.\d+(?:\.\d+)?|latest)\z/
+    private_constant :TARGET_RUBY_FORMAT
+
+    def coerce_target_ruby(value)
+      s = value.to_s
+      unless s.match?(TARGET_RUBY_FORMAT)
+        raise ArgumentError,
+              "target_ruby must be a version (e.g. \"3.4\", \"4.0\", \"3.4.0\") or \"latest\", got #{value.inspect}"
+      end
+
+      s.dup.freeze
+    end
+
     # Slice 2 only accepts `:disabled` for the network policy. The
     # YAML scalar may arrive as a String (`"disabled"`) or already
     # as the Symbol; coerce to the canonical Symbol shape so the
@@ -117,7 +290,7 @@ module Rigor
     # `Configuration` does not require the plugin namespace at
     # load time (Configuration is loaded before Plugin in
     # `lib/rigor.rb`); the two stay in lockstep via spec.
-    VALID_NETWORK_POLICIES = %i[disabled].freeze
+    VALID_NETWORK_POLICIES = %i[disabled allowlist].freeze
     private_constant :VALID_NETWORK_POLICIES
 
     def coerce_network_policy(value)

data/lib/rigor/environment.rb

@@ -41,7 +41,7 @@ module Rigor
       prism rbs
     ].freeze
 
-    attr_reader :class_registry, :rbs_loader
+    attr_reader :class_registry, :rbs_loader, :plugin_registry
 
     # @param class_registry [Rigor::Environment::ClassRegistry]
     # @param rbs_loader [Rigor::Environment::RbsLoader, nil] when nil the
@@ -50,9 +50,17 @@ module Rigor
     #   wires the shared core loader, which is itself lazy: requesting an
     #   environment instance does NOT load RBS until a method or class
     #   query actually consults the loader.
-    def initialize(class_registry: ClassRegistry.default, rbs_loader: nil)
+    # @param plugin_registry [Rigor::Plugin::Registry, nil] v0.1.1
+    #   Track 2 slice 7. The per-run plugin registry the
+    #   inference engine consults at call sites for plugin
+    #   `#flow_contribution_for` overrides. When nil (the
+    #   default), no plugin-level return-type contribution
+    #   participates — useful for tests, the `Environment.default`
+    #   facade, and analyses that don't load plugins.
+    def initialize(class_registry: ClassRegistry.default, rbs_loader: nil, plugin_registry: nil)
       @class_registry = class_registry
       @rbs_loader = rbs_loader
+      @plugin_registry = plugin_registry
       freeze
     end
 
@@ -82,7 +90,7 @@ module Rigor
       #   reflection artefacts) consult the cache. Pass `nil` (the
       #   default) to skip caching for this environment.
       # @return [Rigor::Environment]
-      def for_project(root: Dir.pwd, libraries: [], signature_paths: nil, cache_store: nil)
+      def for_project(root: Dir.pwd, libraries: [], signature_paths: nil, cache_store: nil, plugin_registry: nil)
         resolved_paths = signature_paths || default_signature_paths(root)
         merged_libraries = (DEFAULT_LIBRARIES + libraries.map(&:to_s)).uniq
         loader = RbsLoader.new(
@@ -90,7 +98,7 @@ module Rigor
           signature_paths: resolved_paths,
           cache_store: cache_store
         )
-        new(rbs_loader: loader)
+        new(rbs_loader: loader, plugin_registry: plugin_registry)
       end
 
       private

data/lib/rigor/inference/expression_typer.rb

@@ -981,7 +981,9 @@ module Rigor
           method_name: node.name,
           arg_types: arg_types,
           block_type: block_type,
-          environment: scope.environment
+          environment: scope.environment,
+          call_node: node,
+          scope: scope
         )
         return result if result
 

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

@@ -42,14 +42,45 @@ module Rigor
         }.freeze
         private_constant :NUMERIC_CONSTRUCTORS
 
+        # `Kernel#Integer(s)` predicate-aware refinement set
+        # (v0.1.1 Track 1 slice 2b). Both `decimal-int-string` and
+        # `numeric-string` describe digit-only ASCII strings, so
+        # `Integer(s)` is total over the carrier domain and the
+        # result is `>= 0`. The default `base: 10` invocation
+        # accepts the same shape `String#to_i` does for these
+        # predicates; the `Integer(s, base)` overload is left for
+        # a later slice.
+        INTEGER_REFINEMENT_PREDICATES = Set[:decimal_int, :numeric].freeze
+        private_constant :INTEGER_REFINEMENT_PREDICATES
+
         def try_dispatch(receiver:, method_name:, args:)
           return nil if receiver.nil?
           return try_array(args) if method_name == :Array
           return try_numeric_constructor(method_name, args) if NUMERIC_CONSTRUCTORS.key?(method_name)
+          return try_integer_from_refinement(args) if method_name == :Integer
 
           nil
         end
 
+        # `Kernel#Integer(s)` over a `Refined[String, predicate]`
+        # whose predicate is in {INTEGER_REFINEMENT_PREDICATES}.
+        # Mirrors the `String#to_i` projection in `ShapeDispatch`
+        # (v0.1.1 slice 2a) — the result is always
+        # `non-negative-int`. Returns nil for any other arg shape
+        # so the RBS tier handles the generic `Integer(arg)` case.
+        def try_integer_from_refinement(args)
+          return nil unless args.size == 1
+
+          arg = args.first
+          return nil unless arg.is_a?(Type::Refined)
+
+          base = arg.base
+          return nil unless base.is_a?(Type::Nominal) && base.class_name == "String"
+          return nil unless INTEGER_REFINEMENT_PREDICATES.include?(arg.predicate_id)
+
+          Type::Combinator.non_negative_int
+        end
+
         def try_array(args)
           return nil if args.length != 1
 

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

@@ -52,7 +52,27 @@ module Rigor
 
         CONCAT_METHODS = %i[+ << concat].freeze
         FORMAT_METHODS = %i[format sprintf].freeze
-        private_constant :CONCAT_METHODS, :FORMAT_METHODS
+        # v0.1.1 Track 1 slice 5a — methods that, called with no
+        # arguments on a literal-bearing receiver, return a value
+        # that is also literal-bearing. `#strip` / `#lstrip` /
+        # `#rstrip` / `#chomp` (no-arg) / `#chop` strip a known
+        # subset of characters from the ends, so the survivors
+        # are always a substring of an already-literal value.
+        # `#scrub` (no-arg) replaces invalid bytes; a literal-string
+        # value comes from source code and is always valid UTF-8,
+        # so the result is identical to the receiver. None of
+        # these preserve `non-empty-string`-ness (e.g. `"   ".strip
+        # == ""`); the carrier collapses from `non-empty-literal-string`
+        # down to plain `literal-string`.
+        LITERAL_PRESERVING_METHODS = %i[strip lstrip rstrip chomp chop scrub].freeze
+        # v0.1.1 Track 1 slice 5c — width-padding methods. `center`
+        # / `ljust` / `rjust` take a `width` Integer plus an
+        # optional literal padding `String`. When the receiver
+        # and the (default or supplied) padding are both
+        # literal-bearing, the result is literal-bearing too.
+        WIDTH_PADDING_METHODS = %i[center ljust rjust].freeze
+        private_constant :CONCAT_METHODS, :FORMAT_METHODS,
+                         :LITERAL_PRESERVING_METHODS, :WIDTH_PADDING_METHODS
 
         def try_dispatch(receiver:, method_name:, args:, **) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
           return fold_array_join(receiver, args) if method_name == :join
@@ -61,6 +81,10 @@ module Rigor
           return nil unless Type::Combinator.literal_string_compatible?(receiver)
 
           return fold_string_percent(args) if method_name == :%
+          if args.empty?
+            return LITERAL_PRESERVING_METHODS.include?(method_name) ? Type::Combinator.literal_string : nil
+          end
+          return fold_width_pad(args) if WIDTH_PADDING_METHODS.include?(method_name)
           return nil unless args.size == 1
 
           if CONCAT_METHODS.include?(method_name)
@@ -70,6 +94,23 @@ module Rigor
           end
         end
 
+        # `String#center` / `#ljust` / `#rjust` — first argument is
+        # the target width (Integer-typed), optional second
+        # argument is the padding string (must be literal-bearing
+        # for the result to stay literal). The default padding
+        # (a space) is always literal so the no-second-arg form
+        # passes through. Width is allowed to be any Integer
+        # because Ruby's runtime accepts negative widths and
+        # widths smaller than the receiver's length without
+        # raising.
+        def fold_width_pad(args)
+          return nil unless [1, 2].include?(args.size)
+          return nil unless integer_typed?(args[0])
+          return nil if args.size == 2 && !Type::Combinator.literal_string_compatible?(args[1])
+
+          Type::Combinator.literal_string
+        end
+
         def fold_concat(arg_type)
           return nil unless Type::Combinator.literal_string_compatible?(arg_type)
 
@@ -165,7 +206,7 @@ module Rigor
         end
 
         private_class_method :fold_concat, :fold_repeat, :fold_array_join,
-                             :fold_format, :fold_string_percent,
+                             :fold_format, :fold_string_percent, :fold_width_pad,
                              :literal_or_constant?, :integer_typed?
       end
     end

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

@@ -8,24 +8,40 @@ module Rigor
   module Inference
     module MethodDispatcher
       # Picks the RBS overload that should answer a call given the
-      # caller's actual argument types. Slice 4 phase 2c shape:
+      # caller's actual argument types. Slice 4 phase 2c shape (with
+      # the v0.1.2 interface-strictness preference layered on top):
       #
       # 1. Filter overloads by positional arity (required, optional and
       #    rest_positionals are honored; required_keywords disqualify the
       #    overload because we do not yet thread keyword args through
       #    `call_arg_types`).
-      # 2. Within the arity-matching overloads, accept the first one
-      #    whose every (param, arg) pair returns a `yes` or `maybe`
-      #    answer from `Rigor::Type#accepts(arg, mode: :gradual)`.
-      # 3. If no overload matches, fall back to `method_types.first`
-      #    so existing call sites keep their phase 1 / 2b behavior.
-      #    This preserves the fail-soft invariant of the dispatcher.
+      # 2. **Pass 1 — strict matches first.** Among the arity-matching
+      #    overloads, prefer the first one whose every (param, arg)
+      #    pair returns a `yes` or `maybe` answer AND whose param
+      #    types do NOT translate through `RBS::Types::Alias` /
+      #    `Interface` / `Intersection`. The translator demotes those
+      #    to `Dynamic[Top]`, which gradually accepts any argument —
+      #    so without this preference, an alias-typed overload like
+      #    `Array#[](::int) -> Elem` would beat the strict
+      #    `Array#[](Range) -> Array[Elem]?` overload for a Range
+      #    argument. (Surfaced during v0.1.1 self-analysis; see the
+      #    "Interface-strictness on overload selection" item in
+      #    `docs/MILESTONES.md`.)
+      # 3. **Pass 2 — gradual fall-back.** If no fully strict overload
+      #    matches, accept the first arity-and-gradual-accept match
+      #    (the v0.1.1 behaviour). Alias / Interface / Intersection
+      #    params still reach this pass, so call sites whose only
+      #    candidate IS an alias-typed overload keep working.
+      # 4. If no overload matches at all, fall back to
+      #    `method_types.first` so existing call sites keep their
+      #    phase 1 / 2b behavior. This preserves the fail-soft
+      #    invariant of the dispatcher.
       #
       # The selector is intentionally agnostic about the dispatch kind
       # (instance vs singleton). Both kinds share the same arity and
       # acceptance shape; the difference is only in which `Definition`
       # the caller fetched.
-      module OverloadSelector
+      module OverloadSelector # rubocop:disable Metrics/ModuleLength
         module_function
 
         # @param method_definition [RBS::Definition::Method]
@@ -61,6 +77,18 @@ module Rigor
           # compatibility.
           param_overrides = RbsExtended.param_type_override_map(method_definition)
 
+          # Pass 1: prefer overloads whose param types stay strict —
+          # no translator-induced `Dynamic[Top]` from Alias /
+          # Interface / Intersection. The pass is skipped
+          # entirely when any arg is `Dynamic[Top]` (literally
+          # `untyped`), because gradual acceptance against an
+          # untyped arg accepts every param indiscriminately and
+          # would let pass 1 lock in an arbitrary strict overload
+          # (e.g. `Regexp#=~(nil) -> nil` over the
+          # `(::interned?) -> Integer?` overload). Pass 2 falls
+          # back to the original gradual matcher so overloads
+          # that legitimately rely on duck-typed params still
+          # resolve when nothing stricter applies.
           match = find_matching_overload(
             overloads,
             arg_types: arg_types,
@@ -68,7 +96,17 @@ module Rigor
             instance_type: instance_type,
             type_vars: type_vars,
             block_required: block_required,
-            param_overrides: param_overrides
+            param_overrides: param_overrides,
+            strict: true
+          ) || find_matching_overload(
+            overloads,
+            arg_types: arg_types,
+            self_type: self_type,
+            instance_type: instance_type,
+            type_vars: type_vars,
+            block_required: block_required,
+            param_overrides: param_overrides,
+            strict: false
           )
           return match if match
           return overloads.find { |mt| overload_has_block?(mt) } if block_required
@@ -84,11 +122,14 @@ module Rigor
         class << self
           private
 
-          # rubocop:disable Metrics/ParameterLists
+          # rubocop:disable Metrics/ParameterLists, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
           def find_matching_overload(overloads, arg_types:, self_type:, instance_type:, type_vars:, block_required:,
-                                     param_overrides:)
+                                     param_overrides:, strict:)
+            return nil if strict && arg_types.any? { |t| untyped_arg?(t) }
+
             overloads.find do |method_type|
               next false if block_required && !OverloadSelector.overload_has_block?(method_type)
+              next false if strict && !strictly_typed_params?(method_type, arg_types.size)
 
               matches?(
                 method_type,
@@ -100,7 +141,58 @@ module Rigor
               )
             end
           end
-          # rubocop:enable Metrics/ParameterLists
+          # rubocop:enable Metrics/ParameterLists, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+          # Treats the literal `untyped` carrier (`Dynamic[Top]`)
+          # as too imprecise to drive a strict-pass match. Other
+          # `Dynamic`-wrapped types with a concrete static facet
+          # carry enough information to pick a sensible overload.
+          def untyped_arg?(type)
+            type.is_a?(Type::Dynamic) && type.static_facet.is_a?(Type::Top)
+          end
+
+          # Returns true when every positional param the call
+          # site engages translates to a non-`Dynamic[Top]`
+          # carrier. Alias / Interface / Intersection RBS types
+          # all degrade to `Dynamic[Top]` per the translator's
+          # current shape — those gradually accept any arg, so
+          # an overload that includes one would beat strictly-
+          # typed alternatives in pass 2 of the selector.
+          def strictly_typed_params?(method_type, actual_count)
+            fun = method_type.type
+            return false unless arity_compatible?(fun, actual_count)
+
+            params = positional_params_for(fun, actual_count)
+            params.all? { |param| !alias_or_interface_param?(param.type) }
+          end
+
+          # Recursive: an Optional / Union wrapper is strict iff
+          # every member is strict. Type args of a ClassInstance
+          # are NOT walked — `Range[::int]` is a Range carrier
+          # at the param level; the alias only colours the
+          # element type, which is checked separately when the
+          # element is actually accessed.
+          #
+          # `RBS::Types::Bases::Any` (the explicit `untyped`
+          # keyword) is treated like Alias / Interface /
+          # Intersection — both translate to `Dynamic[Top]`,
+          # both gradually accept anything. A `(untyped) -> T`
+          # catch-all overload that comes after the strictly-
+          # typed ones must lose pass 1 so the typed overloads
+          # win when their param actually fits the arg.
+          def alias_or_interface_param?(rbs_type)
+            case rbs_type
+            when RBS::Types::Alias, RBS::Types::Interface,
+                 RBS::Types::Intersection, RBS::Types::Bases::Any
+              true
+            when RBS::Types::Optional
+              alias_or_interface_param?(rbs_type.type)
+            when RBS::Types::Union
+              rbs_type.types.any? { |t| alias_or_interface_param?(t) }
+            else
+              false
+            end
+          end
 
           # rubocop:disable Metrics/ParameterLists
           def matches?(method_type, arg_types, self_type:, instance_type:, type_vars:, param_overrides:)