rigortype 0.1.11 → 0.1.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c5853d88c57eb0ded87f9fbf801e3cfbbc7672be2a16bcc3171bd7e3f33122c
-  data.tar.gz: d3f3b9d936dd4aab4a10c93b7879b34bee26aa1313007619baadb1381b87310c
+  metadata.gz: 182bad9de02b3b4579fe1c385fa740e30f2df85cad36d8c21647dfb09004b9eb
+  data.tar.gz: 398d4ebc670530522696122117592bd59b60d7f899ae0a8cd58b11c8506ec608
 SHA512:
-  metadata.gz: bebba3258c508b893a7ca22e98b17838bcc7267399882956a4ced9c214e87947754f5a15ecf80029cf601eed58c93fc53ffcb50636002df9f75c00d498a0585b
-  data.tar.gz: 4ac6679d930144ffc5a675a9189ed7ce20d500c5ae9d61820b44fcfbf3e02149b615b3b11a44fa48760c17a75b57ec6d6b5ee3e4a80a4b9139514c742c9c612a
+  metadata.gz: abd25775ea4973023dc7ef7132669a0bf556604c7378caef60aa3c2fbae4ef79bc2651cd3499cecb8046507214dbdc4cb56bdb953c301ec42b0ebb86291202b6
+  data.tar.gz: 9281f16a4b2d39847aaaf408844920dfb9f2e6a914df3544182d6d3832f28f03ca63d8a19aa54ca80977f3431351717a59d7ba704f3361ee92697be21d6193ab

data/lib/rigor/analysis/erb_template_detector.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Analysis
+    # Detects when a `.rb` file is actually an ERB template — a Rails
+    # generator `templates/foo.rb` shape that uses `<%= ... %>` to
+    # interpolate identifiers. Prism rejects the template as invalid
+    # Ruby and the analyzer emits one parse-error diagnostic per scrap
+    # the parser tripped over (≈ 20 on Redmine's
+    # `lib/generators/redmine_plugin_model/templates/migration.rb`),
+    # all of them noise from the user's perspective. The runner / worker
+    # consults this detector before turning parse errors into
+    # diagnostics; an ERB-shaped source is silently skipped.
+    #
+    # Detection is byte-level on the raw source: any occurrence of the
+    # `%>` closing marker proves the file is an ERB template. `%>`
+    # cannot appear in valid Ruby — `%` is a binary operator that
+    # requires an operand on its right side, never `>`. The opening
+    # `<%` is ambiguous in principle (`x<%y` parses as `x < %y`, a
+    # comparison against a `%`-literal) but a real Ruby file with that
+    # shape would still not contain the closing `%>`.
+    module ErbTemplateDetector
+      ERB_CLOSING_MARKER = /%>/
+
+      module_function
+
+      # @param parse_result [Prism::ParseResult]
+      # @return [Boolean] true when the parsed source looks like an
+      #   ERB template (parse errors expected; analysis should skip).
+      def template?(parse_result)
+        source = parse_result.source.source
+        return false unless source.is_a?(String) && !source.empty?
+
+        ERB_CLOSING_MARKER.match?(source)
+      end
+    end
+  end
+end

data/lib/rigor/analysis/runner.rb

@@ -20,6 +20,7 @@ require_relative "buffer_binding"
 require_relative "check_rules"
 require_relative "dependency_source_inference"
 require_relative "diagnostic"
+require_relative "erb_template_detector"
 require_relative "project_scan"
 require_relative "result"
 require_relative "run_stats"
@@ -1457,7 +1458,11 @@ module Rigor
 
       def analyze_file(path, environment) # rubocop:disable Metrics/MethodLength
         parse_result = parse_source(path)
-        return parse_diagnostics(path, parse_result) unless parse_result.errors.empty?
+        unless parse_result.errors.empty?
+          return [] if ErbTemplateDetector.template?(parse_result)
+
+          return parse_diagnostics(path, parse_result)
+        end
 
         scope = seed_project_scope(Scope.empty(environment: environment, source_path: path))
         index = Inference::ScopeIndexer.index(parse_result.value, default_scope: scope)

