rigortype 0.1.14 → 0.1.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1dbcd9b168a06cc8d5f26e0a096f19496c3cebdc8864fb56d966741b8a42577
-  data.tar.gz: 39e428c763e8d8cac6d9743d40d5d654bfaec56362d41e338a6dac974dff27cf
+  metadata.gz: 231749c95c76ed2647fb26973b926e0330953a1eb818b2f363acfbd241cab418
+  data.tar.gz: 46a2f8dd756c64c1f49996d5a84716c2089f7af9d3f8d4f0e1af079fad72da54
 SHA512:
-  metadata.gz: 6cd6a4d0b52fcd2e1e2bacddd6120154ccbe075ef86615c38d7e6d1d942ea158f55abaeb03f01c0a23315a187076912315af98ce74faa4c174c4f6c5c98eac74
-  data.tar.gz: 1d7b600e3dd97a38bf1ac08231a7aa07635210723adf349c014d9100ccc2b0a868deb8a6479d99207e1c0b5e4cf07c158f0f0cb3bda325ec5c7d143e4f5ae90b
+  metadata.gz: bfd342d93895c61d6afbac3323ea7e7b79648ca0fec370e05c68b864769107ef2dbe0c9540ea0410c73499b7fdde3187166edcb01158ce9c9991a114ff63ffa8
+  data.tar.gz: 5a5b01c1fb25acc2f2fb416e5e4eb7ceb9dd15a90975ad7851aa6183c28716059d5331c58b95b8ec09936db43275118934ebbea84d64d443d35b0296e9dcf906

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:

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
@@ -401,7 +419,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 +528,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
 
@@ -1319,18 +1355,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 +1531,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,7 @@ module Rigor
         @source_family = source_family
         @receiver_type = receiver_type
         @method_name = method_name
+        @project_definition_site = project_definition_site
       end
 
       def error?
@@ -65,7 +75,7 @@ module Rigor
       end
 
       def to_h
-        {
+        base = {
           "path" => path,
           "line" => line,
           "column" => column,
@@ -74,6 +84,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

data/lib/rigor/analysis/rule_catalog.rb

@@ -288,6 +288,86 @@ module Rigor
           since: "0.1.2"
         ),
 
+        CheckRules::RULE_OVERRIDE_VISIBILITY_REDUCED => Entry.new(
+          id: CheckRules::RULE_OVERRIDE_VISIBILITY_REDUCED,
+          summary: "Instance-method override reduces the visibility it inherits from an ancestor.",
+          fires_when: [
+            "An instance `def` shadows a same-name instance method defined by a project-discovered " \
+            "ancestor (included/prepended module or superclass, cross-file).",
+            "The override's source-discovered visibility is strictly more restrictive than the " \
+            "ancestor's (public → protected/private, or protected → private).",
+            "Both visibilities are statically observable from project source."
+          ],
+          does_not_fire_when: [
+            "Override raises or preserves visibility (only reductions break substitutability).",
+            "The shadowed method lives on an RBS-known / third-party ancestor (RBS models only " \
+            "public/private; RBS-parent visibility is a deferred follow-on).",
+            "`def self.foo` singleton methods (visibility is instance-side only).",
+            "The `private def foo; end` wrap-around form (not yet tracked by the visibility walker)."
+          ],
+          suppression: "`# rigor:disable def.override-visibility-reduced` on the override.",
+          severity_authored: :warning,
+          severity_by_profile: { lenient: :off, balanced: :warning, strict: :error },
+          since: "0.1.15"
+        ),
+
+        CheckRules::RULE_OVERRIDE_RETURN_WIDENED => Entry.new(
+          id: CheckRules::RULE_OVERRIDE_RETURN_WIDENED,
+          summary: "Instance-method override widens the return type it inherits from an ancestor.",
+          fires_when: [
+            "An instance `def` with an authored RBS signature overrides a same-name method whose " \
+            "RBS signature is declared by a project-discovered ancestor (module or superclass).",
+            "The override's declared return is not acceptable where the ancestor's declared return " \
+            "is expected (`parent_return.accepts(override_return)` is `:no`) — a covariance violation."
+          ],
+          does_not_fire_when: [
+            "Either side lacks an authored RBS signature (WD1 both-sides-authored gate).",
+            "The override narrows or preserves the return (covariant-safe).",
+            "The ancestor's return is `untyped` / `self` / an unbound generic (degrades to " \
+            "`Dynamic[Top]`, which accepts everything — FP-safe).",
+            "The subtype relationship between the two return types is not resolvable from loaded " \
+            "Ruby classes / their ancestors (a user-only class hierarchy degrades to `:maybe` and " \
+            "stays silent — the check has reach over core / stdlib / loadable-gem hierarchies).",
+            "`def self.foo` singleton methods (instance-side only in v1).",
+            "The shadowed method lives only on an RBS-known / third-party ancestor not in the " \
+            "project-discovered chain (user-source ancestor scope in v1)."
+          ],
+          suppression: "`# rigor:disable def.override-return-widened` on the override.",
+          severity_authored: :warning,
+          severity_by_profile: { lenient: :off, balanced: :warning, strict: :error },
+          since: "0.1.15"
+        ),
+
+        CheckRules::RULE_OVERRIDE_PARAM_NARROWED => Entry.new(
+          id: CheckRules::RULE_OVERRIDE_PARAM_NARROWED,
+          summary: "Instance-method override narrows a parameter type it inherits from an ancestor.",
+          fires_when: [
+            "An instance `def` with an authored RBS signature overrides a same-name method whose " \
+            "RBS signature is declared by a project-discovered ancestor (module or superclass).",
+            "At some matching positional parameter index, the override's slot cannot accept the " \
+            "ancestor's parameter type (`override_param.accepts(parent_param)` is `:no`) — a " \
+            "contravariance violation (the override narrowed the parameter)."
+          ],
+          does_not_fire_when: [
+            "Either side lacks an authored RBS signature (WD1 both-sides-authored gate).",
+            "The override widens or preserves the parameter (contravariant-safe).",
+            "Either side is overloaded (more than one method type — arm mapping is ambiguous).",
+            "The ancestor's parameter is `untyped` / an unbound generic / an interface (degrades " \
+            "to `Dynamic[Top]`, which is passable to anything — FP-safe).",
+            "The subtype relationship between the two parameter types is not resolvable from loaded " \
+            "Ruby classes / their ancestors (a user-only class hierarchy degrades to `:maybe` and " \
+            "stays silent — the check has reach over core / stdlib / loadable-gem hierarchies).",
+            "Arity / keyword-requiredness divergence (out of scope for v1 — positional types only).",
+            "`def self.foo` singleton methods (instance-side only in v1).",
+            "The shadowed method lives only on an RBS-known / third-party ancestor (user-source " \
+            "ancestor scope in v1)."
+          ],
+          suppression: "`# rigor:disable def.override-param-narrowed` on the override.",
+          severity_authored: :warning,
+          severity_by_profile: { lenient: :off, balanced: :warning, strict: :error },
+          since: "0.1.15"
+        ),
+
         CheckRules::RULE_IVAR_WRITE_MISMATCH => Entry.new(
           id: CheckRules::RULE_IVAR_WRITE_MISMATCH,
           summary: "Same instance variable assigned a different concrete class within one class.",