rigortype 0.1.18 → 0.1.19

data/lib/rigor/plugin/manifest.rb

@@ -43,7 +43,7 @@ module Rigor
 
       attr_reader :id, :version, :description, :config_schema, :config_defaults, :produces, :consumes,
                   :owns_receivers, :open_receivers, :type_node_resolvers, :block_as_methods,
-                  :heredoc_templates, :nested_class_templates, :trait_registries, :external_files,
+                  :heredoc_templates, :nested_class_templates, :trait_registries,
                   :hkt_registrations, :hkt_definitions, :signature_paths, :protocol_contracts,
                   :source_rbs_synthesizer, :additional_initializers
 
@@ -52,7 +52,7 @@ module Rigor
         description: nil, config_schema: {},
         produces: [], consumes: [], owns_receivers: [], open_receivers: [], type_node_resolvers: [],
         block_as_methods: [], heredoc_templates: [], nested_class_templates: [],
-        trait_registries: [], external_files: [],
+        trait_registries: [],
         hkt_registrations: [], hkt_definitions: [], signature_paths: [], protocol_contracts: [],
         source_rbs_synthesizer: nil, additional_initializers: []
       )
@@ -67,7 +67,6 @@ module Rigor
         validate_heredoc_templates!(heredoc_templates)
         validate_nested_class_templates!(nested_class_templates)
         validate_trait_registries!(trait_registries)
-        validate_external_files!(external_files)
         validate_hkt_registrations!(hkt_registrations)
         validate_hkt_definitions!(hkt_definitions)
         validate_signature_paths!(signature_paths)
@@ -77,7 +76,7 @@ module Rigor
 
         assign_fields(id, version, description, config_schema, produces, consumes, owns_receivers,
                       open_receivers, type_node_resolvers, block_as_methods, heredoc_templates, trait_registries,
-                      external_files, hkt_registrations, hkt_definitions, signature_paths, protocol_contracts,
+                      hkt_registrations, hkt_definitions, signature_paths, protocol_contracts,
                       source_rbs_synthesizer)
         assign_nested_class_templates(nested_class_templates)
         assign_additional_initializers(additional_initializers)
@@ -89,7 +88,7 @@ module Rigor
       # rubocop:disable Metrics/ParameterLists, Metrics/AbcSize
       def assign_fields(id, version, description, config_schema, produces, consumes, owns_receivers,
                         open_receivers, type_node_resolvers, block_as_methods, heredoc_templates, trait_registries,
-                        external_files, hkt_registrations, hkt_definitions, signature_paths, protocol_contracts,
+                        hkt_registrations, hkt_definitions, signature_paths, protocol_contracts,
                         source_rbs_synthesizer)
         @id = id.dup.freeze
         @version = version.dup.freeze
@@ -104,7 +103,6 @@ module Rigor
         @block_as_methods = block_as_methods.dup.freeze
         @heredoc_templates = heredoc_templates.dup.freeze
         @trait_registries = trait_registries.dup.freeze
-        @external_files = external_files.dup.freeze
         @hkt_registrations = hkt_registrations.dup.freeze
         @hkt_definitions = hkt_definitions.dup.freeze
         @signature_paths = signature_paths.map { |p| p.to_s.dup.freeze }.freeze
@@ -170,7 +168,6 @@ module Rigor
           "heredoc_templates" => heredoc_templates.map(&:to_h),
           "nested_class_templates" => nested_class_templates.map(&:to_h),
           "trait_registries" => trait_registries.map(&:to_h),
-          "external_files" => external_files.map(&:to_h),
           "hkt_registrations" => hkt_registrations.map(&:to_h),
           "hkt_definitions" => hkt_definitions.map { |d| { "uri" => d.uri, "params" => d.params } },
           "signature_paths" => signature_paths,
@@ -389,23 +386,6 @@ module Rigor
               "Rigor::Plugin::Macro::TraitRegistry instances, got #{entries.inspect}"
       end
 
