[rubocop#9760] Deprecate range kwarg in range_with_surrounding_space

changelog/change_range_help_range_with_surrounding_space_to_warn_on_kwarg_range.md

@@ -0,0 +1 @@
+* [#9760](https://github.com/rubocop/rubocop/issues/9760): (Deprecation) Change RangeHelp#range_with_surrounding_space to output a deprecation warning when passing the range as a kwarg. ([@pirj][])

lib/rubocop/cop/mixin/range_help.rb

@@ -51,9 +51,18 @@ def range_with_surrounding_comma(range, side = :both)
         Parser::Source::Range.new(buffer, begin_pos, end_pos)
       end
 
-      def range_with_surrounding_space(range:, side: :both,
-                                       newlines: true, whitespace: false,
-                                       continuations: false)
+      NOT_GIVEN = Module.new
+      def range_with_surrounding_space(range_positional = NOT_GIVEN, # rubocop:disable Metrics/ParameterLists
+                                       range: NOT_GIVEN, side: :both, newlines: true,
+                                       whitespace: false, continuations: false)
+        unless range == NOT_GIVEN
+          warn <<~WARNING
+            Passing `range` as a keyword argument is deprecated, and will be removed in RuboCop 2.0. Pass the range as the first positional argument instead.
+          WARNING
+        end
+
+        range = range_positional unless range_positional == NOT_GIVEN
+
         buffer = @processed_source.buffer
         src = buffer.source
 

spec/rubocop/cop/range_help_spec.rb

@@ -35,33 +35,65 @@
   end
 
   describe 'source indicated by #range_with_surrounding_space' do
-    subject do
-      obj = TestRangeHelp.new
-      obj.instance_exec(processed_source) { |src| @processed_source = src }
-      r = obj.send(:range_with_surrounding_space, range: input_range, side: side)
-      processed_source.buffer.source[r.begin_pos...r.end_pos]
-    end
-
     let(:source) { 'f {  a(2) }' }
     let(:processed_source) { parse_source(source) }
     let(:input_range) { Parser::Source::Range.new(processed_source.buffer, 5, 9) }
+    let(:obj) { TestRangeHelp.new }
 
-    context 'when side is :both' do
-      let(:side) { :both }
+    before do
+      obj.instance_exec(processed_source) { |src| @processed_source = src }
+    end
+
+    shared_examples 'works with various `side`s' do
+      context 'when side is :both' do
+        let(:side) { :both }
+
+        it { is_expected.to eq('  a(2) ') }
+      end
+
+      context 'when side is :left' do
+        let(:side) { :left }
 
-      it { is_expected.to eq('  a(2) ') }
+        it { is_expected.to eq('  a(2)') }
+      end
+
+      context 'when side is :right' do
+        let(:side) { :right }
+
+        it { is_expected.to eq('a(2) ') }
+      end
     end
 
-    context 'when side is :left' do
-      let(:side) { :left }
+    context 'when passing range as a kwarg' do
+      subject do
+        r = obj.send(:range_with_surrounding_space, range: input_range, side: side)
+        processed_source.buffer.source[r.begin_pos...r.end_pos]
+      end
 
-      it { is_expected.to eq('  a(2)') }
+      it 'outputs a deprecation message' do
+        expect { obj.__send__(:range_with_surrounding_space, range: input_range) }
+          .to output(/Passing `range` as a keyword argument is deprecated/).to_stderr
+      end
+
+      it_behaves_like 'works with various `side`s' do
+        require 'rspec/support/spec/with_isolated_stderr'
+        include RSpec::Support::WithIsolatedStdErr
+
+        around do |example|
+          with_isolated_stderr do
+            example.run
+          end
+        end
+      end
     end
 
-    context 'when side is :right' do
-      let(:side) { :right }
+    context 'when `range` is passed as a positional argument' do
+      subject do
+        r = obj.send(:range_with_surrounding_space, input_range, side: side)
+        processed_source.buffer.source[r.begin_pos...r.end_pos]
+      end
 
-      it { is_expected.to eq('a(2) ') }
+      it_behaves_like 'works with various `side`s'
     end
   end