rigortype 0.1.17 → 0.1.19

data/lib/rigor/plugin/macro/block_as_method.rb

@@ -4,9 +4,9 @@ module Rigor
   module Plugin
     module Macro
       # ADR-16 Tier A declaration: "the block passed to a
-      # class-level DSL call of one of `verbs` runs as an instance
-      # method on `receiver_constraint`'s subclass tree, with
-      # `self` typed accordingly."
+      # class-level DSL call of one of `method_names` runs as an
+      # instance method on `receiver_constraint`'s subclass tree,
+      # with `self` typed accordingly."
       #
       # Authored on a plugin manifest:
       #
@@ -16,7 +16,7 @@ module Rigor
       #     block_as_methods: [
       #       Rigor::Plugin::Macro::BlockAsMethod.new(
       #         receiver_constraint: "Sinatra::Base",
-      #         verbs: %i[get post put delete head options patch link unlink]
+      #         method_names: %i[get post put delete head options patch link unlink]
       #       )
       #     ]
       #   )
@@ -41,9 +41,10 @@ module Rigor
       #   for the entry to fire. For Sinatra modular-style this is
       #   `"Sinatra::Base"`; the substrate's class-context match
       #   accepts every subclass.
-      # - `verbs` — Array of Symbol method names. A call shape
+      # - `method_names` — Array of Symbol method names. A call shape
       #   `<receiver_subclass>.get('/path') { ... }` matches when
-      #   `:get` is in this list.
+      #   `:get` is in this list. (Named `verbs:` before ADR-60 WD2
+      #   normalised the macro value-object vocabulary.)
       # - `self_type` — Symbol selecting the kind of `self`-binding
       #   the substrate applies inside the block. Slice 1a accepts
       #   only `:receiver_instance` (the block runs as an instance
@@ -53,22 +54,22 @@ module Rigor
       # ## Ractor-shareability
       #
       # All fields are frozen at construction (ADR-15 Phase 1).
-      # `verbs` is dup-frozen so the caller's mutable array does
-      # not leak into the value. `Ractor.shareable?` returns true
-      # after `#initialize`.
+      # `method_names` is dup-frozen so the caller's mutable array
+      # does not leak into the value. `Ractor.shareable?` returns
+      # true after `#initialize`.
       class BlockAsMethod
         SELF_TYPE_RECEIVER_INSTANCE = :receiver_instance
         VALID_SELF_TYPES = [SELF_TYPE_RECEIVER_INSTANCE].freeze
 
-        attr_reader :receiver_constraint, :verbs, :self_type
+        attr_reader :receiver_constraint, :method_names, :self_type
 
-        def initialize(receiver_constraint:, verbs:, self_type: SELF_TYPE_RECEIVER_INSTANCE)
+        def initialize(receiver_constraint:, method_names:, self_type: SELF_TYPE_RECEIVER_INSTANCE)
           validate_receiver_constraint!(receiver_constraint)
-          validate_verbs!(verbs)
+          validate_method_names!(method_names)
           validate_self_type!(self_type)
 
           @receiver_constraint = receiver_constraint.dup.freeze
-          @verbs = verbs.map(&:to_sym).freeze
+          @method_names = method_names.map(&:to_sym).freeze
           @self_type = self_type
           freeze
         end
@@ -76,7 +77,7 @@ module Rigor
         def to_h
           {
             "receiver_constraint" => receiver_constraint,
-            "verbs" => verbs.map(&:to_s),
+            "method_names" => method_names.map(&:to_s),
             "self_type" => self_type.to_s
           }
         end
@@ -84,13 +85,13 @@ module Rigor
         def ==(other)
           other.is_a?(BlockAsMethod) &&
             receiver_constraint == other.receiver_constraint &&
-            verbs == other.verbs &&
+            method_names == other.method_names &&
             self_type == other.self_type
         end
         alias eql? ==
 
         def hash
-          [receiver_constraint, verbs, self_type].hash
+          [receiver_constraint, method_names, self_type].hash
         end
 
         private
@@ -103,17 +104,17 @@ module Rigor
                 "got #{value.inspect}"
         end
 
-        def validate_verbs!(verbs)
-          unless verbs.is_a?(Array) && !verbs.empty?
+        def validate_method_names!(method_names)
+          unless method_names.is_a?(Array) && !method_names.empty?
             raise ArgumentError,