-      # ADR-16 slice 5a — `external_files:` declares the Tier D
-      # substrate entries (external-Ruby-file inclusion under a
-      # declared `self`). Slice 5a carries the declarations on
-      # the manifest; the engine integration that walks the
-      # matched files + narrows their entry scope is **queued for
-      # slice 5b**, gated on demonstrated demand from concrete
-      # plugin targets (Redmine webhook payloads, tDiary plugin
-      # loader, etc.). Plugin authors MAY declare entries today;
-      # the substrate does not yet act on them.
-      def validate_external_files!(entries)
-        return if entries.is_a?(Array) && entries.all?(Macro::ExternalFile)
-
-        raise ArgumentError,
-              "plugin manifest external_files must be an Array of " \
-              "Rigor::Plugin::Macro::ExternalFile instances, got #{entries.inspect}"
-      end
-
       # ADR-20 slice 6 — `hkt_registrations:` declares the
       # Lightweight HKT URI registrations this plugin ships
       # (analogous to `%a{rigor:v1:hkt_register: ...}` directives

data/lib/rigor/plugin/node_rule_walk.rb

@@ -2,6 +2,7 @@
 
 require_relative "node_context"
 require_relative "../source/node_walker"
+require_relative "../analysis/check_rules/rule_walk"
 
 module Rigor
   module Plugin
@@ -64,30 +65,74 @@ module Rigor
       # Walk `root` once, dispatching every node to each matching
       # `(plugin, rule)`. Returns an Array of {Result} in plugin
       # (registry) order. `root` nil yields one empty Result per plugin.
-      def diagnostics_for_file(path:, scope:, root:)
+      #
+      # ADR-53 B4 — when `collector_driver` is given (an
+      # {Analysis::CheckRules::RuleWalk::CollectorDriver}), the SAME
+      # single traversal also drives the built-in {CheckRules} node
+      # collectors: each visited node is dispatched both to the plugin
+      # rules (this walk's original job) and to the built-in collectors
+      # (the `CollectorDriver`), so a file is walked once for both
+      # instead of once each. The two dispatch models coexist: plugin
+      # rules keep `is_a?` matching via the per-class memo and receive a
+      # lazily-built {NodeContext} (ancestors); built-in collectors keep
+      # exact-node-class dispatch and receive the immutable
+      # {RuleWalk::Context} threaded through the descent. Order is
+      # preserved because each side accumulates into its own bucket
+      # (per-plugin {Result}s / per-collector `results`) and the two are
+      # assembled separately by their respective diagnostic builders.
+      # A raising plugin rule isolates only that plugin (per-{State}
+      # rescue) and never aborts built-in collection, nor vice versa
+      # (the collectors' `visit` is the verbatim legacy gather logic,
+      # which does not raise on the corpora).
+      def diagnostics_for_file(path:, scope:, root:, collector_driver: nil)
         return @entries.map { |plugin, _| Result.new(plugin, [], nil) } if root.nil?
 
         states = @entries.map { |plugin, rules| State.new(plugin, rules, scope, root) }
-        walk(path, scope, root, states)
+        walk(path, scope, root, states, collector_driver)
         states.map(&:result)
       end
 
       private
 
-      def walk(path, scope, root, states)
-        Source::NodeWalker.each_with_ancestors(root) do |node, ancestors|
-          context = nil
-          states.each do |state|
-            next if state.failed?
+      def walk(path, scope, root, states, collector_driver)
+        context = collector_driver ? Analysis::CheckRules::RuleWalk::Context.root : nil
+        walk_node(root, [], context, path, scope, states, collector_driver)
+      end
+
+      # The single converged DFS pre-order traversal. Threads both the
+      # live `ancestors` stack (for plugin {NodeContext}) and the
+      # immutable built-in {RuleWalk::Context} (for the collectors),
+      # derived together as the walk descends — the cheap-ancestors
+      # option from the ADR-53 B4 design note. Identical pre-order over
+      # `compact_child_nodes` to both the legacy
+      # `Source::NodeWalker.each_with_ancestors` and `RuleWalk.walk`, so
+      # every node is visited in the same order each side saw before.
+      def walk_node(node, ancestors, context, path, scope, states, collector_driver)
+        return unless node.is_a?(Prism::Node)
+
+        dispatch_plugins(node, ancestors, path, scope, states)
+        collector_driver&.visit(node, context)
+
+        child_context = collector_driver&.descend(node, context)
+        ancestors.push(node)
+        node.compact_child_nodes.each do |child|
+          walk_node(child, ancestors, child_context, path, scope, states, collector_driver)
+        end
+        ancestors.pop
+      end
 
