rigortype 0.2.8 → 0.3.0

data/lib/rigor/analysis/check_rules.rb

@@ -8,12 +8,18 @@ require_relative "../source/constant_path"
 require_relative "../type"
 require_relative "diagnostic"
 require_relative "dependency_recorder"
+require_relative "check_rules/rule_ids"
+require_relative "check_rules/inferred_param_guard"
 require_relative "check_rules/rule_walk"
 require_relative "check_rules/always_truthy_condition_collector"
 require_relative "check_rules/unreachable_clause_collector"
+require_relative "check_rules/shadowed_rescue_collector"
 require_relative "check_rules/dead_assignment_collector"
+require_relative "check_rules/duplicate_hash_key_collector"
+require_relative "check_rules/return_in_ensure_collector"
 require_relative "check_rules/ivar_write_collector"
 require_relative "check_rules/main_pass_collector"
+require_relative "check_rules/void_value_use_collector"
 require_relative "check_rules/self_closedness_scanner"
 
 module Rigor
@@ -44,88 +50,8 @@ module Rigor
     #   loader (RBS-blind environments, unknown stdlib).
     # rubocop:disable Metrics/ModuleLength
     module CheckRules
-      # Canonical identifiers for each rule. Per ADR-8 §
-      # "Diagnostic ID family hierarchy", rule names are
-      # `family.rule-name` two-segment strings; the families
-      # group diagnostics by where they originate
-      # (`call.*` for call-site rules, `flow.*` for flow-analysis
-      # proofs, `assert.*` for runtime-assertion rules,
-      # `dump.*` for debug helpers, `def.*` for method-definition
-      # rules). Used by the configuration `disable:` list and the
-      # in-source `# rigor:disable <rule>` suppression comment
-      # system; new rules MUST register here so user configuration
-      # can refer to them.
-      RULE_UNDEFINED_METHOD = "call.undefined-method"
-      RULE_SELF_UNDEFINED_METHOD = "call.self-undefined-method"
-      RULE_UNRESOLVED_TOPLEVEL = "call.unresolved-toplevel"
-      RULE_WRONG_ARITY = "call.wrong-arity"
-      RULE_ARGUMENT_TYPE = "call.argument-type-mismatch"
-      RULE_NIL_RECEIVER = "call.possible-nil-receiver"
-      RULE_DUMP_TYPE = "dump.type"
-      RULE_ASSERT_TYPE = "assert.type-mismatch"
-      RULE_ALWAYS_RAISES = "flow.always-raises"
-      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"
-      RULE_UNREACHABLE_CLAUSE = "flow.unreachable-clause"
-
-      ALL_RULES = [
-        RULE_UNDEFINED_METHOD,
-        RULE_SELF_UNDEFINED_METHOD,
-        RULE_UNRESOLVED_TOPLEVEL,
-        RULE_WRONG_ARITY,
-        RULE_ARGUMENT_TYPE,
-        RULE_NIL_RECEIVER,
-        RULE_DUMP_TYPE,
-        RULE_ASSERT_TYPE,
-        RULE_ALWAYS_RAISES,
-        RULE_UNREACHABLE_BRANCH,
-        RULE_DEAD_ASSIGNMENT,
-        RULE_ALWAYS_TRUTHY_CONDITION,
-        RULE_UNREACHABLE_CLAUSE,
-        RULE_RETURN_TYPE,
-        RULE_VISIBILITY_MISMATCH,
-        RULE_OVERRIDE_VISIBILITY_REDUCED,
-        RULE_OVERRIDE_RETURN_WIDENED,
-        RULE_OVERRIDE_PARAM_NARROWED,
-        RULE_IVAR_WRITE_MISMATCH
-      ].freeze
-
-      # Backward-compat alias table (ADR-8 § "Backward
-      # compatibility"). Existing user code with
-      # `# rigor:disable undefined-method` /
-      # `disable: [undefined-method]` keeps working — the
-      # legacy unprefixed identifiers map to their canonical
-      # `family.rule-name` form here. Removing the aliases is
-      # a future ADR once user code has migrated; until then,
-      # both spellings resolve identically.
-      LEGACY_RULE_ALIASES = {
-        "undefined-method" => RULE_UNDEFINED_METHOD,
-        "self-undefined-method" => RULE_SELF_UNDEFINED_METHOD,
-        "wrong-arity" => RULE_WRONG_ARITY,
-        "argument-type-mismatch" => RULE_ARGUMENT_TYPE,
-        "possible-nil-receiver" => RULE_NIL_RECEIVER,
-        "dump-type" => RULE_DUMP_TYPE,
-        "assert-type" => RULE_ASSERT_TYPE,
-        "always-raises" => RULE_ALWAYS_RAISES,
-        "unreachable-branch" => RULE_UNREACHABLE_BRANCH,
-        "method-visibility-mismatch" => RULE_VISIBILITY_MISMATCH,
-        "ivar-write-mismatch" => RULE_IVAR_WRITE_MISMATCH,
-        "dead-assignment" => RULE_DEAD_ASSIGNMENT,
-        "always-truthy-condition" => RULE_ALWAYS_TRUTHY_CONDITION,
-        "unreachable-clause" => RULE_UNREACHABLE_CLAUSE
-      }.freeze
-
-      # Family wildcard — a `<family>` token in a suppression
-      # comment or `disable:` list disables every rule whose
-      # canonical id starts with `<family>.`. Per ADR-8 § "1".
-      RULE_FAMILIES = %w[call flow assert dump def].freeze
+      # ADR-87 WD4 — the canonical rule-id table lives in the light `check_rules/rule_ids.rb` (required at the
+      # top of this file) so {Analysis::RuleCatalog} can read it without loading the engine.
 
       # ADR-35 slice 1 — bound for the `def.override-visibility-reduced`
       # ancestor walk, and the public > protected > private ordering