data/lib/rigor/analysis/worker_session.rb

@@ -15,6 +15,7 @@ require_relative "../inference/method_dispatcher/file_folding"
 require_relative "check_rules"
 require_relative "dependency_source_inference"
 require_relative "diagnostic"
+require_relative "erb_template_detector"
 
 module Rigor
   module Analysis
@@ -158,7 +159,11 @@ module Rigor
       # is a per-run aggregate concern handled by the caller.
       def analyze(path)
         parse_result = parse_source(path)
-        return parse_diagnostics(path, parse_result) unless parse_result.errors.empty?
+        unless parse_result.errors.empty?
+          return [] if ErbTemplateDetector.template?(parse_result)
+
+          return parse_diagnostics(path, parse_result)
+        end
 
         scope = Scope.empty(environment: @environment, source_path: path)
         index = Inference::ScopeIndexer.index(parse_result.value, default_scope: scope)

data/lib/rigor/cli/plugins_command.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+require_relative "../configuration"
+require_relative "../plugin"
+require_relative "../plugin/loader"
+require_relative "../plugin/services"
+require_relative "../reflection"
+require_relative "../type/combinator"
+require_relative "plugins_renderer"
+
+module Rigor
+  class CLI
+    # `rigor plugins` — reports the activation status of every
+    # plugin entry in `.rigor.yml` so users (and the
+    # `rigor-project-init` SKILL, CI gates, `rigor init`) can
+    # verify their plugin configuration is actually doing what
+    # they think.
+    #
+    # The command is read-only and idempotent: it loads the
+    # project's `.rigor.yml` (same discovery as `rigor check`),
+    # runs `Plugin::Loader.load` to attempt instantiation, then
+    # prints a table of:
+    #
+    # - load status (`loaded` / `load-error` with reason);
+    # - resolved manifest id, version, description;
+    # - `signature_paths:` (absolute paths + per-dir `.rbs` count);
+    # - every manifest-declared extension surface
+    #   (`open_receivers:` / `owns_receivers:` / `produces:` /
+    #   `consumes:` / `block_as_methods:` / `heredoc_templates:` /
+    #   `trait_registries:` / `external_files:` /
+    #   `type_node_resolvers:` / `hkt_registrations:` /
+    #   `hkt_definitions:` / `protocol_contracts:` /
+    #   `source_rbs_synthesizer:`).
+    #
+    # Output formats: `text` (default, human-readable table) and
+    # `json` (for tooling — SKILLs, CI gates, editor integrations).
+    #
+    # Exit codes:
+    # - `0` — every configured plugin loaded.
+    # - `1` — at least one plugin failed to load AND `--strict`
+    #   was passed. Without `--strict` the command always exits 0;
+    #   load errors are reported but not treated as a gate failure
+    #   (matching `rigor triage`'s advisory shape).
+    #
+    # Future expansion (not in this slice):
+    # - Per-plugin diagnostic counts (would require running the
+    #   full analysis pipeline; out of scope for an inspection
+    #   command).
+    # - Verification that `signature_paths` actually merged into
+    #   the RBS environment without conflict (requires constructing
+    #   the Environment, which is heavier than the loader-only
+    #   pass this slice does).
+    class PluginsCommand
+      USAGE = "Usage: rigor plugins [options]"
+
+      def initialize(argv:, out: $stdout, err: $stderr)
+        @argv = argv
+        @out = out
+        @err = err
+      end
+
+      # @return [Integer] CLI exit status.
+      def run
+        options = parse_options
+        config_path = options.fetch(:config) || Configuration.discover
+        configuration = Configuration.load(options.fetch(:config))
+        rows = build_rows(configuration)
+
+        renderer = PluginsRenderer.new(rows: rows, configuration_path: config_path)
+        @out.puts(options.fetch(:format) == "json" ? renderer.json : renderer.text)
+
+        any_load_errors = rows.any? { |row| row.fetch(:status) == :load_error }
+        return 1 if any_load_errors && options.fetch(:strict)
+
+        0
+      end
+
+      private
+
+      def parse_options
+        options = { config: nil, format: "text", strict: false }
+        OptionParser.new do |opts|
+          opts.banner = USAGE
+          opts.on("--config=PATH", "Path to the Rigor configuration file") { |v| options[:config] = v }
+          opts.on("--format=FORMAT", "Output format: text (default) or json") { |v| options[:format] = v }
+          opts.on("--strict", "Exit 1 if any plugin failed to load (CI gate)") { options[:strict] = true }
+        end.parse!(@argv)
+        validate!(options)
+        options
+      end
+
+      def validate!(options)
+        return if %w[text json].include?(options.fetch(:format))
+
+        raise OptionParser::InvalidArgument, "unsupported format: #{options.fetch(:format)}"
+      end
+
+      # Runs the plugin loader against the project configuration
+      # and returns a row per declared plugin entry. Each row is
+      # a plain Hash with the fields enumerated in the class
+      # docstring so the renderer (text + JSON) reads from a
+      # single shape.
+      #
+      # The loader catches require / init failures and surfaces
+      # them through `registry.load_errors`; we merge those back
+      # into the per-entry rows by matching on `plugin_ref`.
+      def build_rows(configuration)
+        services = build_services(configuration)
+        registry = Plugin::Loader.load(configuration: configuration, services: services)
+
+        rows = configuration.plugins.map { |entry| row_for_entry(entry, registry) }
+        # Surface registry-level errors that did not bind to an
+        # entry (e.g. dependency-cycle errors that name multiple
+        # plugins). The renderer treats these as "orphan" errors.
+        orphan_errors = orphan_load_errors(registry, rows)
+        rows + orphan_errors
+      end
+
+      def build_services(configuration)
+        Plugin::Services.new(
+          reflection: Reflection,
+          type: Type::Combinator,
+          configuration: configuration,
+          cache_store: nil
+        )
+      end
+
+      def row_for_entry(entry, registry)
+        gem_name = entry_gem_name(entry)
+        config = entry_config(entry)
+        plugin = registry.plugins.find do |p|
+          # The loader has already matched the entry to a plugin
+          # class; we can identify it by either the gem name (when
+          # the entry was a String) or the explicit id (when the
+          # entry was a Hash with `id:`).
+          plugin_matches_entry?(p, gem_name, entry_id(entry))
+        end
+
+        if plugin
+          loaded_row(plugin, gem_name, config)
+        else
+          # Find the load error whose plugin_ref names this entry
+          # (the ref is set by Loader to the gem name on require
+          # failures and to the manifest id on later failures).
+          error = registry.load_errors.find do |e|
+            ref = e.plugin_ref.to_s
+            ref == gem_name || ref == entry_id(entry).to_s
+          end
+          load_error_row(gem_name, entry_id(entry), config, error)
+        end
+      end
+
+      def plugin_matches_entry?(plugin, gem_name, entry_id)
+        return true if entry_id && plugin.manifest.id == entry_id
+
+        # A bare gem entry conventionally has manifest.id equal to
+        # the gem name with the `rigor-` prefix stripped.
+        derived_id = gem_name.delete_prefix("rigor-")
+        [derived_id, gem_name].include?(plugin.manifest.id)
+      end
+
+      def loaded_row(plugin, gem_name, config)
+        manifest = plugin.manifest
+        identity_fields(gem_name, manifest, config)
+          .merge(extension_fields(plugin, manifest))
+          .merge(load_error: nil)
+      end
+
+      def identity_fields(gem_name, manifest, config)
+        {
+          gem: gem_name,
+          status: :loaded,
+          id: manifest.id,
+          version: manifest.version,
+          description: manifest.description,
+          config: config
+        }
+      end
+
+      def extension_fields(plugin, manifest)
+        {
+          signature_paths: signature_path_rows(plugin),
+          open_receivers: manifest.open_receivers.dup,
+          owns_receivers: manifest.owns_receivers.dup,
+          produces: manifest.produces.map(&:to_s),
+          consumes: manifest.consumes.map { |c| "#{c.plugin_id}/#{c.name}#{'?' if c.optional}" },
+          source_rbs_synthesizer: !manifest.source_rbs_synthesizer.nil?
+        }.merge(extension_count_fields(manifest))
+      end
+
+      def extension_count_fields(manifest)
+        {
+          block_as_methods: manifest.block_as_methods.size,
+          heredoc_templates: manifest.heredoc_templates.size,
+          trait_registries: manifest.trait_registries.size,
+          external_files: manifest.external_files.size,
+          type_node_resolvers: manifest.type_node_resolvers.size,
+          hkt_registrations: manifest.hkt_registrations.size,
+          hkt_definitions: manifest.hkt_definitions.size,
+          protocol_contracts: manifest.protocol_contracts.size
+        }
+      end
+
+      def load_error_row(gem_name, entry_id, config, error)
+        {
+          gem: gem_name,
+          status: :load_error,
+          id: entry_id,
+          version: nil,
+          description: nil,
+          config: config,
+          signature_paths: [],
+          open_receivers: [],
+          owns_receivers: [],
+          produces: [],
+          consumes: [],
+          block_as_methods: 0,
+          heredoc_templates: 0,
+          trait_registries: 0,
+          external_files: 0,
+          type_node_resolvers: 0,
+          hkt_registrations: 0,
+          hkt_definitions: 0,
+          protocol_contracts: 0,
+          source_rbs_synthesizer: false,
+          load_error: error&.message || "plugin did not register or could not be matched to a registered class"
+        }
+      end
+
+      # For each `signature_paths:` directory the plugin resolves
+      # against its gem root, report the absolute path and a
+      # quick `.rbs`-file count. The count is a sanity signal:
+      # an empty bundle directory loads silently today but
+      # contributes nothing.
+      def signature_path_rows(plugin)
+        plugin.signature_paths.map do |abs|
+          {
+            path: abs,
+            exists: File.directory?(abs),
+            rbs_files: rbs_file_count(abs)
+          }
+        end
+      end
+
+      def rbs_file_count(dir)
+        return 0 unless File.directory?(dir)
+
+        Dir.glob(File.join(dir, "**", "*.rbs")).size
+      end
+
+      def entry_gem_name(entry)
+        case entry
+        when String then entry
+        when Hash
+          string_keyed = entry.to_h { |k, v| [k.to_s, v] }
+          (string_keyed["gem"] || string_keyed["id"]).to_s
+        else entry.to_s
+        end
+      end
+
+      def entry_id(entry)
+        case entry
+        when Hash
+          string_keyed = entry.to_h { |k, v| [k.to_s, v] }
+          string_keyed["id"]
+        end
+      end
+
+      def entry_config(entry)
+        case entry
+        when Hash
+          string_keyed = entry.to_h { |k, v| [k.to_s, v] }
+          string_keyed["config"] || {}
+        else {}
+        end
+      end
+
+      # Build orphan-error rows for load errors whose `plugin_ref`
+      # did not bind to any configured plugin entry (e.g. a
+      # dependency-cycle naming a plugin we already accounted for
+      # but reported alongside another). De-duplicates against
+      # errors we already attached.
+      def orphan_load_errors(registry, rows)
+        attached_refs = rows.compact.flat_map { |row| [row[:gem], row[:id]].compact }.to_set
+        unattached = registry.load_errors.reject { |error| attached_refs.include?(error.plugin_ref.to_s) }
+        unattached.map do |error|
+          {
+            gem: error.plugin_ref.to_s,
+            status: :load_error,
+            id: nil,
+            version: nil,
+            description: nil,
+            config: {},
+            signature_paths: [],
+            open_receivers: [], owns_receivers: [], produces: [], consumes: [],
+            block_as_methods: 0, heredoc_templates: 0, trait_registries: 0,
+            external_files: 0, type_node_resolvers: 0,
+            hkt_registrations: 0, hkt_definitions: 0,
+            protocol_contracts: 0, source_rbs_synthesizer: false,
+            load_error: error.message
+          }
+        end
+      end
+    end
+  end
+end

