rubocop-vicenzo 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5b82e09fef23aac921adb4f653bfbdc1117af279326d24339f68db8abe25ffd
-  data.tar.gz: f5f4d255aacd3851e4f8b7968b663d22db0b0ed9be99bab01a17df43d819c80f
+  metadata.gz: '094cfb18e36f28e2f311e80f435b1b5159f22875cfb8f13b5a0551ca9b5e9218'
+  data.tar.gz: b96a9634c956e7cec399e10a2f7f512a5f2894822ba07fecf7294a502fee56b5
 SHA512:
-  metadata.gz: 79d36dbf73503ca38cca4d5ffd77fd84d56cf4b8d320ff389035c359116e36d66d15a3aad4fd3de10d9787fe29f4b4af66b0b669ce98754415fac8ad954106fa
-  data.tar.gz: 84055ca6301311a752670e04fa5fcd9646fc38844993428a5f952be17a7384cfa5842b9a2daaa7f3be3242d70e0641b7ba02fdd718fee111f995bd1cd4a8b3e0
+  metadata.gz: ba554984ec7092154352415043f2868cd59bd89015de29b0098e01c1f0b2016b8b3a837845cd22e8219e1115b37f4b6e80eb3d5861d0f3325c0ad2894466de23
+  data.tar.gz: 031a968654d68f7fa65e7a57a6178fc97651ae8c20cb4861f25a1f4c9feb5c6d044a3bc7e269e4de392a9a38483ce51296517f852abe61e88ba804ad723140b4