-                  "Plugin::Macro::BlockAsMethod#verbs must be a non-empty Array, got #{verbs.inspect}"
+                  "Plugin::Macro::BlockAsMethod#method_names must be a non-empty Array, got #{method_names.inspect}"
           end
 
-          verbs.each do |v|
+          method_names.each do |v|
             next if v.is_a?(Symbol) || (v.is_a?(String) && !v.empty?)
 
             raise ArgumentError,
-                  "Plugin::Macro::BlockAsMethod#verbs entries must be Symbol/non-empty String, " \
+                  "Plugin::Macro::BlockAsMethod#method_names entries must be Symbol/non-empty String, " \
                   "got #{v.inspect}"
           end
         end

data/lib/rigor/plugin/macro/nested_class_template.rb

@@ -33,7 +33,7 @@ module Rigor
       #         receiver_constraint: "Mangrove::Enum", # `extend`-ed marker module
       #         block_method: :variants,               # the enclosing DSL block
       #         variant_method: :variant,              # each declaration call
-      #         name_arg_position: 0,                  # constant arg → nested class
+      #         symbol_arg_position: 0,                  # constant arg → nested class
       #         inner_arg_position: 1,                 # type arg → `#inner` return
       #         inner_reader: :inner                   # the payload reader name
       #       )
@@ -48,8 +48,10 @@ module Rigor
       #   (`:variants`).
       # - `variant_method` — Symbol naming each declaration call
       #   inside the block (`:variant`).
-      # - `name_arg_position` — Integer (default 0): the argument
+      # - `symbol_arg_position` — Integer (default 0): the argument
       #   index whose literal **constant** names the nested subclass.
+      #   (Named `name_arg_position:` before ADR-60 WD2 normalised
+      #   the macro value-object vocabulary.)
       # - `inner_arg_position` — Integer (default 1): the argument
       #   index whose type expression becomes the `#inner` reader's
       #   return type. Slice A resolves a constant type argument
@@ -69,21 +71,21 @@ module Rigor
       # `Environment#class_ordering`.
       class NestedClassTemplate
         attr_reader :receiver_constraint, :block_method, :variant_method,
-                    :name_arg_position, :inner_arg_position, :inner_reader
+                    :symbol_arg_position, :inner_arg_position, :inner_reader
 
         def initialize(receiver_constraint:, block_method: :variants, variant_method: :variant,
-                       name_arg_position: 0, inner_arg_position: 1, inner_reader: :inner)
+                       symbol_arg_position: 0, inner_arg_position: 1, inner_reader: :inner)
           validate_constraint!(receiver_constraint)
           validate_method!(block_method, "block_method")
           validate_method!(variant_method, "variant_method")
-          validate_position!(name_arg_position, "name_arg_position")
+          validate_position!(symbol_arg_position, "symbol_arg_position")
           validate_position!(inner_arg_position, "inner_arg_position")
           validate_method!(inner_reader, "inner_reader")
 
           @receiver_constraint = receiver_constraint.dup.freeze
           @block_method = block_method.to_sym
           @variant_method = variant_method.to_sym
-          @name_arg_position = name_arg_position
+          @symbol_arg_position = symbol_arg_position
           @inner_arg_position = inner_arg_position
           @inner_reader = inner_reader.to_sym
           freeze
@@ -94,7 +96,7 @@ module Rigor
             "receiver_constraint" => receiver_constraint,
             "block_method" => block_method.to_s,
             "variant_method" => variant_method.to_s,
-            "name_arg_position" => name_arg_position,
+            "symbol_arg_position" => symbol_arg_position,
             "inner_arg_position" => inner_arg_position,
             "inner_reader" => inner_reader.to_s
           }

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,8 +10,8 @@ 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

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

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require_relative "node_context"
+require_relative "../source/node_walker"
+require_relative "../analysis/check_rules/rule_walk"
+
+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.
+      #
+      # 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, collector_driver)
+        states.map(&:result)
+      end
+
+      private
+
+      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
+
+      def dispatch_plugins(node, ancestors, path, scope, states)
+        node_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.
+          node_context ||= NodeContext.new(ancestors)
+          state.run_rules(matched, node, scope, path, node_context)
+        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