rubocop-gusto 11.0.0 → 11.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b642214b2077302ad9ab6e076c66534fe49cfcda33a411b87b9c4b34df8f8b43
-  data.tar.gz: d9a653b4e27f33467921f5a2ffb520e2cc8b3a65f58e7cb4bb888611cea3e69d
+  metadata.gz: 5814e91aac6e402768ff64bd32f0c196838e20d90cbd927286238f68bb9d25b9
+  data.tar.gz: d4e988b9973101b7ea9a683900ae7489cbfe128b681d4137c7317f06a45cc247
 SHA512:
-  metadata.gz: 876ba0b9f58929c28d77c71a370833670b27e0d55ecf8ab937f2882824db8b0da4ba2294a0649f2e54fdf7687b393d6c79be86da874a38d555b4190291c8a36b
-  data.tar.gz: fe18184e9f77db188cbbdc77a5274fbe624d664e73ec97a2b5eec130b3753dd6323e5192e98441fe7832d166e2c8980e0d6231494f4d54b0317a9cb18aae9ee5
+  metadata.gz: 82385ed24fdf344897513f4f034e1f8ae662a5d41b62ccc8dc2c14e735d479deb31acf4c28047fbad1f59d828485798a4677148ca203989f15489d768cb88995
+  data.tar.gz: 403192785be424b372d709d2c7d9bac18491603c2a9449a2edeb5b35c981652e7ee87c307265a381b51d5285134fda5a0178adb04087bb6d2db7c10b51d41ae9

data/CHANGELOG.md

