rigortype 0.1.14 → 0.1.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1dbcd9b168a06cc8d5f26e0a096f19496c3cebdc8864fb56d966741b8a42577
-  data.tar.gz: 39e428c763e8d8cac6d9743d40d5d654bfaec56362d41e338a6dac974dff27cf
+  metadata.gz: 2fb4015697adf7cbc9d65b2ca6ff954c8cac5f784ffb9616153d4af8d2505ccc
+  data.tar.gz: 52ee5acb7d233c0e86c8cdca45151c5f745b4c13d7155fcb15fafdaaed1d6dc9
 SHA512:
-  metadata.gz: 6cd6a4d0b52fcd2e1e2bacddd6120154ccbe075ef86615c38d7e6d1d942ea158f55abaeb03f01c0a23315a187076912315af98ce74faa4c174c4f6c5c98eac74
-  data.tar.gz: 1d7b600e3dd97a38bf1ac08231a7aa07635210723adf349c014d9100ccc2b0a868deb8a6479d99207e1c0b5e4cf07c158f0f0cb3bda325ec5c7d143e4f5ae90b
+  metadata.gz: 4f4b64afe3dbca26f6224762a2f1a3dd0bd4cade2ea9a61a30e2fba28ed29d3bb6d68bdfa73fb450536e5c7fef45e07a10a6fd0cec693ad228a828ff30905f8e
+  data.tar.gz: 4b5faa0d8c7295067f5a0f3d335c1800f22659e47b0428942405b07c1d38649163090f3a461e942a82aecaab6172e774ef88ca44f9a569b1392cdeee0be04086

data/README.md

@@ -58,6 +58,12 @@ Install Rigor in this project by following the instructions at
 https://raw.githubusercontent.com/rigortype/rigor/refs/heads/master/docs/install.md
 ```
 
+Prefer to set up in your language? Find prompts for Japanese, Chinese,
+Korean, Portuguese, Spanish, French, German, Italian, Vietnamese, Thai,
+Indonesian, Polish, Ukrainian, Russian, Romanian, and Turkish at
+[docs/manual/14-rails-quickstart.md](docs/manual/14-rails-quickstart.md#step-1--install-ruby-40-and-rigor-common-to-both-paths)
+(or the [online version](https://rigor.typedduck.fail/reference/manual/14-rails-quickstart/)).
+
 **Manual install** — the recommended path uses
 [`mise`](https://mise.jdx.dev/), which provisions both Ruby 4.0 and
 Rigor pinned per project:
@@ -259,10 +265,12 @@ In-source suppression: `# rigor:disable <rule>` silences a single line;
 
 ## Status
 
-Current released version: **`v0.1.8`** (2026-05-21). The analyzer is
+Current released version: **`v0.1.15`** (2026-05-29). The analyzer is
 usable on real Ruby code today; the rule catalogue is deliberately
 conservative — Rigor's stance is to surface zero false positives while
