rigortype 0.1.17 → 0.1.19

data/lib/rigor/plugin/registry.rb

@@ -4,40 +4,225 @@ require_relative "blueprint"
 
 module Rigor
   module Plugin
-    # Categorises a loaded plugin set by which per-call contribution
-    # paths each plugin actually implements, so the engine's per-dispatch
-    # `collect_plugin_contributions` can iterate only the relevant
-    # plugins instead of calling into every plugin on every call site (a
-    # top hotspot on plugin-heavy projects — GitLab's 11 plugins, of which
-    # only 2 implement any per-call path). Built once per {Registry}; the
+    # 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` 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
+    # which only 2 implement any per-call path). Built once per
+    # {Registry}.
+    #
+    # Ordering contract: the gates only PRUNE consultations that could
+    # not fire (every pruned rule would have failed its own `methods:` /
+    # `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
     # receiver-class ancestry match for `dynamic_return` still happens
-    # per-dispatch inside `Plugin::Base#dynamic_return_type`, so this only
-    # prunes plugins that *structurally* cannot contribute, preserving the
-    # exact contribution order and result.
+    # per-dispatch inside `Plugin::Base#dynamic_return_type`.
     class ContributionIndex
       # Ordered (registry-order) subsets relevant to each collector, and
-      # the membership sets used to gate the two paths within a plugin.
-      attr_reader :for_method_dispatch, :for_statement
+      # the membership sets used to gate the paths within a plugin.
+      # `for_file_diagnostics` is the subset the runner's per-file
+      # diagnostic loop visits: plugins overriding
+      # `#diagnostics_for_file` or declaring at least one `node_rule`.
+      attr_reader :for_method_dispatch, :for_statement, :for_file_diagnostics
+
+      EMPTY_BLOCK_ENTRIES = [].freeze
+      private_constant :EMPTY_BLOCK_ENTRIES
 
       def initialize(plugins)
-        @flow = plugins.select { |p| flow_overridden?(p) }.to_set
-        @dynamic = plugins.reject { |p| p.class.dynamic_returns.empty? }.to_set
-        @type_specifier = plugins.reject { |p| p.class.type_specifiers.empty? }.to_set
-        @for_method_dispatch = plugins.select { |p| @flow.include?(p) || @dynamic.include?(p) }.freeze
-        @for_statement = plugins.select { |p| @flow.include?(p) || @type_specifier.include?(p) }.freeze
+        compile_memberships(plugins)
+        compile_gates
+        @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
+        # because the class graph is fixed for the lifetime of a run.
+        @owns_receiver_memo = {}.compare_by_identity
         freeze
       end
 
-      def flow?(plugin) = @flow.include?(plugin)
       def dynamic?(plugin) = @dynamic.include?(plugin)
       def type_specifier?(plugin) = @type_specifier.include?(plugin)
 