-            matched = state.rules_for(node)
-            next if matched.empty?
+      def dispatch_plugins(node, ancestors, path, scope, states)
+        node_context = nil
+        states.each do |state|
+          next if state.failed?
 
-            # One frozen NodeContext per node, built lazily and shared
-            # across every plugin that matches this node.
-            context ||= NodeContext.new(ancestors)
-            state.run_rules(matched, node, scope, path, context)
-          end
+          matched = state.rules_for(node)
+          next if matched.empty?
+
+          # One frozen NodeContext per node, built lazily and shared
+          # across every plugin that matches this node.
+          node_context ||= NodeContext.new(ancestors)
+          state.run_rules(matched, node, scope, path, node_context)
         end
       end
 

data/lib/rigor/plugin/registry.rb

@@ -7,7 +7,7 @@ module Rigor
     # ADR-52 WD1 — the compiled contribution table. Categorises a loaded
     # plugin set by which per-call contribution paths each plugin
     # actually implements, AND compiles the declarative gates (method
-    # names, `block_as_methods` verbs, `owns_receivers`) into frozen
+    # names, `block_as_methods` method names, `owns_receivers`) into frozen
     # lookup structures, so the engine's hot sites discover "no plugin
     # cares about this call" in O(1) instead of O(plugins × rules) — a
     # top hotspot on plugin-heavy projects (GitLab's 11 plugins, of
@@ -16,7 +16,7 @@ module Rigor
     #
     # Ordering contract: the gates only PRUNE consultations that could
     # not fire (every pruned rule would have failed its own `methods:` /
-    # `verbs:` check); the engine still iterates the plugin subsets in
+    # `method_names:` check); the engine still iterates the plugin subsets in
     # registry order and each plugin's rules in declaration order, so
     # the surviving contributions arrive in exactly the order the
     # ungated walk produced — diagnostics stay byte-identical. The
@@ -36,7 +36,7 @@ module Rigor
       def initialize(plugins)
         compile_memberships(plugins)
         compile_gates
-        @block_entries_by_verb = build_block_entries(plugins)
+        @block_entries_by_method_name = build_block_entries(plugins)
         @owns_receivers = plugins.flat_map { |p| manifest_for(p)&.owns_receivers || [] }.uniq.freeze
         # Per-run ancestry verdict memo, keyed by environment identity
         # then class name. Mutable inside the frozen index — sound
@@ -88,11 +88,12 @@ module Rigor
         gate.nil? || gate.include?(method_name)
       end
 
-      # The `Macro::BlockAsMethod` entries whose `verbs` include `verb`,
-      # in (plugin registration, manifest declaration) order — the same
-      # first-match order the previous plugins × entries walk visited.
-      def block_entries_for(verb)
-        @block_entries_by_verb.fetch(verb, EMPTY_BLOCK_ENTRIES)
+      # The `Macro::BlockAsMethod` entries whose `method_names` include
+      # `method_name`, in (plugin registration, manifest declaration)
+      # order — the same first-match order the previous plugins ×
+      # entries walk visited.
+      def block_entries_for(method_name)
+        @block_entries_by_method_name.fetch(method_name, EMPTY_BLOCK_ENTRIES)
       end
 
       # True when `class_name` equals or inherits from any plugin's
@@ -188,15 +189,15 @@ module Rigor
         gates.values.reduce(Set.new) { |acc, names| acc.merge(names) }.freeze
       end
 
-      # `verb Symbol → [BlockAsMethod entries]`, insertion-ordered by
-      # (plugin, declaration). Verbs are Symbol-normalised by
+      # `method-name Symbol → [BlockAsMethod entries]`, insertion-ordered
+      # by (plugin, declaration). Method names are Symbol-normalised by
       # `Macro::BlockAsMethod#initialize`.
       def build_block_entries(plugins)
         table = {}
         plugins.each do |plugin|
           entries = manifest_for(plugin)&.block_as_methods || []
           entries.each do |entry|
