rigortype 0.1.16 → 0.1.18

data/lib/rigor/plugin/base.rb

@@ -190,44 +190,218 @@ module Rigor
           defined?(@node_file_context_block) ? @node_file_context_block : nil
         end
 
-        # ADR-37 slice 2 — declares a per-call-site return-type
-        # contribution, receiver-gated. The narrow successor to the
-        # `return_type` slot of `flow_contribution_for`:
+        # ADR-37 slice 2 / ADR-52 WD2 — declares a per-call-site
+        # return-type contribution, gated by receiver class, method name,
+        # or both. The narrow successor to the `return_type` slot of the
+        # deleted `flow_contribution_for` hook (ADR-52 WD3):
         #
+        #   # receiver-gated only:
         #   dynamic_return receivers: ["ActiveRecord::Base"] do |call_node, scope|
         #     # self = plugin instance; return a Rigor::Type or nil
         #   end
         #
+        #   # receiver + method gated (preferred for focused rules):
+        #   dynamic_return receivers: ["Result"], methods: [:unwrap, :unwrap!] do |call_node, scope|
+        #     # fires only for Result#unwrap / Result#unwrap!
+        #   end
+        #
+        #   # method-gated only (ADR-52 WD2 — receiver-independent rules,
+        #   # e.g. a unit-dimension DSL whose receiver carrier is a
+        #   # refinement, not a nominal class):
+        #   dynamic_return methods: [:kilometers, :per_hour, :in_meters] do |call_node, scope|
+        #     # fires for any receiver when the method name matches;
+        #     # the block reads the receiver's shape itself
+        #   end
+        #
         # `receivers:` is a non-empty Array of class names; the engine
         # calls the block only when the call's receiver type's class
         # equals or inherits from one of them (via
-        # `Environment#class_ordering`). Method-name and type-shape
-        # refinement stays in the block, which returns a `Rigor::Type`
-        # (or `nil` to decline). The block runs through `instance_exec`,
-        # so `config` / `services` are in scope. This is the
-        # {.producer}-style class DSL (it carries logic needing the
-        # instance, not pure data).
-        def dynamic_return(receivers:, &block)
+        # `Environment#class_ordering`). It MAY be omitted — then the rule
+        # is receiver-independent and fires on `methods:` alone.
+        #
+        # `methods:` is an Array of Symbol method names. When provided, the
+        # block is skipped unless `call_node.name` is in the list —
+        # declarative and cheaper than an in-block guard (the engine
+        # compiles it into the registry's contribution table, ADR-52 WD1).
+        # It is REQUIRED when `receivers:` is omitted: a rule gated on
+        # neither would fire on every dispatch, which is exactly the
+        # ungated cost the `flow_contribution_for` escape valve carries —
+        # `dynamic_return` declines to reintroduce it.
+        #
+        # Method-name and type-shape refinement can still be done inside
+        # the block. The block runs through `instance_exec`, so `config`
+        # / `services` are in scope.
+        # ADR-52 slice 3 — `receivers:` may also be a **callable**
+        # (a `-> { ... }` resolved once per run, lazily, the first time
+        # the rule is consulted — always after `#prepare`) for a receiver
+        # set the plugin only knows at run time:
+        #
+        #   dynamic_return receivers: -> { attachment_index.model_names } do |call_node, scope|
+        #     # fires when the receiver class is one a `prepare`-time scan
+        #     # found; the block does the precise per-call lookup
+        #   end
+        #
+        # The callable runs through `instance_exec`, so it reads the
+        # plugin's own `#prepare`-built indexes. It MUST be idempotent and
+        # post-`#prepare`-safe — reference a lazily-built / memoised index
+        # (as activestorage's `attachment_index` and activerecord's
+        # `model_index` are), never a value captured at class-definition
+        # time. The resolved set is a safe over-approximation of the
+        # block's own filter (it admits subclasses too), so the block
+        # stays the precise gate and diagnostics are unchanged.
+        #
+        # ADR-52 slice 4 — `methods:` may ALSO be a callable, for a
+        # method-name set the plugin only knows at run time (a Sorbet
+        # catalog's keys, a config-derived DSL method name):
+        #
+        #   dynamic_return methods: -> { catalog.method_names } do |call_node, scope|
+        #     ...
+        #   end
+        #
+        # Same contract as a callable `receivers:` — `instance_exec`'d,
+        # resolved lazily after `#prepare`, memoised, idempotent. A
+        # callable method set cannot be compiled into the registry's
+        # name gate (it is unknown at registry-build time), so the
+        # plugin is consulted on every dispatch and the name filter runs
+        # in this instance path instead — the block still only fires for
+        # a listed name, so diagnostics are unchanged.
+        # ADR-52 slice 5a — `file_methods:` is the per-file
+        # specialisation of the run-time `methods:` callable, for a name
+        # set that varies per analysed file (rigor-rspec's `let` names —
+        # the names depend on each file's `describe`/`let` structure, so
+        # one run-wide set cannot exist). The callable receives the file
+        # path, runs through `instance_exec`, and is memoised per
+        # `(rule, path)`:
+        #
+        #   dynamic_return file_methods: ->(path) { let_names_for(path) } do |call_node, scope|
+        #     ...
+        #   end
+        #
+        # Same idempotence contract as the other callables, plus: it MUST
+        # tolerate any path the engine analyses (return `[]` / nil for a
+        # file it has no names for — never raise). Like a callable
+        # `methods:`, it cannot compile into the registry name gate, so
+        # the plugin is consulted on every dispatch and filtered here.
+        # `file_methods:` replaces `methods:` (declaring both is
+        # rejected — they are the same gate at two scopes); it MAY
+        # combine with `receivers:`.
+        def dynamic_return(receivers: nil, methods: nil, file_methods: nil, &block)
           raise ArgumentError, "Plugin::Base.dynamic_return requires a block body" if block.nil?