@@ -171,13 +97,32 @@ module Rigor
         collectors = node_collectors || run_node_collectors(path, root, scope_index)
         diagnostics = collectors[:main_pass].results.dup
         diagnostics.concat(self_undefined_method_diagnostics(path, self_call_misses, root, scope_index))
-        diagnostics.concat(always_truthy_condition_diagnostics(path, collectors[:always_truthy].results))
-        diagnostics.concat(unreachable_clause_diagnostics(path, collectors[:unreachable_clauses].results))
-        diagnostics.concat(ivar_write_mismatch_diagnostics(path, collectors[:ivar_writes].results))
-        diagnostics.concat(dead_assignment_diagnostics(path, collectors[:dead_assignments].results))
+        diagnostics.concat(void_value_use_diagnostics(path, root, scope_index))
+        COLLECTOR_DIAGNOSTIC_BUILDERS.each do |role, builder|
+          diagnostics.concat(send(builder, path, collectors[role].results))
+        end
+        # Suppression-marker validation (`suppression.*`) runs BEFORE the filter so its own diagnostics are
+        # suppressible like any other rule — `# rigor:disable suppression.unknown-rule` on the offending
+        # comment's line works, with no regress (the token itself is known, so it never re-fires).
+        diagnostics.concat(suppression_marker_diagnostics(path, comments))
         filter_suppressed(diagnostics, comments: comments, disabled_rules: disabled_rules)
       end
 
+      # The per-collector diagnostic builders {.diagnose} folds over, in the historical emission order
+      # (always-truthy → unreachable-clause → shadowed-rescue → ivar-write → dead-assignment →
+      # duplicate-hash-key → return-in-ensure). Keys match {.build_node_collectors}' roles; each value is a
+      # `(path, results)` module_function on this module.
+      COLLECTOR_DIAGNOSTIC_BUILDERS = {
+        always_truthy: :always_truthy_condition_diagnostics,
+        unreachable_clauses: :unreachable_clause_diagnostics,
+        shadowed_rescues: :shadowed_rescue_diagnostics,
+        ivar_writes: :ivar_write_mismatch_diagnostics,
+        dead_assignments: :dead_assignment_diagnostics,
+        duplicate_hash_keys: :duplicate_hash_key_diagnostics,
+        return_in_ensure: :return_in_ensure_diagnostics
+      }.freeze
+      private_constant :COLLECTOR_DIAGNOSTIC_BUILDERS
+
       # The verbatim per-node dispatch of the former inline main pass
       # (`diagnose`'s `Source::NodeWalker.each` `case`), now invoked by
       # {MainPassCollector} on the shared {RuleWalk}. Returns the
@@ -212,8 +157,11 @@ module Rigor
           main_pass: MainPassCollector.new(->(node) { main_pass_node_diagnostics(path, node, scope_index) }),
           always_truthy: AlwaysTruthyConditionCollector.new(scope_index),
           unreachable_clauses: UnreachableClauseCollector.new(scope_index),
+          shadowed_rescues: ShadowedRescueCollector.new(scope_index),
           ivar_writes: IvarWriteCollector.new(scope_index),
-          dead_assignments: DeadAssignmentCollector.new(scope_index)
+          dead_assignments: DeadAssignmentCollector.new(scope_index),
+          duplicate_hash_keys: DuplicateHashKeyCollector.new(scope_index),
+          return_in_ensure: ReturnInEnsureCollector.new(scope_index)
         }
       end
 
@@ -313,6 +261,7 @@ module Rigor
           dump_type_diagnostic(path, node, scope_index),
           assert_type_diagnostic(path, node, scope_index),
           always_raises_diagnostic(path, node, scope_index),
+          raise_non_exception_diagnostic(path, node, scope_index),
           visibility_mismatch_diagnostic(path, node, scope_index)
         ].compact
       end
@@ -357,6 +306,31 @@ module Rigor
         end
       end
 
+      # v0.3.0 — `flow.duplicate-hash-key`. Emits a diagnostic for each LATER occurrence of a repeated
+      # LITERAL key within one Hash literal (braced or bare-kwargs) — Ruby keeps the last entry silently
+      # at runtime, so the earlier value is dead. The
+      # `Analysis::CheckRules::DuplicateHashKeyCollector` describes the value-pinned-literal-only
+      # envelope (symbols / plain strings / integers / floats / true / false / nil; never
+      # cross-kind, never interpolation / constants / calls / splats).
+      def duplicate_hash_key_diagnostics(path, duplicate_keys)
+        duplicate_keys.map do |result|
+          build_duplicate_hash_key_diagnostic(path, result)
+        end
+      end
+
+      # v0.3.0 — `flow.return-in-ensure`. One diagnostic per explicit
+      # `return` lexically inside an `ensure` clause body: it silently
+      # discards the method's in-flight return value and swallows any
+      # in-flight exception. Purely syntactic; the
+      # `Analysis::CheckRules::ReturnInEnsureCollector` describes the
+      # frame-aware envelope (nested def / lambda / `define_method`
+      # blocks are excluded, plain blocks are not).
+      def return_in_ensure_diagnostics(path, results)
+        results.map do |result|
+          build_return_in_ensure_diagnostic(path, result[:return_node])
+        end
+      end
+
       # v0.1.2 — `flow.always-truthy-condition`. Fires on
       # `if` / `unless` / ternary predicates whose inferred
       # type is a `Type::Constant` AND that don't fall in