data/lib/rigor/cli/plugins_renderer.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Rigor
+  class CLI
+    # Renderer for `rigor plugins`. Produces a human-readable
+    # text table and a JSON representation from the same row
+    # shape (the Hash documented on
+    # {Rigor::CLI::PluginsCommand#loaded_row}).
+    #
+    # The two formats carry the same content; JSON is meant for
+    # tooling (SKILLs, CI, editor integrations) while text is
+    # for interactive inspection. Rows are printed in the order
+    # the loader resolved them.
+    class PluginsRenderer
+      def initialize(rows:, configuration_path:)
+        @rows = rows
+        @configuration_path = configuration_path
+      end
+
+      def text
+        lines = []
+        lines << header
+        lines << ""
+        @rows.each_with_index do |row, index|
+          lines.concat(row_lines(row))
+          lines << "" unless index == @rows.size - 1
+        end
+        lines << ""
+        lines << footer
+        lines.join("\n")
+      end
+
+      def json
+        JSON.pretty_generate(
+          {
+            "configuration" => @configuration_path,
+            "plugins" => @rows.map { |row| row_json(row) },
+            "summary" => summary
+          }
+        )
+      end
+
+      private
+
+      def header
+        loaded = @rows.count { |r| r[:status] == :loaded }
+        errored = @rows.count { |r| r[:status] == :load_error }
+        config = @configuration_path || "(no .rigor.yml found; using defaults)"
+        "Plugin activation report\n  " \
+          "configuration: #{config}\n  " \
+          "loaded: #{loaded}    load-error: #{errored}"
+      end
+
+      def footer
+        errored = @rows.select { |r| r[:status] == :load_error }
+        if errored.empty?
+          "All configured plugins loaded successfully."
+        else
+          "#{errored.size} plugin(s) failed to load — see above. " \
+            "Run with --strict to make this a CI gate."
+        end
+      end
+
+      def row_lines(row)
+        marker = row[:status] == :loaded ? "OK " : "ERR"
+        head = if row[:status] == :loaded
+                 "  [#{marker}] #{row[:id]}  v#{row[:version]}  (#{row[:gem]})"
+               else
+                 "  [#{marker}] #{row[:gem]}"
+               end
+        lines = [head]
+        lines << "        #{row[:description]}" if row[:description]
+
+        if row[:status] == :load_error
+          lines << "        load error: #{row[:load_error]}"
+          lines << "        config: #{row[:config].inspect}" if row[:config] && !row[:config].empty?
+          return lines
+        end
+
+        lines.concat(loaded_detail_lines(row))
+        lines
+      end
+
+      def loaded_detail_lines(row)
+        lines = []
+        lines.concat(signature_paths_lines(row[:signature_paths])) if row[:signature_paths].any?
+        lines.concat(receiver_and_fact_lines(row))
+        lines.concat(macro_substrate_lines(row))
+        lines.concat(extra_surface_lines(row))
+        lines << "        config: #{row[:config].inspect}" if row[:config] && !row[:config].empty?
+        lines
+      end
+
+      def receiver_and_fact_lines(row)
+        lines = []
+        lines << "        open_receivers: #{row[:open_receivers].join(', ')}" if row[:open_receivers].any?
+        lines << "        owns_receivers: #{row[:owns_receivers].join(', ')}" if row[:owns_receivers].any?
+        lines << "        produces: #{row[:produces].join(', ')}" if row[:produces].any?
+        lines << "        consumes: #{row[:consumes].join(', ')}" if row[:consumes].any?
+        lines
+      end
+
+      def extra_surface_lines(row)
+        lines = []
+        lines << "        protocol_contracts: #{row[:protocol_contracts]}" if row[:protocol_contracts].positive?
+        lines << "        source_rbs_synthesizer: yes" if row[:source_rbs_synthesizer]
+        lines << "        type_node_resolvers: #{row[:type_node_resolvers]}" if row[:type_node_resolvers].positive?
+        if row[:hkt_registrations].positive? || row[:hkt_definitions].positive?
+          lines << "        hkt: #{row[:hkt_registrations]} registration(s), #{row[:hkt_definitions]} definition(s)"
+        end
+        lines
+      end
+
+      def signature_paths_lines(paths)
+        lines = ["        signature_paths:"]
+        paths.each do |entry|
+          marker = entry[:exists] ? "" : " (MISSING)"
+          lines << "          #{entry[:path]}  (#{entry[:rbs_files]} .rbs file(s))#{marker}"
+        end
+        lines
+      end
+
+      def macro_substrate_lines(row)
+        parts = []
+        parts << "block_as_methods=#{row[:block_as_methods]}" if row[:block_as_methods].positive?
+        parts << "heredoc_templates=#{row[:heredoc_templates]}" if row[:heredoc_templates].positive?
+        parts << "trait_registries=#{row[:trait_registries]}" if row[:trait_registries].positive?
+        parts << "external_files=#{row[:external_files]}" if row[:external_files].positive?
+        return [] if parts.empty?
+
+        ["        macro substrate: #{parts.join(', ')}"]
+      end
+
+      def row_json(row)
+        {
+          "gem" => row[:gem],
+          "status" => row[:status].to_s,
+          "id" => row[:id],
+          "version" => row[:version],
+          "description" => row[:description],
+          "config" => row[:config],
+          "signature_paths" => row[:signature_paths].map do |sp|
+            { "path" => sp[:path], "exists" => sp[:exists], "rbs_files" => sp[:rbs_files] }
+          end,
+          "open_receivers" => row[:open_receivers],
+          "owns_receivers" => row[:owns_receivers],
+          "produces" => row[:produces],
+          "consumes" => row[:consumes],
+          "block_as_methods" => row[:block_as_methods],
+          "heredoc_templates" => row[:heredoc_templates],
+          "trait_registries" => row[:trait_registries],
+          "external_files" => row[:external_files],
+          "type_node_resolvers" => row[:type_node_resolvers],
+          "hkt_registrations" => row[:hkt_registrations],
+          "hkt_definitions" => row[:hkt_definitions],
+          "protocol_contracts" => row[:protocol_contracts],
+          "source_rbs_synthesizer" => row[:source_rbs_synthesizer],
+          "load_error" => row[:load_error]
+        }
+      end
+
+      def summary
+        {
+          "total" => @rows.size,
+          "loaded" => @rows.count { |r| r[:status] == :loaded },
+          "load_error" => @rows.count { |r| r[:status] == :load_error }
+        }
+      end
+    end
+  end
+end