-          unless receivers.is_a?(Array) && !receivers.empty? && receivers.all? { |r| r.is_a?(String) && !r.empty? }
-            raise ArgumentError,
-                  "Plugin::Base.dynamic_return receivers: must be a non-empty Array of class-name Strings, " \
-                  "got #{receivers.inspect}"
-          end
+
+          validate_dynamic_return_gate!(receivers, methods, file_methods)
+          validate_dynamic_return_receivers!(receivers) unless receivers.nil?
+          validate_dynamic_return_methods!(methods)
+          validate_dynamic_return_file_methods!(file_methods, methods)
 
           @dynamic_returns ||= []
-          @dynamic_returns << { receivers: receivers.map { |r| r.dup.freeze }.freeze, block: block }.freeze
+          @dynamic_returns << {
+            receivers: normalize_dynamic_return_receivers(receivers),
+            methods: normalize_dynamic_return_methods(methods),
+            file_methods: file_methods,
+            block: block
+          }.freeze
           nil
         end
 
-        # Frozen snapshot of the declared dynamic-return rules.
+        # A class-name Array is frozen element-wise; a run-time callable
+        # (ADR-52 slice 3) is stored verbatim and resolved per instance.
+        def normalize_dynamic_return_receivers(receivers)
+          return nil if receivers.nil?
+          return receivers if receivers.respond_to?(:call)
+
+          receivers.map { |r| r.dup.freeze }.freeze
+        end
+        private :normalize_dynamic_return_receivers
+
+        # A method-name Array is symbol-normalised + frozen; a run-time
+        # callable (ADR-52 slice 4) is stored verbatim and resolved per
+        # instance.
+        def normalize_dynamic_return_methods(methods)
+          return nil if methods.nil?
+          return methods if methods.respond_to?(:call)
+
+          methods.map(&:to_sym).freeze
+        end
+        private :normalize_dynamic_return_methods
+
+        # Frozen snapshot of the declared dynamic-return rules. Memoised:
+        # `@dynamic_returns` is built once at class-definition time (via
+        # `dynamic_return`) and never mutated during analysis, and every
+        # element is already frozen, so a fresh `dup.freeze` per call was
+        # pure waste — the engine calls this for every plugin on every
+        # dispatch (`collect_plugin_contributions`), making it a top
+        # allocation site on plugin-heavy projects. The cached frozen
+        # array is immutable, so sharing one instance across callers is
+        # safe.
+        # rubocop:disable Naming/MemoizedInstanceVariableName -- the
+        # natural name `@dynamic_returns` is the canonical (mutable-at-
+        # definition) store this snapshots; the memo must be distinct.
         def dynamic_returns
-          (@dynamic_returns || []).dup.freeze
+          @dynamic_returns_snapshot ||= (@dynamic_returns || []).dup.freeze
         end