-the inference surface stabilises.
+the inference surface stabilises. The `0.1.x` preview line has been
+hardened against real OSS Rails codebases (Mastodon / Redmine / GitLab
+FOSS); `v0.2.0` will open the first evaluation release.
 
 Release history: [`CHANGELOG.md`](CHANGELOG.md). Forward-looking
 commitments: [Roadmap](https://rigor.typedduck.fail/reference/roadmap/).

data/exe/rigor

@@ -1,6 +1,25 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
+# ADR-39 slice 5 — the `ruby_box` plugin-isolation strategy needs the
+# experimental `Ruby::Box` feature, which is a process-start flag
+# (`RUBY_BOX=1`, not toggleable at runtime). When a project selects that
+# strategy (`RIGOR_PLUGIN_ISOLATION=ruby_box`, or the legacy `RIGOR_BOX`
+# alias) we re-exec the same command with the flag set before anything
+# else loads. The `RUBY_BOX` guard prevents an infinite re-exec, and the
+# inherited environment (RUBYOPT / BUNDLE_*) preserves the Bundler
+# context across the exec. The `none` (default) and `process` strategies
+# need no flag, so this is a no-op for them — behaviour is unchanged
+# unless a project opts into `ruby_box`.
+rigor_isolation = ENV["RIGOR_PLUGIN_ISOLATION"].to_s
+rigor_wants_box = rigor_isolation == "ruby_box" || !ENV["RIGOR_BOX"].to_s.empty?
+if rigor_wants_box && ENV["RUBY_BOX"].to_s.empty?
+  require "rbconfig"
+  ENV["RUBY_BOX"] = "1"
+  ENV["RIGOR_PLUGIN_ISOLATION"] = "ruby_box" if rigor_isolation.empty?
+  exec(RbConfig.ruby, __FILE__, *ARGV)
+end
+
 lib = File.expand_path("../lib", __dir__)
 $LOAD_PATH.unshift(lib) if File.directory?(lib) && !$LOAD_PATH.include?(lib)
 

data/lib/rigor/analysis/check_rules.rb

@@ -67,6 +67,9 @@ module Rigor
       RULE_UNREACHABLE_BRANCH = "flow.unreachable-branch"
       RULE_RETURN_TYPE = "def.return-type-mismatch"
       RULE_VISIBILITY_MISMATCH = "def.method-visibility-mismatch"
+      RULE_OVERRIDE_VISIBILITY_REDUCED = "def.override-visibility-reduced"
+      RULE_OVERRIDE_RETURN_WIDENED = "def.override-return-widened"
+      RULE_OVERRIDE_PARAM_NARROWED = "def.override-param-narrowed"
       RULE_IVAR_WRITE_MISMATCH = "def.ivar-write-mismatch"
       RULE_DEAD_ASSIGNMENT = "flow.dead-assignment"
       RULE_ALWAYS_TRUTHY_CONDITION = "flow.always-truthy-condition"
@@ -85,6 +88,9 @@ module Rigor
         RULE_ALWAYS_TRUTHY_CONDITION,
         RULE_RETURN_TYPE,
         RULE_VISIBILITY_MISMATCH,
+        RULE_OVERRIDE_VISIBILITY_REDUCED,
+        RULE_OVERRIDE_RETURN_WIDENED,
+        RULE_OVERRIDE_PARAM_NARROWED,
         RULE_IVAR_WRITE_MISMATCH
       ].freeze
 
@@ -116,6 +122,12 @@ module Rigor
       # canonical id starts with `<family>.`. Per ADR-8 § "1".
       RULE_FAMILIES = %w[call flow assert dump def].freeze
 
+      # ADR-35 slice 1 — bound for the `def.override-visibility-reduced`
+      # ancestor walk, and the public > protected > private ordering
+      # used to decide whether an override reduces visibility.
+      OVERRIDE_ANCESTOR_WALK_LIMIT = 100
+      VISIBILITY_RANK = { public: 2, protected: 1, private: 0 }.freeze
+
       # Resolves a user-supplied rule token (`undefined-method`,
       # `call.undefined-method`, or the family wildcard `call`)
       # to the set of canonical rule identifiers it disables.
@@ -150,6 +162,12 @@ module Rigor
           when Prism::DefNode
             return_diagnostic = return_type_mismatch_diagnostic(path, node, scope_index)
             diagnostics << return_diagnostic if return_diagnostic
+            override_vis = override_visibility_diagnostic(path, node, scope_index)
+            diagnostics << override_vis if override_vis
+            override_return = override_return_widened_diagnostic(path, node, scope_index)
+            diagnostics << override_return if override_return
+            override_param = override_param_narrowed_diagnostic(path, node, scope_index)
+            diagnostics << override_param if override_param
           when Prism::IfNode, Prism::UnlessNode
             unreachable = unreachable_branch_diagnostic(path, node, scope_index)
             diagnostics << unreachable if unreachable
@@ -365,7 +383,16 @@ module Rigor
           # its model). Flagging an undefined method on a class
           # with an open dynamic surface is unsound, so the rule
           # skips it.
