rubocop-vicenzo 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5b82e09fef23aac921adb4f653bfbdc1117af279326d24339f68db8abe25ffd
-  data.tar.gz: f5f4d255aacd3851e4f8b7968b663d22db0b0ed9be99bab01a17df43d819c80f
+  metadata.gz: 4f2fb87b8d1bfd10a66d52fcd5ede5f1eea78c7c2a8b7b8ea8a692d0efce54b6
+  data.tar.gz: aa25bb974ce70ab9ef752a1e36b83d779abded472022258a86ff8c2fdc483d77
 SHA512:
-  metadata.gz: 79d36dbf73503ca38cca4d5ffd77fd84d56cf4b8d320ff389035c359116e36d66d15a3aad4fd3de10d9787fe29f4b4af66b0b669ce98754415fac8ad954106fa
-  data.tar.gz: 84055ca6301311a752670e04fa5fcd9646fc38844993428a5f952be17a7384cfa5842b9a2daaa7f3be3242d70e0641b7ba02fdd718fee111f995bd1cd4a8b3e0
+  metadata.gz: 57918353d578d8c2a5840617ccfefe7a996aad212dbce8921ae18a1bf302bf89fb6a5e40f6b9cdd97d082c4fb74d2e26fb2a9148d92e83fbb074e6c094da996b
+  data.tar.gz: be26bf4c722a8e351112c02d58bba96d06fd62fa230e8feb20e3f80675c82f6ca377875a53281df99d39ccabf8fc5de2822f9eff985a6c7a3cbe188dedd3ff6d

data/.release-please-manifest.json

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

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [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.7.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,42 @@ 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/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/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_cops.rb

@@ -1,15 +1,19 @@
 # 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/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.7.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.7.0
 platform: ruby
 authors:
 - Bruno Vicenzo
@@ -75,17 +75,23 @@ 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/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/style/json_parse_symbolize_names.rb
 - lib/rubocop/cop/vicenzo/style/multiline_method_call_parentheses.rb
 - lib/rubocop/cop/vicenzo_cops.rb