+        # rubocop:enable Naming/MemoizedInstanceVariableName
+
+        # ADR-52 WD2 — a rule must gate on something. `receivers:` alone,
+        # `methods:` alone, or both are valid; neither is not (it would
+        # fire on every dispatch).
+        def validate_dynamic_return_gate!(receivers, methods, file_methods)
+          return unless receivers.nil? && file_methods.nil?
+          return if (methods.is_a?(Array) && !methods.empty?) || methods.respond_to?(:call)
+
+          raise ArgumentError,
+                "Plugin::Base.dynamic_return requires receivers:, methods:, or file_methods: — a rule " \
+                "gated on none would fire on every dispatch (that is what flow_contribution_for is for)"
+        end
+
+        # ADR-52 slice 5a — `file_methods:` must be a callable, and is
+        # mutually exclusive with `methods:` (one name gate, two scopes —
+        # declaring both is a contradiction, not a composition).
+        def validate_dynamic_return_file_methods!(file_methods, methods)
+          return if file_methods.nil?
+
+          unless file_methods.respond_to?(:call)
+            raise ArgumentError,
+                  "Plugin::Base.dynamic_return file_methods: must be a callable receiving the file path, " \
+                  "got #{file_methods.inspect}"
+          end
+          return if methods.nil?
+
+          raise ArgumentError,
+                "Plugin::Base.dynamic_return file_methods: replaces methods: — declare one name gate, " \
+                "not both"
+        end
+
+        def validate_dynamic_return_receivers!(receivers)
+          # ADR-52 slice 3 — a run-time callable is resolved per instance
+          # after `#prepare`; its shape is checked at resolution time.
+          return if receivers.respond_to?(:call)
+          return if receivers.is_a?(Array) && !receivers.empty? && receivers.all? { |r| r.is_a?(String) && !r.empty? }
+
+          raise ArgumentError,
+                "Plugin::Base.dynamic_return receivers: must be a non-empty Array of class-name Strings " \
+                "or a callable, got #{receivers.inspect}"
+        end
+
+        def validate_dynamic_return_methods!(methods)
+          return if methods.nil?
+          # ADR-52 slice 4 — a run-time callable resolves to the name set
+          # per instance after `#prepare`; its shape is checked then.
+          return if methods.respond_to?(:call)
+          return if methods.is_a?(Array) && !methods.empty? &&
+                    methods.all? { |m| m.is_a?(Symbol) || (m.is_a?(String) && !m.empty?) }
+
+          raise ArgumentError,
+                "Plugin::Base.dynamic_return methods: must be a non-empty Array of Symbol/String, a callable, " \
+                "or nil, got #{methods.inspect}"
+        end
+
+        private :validate_dynamic_return_gate!, :validate_dynamic_return_receivers!,
+                :validate_dynamic_return_methods!, :validate_dynamic_return_file_methods!
 
         # ADR-37 slice 2 — declares a predicate/assertion narrowing
         # contribution, method-gated. The narrow successor to the
-        # `post_return_facts` slot of `flow_contribution_for`:
+        # `post_return_facts` slot of the deleted `flow_contribution_for`
+        # hook (ADR-52 WD3):
         #
         #   type_specifier methods: [:assert_kind_of] do |call_node, scope|
         #     # return an Array of post-return facts, or nil
@@ -250,10 +424,14 @@ module Rigor
           nil
         end
 
-        # Frozen snapshot of the declared type-specifier rules.
+        # Frozen snapshot of the declared type-specifier rules. Memoised
+        # for the same reason as {dynamic_returns} — consulted per plugin
+        # per dispatch, over an array fixed at class-definition time.
+        # rubocop:disable Naming/MemoizedInstanceVariableName -- see dynamic_returns
         def type_specifiers
-          (@type_specifiers || []).dup.freeze
+          @type_specifiers_snapshot ||= (@type_specifiers || []).dup.freeze
         end
+        # rubocop:enable Naming/MemoizedInstanceVariableName
       end
 
       attr_reader :services, :config
@@ -261,6 +439,12 @@ module Rigor
       def initialize(services:, config: {})
         @services = services
         @config = merge_config_defaults(config).freeze
+        # ADR-52 slice 3 — per-rule cache of resolved run-time
+        # `dynamic_return receivers:` callables. Created here (before any
+        # subclass `initialize` freezes the instance) so the lazy
+        # memo-on-first-dispatch is a Hash-content mutation, sound even on
+        # a self-freezing plugin.
+        @dynamic_return_runtime_cache = {}
       end
 
       # Override in subclasses to wire any state the plugin needs
