rigortype 0.1.17 → 0.1.19

data/lib/rigor/analysis/check_rules.rb

@@ -7,10 +7,12 @@ require_relative "../source/node_walker"
 require_relative "../type"
 require_relative "diagnostic"
 require_relative "dependency_recorder"
+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/dead_assignment_collector"
 require_relative "check_rules/ivar_write_collector"
+require_relative "check_rules/main_pass_collector"
 require_relative "check_rules/self_closedness_scanner"
 
 module Rigor
@@ -162,32 +164,149 @@ module Rigor
       # @param root [Prism::Node]
       # @param scope_index [Hash{Prism::Node => Rigor::Scope}]
       # @return [Array<Rigor::Analysis::Diagnostic>]
-      def diagnose(path:, root:, scope_index:, self_call_misses: [], comments: [], disabled_rules: [])
+      #
+      # ADR-53 B4 — when `node_collectors` is supplied, the converged
+      # {Plugin::NodeRuleWalk} traversal has already populated the built-in
+      # collectors (including the main pass) in one shared walk with the
+      # plugin node-rules, so they are consumed as-is. When it is nil (a
+      # direct caller with no plugin walk, e.g. a unit test), the standalone
+      # {RuleWalk} walk runs here instead, so `diagnose` stays correct
+      # without the converged path.
+      def diagnose(path:, root:, scope_index:, self_call_misses: [], comments: [], disabled_rules: [],
+                   node_collectors: nil)
+        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))
+        filter_suppressed(diagnostics, comments: comments, disabled_rules: disabled_rules)
+      end
+
+      # 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
+      # diagnostics for one node, in the same emission order as before.
+      def main_pass_node_diagnostics(path, node, scope_index)
+        case node
+        when Prism::CallNode
+          call_node_diagnostics(path, node, scope_index)
+        when Prism::DefNode
+          [
+            return_type_mismatch_diagnostic(path, node, scope_index),
+            override_visibility_diagnostic(path, node, scope_index),
+            override_return_widened_diagnostic(path, node, scope_index),
+            override_param_narrowed_diagnostic(path, node, scope_index)
+          ].compact
+        when Prism::IfNode, Prism::UnlessNode
+          [unreachable_branch_diagnostic(path, node, scope_index)].compact
+        else
+          []
+        end
+      end
+
+      # Constructs the fresh, unpopulated built-in collector set keyed by
+      # role, including the main pass. Split out so the converged walk
+      # (ADR-53 B4) can build the collectors, drive them via a
+      # {RuleWalk::CollectorDriver} inside the single {Plugin::NodeRuleWalk}
+      # traversal, and hand the populated set back to {.diagnose} as
+      # `node_collectors:`. The main pass needs `path` because its per-node
+      # diagnostics carry it (ADR-53 B3c hosts it on the same walk).
+      def build_node_collectors(path, scope_index)
+        {
+          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),
+          ivar_writes: IvarWriteCollector.new(scope_index),
+          dead_assignments: DeadAssignmentCollector.new(scope_index)
+        }
+      end
+
+      # A {RuleWalk::CollectorDriver} over a built-in collector set, for a
+      # foreign traversal to drive (ADR-53 B4). The driver visits each node
+      # and derives child contexts exactly as the standalone {RuleWalk}
+      # walk would.
+      def node_collector_driver(collectors)
+        RuleWalk::CollectorDriver.new(collectors.values)
+      end
+
+      # ADR-53 Track B — the {RuleWalk}-hosted built-in collectors (the main
+      # pass and the four fact collectors) all ride one traversal of the
+      # file instead of one walk each. Returns the populated collectors
+      # keyed by role so the caller can build the diagnostics from each
+      # collector's `results`. Used on the standalone path (no converged
+      # plugin walk); the converged path populates the same collector set
+      # via {.node_collector_driver} instead.
+      #
+      # Under `RIGOR_SHADOW_RULE_WALK=1` each hosted collector's legacy
+      # single-collector `#collect` walk also runs as the oracle and any
+      # divergence aborts the run — the corpus-scale half of the
+      # equivalence harness (the curated half is `rule_walk_equivalence_spec`).
+      def run_node_collectors(path, root, scope_index)
+        collectors = build_node_collectors(path, scope_index)
+        RuleWalk.run(root, collectors.values)
+        shadow_verify_node_collectors(path, root, scope_index, collectors) if ENV["RIGOR_SHADOW_RULE_WALK"]
+        collectors
+      end
+
+      def shadow_verify_node_collectors(path, root, scope_index, collectors)
+        divergences = collectors.filter_map do |role, collector|
+          legacy = oracle_results(role, collector, path, root, scope_index)
+          next if comparable(legacy) == comparable(collector.results)
+
+          "#{role} legacy=#{legacy.size} walk=#{collector.results.size}"
+        end
+        return if divergences.empty?
+
+        raise "RIGOR_SHADOW_RULE_WALK divergence: #{divergences.join('; ')}"
+      end
+
+      # Normalises a collector's result for value comparison. The fact
+      # collectors return `Data` / Hash structures that already compare by
+      # value; the main pass returns {Diagnostic} objects (plain objects
+      # with identity `==`), so serialise those to hashes first.
+      def comparable(results)
+        return results.map(&:to_h) if results.is_a?(Array) && results.first.is_a?(Diagnostic)
+
+        results
+      end
+
+      # The oracle each hosted collector's walk result is checked against.
+      # The fact collectors re-run their legacy single-collector `#collect`
+      # walk; the main pass re-runs the former inline `Source::NodeWalker`
+      # `case` (`main_pass_oracle`) since its diagnostics are the result.
+      def oracle_results(role, collector, path, root, scope_index)
+        return main_pass_oracle(path, root, scope_index) if role == :main_pass
+
+        collector.class.new(scope_index).collect(root)
+      end
+
+      # The former inline main pass, kept as the shadow oracle: walks the
+      # tree with `Source::NodeWalker.each` and accumulates the same
+      # per-node diagnostics in the same order {MainPassCollector} now
+      # produces them on the shared walk.
+      def main_pass_oracle(path, root, scope_index)
         diagnostics = []
         Source::NodeWalker.each(root) do |node|