-            entry.verbs.each { |verb| (table[verb] ||= []) << entry }
+            entry.method_names.each { |name| (table[name] ||= []) << entry }
           end
         end
         table.each_value(&:freeze)

data/lib/rigor/scope/discovery_index.rb

@@ -22,6 +22,7 @@ module Rigor
       :in_source_constants,
       :discovered_methods,
       :discovered_def_nodes,
+      :discovered_singleton_def_nodes,
       :discovered_def_sources,
       :discovered_method_visibilities,
       :discovered_superclasses,
@@ -46,6 +47,7 @@ module Rigor
         in_source_constants: EMPTY_TABLE,
         discovered_methods: EMPTY_TABLE,
         discovered_def_nodes: EMPTY_TABLE,
+        discovered_singleton_def_nodes: EMPTY_TABLE,
         discovered_def_sources: EMPTY_TABLE,
         discovered_method_visibilities: EMPTY_TABLE,
         discovered_superclasses: EMPTY_TABLE,

data/lib/rigor/scope.rb

@@ -22,6 +22,7 @@ module Rigor
     attr_reader :environment, :locals, :fact_store, :self_type,
                 :ivars, :cvars, :globals,
                 :indexed_narrowings, :method_chain_narrowings,
+                :declaration_sourced,
                 :source_path, :discovery
 
     # ADR-53 Track A — the seed-time discovery tables live on the
@@ -43,6 +44,7 @@ module Rigor
     def in_source_constants = @discovery.in_source_constants
     def discovered_methods = @discovery.discovered_methods
     def discovered_def_nodes = @discovery.discovered_def_nodes
+    def discovered_singleton_def_nodes = @discovery.discovered_singleton_def_nodes
     def discovered_def_sources = @discovery.discovered_def_sources
     def discovered_method_visibilities = @discovery.discovered_method_visibilities
     def discovered_superclasses = @discovery.discovered_superclasses
@@ -86,8 +88,19 @@ module Rigor
     EMPTY_VAR_BINDINGS = {}.freeze
     EMPTY_INDEXED_NARROWINGS = {}.freeze
     EMPTY_CHAIN_NARROWINGS = {}.freeze
+    # ADR-58 WD1 — the set of variable references whose binding's `nil`
+    # constituent is *declaration-sourced*: it arrives only via the
+    # class-ivar index seed (a ctor `@x = nil` written in another method),
+    # never through a method-local write, narrowing, or parameter. Members
+    # are frozen `[kind, name]` pairs (`[:ivar, :@x]`, `[:local, :r]`).
+    # `possible-nil-receiver` consults this set and declines to fire when the
+    # receiver's optionality is purely declaration-sourced — the working
+    # program's cross-method invariant is assumed per the robustness
+    # principle. Any flow-live touch (write / narrowing) drops the mark, so
+    # the diagnostic keeps firing exactly as before on flow-observed nil.
+    EMPTY_DECLARATION_SOURCED = Set.new.freeze
     private_constant :EMPTY_VAR_BINDINGS, :EMPTY_INDEXED_NARROWINGS,
-                     :EMPTY_CHAIN_NARROWINGS
+                     :EMPTY_CHAIN_NARROWINGS, :EMPTY_DECLARATION_SOURCED
 
     class << self
       def empty(environment: Environment.default, source_path: nil)
@@ -106,6 +119,7 @@ module Rigor
       discovery: DiscoveryIndex::EMPTY,
       indexed_narrowings: EMPTY_INDEXED_NARROWINGS,
       method_chain_narrowings: EMPTY_CHAIN_NARROWINGS,
+      declaration_sourced: EMPTY_DECLARATION_SOURCED,
       source_path: nil
     )
       @environment = environment
@@ -118,6 +132,7 @@ module Rigor
       @discovery = discovery
       @indexed_narrowings = indexed_narrowings
       @method_chain_narrowings = method_chain_narrowings
+      @declaration_sourced = declaration_sourced
       @source_path = source_path
       freeze
     end
@@ -141,9 +156,15 @@ module Rigor
       # narrowing keyed on `(local, :x, :last)` no longer holds.
       new_indexed_narrowings = drop_indexed_narrowings_for(:local, name)
       new_chain_narrowings = drop_chain_narrowings_for(:local, name)
