rubocop-vicenzo 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a18abf5413cb9807bf31adf6adeb6ac47e3fd0e7ec8cb2d47217db9b1617ed40
-  data.tar.gz: 871b1cb1de89c418517b67919402004ea95044aad2b1a8a0602ceb29953d1093
+  metadata.gz: 4f2fb87b8d1bfd10a66d52fcd5ede5f1eea78c7c2a8b7b8ea8a692d0efce54b6
+  data.tar.gz: aa25bb974ce70ab9ef752a1e36b83d779abded472022258a86ff8c2fdc483d77
 SHA512:
-  metadata.gz: c629161e84a929d57e0ef7fdec80d17a21742adc08c7f1bafb601356815e99862d987806bfced0e88fb5d1c085af35a4f0e6039dde7cdd664c635a51e9984110
-  data.tar.gz: 05ddcb76888e50820eda315fa63087c12a01ace730090bd5250f363a2a01b46e8277342ff903d371a5b5d6a0d8c9abcf28023a88caca421c7bfca558acbae110
+  metadata.gz: 57918353d578d8c2a5840617ccfefe7a996aad212dbce8921ae18a1bf302bf89fb6a5e40f6b9cdd97d082c4fb74d2e26fb2a9148d92e83fbb074e6c094da996b
+  data.tar.gz: be26bf4c722a8e351112c02d58bba96d06fd62fa230e8feb20e3f80675c82f6ca377875a53281df99d39ccabf8fc5de2822f9eff985a6c7a3cbe188dedd3ff6d

data/.release-please-manifest.json

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

data/CHANGELOG.md