-          case node
-          when Prism::CallNode
-            diagnostics.concat(call_node_diagnostics(path, node, scope_index))
-          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
-          end
+          diagnostics.concat(main_pass_node_diagnostics(path, node, scope_index))
         end
-        diagnostics.concat(self_undefined_method_diagnostics(path, self_call_misses, root, scope_index))
-        diagnostics.concat(always_truthy_condition_diagnostics(path, root, scope_index))
-        diagnostics.concat(unreachable_clause_diagnostics(path, root, scope_index))
-        diagnostics.concat(ivar_write_mismatch_diagnostics(path, root, scope_index))
-        diagnostics.concat(dead_assignment_diagnostics(path, root, scope_index))
-        filter_suppressed(diagnostics, comments: comments, disabled_rules: disabled_rules)
+        diagnostics
+      end
+
+      # ADR-53 B4 — corpus-scale oracle for the CONVERGED walk: the
+      # collectors (including the main pass, ADR-53 B3c) were populated by
+      # the {Plugin::NodeRuleWalk} traversal, not by `RuleWalk.run`, so
+      # re-run each collector's legacy oracle (the fact collectors'
+      # `#collect` walk, the main pass's inline `Source::NodeWalker` `case`)
+      # and assert the converged walk produced byte-identical results. Same
+      # divergence contract as {.shadow_verify_node_collectors}; nil
+      # collectors (caller without built-in collection) is a no-op. `path`
+      # is threaded because the main pass's oracle carries it.
+      def shadow_verify_converged_collectors(path, root, scope_index, collectors)
+        return if collectors.nil?
+
+        shadow_verify_node_collectors(path, root, scope_index, collectors)
       end
 
       def call_node_diagnostics(path, node, scope_index)
@@ -224,8 +343,8 @@ module Rigor
       #   Class-level ivars (`@x = 1` outside any def, in the
       #   class body) are also skipped — they're a separate
       #   surface (`Module#@var`) the engine doesn't yet model.
-      def ivar_write_mismatch_diagnostics(path, root, scope_index)
-        IvarWriteCollector.new(scope_index).collect(root).flat_map do |class_name, writes_by_ivar|
+      def ivar_write_mismatch_diagnostics(path, ivar_writes)
+        ivar_writes.flat_map do |class_name, writes_by_ivar|
           writes_by_ivar.flat_map do |ivar_name, writes|
             ivar_mismatch_diagnostics_for(path, class_name, ivar_name, writes)
           end