+      # O(1) "could any plugin contribute a return type for a call named
+      # `method_name`?" — false only when every `dynamic_return` rule is
+      # `methods:`-gated on other names, in which case the ungated walk
+      # would have produced zero contributions too.
+      def dispatch_candidate?(method_name)
+        return true if @dynamic_global_gate.nil?
+
+        @dynamic_global_gate.include?(method_name)
+      end
+
+      # O(1) statement-path sibling of {#dispatch_candidate?} over the
+      # `type_specifier` rules (which are always `methods:`-gated).
+      def statement_candidate?(method_name)
+        return true if @type_specifier_global_gate.nil?
+
+        @type_specifier_global_gate.include?(method_name)
+      end
+
+      # Per-plugin gate: false when the plugin declares no
+      # `dynamic_return` rules at all, or when every rule is
+      # `methods:`-gated and none lists `method_name` — i.e. when
+      # `#dynamic_return_type` would return nil without ever entering a
+      # rule block. Subsumes the old `dynamic?(plugin)` membership
+      # check at the collector's call site.
+      def dynamic_candidate_for?(plugin, method_name)
+        return false unless @dynamic.include?(plugin)
+
+        gate = @dynamic_gates[plugin]
+        gate.nil? || gate.include?(method_name)
+      end
+
+      # Per-plugin gate over `type_specifier` rules; same contract as
+      # {#dynamic_candidate_for?}.
+      def type_specifier_candidate_for?(plugin, method_name)
+        return false unless @type_specifier.include?(plugin)
+
+        gate = @type_specifier_gates[plugin]
+        gate.nil? || gate.include?(method_name)
+      end
+
+      # 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
+      # manifest-declared `owns_receivers:` entry. The union is compiled
+      # at build time (almost always empty → O(1) false) and per-class
+      # verdicts memoise per environment.
+      def owns_receiver?(class_name, environment)
+        return false if @owns_receivers.empty? || class_name.nil?
+
+        memo = (@owns_receiver_memo[environment] ||= {})
+        memo.fetch(class_name) do
+          memo[class_name] =
+            @owns_receivers.any? { |owner| class_matches_owner?(class_name, owner, environment) }
+        end
+      end
+
       private
 
-      # A plugin contributes via the legacy `flow_contribution_for` slot
-      # only when it overrides the no-op base implementation.
-      def flow_overridden?(plugin)
-        plugin.method(:flow_contribution_for).owner != Rigor::Plugin::Base
+      # The categorisation sets + the ordered per-collector subsets.
+      def compile_memberships(plugins)
+        plugins.each { |p| reject_legacy_flow_hook!(p) }
+        @dynamic = plugins.reject { |p| p.class.dynamic_returns.empty? }.to_set
+        @type_specifier = plugins.reject { |p| p.class.type_specifiers.empty? }.to_set
+        compile_collector_subsets(plugins)
+      end
+
+      def compile_collector_subsets(plugins)
+        @for_method_dispatch = plugins.select { |p| @dynamic.include?(p) }.freeze
+        @for_statement = plugins.select { |p| @type_specifier.include?(p) }.freeze
+        @for_file_diagnostics =
+          plugins.select { |p| file_diagnostics_overridden?(p) || !p.class.node_rules.empty? }.freeze
+      end
+
+      # The per-plugin and registry-global method-name gates.
+      def compile_gates
+        @dynamic_gates = build_name_gates(@dynamic) { |p| p.class.dynamic_returns }
+        @type_specifier_gates = build_name_gates(@type_specifier) { |p| p.class.type_specifiers }
+        @dynamic_global_gate = union_gate(@dynamic_gates)
+        @type_specifier_global_gate = union_gate(@type_specifier_gates)
+      end
+
+      # ADR-52 WD3 — the legacy ungated `flow_contribution_for` hook was
+      # deleted pre-1.0. A plugin still defining it would silently never
+      # be called, which is the worst failure mode for its author —
+      # surface a loud load-time error with the migration mapping
+      # instead. (The Base default is gone, so any definer wrote it
+      # themselves.)
+      def reject_legacy_flow_hook!(plugin)
+        return unless plugin.respond_to?(:flow_contribution_for)
+
+        raise ArgumentError,
+              "plugin #{(plugin.class.name || plugin.class).inspect} defines `flow_contribution_for`, " \
+              "which was removed (ADR-52). Declare the per-call return type via `dynamic_return` " \
+              "(receivers:/methods:/file_methods: gates, static or callable) and post-return narrowing " \
+              "facts via `type_specifier` — see the CHANGELOG migration note."
+      end
+
+      # Same `Method#owner` trick for the per-file diagnostics hook —
+      # the Base default returns `[]`, so a non-overriding plugin can be
+      # skipped without calling it.
+      def file_diagnostics_overridden?(plugin)
+        plugin.method(:diagnostics_for_file).owner != Rigor::Plugin::Base
+      end
+
+      # `plugin → Set[Symbol] | nil`. A frozen Set when EVERY rule of
+      # the plugin is `methods:`-gated (the union of those names); nil
+      # when any rule is ungated (the plugin must be consulted for every
+      # method name, exactly as before).
+      def build_name_gates(members)
+        gates = {}
+        members.each do |plugin|
+          rules = yield(plugin)
+          # A static method-name Array can be compiled into the gate. A
+          # run-time callable `methods:` (ADR-52 slice 4) is unknown until
+          # after `#prepare`, and a receiver-only rule has no `methods:` —
+          # either makes the plugin ungated-by-name (nil), consulted on
+          # every dispatch and filtered in the instance path.
+          gates[plugin] =
+            if rules.all? { |rule| rule[:methods].is_a?(Array) }
+              rules.flat_map { |rule| rule[:methods] }.to_set.freeze
+            end
+        end
+        gates.freeze
+      end
+
+      # The registry-wide union of per-plugin gates, or nil when any
+      # plugin is ungated (no global pruning possible). An empty
+      # plugin set unions to an empty frozen Set — the collectors'
+      # `relevant.empty?` early return fires before it is consulted.
+      def union_gate(gates)
+        return nil if gates.value?(nil)
+
+        gates.values.reduce(Set.new) { |acc, names| acc.merge(names) }.freeze
+      end
+
+      # `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.method_names.each { |name| (table[name] ||= []) << entry }
+          end
+        end
+        table.each_value(&:freeze)
+        table.freeze
+      end
+
+      # Mirrors `MethodDispatcher`'s previous per-dispatch matching:
+      # exact-name fast path, then `Environment#class_ordering`,
+      # degrading to "no match" on any resolution failure.
+      def class_matches_owner?(class_name, owner, environment)
+        return true if class_name == owner
+        return false if environment.nil?
+
+        %i[equal subclass].include?(environment.class_ordering(class_name, owner))
+      rescue StandardError
+        false
+      end
+
+      # Manifest access tolerant of manifest-less plugin doubles in unit
+      # specs (a real loaded plugin always carries one — the loader
+      # validates it).
+      def manifest_for(plugin)
+        plugin.manifest
+      rescue StandardError
+        nil
       end
     end
 
