rigortype 0.1.18 → 0.2.0

data/lib/rigor/plugin/macro.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require_relative "macro/block_as_method"
-require_relative "macro/external_file"
 require_relative "macro/heredoc_template"
 require_relative "macro/nested_class_template"
 require_relative "macro/trait_registry"
@@ -11,15 +10,14 @@ module Rigor
     # Substrate declarations for the macro / DSL expansion tiers
     # introduced by ADR-16. Plugin authors declare entries under
     # `Plugin::Manifest` slots (`block_as_methods:`,
-    # `trait_registries:`, `heredoc_macros:`,
-    # `external_file_inclusions:`) and the substrate consumes them
+    # `trait_registries:`, `heredoc_templates:`,
+    # `nested_class_templates:`) and the substrate consumes them
     # to recognise the call shapes a library exposes to its users.
     #
-    # Slice 1a (this file's first delivery) ships the Tier A value
-    # class only. The other tiers' value classes + their manifest
-    # slots arrive in subsequent slices per ADR-16 § Implementation
-    # slicing. The namespace is reserved here so subsequent slices
-    # add files alongside `block_as_method.rb` without churn.
+    # Tier A (`BlockAsMethod`), Tier B (`TraitRegistry`), Tier C
+    # (`HeredocTemplate`), and ADR-36 nested-class emission
+    # (`NestedClassTemplate`) value classes are all shipped here.
+    # Engine wiring lives in `lib/rigor/inference/`.
     #
     # Per ADR-16 § WD13, substrate-produced output ships at a
     # **floor** in v0.1.x ("substrate-affected code parses cleanly

data/lib/rigor/plugin/manifest.rb

@@ -32,9 +32,9 @@ module Rigor
       # its `#prepare(services)` hook. `consumes:` lists the
       # `(plugin_id, name)` pairs this plugin reads from
       # `services.fact_store`. The loader uses both for
-      # topological sort + missing-producer detection (slice 5);
-      # slice 4 carries the declarations on the manifest but the
-      # loader does not yet enforce them.
+      # topological sort + missing-producer detection; slice 4
+      # added the declarations; slice 5 (`Loader#topo_sort_plugins`)
+      # enforces ordering and missing-producer validation.
       class Consumption < Data.define(:plugin_id, :name, :optional)
         def initialize(plugin_id:, name:, optional: false)
           super(plugin_id: plugin_id.to_s, name: name.to_sym, optional: optional ? true : false)
@@ -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,
@@ -280,10 +277,18 @@ module Rigor
         end
       end
 
-      def validate_produces!(produces)
-        return if produces.is_a?(Array) && produces.all? { |p| p.is_a?(Symbol) || p.is_a?(String) }
+      # Shared shape check for the Array-of-X manifest fields. Every entry
+      # must satisfy the block; otherwise raise the uniform "must be an
+      # Array of <label>" message. Centralises the message format the
+      # field validators below share so it cannot drift between them.
+      def validate_array_of!(field, value, label, &)
+        return if value.is_a?(Array) && value.all?(&)
 
-        raise ArgumentError, "plugin manifest produces must be an Array of Symbol/String, got #{produces.inspect}"
+        raise ArgumentError, "plugin manifest #{field} must be an Array of #{label}, got #{value.inspect}"
+      end
+
+      def validate_produces!(produces)
+        validate_array_of!("produces", produces, "Symbol/String") { |p| p.is_a?(Symbol) || p.is_a?(String) }
       end
 
       # ADR-10 5a — `owns_receivers:` declares the class names
@@ -294,11 +299,7 @@ module Rigor
       # so plugin contributions stay authoritative for those
       # types.
       def validate_owns_receivers!(owns_receivers)
-        return if owns_receivers.is_a?(Array) && owns_receivers.all? { |c| c.is_a?(String) && !c.empty? }
-
-        raise ArgumentError,
-              "plugin manifest owns_receivers must be an Array of non-empty String, " \
-              "got #{owns_receivers.inspect}"
+        validate_array_of!("owns_receivers", owns_receivers, "non-empty String") { |c| c.is_a?(String) && !c.empty? }
       end
 
       # ADR-26 — `open_receivers:` declares the class names this