@@ -238,8 +357,8 @@ module Rigor
       # read in the same body. The
       # `Analysis::CheckRules::DeadAssignmentCollector` describes
       # the conservative envelope.
-      def dead_assignment_diagnostics(path, root, scope_index)
-        DeadAssignmentCollector.new(scope_index).collect(root).map do |result|
+      def dead_assignment_diagnostics(path, dead_assignments)
+        dead_assignments.map do |result|
           build_dead_assignment_diagnostic(path, result[:write_node], result[:def_node])
         end
       end
@@ -251,8 +370,8 @@ module Rigor
       # predicate skip envelope (see
       # `Analysis::CheckRules::AlwaysTruthyConditionCollector`
       # for the full triage rationale).
-      def always_truthy_condition_diagnostics(path, root, scope_index)
-        AlwaysTruthyConditionCollector.new(scope_index).collect(root).map do |result|
+      def always_truthy_condition_diagnostics(path, results)
+        results.map do |result|
           build_always_truthy_condition_diagnostic(path, result.node, result.polarity)
         end
       end
@@ -261,8 +380,8 @@ module Rigor
       # the flow engine's narrowing proves can never match (its narrowed
       # subject is `bot`). The squiggle lands on the dead clause's body,
       # mirroring `flow.unreachable-branch`.
-      def unreachable_clause_diagnostics(path, root, scope_index)
-        UnreachableClauseCollector.new(scope_index).collect(root).map do |result|
+      def unreachable_clause_diagnostics(path, results)
+        results.map do |result|
           build_unreachable_clause_diagnostic(path, result)
         end
       end
@@ -393,7 +512,18 @@ module Rigor
           scope = scope_index[call_node]
           return nil if scope.nil?
 
-          receiver_type = scope.type_of(call_node.receiver)
+          # 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
+          # all, so it is silent (no dead-code diagnostic — `&.` is the
+          # nil-skip operator by design, and frightening working
+          # `@x = nil; @x&.m` code would breach FP discipline). A nil-bearing
+          # *union* receiver is left to flow through unchanged: a `T | nil`
+          # union has no single concrete class, so the rule already bails
+          # below — preserving that keeps `&.` from newly firing on the
+          # non-nil constituent (which, for a cross-file project def, would
+          # be a working-code false positive).
+          receiver_type = safe_navigation_receiver(call_node, scope)
           class_name = concrete_class_name(receiver_type)
           return nil if class_name.nil?
 
@@ -714,7 +844,7 @@ module Rigor
         # by `undefined_method_diagnostic`; it returns nil
         # when the call's receiver / RBS coverage / call shape
         # disqualifies the rule.
-        # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/AbcSize
         def wrong_arity_diagnostic(path, call_node, scope_index)
           return nil if call_node.receiver.nil?
           return nil unless plain_positional_call?(call_node)
@@ -727,6 +857,15 @@ module Rigor
           return nil if class_name.nil?
 
           kind = receiver_type.is_a?(Type::Singleton) ? :singleton : :instance
+          # `Struct.new(:a, :b).new(...)` chained: the inner
+          # `Struct.new(...)` is an anonymous Struct *subclass* whose
+          # `.new` accepts any positional arity (one slot per member,
+          # all defaulting to nil) — including zero. The receiver types
+          # as `Singleton[Struct]` (so the call-site `.new` dispatches,
+          # per the dispatcher's `struct_new_lift`), but validating that
+          # `.new` against the real `Struct.new(*Symbol)` signature is a
+          # false positive. Skip arity-checking the chained position.
+          return nil if anonymous_struct_new_call?(call_node, class_name, kind)
           return nil if scope.discovered_method?(class_name, call_node.name, kind)
 
           return nil unless Rigor::Reflection.rbs_class_known?(class_name, scope: scope)
@@ -744,7 +883,25 @@ module Rigor
 
           build_arity_diagnostic(path, call_node, class_name, min, max, actual)
         end
