rigortype 0.1.17 → 0.1.18

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

data/lib/rigor/plugin/registry.rb

@@ -4,40 +4,224 @@ 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` verbs, `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:` /
+    # `verbs:` 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_verb = 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 `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)
+      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
+
+      # `verb Symbol → [BlockAsMethod entries]`, insertion-ordered by
+      # (plugin, declaration). Verbs 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 }
+          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 +262,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 +362,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 +381,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 +392,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 +406,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 +441,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)