-          return nil if open_receiver?(class_name, scope)
+          # An unbounded receiver surface: either a plugin-declared
+          # open receiver (ADR-26 — e.g. `ActiveRecord::Relation`), or
+          # a type Rigor synthesized (a missing-namespace module / a
+          # stub for a referenced-but-undeclared type) to keep a
+          # malformed project signature buildable. A synthesized stub's
+          # method table is empty only because Rigor invented it, not
+          # because the real type is empty (the real `DRb` has
+          # `start_service`), so enumerating it to prove a call
+          # "undefined" would be a false positive.
+          return nil if unbounded_receiver_surface?(class_name, scope)
 
           # Slice 7 phase 12 — suppress when the user has
           # declared the method in source (`def` /
@@ -401,7 +428,24 @@ module Rigor
           return nil if module_mixin_receiver?(receiver_type, scope) &&
                         lookup_method(receiver_type, "Object", call_node.name, scope)
 
-          build_undefined_method_diagnostic(path, call_node, receiver_type)
+          definition_site = project_definition_site(scope, class_name, call_node.name, kind)
+          build_undefined_method_diagnostic(path, call_node, receiver_type, definition_site, class_name)
+        end
+
+        # ADR-17 — when the project itself defines this method on the
+        # receiver class somewhere in the analyzed file set (a reopened
+        # core/stdlib/gem class the dispatcher does not apply cross-
+        # file), return that `"path:line"` site so the diagnostic points
+        # at `pre_eval:` instead of reading as a bare unresolved call.
+        # Instance-side only (the cross-file def-source index tracks
+        # `def` instance methods); the diagnostic still fires — Rigor
+        # does not auto-apply project monkey-patches (the full-project
+        # pre-pass is deferred per ADR-17 slice 5) — but it is now
+        # actionable rather than mistakable for a typo.
+        def project_definition_site(scope, class_name, method_name, kind)
+          return nil unless kind == :instance
+
+          scope.user_def_site_for(class_name, method_name)
         end
 
         def module_mixin_receiver?(receiver_type, scope)
@@ -493,7 +537,8 @@ module Rigor
                      "`def` or a monkey-patch on Object/Kernel, list that file in " \
                      "`.rigor.yml`'s `pre_eval:` (ADR-17) so the analyzer sees it.",
             severity: :warning,
-            rule: RULE_UNRESOLVED_TOPLEVEL
+            rule: RULE_UNRESOLVED_TOPLEVEL,
+            method_name: call_node.name.to_s
           )
         end
 
@@ -530,6 +575,14 @@ module Rigor
         # loaded plugin (manifest `open_receivers:`). An open
         # class responds beyond its RBS surface, so the
         # `call.undefined-method` rule must not fire for it.
+        # True when the receiver class responds beyond an enumerable
+        # RBS method table, so proving a call "undefined" against it is
+        # unsound: a plugin-declared open receiver, or a Rigor-
+        # synthesized stub type (see `RbsLoader#synthesized_type_names`).
+        def unbounded_receiver_surface?(class_name, scope)
+          open_receiver?(class_name, scope) || synthesized_stub_receiver?(class_name, scope)
+        end
+
         def open_receiver?(class_name, scope)
           registry = scope.environment&.plugin_registry
           return false if registry.nil?
@@ -537,6 +590,13 @@ module Rigor
           registry.open_receiver?(class_name)
         end
 
+        def synthesized_stub_receiver?(class_name, scope)
+          loader = scope.environment&.rbs_loader
+          return false if loader.nil? || !loader.respond_to?(:synthesized_type_names)
+
+          loader.synthesized_type_names.include?(class_name.to_s.sub(/\A::/, ""))
+        end
+
         def definition_available?(receiver_type, class_name, scope)
           if receiver_type.is_a?(Type::Singleton)
             !Rigor::Reflection.singleton_definition(class_name, scope: scope).nil?
@@ -1319,18 +1379,33 @@ module Rigor
           )
         end
 
-        def build_undefined_method_diagnostic(path, call_node, receiver_type)
+        def build_undefined_method_diagnostic(path, call_node, receiver_type, definition_site = nil, class_name = nil)
           location = call_node.message_loc || call_node.location
           rendered_receiver = receiver_type.describe
