From b7d0877332c64a987df6ad9076f41e95cf0ae3a4 Mon Sep 17 00:00:00 2001
From: Dave Corson-Knowles <david.corsonknowles@gmail.com>
Date: Mon, 14 Oct 2024 15:46:15 -0700
Subject: [PATCH] Deprecate top_level_group? and test it in a Cop class

In this PR, we add a deprecation message for top_level_group?, which has no callers in current Rubocop/RSpec. The specs for this change complete line coverage for this repo.
---
 CHANGELOG.md                                  |  1 +
 .../cop/rspec/mixin/top_level_group.rb        |  6 +++++
 .../cop/rspec/mixin/top_level_group_spec.rb   | 24 +++++++++++++++++++
 3 files changed, 31 insertions(+)
 create mode 100644 spec/rubocop/cop/rspec/mixin/top_level_group_spec.rb

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b911f161d..783874b7f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,7 @@
 - Fix `RSpec/VoidExpect` to only operate inside an example block. ([@corsonknowles])
 - Change `RSpec/ContextWording` cop to always report an offense when both `Prefixes` and `AllowedPatterns` are empty. ([@ydah])
 - Fix an error for `RSpec/ChangeByZero` when `change (...) .by (0)` and `change (...)`, concatenated with `and` and `or`. ([@ydah])
+- Deprecate `top_level_group?` method from `TopLevelGroup` mixin as all of its callers were intentionally removed from `Rubocop/RSpec`. ([@corsonknowles])
 
 ## 3.1.0 (2024-10-01)
 
diff --git a/lib/rubocop/cop/rspec/mixin/top_level_group.rb b/lib/rubocop/cop/rspec/mixin/top_level_group.rb
index c3b48fb1d..1d4d8c6a2 100644
--- a/lib/rubocop/cop/rspec/mixin/top_level_group.rb
+++ b/lib/rubocop/cop/rspec/mixin/top_level_group.rb
@@ -7,6 +7,9 @@ module RSpec
       module TopLevelGroup
         extend RuboCop::NodePattern::Macros
 
+        DEPRECATED_MODULE_METHOD_WARNING =
+          'top_level_group? is deprecated and will be ' \
+          'removed in the next major version of rubocop_rspec.'
         def on_new_investigation
           super
 
@@ -28,7 +31,10 @@ def on_top_level_example_group(_node); end
 
         def on_top_level_group(_node); end
 
+        # @private
+        # @deprecated All callers of this method have been removed.
         def top_level_group?(node)
+          warn DEPRECATED_MODULE_METHOD_WARNING, uplevel: 1
           top_level_groups.include?(node)
         end
 
diff --git a/spec/rubocop/cop/rspec/mixin/top_level_group_spec.rb b/spec/rubocop/cop/rspec/mixin/top_level_group_spec.rb
new file mode 100644
index 000000000..251e3d711
--- /dev/null
+++ b/spec/rubocop/cop/rspec/mixin/top_level_group_spec.rb
@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+RSpec.describe RuboCop::Cop::RSpec::TopLevelGroup do
+  describe '#top_level_group?' do
+    let(:stub_class) do
+      Class.new do
+        include RuboCop::Cop::RSpec::TopLevelGroup
+
+        def initialize
+          @top_level_groups = []
+        end
+
+        def test_top_level_group
+          top_level_group?(nil)
+        end
+      end
+    end
+
+    it 'warns because it is deprecated' do
+      expect { stub_class.new.test_top_level_group }.to \
+        output(/warning: top_level_group\? is deprecated/).to_stderr
+    end
+  end
+end