+      # ADR-58 WD1 — rebinding a local is a flow-live touch: any prior
+      # declaration-sourced mark on `name` no longer holds (the new value
+      # may carry a method-local nil). `with_declaration_sourced_local`
+      # re-establishes the mark afterward when the RHS is a pure copy of a
+      # declaration-sourced ivar read; the default is to drop it.
       rebuild(locals: new_locals, fact_store: new_fact_store,
               indexed_narrowings: new_indexed_narrowings,
-              method_chain_narrowings: new_chain_narrowings)
+              method_chain_narrowings: new_chain_narrowings,
+              declaration_sourced: drop_declaration_sourced_for(:local, name))
     end
 
     def with_fact(fact)
@@ -201,9 +222,46 @@ module Rigor
     def with_ivar(name, type)
       new_indexed_narrowings = drop_indexed_narrowings_for(:ivar, name)
       new_chain_narrowings = drop_chain_narrowings_for(:ivar, name)
+      # ADR-58 WD1 — a method-local ivar write or narrowing is flow-live:
+      # drop any declaration-sourced mark so subsequent reads of `@name`
+      # observe flow-live provenance and fire as before. The seed path uses
+      # `seed_declaration_sourced_ivar` to (re-)establish the mark.
       rebuild(ivars: @ivars.merge(name.to_sym => type).freeze,
               indexed_narrowings: new_indexed_narrowings,
-              method_chain_narrowings: new_chain_narrowings)
+              method_chain_narrowings: new_chain_narrowings,
+              declaration_sourced: drop_declaration_sourced_for(:ivar, name))
+    end
+
+    # ADR-58 WD1 — used by the method-entry seed to mark an ivar whose only
+    # provenance is the class-ivar index. Unlike `with_ivar` this binds the
+    # type AND records the declaration-sourced mark in one transition.
+    def seed_declaration_sourced_ivar(name, type)
+      rebuild(ivars: @ivars.merge(name.to_sym => type).freeze,
+              declaration_sourced: add_declaration_sourced(:ivar, name))
+    end
+
+    # ADR-58 WD1 — a local assignment `r = @right` whose RHS is a pure read
+    # of a declaration-sourced ivar inherits the mark, so the survey's exact
+    # rotation/traversal shape (`r = @right; r.key`) does not fire. Binds the
+    # type and stamps the local's mark in one transition (the plain
+    # `with_local` would have dropped it).
+    def with_declaration_sourced_local(name, type)
+      written = with_local(name, type)
+      written.with_local_declaration_mark(name)
+    end
+
+    # ADR-58 WD1 — re-stamp the local mark on a scope produced by
+    # `with_local` (which always drops it). Public so the sibling
+    # `with_declaration_sourced_local` can call it across the new
+    # post-write receiver without reaching into a private method.
+    def with_local_declaration_mark(name)
+      rebuild(declaration_sourced: add_declaration_sourced(:local, name))
+    end
+
+    # ADR-58 WD1 — true when `(kind, name)`'s binding optionality is purely
+    # declaration-sourced (no flow-live write/narrowing has touched it).
+    def declaration_sourced?(kind, name)
+      @declaration_sourced.include?([kind.to_sym, name.to_sym])
     end
 
     def with_cvar(name, type)
@@ -214,6 +272,23 @@ module Rigor
       rebuild(globals: @globals.merge(name.to_sym => type).freeze)
     end
 