+          message = "undefined method `#{call_node.name}' for #{rendered_receiver}"
+          # ADR-17 — when the project itself defines this method on the
+          # receiver class somewhere in the file set, name the site and
+          # point at `pre_eval:`. Rigor does not apply project monkey-
+          # patches cross-file automatically, so the diagnostic still
+          # fires, but the enriched message makes it actionable (and
+          # `rigor triage` keys on the structured `project_definition_site`
+          # field to recommend `pre_eval:` with high confidence).
+          if definition_site
+            def_owner = class_name || rendered_receiver
+            message += "; the project defines `#{def_owner}##{call_node.name}' at " \
+                       "#{definition_site} — Rigor does not apply project monkey-patches " \
+                       "cross-file; list that file in `.rigor.yml`'s `pre_eval:` (ADR-17)"
+          end
           Diagnostic.new(
             rule: RULE_UNDEFINED_METHOD,
             path: path,
             line: location.start_line,
             column: location.start_column + 1,
-            message: "undefined method `#{call_node.name}' for #{rendered_receiver}",
+            message: message,
             severity: :error,
             receiver_type: rendered_receiver,
-            method_name: call_node.name.to_s
+            method_name: call_node.name.to_s,
+            project_definition_site: definition_site
           )
         end
 
@@ -1480,6 +1555,353 @@ module Rigor
             severity: severity
           )
         end