data/.release-please-manifest.json

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

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # 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)
+
+
+### Features
+
+* add RSpec cops against subjects hidden in lets ([#30](https://github.com/bvicenzo/rubocop-vicenzo/issues/30)) ([9daf259](https://github.com/bvicenzo/rubocop-vicenzo/commit/9daf25972252fdfdb92a51bba9cfe70e63446d17))
+* add Vicenzo/RSpec/SubjectIsMethodResult cop ([#28](https://github.com/bvicenzo/rubocop-vicenzo/issues/28)) ([b69245a](https://github.com/bvicenzo/rubocop-vicenzo/commit/b69245af973f3341bbe62bca628333c5acb909d7))
+
 ## [0.6.0](https://github.com/bvicenzo/rubocop-vicenzo/compare/v0.5.0...v0.6.0) (2026-08-19)
 
 

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.6.0', require: false
+  gem 'rubocop-vicenzo', '~> 0.8.0', require: false
 end
 ```
 <!-- x-release-please-end-version -->

data/config/default.yml

@@ -11,6 +11,18 @@ Vicenzo/Rails/EnumInclusionOfValidation:
   Severity: convention
   VersionAdded: '0.1.0'
 
+Vicenzo/RSpec/CompetingSubjects:
+  Description: 'Definitions the expectations assert on, two or more in a group declaring no subject, are either hidden contexts or a premise that belongs in a before.'
+  Enabled: true
+  Severity: convention
+  AllowedMethods: []
+  Include:
+    - '**/spec/**/*_spec.rb'
+  Exclude:
+    - '**/spec/support/**/*'
+    - '**/spec/factories/**/*'
+  VersionAdded: '0.7.0'
+
 Vicenzo/RSpec/ConditionalInSpec:
   Description: 'Do not use conditional logic in specs. Extract each branch into an explicit context instead.'
   Enabled: true
@@ -91,6 +103,97 @@ Vicenzo/RSpec/LeakyDefinition:
     - '**/spec/support/**/*'
     - '**/spec/factories/**/*'
 
+Vicenzo/RSpec/LetIsMethodResult:
+  Description: 'A let under an example group describing a method must not hold the result of calling that method on the subject.'
+  Enabled: true
+  Severity: convention
+  AllowedMethods: []
+  Include:
+    - '**/spec/**/*_spec.rb'
+  Exclude:
+    - '**/spec/support/**/*'
+    - '**/spec/factories/**/*'
+  VersionAdded: '0.7.0'
+
+Vicenzo/RSpec/SubjectDefinedAsLet:
+  Description: 'A let the expectations assert on, in a group declaring no subject, must be declared as the subject.'
+  Enabled: true
+  Severity: convention
+  AllowedMethods: []
+  Include:
+    - '**/spec/**/*_spec.rb'
+  Exclude:
+    - '**/spec/support/**/*'
+    - '**/spec/factories/**/*'
+  VersionAdded: '0.7.0'
+
+Vicenzo/RSpec/SubjectIsMethodResult:
+  Description: 'The subject of an example group describing a method must be the object under test, not the method result.'
+  Enabled: true
+  Severity: convention
+  AllowedMethods: []
+  Include:
+    - '**/spec/**/*_spec.rb'
+  Exclude:
+    - '**/spec/support/**/*'
+    - '**/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/competing_subjects.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require_relative 'mixin/described_method'
+require_relative 'mixin/expectation_target'
+require_relative 'mixin/premise_tracking'
+
+module RuboCop
+  module Cop
+    module Vicenzo
+      module RSpec
+        # Two or more definitions the expectations assert on, in a group that declares no subject, are
+        # contexts that were never written.
+        #
+        # A group speaks about one subject. When its examples each assert on a different definition, the
+        # group is not one scenario with several facts: it is several scenarios sharing a roof, and the
+        # circumstance that tells them apart - the one a `context` would have named - lives only in the
+        # definitions' names and in the reader's head.
+        #
+        # The fix is structural, and it is never to pick one of them to promote. Which shape it takes
+        # depends on what the definitions are to this group, and working that out is the whole job -
+        # which is why the offense names what was found rather than prescribing a repair:
+        #
+        # 1. They are different scenarios. Give each its own `context`, saying out loud the circumstance
+        #    it stands for, and let each declare the subject it is about. What was encoded in
+        #    `record_1` / `record_2` becomes a sentence, and the example shrinks to the outcome alone.
+        # 2. One outcome covers them all. Then they were never subjects: they are the premise. Move them
+        #    into a `before`, unnamed, and assert on the collection they belong to.
+        #
+        # Both are corrections to the spec. Neither is silencing the cop: a definition named
+        # `record_1` is the shape this smell takes, so renaming it settles nothing, and an inline
+        # disable directive keeps the hidden scenario hidden - which is the cost being paid here.
+        #
+        # A group that already declares a subject is left alone - there the subject is settled and the
+        # other definitions are premises, whatever their names suggest.
+        #
+        # @example
+        #   # bad - two subjects under one roof; the circumstances are only in the names
+        #   describe '#approved?' do
+        #     let!(:reviewed_post) { create(:post, reviewed_at: Time.current) }
+        #     let!(:draft_post) { create(:post) }
+        #
+        #     it { expect(reviewed_post).to be_approved }
+        #     it { expect(draft_post).not_to be_approved }
+        #   end
+        #
+        #   # good - one context per scenario, each with its own subject
+        #   describe '#approved?' do
+        #     context 'when the post has been reviewed' do
+        #       subject(:post) { create(:post, reviewed_at: Time.current) }
+        #
+        #       it { is_expected.to be_approved }
+        #     end
+        #
+        #     context 'without a review' do
+        #       subject(:post) { create(:post) }
+        #
+        #       it { is_expected.not_to be_approved }
+        #     end
+        #   end
+        #
+        # @example when one outcome covers every record, they are the premise
+        #   # bad - two records named as if each were a subject
+        #   describe '#deactivate' do
+        #     let!(:pending_alert) { create(:alert, :pending) }
+        #     let!(:firing_alert) { create(:alert, :firing) }
+        #
+        #     it 'dismisses every alert', :aggregate_failures do
+        #       monitor.deactivate
+        #
+        #       expect(pending_alert.reload).to be_dismissed
+        #       expect(firing_alert.reload).to be_dismissed
+        #     end
+        #   end
+        #
+        #   # good - the records are the premise, and the outcome is about the collection
+        #   describe '#deactivate' do
+        #     before do
+        #       create(:alert, :pending)
+        #       create(:alert, :firing)
+        #     end
+        #
+        #     it 'dismisses every alert' do
+        #       monitor.deactivate
+        #
+        #       expect(monitor.alerts).to contain_exactly(be_dismissed, be_dismissed)
+        #     end
+        #   end
+        #
+        # @example records a single expectation compares are not competing subjects
+        #   # good - both records build the one answer the example is about
+        #   describe '.recent' do
+        #     let!(:recent_order) { create(:order, created_at: 1.day.ago) }
+        #     let!(:old_order) { create(:order, created_at: 1.year.ago) }
+        #
+        #     it { expect(described_class.recent).to contain_exactly(recent_order) }
+        #   end
+        class CompetingSubjects < RuboCop::Cop::RSpec::Base
+          include DescribedMethod
+          include ExpectationTarget
+          include PremiseTracking
+
+          MSG = 'The expectations here are about %<names>s, so this group has no one subject. Work out ' \
+                'what these definitions are to it, and let the structure say so.'
+
+          def on_block(node)
+            return unless example_group?(node)
+
+            names = competing_names(node)
+
+            return if names.size < 2
+
+            add_offense(node.send_node, message: format(MSG, names: names.join(', ')))
+          end
+
+          alias on_numblock on_block
+          alias on_itblock on_block
+
+          private
+
+          def competing_names(group)
+            return [] if declares_subject?(group)
+
+            asserted_definitions(group).reject { |name| exempt?(group, name) }.map { |name| "`:#{name}`" }
+          end
+
+          def exempt?(group, name)
+            return false if allowed_methods.empty?
+
+            definition = definition_named(group, name)
+
+            !definition.nil? && !call_in_chain(definition.body) do |call|
+              allowed_methods.include?(call.method_name.to_s)
+            end.nil?
+          end
+
+          def definition_named(group, name)
+            found = nil
+
+            each_child_block(group) do |child|
+              found ||= child if premise?(child) && premise_name(child)&.to_sym == name
+            end
+
+            found
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative 'mixin/described_method'
+require_relative 'mixin/premise_tracking'
+
+module RuboCop
+  module Cop
+    module Vicenzo
+      module RSpec
+        # A `let` under an example group that describes a method must not hold what calling that method
+        # on the subject returned.
+        #
+        # This is the same inversion `Vicenzo/RSpec/SubjectIsMethodResult` reports, moved one definition
+        # away: the subject stays the object under test, and the result is parked in a `let` that the
+        # expectation then asserts on. What the example says out loud becomes a name, and the action -
+        # the subject receiving the method - is nowhere in the example that is supposed to describe it.
+        #
+        # The fix is not to rename the `let` or to move it: it is to undo it. Even when the `let` is read
+        # inside an `expect`, what it holds belongs in the expectation itself, where the sentence reads
+        # whole - the cat catches the ball, and that is what is asserted.
+        #
+        # Only calls on the subject count, which is what separates the result from the setup: a `let`
+        # calling the described method on some other object is building a premise, not the outcome the
+        # example is about. `AllowedMethods` is shared with the sibling cop and ships empty, for the
+        # layers whose convention is a single entry point.
+        #
+        # @example
+        #   # bad - the expectation asserts on a name; the cat never catches anything in the example
+        #   describe '#catch' do
+        #     subject(:cat) { Cat.new(name: 'Bixano') }
+        #
+        #     let(:catch) { cat.catch(object: Ball.new) }
+        #
+        #     it { expect(catch).to eq(:success) }
+        #   end
+        #
+        #   # good - the action is in the expectation
+        #   describe '#catch' do
+        #     subject(:cat) { Cat.new(name: 'Bixano') }
+        #
+        #     it { expect(cat.catch(object: Ball.new)).to eq(:success) }
+        #   end
+        #
+        # @example a call on another object is a premise, not the result
+        #   # good - the described method builds the state the example starts from
+        #   describe '#catch' do
+        #     subject(:cat) { Cat.new(name: 'Bixano') }
+        #
+        #     let(:taken_ball) { other_cat.catch(object: Ball.new) }
+        #   end
+        class LetIsMethodResult < RuboCop::Cop::RSpec::Base
+          include DescribedMethod
+          include PremiseTracking
+
+          MSG = 'Let `:%<name>s` holds what `%<method>s` returned. Undo it and call `%<method>s` on the ' \
+                'subject inside the expectation.'
+
+          def on_block(node)
+            return unless let?(node) || let_it_be?(node)
+
+            method_name = described_method_name(node)
+            return if method_name.nil? || allowed_methods.include?(method_name)
+
+            invocation = invocation_on_subject(node, method_name)
+            return unless invocation
+
+            add_offense(invocation, message: format(MSG, name: premise_name(node), method: method_name))
+          end
+
+          alias on_numblock on_block
+          alias on_itblock on_block
+
+          private
+
+          def invocation_on_subject(node, method_name)
+            names = subject_names(node)
+
+            call_in_chain(node.body) do |call|
+              call.method?(method_name) && subject_reference?(call.receiver, names)
+            end
+          end
+
+          # `subject` always refers to the subject, declared or implicit; a named one answers to its name
+          # as well.
+          def subject_names(node)
+            names = Set[:subject]
+
+            node.each_ancestor(:any_block).each do |ancestor|
+              next unless example_group?(ancestor)
+
+              each_child_block(ancestor) { |child| names << subject_name(child) if subject?(child) }
+            end
+
+            names
+          end
+
+          # An anonymous `subject!` is still read as `subject`.
+          def subject_name(node)
+            name = premise_name(node).to_sym
+
+            name == :subject! ? :subject : name
+          end
+
+          def subject_reference?(receiver, names)
+            return false unless receiver&.send_type? && receiver.receiver.nil? && receiver.arguments.empty?
+
+            names.include?(receiver.method_name)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Vicenzo
+      module RSpec
+        # Shared helpers for the cops that read an example group naming a method - `#instance_method`,
+        # `.class_method`, `#method(signature)`, or the bare method name - and ask what the definitions
+        # under it are built from.
+        #
+        # Meant for cops inheriting from `RuboCop::Cop::RSpec::Base`: `example_group?` and `cop_config`
+        # come from there.
+        module DescribedMethod
+          # `#catch`, `.catch`, and the form carrying a signature such as `#catch(object:)`.
+          PREFIXED_METHOD_DESCRIPTION = /\A[#.](?<name>.+?)(?:\(.*\))?\z/
+          # `catch` - a description that is nothing but a method name.
+          BARE_METHOD_DESCRIPTION = /\A(?<name>\w+[?!=]?)\z/
+
+          private
+
+          # The nearest enclosing example group naming a method: a definition sitting in a `context` still
+          # answers to the `describe '#method'` wrapping it.
+          def described_method_name(node)
+            node
+              .each_ancestor(:any_block)
+              .lazy
+              .filter_map { |ancestor| method_name_from(ancestor) if example_group?(ancestor) }
+              .first
+          end
+
+          def method_name_from(node)
+            description = node.send_node.first_argument
+            return unless description.respond_to?(:str_type?) && description.str_type?
+
+            match = PREFIXED_METHOD_DESCRIPTION.match(description.value) ||
+                    BARE_METHOD_DESCRIPTION.match(description.value)
+
+            match&.[](:name)
+          end
+
+          def allowed_methods
+            cop_config.fetch('AllowedMethods', [])
+          end
+
+          # Walks the expression a definition returns down its receiver chain, yielding each call, so that
+          # `Cat.new.catch(ball).to_s` is seen as built on `catch` while `Cat.new(catches: other.catch)`
+          # is not - there, nothing of `catch` reaches the value.
+          def call_in_chain(body)
+            node = returned_expression(body)
+
+            while node
+              node = node.send_node if node.any_block_type?
+              break unless node.type?(:call)
+              return node if yield(node)
+
+              node = node.receiver
+            end
+
+            nil
+          end
+
+          def returned_expression(body)
+            return if body.nil?
+
+            body.begin_type? ? body.children.last : body
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Vicenzo
+      module RSpec
+        # Shared helpers to tell which definitions an example group's expectations are *about*.
+        #
+        # Only the left-hand side of an expectation counts - `expect(order)` and `expect { order }`.
+        # What sits inside the matcher is the expected answer, not the subject: in
+        # `expect(described_class.recent).to contain_exactly(recent_order)`, `recent_order` is part of the
+        # answer, and reading it as the subject would turn the correct way of specifying a scope into an
+        # offense.
+        #
+        # Meant for cops inheriting from `RuboCop::Cop::RSpec::Base` and including `PremiseTracking`:
+        # `let?`, `example_group?` and `premise_name` come from there.
+        module ExpectationTarget
+          EXPECTATION_RUNNERS = %i[to not_to to_not].freeze
+
+          # Verifying a message is a statement about a collaborator, never about the subject.
+          MESSAGE_MATCHERS = %i[receive have_received receive_messages receive_message_chain].freeze
+
+          private
+
+          # The definitions declared directly in this group that its expectations assert on.
+          def asserted_definitions(group)
+            names = []
+
+            each_child_block(group) do |child|
+              next unless let?(child) || let_it_be?(child)
+
+              name = premise_name(child)&.to_sym
+
+              names << name if name && asserted_on?(group, name)
+            end
+
+            names
+          end
+
+          def asserted_on?(group, name)
+            return false if group.nil?
+
+            group.each_descendant(:send).any? { |send_node| expectation_on?(send_node, name) }
+          end
+
+          def expectation_on?(node, name)
+            return false unless node.method?(:expect) && node.receiver.nil?
+            return false unless reference?(node.first_argument || node.block_node&.body, name)
+
+            !message_expectation?(node)
+          end
+
+          def reference?(node, name)
+            return false unless node&.send_type? && node.receiver.nil? && node.arguments.empty?
+
+            node.method?(name)
+          end
+
+          def message_expectation?(node)
+            MESSAGE_MATCHERS.include?(matcher_name(expectation_matcher(node)))
+          end
+
+          def expectation_matcher(node)
+            runner = node.block_node&.parent || node.parent
+
+            return unless runner&.send_type? && EXPECTATION_RUNNERS.include?(runner.method_name)
+
+            runner.first_argument
+          end
+
+          # The matcher a chained expectation starts from: `receive(:set).with(key)` starts at `receive`.
+          def matcher_name(node)
+            node = node.receiver while node&.receiver
+
+            node&.method_name
+          end
+
+          def enclosing_example_group(node)
+            node.each_ancestor(:any_block).find { |ancestor| example_group?(ancestor) }
+          end
+
+          def subject_declared?(node)
+            node.each_ancestor(:any_block).any? do |ancestor|
+              next false unless example_group?(ancestor)
+
+              declares_subject?(ancestor)
+            end
+          end
+
+          def declares_subject?(group)
+            declared = false
+
+            each_child_block(group) { |child| declared ||= subject?(child) }
+
+            declared
+          end
+        end
+      end
+    end
+  end
+end

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/subject_defined_as_let.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require_relative 'mixin/described_method'
+require_relative 'mixin/expectation_target'
+require_relative 'mixin/premise_tracking'
+
+module RuboCop
+  module Cop
+    module Vicenzo
+      module RSpec
+        # A `let` the expectations assert on, in an example group that declares no subject, is the
+        # subject wearing another name. Declare it as one.
+        #
+        # The subject of a specification is what the sentences are about. When every expectation in a
+        # group reads `expect(service)`, `service` is that - and calling it a `let` costs the group the
+        # one declaration that says so out loud, leaves `is_expected` unavailable, and hides the
+        # redefinitions from the cops that watch subjects for a living.
+        #
+        # This says nothing about what the subject should hold - that is
+        # `Vicenzo/RSpec/SubjectIsMethodResult`'s question, and it already knows the conventions the
+        # project declared. The two compose without arguing: declare the subject, and if the value it
+        # holds is not fit to be the subject either, the sibling cop says so next.
+        #
+        # `AllowedMethods` exempts a `let` whose value comes from calling one of the listed methods, for
+        # the projects where such a definition is deliberately a `let`. It ships empty.
+        #
+        # @example
+        #   # bad - every expectation is about `service`, yet the group declares no subject
+        #   describe '.call' do
+        #     context 'when the order is unknown' do
+        #       let(:service) { described_class.(order_id: 42) }
+        #
+        #       it { expect(service).to be_failure }
+        #     end
+        #   end
+        #
+        #   # good - the subject is declared, and `is_expected` reads the sentence back
+        #   describe '.call' do
+        #     context 'when the order is unknown' do
+        #       subject(:service) { described_class.(order_id: 42) }
+        #
+        #       it { is_expected.to be_failure }
+        #     end
+        #   end
+        #
+        # @example a let the expectations only read through is a premise
+        #   # good - the expectation is about the book, not about the author
+        #   describe '#author' do
+        #     subject(:book) { create(:book, author:) }
+        #
+        #     let(:author) { create(:author) }
+        #
+        #     it { expect(book.author).to eq(author) }
+        #   end
+        class SubjectDefinedAsLet < RuboCop::Cop::RSpec::Base
+          include DescribedMethod
+          include ExpectationTarget
+          include PremiseTracking
+
+          MSG = 'Let `:%<name>s` is what the expectations assert on, so it is the subject. ' \
+                'Declare it with `subject(:%<name>s)`.'
+
+          def on_block(node)
+            name = subject_in_disguise(node)
+
+            return if name.nil?
+
+            add_offense(node.send_node, message: format(MSG, name:))
+          end
+
+          alias on_numblock on_block
+          alias on_itblock on_block
+
+          private
+
+          # The name a definition should have been declared under, or `nil` when it is a `let` like any
+          # other: not a definition at all, one the group already has a subject for, one whose value the
+          # project exempted, or one no expectation is about.
+          def subject_in_disguise(node)
+            return unless candidate?(node)
+
+            group = enclosing_example_group(node)
+
+            return if group.nil?
+
+            name = premise_name(node)&.to_sym
+
+            # Two definitions asserted side by side cannot both be this group's subject: they are
+            # hidden contexts, which `Vicenzo/RSpec/CompetingSubjects` reads.
+            return unless asserted_definitions(group) == [name]
+
+            name
+          end
+
+          def candidate?(node)
+            (let?(node) || let_it_be?(node)) && !subject_declared?(node) && !allowed_value?(node)
+          end
+
+          def allowed_value?(node)
+            return false if allowed_methods.empty?
+
+            !call_in_chain(node.body) { |call| allowed_methods.include?(call.method_name.to_s) }.nil?
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative 'mixin/described_method'
+
+module RuboCop
+  module Cop
+    module Vicenzo
+      module RSpec
+        # The subject of an example group that describes a method must be the object under test,
+        # not what the method returned.
+        #
+        # A specification is read as a sentence. In "the cat caught the ball", the subject is the
+        # cat, not the ball. Storing the return value in the subject inverts that: the object the
+        # example is about disappears from the text, the subject's name starts to lie (a
+        # `subject(:cat)` holding a `Symbol`), and every scenario that would need the same object
+        # in a different state has to redefine the whole call.
+        #
+        # An example group names a method when its description reads `#instance_method`,
+        # `.class_method`, or the bare method name. The cop then looks at the subjects declared
+        # under it - including the ones nested in a `context` - and reports the ones whose value
+        # comes from calling that method.
+        #
+        # Some layers legitimately specify a single entry point, where the result is the subject
+        # (a service object always invoked through `call`, for instance). `AllowedMethods` exists
+        # for those and ships empty: the convention belongs to the project that adopts it, not to
+        # this gem. Declaring it there - or excluding a whole directory through the standard
+        # `Exclude` - keeps the exemption visible and reviewable in `.rubocop.yml`.
+        #
+        # An inline disable directive is not that: it is an exemption nobody reviewed. Dropping
+        # the `#` from the description is not either - the cop reads bare descriptions too, and the
+        # only thing lost is the reader's clue that a method is being specified there.
+        #
+        # @example
+        #   # bad - the subject is the ball
+        #   describe '#catch' do
+        #     subject(:catch) { Cat.new(name: 'Bixano').catch(object: Ball.new) }
+        #
+        #     it { is_expected.to eq(:success) }
+        #   end
+        #
+        #   # good - the subject is the cat
+        #   describe '#catch' do
+        #     subject(:cat) { Cat.new(name: 'Bixano') }
+        #
+        #     it { expect(cat.catch(object: Ball.new)).to eq(:success) }
+        #   end
+        #
+        # @example a description without a prefix names a method too
+        #   # bad - dropping the '#' silences nothing and costs the reader the
+        #   # one clue that a method is being specified here
+        #   describe 'catch' do
+        #     subject(:catch) { Cat.new(name: 'Bixano').catch(object: Ball.new) }
+        #   end
+        #
+        # @example AllowedMethods: ['call']
+        #   # good - a layer whose convention is a single entry point. Declared in
+        #   # .rubocop.yml, the exemption stays visible and reviewable, which an
+        #   # inline disable directive never is
+        #   describe '.call' do
+        #     subject(:result) { described_class.(object: Ball.new) }
+        #   end
+        class SubjectIsMethodResult < RuboCop::Cop::RSpec::Base
+          include DescribedMethod
+
+          MSG = 'Subject holds what `%<method>s` returned, not the object under test. ' \
+                'Make the subject the object that receives `%<method>s`, and call it inside the example.'
+
+          def on_block(node)
+            return unless subject?(node)
+
+            method_name = described_method_name(node)
+            return if method_name.nil? || allowed_methods.include?(method_name)
+
+            invocation = call_in_chain(node.body) { |call| call.method?(method_name) }
+            return unless invocation
+
+            add_offense(invocation, message: format(MSG, method: method_name))
+          end
+
+          alias on_numblock on_block
+          alias on_itblock on_block
+        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

@@ -1,15 +1,24 @@
 # frozen_string_literal: true
 
+require_relative 'vicenzo/rspec/competing_subjects'
 require_relative 'vicenzo/rspec/conditional_in_spec'
 require_relative 'vicenzo/rspec/derived_premises'
 require_relative 'vicenzo/rspec/dynamic_example_generation'
 require_relative 'vicenzo/rspec/inconsistent_sibling_structure'
 require_relative 'vicenzo/rspec/iteration_inside_example'
+require_relative 'vicenzo/rspec/let_is_method_result'
 require_relative 'vicenzo/rspec/mutated_premises'
 require_relative 'vicenzo/rspec/nested_context_improper_start'
 require_relative 'vicenzo/rspec/nested_let_redefinition'
 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.6.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.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Bruno Vicenzo
@@ -75,17 +75,29 @@ files:
 - lib/rubocop-vicenzo.rb
 - lib/rubocop/cop/vicenzo/layout/multiline_method_call_line_breaks.rb
 - lib/rubocop/cop/vicenzo/rails/enum_inclusion_of_validation.rb
+- lib/rubocop/cop/vicenzo/rspec/competing_subjects.rb
 - lib/rubocop/cop/vicenzo/rspec/conditional_in_spec.rb
 - lib/rubocop/cop/vicenzo/rspec/derived_premises.rb
 - lib/rubocop/cop/vicenzo/rspec/dynamic_example_generation.rb
 - lib/rubocop/cop/vicenzo/rspec/inconsistent_sibling_structure.rb
 - lib/rubocop/cop/vicenzo/rspec/iteration_inside_example.rb
 - lib/rubocop/cop/vicenzo/rspec/leaky_definition.rb
+- lib/rubocop/cop/vicenzo/rspec/let_is_method_result.rb
+- 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