@@ -380,6 +354,25 @@ module Rigor
         end
       end
 
+      # ADR-100 WD2 — `static.value-use.void`. Runs a standalone walk (like `self_undefined_method_diagnostics`)
+      # over `root`, so its value-context slot inspection stays independent of the shared per-node
+      # {RuleWalk}. Each result is a value-context use of a call whose author-declared `-> void` return the
+      # engine recovered to `top`.
+      def void_value_use_diagnostics(path, root, scope_index)
+        VoidValueUseCollector.new(scope_index).collect(root).map do |result|
+          build_void_value_use_diagnostic(path, result)
+        end
+      end
+
+      # `flow.shadowed-rescue-clause` — one diagnostic per rescue clause every earlier-comparable class of
+      # which is already caught by an earlier clause of the same chain (see {ShadowedRescueCollector} for
+      # the ancestry-certainty envelope).
+      def shadowed_rescue_diagnostics(path, results)
+        results.map do |result|
+          build_shadowed_rescue_diagnostic(path, result)
+        end
+      end
+
       def ivar_mismatch_diagnostics_for(path, class_name, ivar_name, writes)
         return [] if writes.size < 2
 
@@ -454,6 +447,23 @@ module Rigor
       FILE_SUPPRESSION_PATTERN = /#\s*rigor:disable-file\s+(?<rules>[\w.,\s-]+)/
       private_constant :FILE_SUPPRESSION_PATTERN
 
+      # A `rigor:disable[-file]` marker word regardless of whether any rule tokens follow. Used only by the
+      # `suppression.empty` detection — the two suppression patterns above require at least one token
+      # character, so a bare `# rigor:disable` never reaches them. The lookahead keeps
+      # `rigor:disable-something-else` from counting as a marker.
+      BARE_SUPPRESSION_MARKER = /#\s*rigor:disable(?<file>-file)?(?![\w-])(?<rest>.*)/
+      private_constant :BARE_SUPPRESSION_MARKER
+
+      # A `rigor:` marker word that is NOT part of Rigor's suppression grammar but reads like an attempted
+      # suppression — the RuboCop-reflex spellings `rigor:disable-next-line <rules>` and
+      # `rigor:enable <rules>`. These are invisible to both suppression patterns above (the hyphenated
+      # suffix fails LINE_SUPPRESSION_PATTERN's `\s+` and BARE_SUPPRESSION_MARKER's lookahead), so without
+      # surveillance they silently suppress nothing. Matches `disable-<suffix>` for any suffix other than
+      # `file`, and `enable` with or without a suffix.
+      UNKNOWN_SUPPRESSION_MARKER =
+        /#\s*rigor:(?<marker>disable-(?!file(?![\w-]))[\w-]+|enable(?:-[\w-]+)?)(?![\w-])(?<rest>.*)/
+      private_constant :UNKNOWN_SUPPRESSION_MARKER
+
       # @return [Array<(Hash{Integer => Set}, Set)>] pair of
       #   `(line_suppressions, file_suppressions)`. Line
       #   suppressions are keyed by source line number; file
@@ -478,6 +488,128 @@ module Rigor
         end
       end
 