@@ -271,22 +455,13 @@ module Rigor
         nil
       end
 
-      # ADR-2 § "Flow Contribution Bundle" / v0.1.1 Track 2
-      # slice 7 — per-call return-type contribution hook. When
-      # the inference engine dispatches a `Prism::CallNode` and
-      # neither the precision tiers nor RBS resolve a result,
-      # `MethodDispatcher` consults each loaded plugin via this
-      # hook ahead of `RbsDispatch`. Plugins that override the
-      # default return a {Rigor::FlowContribution} bundle whose
-      # `return_type` slot pins the call site's result type.
-      #
-      # Default returns nil — plugins that don't refine return
-      # types skip the override. Failures are isolated: a hook
-      # that raises gets its contribution dropped silently for
-      # this call so the rest of the dispatch chain continues.
-      def flow_contribution_for(call_node:, scope:) # rubocop:disable Lint/UnusedMethodArgument
-        nil
-      end
+      # NOTE: (ADR-52 WD3): the legacy ungated per-call hook
+      # `flow_contribution_for` was DELETED here pre-1.0 after its five
+      # production users migrated. Per-call return types are declared via
+      # the gated {.dynamic_return} DSL (static / run-time / per-file
+      # name sets, static / run-time receiver sets); post-return
+      # narrowing facts via {.type_specifier}. See the CHANGELOG
+      # migration note for the idiom-by-idiom mapping.
 
       # ADR-9 slice 3 — per-run preparation hook. The runner
       # invokes `#prepare(services)` on every loaded plugin once
@@ -363,10 +538,14 @@ module Rigor
 
         diagnostics = []
         Source::NodeWalker.each_with_ancestors(root) do |node, ancestors|
+          # One frozen NodeContext per node, shared across the rules
+          # that match it (ADR-52 WD1) — built lazily so non-matching
+          # nodes (the vast majority) allocate nothing.
+          context = nil
           rules.each do |rule|
             next unless node.is_a?(rule[:node_type])
 
-            context = NodeContext.new(ancestors)
+            context ||= NodeContext.new(ancestors)
             diagnostics.concat(Array(instance_exec(node, scope, path, file_context, context, &rule[:block])))
           end
         end
@@ -375,20 +554,22 @@ module Rigor
 
       # ADR-37 slice 2 — the return type contributed by this plugin's
       # {.dynamic_return} rules for a call, or nil. The engine calls this
-      # from `MethodDispatcher` alongside (and ahead of) the legacy
-      # `flow_contribution_for`; a rule fires only when `receiver_type`'s
+      # from `MethodDispatcher`; a rule fires only when `receiver_type`'s
       # class equals or inherits from one of its declared `receivers:`.
       # First non-nil wins (declaration order). Failures isolate to nil.
       def dynamic_return_type(call_node:, scope:, receiver_type:)
         rules = self.class.dynamic_returns
         return nil if rules.empty? || receiver_type.nil?
 
+        # `class_name` is nil for a receiver carrier with no nominal
+        # class (a refinement dimension, an inferred shape) — fine for a
+        # receiver-less (methods-only) rule (ADR-52 WD2), which gates on
+        # the method name alone and reads the receiver shape inside its
+        # own block.
         class_name = dynamic_return_receiver_class_name(receiver_type)
-        return nil if class_name.nil?
-
         environment = scope&.environment
         rules.each do |rule|
-          next unless rule[:receivers].any? { |c| class_matches_receiver?(class_name, c, environment) }
+          next unless dynamic_return_rule_applies?(rule, call_node, class_name, environment, scope)
 
           result = instance_exec(call_node, scope, &rule[:block])
           return result if result
@@ -400,8 +581,8 @@ module Rigor
 
       # ADR-37 slice 2 — the post-return narrowing facts contributed by
       # this plugin's {.type_specifier} rules for a call. The engine
-      # calls this from `StatementEvaluator` alongside the legacy
-      # `flow_contribution_for`; a rule fires only when `call_node.name`
+      # calls this from `StatementEvaluator`; a rule fires only when
+      # `call_node.name`
       # is one of its declared `methods:`. Failures isolate to [].
       def type_specifier_facts(call_node:, scope:)
         rules = self.class.type_specifiers
@@ -643,6 +824,82 @@ module Rigor
         end
       end
 