@@ -78,9 +263,29 @@ module Rigor
         @load_errors = load_errors.dup.freeze
         @blueprints = blueprints.dup.freeze
         @contribution_index = ContributionIndex.new(@plugins)
+        # ADR-52 WD1 — aggregate queries the engine issues per def /
+        # per diagnostic candidate / per path are compiled once here
+        # (the registry is frozen, so the flat_map-on-every-call
+        # versions re-derived an invariant). `@contracts_by_path` is a
+        # mutable per-path memo inside the frozen registry — safe
+        # because the contract set and the glob semantics are fixed
+        # for the lifetime of the run.
+        @additional_initializers = @plugins.flat_map { |p| safe_manifest(p)&.additional_initializers || [] }.freeze
+        @open_receivers = @plugins.flat_map { |p| (safe_manifest(p)&.open_receivers || []).map(&:to_s) }.uniq.freeze
+        @open_receivers_set = @open_receivers.to_set.freeze
+        @protocol_contracts = @plugins.flat_map { |p| safe_protocol_contracts(p) }.freeze
+        @contracts_by_path = {}
+        # ADR-52 WD4 — the single engine-owned node-rule walk, compiled
+        # once per run from the node-rule plugin subset (registry order).
+        # The runner reuses it for every file; it builds fresh per-file
+        # state internally, so it is safe to freeze and share.
+        @node_rule_walk = NodeRuleWalk.new(@plugins)
         freeze
       end
 
+      # ADR-52 WD4 — the per-run node-rule walk (see {NodeRuleWalk}).
+      attr_reader :node_rule_walk
+
       # ADR-15 Phase 3 — build a fresh Registry from the supplied
       # blueprint set by replaying {Blueprint#materialize} per
       # entry against `services`. The returned registry carries
