rubocop-vicenzo 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f2fb87b8d1bfd10a66d52fcd5ede5f1eea78c7c2a8b7b8ea8a692d0efce54b6
-  data.tar.gz: aa25bb974ce70ab9ef752a1e36b83d779abded472022258a86ff8c2fdc483d77
+  metadata.gz: '094cfb18e36f28e2f311e80f435b1b5159f22875cfb8f13b5a0551ca9b5e9218'
+  data.tar.gz: b96a9634c956e7cec399e10a2f7f512a5f2894822ba07fecf7294a502fee56b5
 SHA512:
-  metadata.gz: 57918353d578d8c2a5840617ccfefe7a996aad212dbce8921ae18a1bf302bf89fb6a5e40f6b9cdd97d082c4fb74d2e26fb2a9148d92e83fbb074e6c094da996b
-  data.tar.gz: be26bf4c722a8e351112c02d58bba96d06fd62fa230e8feb20e3f80675c82f6ca377875a53281df99d39ccabf8fc5de2822f9eff985a6c7a3cbe188dedd3ff6d
+  metadata.gz: ba554984ec7092154352415043f2868cd59bd89015de29b0098e01c1f0b2016b8b3a837845cd22e8219e1115b37f4b6e80eb3d5861d0f3325c0ad2894466de23
+  data.tar.gz: 031a968654d68f7fa65e7a57a6178fc97651ae8c20cb4861f25a1f4c9feb5c6d044a3bc7e269e4de392a9a38483ce51296517f852abe61e88ba804ad723140b4

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.7.0"
+  ".": "0.8.0"
 }

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.8.0](https://github.com/bvicenzo/rubocop-vicenzo/compare/v0.7.0...v0.8.0) (2026-09-09)
+
+
+### Features
+
+* add RSpec cops against top-level declarations ([#31](https://github.com/bvicenzo/rubocop-vicenzo/issues/31)) ([ef5e207](https://github.com/bvicenzo/rubocop-vicenzo/commit/ef5e20728c0c4bc94dbb5eec54a48ff5197d1b25))
+
 ## [0.7.0](https://github.com/bvicenzo/rubocop-vicenzo/compare/v0.6.0...v0.7.0) (2026-08-31)
 
 

data/README.md

@@ -11,7 +11,7 @@ Add it to the `development`/`test` group of your `Gemfile`:
 <!-- x-release-please-start-version -->
 ```ruby
 group :development, :test do
-  gem 'rubocop-vicenzo', '~> 0.7.0', require: false
+  gem 'rubocop-vicenzo', '~> 0.8.0', require: false
 end
 ```
 <!-- x-release-please-end-version -->

data/config/default.yml

@@ -139,6 +139,61 @@ Vicenzo/RSpec/SubjectIsMethodResult:
     - '**/spec/factories/**/*'
   VersionAdded: '0.7.0'
 
+Vicenzo/RSpec/TopLevelContext:
+  Description: 'A context must not be declared in the top-level example group, where it is a scenario for every example in the file.'
+  Enabled: true
+  Severity: warning
+  Include:
+    - '**/spec/**/*_spec.rb'
+  Exclude:
+    - '**/spec/support/**/*'
+    - '**/spec/factories/**/*'
+  VersionAdded: '0.8.0'
+
+Vicenzo/RSpec/TopLevelExample:
+  Description: 'An example must not be declared in the top-level example group, which names no behaviour.'
+  Enabled: true
+  Severity: warning
+  Include:
+    - '**/spec/**/*_spec.rb'
+  Exclude:
+    - '**/spec/support/**/*'
+    - '**/spec/factories/**/*'
+  VersionAdded: '0.8.0'
+
+Vicenzo/RSpec/TopLevelHook:
+  Description: 'A hook must not be declared in the top-level example group, where it runs for every example in the file.'
+  Enabled: true
+  Severity: warning
+  Include:
+    - '**/spec/**/*_spec.rb'
+  Exclude:
+    - '**/spec/support/**/*'
+    - '**/spec/factories/**/*'
+  VersionAdded: '0.8.0'
+
+Vicenzo/RSpec/TopLevelLet:
+  Description: 'A let must not be declared in the top-level example group, where it reaches every example in the file.'
+  Enabled: true
+  Severity: warning
+  Include:
+    - '**/spec/**/*_spec.rb'
+  Exclude:
+    - '**/spec/support/**/*'
+    - '**/spec/factories/**/*'
+  VersionAdded: '0.8.0'
+
+Vicenzo/RSpec/TopLevelSubject:
+  Description: 'A subject must not be declared in the top-level example group, where it reaches every example in the file.'
+  Enabled: true
+  Severity: warning
+  Include:
+    - '**/spec/**/*_spec.rb'
+  Exclude:
+    - '**/spec/support/**/*'
+    - '**/spec/factories/**/*'
+  VersionAdded: '0.8.0'
+
 Vicenzo/Style/JsonParseSymbolizeNames:
   Description: 'Enforces passing `symbolize_names: true` to `JSON.parse` so keys are symbols.'
   Enabled: true

data/lib/rubocop/cop/vicenzo/rspec/mixin/top_level_definition.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative 'premise_tracking'
+
+module RuboCop
+  module Cop
+    module Vicenzo
+      module RSpec
+        # Shared machinery for the cops that read what a spec declares straight inside the top-level
+        # example group - the widest scope a file has, and the one every example written later inherits
+        # whether it wanted to or not.
+        #
+        # The including cop says which children it reads, through `#definition?`, and how to word the
+        # offense, through `MSG`. A cop that names what it found overrides `#message_for`, and may read
+        # the name through `#declared_name`.
+        #
+        # Meant for cops inheriting from `RuboCop::Cop::RSpec::Base`: `example_group?` comes from there.
+        module TopLevelDefinition
+          include PremiseTracking
+
+          def on_block(node)
+            return unless top_level_example_group?(node)
+
+            each_child_block(node) do |child|
+              add_offense(child.send_node, message: message_for(child)) if definition?(child)
+            end
+          end
+
+          alias on_numblock on_block
+
+          private
+
+          def top_level_example_group?(node)
+            example_group?(node) && outermost_example_group?(node)
+          end
+
+          def message_for(_node)
+            self.class::MSG
+          end
+
+          # The name the definition was given, or `nil` when there is none to read: an anonymous
+          # `subject { ... }`, or a name only known at runtime.
+          def declared_name(node)
+            argument = node.send_node.first_argument
+
+            argument.value.to_sym if argument&.type?(:sym, :str)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/vicenzo/rspec/top_level_context.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative 'mixin/top_level_definition'
+
+module RuboCop
+  module Cop
+    module Vicenzo
+      module RSpec
+        # A context declared straight inside the top-level example group is a scenario for the whole
+        # file. Nest it in the group whose behaviour it is a scenario of.
+        #
+        # A context answers "under which circumstances?", and the question only means something once a
+        # behaviour has been named. Declared at the root, the scenario applies to every example in the
+        # file at once - the same overreach a root subject or a root let has, since the premises the
+        # context declares are handed to everything written under it later.
+        #
+        # It is also how the file loses the describe it never had: the first behaviour goes under
+        # `context 'when ...'`, the second one needs the same circumstances worded slightly differently,
+        # and what should have been two groups naming two behaviours becomes a tree of scenarios naming
+        # none.
+        #
+        # @example
+        #   # bad - the scenario is about `#adult?`, yet it covers the whole file
+        #   RSpec.describe Person do
+        #     context 'when the person is a minor' do
+        #       subject(:person) { described_class.new(age: 17) }
+        #
+        #       it { is_expected.not_to be_adult }
+        #     end
+        #   end
+        #
+        #   # good - the behaviour is named first, the scenario belongs to it
+        #   RSpec.describe Person do
+        #     describe '#adult?' do
+        #       context 'when the person is a minor' do
+        #         subject(:person) { described_class.new(age: 17) }
+        #
+        #         it { is_expected.not_to be_adult }
+        #       end
+        #     end
+        #   end
+        class TopLevelContext < RuboCop::Cop::RSpec::Base
+          include TopLevelDefinition
+
+          MSG = 'This context is declared in the top-level example group, so it is a scenario for every ' \
+                'example in the file. Nest it in the group whose behaviour it is a scenario of.'
+
+          CONTEXTS = %i[context fcontext xcontext].freeze
+
+          # @!method context_definition?(node)
+          def_node_matcher :context_definition?, <<~PATTERN
+            (any_block (send nil? {#{CONTEXTS.map(&:inspect).join(' ')}} ...) ...)
+          PATTERN
+
+          private
+
+          def definition?(node) = context_definition?(node)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/vicenzo/rspec/top_level_example.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative 'mixin/top_level_definition'
+
+module RuboCop
+  module Cop
+    module Vicenzo
+      module RSpec
+        # An example declared straight inside the top-level example group is about no behaviour in
+        # particular. Move it into the group describing the behaviour it exercises.
+        #
+        # The top-level group names the object under test, not one of the things it does. An example
+        # hanging directly off it therefore reads as a statement about the object as a whole, when it is
+        # always a statement about one behaviour - the group naming that behaviour is simply missing, and
+        # with it the place where the next example about the same behaviour would go.
+        #
+        # It is also the shape that keeps premises in the top-level group alive: as long as examples live
+        # at the root, the subject and the lets they read have nowhere else to be declared, which is what
+        # `Vicenzo/RSpec/TopLevelSubject` and `Vicenzo/RSpec/TopLevelLet` report.
+        #
+        # @example
+        #   # bad - the example is about `#adult?`, but no group says so
+        #   RSpec.describe Person do
+        #     it { is_expected.to be_adult }
+        #   end
+        #
+        #   # good - the behaviour the example is about has a name, and a home
+        #   RSpec.describe Person do
+        #     describe '#adult?' do
+        #       subject(:person) { described_class.new(age: 18) }
+        #
+        #       it { is_expected.to be_adult }
+        #     end
+        #   end
+        class TopLevelExample < RuboCop::Cop::RSpec::Base
+          include TopLevelDefinition
+
+          MSG = 'This example is declared in the top-level example group, which names no behaviour. ' \
+                'Move it into the group describing the behaviour it exercises.'
+
+          private
+
+          def definition?(node) = example?(node)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/vicenzo/rspec/top_level_hook.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative 'mixin/top_level_definition'
+
+module RuboCop
+  module Cop
+    module Vicenzo
+      module RSpec
+        # A hook declared straight inside the top-level example group runs for every example in the
+        # file. Declare it in the group whose examples need it.
+        #
+        # A hook is a premise like any other - it just builds the state through side effects instead of
+        # a name. Declared at the root it reaches every example, including the ones written later that
+        # never asked for that state, and the group that needs the state built differently can only
+        # undo it, override it, or work around it.
+        #
+        # It is also the escape hatch left open once the root cannot hold a `subject` or a `let` any
+        # more: the premise stops being declared and starts being performed, which is harder to read and
+        # invisible to the cops that watch definitions. `Vicenzo/RSpec/TopLevelSubject` and
+        # `Vicenzo/RSpec/TopLevelLet` close the front door; this one closes the back.
+        #
+        # @example
+        #   # bad - every example in the file runs inside this state
+        #   RSpec.describe Person do
+        #     before { travel_to(Time.zone.local(2026, 1, 1)) }
+        #
+        #     describe '#adult?' do
+        #       it { is_expected.to be_adult }
+        #     end
+        #   end
+        #
+        #   # good - the state belongs to the examples that need it
+        #   RSpec.describe Person do
+        #     describe '#adult?' do
+        #       before { travel_to(Time.zone.local(2026, 1, 1)) }
+        #
+        #       it { is_expected.to be_adult }
+        #     end
+        #   end
+        class TopLevelHook < RuboCop::Cop::RSpec::Base
+          include TopLevelDefinition
+
+          MSG = 'Hook `%<name>s` is declared in the top-level example group, so it runs for every ' \
+                'example in the file. Declare it in the group whose examples need it.'
+
+          private
+
+          def message_for(node) = format(MSG, name: node.method_name)
+
+          def definition?(node) = hook?(node)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/vicenzo/rspec/top_level_let.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative 'mixin/top_level_definition'
+
+module RuboCop
+  module Cop
+    module Vicenzo
+      module RSpec
+        # A let declared straight inside the top-level example group is the root of the nested
+        # redefinition problem. Declare it in the group whose examples read it.
+        #
+        # The top-level group is the widest scope a file has: a let born there is handed to every
+        # example, including all the ones written later that were never considered when it was written.
+        # The first sibling group that needs the value to be slightly different has nowhere to go but
+        # over the top of it - a redefinition, a near-copy under another name, or a `before` that mutates
+        # the value back into shape. None of those read as a specification any more, and each one is a
+        # scenario nobody named.
+        #
+        # Declaring the let in the group that reads it costs one extra line per group and buys back the
+        # naming: each group states the premises its examples start from, and a sibling that starts from
+        # a different value is a different group with its own declaration, not an override of someone
+        # else's.
+        #
+        # This is the preventive half of `Vicenzo/RSpec/NestedLetRedefinition`, which reports the
+        # redefinition once it exists. Keeping the top-level group free of lets means there is nothing to
+        # redefine.
+        #
+        # @example
+        #   # bad - the let reaches every example, so `#adult?` can only override it
+        #   RSpec.describe Person do
+        #     let(:age) { 42 }
+        #
+        #     describe '#tall?' do
+        #       it { is_expected.to be_tall }
+        #     end
+        #
+        #     describe '#adult?' do
+        #       let(:age) { 17 }
+        #
+        #       it { is_expected.not_to be_adult }
+        #     end
+        #   end
+        #
+        #   # good - each group declares the premises its examples start from
+        #   RSpec.describe Person do
+        #     describe '#tall?' do
+        #       subject(:person) { described_class.new(height: 1.75) }
+        #
+        #       it { is_expected.to be_tall }
+        #     end
+        #
+        #     describe '#adult?' do
+        #       subject(:person) { described_class.new(age: 17) }
+        #
+        #       it { is_expected.not_to be_adult }
+        #     end
+        #   end
+        #
+        # @example a context is as good a home as a describe
+        #   # good - the premise belongs to the scenario, and the scenario is a context
+        #   RSpec.describe Person do
+        #     describe '#adult?' do
+        #       context 'when the person is a minor' do
+        #         subject(:person) { described_class.new(age:) }
+        #
+        #         let(:age) { 17 }
+        #
+        #         it { is_expected.not_to be_adult }
+        #       end
+        #     end
+        #   end
+        class TopLevelLet < RuboCop::Cop::RSpec::Base
+          include TopLevelDefinition
+
+          MSG = 'Let `:%<name>s` is declared in the top-level example group, where it reaches every ' \
+                'example in the file. Declare it in the group whose examples read it.'
+          MSG_UNNAMED = 'A let is declared in the top-level example group, where it reaches every ' \
+                        'example in the file. Declare it in the group whose examples read it.'
+
+          private
+
+          def message_for(node)
+            name = declared_name(node)
+
+            name.nil? ? MSG_UNNAMED : format(MSG, name:)
+          end
+
+          def definition?(node) = let?(node) || let_it_be?(node)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/vicenzo/rspec/top_level_subject.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative 'mixin/top_level_definition'
+
+module RuboCop
+  module Cop
+    module Vicenzo
+      module RSpec
+        # A subject declared straight inside the top-level example group is the root of the nested
+        # redefinition problem. Declare it in the group whose examples read it.
+        #
+        # The top-level group is the widest scope a file has: a subject born there is handed to every
+        # example, including all the ones written later that were never considered when it was written.
+        # The first sibling group that needs the object built slightly differently has nowhere to go but
+        # over the top of it - a redefinition, a second subject under another name, or a `before` that
+        # patches the object back into shape. None of those read as a specification any more, and each
+        # one is a scenario nobody named.
+        #
+        # Declaring the subject in the group that asserts on it costs one extra line per group and buys
+        # back the naming: each group states the object it is about, and a sibling that needs a different
+        # object is a different group with its own declaration, not an override of someone else's.
+        #
+        # This is the preventive half of `Vicenzo/RSpec/NestedSubjectRedefinition`, which reports the
+        # redefinition once it exists. Keeping the top-level group free of subjects means there is
+        # nothing to redefine.
+        #
+        # @example
+        #   # bad - the subject reaches every example, so `#tall?` can only override it
+        #   RSpec.describe Person do
+        #     subject(:person) { described_class.new }
+        #
+        #     describe '#adult?' do
+        #       before { person.age = 18 }
+        #
+        #       it { is_expected.to be_adult }
+        #     end
+        #
+        #     describe '#tall?' do
+        #       subject(:person) { described_class.new(height: 1.75) }
+        #
+        #       it { is_expected.to be_tall }
+        #     end
+        #   end
+        #
+        #   # good - each group declares the person its examples are about
+        #   RSpec.describe Person do
+        #     describe '#adult?' do
+        #       subject(:person) { described_class.new(age: 18) }
+        #
+        #       it { is_expected.to be_adult }
+        #     end
+        #
+        #     describe '#tall?' do
+        #       subject(:person) { described_class.new(height: 1.75) }
+        #
+        #       it { is_expected.to be_tall }
+        #     end
+        #   end
+        #
+        # @example a context is as good a home as a describe
+        #   # good - the subject belongs to the scenario, and the scenario is a context
+        #   RSpec.describe Person do
+        #     describe '#adult?' do
+        #       context 'when the person is of age' do
+        #         subject(:person) { described_class.new(age: 18) }
+        #
+        #         it { is_expected.to be_adult }
+        #       end
+        #     end
+        #   end
+        class TopLevelSubject < RuboCop::Cop::RSpec::Base
+          include TopLevelDefinition
+
+          MSG = 'Subject `:%<name>s` is declared in the top-level example group, where it reaches every ' \
+                'example in the file. Declare it in the group whose examples read it.'
+          MSG_UNNAMED = 'The subject is declared in the top-level example group, where it reaches every ' \
+                        'example in the file. Declare it in the group whose examples read it.'
+
+          private
+
+          def message_for(node)
+            name = declared_name(node)
+
+            name.nil? ? MSG_UNNAMED : format(MSG, name:)
+          end
+
+          def definition?(node) = subject?(node)
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/vicenzo_cops.rb

@@ -14,6 +14,11 @@ require_relative 'vicenzo/rspec/nested_subject_redefinition'
 require_relative 'vicenzo/rspec/leaky_definition'
 require_relative 'vicenzo/rspec/subject_defined_as_let'
 require_relative 'vicenzo/rspec/subject_is_method_result'
+require_relative 'vicenzo/rspec/top_level_context'
+require_relative 'vicenzo/rspec/top_level_example'
+require_relative 'vicenzo/rspec/top_level_hook'
+require_relative 'vicenzo/rspec/top_level_let'
+require_relative 'vicenzo/rspec/top_level_subject'
 require_relative 'vicenzo/rails/enum_inclusion_of_validation'
 require_relative 'vicenzo/layout/multiline_method_call_line_breaks'
 require_relative 'vicenzo/style/json_parse_symbolize_names'

data/lib/rubocop/vicenzo/version.rb

@@ -2,6 +2,6 @@
 
 module RuboCop
   module Vicenzo
-    VERSION = '0.7.0'
+    VERSION = '0.8.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-vicenzo
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Bruno Vicenzo
@@ -86,12 +86,18 @@ files:
 - lib/rubocop/cop/vicenzo/rspec/mixin/described_method.rb
 - lib/rubocop/cop/vicenzo/rspec/mixin/expectation_target.rb
 - lib/rubocop/cop/vicenzo/rspec/mixin/premise_tracking.rb
+- lib/rubocop/cop/vicenzo/rspec/mixin/top_level_definition.rb
 - lib/rubocop/cop/vicenzo/rspec/mutated_premises.rb
 - lib/rubocop/cop/vicenzo/rspec/nested_context_improper_start.rb
 - lib/rubocop/cop/vicenzo/rspec/nested_let_redefinition.rb
 - lib/rubocop/cop/vicenzo/rspec/nested_subject_redefinition.rb
 - lib/rubocop/cop/vicenzo/rspec/subject_defined_as_let.rb
 - lib/rubocop/cop/vicenzo/rspec/subject_is_method_result.rb
+- lib/rubocop/cop/vicenzo/rspec/top_level_context.rb
+- lib/rubocop/cop/vicenzo/rspec/top_level_example.rb
+- lib/rubocop/cop/vicenzo/rspec/top_level_hook.rb
+- lib/rubocop/cop/vicenzo/rspec/top_level_let.rb
+- lib/rubocop/cop/vicenzo/rspec/top_level_subject.rb
 - lib/rubocop/cop/vicenzo/style/json_parse_symbolize_names.rb
 - lib/rubocop/cop/vicenzo/style/multiline_method_call_parentheses.rb
 - lib/rubocop/cop/vicenzo_cops.rb