+      # The gate for one `dynamic_return` rule. Method-name gate first —
+      # a Symbol-array probe vs the receiver ancestry resolution below
+      # (ADR-52 WD1); both are pure predicates, so order only affects
+      # cost. A receiver-less rule (ADR-52 WD2) skips the ancestry check
+      # entirely and fires on the method name alone.
+      def dynamic_return_rule_applies?(rule, call_node, class_name, environment, scope)
+        return false if rule[:methods] && !resolved_dynamic_return_methods(rule).include?(call_node.name)
+
+        if rule[:file_methods]
+          # The path is read here, not in `dynamic_return_type`, so a
+          # spec-double scope without `source_path` only affects
+          # `file_methods:` rules (other gate forms never touch it).
+          path = scope.respond_to?(:source_path) ? scope.source_path : nil
+          return false unless resolved_dynamic_return_file_methods(rule, path).include?(call_node.name)
+        end
+
+        receivers = resolved_dynamic_return_receivers(rule)
+        return true if receivers.nil?
+        return false if class_name.nil?
+
+        receivers.any? { |c| class_matches_receiver?(class_name, c, environment) }
+      end
+
+      # ADR-52 slice 4 — the rule's method-name set. A static Array is
+      # returned as-is (`#include?` over Symbols); a run-time callable is
+      # `instance_exec`'d against this plugin and memoised as a Symbol Set,
+      # same lazy/idempotent contract as a callable `receivers:`. The
+      # cache key is namespaced so a rule that makes both `methods:` and
+      # `receivers:` callable keeps two distinct memo slots.
+      def resolved_dynamic_return_methods(rule)
+        methods = rule[:methods]
+        return methods unless methods.respond_to?(:call)
+
+        (@dynamic_return_runtime_cache ||= {})[[:methods, rule]] ||=
+          Array(instance_exec(&methods)).to_set(&:to_sym).freeze
+      end
+
+      # ADR-52 slice 5a — the rule's per-file method-name set. The
+      # `file_methods:` callable is `instance_exec`'d with the file path
+      # and memoised per `(rule, path)` — one resolution per analysed
+      # file, the per-file analogue of the run-wide `methods:` memo. A
+      # nil path (synthetic call sites with no file context) resolves to
+      # the empty set: the gate has nothing to key on, so the rule
+      # declines — fail-closed, consistent with the gate's purpose. A
+      # raising callable degrades to "declines this dispatch" via
+      # `dynamic_return_type`'s surrounding rescue.
+      EMPTY_NAME_SET = Set.new.freeze
+      private_constant :EMPTY_NAME_SET
+
+      def resolved_dynamic_return_file_methods(rule, path)
+        return EMPTY_NAME_SET if path.nil?
+
+        (@dynamic_return_runtime_cache ||= {})[[:file_methods, rule, path]] ||=
+          Array(instance_exec(path, &rule[:file_methods])).to_set(&:to_sym).freeze
+      end
+
+      # ADR-52 slice 3 — the rule's receiver class-name Array. A static
+      # Array is returned as-is; a run-time callable is `instance_exec`'d
+      # against this plugin (so it reads the `#prepare`-built indexes) and
+      # memoised per rule for the run. Resolution is lazy — first reached
+      # during file analysis, always after `#prepare` — and the callable
+      # is required to be idempotent, so the memoised set is stable. A
+      # callable that raises degrades to "no receivers match" (the rule
+      # declines), never a crash, consistent with the surrounding rescue.
+      def resolved_dynamic_return_receivers(rule)
+        receivers = rule[:receivers]
+        return receivers unless receivers.respond_to?(:call)
+
+        # `||= {}` keeps the path correct even when a caller bypassed
+        # `initialize` (`allocate` in unit specs that inject a fake
+        # index); a self-freezing plugin already has the Hash from
+        # `initialize`, so the `||=` is a no-op there (never a FrozenError).
+        (@dynamic_return_runtime_cache ||= {})[rule] ||=
+          Array(instance_exec(&receivers)).map { |c| c.to_s.dup.freeze }.freeze
+      end
+
       # True when `class_name` equals or inherits from `constraint`,
       # matched through `Environment#class_ordering` (the mechanism
       # `MacroBlockSelfType` / `additional_initializers` use). Degrades to

