rubocop-prefer_it_parameter 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5cc86f9725bb1e055df24642820dd33b8f6783b9a8b493f9ee4b8fbb74672107
-  data.tar.gz: d6baada0d759d55b85a28966463ebb479d4db86aeaebe4cd09ea5bfeca4b9310
+  metadata.gz: a654f707a32decb9fe04e213f80d731587b30ca23daa159fabcf6b34d7ce1b9c
+  data.tar.gz: d3e5ba34a8f33a1d1064d1f2f7c7d0d276b90e94b01fff3ef35bcd433f695c99
 SHA512:
-  metadata.gz: d5828d52ff9ecf241a7c27f8b623ce4b7c479492c96c0600c992bb39eb5620a9b65c2a6914d1bf4aeaae0451295a4961a1105bc5af8c1f05f2a731b51e30970b
-  data.tar.gz: afd728b9c7367f1e4af45a695169fa3fd07fb1b52ca6ab855c56af99e09bacc312f1074458ba580befa36a8b769e5a170badf166ba0763ddd41538974825cf40
+  metadata.gz: b35242ffe25304f9790f90d9ad875529d07c0522ef9bf8d82ea3ff76d815eeb2cd864ab0e06a8bd0a8a821d255deb60b9df74e776b7b2342ba4b0be654306efa
+  data.tar.gz: 70af29593bdb22415d82812c08323d353e8c14d1447ea4c3d2c31f5715288e3dfd1c1eee72be7caccd8679fd7a3f2bcfe55cb144b48f70ad0dff10d41c71ab96

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
+## [1.1.0] - 2026-09-07
+
+- `Style/PreferItParameter`: recognize RSpec's custom matcher DSL (`RSpec::Matchers.define`)
+  as a built-in exception, alongside `lambda`/`proc`/`Proc.new`/`define_method`/
+  `define_singleton_method`; these are always checked and cannot be disabled.
+- `Style/PreferItParameter`: add the `IgnoredBlockContexts` config option, so a project
+  can name its own such unsafe blocks on top of the built-ins above. As part of this,
+  the built-in `Proc.new` check now matches by exact receiver source text rather than
+  resolved constant name, so a `Proc` reached through another namespace is no longer
+  recognized.
+
 ## [1.0.0] - 2026-08-05
 
 Initial release.

data/README.md

@@ -70,6 +70,47 @@ A block is left alone when it:
 - references a local variable named `it` from an enclosing scope, or assigns to `it`
 - already names its argument `it` — dropping it would revive an `it` from an enclosing scope (`Style/ItAssignment` forbids the name instead)
 - defines a callable or a method — `->(x) { }`, `lambda`, `proc`, `Proc.new`, `define_method`, `define_singleton_method` — since the parameter list is part of its API and `it` drops the parameter name