+
+        # ADR-35 slice 1 — `def.override-visibility-reduced`. The
+        # Liskov signature rule for visibility: an instance-method
+        # override MUST NOT reduce the visibility it inherits
+        # (public → protected/private, or protected → private),
+        # because a caller holding the supertype that invokes the
+        # method breaks when handed the subtype.
+        #
+        # Slice-1 scope (ADR-35 WD1, visibility carve-out): both the
+        # override and the shadowed method must have a STATICALLY
+        # OBSERVABLE visibility. The override's visibility is read
+        # from the source-discovered table; the parent is resolved
+        # against the project-discovered ancestor chain (user-source
+        # classes / modules only — RBS-known ancestors, whose
+        # accessibility RBS models as public/private only, are a
+        # deferred follow-on). When either side is not observable
+        # the rule stays silent.
+        def override_visibility_diagnostic(path, def_node, scope_index)
+          return nil unless def_node.receiver.nil? # instance methods only
+
+          scope = scope_index[def_node]
+          return nil if scope.nil?
+
+          self_type = scope.self_type
+          return nil unless self_type.respond_to?(:class_name)
+
+          class_name = self_type.class_name.to_s
+          method_name = def_node.name
+
+          override_visibility = scope.discovered_method_visibility(class_name, method_name)
+          return nil if override_visibility.nil?
+
+          parent = nearest_ancestor_visibility(scope, class_name, method_name)
+          return nil if parent.nil?
+
+          parent_class, parent_visibility = parent
+          # Unknown ancestor visibility (e.g. the defining file was not
+          # in the analyzed set) → cannot prove a reduction, stay silent.
+          return nil if parent_visibility.nil?
+          return nil unless visibility_reduced?(parent_visibility, override_visibility)
+
+          build_override_visibility_diagnostic(
+            path, def_node, parent_class, parent_visibility, override_visibility
+          )
+        end
+
+        # Returns true when `override_visibility` is strictly more
+        # restrictive than `parent_visibility` under the
+        # public > protected > private ordering.
+        def visibility_reduced?(parent_visibility, override_visibility)
+          parent_rank = VISIBILITY_RANK[parent_visibility]
+          override_rank = VISIBILITY_RANK[override_visibility]
+          return false if parent_rank.nil? || override_rank.nil?
+
+          override_rank < parent_rank
+        end
+
+        # Breadth-first walk of the project-discovered ancestor chain
+        # (included / prepended modules first, then the superclass —
+        # Ruby's MRO ordering), yielding each resolved ancestor class
+        # name nearest-first. Returns the first truthy value the block
+        # produces, or nil. Cross-file: the chain is followed through
+        # the scope tables the runner seeds from the project pre-pass
+        # (ADR-24 WD1). Cycle-guarded and node-count-capped. Mirrors
+        # `ExpressionTyper#resolve_user_def_through_ancestors`.
+        def each_project_ancestor(scope, class_name)
+          queue = ancestor_class_names(scope, class_name)
+          seen = { class_name.to_s => true }
+          visited = 0
+          until queue.empty?
+            current = queue.shift
+            next if current.nil? || seen[current]
+
+            seen[current] = true
+            visited += 1
+            return nil if visited > OVERRIDE_ANCESTOR_WALK_LIMIT
+
+            result = yield current
+            return result if result
+
+            ancestor_class_names(scope, current).each { |name| queue.push(name) }
+          end
+          nil
+        end
+
+        # `[defining_class, visibility]` for the nearest user-source
+        # ancestor that defines an instance method `method_name`, or nil.
+        def nearest_ancestor_visibility(scope, class_name, method_name)
+          each_project_ancestor(scope, class_name) do |ancestor|
+            # Stop at the nearest ancestor that DEFINES the method; its
+            # visibility may be nil (unknown) — the caller treats unknown
+            # as "cannot prove a reduction" and stays silent. Never
+            # fabricate `:public` from a missing entry (that produced a
+            # large false-positive cluster on cross-file Rails concerns).
+            [ancestor, scope.discovered_method_visibility(ancestor, method_name)] if scope.user_def_for(ancestor,
+                                                                                                        method_name)
+          end
+        end
+
+        # Direct ancestors of `class_name` as project-discovered,
+        # qualified names: included / prepended modules first, then
+        # the superclass. As-written names are resolved against the
+        # subclass's lexical nesting; names that resolve to no
+        # project class/module (RBS-known / third-party) are dropped.
+        def ancestor_class_names(scope, class_name)
+          names = []
+          scope.includes_of(class_name).each do |raw|
+            resolved = resolve_override_ancestor_name(scope, class_name, raw)
+            names << resolved if resolved
+          end
+          raw_super = scope.superclass_of(class_name)
+          if raw_super
+            resolved_super = resolve_override_ancestor_name(scope, class_name, raw_super)
+            names << resolved_super if resolved_super
+          end
+          names
+        end
+
+        def resolve_override_ancestor_name(scope, subclass_qualified, raw_ancestor)
+          segments = subclass_qualified.to_s.split("::")
+          (segments.length - 1).downto(0) do |i|
+            candidate = (segments[0, i] + [raw_ancestor]).join("::")
+            return candidate if known_user_class?(scope, candidate)
+          end
+          nil
+        end
+
+        def known_user_class?(scope, name)
+          scope.discovered_superclasses.key?(name) ||
+            scope.discovered_def_nodes.key?(name) ||
+            scope.discovered_includes.key?(name)
+        end
+
+        def build_override_visibility_diagnostic(path, def_node, parent_class, parent_visibility, override_visibility)
+          location = def_node.name_loc || def_node.location
+          Diagnostic.new(
+            rule: RULE_OVERRIDE_VISIBILITY_REDUCED,
+            path: path,
+            line: location.start_line,
+            column: location.start_column + 1,
+            message: "visibility of `#{def_node.name}' reduced from #{parent_visibility} to " \
+                     "#{override_visibility} (overrides #{parent_class}##{def_node.name}); " \
+                     "breaks substitutability",
+            severity: :warning
+          )
+        end
+
+        # ADR-35 slice 2 — `def.override-return-widened`. The Liskov
+        # signature rule for returns (covariance): an override may
+        # *narrow* the return it inherits (return a more specific type)
+        # but MUST NOT *widen* it. A caller holding the supertype uses
+        # the result as the parent's return type; a wider override
+        # return breaks that use.
+        #
+        # WD1 gate (proper, type-direction): both the override and the
+        # shadowed ancestor method must carry an explicitly-authored
+        # RBS signature. The override side is gated by
+        # `defined_on?` (the RBS method is declared on the overriding
+        # class itself, not merely inherited); the parent side is the
+        # nearest project-discovered ancestor whose RBS declares the
+        # method. Inference-only either side → silent.
+        #
+        # Fires only on a proven (`:no`) widening; generic / `untyped`
+        # / `self` parent returns degrade to `Dynamic[Top]` and accept
+        # everything, so they stay silent (FP-safe). `self`/`instance`
+        # are translated with `self_type: nil` on both sides, so a
+        # parent `-> self` and an override `-> self` never fire.
+        def override_return_widened_diagnostic(path, def_node, scope_index)
+          return nil unless def_node.receiver.nil? # instance methods only (singleton: follow-on)
+
+          scope = scope_index[def_node]
+          return nil if scope.nil?
+
+          self_type = scope.self_type
+          return nil unless self_type.respond_to?(:class_name)
+
+          class_name = self_type.class_name.to_s
+          method_name = def_node.name
+
+          override_method = safe_instance_method_definition(class_name, method_name, scope)
+          return nil if override_method.nil?
+          return nil unless defined_on?(override_method, class_name)
+
+          parent = nearest_ancestor_method_def(scope, class_name, method_name)
+          return nil if parent.nil?
+
+          parent_class, parent_method = parent
+          override_return = declared_return_union(override_method, scope.environment)
+          parent_return = declared_return_union(parent_method, scope.environment)
+          return nil if override_return.nil? || parent_return.nil?
+          return nil if dynamic_top?(parent_return) # untyped / unbound-generic parent contract
+
+          return nil unless parent_return.accepts(override_return).no?
+
+          build_override_return_widened_diagnostic(
+            path, def_node, parent_class, parent_return, override_return
+          )
+        end
+
+        # `[defining_class, RBS::Definition::Method]` for the nearest
+        # project-discovered ancestor whose RBS declares `method_name`
+        # (not the starting class's own declaration), or nil.
+        def nearest_ancestor_method_def(scope, class_name, method_name)
+          each_project_ancestor(scope, class_name) do |ancestor|
+            method_def = safe_instance_method_definition(ancestor, method_name, scope)
+            [ancestor, method_def] if method_def && !defined_on?(method_def, class_name)
+          end
+        end
+
+        def safe_instance_method_definition(class_name, method_name, scope)
+          Reflection.instance_method_definition(class_name, method_name, scope: scope)
+        rescue StandardError
+          nil
+        end
+
+        # True when `method_def`'s RBS declaration lives on `class_name`
+        # itself (rather than being inherited from an ancestor).
+        def defined_on?(method_def, class_name)
+          defined_in = method_def.defined_in
+          return false if defined_in.nil?
+
+          normalize_class_name(defined_in.to_s) == normalize_class_name(class_name)
+        end
+
+        def normalize_class_name(name)
+          name.to_s.delete_prefix("::")
+        end
+
+        def build_override_return_widened_diagnostic(path, def_node, parent_class, parent_return, override_return)
+          location = def_node.name_loc || def_node.location
+          Diagnostic.new(
+            rule: RULE_OVERRIDE_RETURN_WIDENED,
+            path: path,
+            line: location.start_line,
+            column: location.start_column + 1,
+            message: "return type of `#{def_node.name}' widened from #{parent_return.describe(:short)} " \
+                     "to #{override_return.describe(:short)} (overrides #{parent_class}##{def_node.name}); " \
+                     "breaks substitutability",
+            severity: :warning
+          )
+        end
+
+        # ADR-35 slice 3 — `def.override-param-narrowed`. The Liskov
+        # signature rule for parameters (contravariance): an override
+        # may *widen* a parameter (accept a supertype — accepting more
+        # is safe) but MUST NOT *narrow* it. A caller holding the
+        # supertype passes a parent-typed argument; a narrowed override
+        # parameter cannot accept it.
+        #
+        # Direction (ADR-35 WD3, corrected): fire on
+        # `override_param.accepts(parent_param) == :no` — the override's
+        # (narrowed) slot cannot accept the wider parent argument type.
+        # WD4: type comparison at matching POSITIONAL parameter indices
+        # only; arity / keyword-requiredness divergence is out of scope
+        # for v1. Same WD1 both-sides-authored gate as slice 2;
+        # `untyped` / unbound-generic / interface parent params degrade
+        # to `Dynamic[Top]` and are skipped (FP-safe). To avoid
+        # overload-arm ambiguity, both sides must have exactly one
+        # method type.
+        def override_param_narrowed_diagnostic(path, def_node, scope_index)
+          return nil unless def_node.receiver.nil? # instance methods only
+
+          scope = scope_index[def_node]
+          return nil if scope.nil?
+
+          self_type = scope.self_type
+          return nil unless self_type.respond_to?(:class_name)
+
+          class_name = self_type.class_name.to_s
+          method_name = def_node.name
+
+          override_method = safe_instance_method_definition(class_name, method_name, scope)
+          return nil if override_method.nil?
+          return nil unless defined_on?(override_method, class_name)
+
+          parent = nearest_ancestor_method_def(scope, class_name, method_name)
+          return nil if parent.nil?
+
+          parent_class, parent_method = parent
+          override_params = positional_param_types(override_method)
+          parent_params = positional_param_types(parent_method)
+          return nil if override_params.nil? || parent_params.nil?
+
+          index = first_narrowed_param_index(override_params, parent_params)
+          return nil if index.nil?
+
+          build_override_param_narrowed_diagnostic(
+            path, def_node, parent_class, index, parent_params[index], override_params[index]
+          )
+        end
+
+        # Translated positional (required + optional) parameter types of
+        # a method's single method type, or nil when the method is
+        # overloaded (multiple method types — arm mapping is ambiguous)
+        # or the parameter list is not introspectable. Per-position
+        # translation failures yield `nil` at that slot (skipped by the
+        # comparison). `self`/`instance` translate with `self_type: nil`
+        # (→ `Dynamic[Top]`), matching the return-side handling.
+        def positional_param_types(method_def)
+          method_types = method_def.method_types
+          return nil unless method_types.size == 1
+
+          func = method_types.first.type
+          return nil unless func.respond_to?(:required_positionals)
+
+          (func.required_positionals + func.optional_positionals).map do |param|
+            Inference::RbsTypeTranslator.translate(
+              param.type, self_type: nil, instance_type: nil, type_vars: {}
+            )
+          rescue StandardError
+            nil
+          end
+        end
+
+        # Index of the first positional parameter the override narrows
+        # relative to the parent, or nil. A position is a violation when
+        # the override's slot cannot accept the parent's argument type
+        # (`override_param.accepts(parent_param) == :no`). Positions
+        # where either side is missing/untranslatable, or the parent
+        # type degraded to `Dynamic[Top]` (untyped / unbound generic /
+        # interface), are skipped.
+        def first_narrowed_param_index(override_params, parent_params)
+          count = [override_params.size, parent_params.size].min
+          count.times do |i|
+            override_param = override_params[i]
+            parent_param = parent_params[i]
+            next if override_param.nil? || parent_param.nil?
+            next if dynamic_top?(parent_param) || dynamic_top?(override_param)
+
+            return i if override_param.accepts(parent_param).no?
+          end
+          nil
+        end
+
+        def build_override_param_narrowed_diagnostic(path, def_node, parent_class, index, parent_param, override_param)
+          location = def_node.name_loc || def_node.location
+          Diagnostic.new(
+            rule: RULE_OVERRIDE_PARAM_NARROWED,
+            path: path,
+            line: location.start_line,
+            column: location.start_column + 1,
+            message: "parameter #{index + 1} of `#{def_node.name}' narrowed from " \
+                     "#{parent_param.describe(:short)} to #{override_param.describe(:short)} " \
+                     "(overrides #{parent_class}##{def_node.name}); breaks substitutability",
+            severity: :warning
+          )
+        end
       end
       # rubocop:enable Metrics/ClassLength
     end