data/lib/rigor/cli.rb

@@ -32,6 +32,7 @@ module Rigor
       "baseline" => :run_baseline,
       "triage" => :run_triage,
       "coverage" => :run_coverage,
+      "plugins" => :run_plugins,
       "playground" => :run_playground
     }.freeze
 
@@ -475,9 +476,29 @@ module Rigor
 
       File.write(path, init_template)
       @out.puts("Created #{path}")
+      print_init_next_steps(path)
       0
     end
 
+    # `rigor init`'s template ships empty `plugins:` so a fresh
+    # init has nothing to validate — but the moment the user adds
+    # any plugin entry, the activation-failure surfaces enumerated
+    # in `rigor plugins`'s docstring become real. Point them at
+    # the verification command + the canonical readiness flow so
+    # silent failures (the cwd / Gemfile / signature_paths
+    # mismatches that surfaced during the Mastodon trial) get
+    # caught the first time the user wires a plugin, not the first
+    # time `rigor check` reports false positives that should have
+    # been covered.
+    def print_init_next_steps(path)
+      @out.puts ""
+      @out.puts "Next steps:"
+      @out.puts "  1. Edit #{path} — add the `plugins:` your project needs."
+      @out.puts "  2. Run `rigor plugins` to verify every configured plugin loads."
+      @out.puts "     (`--strict` exits 1 on failure; ideal CI gate.)"
+      @out.puts "  3. Run `rigor check` to analyse your code."
+    end
+
     # Renders the starter `.rigor.yml` body. The template
     # serialises `Configuration::DEFAULTS` (so the on-disk file
     # round-trips through `Configuration.load`) and prepends a