@@ -1,4 +1,19 @@
-## [Unreleased]
+# 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)
+
+
+### Features
+
+* add RSpec cops against mutated and derived premises ([#26](https://github.com/bvicenzo/rubocop-vicenzo/issues/26)) ([b138dd0](https://github.com/bvicenzo/rubocop-vicenzo/commit/b138dd00a76e1bcd62e95c1f2c51dca5b4232319))
 
 ## [0.5.0] - 2026-06-29
 

data/CONTRIBUTING.md

@@ -0,0 +1,100 @@
+# Contributing
+
+## Development setup
+
+Run `bin/setup` once after cloning. It installs dependencies and points
+`core.hooksPath` at `.githooks/`, enabling a `commit-msg` hook that enforces
+Conventional Commits locally.
+
+Run the test suite and the linter with the default task — the same one CI runs:
+
+```bash
+bundle exec rake
+```
+
+## Commit messages — Conventional Commits
+
+This project follows [Conventional Commits](https://www.conventionalcommits.org/).
+The version bump and the `CHANGELOG.md` are generated automatically from commit
+messages, so the prefix matters:
+
+| Type | When to use | Release effect |
+|------|-------------|----------------|
+| `feat:` | New cop or user-facing capability | minor bump |
+| `fix:` | Bug fix in a cop or in the config | patch bump |
+| `feat!:` or a `BREAKING CHANGE:` footer | Backwards-incompatible change | minor bump while `0.x`, major from `1.0` on |
+| `chore:` `ci:` `docs:` `style:` `test:` `refactor:` | Maintenance | no release |
+
+Title format: `type: short description` (e.g.
+`feat: add Vicenzo/Style/JsonParseSymbolizeNames cop`).
+
+Pull requests are squash-merged, so **the PR title becomes the commit message
+release-please reads**. Get the title right even when the individual commits are
+messy.
+
+## Adding a new cop
+
+Generate the cop, its spec and its `config/default.yml` entry with:
+
+```bash
+bundle exec rake 'new_cop[Vicenzo/Department/CopName]'
+```
+
+The generator writes `VersionAdded: '<<next>>'` into `config/default.yml`. Leave
+that placeholder alone — never replace it with a version by hand. The release
+workflow fills it in with the version being released (see below).
+
+## Releasing (release-please)
+
+Releases are automated with [release-please](https://github.com/googleapis/release-please):
+
+1. Every push to `master` creates or updates a **release PR** titled
+   `chore(master): release X.Y.Z`. It bumps
+   `lib/rubocop/vicenzo/version.rb`, `.release-please-manifest.json`,
+   `Gemfile.lock` and the version in the `README.md` install snippet, and updates
+   `CHANGELOG.md` from the Conventional Commits made since the last release.
+2. New cops are added with `VersionAdded: '<<next>>'`. The release workflow
+   replaces every `<<next>>` in `config/default.yml` with the version being
+   released, directly on the release PR — no manual editing needed. This matters
+   because `rake docs:generate` reads `VersionAdded` to build the "Version Added"
+   column of the documentation site.
+3. **Merging the release PR** creates the git tag `vX.Y.Z` and a GitHub Release.
+   That in turn triggers two things automatically:
+   - `.github/workflows/publish.yml` publishes the gem to RubyGems via
+     [Trusted Publishing](https://guides.rubygems.org/trusted-publishing/) (OIDC,
+     no API key stored in the repository).
+   - `.github/workflows/docs.yml` rebuilds and deploys the documentation site to
+     GitHub Pages, because `lib/rubocop/vicenzo/version.rb` changed.
+4. The release PR always reflects **everything on `master` since the last
+   release**. Cut releases promptly: merge the release PR before landing
+   unrelated new work you don't want included in that release.
+
+Nothing about a release is done by hand — there is no `rake release` to run
+locally and no version to edit yourself.
+
+## If the release PR is failing
+
+release-please only rebuilds the release branch when a **releasable** commit
+(`feat:` / `fix:`) lands on `master`. Non-releasable fixes (`chore:`, `style:`,
+`ci:`, `docs:`, `test:`) do **not** rebuild it, so the release branch can fall
+behind `master` and its CI can run stale code.
+
+When the release PR's CI is red:
+
+1. Push the fix to `master` through a normal PR. **Never** push directly to the
+   `release-please--…` branch — release-please overwrites it.
+2. If those fix commits are non-releasable (so the release PR won't refresh on
+   its own), **close the release PR and delete its branch**. On the next push to
+   `master`, release-please recreates the release PR from the current `master`
+   (now including the fix) and its CI passes.
+3. Merge the freshly recreated release PR.
+
+Never manually rebase or force-push the release-please branch.
+
+## If the gem was not published
+
+The tag and the GitHub Release already exist, so publishing is retryable: fix the
+cause and use **Re-run jobs** on the failed `Publish gem` workflow run. An
+authentication failure points at the trusted publisher registration on RubyGems
+(the repository or the workflow filename must match `publish.yml`), not at the
+workflow itself.

data/README.md

@@ -6,7 +6,20 @@
 
 ## Installation
 
-Install the gem and add to the application's Gemfile by executing:
+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
+end
+```
+<!-- x-release-please-end-version -->
+
+> The version above is kept current automatically on every release; pin to
+> whichever version you prefer.
+
+Or let Bundler add the latest version for you:
 
 ```bash
 bundle add rubocop-vicenzo --group=development --require=false
@@ -55,7 +68,13 @@ rubocop --plugin rubocop-vicenzo
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+Releases are automated: the version, the `CHANGELOG.md`, the git tag and the push
+to [rubygems.org](https://rubygems.org) are all derived from
+[Conventional Commits](https://www.conventionalcommits.org/) by release-please.
+There is no version to edit and no release command to run by hand — see
+[CONTRIBUTING.md](CONTRIBUTING.md).
 
 ### Documentation
 
@@ -92,7 +111,7 @@ bundle exec rake 'new_cop[Vicenzo/OptionalNamespace/CopName]'
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/rubocop-vicenzo. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/rubocop-vicenzo/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/bvicenzo/rubocop-vicenzo. Read [CONTRIBUTING.md](CONTRIBUTING.md) first — it covers the commit conventions the release automation depends on. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/bvicenzo/rubocop-vicenzo/blob/master/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -100,4 +119,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Rubocop::Vicenzo project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/rubocop-vicenzo/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Rubocop::Vicenzo project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/bvicenzo/rubocop-vicenzo/blob/master/CODE_OF_CONDUCT.md).

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
@@ -22,6 +34,17 @@ Vicenzo/RSpec/ConditionalInSpec:
     - '**/spec/factories/**/*'
   VersionAdded: '0.4.0'
 
+Vicenzo/RSpec/DerivedPremises:
+  Description: 'Do not derive a premise from another premise; declare the complete value where it is needed.'
+  Enabled: true
+  Severity: warning
+  Include:
+    - '**/spec/**/*_spec.rb'
+  Exclude:
+    - '**/spec/support/**/*'
+    - '**/spec/factories/**/*'
+  VersionAdded: '0.6.0'
+
 Vicenzo/RSpec/DynamicExampleGeneration:
   Description: 'Do not use iteration to dynamically generate example groups or examples.'
   Enabled: true
@@ -40,6 +63,17 @@ Vicenzo/RSpec/IterationInsideExample:
   Severity: warning
   VersionAdded: '0.4.0'
 
+Vicenzo/RSpec/MutatedPremises:
+  Description: 'Do not mutate the premises (let, let_it_be, subject) an example starts from.'
+  Enabled: true
+  Severity: warning
+  Include:
+    - '**/spec/**/*_spec.rb'
+  Exclude:
+    - '**/spec/support/**/*'
+    - '**/spec/factories/**/*'
+  VersionAdded: '0.6.0'
+
 Vicenzo/RSpec/NestedContextImproperStart:
   Description: 'Check if the nested context does not start as a root one.'
   Enabled: true
@@ -69,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/derived_premises.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative 'mixin/premise_tracking'
+
+module RuboCop
+  module Cop
+    module Vicenzo
+      module RSpec
+        # Do not derive a premise from another premise.
+        #
+        # `let(:params) { base_params.merge(age: 10) }` does not mutate anything, but it splits a single premise
+        # across two definitions: to know what `params` holds in a context you have to read another `let` — usually
+        # one that exists only to be modified. Declare the complete value in the context that needs it.
+        #
+        # Only premise definitions (`let`, `let_it_be`, `subject`) are inspected, and only when the copy starts from
+        # another premise: deriving from a factory or from a literal is untouched.
+        #
+        # @example
+        #   # bad
+        #
+        #   let(:base_params) { { name: 'Ada' } }
+        #   let(:params) { base_params.merge(age: 10) }
+        #
+        #   # good
+        #
+        #   context 'when the age is informed' do
+        #     let(:params) { { name: 'Ada', age: 10 } }
+        #   end
+        #
+        #   context 'when the age is unknown' do
+        #     let(:params) { { name: 'Ada' } }
+        #   end
+        #
+        # @example
+        #   # good — the source is a factory, not another premise
+        #
+        #   let(:params) { attributes_for(:order).merge(value: 10) }
+        class DerivedPremises < RuboCop::Cop::RSpec::Base
+          include PremiseTracking
+
+          MSG = 'Do not derive the premise `%<name>s` from `%<source>s`. ' \
+                'Declare the complete value in the context that needs it.'
+
+          DERIVING_METHODS = %i[merge deep_merge reverse_merge dup clone except slice].freeze
+
+          def on_block(node)
+            return unless example_group?(node) && outermost_example_group?(node)
+
+            walk_example_group(node, all_premises(node))
+          end
+
+          alias on_numblock on_block
+
+          private
+
+          def on_premise(node, premises)
+            name = premise_name(node)
+
+            mutating_calls(node).each do |call|
+              next unless DERIVING_METHODS.include?(call.method_name)
+
+              source = premise_receiver(call, premises)
+
+              next if source.nil?
+
+              add_offense(call, message: format(MSG, name:, source:))
+            end
+          end
+
+          def on_setup_hook(node, premises); end
+        end
+      end
+    end
+  end
+end

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

@@ -14,7 +14,7 @@ module RuboCop
         # @example
         #   # bad
         #
-        #   [:admin, :driver].each do |role|
+        #   [:admin, :editor].each do |role|
         #     context "when role is #{role}" do
         #       it 'does something' do
         #         ...
@@ -32,8 +32,8 @@ module RuboCop
         #     end
         #   end
         #
-        #   context 'when role is driver' do
-        #     let(:role) { :driver }
+        #   context 'when role is editor' do
+        #     let(:role) { :editor }
         #
         #     it 'does something' do
         #       ...

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

@@ -16,27 +16,27 @@ module RuboCop
         # @example
         #   # bad — expect is called inside the iteration
         #
-        #   it 'returns vehicle costs general values' do
-        #     response_body[:vehicle_costs].first.each do |attribute, value|
-        #       expect(value).to eq(vehicle_cost.send(attribute).to_s)
+        #   it 'returns product prices general values' do
+        #     response_body[:product_prices].first.each do |attribute, value|
+        #       expect(value).to eq(product_price.send(attribute).to_s)
         #     end
         #   end
         #
         #   # good — iteration builds data, expect is called once outside
         #
         #   it 'returns the expected column names' do
-        #     columns = VehicleCost.column_names.map { |column| column.gsub('_centavos', '') }
-        #     expect(response_body[:vehicle_costs].first.keys).to match_array(columns.map(&:to_sym))
+        #     columns = ProductPrice.column_names.map { |column| column.gsub('_cents', '') }
+        #     expect(response_body[:product_prices].first.keys).to match_array(columns.map(&:to_sym))
         #   end
         #
         #   # good — each attribute has an explicit example
         #
         #   it 'returns the correct name' do
-        #     expect(response_body[:vehicle_costs].first[:name]).to eq(vehicle_cost.name)
+        #     expect(response_body[:product_prices].first[:name]).to eq(product_price.name)
         #   end
         #
         #   it 'returns the correct value' do
-        #     expect(response_body[:vehicle_costs].first[:value]).to eq(vehicle_cost.value.to_s)
+        #     expect(response_body[:product_prices].first[:value]).to eq(product_price.value.to_s)
         #   end
         class IterationInsideExample < RuboCop::Cop::RSpec::Base
           MSG = 'Do not call `expect` inside an iteration. ' \