data/lib/rigor/analysis/diagnostic.rb

@@ -9,7 +9,7 @@ module Rigor
       DEFAULT_SOURCE_FAMILY = :builtin
 
       attr_reader :path, :line, :column, :message, :severity, :rule, :source_family,
-                  :receiver_type, :method_name
+                  :receiver_type, :method_name, :project_definition_site
 
       # `rule:` is the stable identifier (a kebab-case string)
       # of the diagnostic's source rule. It is used by the
@@ -35,9 +35,18 @@ module Rigor
       # message wording. Both stay nil for rules that have no such
       # pair; a consumer that finds them nil falls back to message
       # parsing.
+      #
+      # `project_definition_site:` is an optional `"path:line"` string
+      # set by `call.undefined-method` when the project itself defines
+      # the called method on the receiver class somewhere in the
+      # analyzed file set (a reopened core/stdlib/gem class the
+      # dispatcher does not apply cross-file — see ADR-17). Its presence
+      # is the high-confidence "this is a project monkey-patch, not a
+      # bug" signal `rigor triage` keys on to recommend `pre_eval:`.
+      # Nil for every other diagnostic.
       def initialize(path:, line:, column:, message:, severity: :error, rule: nil, # rubocop:disable Metrics/ParameterLists
                      source_family: DEFAULT_SOURCE_FAMILY,
-                     receiver_type: nil, method_name: nil)
+                     receiver_type: nil, method_name: nil, project_definition_site: nil)
         @path = path
         @line = line
         @column = column