@@ -597,6 +618,12 @@ module Rigor
       CLI::CoverageCommand.new(argv: @argv, out: @out, err: @err).run
     end
 
+    def run_plugins
+      require_relative "cli/plugins_command"
+
+      CLI::PluginsCommand.new(argv: @argv, out: @out, err: @err).run
+    end
+
     def run_playground
       begin
         require "rigor/playground"
@@ -653,6 +680,7 @@ module Rigor
           mcp        Run the Rigor MCP server over stdio (ADR-33)
           triage     Summarise diagnostics: distribution, hotspots, hints (ADR-23)
           coverage   Report type-precision coverage (precise vs Dynamic ratio)
+          plugins    Report activation status of every configured plugin
           playground Start the browser playground (requires rigor-playground gem)
           version    Print the Rigor version
           help       Print this help

data/lib/rigor/inference/block_parameter_binder.rb

@@ -106,6 +106,8 @@ module Rigor
         params_node = params_root.parameters
         return {} if params_node.nil?
 
+        apply_auto_splat(params_node)
+
         bindings = {}
         bind_positionals(params_node, bindings, 0)
         bind_rest(params_node, bindings)
@@ -115,6 +117,39 @@ module Rigor
         bindings
       end
 
+      # Ruby blocks (NOT lambdas) auto-splat a single yielded
+      # Tuple-shaped value when the block declares more than one
+      # required positional parameter:
+      #
+      #   { a: 1 }.each { |k, v| ... }
+      #
+      # yields `[key, value]` as a single arg, but the two-param
+      # block sees `k = key, v = value`. RBS / IteratorDispatch
+      # encode this as the block taking ONE `[K, V]` Tuple
+      # parameter; without this fix-up the binder would assign
+      # `k = Tuple[K, V]` and `v = Dynamic[Top]`, and any call
+      # on `k.<method-not-on-Tuple>` would false-fire.
+      #
+      # The rule fires only when (a) the receiver yields exactly
+      # one value (`expected_param_types.size == 1`), (b) the
+      # block declares more than one positional slot, and (c)
+      # that single expected element is a Tuple. Multi-arg yields
+      # (e.g. `each_with_index`'s `(element, index)` pair) are
+      # NOT auto-splatted — matching Ruby semantics where a
+      # multi-arg yield to a `|a, b, c|` block fills the extra
+      # slot with nil rather than splatting any element.
+      def apply_auto_splat(params_node)
+        return unless @expected_param_types.size == 1
+
+        pos_count = params_node.requireds.size + params_node.optionals.size + params_node.posts.size
+        return unless pos_count > 1
+
+        first = @expected_param_types[0]
+        return unless first.is_a?(Type::Tuple)
+
+        @expected_param_types = first.elements
+      end
+
       def bind_positionals(params_node, bindings, cursor)
         cursor = bind_required_positionals(params_node, bindings, cursor)
         cursor = bind_optional_positionals(params_node, bindings, cursor)