-        # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/AbcSize
+
+        # True for the outer `.new` of a chained `Struct.new(...).new`:
+        # `class_name`/`kind` already pin the receiver to
+        # `Singleton[Struct]`, and the receiver node is itself a
+        # `Struct.new` (or `::Struct.new`) call — the anonymous subclass.
+        def anonymous_struct_new_call?(call_node, class_name, kind)
+          return false unless class_name == "Struct" && kind == :singleton
+          return false unless call_node.name == :new
+
+          receiver = call_node.receiver
+          return false unless receiver.is_a?(Prism::CallNode) && receiver.name == :new
+
+          inner = receiver.receiver
+          return true if inner.is_a?(Prism::ConstantReadNode) && inner.name == :Struct
+
+          # `::Struct.new(...).new` — a top-level constant path.
+          inner.is_a?(Prism::ConstantPathNode) && inner.parent.nil? && inner.name == :Struct
+        end
 
         def plain_positional_call?(call_node)
           arguments = call_node.arguments
@@ -836,6 +993,17 @@ module Rigor
           scope = scope_index[call_node]
           return nil if scope.nil?
 
+          # ADR-58 WD1 — a receiver whose `nil` constituent is purely
+          # declaration-sourced (the class-ivar index seed of a ctor
+          # `@x = nil` written in another method, possibly copied into a
+          # local via `r = @right`) does not fire by default: the working
+          # program's cross-method invariant is assumed per the robustness
+          # principle. The nil stays in the displayed type; only its use as
+          # diagnostic fuel is withheld. Any flow-live touch (method-local
+          # nil write, failed-guard narrowing) drops the mark upstream, so
+          # flow-observed nil keeps firing exactly as before.
+          return nil if scope.declaration_sourced?(:local, call_node.receiver.name)
+
           receiver_type = scope.type_of(call_node.receiver)
           return nil unless receiver_type.is_a?(Type::Union)
 
@@ -855,6 +1023,21 @@ module Rigor
           union.members.any? { |member| nil_member?(member) }
         end
 
+        # The receiver type the `call.undefined-method` existence check
+        # should reason about. For a safe-navigation call whose receiver
+        # types as exactly `nil`, this is `Type::Bot` — the call is
+        # statically skipped at runtime, and `concrete_class_name(Bot)` is
+        # nil so the rule bails (silent). Every other receiver (including a
+        # `T | nil` union, which already has no single concrete class) flows
+        # through unchanged.
+        def safe_navigation_receiver(call_node, scope)
+          receiver_type = scope.type_of(call_node.receiver)
+          return receiver_type unless call_node.safe_navigation?
+          return receiver_type unless nil_member?(receiver_type)
+
+          Type::Combinator.bot
+        end
+
         def nil_member?(member)
           (member.is_a?(Type::Constant) && member.value.nil?) ||
             (member.is_a?(Type::Nominal) && member.class_name == "NilClass")
@@ -1020,7 +1203,8 @@ module Rigor
             rule: RULE_NIL_RECEIVER,
             path: path,
             message: "possible nil receiver: `#{call_node.name}' is undefined on NilClass",
-            severity: :error
+            severity: :error,
+            method_name: call_node.name.to_s
           )
         end
 
@@ -1208,7 +1392,9 @@ module Rigor
             rule: RULE_VISIBILITY_MISMATCH,
             path: path,
             message: "private method `#{call_node.name}' called on #{receiver_type.class_name} receiver",
-            severity: :error
+            severity: :error,
+            receiver_type: receiver_type.class_name,
+            method_name: call_node.name.to_s
           )
         end
 
@@ -1407,12 +1593,49 @@ module Rigor
             arg_type = scope.type_of(arg)
             next if arg_type.is_a?(Type::Dynamic) || arg_type.is_a?(Type::Top)
 
-            result = Inference::Acceptance.accepts(param_type, arg_type, mode: :gradual)
-            return { node: arg, name: param.name, expected: param_type, actual: arg_type } if result.no?
+            next unless argument_genuinely_mismatches?(arg, arg_type, param_type, scope)
+
+            return { node: arg, name: param.name, expected: param_type, actual: arg_type }
           end
           nil
         end
 