@@ -312,11 +313,7 @@ module Rigor
       # `owns_receivers:` (which routes dispatch); this one only
       # suppresses the diagnostic.
       def validate_open_receivers!(open_receivers)
-        return if open_receivers.is_a?(Array) && open_receivers.all? { |c| c.is_a?(String) && !c.empty? }
-
-        raise ArgumentError,
-              "plugin manifest open_receivers must be an Array of non-empty String, " \
-              "got #{open_receivers.inspect}"
+        validate_array_of!("open_receivers", open_receivers, "non-empty String") { |c| c.is_a?(String) && !c.empty? }
       end
 
       # ADR-13 slice 2 — `type_node_resolvers:` declares the
@@ -328,11 +325,9 @@ module Rigor
       # integration that actually drives the chain lands in
       # slice 3.
       def validate_type_node_resolvers!(resolvers)
-        return if resolvers.is_a?(Array) && resolvers.all?(TypeNodeResolver)
-
-        raise ArgumentError,
-              "plugin manifest type_node_resolvers must be an Array of " \
-              "Rigor::Plugin::TypeNodeResolver instances, got #{resolvers.inspect}"
+        validate_array_of!("type_node_resolvers", resolvers, "Rigor::Plugin::TypeNodeResolver instances") do |r|
+          r.is_a?(TypeNodeResolver)
+        end
       end
 
       # ADR-16 slice 1a — `block_as_methods:` declares the Tier A
@@ -341,11 +336,9 @@ module Rigor
       # actually narrows `Scope#self_type` for matching blocks
       # arrives in a subsequent slice.
       def validate_block_as_methods!(entries)
-        return if entries.is_a?(Array) && entries.all?(Macro::BlockAsMethod)
-
-        raise ArgumentError,
-              "plugin manifest block_as_methods must be an Array of " \
-              "Rigor::Plugin::Macro::BlockAsMethod instances, got #{entries.inspect}"
+        validate_array_of!("block_as_methods", entries, "Rigor::Plugin::Macro::BlockAsMethod instances") do |e|
+          e.is_a?(Macro::BlockAsMethod)
+        end
       end
 
       # ADR-16 slice 2a — `heredoc_templates:` declares the Tier C
@@ -354,11 +347,9 @@ module Rigor
       # manifest; the pre-pass + `SyntheticMethodIndex` that actually
       # emit synthetic methods arrive in slice 2b.
       def validate_heredoc_templates!(entries)
-        return if entries.is_a?(Array) && entries.all?(Macro::HeredocTemplate)
-
-        raise ArgumentError,
-              "plugin manifest heredoc_templates must be an Array of " \
-              "Rigor::Plugin::Macro::HeredocTemplate instances, got #{entries.inspect}"
+        validate_array_of!("heredoc_templates", entries, "Rigor::Plugin::Macro::HeredocTemplate instances") do |e|
+          e.is_a?(Macro::HeredocTemplate)
+        end
       end
 
       # ADR-36 — `nested_class_templates:` declares the
@@ -368,11 +359,10 @@ module Rigor
       # subclasses + their `#inner` reader through the existing
       # `SyntheticMethodIndex` primitive.
       def validate_nested_class_templates!(entries)
-        return if entries.is_a?(Array) && entries.all?(Macro::NestedClassTemplate)
-
-        raise ArgumentError,
-              "plugin manifest nested_class_templates must be an Array of " \
-              "Rigor::Plugin::Macro::NestedClassTemplate instances, got #{entries.inspect}"
+        validate_array_of!("nested_class_templates", entries,
+                           "Rigor::Plugin::Macro::NestedClassTemplate instances") do |e|
+          e.is_a?(Macro::NestedClassTemplate)
+        end
       end
 
       # ADR-16 slice 3a — `trait_registries:` declares the Tier B