+      # PHPStan-`IgnoreParseErrorRule`-modelled surveillance over the suppression markers themselves: a
+      # malformed or ineffective `# rigor:disable` / `# rigor:disable-file` comment must not silently no-op
+      # (the typo'd `# rigor:disable call.undefined-metod` suppresses nothing and the user never learns).
+      # Emits `suppression.unknown-rule` for every marker token that resolves to no known identifier, and
+      # `suppression.empty` for a marker that lists no rules at all. The MATCHING semantics are deliberately
+      # unchanged — an unknown token is still kept verbatim per the diagnostic-policy spec — so this is
+      # additive surveillance only. Both diagnostics run before {.filter_suppressed} and flow through it,
+      # so they are themselves suppressible (`# rigor:disable suppression.unknown-rule`) with no regress:
+      # that token is known, so acknowledging it never re-fires the rule.
+      def suppression_marker_diagnostics(path, comments)
+        comments.each_with_object([]) do |comment, diagnostics|
+          source = comment.location.slice
+          if (match = FILE_SUPPRESSION_PATTERN.match(source))
+            validate_suppression_tokens(match[:rules], "rigor:disable-file", path, comment, diagnostics)
+          elsif (match = LINE_SUPPRESSION_PATTERN.match(source))
+            validate_suppression_tokens(match[:rules], "rigor:disable", path, comment, diagnostics)
+          else
+            diagnose_bare_suppression_marker(path, comment, source, diagnostics)
+          end
+        end
+      end
+
+      def validate_suppression_tokens(raw, marker, path, comment, diagnostics)
+        tokens = raw.to_s.split(/[\s,]+/).reject(&:empty?)
+        if tokens.empty?
+          diagnostics << empty_suppression_diagnostic(path, comment, marker)
+          return
+        end
+
+        tokens.each do |token|
+          next if known_suppression_token?(token)
+
+          diagnostics << unknown_suppression_rule_diagnostic(path, comment, marker, token)
+        end
+      end
+
+      # A comment carrying the marker word but not the token-bearing suppression grammar. A remainder of
+      # nothing but whitespace / commas is a genuinely empty marker (`# rigor:disable`); anything else
+      # (documentation prose like "`# rigor:disable <rule>` comments") is left alone as an ordinary
+      # comment, matching the parse path, which never treats it as a suppression either.
+      def diagnose_bare_suppression_marker(path, comment, source, diagnostics)
+        bare = BARE_SUPPRESSION_MARKER.match(source)
+        if bare
+          return unless bare[:rest].match?(/\A[\s,]*\z/)
+
+          marker = bare[:file] ? "rigor:disable-file" : "rigor:disable"
+          diagnostics << empty_suppression_diagnostic(path, comment, marker)
+          return
+        end
+
+        diagnose_unknown_suppression_marker(path, comment, source, diagnostics)
+      end
+
+      # `# rigor:disable-next-line <rule>` / `# rigor:enable <rule>` — a marker word Rigor's grammar does
+      # not recognise but that reads as an attempted suppression (the RuboCop reflex). Fires only when the
+      # remainder is empty or looks like a rule list, so prose mentioning the spelling in backticks stays
+      # an ordinary comment — the same escape the empty-marker detection observes.
+      def diagnose_unknown_suppression_marker(path, comment, source, diagnostics)
+        unknown = UNKNOWN_SUPPRESSION_MARKER.match(source)
+        return if unknown.nil?
+
+        rest = unknown[:rest]
+        return unless rest.match?(/\A[\s,]*\z/) || rest.match?(/\A\s+[\w.,\s-]+\z/)
+
+        diagnostics << unknown_suppression_marker_diagnostic(path, comment, unknown[:marker])
+      end
+
+      # True when a suppression token resolves to a diagnostic identifier some producer can emit: a
+      # canonical CheckRules id, a legacy alias, the `all` wildcard, a family wildcard, a bare
+      # non-catalogue engine id, or a dotted id under a known non-check family (`rbs_extended.*`,
+      # `dynamic.*`, `rbs.*`, `pre-eval.*`, and any `plugin.`-prefixed id — plugins load dynamically, so
+      # their rule vocabulary cannot be enumerated here and under-warning is the FP-safe direction).
+      def known_suppression_token?(token)
+        return true if token == "all"
+        return true if ALL_RULES.include?(token) || LEGACY_RULE_ALIASES.key?(token) ||
+                       RULE_FAMILIES.include?(token) || NON_CHECK_DIAGNOSTIC_IDS.include?(token)
+
+        family, rest = token.split(".", 2)
+        !rest.nil? && NON_CHECK_DIAGNOSTIC_FAMILIES.include?(family)
+      end
+
+      def unknown_suppression_rule_diagnostic(path, comment, marker, token)
+        Diagnostic.new(
+          path: path,
+          line: comment.location.start_line,
+          column: comment.location.start_column + 1,
+          message: "unknown rule `#{token}` in `# #{marker}` — the token matches no known rule, alias, " \
+                   "or family, so this suppression has no effect. Likely a typo; `rigor explain <rule>` " \
+                   "lists the canonical ids.",
+          severity: :warning,
+          rule: RULE_SUPPRESSION_UNKNOWN_RULE,
+          source_family: :builtin
+        )
+      end
+
+      def unknown_suppression_marker_diagnostic(path, comment, marker)
+        Diagnostic.new(
+          path: path,
+          line: comment.location.start_line,
+          column: comment.location.start_column + 1,
+          message: "unrecognised suppression marker `rigor:#{marker}` — Rigor's markers are " \
+                   "`# rigor:disable <rules>` (suppresses on its own line) and " \
+                   "`# rigor:disable-file <rules>`, so this comment suppresses nothing.",
+          severity: :warning,
+          rule: RULE_SUPPRESSION_UNKNOWN_MARKER,
+          source_family: :builtin
+        )
+      end
+
+      def empty_suppression_diagnostic(path, comment, marker)
+        Diagnostic.new(
+          path: path,
+          line: comment.location.start_line,
+          column: comment.location.start_column + 1,
+          message: "`# #{marker}` lists no rules, so this suppression has no effect. Name the rules to " \
+                   "suppress (`# #{marker} call.undefined-method`) or use `# #{marker} all`.",
+          severity: :warning,
+          rule: RULE_SUPPRESSION_EMPTY,
+          source_family: :builtin
+        )
+      end
+
       # Expands a list of user-supplied rule tokens into the
       # canonical-id set per ADR-8 § "Backward compatibility".
       # `disabled_rules` accepts unprefixed legacy names
@@ -500,12 +632,16 @@ module Rigor
       class << self
         private
 
-        def undefined_method_diagnostic(path, call_node, scope_index)
+        def undefined_method_diagnostic(path, call_node, scope_index) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
           return nil if call_node.receiver.nil?
 
           scope = scope_index[call_node]
           return nil if scope.nil?
 
+          # ADR-67 WD6b — an inferred-parameter receiver's type is an open-call-site lower bound; firing
+          # undefined-method against it is an FP by construction. Decline.
+          return nil if inferred_param_receiver?(call_node, scope)
+
           # N3 — a safe-navigation call (`recv&.m`) never dispatches on the
           # nil edge of its receiver: at runtime it short-circuits to nil.
           # A receiver that types as exactly `nil` yields nil with no call at
@@ -727,6 +863,28 @@ module Rigor
         }.freeze
         private_constant :CONSTANT_CLASSES
 