+    # Regex match-data globals (`$~`, `$&`, `$1..$9`, the pre/post-match
+    # and last-paren back-references). Narrowed on a successful-`=~` /
+    # `case`-`when` match edge (see `Narrowing#regex_match_predicate_scopes`);
+    # any subsequent method call could run another match and rebind every
+    # one of them, so `eval_call` forgets the narrowed facts here. Always
+    # safe — only drops facts, so a subsequent read falls back to the
+    # default `String | nil`. Program-level `$GLOBAL = ...` seeds use other
+    # names and are untouched.
+    MATCH_DATA_GLOBALS = %i[$~ $& $` $' $+ $1 $2 $3 $4 $5 $6 $7 $8 $9].freeze
+    private_constant :MATCH_DATA_GLOBALS
+
+    def forget_match_globals
+      return self unless @globals.keys.any? { |k| MATCH_DATA_GLOBALS.include?(k) }
+
+      rebuild(globals: @globals.except(*MATCH_DATA_GLOBALS).freeze)
+    end
+
     # Slice 7 phase 2 — class-level ivar accumulator. Keyed by
     # the qualified class name (e.g. `"Rigor::Scope"`); the
     # value is a `Hash[Symbol, Type::t]` of every ivar that
@@ -263,8 +338,9 @@ module Rigor
     # scope (no enclosing `class` / `module` body). True at the top
     # of a file AND inside a top-level `def` body (since toplevel
     # defs leave `self_type` nil per the existing scope-construction
-    # contract, mirroring how ADR-24's `adoptable_self_call_result?`
-    # also keys on `self_type.nil?` for the same context). Used by
+    # contract — the same nil-`self_type` signal ADR-24's self-call
+    # return adoption historically keyed on before ADR-57 opened the
+    # gate unconditionally). Used by
     # `CheckRules#unresolved_toplevel_diagnostic` to gate the
     # `call.unresolved-toplevel` rule so it fires only outside
     # class / module bodies, where Rails-DSL metaprogramming
@@ -289,6 +365,22 @@ module Rigor
       node
     end
 
+    # Module-singleton call resolution (ADR-57 follow-up) — companion of
+    # {#user_def_for} for SINGLETON-side defs (`def self.x`, `def Foo.x`,
+    # `class << self` bodies, and `module_function` defs). Returns the
+    # `Prism::DefNode` for `class_name.method_name` invoked on the
+    # module/class constant itself, or nil. The `discovered_def_nodes`
+    # table is deliberately instance-side only (its ancestor walk binds
+    # `self` as `Nominal`), so singleton bodies live in a parallel table
+    # the `ScopeIndexer` populates alongside it. Records the same
+    # cross-file dependency edge as the instance path (ADR-46).
+    def singleton_def_for(class_name, method_name)
+      table = @discovery.discovered_singleton_def_nodes[class_name.to_s]
+      node = table && table[method_name.to_sym]
+      record_cross_file_method(class_name, method_name, node) if Analysis::DependencyRecorder.active?
+      node
+    end
+
     # ADR-46 slice 1 — note the cross-file dependency this resolution
     # creates: the file defining `class_name#method_name` (the consumer's
     # analysis reads its body via `infer_user_method_return`), or, when
@@ -564,7 +656,8 @@ module Rigor
         @cvars == other.cvars &&
         @globals == other.globals &&
         @indexed_narrowings == other.indexed_narrowings &&
-        @method_chain_narrowings == other.method_chain_narrowings
+        @method_chain_narrowings == other.method_chain_narrowings &&
+        @declaration_sourced == other.declaration_sourced
     end
     alias eql? ==
 
@@ -580,6 +673,7 @@ module Rigor
       discovery: @discovery,
       indexed_narrowings: @indexed_narrowings,
       method_chain_narrowings: @method_chain_narrowings,
+      declaration_sourced: @declaration_sourced,
       source_path: @source_path
     )
       self.class.new(
@@ -589,6 +683,7 @@ module Rigor
         discovery: discovery,
         indexed_narrowings: indexed_narrowings,
         method_chain_narrowings: method_chain_narrowings,
+        declaration_sourced: declaration_sourced,
         source_path: source_path
       )
     end
@@ -621,10 +716,22 @@ module Rigor
         discovery: @discovery,
         indexed_narrowings: join_bindings(@indexed_narrowings, other.indexed_narrowings),
         method_chain_narrowings: join_bindings(@method_chain_narrowings, other.method_chain_narrowings),
+        # ADR-58 WD1 — a ref is declaration-sourced after a join only when
+        # BOTH branches agree it is. If either path made the binding
+        # flow-live (a method-local nil write / failed-guard narrowing), the
+        # merge is flow-live and `possible-nil-receiver` fires as before.
+        declaration_sourced: join_declaration_sourced(other),
         source_path: source_path
       )
     end
 
