rigortype 0.1.16 → 0.1.18

data/lib/rigor/plugin/registry.rb

@@ -4,6 +4,227 @@ require_relative "blueprint"
 
 module Rigor
   module Plugin
+    # 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`.
+    class ContributionIndex
+      # Ordered (registry-order) subsets relevant to each collector, and
+      # 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)
+        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 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
+
+      # 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
+
     # Read-side query API over the plugins loaded for a single
     # `Analysis::Runner.run`. Constructed by
     # {Rigor::Plugin::Loader.load} and exposed downstream so the
@@ -24,7 +245,7 @@ module Rigor
     # {.materialize} per-Ractor; the live `plugins` carriage on
     # the coordinator registry stays unchanged.
     class Registry
-      attr_reader :plugins, :load_errors, :blueprints
+      attr_reader :plugins, :load_errors, :blueprints, :contribution_index
 
       # @param plugins [Array<Rigor::Plugin::Base>] instantiated
       #   plugin instances in deterministic order.
@@ -40,9 +261,30 @@ module Rigor
         @plugins = plugins.dup.freeze
         @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
@@ -120,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
@@ -138,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`
@@ -149,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
@@ -163,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
@@ -194,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

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+require_relative "../rbs_extended"
+require_relative "../inference/rbs_type_translator"
+
+module Rigor
+  module RbsExtended
+    # Verifies every `rigor:v1:conforms-to <Interface>` class- /
+    # module-level directive in the loaded RBS environment (spec:
+    # `docs/type-specification/rbs-extended.md` § "Explicit
+    # conformance directive"). For each annotated class, the
+    # directive asserts the class satisfies the named structural
+    # interface as a *checked design assertion* — independent of
+    # whether any current call site exercises that requirement.
+    # Multiple directives on one class combine as an intersection:
+    # each interface is checked independently.
+    #
+    # ## Two checked tiers
+    #
+    # 1. **Presence** (FP-free): an interface method the class provably does
+    #    NOT provide anywhere in its RBS-resolved method set (own, inherited,
+    #    included) is a definitive non-conformance.
+    # 2. **Signature compatibility** (covariant return / contravariant
+    #    params): for a method the class DOES provide, the provided RBS
+    #    signature must be a behavioural subtype of the interface's required
+    #    one. Both sides are *authored* RBS (the class in `signature_paths:`
+    #    RBS, the interface in a loaded `sig`/library), so this is the same
+    #    FP-safe both-sides-authored construction as the
+    #    [ADR-35](../../../docs/adr/35-override-signature-compatibility.md)
+    #    `def.override-*` rules — not the inferred-signature comparison whose
+    #    FP risk justified deferring it. Conservative: single-method-type
+    #    (non-overloaded) signatures only, `Dynamic[Top]` positions skipped,
+    #    fires only on a proven `accepts(...).no?` violation.
+    #
+    # ## Output records (all drained by {Rigor::Analysis::Runner})
+    #
+    # - `Unsatisfied` — the class is missing one or more required interface
+    #   methods. Surfaces as `rbs_extended.unsatisfied-conformance`.
+    # - `IncompatibleSignature` — a provided method's signature violates the
+    #   interface contract (return widened, or a parameter narrowed). Same
+    #   rule, signature-specific message.
+    # - `UnresolvedInterface` — the named interface is not loaded (a typo, or
+    #   the defining library / `sig` set is not on the RBS load path).
+    #   Surfaces as `dynamic.rbs-extended.unresolved` `:info`, the fail-soft
+    #   channel the other directive parsers use, so a bad name never silently
+    #   disables the author's assertion.
+    #
+    # Fail-soft throughout: a class whose own definition cannot be built (RBS
+    # error) is skipped rather than reported.
+    module ConformanceChecker
+      Unsatisfied = Data.define(:class_name, :interface_name, :missing_methods, :location)
+      IncompatibleSignature = Data.define(:class_name, :interface_name, :method_name, :detail, :location)
+      UnresolvedInterface = Data.define(:class_name, :interface_name, :location)
+
+      module_function
+
+      # Scans `rbs_loader` for `conforms-to` directives and returns the
+      # failure / unresolved records in source order. Returns an empty array
+      # when no directive is present, the loader is nil, or the env failed to
+      # build (the loader's iterators are themselves fail-soft).
+      def scan(rbs_loader)
+        return [] if rbs_loader.nil?
+
+        results = []
+        rbs_loader.each_class_decl_annotation_with_name do |class_name, string, location|
+          interface_name = RbsExtended.parse_conforms_to_annotation(string)
+          next if interface_name.nil?
+
+          results.concat(check_one(rbs_loader, class_name, interface_name, location))
+        end
+        results
+      end
+
+      # @return [Array] zero or more records for one (class, interface) pair.
+      def check_one(rbs_loader, class_name, interface_name, location)
+        interface_def = resolve_interface(rbs_loader, class_name, interface_name)
+        if interface_def.nil?
+          return [UnresolvedInterface.new(
+            class_name: normalize(class_name), interface_name: interface_name, location: location
+          )]
+        end
+
+        class_def = rbs_loader.instance_definition(class_name)
+        return [] if class_def.nil? # fail-soft: cannot prove non-conformance
+
+        required = interface_def.methods
+        provided = class_def.methods
+        records = []
+        collect_missing(records, class_name, interface_name, required, provided, location)
+        collect_incompatible(records, class_name, interface_name, required, provided, location)
+        records
+      end
+
+      def collect_missing(records, class_name, interface_name, required, provided, location)
+        missing = required.keys - provided.keys
+        return if missing.empty?
+
+        records << Unsatisfied.new(
+          class_name: normalize(class_name), interface_name: interface_name,
+          missing_methods: missing, location: location
+        )
+      end
+
+      def collect_incompatible(records, class_name, interface_name, required, provided, location)
+        (required.keys & provided.keys).each do |method_name|
+          detail = signature_mismatch(required[method_name], provided[method_name])
+          next if detail.nil?
+
+          records << IncompatibleSignature.new(
+            class_name: normalize(class_name), interface_name: interface_name,
+            method_name: method_name, detail: detail, location: location
+          )
+        end
+      end
+
+      # Returns a human-readable mismatch detail when `provided` is NOT a
+      # behavioural subtype of the `required` (interface) signature, else
+      # 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) ||
+          arity_detail(required_method, provided_method) ||
+          keyword_detail(required_method, provided_method)
+      end
+
+      def return_detail(required_method, provided_method)
+        req = translate(required_method.method_types.first.type.return_type)
+        prov = translate(provided_method.method_types.first.type.return_type)
+        return nil if req.nil? || prov.nil?
+        return nil if dynamic_top?(req) || dynamic_top?(prov)
+        return nil unless req.accepts(prov).no?
+
+        "return type #{prov.describe(:short)} is not a subtype of the required #{req.describe(:short)}"
+      end
+
+      def param_detail(required_method, provided_method)
+        req = positional_param_types(required_method)
+        prov = positional_param_types(provided_method)
+        return nil if req.nil? || prov.nil?
+
+        [req.size, prov.size].min.times do |i|
+          rp = req[i]
+          pp = prov[i]
+          next if rp.nil? || pp.nil? || dynamic_top?(rp) || dynamic_top?(pp)
+          next unless pp.accepts(rp).no?
+
+          return "parameter #{i + 1} type #{pp.describe(:short)} does not accept the " \
+                 "required #{rp.describe(:short)}"
+        end
+        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)
+
+        (func.required_positionals + func.optional_positionals).map { |param| translate(param.type) }
+      end
+
+      # Resolves the (possibly namespace-relative) `interface_name` against
+      # the declaring class's namespace chain, mirroring Ruby constant
+      # lookup: `conforms-to _Foo` inside `Bar::Baz` tries `Bar::Baz::_Foo`,
+      # `Bar::_Foo`, then top-level `_Foo` (longest prefix first). Returns
+      # the first interface definition that resolves, or nil. (A leading
+      # `::` is already stripped by the parser, so an intended-absolute name
+      # still resolves via the trailing top-level candidate.)
+      def resolve_interface(rbs_loader, class_name, interface_name)
+        candidate_interface_names(class_name, interface_name).each do |candidate|
+          defn = rbs_loader.interface_definition(candidate)
+          return defn if defn
+        end
+        nil
+      end
+
+      def candidate_interface_names(class_name, interface_name)
+        prefixes = namespace_prefixes(class_name)
+        prefixes.map { |prefix| "#{prefix}::#{interface_name}" } + [interface_name]
+      end
+
+      # Namespace prefixes of a qualified name, longest first:
+      # `"Bar::Baz"` → `["Bar::Baz", "Bar"]`. Covers both the
+      # `class Bar::Baz` and the `module Bar; class Baz` nesting shapes
+      # (a superset of `Module.nesting`, which the directive's resolved
+      # class name does not record).
+      def namespace_prefixes(class_name)
+        parts = normalize(class_name).split("::")
+        (1..parts.size).to_a.reverse.map { |count| parts.first(count).join("::") }
+      end
+
+      def translate(rbs_type)
+        Inference::RbsTypeTranslator.translate(rbs_type, self_type: nil, instance_type: nil, type_vars: {})
+      rescue StandardError
+        nil
+      end
+
+      def dynamic_top?(type)
+        type.is_a?(Type::Dynamic) || (type.respond_to?(:top?) && type.top?.yes?)
+      end
+
+      def normalize(class_name)
+        class_name.to_s.sub(/\A::/, "")
+      end
+    end
+  end
+end