data/lib/rigor/plugin/node_rule_walk.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require_relative "node_context"
+require_relative "../source/node_walker"
+
+module Rigor
+  module Plugin
+    # ADR-52 WD4 — one engine-owned AST walk per file for node rules.
+    #
+    # Before this, every plugin that declared a {Base.node_rule} walked
+    # the file's AST itself (`Base#node_rule_diagnostics` →
+    # `Source::NodeWalker.each_with_ancestors`), so a project with N
+    # node-rule plugins paid N walks per file. This folds them into a
+    # single walk that dispatches each visited node to every matching
+    # `(plugin, rule)` pair.
+    #
+    # Behaviour is preserved exactly so the diagnostics stay
+    # byte-identical (the WD6 gate):
+    #
+    # * Each plugin's `node_file_context` block runs once per file,
+    #   before any of its rules fire, `instance_exec`'d on that plugin —
+    #   same as the per-plugin walk.
+    # * One frozen {NodeContext} is built per node, lazily, only when at
+    #   least one rule matches it. Because it wraps only the ancestors it
+    #   is safe to share across plugins for the same node.
+    # * Each rule block is `instance_exec`'d on its own plugin instance
+    #   with the same five arguments `(node, scope, path, file_context,
+    #   context)`.
+    # * A plugin whose context block or any rule block raises has its
+    #   whole node-rule contribution isolated — the walk records the
+    #   error against that plugin and continues, matching the runner's
+    #   per-plugin rescue around the old `#node_rule_diagnostics` call.
+    # * Diagnostics are bucketed per plugin and returned in the
+    #   registry order the runner already iterates, so emission order is
+    #   unchanged (plugin-major, not node-major) — order preservation is
+    #   what keeps the gate byte-identical in this slice.
+    #
+    # The result is an ordered Array of {Result}, one per node-rule
+    # plugin (registry order). `Result#error` is non-nil iff that
+    # plugin's context or a rule block raised, in which case
+    # `#diagnostics` is empty; the runner turns the error into the same
+    # per-plugin `runtime-error` envelope it produced before.
+    class NodeRuleWalk
+      # One plugin's node-rule outcome for a single file. `error` is the
+      # exception raised by the plugin's context block or a rule block
+      # (nil on success); when set, `diagnostics` is empty.
+      Result = Struct.new(:plugin, :diagnostics, :error)
+
+      # Plugins that declare at least one `node_rule`, paired with their
+      # frozen rule list, in registry order. Built once per run and
+      # reused for every file.
+      def initialize(plugins)
+        @entries = plugins.filter_map do |plugin|
+          rules = plugin.class.node_rules
+          rules.empty? ? nil : [plugin, rules]
+        end.freeze
+        freeze
+      end
+
+      def empty?
+        @entries.empty?
+      end
+
+      # 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:)
+        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)
+        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?
+
+            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.
+            context ||= NodeContext.new(ancestors)
+            state.run_rules(matched, node, scope, path, context)
+          end
+        end
+      end
+
+      # Mutable per-(plugin, file) walk state. Kept private to the walk —
+      # holds the diagnostics bucket, the file context, the per-concrete-
+      # class match memo, and the isolation flag.
+      class State
+        def initialize(plugin, rules, scope, root)
+          @plugin = plugin
+          @rules = rules
+          @diagnostics = []
+          @match_cache = {}.compare_by_identity
+          @error = nil
+          build_file_context(scope, root)
+        end
+
+        def failed?
+          !@error.nil?
+        end
+
+        # Rules whose `node_type` this concrete node satisfies, memoised
+        # by the node's class so the `is_a?` scan runs once per class.
+        # Preserves `is_a?` semantics when a rule's `node_type` is a
+        # superclass of the concrete node.
+        def rules_for(node)
+          @match_cache[node.class] ||=
+            @rules.select { |rule| node.is_a?(rule[:node_type]) }
+        end
+
+        def run_rules(matched, node, scope, path, context)
+          matched.each do |rule|
+            result = @plugin.instance_exec(node, scope, path, @file_context, context, &rule[:block])
+            @diagnostics.concat(Array(result))
+          end
+        rescue StandardError => e
+          @error = e
+          @diagnostics = []
+        end
+
+        def result
+          NodeRuleWalk::Result.new(@plugin, @diagnostics, @error)
+        end
+
+        private
+
+        def build_file_context(scope, root)
+          block = @plugin.class.node_file_context_block
+          @file_context = block ? @plugin.instance_exec(root, scope, &block) : nil
+        rescue StandardError => e
+          @error = e
+          @file_context = nil
+        end
+      end
+      private_constant :State
+    end
+  end
+end