@@ -158,14 +363,15 @@ module Rigor
       # beyond its RBS-declared method surface. `open_receiver?`
       # is the membership predicate `Analysis::CheckRules` consults
       # to skip the `call.undefined-method` rule for such a class.
-      def open_receivers
-        plugins.flat_map { |plugin| plugin.manifest.open_receivers }
-      end
+      # Compiled at construction (ADR-52 WD1) — the predicate runs per
+      # undefined-method candidate, so the previous per-call flat_map
+      # re-derived a frozen invariant.
+      attr_reader :open_receivers
 
       def open_receiver?(class_name)
         return false if class_name.nil?
 
-        open_receivers.include?(class_name.to_s)
+        @open_receivers_set.include?(class_name.to_s)
       end
 
       # ADR-28 — flat, ordered list of every loaded plugin's
@@ -176,10 +382,10 @@ module Rigor
       # Consumed by `Inference::MethodParameterBinder` (the
       # parameter-type provision) and by contributing plugins'
       # `#diagnostics_for_file` hooks (the presence + return-type
-      # check).
-      def protocol_contracts
-        plugins.flat_map(&:protocol_contracts)
-      end
+      # check). Compiled at construction (ADR-52 WD1); a plugin's
+      # config-folding `#protocol_contracts` override is stable for the
+      # run because config is injected at construction.
+      attr_reader :protocol_contracts
 
       # ADR-38 — flat, ordered list of every loaded plugin's
       # manifest-declared `Rigor::Plugin::AdditionalInitializer`
@@ -187,9 +393,9 @@ module Rigor
       # read-before-write nil soundness gate: a `def` whose name an
       # entry covers, on a class that equals or inherits from the
       # entry's `receiver_constraint`, is treated like `initialize`.
-      def additional_initializers
-        plugins.flat_map { |plugin| plugin.manifest.additional_initializers }
-      end
+      # Compiled at construction (ADR-52 WD1) — consulted per `def`
+      # node, ×2 sites in `ScopeIndexer`.
+      attr_reader :additional_initializers
 
       # ADR-28 — the subset of `protocol_contracts` whose
       # `path_glob` matches `path`. Contract globs are authored
@@ -201,11 +407,15 @@ module Rigor
       # suffix. `File::FNM_PATHNAME` keeps `*` from crossing `/`;
       # `File::FNM_EXTGLOB` enables `{a,b}` groups. Returns `[]` for
       # a nil path so the binder can call this unconditionally.
+      # Memoised per path (ADR-52 WD1) — consulted per `def` node by
+      # `MethodParameterBinder`, and the fnmatch sweep over every
+      # contract is pure in (contract set, path).
       def contracts_for_path(path)
         return [] if path.nil?
 
         path_s = path.to_s
-        protocol_contracts.select { |contract| path_matches_glob?(contract.path_glob, path_s) }
+        @contracts_by_path[path_s] ||=
+          protocol_contracts.select { |contract| path_matches_glob?(contract.path_glob, path_s) }.freeze
       end
 
       # ADR-32 WD4 + WD5 — flat ordered list of
@@ -232,14 +442,33 @@ module Rigor
       FNMATCH_FLAGS = File::FNM_PATHNAME | File::FNM_EXTGLOB
       private_constant :FNMATCH_FLAGS
 
-      EMPTY = new.freeze
-
       private
 
       def path_matches_glob?(glob, path)
         File.fnmatch?(glob, path, FNMATCH_FLAGS) ||
           File.fnmatch?(File.join("**", glob), path, FNMATCH_FLAGS)
       end