@@ -382,28 +372,9 @@ module Rigor
       # `SyntheticMethodIndex` (slice 2b primitive) arrives in
       # slice 3b.
       def validate_trait_registries!(entries)
-        return if entries.is_a?(Array) && entries.all?(Macro::TraitRegistry)
-
-        raise ArgumentError,
-              "plugin manifest trait_registries must be an Array of " \
-              "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}"
+        validate_array_of!("trait_registries", entries, "Rigor::Plugin::Macro::TraitRegistry instances") do |e|
+          e.is_a?(Macro::TraitRegistry)
+        end
       end
 
       # ADR-20 slice 6 — `hkt_registrations:` declares the
@@ -418,11 +389,9 @@ module Rigor
       # user `.rbs` overlays merge on top of plugin entries
       # last-write-wins.
       def validate_hkt_registrations!(entries)
-        return if entries.is_a?(Array) && entries.all?(Inference::HktRegistry::Registration)
-
-        raise ArgumentError,
-              "plugin manifest hkt_registrations must be an Array of " \
-              "Rigor::Inference::HktRegistry::Registration instances, got #{entries.inspect}"
+        validate_array_of!("hkt_registrations", entries, "Rigor::Inference::HktRegistry::Registration instances") do |e|
+          e.is_a?(Inference::HktRegistry::Registration)
+        end
       end
 
       # ADR-20 slice 6 — `hkt_definitions:` declares the
@@ -435,11 +404,9 @@ module Rigor
       # via {Rigor::Inference::HktBody}'s node-constructor API
       # without parsing a string.
       def validate_hkt_definitions!(entries)
-        return if entries.is_a?(Array) && entries.all?(Inference::HktRegistry::Definition)
-
-        raise ArgumentError,
-              "plugin manifest hkt_definitions must be an Array of " \
-              "Rigor::Inference::HktRegistry::Definition instances, got #{entries.inspect}"
+        validate_array_of!("hkt_definitions", entries, "Rigor::Inference::HktRegistry::Definition instances") do |e|
+          e.is_a?(Inference::HktRegistry::Definition)
+        end
       end
 
       # ADR-25 — `signature_paths:` declares the RBS signature
@@ -449,11 +416,7 @@ module Rigor
       # loader validates each exists and `Environment.for_project`
       # merges the resolved set into the RBS environment.
       def validate_signature_paths!(paths)
-        return if paths.is_a?(Array) && paths.all? { |p| p.is_a?(String) && !p.empty? }
-
-        raise ArgumentError,
-              "plugin manifest signature_paths must be an Array of non-empty String, " \
-              "got #{paths.inspect}"
+        validate_array_of!("signature_paths", paths, "non-empty String") { |p| p.is_a?(String) && !p.empty? }
       end
 
       # ADR-28 — `protocol_contracts:` declares the path-scoped
@@ -469,11 +432,9 @@ module Rigor
       # MAY override `Plugin::Base#protocol_contracts` to fold in
       # per-project config (e.g. a custom convention path).
       def validate_protocol_contracts!(entries)
-        return if entries.is_a?(Array) && entries.all?(ProtocolContract)
-
-        raise ArgumentError,
-              "plugin manifest protocol_contracts must be an Array of " \
-              "Rigor::Plugin::ProtocolContract instances, got #{entries.inspect}"
+        validate_array_of!("protocol_contracts", entries, "Rigor::Plugin::ProtocolContract instances") do |e|
+          e.is_a?(ProtocolContract)
+        end
       end
 
       # ADR-38 — `additional_initializers:` declares the
@@ -485,11 +446,9 @@ module Rigor
       # loaded plugins; `Inference::ScopeIndexer` consults the set at
       # its single gate.
       def validate_additional_initializers!(entries)