+        # ADR-67 WD6b — true when this call's receiver is *rooted at* a pristine inferred-parameter local (the
+        # call-site union seeded at method entry). Every negative in-body rule (`call.undefined-method`,
+        # wrong-arity, argument-type-mismatch, possible-nil, visibility) declines on such a receiver: an open
+        # call-site set makes the inferred type a *lower bound*, so a diagnostic against it is a false positive
+        # by construction (the same reasoning that keeps ADR-67 WD1 non-negotiable at the parameter boundary,
+        # carried into the body). No-op on a normal `check` run — `inferred_param?` is false unless the
+        # `parameter_inference:` gate seeded the table.
+        def inferred_param_receiver?(call_node, scope)
+          inferred_param_rooted?(call_node.receiver, scope)
+        end
+
+        # ADR-67 WD6b — the argument-position analogue: true when `arg` is rooted at an inferred-parameter
+        # local. The argument-type-mismatch rule declines on it for the same lower-bound reason.
+        def inferred_param_argument?(arg, scope)
+          inferred_param_rooted?(arg, scope)
+        end
+
+        # ADR-67 WD6b — see {CheckRules::InferredParamGuard} for the shared root-walk contract.
+        def inferred_param_rooted?(node, scope)
+          InferredParamGuard.rooted?(node, scope)
+        end
+
         def constant_class_name(value)
           CONSTANT_CLASSES.each { |klass, name| return name if value.is_a?(klass) }
           nil
@@ -942,6 +1100,10 @@ module Rigor
           scope = scope_index[call_node]
           return nil if scope.nil?
 
+          # ADR-67 WD6b — an inferred-parameter receiver's type is an open-call-site lower bound; a wrong-arity
+          # firing against it is an FP by construction. Decline.
+          return nil if inferred_param_receiver?(call_node, scope)
+
           receiver_type = scope.type_of(call_node.receiver)
           class_name = concrete_class_name(receiver_type)
           return nil if class_name.nil?
@@ -1094,6 +1256,11 @@ module Rigor
           # flow-observed nil keeps firing exactly as before.
           return nil if scope.declaration_sourced?(:local, call_node.receiver.name)
 
+          # ADR-67 WD6b — an inferred-parameter receiver's type (incl. any nil constituent unioned in from a
+          # nil call site) is an open-call-site lower bound; a possible-nil firing against it is an FP by
+          # construction. Decline.
+          return nil if scope.inferred_param?(call_node.receiver.name)
+
           receiver_type = scope.type_of(call_node.receiver)
           return nil unless receiver_type.is_a?(Type::Union)
 
@@ -1396,6 +1563,178 @@ module Rigor
           )
         end
 