+
+      # Construction-time manifest access tolerant of manifest-less
+      # plugin doubles in unit specs (a real loaded plugin always
+      # carries one — the loader validates it). Mirrors
+      # `ContributionIndex#manifest_for`.
+      def safe_manifest(plugin)
+        plugin.manifest
+      rescue StandardError
+        nil
+      end
+
+      def safe_protocol_contracts(plugin)
+        plugin.protocol_contracts || []
+      rescue StandardError
+        []
+      end
     end
+
+    # Assigned after the class body completes — `Registry.new` runs at
+    # assignment time and `#initialize` calls private helpers defined
+    # late in the body.
+    Registry::EMPTY = Registry.new.freeze
   end
 end

data/lib/rigor/plugin.rb

@@ -9,6 +9,7 @@ require_relative "plugin/io_boundary"
 require_relative "plugin/fact_store"
 require_relative "plugin/services"
 require_relative "plugin/base"
+require_relative "plugin/node_rule_walk"
 require_relative "plugin/registry"
 require_relative "plugin/load_error"
 require_relative "plugin/box"

data/lib/rigor/rbs_extended/conformance_checker.rb

@@ -118,12 +118,17 @@ module Rigor
       # nil. Mirrors the ADR-35 override checks: covariant return,
       # contravariant params, single method type only, `Dynamic[Top]`
       # positions skipped (fires only on a proven `accepts(...).no?`).
+      # Also checks arity divergence and keyword-requiredness divergence
+      # (positional-type comparison only was the initial scope; these
+      # extend it to the cases that cause runtime ArgumentError).
       def signature_mismatch(required_method, provided_method)
         return nil unless required_method.method_types.size == 1
         return nil unless provided_method.method_types.size == 1
 
         return_detail(required_method, provided_method) ||
-          param_detail(required_method, provided_method)
+          param_detail(required_method, provided_method) ||
+          arity_detail(required_method, provided_method) ||
+          keyword_detail(required_method, provided_method)
       end
 
       def return_detail(required_method, provided_method)
@@ -153,6 +158,86 @@ module Rigor
         nil
       end
 
+      # Checks positional-count divergence — cases that would cause a
+      # runtime `ArgumentError` even when every declared type matches.
+      # Skipped when either side has a rest parameter (`*args`) since
+      # that makes the arity range unbounded. Two violation shapes:
+      # (a) provided requires MORE positionals than the interface allows
+      #     (caller passes ≤ interface total → provided raises);
+      # (b) provided accepts FEWER positionals than the interface requires
+      #     (caller passes ≥ interface required → provided raises).
+      def arity_detail(required_method, provided_method)
+        req_func = required_method.method_types.first.type
+        prov_func = provided_method.method_types.first.type
+        return nil unless req_func.respond_to?(:required_positionals)
+        return nil unless prov_func.respond_to?(:required_positionals)
+
+        req_req  = req_func.required_positionals.size
+        req_opt  = req_func.optional_positionals.size
+        prov_req = prov_func.required_positionals.size
+        prov_opt = prov_func.required_positionals.size + prov_func.optional_positionals.size
+
+        # (a) provided requires too many — callers may not pass enough
+        if req_func.rest_positionals.nil? && prov_req > req_req + req_opt
+          return "requires #{prov_req} positional argument#{'s' if prov_req != 1} " \
+                 "but the interface allows at most #{req_req + req_opt}"
+        end
+
+        # (b) provided accepts too few — callers will pass more than provided can handle
+        if prov_func.rest_positionals.nil? && req_req > prov_opt
+          return "accepts at most #{prov_opt} positional argument#{'s' if prov_opt != 1} " \
+                 "but the interface requires at least #{req_req}"
+        end
+
+        nil
+      end
+
+      # Checks keyword-requiredness divergence.
+      # (a) A keyword the interface requires that the provided method does
+      #     not accept at all → callers will pass it, provided will raise.
+      # (b) A keyword the provided method requires that the interface does
+      #     not mention → callers following the interface won't pass it,
+      #     provided will raise.
+      # Skipped when either side has a keyword rest (`**kwargs`).
+      def keyword_detail(required_method, provided_method)
+        req_func, prov_func = keyword_funcs(required_method, provided_method)
+        return nil unless req_func
+
+        prov_accepted = accepted_keywords(prov_func)
+        req_accepted  = accepted_keywords(req_func)
+
+        not_accepted = req_func.required_keywords.keys - prov_accepted
+        return keyword_mismatch_message("does not accept required", not_accepted) if not_accepted.any?
+
+        extra_required = prov_func.required_keywords.keys - req_accepted
+        if extra_required.any?
+          return keyword_mismatch_message("requires", extra_required,
+                                          suffix: " not declared by the interface")
+        end
+
+        nil
+      end
+
+      def keyword_funcs(required_method, provided_method)
+        req_func  = required_method.method_types.first.type
+        prov_func = provided_method.method_types.first.type
+        return [nil, nil] unless req_func.respond_to?(:required_keywords)
+        return [nil, nil] unless prov_func.respond_to?(:required_keywords)
+        return [nil, nil] unless req_func.rest_keywords.nil? && prov_func.rest_keywords.nil?
+
+        [req_func, prov_func]
+      end
+
+      def accepted_keywords(func)
+        func.required_keywords.keys + func.optional_keywords.keys
+      end
+
+      def keyword_mismatch_message(prefix, kw_keys, suffix: "")
+        listed = kw_keys.sort.map { |k| "`#{k}:`" }.join(", ")
+        noun   = kw_keys.size == 1 ? "keyword" : "keywords"
+        "#{prefix} #{noun} #{listed}#{suffix}"
+      end
+
       def positional_param_types(method_def)
         func = method_def.method_types.first.type
         return nil unless func.respond_to?(:required_positionals)