@@ -47,6 +56,47 @@ module Rigor
         @source_family = source_family
         @receiver_type = receiver_type
         @method_name = method_name
+        @project_definition_site = project_definition_site
+      end
+
+      # Builds a Diagnostic positioned at a Prism node. Internalises
+      # the load-bearing convention every caller otherwise repeats:
+      # the line is the node's 1-based `start_line` and the column is
+      # `start_column + 1` (Prism columns are 0-based; Rigor reports
+      # 1-based). Pass any node responding to `#location`; all other
+      # fields forward to `#initialize` unchanged.
+      #
+      # `Plugin::Base#diagnostic` wraps this for plugin authors (who
+      # must not set `source_family` — the runner stamps it); core
+      # rules and other producers call it directly.
+      def self.from_node(node, path:, message:, severity: :error, rule: nil, # rubocop:disable Metrics/ParameterLists
+                         source_family: DEFAULT_SOURCE_FAMILY,
+                         receiver_type: nil, method_name: nil, project_definition_site: nil)
+        from_location(
+          node.location, path: path, message: message, severity: severity, rule: rule,
+                         source_family: source_family, receiver_type: receiver_type,
+                         method_name: method_name, project_definition_site: project_definition_site
+        )
+      end
+
+      # Builds a Diagnostic from an explicit Prism location, applying
+      # the same 1-based `line` / `start_column + 1` convention as
+      # {.from_node}. Use this when the diagnostic should point at a
+      # *sub-location* rather than the whole node — most often a call's
+      # `message_loc` (the matcher / method name) instead of the
+      # receiver-spanning `node.location`. {.from_node} is sugar for
+      # `from_location(node.location, …)`.
+      def self.from_location(location, path:, message:, severity: :error, rule: nil, # rubocop:disable Metrics/ParameterLists
+                             source_family: DEFAULT_SOURCE_FAMILY,
+                             receiver_type: nil, method_name: nil, project_definition_site: nil)
+        new(
+          path: path,
+          line: location.start_line,
+          column: location.start_column + 1,
+          message: message, severity: severity, rule: rule, source_family: source_family,
+          receiver_type: receiver_type, method_name: method_name,
+          project_definition_site: project_definition_site
+        )
       end
 
       def error?
@@ -65,7 +115,7 @@ module Rigor
       end
 
       def to_h
-        {
+        base = {
           "path" => path,
           "line" => line,
           "column" => column,
@@ -74,6 +124,8 @@ module Rigor
           "source_family" => source_family.to_s,
           "message" => message
         }
+        base["project_definition_site"] = project_definition_site if project_definition_site
+        base
       end
 
       # Text rendering for `rigor check`. The qualified rule