+        # `call.raise-non-exception` — `raise x` / `fail x` where the first argument's statically-inferred
+        # type is provably NOT a legal raise operand (PHPStan ThrowExprTypeRule analogue). Legal operands:
+        # an Exception class object, an Exception instance, a String (raises RuntimeError), or any object
+        # whose class defines `#exception` (the duck protocol `raise` consults at runtime). Anything else
+        # (`raise 42`, `raise :sym`, `raise nil` — an explicit nil argument is a TypeError, unlike bare
+        # `raise` which re-raises `$!`) raises TypeError at runtime.
+        #
+        # Conservative envelope (FP discipline):
+        # - Implicit-self `raise` / `fail` only; an explicit-receiver call is a user method, not Kernel#raise.
+        # - Silent when the project redefines `raise` / `fail` anywhere the call could resolve (a same-file
+        #   toplevel def, an Object/Kernel monkey-patch, or a def on the enclosing class — in source or via
+        #   `pre_eval:`).
+        # - Only the first positional argument is checked; splat / kwargs / forwarded first args bail.
+        # - Fires only on a concrete verdict: Dynamic / Top / unknown / unresolved types are silent, and a
+        #   Union fires only when EVERY arm is independently illegal.
+        # - A Class operand (`Type::Singleton`) is exact, so both `:disjoint` and `:superclass` orderings
+        #   against Exception are provably illegal — but only when the class is RBS-known, not an ADR-26
+        #   open receiver / synthesized stub, and its singleton defines no `exception` method.
+        # - An instance operand's nominal class is NOT exact (a runtime subclass could define `#exception`
+        #   or be an Exception), so only `:disjoint` fires, and the generic carriers (`Class` / `Module` /
+        #   `Object` / `BasicObject`) plus module-typed values (any includer could be an Exception) bail.
+        RAISE_METHOD_NAMES = %i[raise fail].freeze
+        private_constant :RAISE_METHOD_NAMES
+
+        # Instance types whose nominal class subsumes exception values (or class objects), so a "disjoint
+        # from Exception" ordering proves nothing about the runtime value. `Object` / `BasicObject` order as
+        # `:superclass` (already silent) but are listed for explicitness.
+        RAISE_UNEXACT_INSTANCE_CLASSES = %w[Class Module Object BasicObject].freeze
+        private_constant :RAISE_UNEXACT_INSTANCE_CLASSES
+
+        def raise_non_exception_diagnostic(path, call_node, scope_index)
+          return nil unless call_node.receiver.nil?
+          return nil unless RAISE_METHOD_NAMES.include?(call_node.name)
+          return nil unless call_node.block.nil?
+
+          arg = first_positional_raise_operand(call_node)
+          return nil if arg.nil?
+
+          scope = scope_index[arg] || scope_index[call_node]
+          return nil if scope.nil?
+          return nil if raise_redefined_in_scope?(scope, call_node.name)
+
+          operand_type = scope.type_of(arg)
+          return nil unless raise_operand_verdict(operand_type, scope) == :illegal
+
+          build_raise_non_exception_diagnostic(path, call_node, operand_type)
+        end
+
+        def first_positional_raise_operand(call_node)
+          args = call_node.arguments&.arguments
+          return nil if args.nil? || args.empty?
+
+          first = args.first
+          return nil if first.is_a?(Prism::SplatNode) || first.is_a?(Prism::KeywordHashNode) ||
+                        first.is_a?(Prism::BlockArgumentNode) || first.is_a?(Prism::ForwardingArgumentsNode)
+
+          first
+        end
+
+        # True when a project-side definition of `raise` / `fail` could shadow Kernel's at this call site:
+        # a same-file toplevel def, a monkey-patch on Object / Kernel (in source or `pre_eval:`), or a def
+        # on the enclosing class (instance or singleton side — implicit self dispatches to either depending
+        # on context, and being silent for both is the cheap conservative answer).
+        def raise_redefined_in_scope?(scope, name)
+          return true if scope.top_level_def_for(name)
+          return true if source_declared_method?(scope, "Object", name, :instance)
+          return true if source_declared_method?(scope, "Kernel", name, :instance)
+
+          self_type = scope.self_type
+          return false unless self_type.respond_to?(:class_name)
+
+          class_name = self_type.class_name
+          return false if class_name.nil?
+
+          source_declared_method?(scope, class_name, name, :instance) ||
+            source_declared_method?(scope, class_name, name, :singleton)
+        end
+
+        # Trinary verdict — `:legal` / `:illegal` / `:unknown`. Only `:illegal` fires; anything the engine
+        # cannot prove stays `:unknown` (silent).
+        def raise_operand_verdict(type, scope)
+          case type
+          when Type::Union
+            verdicts = type.members.map { |member| raise_operand_verdict(member, scope) }
+            return :illegal if verdicts.all?(:illegal)
+
+            verdicts.all?(:legal) ? :legal : :unknown
+          when Type::Singleton
+            raise_class_operand_verdict(type.class_name, scope)
+          else
+            raise_instance_operand_verdict(type, scope)
+          end
+        end
+
+        # A `Type::Singleton` names ONE exact class / module object, so an ordering that places it outside
+        # Exception's ancestry (`:disjoint`, or `:superclass` — e.g. `raise Object`) is a proof, provided
+        # the singleton also lacks an `exception` method (`raise Klass` calls `Klass.exception`). A module
+        # constant orders `:disjoint` and fires unless its singleton defines `exception`.
+        def raise_class_operand_verdict(class_name, scope)
+          return :unknown if class_name.nil? || scope.environment.nil?
+          return :unknown if unbounded_receiver_surface?(class_name, scope)
+          return :unknown if Rigor::Reflection.discovered_class?(class_name, scope: scope)
+          return :unknown unless Rigor::Reflection.rbs_class_known?(class_name, scope: scope)
+
+          case Rigor::Reflection.class_ordering(class_name, "Exception", scope: scope)
+          when :equal, :subclass then :legal
+          when :superclass, :disjoint
+            raise_duck_exception?(class_name, :singleton, scope) ? :legal : :illegal
+          else
+            :unknown
+          end
+        end
+
+        # An instance operand: legal when its class is String-family (raises RuntimeError) or an Exception
+        # descendant; illegal only when the class is fully known, exact enough (not a generic metaclass /
+        # module carrier), provably disjoint from BOTH, and defines no `#exception`. `:superclass` stays
+        # silent — a value typed `Object` may well BE an Exception at runtime.
+        def raise_instance_operand_verdict(type, scope)
+          class_name = concrete_class_name(type)
+          return :unknown if class_name.nil? || scope.environment.nil?
+          return :unknown if RAISE_UNEXACT_INSTANCE_CLASSES.include?(class_name)
+          return :unknown if unbounded_receiver_surface?(class_name, scope)
+          # A project-declared class's ancestry must not be proven from RBS alone: a `sig/` declaration that
+          # omits the superclass (`class Conflict` for a source-side `class Conflict < StandardError`)
+          # defaults to Object in the RBS env, which would read as "disjoint from Exception" for a class
+          # that IS one at runtime (the rule's first self-check firing, `Plugin::FactStore::Conflict`).
+          # Source-discovered classes stay silent.
+          return :unknown if Rigor::Reflection.discovered_class?(class_name, scope: scope)
+          return :unknown unless Rigor::Reflection.rbs_class_known?(class_name, scope: scope)
+          return :unknown if scope.environment.rbs_module?(class_name)
+
+          string_ordering = Rigor::Reflection.class_ordering(class_name, "String", scope: scope)
+          return :legal if %i[equal subclass].include?(string_ordering)
+
+          case Rigor::Reflection.class_ordering(class_name, "Exception", scope: scope)
+          when :equal, :subclass then :legal
+          when :disjoint
+            raise_duck_exception?(class_name, :instance, scope) ? :legal : :illegal
+          else
+            :unknown
+          end
+        end
+
+        # Whether the class carries an `exception` method on the given side — from RBS, an in-source `def`,
+        # or a `pre_eval:` patch. An unbuildable definition returns true (assume the duck) so structural
+        # RBS gaps never manufacture a firing.
+        def raise_duck_exception?(class_name, kind, scope)
+          return true if source_declared_method?(scope, class_name, :exception, kind)
+
+          definition = if kind == :singleton
+                         Rigor::Reflection.singleton_definition(class_name, scope: scope)
+                       else
+                         Rigor::Reflection.instance_definition(class_name, scope: scope)
+                       end
+          return true if definition.nil?
+
+          !definition.methods[:exception].nil?
+        end
+
+        def build_raise_non_exception_diagnostic(path, call_node, operand_type)
+          Diagnostic.from_message_loc(
+            call_node,
+            rule: RULE_RAISE_NON_EXCEPTION,
+            path: path,
+            message: "`#{call_node.name}' operand types as #{operand_type.describe(:short)}, which is not " \
+                     "an Exception class, an Exception instance, a String, or an object defining " \
+                     "`#exception' — this raises TypeError at runtime",
+            severity: :error,
+            method_name: call_node.name.to_s
+          )
+        end
+
         # v0.1.2 — `flow.unreachable-branch`. Fires when an `IfNode` / `UnlessNode` whose predicate is a
         # literal `true` / `false` / `nil` (or a literal numeric / string / symbol whose Ruby truthiness is
         # known at-a-glance) has an observable dead branch. The diagnostic points at the dead branch (not