+        # The parameter rejects the argument AND the rejection is not a
+        # withheld declaration-sourced-nil case.
+        def argument_genuinely_mismatches?(arg, arg_type, param_type, scope)
+          return false unless Inference::Acceptance.accepts(param_type, arg_type, mode: :gradual).no?
+
+          # ADR-58 (N2 extension) — the same declaration-sourced-nil-is-not-
+          # diagnostic-fuel criterion that governs `possible-nil-receiver`
+          # applies here. When the only reason the argument is rejected is a
+          # *declaration-sourced* nil constituent (the class-ivar index seed
+          # of a ctor `@x = nil` / a non-definitely-assigned ivar read), and
+          # the argument type with that nil removed WOULD be accepted, the
+          # working program's cross-method invariant is assumed and we do not
+          # fire. Flow-live nil (a method-local `@x = nil` write, a failed-
+          # guard narrowing) drops the provenance mark upstream and still
+          # fires. The argument's type is unchanged — only the firing
+          # decision is gated.
+          !declaration_sourced_nil_only_mismatch?(arg, arg_type, param_type, scope)
+        end
+
+        # True when `arg` is a declaration-sourced ivar read whose rejection is
+        # caused solely by its nil constituent: stripping nil from the argument
+        # type yields a type the parameter accepts (gradual mode). Mirrors the
+        # `possible-nil-receiver` WD1 gate, keyed on the ivar provenance mark
+        # rather than a local copy.
+        def declaration_sourced_nil_only_mismatch?(arg, arg_type, param_type, scope)
+          return false unless arg.is_a?(Prism::InstanceVariableReadNode)
+          return false unless scope.declaration_sourced?(:ivar, arg.name)
+          return false unless arg_type.is_a?(Type::Union)
+          return false unless union_contains_nil?(arg_type)
+
+          non_nil = Type::Combinator.union(*arg_type.members.reject { |m| nil_member?(m) })
+          return false if non_nil.is_a?(Type::Bot)
+
+          Inference::Acceptance.accepts(param_type, non_nil, mode: :gradual).yes?
+        end
+
         def argument_check_eligible?(function)
           # See `arity_eligible?`: `UntypedFunction` lacks
           # the per-arity accessors. Treat it as ineligible
@@ -1443,7 +1666,9 @@ module Rigor
             rule: RULE_ARGUMENT_TYPE,
             path: path,
             message: message,
-            severity: :error
+            severity: :error,
+            receiver_type: class_name,
+            method_name: call_node.name.to_s
           )
         end
 
@@ -1456,7 +1681,9 @@ module Rigor
             rule: RULE_WRONG_ARITY,
             path: path,
             message: message,
-            severity: :error
+            severity: :error,
+            receiver_type: class_name,
+            method_name: call_node.name.to_s
           )
         end
 
@@ -1629,7 +1856,8 @@ module Rigor
             path: path,
             message: "return-type mismatch on `#{def_node.name}': " \
                      "declared #{declared.describe(:short)}, inferred #{inferred.describe(:short)}",
-            severity: severity
+            severity: severity,
+            method_name: def_node.name.to_s
           )
         end
 
@@ -1781,7 +2009,8 @@ module Rigor
             message: "visibility of `#{def_node.name}' reduced from #{parent_visibility} to " \
                      "#{override_visibility} (overrides #{parent_class}##{def_node.name}); " \
                      "breaks substitutability",
-            severity: :warning
+            severity: :warning,
+            method_name: def_node.name.to_s
           )
         end
 
@@ -1874,7 +2103,8 @@ module Rigor
             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
+            severity: :warning,
+            method_name: def_node.name.to_s
           )
         end
 
@@ -1978,7 +2208,8 @@ module Rigor
             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
+            severity: :warning,
+            method_name: def_node.name.to_s
           )
         end
       end

data/lib/rigor/analysis/diagnostic.rb

@@ -132,6 +132,12 @@ module Rigor
         "#{source_family}.#{rule}"
       end
 
+      # `--format json` serialisation. The structured `receiver_type`
+      # / `method_name` / `project_definition_site` fields are emitted
+      # only when populated, so a consumer (`jq`, `rigor triage`, an AI
+      # agent) can group a `rigor check --format json` stream by the
+      # called class / method without parsing the human-readable
+      # `message` — the message wording is presentation, not contract.
       def to_h
         base = {
           "path" => path,
@@ -142,6 +148,8 @@ module Rigor
           "source_family" => source_family.to_s,
           "message" => message
         }
+        base["receiver_type"] = receiver_type if receiver_type
+        base["method_name"] = method_name if method_name
         base["project_definition_site"] = project_definition_site if project_definition_site
         base
       end