-        return if entries.is_a?(Array) && entries.all?(AdditionalInitializer)
-
-        raise ArgumentError,
-              "plugin manifest additional_initializers must be an Array of " \
-              "Rigor::Plugin::AdditionalInitializer instances, got #{entries.inspect}"
+        validate_array_of!("additional_initializers", entries, "Rigor::Plugin::AdditionalInitializer instances") do |e|
+          e.is_a?(AdditionalInitializer)
+        end
       end
 
       # ADR-32 WD4 — `source_rbs_synthesizer:` declares a callable

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)
@@ -316,13 +317,12 @@ module Rigor
         !load_errors.empty?
       end
 
-      # ADR-13 slice 2 — flat ordered list of every loaded
-      # plugin's manifest-declared {TypeNodeResolver} instances,
-      # in plugin registration order. Slice 3 wires this into
-      # the parser's resolver chain; until then the method is a
-      # read-side aggregator only. The first non-nil
-      # `#resolve(node, scope)` return wins per ADR-13 WD3 / WD5
-      # — registration order is the user's lever.
+      # ADR-13 — flat ordered list of every loaded plugin's
+      # manifest-declared {TypeNodeResolver} instances, in plugin
+      # registration order. `Environment#build_name_scope` builds a
+      # `TypeNode::ResolverChain` from this list (environment.rb).
+      # The first non-nil `#resolve(node, scope)` return wins per
+      # ADR-13 WD3 / WD5 — registration order is the user's lever.
       def type_node_resolvers
         plugins.flat_map { |plugin| plugin.manifest.type_node_resolvers }
       end

data/lib/rigor/plugin/type_node_resolver.rb

@@ -24,14 +24,12 @@ module Rigor
     #     )
     #   end
     #
-    # Slice 2 of the ADR-13 envelope (this file) ships the base
-    # class + manifest hook + registry aggregation. The parser-
-    # side wiring that actually consults the resolver chain
-    # arrives in slice 3, when {Rigor::TypeNode::NameScope} and
-    # the dispatcher between {Rigor::Builtins::ImportedRefinements::Parser}
-    # and the chain land. Until then resolvers can be unit-tested
-    # in isolation but never run for a real `%a{rigor:v1:...}`
-    # payload.
+    # ADR-13 — base class, manifest hook, and registry aggregation
+    # for plugin-contributed type-node resolvers. Resolvers declared
+    # via `manifest(type_node_resolvers:)` run for every real
+    # `%a{rigor:v1:...}` payload through `TypeNode::ResolverChain`
+    # (built by `Environment#build_name_scope` from
+    # `Plugin::Registry#type_node_resolvers`).
     #
     # Resolvers SHOULD be stateless and re-entrant; the registry
     # builds the chain once per `Analysis::Runner.run` and may