@@ -1468,6 +1807,10 @@ module Rigor
           scope = scope_index[call_node]
           return nil if scope.nil?
 
+          # ADR-67 WD6b — an inferred-parameter receiver's nominal type is an open-call-site lower bound; a
+          # private-method visibility firing against it is an FP by construction. Decline.
+          return nil if inferred_param_receiver?(call_node, scope)
+
           receiver_type = scope.type_of(call_node.receiver)
           return nil unless receiver_type.is_a?(Type::Nominal)
 
@@ -1532,6 +1875,17 @@ module Rigor
           )
         end
 
+        def build_void_value_use_diagnostic(path, result)
+          Diagnostic.from_node(
+            result.void_node,
+            rule: RULE_VALUE_USE_VOID,
+            path: path,
+            message: "value use of `void': `#{result.origin.label}' declares `-> void', so its return " \
+                     "recovers to `top' and should not be used as a value",
+            severity: :warning
+          )
+        end
+
         def unreachable_clause_message(result)
           subject = result.subject_name
           kw = result.keyword
@@ -1547,6 +1901,24 @@ module Rigor
           end
         end
 
+        def build_shadowed_rescue_diagnostic(path, result)
+          Diagnostic.from_node(
+            result.clause,
+            rule: RULE_SHADOWED_RESCUE_CLAUSE,
+            path: path,
+            message: shadowed_rescue_message(result),
+            severity: :warning
+          )
+        end
+
+        def shadowed_rescue_message(result)
+          earlier = result.earlier_sources.each_with_index.map do |source, index|
+            "`#{source}' (line #{result.earlier_lines[index]})"
+          end
+          "shadowed `#{result.clause_source}': every exception class it names is already caught " \
+            "by the earlier #{earlier.join(' and ')} clause#{'s' if earlier.size > 1}, so this clause can never run"
+        end
+
         def build_dead_assignment_diagnostic(path, write_node, def_node)
           Diagnostic.from_name_loc(
             write_node,
@@ -1557,6 +1929,32 @@ module Rigor
           )
         end
 