+- is nested inside RSpec's custom matcher DSL (`RSpec::Matchers.define`) as `match`, `match_when_negated`, `match_unless_raises`, `chain`, `failure_message`, `failure_message_when_negated` or `description` — these blocks are turned into actual methods internally, where `it`'s implicit binding does not reliably survive (see below)
+- matches a project-specific entry in `IgnoredBlockContexts` (see below)
+
+The `Proc.new`/`lambda`/etc. and RSpec cases above are built into the cop and always checked — they cannot be turned off. `IgnoredBlockContexts` is how a project adds its own such cases on top of them.
+
+#### `IgnoredBlockContexts`
+
+A block can be unsafe to convert for reasons specific to how it's used, not just because of what method it's passed to — this is exactly why RSpec's matcher DSL and `Proc.new` are already built-in exceptions above. `IgnoredBlockContexts` lets a project name its *own* such cases the same way, each scoped to the call it's nested inside (or, for `Proc.new`-like cases, matched wherever it's called), so a generic method name doesn't suppress the check on unrelated code.
+
+```ruby
+# bad
+RSpec::Matchers.define :be_valid_foo do
+  match { it.is_a?(Foo) && it.valid? }
+end
+
+# good
+RSpec::Matchers.define :be_valid_foo do
+  match { |actual| actual.is_a?(Foo) && actual.valid? }
+end
+```
+
+`IgnoredBlockContexts` is empty by default. The built-in cases above are not stored in this config option at all — they're checked independently — so setting `IgnoredBlockContexts` in your `.rubocop.yml` only *adds* entries; it can never disable a built-in case:
+
+```yaml
+Style/PreferItParameter:
+  IgnoredBlockContexts:
+    OurDsl.define_matcher:
+      - our_custom_dsl_method
+```
+
+A block named this way is only ignored when it's nested inside the matching enclosing call — so `our_custom_dsl_method { |x| x.foo }` written anywhere else is unaffected and still converted, even though the method name is the same. This is what keeps a generic name from silently suppressing the check on unrelated code.
+
+An enclosing call written without a receiver (`define_matcher:` instead of `OurDsl.define_matcher:`) only matches a bare call with no receiver at all. Write `*.define_matcher:` to match regardless of receiver instead — the same way `lambda` or `define_method` are matched in the exceptions list above. A value of `nil` (an entry with nothing under it) means the call itself is unsafe wherever it appears, with no nesting required — this is how the built-in `Proc.new` case works internally:
+
+```yaml
+Style/PreferItParameter:
+  IgnoredBlockContexts:
+    "*.our_dsl_method":  # any receiver, no nesting required
+    OurDsl.define_matcher:  # this exact receiver, blocks nested inside it
+      - our_custom_dsl_method
+```
 
 ## Related cops
 
@@ -105,6 +146,7 @@ The autocorrection is marked unsafe (`SafeAutoCorrect: false`), so `rubocop -a`
 - A local variable or parameter named `it` takes precedence over the block parameter. The cop skips a block that references such a variable, but it cannot detect one that the block never references — there the autocorrection silently changes what the block sees. Enabling `Style/ItAssignment` is therefore a prerequisite.
 - `Proc#parameters` loses the argument name: `[[:opt, :x]]` becomes `[[:opt]]`. Blocks that define a callable or a method are excluded for this reason, but a block captured with `&block` and introspected elsewhere is still affected.
 - `binding.local_variable_get(:x)` inside the block stops working.
+- A block can be unsafe to convert for reasons specific to its own context — e.g. a library that turns it into an actual method internally may stop passing it an argument at all. RSpec's custom matcher DSL is built in for this reason (see [Exceptions](#exceptions)); [`IgnoredBlockContexts`](#ignoredblockcontexts) lets a project name the same kind of case for a library this cop doesn't know about.
 
 ## Requirements
 

data/config/default.yml

@@ -4,3 +4,4 @@ Style/PreferItParameter:
   Enabled: true
   SafeAutoCorrect: false
   VersionAdded: '1.0'
+  IgnoredBlockContexts: {}

data/lib/rubocop/cop/style/prefer_it_parameter.rb

@@ -15,9 +15,19 @@ module RuboCop
       #   change what the block sees. Enabling `Style/ItAssignment` rules such names
       #   out. Additionally, `it` drops the argument name from `Proc#parameters`
       #   (`[[:opt, :x]]` becomes `[[:opt]]`) and breaks
-      #   `binding.local_variable_get(:x)` inside the block. Blocks that define a
-      #   callable or a method are skipped for that reason, but a block captured with
-      #   `&block` and introspected elsewhere is still affected.
+      #   `binding.local_variable_get(:x)` inside the block. A block captured with
+      #   `&block` and introspected elsewhere is still affected even when none of
+      #   the below applies.
+      #
+      #   Some blocks are unsafe to convert for reasons this cop cannot see from the
+      #   AST alone — `->(x) { }`, `lambda`, `proc`, `Proc.new`, `define_method` and
+      #   `define_singleton_method` all define a callable or a method, where the
+      #   parameter list is part of its API and `it` drops the parameter name; RSpec's
+      #   custom matcher DSL turns `match`, `chain` and similar blocks into actual
+      #   methods internally, where `it`'s implicit binding does not reliably survive.
+      #   These are all built in and cannot be turned off. `IgnoredBlockContexts` lets
+      #   a project add its own cases the same way, scoped to where they're nested so
+      #   a generic method name doesn't suppress the check on unrelated code.
       #
       # @example
       #   # bad
@@ -47,6 +57,11 @@ module RuboCop
       #   ->(x) { puts x }
       #   define_method(:m) { |x| x + 1 }
       #
+      #   # good - RSpec turns this block into a method internally, where `it` cannot be trusted
+      #   RSpec::Matchers.define :be_valid_foo do
+      #     match { |actual| actual.valid? }
+      #   end
+      #
       #   # bad
       #   items.map { |item| {item:} }
       #
@@ -64,7 +79,25 @@ module RuboCop
 
         INNER_BLOCK_TYPES = %i[block numblock itblock].freeze #: Array[Symbol]
 
-        CALLABLE_METHODS = %i[define_method define_singleton_method lambda proc].freeze #: Array[Symbol]
+        # Maps a call to the method names that are unsafe when nested inside it, in
+        # the same format as the `IgnoredBlockContexts` config option (see
+        # `matches_context?` for the exact matching rules). A `nil` value means the
+        # call itself is unsafe, wherever it appears, with no nesting required —
+        # `lambda`/`proc`/`define_method`/`define_singleton_method` match regardless
+        # of receiver (`*.`), `Proc.new` requires that exact receiver. These are core
+        # Ruby behavior and RSpec's widely-used matcher DSL, so unlike
+        # `IgnoredBlockContexts` they're built in and cannot be turned off.
+        BUILTIN_IGNORED_BLOCK_CONTEXTS = {
+          "*.lambda" => nil,
+          "*.proc" => nil,
+          "*.define_method" => nil,
+          "*.define_singleton_method" => nil,
+          "Proc.new" => nil,
+          "RSpec::Matchers.define" => %i[
+            match match_when_negated match_unless_raises chain
+            failure_message failure_message_when_negated description
+          ]
+        }.freeze #: Hash[String, Array[Symbol]?]
 
         # @rbs node: RuboCop::AST::BlockNode
         def on_block(node) #: void
@@ -86,7 +119,7 @@ module RuboCop
         # @rbs body: RuboCop::AST::Node
         def convertible_argument_name(node, body) #: Symbol?
           return unless node.single_line?
-          return if defines_callable?(node)
+          return if ignored?(node)
 
           name = sole_argument_name(node)
           return unless name
@@ -105,24 +138,90 @@ module RuboCop
           lvar_references(body, :it).any? || reassigned?(body, :it)
         end
 
-        # `it` drops the parameter name from `Proc#parameters`, which changes the
-        # meaning of a block that defines a callable object or a method: there the
-        # parameter list is part of the API, unlike a block passed to `each` or `map`.
+        # A block can be unsafe to convert for reasons specific to how it's used, not
+        # just because of what method it's passed to — see `BUILTIN_IGNORED_BLOCK_CONTEXTS`
+        # for the built-in cases and `matches_context?` for what a context means.
+        # `IgnoredBlockContexts` lets a project add its own cases the same way; it is
+        # checked separately from, and in addition to, the built-in ones, so a project
+        # can never accidentally disable those by overriding this config option.
         #
         # @rbs node: RuboCop::AST::BlockNode
-        def defines_callable?(node) #: bool
-          CALLABLE_METHODS.include?(node.method_name) || proc_new?(node)
+        def ignored?(node) #: bool
+          ignored_in?(node, BUILTIN_IGNORED_BLOCK_CONTEXTS) || ignored_in?(node, ignored_block_contexts)
         end
 
         # @rbs node: RuboCop::AST::BlockNode
-        def proc_new?(node) #: bool
-          return false unless node.method?(:new)
+        # @rbs contexts: Hash[String, Array[Symbol]?]
+        def ignored_in?(node, contexts) #: bool
+          contexts.any? { |context, method_names| matches_context?(node, context, method_names) }
+        end
 
-          receiver = node.send_node.receiver
-          return false unless receiver&.const_type?
+        # @rbs @ignored_block_contexts: Hash[String, Array[Symbol]?]
 
-          const = receiver #: RuboCop::AST::ConstNode
-          const.short_name == :Proc
+        def ignored_block_contexts #: Hash[String, Array[Symbol]?]
+          default = {} #: Hash[String, Array[String]?]
+          @ignored_block_contexts ||= cop_config.fetch("IgnoredBlockContexts", default).transform_values do |names|
+            names&.map(&:to_sym)
+          end
+        end
+
+        # A `nil` (or empty) `method_names` means `context` describes the node's own
+        # call, checked with no nesting required — this is how `Proc.new` and the
+        # receiver-blind `*.lambda`-style entries work. Otherwise, `context` names an
+        # enclosing call the node must be nested inside, and `method_names` are the
+        # names that are unsafe within it — this is how RSpec's matcher DSL works.
+        #
+        # @rbs node: RuboCop::AST::BlockNode
+        # @rbs context: String
+        # @rbs method_names: Array[Symbol]?
+        def matches_context?(node, context, method_names) #: bool
+          if method_names.nil? || method_names.empty?
+            receiver_source, method_name = parse_context(context)
+            context_call?(node.send_node, receiver_source, method_name)
+          else
+            method_names.include?(node.method_name) && nested_in_context?(node, context)
+          end
+        end
+
+        # `numblock` and `itblock` (a `_1` or `it` block) are included since
+        # rubocop-ast maps both to `BlockNode`, so `#send_node` works the same as for
+        # a plain `block`.
+        #
+        # @rbs node: RuboCop::AST::BlockNode
+        # @rbs context: String
+        def nested_in_context?(node, context) #: bool
+          receiver_source, method_name = parse_context(context)
+          node.each_ancestor(*INNER_BLOCK_TYPES).any? do |ancestor|
+            block_ancestor = ancestor #: RuboCop::AST::BlockNode
+            context_call?(block_ancestor.send_node, receiver_source, method_name)
+          end
+        end
+
+        # @rbs context: String
+        def parse_context(context) #: [String, String]
+          receiver_source, _dot, method_name = context.rpartition(".")
+          [receiver_source, method_name]
+        end
+
+        # `receiver_source` of `"*"` matches any receiver, or none. An empty
+        # `receiver_source` (`context` had no `.`) requires no receiver at all.
+        # Otherwise the receiver's source must match exactly, modulo a leading `::`
+        # on either side — `::Proc` is not receiver-less, its source is `"::Proc"`
+        # (a `cbase`-prefixed const), so this is what lets `Proc.new` also match
+        # `::Proc.new`.
+        #
+        # @rbs send_node: RuboCop::AST::SendNode
+        # @rbs receiver_source: String
+        # @rbs method_name: String
+        def context_call?(send_node, receiver_source, method_name) #: bool
+          return false unless send_node.method?(method_name.to_sym)
+          return true if receiver_source == "*"
+          return send_node.receiver.nil? if receiver_source.empty?
+
+          actual_receiver_source = send_node.receiver&.source
+          return false unless actual_receiver_source
+
+          actual_receiver_source.delete_prefix("::") == receiver_source.delete_prefix("::")
         end
 
         # @rbs node: RuboCop::AST::BlockNode

data/lib/rubocop/prefer_it_parameter/version.rb

@@ -2,6 +2,6 @@
 
 module RuboCop
   module PreferItParameter
-    VERSION = "1.0.0"
+    VERSION = "1.1.0"
   end
 end

data/sig/rubocop/cop/style/prefer_it_parameter.rbs

@@ -15,9 +15,19 @@ module RuboCop
       #   change what the block sees. Enabling `Style/ItAssignment` rules such names
       #   out. Additionally, `it` drops the argument name from `Proc#parameters`
       #   (`[[:opt, :x]]` becomes `[[:opt]]`) and breaks
-      #   `binding.local_variable_get(:x)` inside the block. Blocks that define a
-      #   callable or a method are skipped for that reason, but a block captured with
-      #   `&block` and introspected elsewhere is still affected.
+      #   `binding.local_variable_get(:x)` inside the block. A block captured with
+      #   `&block` and introspected elsewhere is still affected even when none of
+      #   the below applies.
+      #
+      #   Some blocks are unsafe to convert for reasons this cop cannot see from the
+      #   AST alone — `->(x) { }`, `lambda`, `proc`, `Proc.new`, `define_method` and
+      #   `define_singleton_method` all define a callable or a method, where the
+      #   parameter list is part of its API and `it` drops the parameter name; RSpec's
+      #   custom matcher DSL turns `match`, `chain` and similar blocks into actual
+      #   methods internally, where `it`'s implicit binding does not reliably survive.
+      #   These are all built in and cannot be turned off. `IgnoredBlockContexts` lets
+      #   a project add its own cases the same way, scoped to where they're nested so
+      #   a generic method name doesn't suppress the check on unrelated code.
       #
       # @example
       #   # bad
@@ -47,6 +57,11 @@ module RuboCop
       #   ->(x) { puts x }
       #   define_method(:m) { |x| x + 1 }
       #
+      #   # good - RSpec turns this block into a method internally, where `it` cannot be trusted
+      #   RSpec::Matchers.define :be_valid_foo do
+      #     match { |actual| actual.valid? }
+      #   end
+      #
       #   # bad
       #   items.map { |item| {item:} }
       #
@@ -63,7 +78,15 @@ module RuboCop
 
         INNER_BLOCK_TYPES: Array[Symbol]
 
-        CALLABLE_METHODS: Array[Symbol]
+        # Maps a call to the method names that are unsafe when nested inside it, in
+        # the same format as the `IgnoredBlockContexts` config option (see
+        # `matches_context?` for the exact matching rules). A `nil` value means the
+        # call itself is unsafe, wherever it appears, with no nesting required —
+        # `lambda`/`proc`/`define_method`/`define_singleton_method` match regardless
+        # of receiver (`*.`), `Proc.new` requires that exact receiver. These are core
+        # Ruby behavior and RSpec's widely-used matcher DSL, so unlike
+        # `IgnoredBlockContexts` they're built in and cannot be turned off.
+        BUILTIN_IGNORED_BLOCK_CONTEXTS: Hash[String, Array[Symbol]?]
 
         # @rbs node: RuboCop::AST::BlockNode
         def on_block: (RuboCop::AST::BlockNode node) -> void
@@ -81,15 +104,57 @@ module RuboCop
         # @rbs body: RuboCop::AST::Node
         def shadows_it?: (RuboCop::AST::Node body) -> bool
 
-        # `it` drops the parameter name from `Proc#parameters`, which changes the
-        # meaning of a block that defines a callable object or a method: there the
-        # parameter list is part of the API, unlike a block passed to `each` or `map`.
+        # A block can be unsafe to convert for reasons specific to how it's used, not
+        # just because of what method it's passed to — see `BUILTIN_IGNORED_BLOCK_CONTEXTS`
+        # for the built-in cases and `matches_context?` for what a context means.
+        # `IgnoredBlockContexts` lets a project add its own cases the same way; it is
+        # checked separately from, and in addition to, the built-in ones, so a project
+        # can never accidentally disable those by overriding this config option.
+        #
+        # @rbs node: RuboCop::AST::BlockNode
+        def ignored?: (RuboCop::AST::BlockNode node) -> bool
+
+        # @rbs node: RuboCop::AST::BlockNode
+        # @rbs contexts: Hash[String, Array[Symbol]?]
+        def ignored_in?: (RuboCop::AST::BlockNode node, Hash[String, Array[Symbol]?] contexts) -> bool
+
+        @ignored_block_contexts: Hash[String, Array[Symbol]?]
+
+        def ignored_block_contexts: () -> Hash[String, Array[Symbol]?]
+
+        # A `nil` (or empty) `method_names` means `context` describes the node's own
+        # call, checked with no nesting required — this is how `Proc.new` and the
+        # receiver-blind `*.lambda`-style entries work. Otherwise, `context` names an
+        # enclosing call the node must be nested inside, and `method_names` are the
+        # names that are unsafe within it — this is how RSpec's matcher DSL works.
         #
         # @rbs node: RuboCop::AST::BlockNode
-        def defines_callable?: (RuboCop::AST::BlockNode node) -> bool
+        # @rbs context: String
+        # @rbs method_names: Array[Symbol]?
+        def matches_context?: (RuboCop::AST::BlockNode node, String context, Array[Symbol]? method_names) -> bool
 
+        # `numblock` and `itblock` (a `_1` or `it` block) are included since
+        # rubocop-ast maps both to `BlockNode`, so `#send_node` works the same as for
+        # a plain `block`.
+        #
         # @rbs node: RuboCop::AST::BlockNode
-        def proc_new?: (RuboCop::AST::BlockNode node) -> bool
+        # @rbs context: String
+        def nested_in_context?: (RuboCop::AST::BlockNode node, String context) -> bool
+
+        # @rbs context: String
+        def parse_context: (String context) -> [ String, String ]
+
+        # `receiver_source` of `"*"` matches any receiver, or none. An empty
+        # `receiver_source` (`context` had no `.`) requires no receiver at all.
+        # Otherwise the receiver's source must match exactly, modulo a leading `::`
+        # on either side — `::Proc` is not receiver-less, its source is `"::Proc"`
+        # (a `cbase`-prefixed const), so this is what lets `Proc.new` also match
+        # `::Proc.new`.
+        #
+        # @rbs send_node: RuboCop::AST::SendNode
+        # @rbs receiver_source: String
+        # @rbs method_name: String
+        def context_call?: (RuboCop::AST::SendNode send_node, String receiver_source, String method_name) -> bool
 
         # @rbs node: RuboCop::AST::BlockNode
         def sole_argument_name: (RuboCop::AST::BlockNode node) -> Symbol?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-prefer_it_parameter
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Takeshi KOMIYA