data/lib/rigor/protection/mutation_scanner.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../analysis/runner"
+require_relative "mutator"
+
+module Rigor
+  module Protection
+    # ADR-63 Tier 2 — the mutation *effectiveness* tier (the truth tier behind
+    # Tier 1's static {Inference::ProtectionScanner} proxy). For one file it
+    # answers the question Tier 1 only bounds: when a type-visible bug is
+    # introduced at a dispatch site, does Rigor actually catch it?
+    #
+    # Mechanism (the ADR-62 warm loop, narrowed to per-file measurement):
+    # generate the type-visible mutations ({Mutator}), keep only those whose
+    # receiver Rigor holds a concrete type for (the type-aware filter — the
+    # FP-safe meaning-maker; an unresolved receiver is kept), then for each:
+    # re-analyse the mutated SOURCE against a clean baseline and read whether a
+    # NEW diagnostic appears. A *killed* mutation is a caught breakage; a
+    # *survived* one is a breakage Rigor missed — an "add a type here" site.
+    #
+    # The expensive builds (RBS environment + the whole-project pre-pass scan)
+    # are paid ONCE by the caller and threaded in via `environment:` /
+    # `project_scan:`; each mutant reuses them through
+    # `Runner.new(prebuilt:)#run_source` (in-memory overlay, no disk write).
+    # Passing `prebuilt:` disables the run-result cache (whose key digests the
+    # *disk* file), so a mutant is never served a stale clean hit.
+    class MutationScanner
+      # A surviving mutation site — a breakage Rigor did not catch.
+      SurvivingSite = Data.define(:line, :receiver, :method_name, :operator)
+
+      FileResult = Data.define(:path, :killed, :survived, :sites) do
+        # Mutations actually analysed (parse-invalid mutants are not counted).
+        def total = killed + survived
+
+        # Effectiveness ratio; a file with no type-relevant mutation is
+        # vacuously fully effective (no breakage was available to miss).
+        def ratio = total.zero? ? 1.0 : killed.to_f / total
+      end
+
+      # @param configuration [Rigor::Configuration]
+      # @param environment [Rigor::Environment] pre-built once by the caller
+      # @param project_scan [Rigor::Analysis::ProjectScan] pre-built once
+      # @param limit [Integer, nil] optional per-file mutation cap (sampled with
+      #   `seed`); nil analyses every type-relevant mutation (deterministic).
+      # @param seed [Integer] RNG seed for the optional sample.
+      def initialize(configuration:, environment:, project_scan:, limit: nil, seed: 1)
+        @configuration = configuration
+        @environment = environment
+        @project_scan = project_scan
+        @limit = limit
+        @seed = seed
+      end
+
+      # @param path [String] the file to measure (used as the in-memory bind path)
+      # @param source [String, nil] the file's source; read from disk when nil
+      # @return [FileResult]
+      def scan_file(path, source: nil)
+        source ||= File.read(path, encoding: Encoding::UTF_8)
+        mutator = Mutator.new(source)
+        kept, = mutator.filter_by_type(mutator.mutations, environment: @environment, path: path)
+        kept = sample(kept)
+        return FileResult.new(path: path, killed: 0, survived: 0, sites: []) if kept.empty?
+
+        baseline = signatures(analyse(source, path))
+        measure(source, path, kept, baseline)
+      end
+
+      private
+
+      def measure(source, path, mutations, baseline)
+        killed = 0
+        sites = []
+        mutations.each do |mut|
+          case classify(source, path, mut, baseline)
+          when :killed then killed += 1
+          when :survived then sites << surviving_site(mut)
+            # :invalid — a parse-broken mutant; not a measurement, skip it.
+          end
+        end
+        FileResult.new(path: path, killed: killed, survived: sites.size, sites: sites)
+      end
+
+      def classify(source, path, mut, baseline)
+        mutant_source = mut.apply(source)
+        return :invalid unless Prism.parse(mutant_source).success?
+
+        new_diagnostics = analyse(mutant_source, path).reject { |d| baseline.include?(sig(d)) }
+        new_diagnostics.empty? ? :survived : :killed
+      rescue StandardError
+        # A harness-level failure on one mutant must not abort the file.
+        :invalid
+      end
+
+      # cache_store: nil + prebuilt: scan ⇒ the run cache is bypassed and the
+      # mutant is always re-analysed against the in-memory bytes.
+      def analyse(source, path)
+        Rigor::Analysis::Runner.new(
+          configuration: @configuration, environment: @environment, prebuilt: @project_scan,
+          cache_store: nil, collect_stats: false
+        ).run_source(source: source, path: path).diagnostics
+      end
+
+      def sample(mutations)
+        return mutations unless @limit
+
+        mutations.sample(@limit, random: Random.new(@seed))
+      end
+
+      def signatures(diagnostics) = diagnostics.to_set { |d| sig(d) }
+      def sig(diagnostic) = [diagnostic.rule, diagnostic.path, diagnostic.line, diagnostic.column, diagnostic.message]
+
+      def surviving_site(mut)
+        SurvivingSite.new(line: mut.line, receiver: mut.anchor_type,
+                          method_name: mut.method_name, operator: mut.operator.to_s)
+      end
+    end
+  end
+end