@@ -3,6 +3,14 @@
 - Remove redundant `Rails: Enabled: true` from `config/rails.yml` (already set by rubocop-rails' own defaults)
 - Enable `Rails/DefaultScope` cop (disabled by default in rubocop-rails)
 
+## [11.1.0](https://github.com/Gusto/rubocop-gusto/compare/v11.0.0...v11.1.0) (2026-06-17)
+
+
+### Features
+
+* add `Sidekiq/PerformAsyncStub` in a separate config ([#131](https://github.com/Gusto/rubocop-gusto/issues/131)) ([22670d4](https://github.com/Gusto/rubocop-gusto/commit/22670d4a34487417bdb50b8be25e82fb0cac3614))
+* add cops-only entrypoints for selective adoption ([#132](https://github.com/Gusto/rubocop-gusto/issues/132)) ([f0911c2](https://github.com/Gusto/rubocop-gusto/commit/f0911c2f9fc6d272bc8ccb5af830daf659c6ba62))
+
 ## [11.0.0](https://github.com/Gusto/rubocop-gusto/compare/v10.10.0...v11.0.0) (2026-06-08)
 
 

data/README.md

@@ -28,15 +28,31 @@ $ bundle
 bundle exec rubocop-gusto init
 ```
 
-This adds `rubocop-gusto` to your `.rubocop.yml` `plugins:` list and includes any relevant configuration (e.g. Rails-specific rules when Rails is detected).
+This adds `rubocop-gusto` to your `.rubocop.yml` `plugins:` list and includes any relevant configuration (e.g. Rails-specific rules when Rails is detected, Sidekiq-specific rules when the Sidekiq gem is present).
 
 If this is an existing project, it is recommended to run the autocorrector (`bundle exec rubocop -a`) and then to regenerate the `.rubocop_todo.yml` (`bundle exec rubocop --auto-gen-config`), so issues can be dealt with piecemeal.
 
+#### Sidekiq configuration
+
+Sidekiq-specific cops live in `config/sidekiq.yml` and are **not** included in `config/default.yml`, so projects without Sidekiq are not linted for those patterns. Running `bundle exec rubocop-gusto init` adds `config/sidekiq.yml` to your `inherit_gem` list automatically when Sidekiq is listed in your `Gemfile` or `Gemfile.lock`.
+
+For an existing project that already uses Sidekiq, add the Sidekiq config to your `.rubocop.yml`:
+
+```yaml
+inherit_gem:
+  rubocop-gusto:
+    - config/default.yml
+    - config/sidekiq.yml
+```
+
+If your project also uses Rails, include `config/rails.yml` as well (order does not matter). Re-run `bundle exec rubocop-gusto init` to merge this in automatically.
+
 ### Available cops
 
 Custom cops live under the following namespaces:
 
 - `Gusto/` — general Gusto-specific cops (see [`lib/rubocop/cop/gusto/`](lib/rubocop/cop/gusto/))
+- `Sidekiq/` — cops scoped to Sidekiq patterns (see [`lib/rubocop/cop/sidekiq/`](lib/rubocop/cop/sidekiq/)); configured in [`config/sidekiq.yml`](config/sidekiq.yml)
 - `Rack/` — cops scoped to Rack middleware patterns (see [`lib/rubocop/cop/rack/`](lib/rubocop/cop/rack/))
 
 ## Publishing New Versions
@@ -66,7 +82,7 @@ PR titles must use [Conventional Commits](https://www.conventionalcommits.org/)
 
 ### Adding a new cop
 
-1. Create `lib/rubocop/cop/gusto/<cop_name>.rb`
+1. Create `lib/rubocop/cop/gusto/<cop_name>.rb`, see [how to create a new cop](https://docs.rubocop.org/rubocop/latest/development.html#create-a-new-cop) and [how to choose a name](https://docs.rubocop.org/rubocop-rspec/development.html#choose-a-name)
 2. Add an entry to `config/default.yml`, then sort it:
    ```sh
    bundle exec rubocop-gusto sort config/default.yml

data/config/default.yml

@@ -1,3 +1,5 @@
+inherit_from: gusto_cops.yml
+
 plugins:
   - rubocop-rspec
   - rubocop-performance
@@ -30,135 +32,6 @@ Gemspec/RequiredRubyVersion:
   # We manage our Ruby version in our version file and import that to our Gemfile.
   Enabled: false
 
-Gusto/BootsnapLoadFile:
-  Description: 'Do not use Bootsnap to load files. Use `require` instead.'
-
-Gusto/DatadogConstant:
-  Exclude:
-    # calling DataDog directly only allowed in initializers, its library, and tests
-    - 'config/application.rb'
-    - 'config/initializers/datadog.rb'
-    - 'lib/datadog/**/*'
-    - '**/spec/**/*'
-  Description: 'Do not call Datadog directly, use an appropriate wrapper library.'
-
-Gusto/DescribedClassConstantReference:
-  Description: 'Flags constants scoped through `described_class` (e.g. `described_class::Foo`), which Sorbet cannot resolve statically.'
-  Enabled: true
-  SafeAutoCorrect: false
-  Include:
-    - '**/spec/**/*'
-
-Gusto/DiscouragedGem:
-  Description: 'Flags installation of discouraged gems in Gemfiles and gemspecs.'
-  Enabled: false
-  Gems: {}
-
-Gusto/ExecuteMigration:
-  Description: "Don't use `execute` in migrations. Use a backfill rake task instead."
-  Include:
-    - 'db/migrate/*.rb'
-
-Gusto/FactoryClassesOrModules:
-  Description: 'Do not define modules or classes in factory directories - they break reloading.'
-  Include:
-    - 'spec/**/factories/*.rb'
-
-Gusto/MinByMaxBy:
-  Description: 'Checks for the use of `min` or `max` with a proc. Corrects to `min_by` or `max_by`.'
-  Safe: false
-  Severity: error
-
-Gusto/NoMetaprogramming:
-  Description: 'Avoid using metaprogramming techniques like define_method and instance_eval which make code harder to understand and debug.'
-
-Gusto/NoRescueErrorMessageChecking:
-  Description: 'Checks for the presence of error message checking within rescue blocks.'
-
-Gusto/NoSend:
-  Description: 'Do not call a private method via `__send__`.'
-  Exclude:
-    - '**/spec/**/*'
-
-Gusto/PaperclipOrAttachable:
-  Description: 'No more new paperclip or Attachable are allowed. Use ActiveStorage instead.'
-
-Gusto/PerformClassMethod:
-  Description: 'Prevents accidental definition of `perform` class methods (should be instance methods instead).'
-  # List of modules that include Sidekiq::Worker.
-  # Add your other base modules here if they include Sidekiq::Worker too.
-  WorkerModules:
-    - Sidekiq::Worker
-
-Gusto/PolymorphicTypeValidation:
-  Description: 'Ensures that polymorphic relations include a type validation, which is necessary for generating Sorbet types.'
-  Include:
-    - '**/models/**/*.rb'
-
-Gusto/PreferProcessLastStatus:
-  Description: 'Prefer using `Process.last_status` instead of the global variables: `$?` and `$CHILD_STATUS`.'
-
-Gusto/RablExtends:
-  Description: 'Disallows the use of `extends` in Rabl templates due to poor caching performance. Inline the templating to generate your JSON instead.'
-  Include:
-    - '**/*.json.rabl'
-
-Gusto/RailsEnv:
-  Description: 'Use Feature Flags or config instead of `Rails.env`.'
-
-Gusto/RakeConstants:
-  Description: 'Do not define a constant in rake file, because they are sometimes `load`ed, instead of `require`d which can lead to warnings about redefining constants.'
-  Include:
-    - '**/*.rake'
-    - 'Rakefile'
-
-Gusto/RegexpBypass:
-  Description: 'Ensures regular expressions use \A and \z anchors instead of ^ and $ for security validation.'
-  Exclude:
-    - '**/spec/**/*'
-  Safe: false
-
-Gusto/RspecDateTimeMock:
-  Description: "Don't mock Date/Time/DateTime directly. Use Rails Testing Time Helpers (eg `freeze_time` and `travel_to`) instead."
-  Include:
-    - '**/spec/**/*'
-  Safe: false
-
-Gusto/SidekiqParams:
-  Description: 'Sidekiq perform methods cannot take keyword arguments.'
-
-Gusto/ToplevelConstants:
-  Description: 'Prevents top-level constants from being defined outside of initializers.'
-  Include:
-    - '**/*.rb'
-  Exclude:
-    - '**/bin/*'
-    - 'bin/*'
-    - 'config/**/*'
-    - 'lib/*.rb'
-    - 'packs/**/{db/seeds,lib,config/initializers}/**/*'
-    - 'script/**/*'
-    - 'spec/rails_helper.rb'
-    - '**/spec/support/**/*'
-    - '**/*/spec_helper.rb'
-    - 'spec/support/**/*.rb'
-
-Gusto/UnreferencedLet:
-  Description: 'Removes a lazy let whose name is never referenced (its block never runs).'
-  Enabled: true
-  Include:
-    - '**/spec/**/*_spec.rb'
-  # Deletion is unsafe (explicit -A required, never applied on a plain run): the cop is heuristic
-  # and cannot see references made across files via shared examples or included harnesses.
-  SafeAutoCorrect: false
-
-Gusto/UsePaintNotColorize:
-  Description: 'Use Paint instead of colorize for terminal colors.'
-  SafeAutoCorrect: false
-
-Gusto/VcrRecordings:
-  Description: 'VCR should be set to not record in tests. Use vcr: {record: :none}.'
-
 Layout/BlockAlignment:
   EnforcedStyleAlignWith: start_of_block
 
@@ -389,6 +262,13 @@ Rack/LowercaseHeaderKeys:
 Rake/ClassDefinitionInTask:
   Enabled: false
 
+Sidekiq/PerformAsyncStub:
+  Description: 'Prefer checking enqueued jobs over stubbing `perform_async`.'
+  Enabled: false
+  SafeAutoCorrect: false # Autocorrect appends `.and_call_original`, which runs real `perform_async` during the example
+  Include:
+    - '**/spec/**/*_spec.rb'
+
 Sorbet/ForbidTUnsafe:
   # T.unsafe completely disables typechecking. Prefer T.cast, shims, or
   # reorganizing the code over silently turning off the type checker.

data/config/gusto_cops.yml

@@ -0,0 +1,135 @@
+# Gusto cop defaults only — no built-in cop overrides.
+# Use this with `inherit_gem` when you want Gusto cop scoping (Include/Exclude/Severity)
+# without inheriting rubocop-gusto's full configuration layer.
+#
+# In your .rubocop.yml:
+#   require:
+#     - rubocop/cop/gusto/all
+#   inherit_gem:
+#     rubocop-gusto:
+#       - config/gusto_cops.yml
+
+Gusto/BootsnapLoadFile:
+  Description: 'Do not use Bootsnap to load files. Use `require` instead.'
+
+Gusto/DatadogConstant:
+  Exclude:
+    # calling DataDog directly only allowed in initializers, its library, and tests
+    - 'config/application.rb'
+    - 'config/initializers/datadog.rb'
+    - 'lib/datadog/**/*'
+    - '**/spec/**/*'
+  Description: 'Do not call Datadog directly, use an appropriate wrapper library.'
+
+Gusto/DescribedClassConstantReference:
+  Description: 'Flags constants scoped through `described_class` (e.g. `described_class::Foo`), which Sorbet cannot resolve statically.'
+  Enabled: true
+  SafeAutoCorrect: false
+  Include:
+    - '**/spec/**/*'
+
+Gusto/DiscouragedGem:
+  Description: 'Flags installation of discouraged gems in Gemfiles and gemspecs.'
+  Enabled: false
+  Gems: {}
+
+Gusto/ExecuteMigration:
+  Description: "Don't use `execute` in migrations. Use a backfill rake task instead."
+  Include:
+    - 'db/migrate/*.rb'
+
+Gusto/FactoryClassesOrModules:
+  Description: 'Do not define modules or classes in factory directories - they break reloading.'
+  Include:
+    - 'spec/**/factories/*.rb'
+
+Gusto/MinByMaxBy:
+  Description: 'Checks for the use of `min` or `max` with a proc. Corrects to `min_by` or `max_by`.'
+  Safe: false
+  Severity: error
+
+Gusto/NoMetaprogramming:
+  Description: 'Avoid using metaprogramming techniques like define_method and instance_eval which make code harder to understand and debug.'
+
+Gusto/NoRescueErrorMessageChecking:
+  Description: 'Checks for the presence of error message checking within rescue blocks.'
+
+Gusto/NoSend:
+  Description: 'Do not call a private method via `__send__`.'
+  Exclude:
+    - '**/spec/**/*'
+
+Gusto/PaperclipOrAttachable:
+  Description: 'No more new paperclip or Attachable are allowed. Use ActiveStorage instead.'
+
+Gusto/PerformClassMethod:
+  Description: 'Prevents accidental definition of `perform` class methods (should be instance methods instead).'
+  WorkerModules:
+    - Sidekiq::Worker
+
+Gusto/PolymorphicTypeValidation:
+  Description: 'Ensures that polymorphic relations include a type validation, which is necessary for generating Sorbet types.'
+  Include:
+    - '**/models/**/*.rb'
+
+Gusto/PreferProcessLastStatus:
+  Description: 'Prefer using `Process.last_status` instead of the global variables: `$?` and `$CHILD_STATUS`.'
+
+Gusto/RablExtends:
+  Description: 'Disallows the use of `extends` in Rabl templates due to poor caching performance. Inline the templating to generate your JSON instead.'
+  Include:
+    - '**/*.json.rabl'
+
+Gusto/RailsEnv:
+  Description: 'Use Feature Flags or config instead of `Rails.env`.'
+
+Gusto/RakeConstants:
+  Description: 'Do not define a constant in rake file, because they are sometimes `load`ed, instead of `require`d which can lead to warnings about redefining constants.'
+  Include:
+    - '**/*.rake'
+    - 'Rakefile'
+
+Gusto/RegexpBypass:
+  Description: 'Ensures regular expressions use \A and \z anchors instead of ^ and $ for security validation.'
+  Exclude:
+    - '**/spec/**/*'
+  Safe: false
+
+Gusto/RspecDateTimeMock:
+  Description: "Don't mock Date/Time/DateTime directly. Use Rails Testing Time Helpers (eg `freeze_time` and `travel_to`) instead."
+  Include:
+    - '**/spec/**/*'
+  Safe: false
+
+Gusto/SidekiqParams:
+  Description: 'Sidekiq perform methods cannot take keyword arguments.'
+
+Gusto/ToplevelConstants:
+  Description: 'Prevents top-level constants from being defined outside of initializers.'
+  Include:
+    - '**/*.rb'
+  Exclude:
+    - '**/bin/*'
+    - 'bin/*'
+    - 'config/**/*'
+    - 'lib/*.rb'
+    - 'packs/**/{db/seeds,lib,config/initializers}/**/*'
+    - 'script/**/*'
+    - 'spec/rails_helper.rb'
+    - '**/spec/support/**/*'
+    - '**/*/spec_helper.rb'
+    - 'spec/support/**/*.rb'
+
+Gusto/UnreferencedLet:
+  Description: 'Removes a lazy let whose name is never referenced (its block never runs).'
+  Enabled: true
+  Include:
+    - '**/spec/**/*_spec.rb'
+  SafeAutoCorrect: false
+
+Gusto/UsePaintNotColorize:
+  Description: 'Use Paint instead of colorize for terminal colors.'
+  SafeAutoCorrect: false
+
+Gusto/VcrRecordings:
+  Description: 'VCR should be set to not record in tests. Use vcr: {record: :none}.'

data/config/sidekiq.yml

@@ -0,0 +1,7 @@
+#
+# This file should be inherited alongside default.yml for projects using Sidekiq
+#
+# After you add a rule, sort this file with `bundle exec rubocop-gusto sort config/sidekiq.yml`
+
+Sidekiq/PerformAsyncStub:
+  Enabled: true

data/lib/rubocop/cop/gusto/all.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "rubocop"
+require_relative "../../gusto"
+require_relative "../../gusto/version"
+
+Dir.glob("#{__dir__}/*.rb").each { |f| require f unless f == __FILE__ }

data/lib/rubocop/cop/gusto/bootsnap_load_file.rb

@@ -3,7 +3,17 @@
 module RuboCop
   module Cop
     module Gusto
-      # Do not use Bootsnap to load files. Use `require` instead.
+      # Prefer `YAML.load_file`/`JSON.load_file` over reading a file and then
+      # parsing its contents. Bootsnap caches the parsed result of `load_file`,
+      # so this improves load time.
+      #
+      # @example
+      #   # bad
+      #   YAML.load(File.read("config.yml"))
+      #   File.open("config.yml") { |f| YAML.load(f) }
+      #
+      #   # good
+      #   YAML.load_file("config.yml")
       class BootsnapLoadFile < Base
         PROHIBITED_CONSTANTS = Set[:YAML, :JSON].freeze
         RESTRICT_ON_SEND = %i(load).freeze

data/lib/rubocop/cop/gusto/datadog_constant.rb

@@ -3,6 +3,16 @@
 module RuboCop
   module Cop
     module Gusto
+      # Disallow referencing the `Datadog` constant directly. Calls should go
+      # through an approved wrapper library so instrumentation stays consistent
+      # and swappable.
+      #
+      # @example
+      #   # bad
+      #   Datadog::Tracing.active_trace
+      #
+      #   # good
+      #   Observability.active_trace
       class DatadogConstant < Base
         MSG = "Do not call Datadog directly, use an appropriate wrapper library."
         NAMESPACE = "Datadog"

data/lib/rubocop/cop/gusto/discouraged_gem.rb

@@ -3,13 +3,16 @@
 module RuboCop
   module Cop
     module Gusto
-      # Flags installation of discouraged gems (e.g., timecop) in Gemfiles and gemspecs.
+      # Flag installation of discouraged gems (e.g. timecop) in Gemfiles and
+      # gemspecs. The discouraged gems an advice about alternatives are configured under
+      # `Gems:`; intended to be enabled in Rails projects via config/rails.yml.
       #
-      # Configuration:
-      #   Gems:
-      #     timecop: "Use Rails' time helpers (e.g., freeze_time, travel_to) instead of Timecop."
+      # @example Gems: { timecop: "Use Rails' time helpers instead of Timecop." }
+      #   # bad
+      #   gem "timecop"
       #
-      # This cop is intended to be enabled in Rails projects via config/rails.yml.
+      #   # good
+      #   # Use Rails' time helpers (freeze_time, travel_to) instead.
       class DiscouragedGem < Base
         MSG = "Avoid using the '%{gem}' gem. %{advice}"
 

data/lib/rubocop/cop/gusto/execute_migration.rb

@@ -3,6 +3,20 @@
 module RuboCop
   module Cop
     module Gusto
+      # Disallow `execute` (raw SQL) in migrations. Run raw SQL from a backfill
+      # rake task, or pass SQL options to `add_column`/`change_column` instead,
+      # so migrations stay reversible and schema-focused.
+      #
+      # @example
+      #   # bad
+      #   def up
+      #     execute("UPDATE users SET active = true")
+      #   end
+      #
+      #   # good
+      #   def up
+      #     add_column :users, :active, :boolean, default: true
+      #   end
       class ExecuteMigration < Base
         MSG = "Do not use `execute` to run raw SQL in a migration. Run the query from a backfill rake task or pass the SQL options to the `add_column`/`change_column` method."
         RESTRICT_ON_SEND = [:execute].freeze

data/lib/rubocop/cop/gusto/factory_classes_or_modules.rb

@@ -3,6 +3,24 @@
 module RuboCop
   module Cop
     module Gusto
+      # Disallow defining classes or modules in factory directories. They break
+      # Rails autoloading/reloading; define shared helpers outside the factories.
+      #
+      # @example
+      #   # bad
+      #   # spec/factories/users.rb
+      #   class UserHelper
+      #   end
+      #
+      #   FactoryBot.define do
+      #     factory :user
+      #   end
+      #
+      #   # good
+      #   # spec/factories/users.rb
+      #   FactoryBot.define do
+      #     factory :user
+      #   end
       class FactoryClassesOrModules < Base
         MSG = "Do not define modules or classes in factory directories - they break reloading"
 

data/lib/rubocop/cop/gusto/paperclip_or_attachable.rb

@@ -4,6 +4,15 @@
 module RuboCop
   module Cop
     module Gusto
+      # Disallow new Paperclip / Attachable attachments. New attachments should
+      # use ActiveStorage instead.
+      #
+      # @example
+      #   # bad
+      #   has_attached_file :avatar
+      #
+      #   # good
+      #   has_one_attached :avatar
       class PaperclipOrAttachable < Base
         MSG = "No more new paperclip or Attachable are allowed. New attachments should use ActiveStorage instead"
         RESTRICT_ON_SEND = %i(has_attached_file has_pdf_attachment has_attachment).freeze

data/lib/rubocop/cop/gusto/polymorphic_type_validation.rb

@@ -1,11 +1,26 @@
 # frozen_string_literal: true
 
-# This cop enforces that polymorphic relations have a corresponding validation
-# for their type field with an inclusion validation. This is required in order for Tapioca
-# to generate correct Sorbet types
 module RuboCop
   module Cop
     module Gusto
+      # Require polymorphic relations to validate their `*_type` field with an
+      # inclusion validation (or `polymorphic_methods_for`). This is needed for
+      # Tapioca to generate correct Sorbet types.
+      #
+      # @example
+      #   # bad
+      #   belongs_to :subscription_detail, polymorphic: true
+      #
+      #   # good
+      #   VALID_TYPES = T.let([Foo.polymorphic_name, Bar.polymorphic_name].freeze, T::Array[String])
+      #   belongs_to :subscription_detail, polymorphic: true
+      #   validates :subscription_detail_type, presence: true, inclusion: { in: VALID_TYPES }
+      #
+      #   # also good
+      #   include PolymorphicCallable
+      #   VALID_TYPES = T.let([Foo.polymorphic_name, Bar.polymorphic_name].freeze, T::Array[String])
+      #   belongs_to :subscription_detail, polymorphic: true
+      #   polymorphic_methods_for :subscription_detail, VALID_TYPES
       class PolymorphicTypeValidation < Base
         RESTRICT_ON_SEND = %i(belongs_to validates polymorphic_methods_for).freeze
 

data/lib/rubocop/cop/gusto/sidekiq_params.rb

@@ -3,6 +3,18 @@
 module RuboCop
   module Cop
     module Gusto
+      # Disallow keyword arguments on Sidekiq `perform` methods. Sidekiq
+      # serializes job arguments as JSON and replays them positionally, so
+      # keyword arguments are not preserved.
+      #
+      # @example
+      #   # bad
+      #   def perform(user_id:, force: false)
+      #   end
+      #
+      #   # good
+      #   def perform(user_id, force = false)
+      #   end
       class SidekiqParams < Base
         MSG = "Sidekiq perform methods cannot take keyword arguments"
 

data/lib/rubocop/cop/gusto/unreferenced_let.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "open3"
+require "rubocop-rspec"
 
 module RuboCop
   module Cop
@@ -54,7 +55,7 @@ module RuboCop
         extend AutoCorrector
         include RangeHelp
 
-        DEFINITION_METHODS = %i(let let! subject).freeze
+        DEFINITION_METHODS = Set[:let, :let!, :subject].freeze
         # `let`s consumed by a test framework rather than by a reference in the spec file. The
         # rubocop-rspec `:config` shared context reads `cop_config`, so it is live even though the
         # spec never names it.
@@ -80,7 +81,7 @@ module RuboCop
         # `subject` that overrides a `let` of the same name) are never flagged.
         # @!method definition_name(node)
         def_node_matcher :definition_name, <<~PATTERN
-          (any_block (send nil? {#{DEFINITION_METHODS.map { ":#{it}" }.join(' ')}} (sym $_) ...) ...)
+          (any_block (send nil? %DEFINITION_METHODS (sym $_) ...) ...)
         PATTERN
 
         class << self

data/lib/rubocop/cop/sidekiq/perform_async_stub.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Sidekiq
+      # Checks that `perform_async` calls to enqueue Sidekiq jobs are not stubbed
+      #
+      # @example
+      #   # bad
+      #   allow(Foo).to receive(:perform_async)
+      #   expect(Foo).to receive(:perform_async)
+      #   expect(Foo).not_to receive(:perform_async)
+      #
+      #   # good (still invokes the real method)
+      #   allow(Foo).to receive(:perform_async).and_call_original
+      #   expect(Foo).to receive(:perform_async).with(arg).and_call_original
+      #   allow(Foo).to receive(:perform_async).and_wrap_original { |m, *args| m.call(*args) }
+      #
+      #   # good (checking enqueued jobs)
+      #   expect { subject }.to change(Foo.jobs, :count).by(n)
+      #   expect { subject }.not_to change(Foo.jobs, :count)
+      #   expect(Foo.jobs.count).to eq(n)
+      #
+      #   # good (only checks previously pre-stubbed objects)
+      #   expect(Foo).to have_received(:perform_async)
+      #
+      # @safety
+      #   Autocorrect is unsafe: it appends `.and_call_original` on positive `receive` only, which runs
+      #   the real `perform_async` during the example (may enqueue jobs, hit external code, or
+      #   change expectations vs a pure stub). There is no autocorrect for `not_to` / `to_not receive`,
+      #   since `.and_call_original` would not apply to a negative expectation. Autocorrect is also
+      #   suppressed when the expectation uses a block, since appending `.and_call_original` would
+      #   rebind the block to the wrong method.
+      class PerformAsyncStub < Base
+        extend AutoCorrector
+
+        MSG = "Prefer checking enqueued jobs over stubbing `perform_async`."
+        MSG_RECEIVE = "Prefer checking enqueued jobs over stubbing `perform_async` or add `.and_call_original`."
+        RESTRICT_ON_SEND = %i(receive).freeze
+
+        # TODO: this should match on perform_async, not on receive, requires pattern update
+        # @!method stub_perform_async?(node)
+        def_node_matcher :stub_perform_async?, <<~PATTERN
+          (send nil? :receive (sym :perform_async))
+        PATTERN
+
+        def on_send(node)
+          return unless stub_perform_async?(node)
+
+          negative_expectation = false
+          calls_original = false
+
+          current = node.parent
+          while current&.call_type?
+            negative_expectation = true if current.method?(:not_to) || current.method?(:to_not)
+            calls_original = true if current.method?(:and_call_original) || current.method?(:and_wrap_original)
+
+            current = current.parent
+          end
+
+          return add_offense(node) if negative_expectation
+          return if calls_original # already have .and_call_original, not an offense
+
+          tail = message_expectation_chain_tail(node)
+          return add_offense(node, message: MSG_RECEIVE) if tail.parent&.block_type?
+
+          add_offense(node, message: MSG_RECEIVE) do |corrector|
+            corrector.insert_after(tail, ".and_call_original")
+          end
+        end
+
+        alias_method :on_csend, :on_send
+
+        private
+
+        def message_expectation_chain_tail(node)
+          tail = node
+          loop do
+            parent = tail.parent
+            break unless parent&.call_type?
+            break unless parent.receiver.equal?(tail)
+
+            tail = parent
+          end
+          tail
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/gusto/init.rb

@@ -10,6 +10,8 @@ module RuboCop
       include Thor::Actions
 
       PLUGINS = %w(rubocop-gusto rubocop-rspec rubocop-performance rubocop-rake rubocop-rails).freeze
+      SIDEKIQ_GEM_PATTERN = /\A\s*gem\s+['"]sidekiq['"]/
+      SIDEKIQ_LOCKFILE_PATTERN = /\A\s+sidekiq\s+\(/
 
       class_option :rubocop_yml, type: :string, default: ".rubocop.yml"
 
@@ -34,13 +36,8 @@ module RuboCop
           config = ConfigYml.load_file(options[:rubocop_yml])
         end
 
-        if rails?
-          config.add_inherit_gem("rubocop-gusto", "config/default.yml", "config/rails.yml")
-          config.add_plugin(PLUGINS)
-        else
-          config.add_inherit_gem("rubocop-gusto", "config/default.yml")
-          config.add_plugin(PLUGINS - %w(rubocop-rails))
-        end
+        config.add_inherit_gem("rubocop-gusto", *inherit_gem_configs)
+        config.add_plugin(rails? ? PLUGINS : PLUGINS - %w(rubocop-rails))
 
         config.sort!
         config.write(options[:rubocop_yml])
@@ -51,9 +48,25 @@ module RuboCop
 
       private
 
+      def inherit_gem_configs
+        configs = ["config/default.yml"]
+        configs << "config/rails.yml" if rails?
+        configs << "config/sidekiq.yml" if sidekiq?
+        configs
+      end
+
       def rails?
         File.exist?("config/application.rb")
       end
+
+      def sidekiq?
+        gem_referenced?("Gemfile", SIDEKIQ_GEM_PATTERN) ||
+          gem_referenced?("Gemfile.lock", SIDEKIQ_LOCKFILE_PATTERN)
+      end
+
+      def gem_referenced?(path, pattern)
+        File.exist?(path) && File.foreach(path).any? { |line| line.match?(pattern) }
+      end
     end
   end
 end

data/lib/rubocop/gusto/version.rb

@@ -2,6 +2,6 @@
 
 module RuboCop
   module Gusto
-    VERSION = "11.0.0"
+    VERSION = "11.1.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-gusto
 version: !ruby/object:Gem::Version
-  version: 11.0.0
+  version: 11.1.0
 platform: ruby
 authors:
 - Gusto Engineering
@@ -119,10 +119,13 @@ files:
 - LICENSE
 - README.md
 - config/default.yml
+- config/gusto_cops.yml
 - config/rails.yml
+- config/sidekiq.yml
 - exe/gusto-rubocop
 - exe/rubocop-gusto
 - lib/rubocop-gusto.rb
+- lib/rubocop/cop/gusto/all.rb
 - lib/rubocop/cop/gusto/bootsnap_load_file.rb
 - lib/rubocop/cop/gusto/datadog_constant.rb
 - lib/rubocop/cop/gusto/described_class_constant_reference.rb
@@ -151,6 +154,7 @@ files:
 - lib/rubocop/cop/internal_affairs/require_restrict_on_send.rb
 - lib/rubocop/cop/rack/lowercase_header_keys.rb
 - lib/rubocop/cop/rspec/scattered_let.rb
+- lib/rubocop/cop/sidekiq/perform_async_stub.rb
 - lib/rubocop/gusto.rb
 - lib/rubocop/gusto/cli.rb
 - lib/rubocop/gusto/config_yml.rb
@@ -171,7 +175,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.4'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="