+        # The diagnostic points at the LATER occurrence (the entry that wins at runtime) and names the
+        # first occurrence's line, so the fix — delete or rename one of the two — is visible from the
+        # message alone.
+        def build_duplicate_hash_key_diagnostic(path, result)
+          first_line = result[:first_key_node].location.start_line
+          Diagnostic.from_node(
+            result[:key_node],
+            rule: RULE_DUPLICATE_HASH_KEY,
+            path: path,
+            message: "duplicate hash key `#{result[:key_label]}' in the same literal; this entry " \
+                     "overwrites the value first set at line #{first_line}",
+            severity: :warning
+          )
+        end
+
+        def build_return_in_ensure_diagnostic(path, return_node)
+          Diagnostic.from_location(
+            return_node.keyword_loc,
+            rule: RULE_RETURN_IN_ENSURE,
+            path: path,
+            message: "`return' inside `ensure' discards the method's in-flight return value " \
+                     "and swallows any in-flight exception",
+            severity: :warning
+          )
+        end
+
         def build_ivar_write_mismatch_diagnostic(path, node, class_name, ivar_name, first_class, other_class)
           Diagnostic.from_name_loc(
             node,
@@ -1675,6 +2073,9 @@ module Rigor
           param_overrides = Rigor::RbsExtended.param_type_override_map(method_def, environment: scope.environment)
           mismatch = argument_mismatch(method_def.method_types, call_node, scope, param_overrides)
           return nil if mismatch.nil?
+          # ADR-67 WD6b — the mismatching argument is an inferred-parameter local, whose type is an
+          # open-call-site lower bound; firing argument-type-mismatch against it is an FP by construction.
+          return nil if inferred_param_argument?(mismatch[:node], scope)
 
           build_argument_type_diagnostic(path, call_node, class_name, mismatch)
         end
@@ -2169,11 +2570,16 @@ module Rigor
           declared_return_union(method_def, scope.environment)
         end
 
-        def declared_return_union(method_def, _environment)
+        # `type_vars:` — ADR-35 WD9 tier 1. When the caller supplies a generic-instantiation
+        # substitution map (parent-side, keyed by the parent class's declared type-parameter names),
+        # a `-> T` return is translated at its instantiated type (`-> Integer`) rather than degrading
+        # to `Dynamic[Top]`. The default empty map is the pre-WD9 behaviour, under which any type
+        # variable degrades to `Dynamic[Top]` and the rule stays silent.
+        def declared_return_union(method_def, _environment, type_vars: {})
           translated = method_def.method_types.filter_map do |mt|
             Inference::RbsTypeTranslator.translate(
               mt.type.return_type,
-              self_type: nil, instance_type: nil, type_vars: {}
+              self_type: nil, instance_type: nil, type_vars: type_vars
             )
           rescue StandardError
             nil
@@ -2401,8 +2807,9 @@ module Rigor
           return nil if resolved.nil?
 
           scope, override_method, parent_class, parent_method = resolved
+          parent_type_vars = ancestor_instantiation_type_vars(scope, parent_class)
           override_return = declared_return_union(override_method, scope.environment)
-          parent_return = declared_return_union(parent_method, scope.environment)
+          parent_return = declared_return_union(parent_method, scope.environment, type_vars: parent_type_vars)
           return nil if override_return.nil? || parent_return.nil?
           return nil if dynamic_top?(parent_return) # untyped / unbound-generic parent contract
 
@@ -2441,6 +2848,56 @@ module Rigor
           name.to_s.delete_prefix("::")
         end
 
+        # ADR-35 WD9 tier 1 — generic-instantiation-aware comparison. Builds the substitution map
+        # `{ parent_type_param_name => instantiated Rigor::Type }` for the parent contract as the
+        # overriding subclass instantiates it (RBS `class Sub < Parent[Concrete]` / `include
+        # _Iface[Concrete]`). Mirrors the ADR-4 Phase 2d dispatcher zip (`build_type_vars`): the
+        # parent's declared type-parameter names zipped against the subclass-side instantiation args.
+        #
+        # Returns `{}` — restoring the pre-WD9 behaviour under which any parent type variable degrades
+        # to `Dynamic[Top]` and the rule stays silent — whenever the subclass does not instantiate the
+        # ancestor generically, the RBS definition cannot be built, arities disagree, or an argument
+        # fails to translate. This is the FP-safety contract: substitution only ever *adds* precision
+        # (a `-> T` compared at `-> Integer`); an unbound / unresolved generic keeps degrading to
+        # silence, never a false `:no`.
+        def ancestor_instantiation_type_vars(scope, parent_class)
+          self_type = scope.self_type
+          return {} unless self_type.respond_to?(:class_name)
+
+          args = ancestor_instantiation_args(scope, self_type.class_name.to_s, parent_class)
+          return {} if args.nil? || args.empty?
+
+          param_names = Reflection.class_type_param_names(parent_class, scope: scope)
+          return {} if param_names.empty? || param_names.size != args.size
+
+          translated = args.map do |arg|
+            Inference::RbsTypeTranslator.translate(arg, self_type: nil, instance_type: nil, type_vars: {})
+          rescue StandardError
+            nil
+          end
+          return {} if translated.any?(&:nil?)
+
+          param_names.zip(translated).to_h
+        end
+
+        # The RBS type arguments the subclass applies to `parent_class` in its ancestry, or nil when
+        # the subclass has no RBS definition or does not name that ancestor. Reads the resolved
+        # instance-ancestor list (`RBS::Definition#ancestors`), whose `Ancestor::Instance` entries carry
+        # the instantiation `.args` for each superclass / included module. Fail-soft: any RBS build
+        # error yields nil, which the caller treats as "no instantiation" and degrades to silence.
+        def ancestor_instantiation_args(scope, subclass_name, parent_class)
+          definition = Reflection.instance_definition(subclass_name, scope: scope)
+          return nil if definition.nil?
+
+          target = normalize_class_name(parent_class)
+          ancestor = definition.ancestors.ancestors.find do |anc|
+            anc.respond_to?(:args) && normalize_class_name(anc.name.to_s) == target
+          end
+          ancestor&.args
+        rescue ::RBS::BaseError, StandardError
+          nil
+        end
+
         def build_override_return_widened_diagnostic(path, def_node, parent_class, parent_return, override_return)
           Diagnostic.from_name_loc(
             def_node,
@@ -2469,9 +2926,10 @@ module Rigor
           resolved = resolve_authored_override(def_node, scope_index)
           return nil if resolved.nil?
 
-          _scope, override_method, parent_class, parent_method = resolved
+          scope, override_method, parent_class, parent_method = resolved
+          parent_type_vars = ancestor_instantiation_type_vars(scope, parent_class)
           override_params = positional_param_types(override_method)
-          parent_params = positional_param_types(parent_method)
+          parent_params = positional_param_types(parent_method, type_vars: parent_type_vars)
           return nil if override_params.nil? || parent_params.nil?
 
           index = first_narrowed_param_index(override_params, parent_params)
@@ -2487,7 +2945,11 @@ module Rigor
         # 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)
+        # `type_vars:` — ADR-35 WD9 tier 1, parent side only. Substitutes the generic-instantiation
+        # map (parent class's type params → the subclass's instantiation) so a parent `(T)` parameter
+        # is compared at its instantiated type. Empty (the default, and the override side) keeps the
+        # pre-WD9 degrade-to-`Dynamic[Top]` behaviour.
+        def positional_param_types(method_def, type_vars: {})
           method_types = method_def.method_types
           return nil unless method_types.size == 1
 
@@ -2496,7 +2958,7 @@ module Rigor
 
           (func.required_positionals + func.optional_positionals).map do |param|
             Inference::RbsTypeTranslator.translate(
-              param.type, self_type: nil, instance_type: nil, type_vars: {}
+              param.type, self_type: nil, instance_type: nil, type_vars: type_vars
             )
           rescue StandardError
             nil