+    def join_declaration_sourced(other)
+      return @declaration_sourced if @declaration_sourced.equal?(other.declaration_sourced)
+      return EMPTY_DECLARATION_SOURCED if @declaration_sourced.empty? || other.declaration_sourced.empty?
+
+      (@declaration_sourced & other.declaration_sourced).freeze
+    end
+
     def indexed_key(receiver_kind, receiver_name, key)
       IndexedKey.new(
         receiver_kind: receiver_kind.to_sym,
@@ -652,6 +759,25 @@ module Rigor
       filtered.size == @indexed_narrowings.size ? @indexed_narrowings : filtered.freeze
     end
 
+    # ADR-58 WD1 — set/clear the declaration-sourced provenance mark.
+    def add_declaration_sourced(kind, name)
+      ref = [kind.to_sym, name.to_sym]
+      return @declaration_sourced if @declaration_sourced.include?(ref)
+
+      (@declaration_sourced.dup << ref).freeze
+    end
+
+    def drop_declaration_sourced_for(kind, name)
+      return @declaration_sourced if @declaration_sourced.empty?
+
+      ref = [kind.to_sym, name.to_sym]
+      return @declaration_sourced unless @declaration_sourced.include?(ref)
+
+      dropped = @declaration_sourced.dup
+      dropped.delete(ref)
+      dropped.freeze
+    end
+
     def drop_chain_narrowings_for(receiver_kind, receiver_name)
       return @method_chain_narrowings if @method_chain_narrowings.empty?
 

data/lib/rigor/sig_gen/generator.rb

@@ -118,7 +118,15 @@ module Rigor
         @class_shells = Set.new
         defs = collect_method_definitions(parse_result.value)
         candidates_from_defs = defs.filter_map do |def_node, class_name, kind|
+          # An analyzer bug typing one def's body must cost only that
+          # def's candidate, never the whole `rigor sig-gen` run. The
+          # `check` path recovers each *file* this way
+          # (worker_session.rb); sig-gen recovers per-def so the rest of
+          # the file's candidates still emit.
+
           classify_def(path, def_node, class_name, kind, scope_index)
+        rescue StandardError
+          nil
         end
         obs_ivar_map = build_observed_ivar_map(parse_result.value)
         candidates_from_defs + collect_attr_candidates(parse_result.value, path, scope_index, obs_ivar_map)

data/lib/rigor/triage/catalogue.rb

@@ -304,26 +304,11 @@ module Rigor
         m && [m[1], m[2]]
       end
 
-      # Normalises a message receiver token to a class name.
-      # Integer / string / symbol literals fold to their class;
-      # `Foo[...]` keeps the `Array[...]` form (H4 needs it);
-      # `singleton(Foo)` and bare `Foo` fold to `Foo`.
+      # Normalises a message receiver token to a class name. The fold
+      # logic is shared with the selector axis — see
+      # {Triage.normalize_receiver}.
       def receiver_class(token)
-        t = token.strip
-        return "Integer" if t.match?(/\A-?\d+\z/)
-        return "Float"   if t.match?(/\A-?\d+\.\d+\z/)
-        return "String"  if t.start_with?('"', "'")
-        return "Symbol"  if t.start_with?(":")
-
-        singleton = t[/\Asingleton\(([\w:]+)\)\z/, 1]
-        return singleton if singleton
-        return t if t.start_with?("Array[")
-
-        nominal = t[/\A([\w:]+)\[/, 1]
-        return nominal if nominal
-        return t if t.match?(/\A[\w:]+\z/)
-
-        nil
+        Triage.normalize_receiver(token)
       end
 
       def activesupport?(receiver, method)

data/lib/rigor/triage.rb

@@ -18,7 +18,15 @@ module Rigor
     Summary = Data.define(:total, :error, :warning, :info)
     RuleCount = Data.define(:rule, :count)
     Hotspot = Data.define(:file, :count, :by_rule)
-    Report = Data.define(:summary, :distribution, :hotspots, :hints)
+    # A (receiver-class, method) dispatch target the diagnostics
+    # cluster on, built from the structured `Diagnostic#receiver_type`
+    # / `#method_name` fields — never from message-string parsing.
+    # `receiver` is nil for method-only diagnostics (a toplevel call,
+    # a `def`-side return / override finding that has no call
+    # receiver); `files` is the distinct-file count (a systemic vs.
+    # localised signal); `rules` is the per-rule breakdown.
+    Selector = Data.define(:receiver, :method_name, :count, :files, :rules)
+    Report = Data.define(:summary, :distribution, :selectors, :hotspots, :hints)
 
     module_function
 
@@ -30,6 +38,7 @@ module Rigor
       Report.new(
         summary: build_summary(diagnostics),
         distribution: build_distribution(diagnostics),
+        selectors: build_selectors(diagnostics),
         hotspots: build_hotspots(diagnostics, top),
         hints: hints ? Catalogue.recognise(diagnostics) : []
       )
@@ -57,6 +66,61 @@ module Rigor
                  .sort_by { |row| [-row.count, row.rule] }
     end
 
+    # The class/method aggregation axis (ADR-23 follow-up). Groups
+    # every diagnostic that carries a `method_name` by its
+    # `(receiver_type, method_name)` pair so a consumer can answer
+    # "which method / class concentrates the diagnostics?" with a
+    # `jq` query over the JSON instead of parsing message text.
+    # Method-only diagnostics (nil `receiver_type`) keep a null
+    # `receiver` and still group by method. The full list is
+    # returned uncapped — the JSON is the agent-facing surface; the
+    # text renderer caps its own rows.
+    def build_selectors(diagnostics)
+      diagnostics.select(&:method_name)
+                 .group_by { |d| [normalize_receiver(d.receiver_type) || d.receiver_type, d.method_name.to_s] }
+                 .map { |(receiver, method), group| selector_for(receiver, method, group) }
+                 .sort_by { |s| [-s.count, s.receiver.to_s, s.method_name] }
+    end
+
+    # Folds a receiver token — a `Diagnostic#receiver_type` display
+    # string or a message-parsed token — to the class the diagnostics
+    # should bucket under, so the selector axis does not fragment one
+    # method across every distinct literal receiver. String / integer
+    # / float / symbol literals collapse to their class; `singleton(C)`
+    # and a bare `C` fold to `C`; a generic `C[...]` keeps the
+    # `Array[String]` element form (the AR-relation heuristic keys on
+    # it). Returns nil for a token it cannot reduce to a class (a
+    # union display, an inferred shape) — the caller keeps the raw
+    # string then, never losing the row. Shared with {Catalogue}.
+    def normalize_receiver(token)
+      return nil if token.nil?
+
+      t = token.to_s.strip
+      return "Integer" if t.match?(/\A-?\d+\z/)
+      return "Float"   if t.match?(/\A-?\d+\.\d+\z/)
+      return "String"  if t.start_with?('"', "'")
+      return "Symbol"  if t.start_with?(":")
+
+      singleton = t[/\Asingleton\(([\w:]+)\)\z/, 1]
+      return singleton if singleton
+      return t if t.start_with?("Array[")
+
+      nominal = t[/\A([\w:]+)\[/, 1]
+      return nominal if nominal
+      return t if t.match?(/\A[\w:]+\z/)
+
+      nil
+    end
+
+    def selector_for(receiver, method, group)
+      rules = group.group_by { |d| rule_key(d) }
+                   .transform_values(&:size)
+                   .sort_by { |rule, count| [-count, rule] }
+                   .to_h
+      Selector.new(receiver: receiver, method_name: method, count: group.size,
+                   files: group.map(&:path).uniq.size, rules: rules)
+    end
+
     def build_hotspots(diagnostics, top)
       diagnostics.group_by(&:path)
                  .map { |path, group| hotspot_for(path, group) }
@@ -79,6 +143,10 @@ module Rigor
           "warning" => report.summary.warning, "info" => report.summary.info
         },
         "distribution" => report.distribution.map { |r| { "rule" => r.rule, "count" => r.count } },
+        "selectors" => report.selectors.map do |s|
+          { "receiver" => s.receiver, "method" => s.method_name, "count" => s.count,
+            "files" => s.files, "rules" => s.rules }
+        end,
         "hotspots" => report.hotspots.map do |h|
           { "file" => h.file, "count" => h.count, "by_rule" => h.by_rule }
         end,