data/lib/rigor/scope/discovery_index.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Rigor
+  class Scope
+    # ADR-53 Track A — the seed-time discovery context every Scope snapshot
+    # carries by a single reference. Holds the tables the index-time
+    # pre-passes (`Inference::ScopeIndexer` per file, plus the cross-file
+    # project pre-pass) populate and that no control-flow transition ever
+    # varies: `Scope#==` ignores them and `Scope#join` copies them from the
+    # receiver unexamined, which is the membership litmus the ADR fixes.
+    #
+    # Immutable (`Data` instances are frozen); deriving a seeded index goes
+    # through `#with(table_name: table)`. `Scope` exposes each table through
+    # its existing reader surface, so engine call sites and plugins are
+    # unaffected by the extraction.
+    DiscoveryIndex = Data.define(
+      :declared_types,
+      :class_ivars,
+      :class_cvars,
+      :program_globals,
+      :discovered_classes,
+      :in_source_constants,
+      :discovered_methods,
+      :discovered_def_nodes,
+      :discovered_singleton_def_nodes,
+      :discovered_def_sources,
+      :discovered_method_visibilities,
+      :discovered_superclasses,
+      :discovered_includes,
+      :discovered_class_sources,
+      :data_member_layouts
+    )
+
+    class DiscoveryIndex
+      EMPTY_NODE_TABLE = {}.compare_by_identity.freeze
+      EMPTY_TABLE = {}.freeze
+      private_constant :EMPTY_NODE_TABLE, :EMPTY_TABLE
+
+      # The shared all-empty index `Scope.empty` (and every scope that never
+      # sees a seeding pass) points at — one allocation per process.
+      EMPTY = new(
+        declared_types: EMPTY_NODE_TABLE,
+        class_ivars: EMPTY_TABLE,
+        class_cvars: EMPTY_TABLE,
+        program_globals: EMPTY_TABLE,
+        discovered_classes: EMPTY_TABLE,
+        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,
+        discovered_includes: EMPTY_TABLE,
+        discovered_class_sources: EMPTY_TABLE,
+        data_member_layouts: EMPTY_TABLE
+      )
+    end
+  end
+end