rubocop-gusto 11.9.1 → 11.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5581a398e181fa5cee526273621f36357e83dba9fe912433df5a4cbe2129b2e7
-  data.tar.gz: db3825a6506974aa565e427d2e83fa1cbb618b31136c4bdbbb13840e81dd1eb1
+  metadata.gz: 7f748fe3b65ef76b93bb947a6058c589a813ab9cb5b1e941e4728c566b595e3d
+  data.tar.gz: 96f689862a97b10381440f8a06ce03dd5c52cc440908249bee2500b74571b16c
 SHA512:
-  metadata.gz: '089fac7ad4fea249760ba0d5138e78a42152f198796b7f920d78ee656ba5cfb4d56b66a20918a90488431534b497110b366a66f467703c22797d5d4a51a94aba'
-  data.tar.gz: 681ef77cd2115bac46da1f0713adfa9fd05ed77204cec941c47cbe7a45d30b62d2b3128997665567923eaaa6509464f10c78867869fed7aed34d9b7bc3870f21
+  metadata.gz: a15c149f1360e7bd8a1fa2c49e73f52410a5992c1f7caaf235331fa28127de6011658a1abb36414bb762647f8ddb6afbd4563c7b146e2e31011a340686132e3e
+  data.tar.gz: 35e67c0e1cee739e8cb07ad6be077813b0e296c942ca593a1109153894e6bba933a789455b97fdbf94b826135bd91c05f1e618856230a885c0504f2cd2e92e52

data/CHANGELOG.md

@@ -3,9 +3,31 @@
 - 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.11.0](https://github.com/Gusto/rubocop-gusto/compare/v11.10.0...v11.11.0) (2026-10-27)
+
+
+### Features
+
+* add Gusto/Sorbet/StructDefaultEvaluatedOnce cop ([#194](https://github.com/Gusto/rubocop-gusto/issues/194)) ([e58c907](https://github.com/Gusto/rubocop-gusto/commit/e58c907195fd589cf94c1ab67fbd89fbc603102b))
+* Flag PII accessors and raw params in logs ([#119](https://github.com/Gusto/rubocop-gusto/issues/119)) ([c9f5342](https://github.com/Gusto/rubocop-gusto/commit/c9f53428b2d99bfb31091f066395d3c896155f4e))
+* move the Rack and Sidekiq cops under the Gusto department ([#192](https://github.com/Gusto/rubocop-gusto/issues/192)) ([acd6a2c](https://github.com/Gusto/rubocop-gusto/commit/acd6a2c65a51abf81f74ab1072dbb8de03af2238))
+
+## [11.10.0](https://github.com/Gusto/rubocop-gusto/compare/v11.9.1...v11.10.0) (2026-10-22)
+
+
+### Features
+
+* add Gusto/TimeoutTimeout cop ([#195](https://github.com/Gusto/rubocop-gusto/issues/195)) ([ef28938](https://github.com/Gusto/rubocop-gusto/commit/ef28938194582f3e7f804694a6a9fa7f6b005b99))
+* per-group scoping for Gusto/UnreferencedLet ([de8504c](https://github.com/Gusto/rubocop-gusto/commit/de8504c66110dea8d2ab1a57ea66870a181ce633))
+* per-group UnreferencedLet scoping ([#187](https://github.com/Gusto/rubocop-gusto/issues/187)) ([de8504c](https://github.com/Gusto/rubocop-gusto/commit/de8504c66110dea8d2ab1a57ea66870a181ce633))
+
 ## [11.9.1](https://github.com/Gusto/rubocop-gusto/compare/v11.9.0...v11.9.1) (2026-09-28)
 
 
+### Features
+
+* flag transitive discouraged gems via the lockfile and discourage ostruct ([#188](https://github.com/Gusto/rubocop-gusto/issues/188)) ([3fb0a2c](https://github.com/Gusto/rubocop-gusto/commit/3fb0a2c825777d768c4d2d92b8504eae44723d5a))
+
 ### Bug Fixes
 
 * port upstream review of Gusto/HardcodedAbsentRecordId ([#180](https://github.com/Gusto/rubocop-gusto/issues/180)) ([6198928](https://github.com/Gusto/rubocop-gusto/commit/6198928187db6920c18c882c3167a1cf8edeccf1))

data/README.md

@@ -88,14 +88,31 @@ inherit_gem:
 
 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.
 
+#### Logging configuration
+
+The `Gusto/Logging` cops report likely sensitive data in `Rails.logger`, `Sidekiq.logger`,
+and bare `logger` calls, including chained `.tagged(...)` loggers and message blocks.
+Each cop has its own severity, exclusions, todo entries, and inline disables:
+
+- `PiiAccessor` checks configured PII methods such as `user.email`.
+- `RawParams` checks unfiltered `params`, including serialization and `require` without narrowing.
+
+All ship at `Severity: info`, which does not fail RuboCop at its default failure threshold.
+Spec and test files are excluded. Promote each cop independently after reviewing its hits;
+for example, set `Gusto/Logging/PiiAccessor: Severity: warning` in your project configuration.
+Configure `PiiMethods` on `Gusto/Logging` to customize the shared sensitive-method list.
+
+These are syntax-based heuristics: selecting a params key is allowed, not proof that it is safe;
+plain local variables and values assembled outside the log call may escape detection.
+
 ### Available cops
 
 Custom cops live under the following namespaces:
 
 - `Gusto/` — general Gusto-specific cops (see [`lib/rubocop/cop/gusto/`](lib/rubocop/cop/gusto/))
 - `Gusto/Graphql/` — cops scoped to the graphql-ruby schema DSL (see [`lib/rubocop/cop/gusto/graphql/`](lib/rubocop/cop/gusto/graphql/)); configured in [`config/graphql.yml`](config/graphql.yml)
-- `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/))
+- `Gusto/Logging/` — independently configurable checks for sensitive data in logs (see [`lib/rubocop/cop/gusto/logging/`](lib/rubocop/cop/gusto/logging/))
+- `Gusto/Sidekiq/` — cops scoped to Sidekiq patterns (see [`lib/rubocop/cop/gusto/sidekiq/`](lib/rubocop/cop/gusto/sidekiq/)); enabled by [`config/sidekiq.yml`](config/sidekiq.yml)
 
 ## Publishing New Versions
 

data/config/default.yml

@@ -242,38 +242,9 @@ RSpec/StubbedMock:
 RSpec/SubjectStub:
   Enabled: false
 
-Rack/LowercaseHeaderKeys:
-  Description: 'HTTP response header keys should be lowercase for HTTP/2 and modern web standards compatibility.'
-  Enabled: true
-  Include:
-    - 'lib/middleware/**/*.rb'
-    - 'app/middleware/**/*.rb'
-    - 'app/controllers/**/*.rb'
-    - 'app/public/**/*controller*.rb'
-    - 'app/helpers/**/*.rb'
-    - 'packs/**/middleware/**/*.rb'
-    - 'packs/**/controllers/**/*.rb'
-    - 'packs/**/app/public/**/*controller*.rb'
-    - 'packs/**/app/helpers/**/*.rb'
-    - 'packs/**/lib/**/*_app.rb'
-    - 'components/**/middleware/**/*.rb'
-    - 'components/**/controllers/**/*.rb'
-    - 'config/initializers/**/*.rb'
-  Exclude:
-    - '**/spec/**/*'
-
 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:
-    # Not just `*_spec.rb`: shared contexts, support files and system-spec helpers install these
-    # stubs on behalf of the specs that include them, which is where they are hardest to spot.
-    - '**/spec/**/*'
-
 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

@@ -112,6 +112,66 @@ Gusto/HardcodedId:
   AllowedFactories: []
   AllowedReceivers: []
 
+Gusto/Logging:
+  # Exclusions live on each cop because RuboCop 1.76 replaces department Exclude arrays.
+  PiiMethods:
+    - email
+    - ssn
+    - social_security_number
+    - first_name
+    - last_name
+    - full_name
+    - phone
+    - phone_number
+    - ein
+    - tin
+    - tax_id
+    - account_number
+    - routing_number
+    - date_of_birth
+    - address
+    - bank_account_number
+
+Gusto/Logging/PiiAccessor:
+  Description: 'Flags PII accessor methods such as `.email` in log calls.'
+  Severity: info
+  inherit_mode:
+    merge:
+      - Exclude
+  Exclude:
+    - '**/spec/**/*'
+    - '**/test/**/*'
+
+Gusto/Logging/RawParams:
+  Description: 'Flags logging raw `params`, which may contain PII.'
+  Severity: info
+  inherit_mode:
+    merge:
+      - Exclude
+  Exclude:
+    - '**/spec/**/*'
+    - '**/test/**/*'
+
+Gusto/LowercaseHeaders:
+  Description: 'HTTP response header keys should be lowercase for HTTP/2 and modern web standards compatibility.'
+  Enabled: true
+  Include:
+    - 'lib/middleware/**/*.rb'
+    - 'app/middleware/**/*.rb'
+    - 'app/controllers/**/*.rb'
+    - 'app/public/**/*controller*.rb'
+    - 'app/helpers/**/*.rb'
+    - 'packs/**/middleware/**/*.rb'
+    - 'packs/**/controllers/**/*.rb'
+    - 'packs/**/app/public/**/*controller*.rb'
+    - 'packs/**/app/helpers/**/*.rb'
+    - 'packs/**/lib/**/*_app.rb'
+    - 'components/**/middleware/**/*.rb'
+    - 'components/**/controllers/**/*.rb'
+    - 'config/initializers/**/*.rb'
+  Exclude:
+    - '**/spec/**/*'
+
 Gusto/MinByMaxBy:
   Description: 'Checks for the use of `min` or `max` with a proc. Corrects to `min_by` or `max_by`.'
   Safe: false
@@ -176,6 +236,16 @@ Gusto/RspecDateTimeMock:
     - '**/spec/**/*'
   Safe: false
 
+Gusto/Sidekiq/PerformAsyncStub:
+  Description: 'Prefer checking enqueued jobs over stubbing `perform_async`.'
+  # Opted into via config/sidekiq.yml when the project depends on Sidekiq.
+  Enabled: false
+  SafeAutoCorrect: false # Autocorrect appends `.and_call_original`, which runs real `perform_async` during the example
+  Include:
+    # Not just `*_spec.rb`: shared contexts, support files and system-spec helpers install these
+    # stubs on behalf of the specs that include them, which is where they are hardest to spot.
+    - '**/spec/**/*'
+
 Gusto/SidekiqParams:
   Description: 'Sidekiq perform methods cannot take keyword arguments.'
 
@@ -191,6 +261,13 @@ Gusto/Sorbet/PredicateBooleanReturn:
   # which can change behavior in subtle ways.
   SafeAutoCorrect: false
 
+Gusto/Sorbet/StructDefaultEvaluatedOnce:
+  Description: 'T::Struct `default:` values are evaluated once at class load; use `factory:` for clock or random values.'
+  # Opted into via config/sorbet.yml when the project depends on Sorbet.
+  Enabled: false
+  # Autocorrect gives each instance a fresh value instead of the one computed at load time.
+  SafeAutoCorrect: false
+
 Gusto/SuddenAssociations:
   Description: 'Prevents defining Rails associations on another class from outside the class body.'
   # Opted into via config/rails.yml; the association DSL only exists in a Rails project.
@@ -198,6 +275,11 @@ Gusto/SuddenAssociations:
   Exclude:
     - '**/spec/**/*' # allow stubbing, although this is still odd
 
+Gusto/TimeoutTimeout:
+  Description: 'Flags `Timeout.timeout`, which interrupts its block with `Thread#raise` at an arbitrary point.'
+  Exclude:
+    - '**/spec/**/*'
+
 Gusto/ToplevelConstants:
   Description: 'Prevents top-level constants from being defined outside of initializers.'
   Include:
@@ -220,6 +302,9 @@ Gusto/UnreferencedLet:
   Include:
     - '**/spec/**/*_spec.rb'
   SafeAutoCorrect: false
+  PerExampleGroup: false
+  Cascade: false
+  LocalContextIncludes: []
 
 Gusto/UsePaintNotColorize:
   Description: 'Use Paint instead of colorize for terminal colors.'

data/config/obsoletion.yml

@@ -22,3 +22,13 @@ renamed:
   Graphql/PreventScalarsDate: GraphQL/DisallowedTypes
   Graphql/ResolverIgnoresObject: Gusto/Graphql/ResolverIgnoresObject
   Graphql/TypeVariables: Gusto/Graphql/TypeVariables
+
+  # `Rack` and `Sidekiq` held one Gusto-authored cop each, alongside departments other gems
+  # own. They now live under `Gusto/`. These warn rather than error, so a consumer's existing
+  # config for the old name keeps applying to the new one until it is renamed.
+  Rack/LowercaseHeaderKeys:
+    new_name: Gusto/LowercaseHeaders
+    severity: warning
+  Sidekiq/PerformAsyncStub:
+    new_name: Gusto/Sidekiq/PerformAsyncStub
+    severity: warning

data/config/sidekiq.yml

@@ -3,5 +3,5 @@
 #
 # After you add a rule, sort this file with `bundle exec rubocop-gusto sort config/sidekiq.yml`
 
-Sidekiq/PerformAsyncStub:
+Gusto/Sidekiq/PerformAsyncStub:
   Enabled: true

data/config/sorbet.yml

@@ -5,3 +5,6 @@
 
 Gusto/Sorbet/PredicateBooleanReturn:
   Enabled: true
+
+Gusto/Sorbet/StructDefaultEvaluatedOnce:
+  Enabled: true

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

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

data/lib/rubocop/cop/gusto/logging/log_call_concerns.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Gusto
+      module Logging
+        # Log-call detection and argument traversal shared by the `Gusto/Logging` cops.
+        module LogCallConcerns
+          extend NodePattern::Macros
+
+          LOG_METHODS = %i(debug info warn error fatal log).freeze
+
+          # @!method rails_logger?(node)
+          def_node_matcher :rails_logger?, <<~PATTERN
+            (send (const {nil? cbase} :Rails) :logger)
+          PATTERN
+
+          # @!method sidekiq_logger?(node)
+          def_node_matcher :sidekiq_logger?, <<~PATTERN
+            (send (const {nil? cbase} :Sidekiq) :logger)
+          PATTERN
+
+          # @!method bare_logger?(node)
+          def_node_matcher :bare_logger?, <<~PATTERN
+            (send nil? :logger)
+          PATTERN
+
+          # @!method raw_params?(node)
+          def_node_matcher :raw_params?, <<~PATTERN
+            (send nil? :params)
+          PATTERN
+
+          private
+
+          def logger_call?(node)
+            supported_logger?(node.receiver)
+          end
+
+          def supported_logger?(node)
+            return false unless node
+            return true if rails_logger?(node) || sidekiq_logger?(node) || bare_logger?(node)
+
+            node.call_type? && node.method?(:tagged) && supported_logger?(node.receiver)
+          end
+
+          def pii_methods
+            @pii_methods ||= Array(config.dig("Gusto/Logging", "PiiMethods")).map(&:to_s).to_set
+          end
+
+          def pii_method?(method_name)
+            name = method_name.to_s
+            pii_methods.include?(name) || pii_methods.any? { |pii| name.end_with?("_#{pii}") }
+          end
+
+          def each_send_in_log(log_node, &callback)
+            log_node.arguments.each do |arg|
+              yield_sends_from(arg, &callback)
+            end
+
+            # Block-form logging carries the message in the block, not the arguments: `logger.info { "..." }`
+            parent_node = log_node.parent
+            if parent_node&.block_type? && parent_node.send_node == log_node
+              yield_sends_from(parent_node.body, &callback)
+            end
+          end
+
+          def yield_sends_from(node, &callback)
+            return unless node
+
+            yield node if node.call_type?
+            node.each_descendant(:call, &callback)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/gusto/logging/pii_accessor.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "log_call_concerns"
+
+module RuboCop
+  module Cop
+    module Gusto
+      module Logging
+        # Flags PII accessor methods, such as `.email` or `.ssn`, in log calls.
+        #
+        # Only calls with a receiver count (`user.email`, not a bare `email`). A predicate on the
+        # accessor (`user.email.present?`) is allowed because it logs a boolean, not the value.
+        # `PiiMethods` comes from the `Gusto/Logging` department. Each entry also
+        # matches as an underscore suffix, so `tax_id` covers `client_tax_id`.
+        #
+        # @example
+        #   # bad
+        #   Rails.logger.info("User: #{user.email}")
+        #   logger.warn("Failed for #{employee.ssn}")
+        #   Rails.logger.info("Tax ID: #{input.client_tax_id}")
+        #
+        #   # good
+        #   Rails.logger.info("User: #{user.id}")
+        #   Rails.logger.info("Has email: #{user.email.present?}")
+        #
+        class PiiAccessor < Base
+          include LogCallConcerns
+
+          MSG = "Avoid logging PII accessor `.%{method}`. Log an identifier instead."
+          RESTRICT_ON_SEND = LOG_METHODS
+
+          def on_send(node)
+            return unless logger_call?(node)
+
+            each_send_in_log(node) do |send_node|
+              next unless send_node.receiver
+              next unless pii_method?(send_node.method_name)
+              next if predicate_receiver?(send_node)
+
+              add_offense(send_node, message: format(MSG, method: send_node.method_name))
+            end
+          end
+
+          alias_method :on_csend, :on_send
+
+          private
+
+          def predicate_receiver?(node)
+            parent = node.parent
+            parent.call_type? && parent.predicate_method?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/gusto/logging/raw_params.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative "log_call_concerns"
+
+module RuboCop
+  module Cop
+    module Gusto
+      module Logging
+        # Flags logging raw `params`, which may contain PII.
+        #
+        # `slice`, `permit`, `fetch`, `dig`, and `[]` are allowed; single-key access may still return a nested hash.
+        # `params.require(:key)` alone is flagged because it returns the whole nested hash.
+        #
+        # @example
+        #   # bad
+        #   Rails.logger.info(params)
+        #   logger.info(params.inspect)
+        #   Rails.logger.info(params.require(:user))
+        #
+        #   # good
+        #   Rails.logger.info(params.slice(:id, :status))
+        #   Rails.logger.info(params.require(:user).permit(:id))
+        #
+        class RawParams < Base
+          include LogCallConcerns
+
+          MSG = "Avoid logging raw `params` which may contain PII. " \
+                "Select reviewed fields with `params.slice(...)`. " \
+                "In Rails, `params.permit(...)` also selects fields, " \
+                "or use `request.filtered_parameters` for configured filtering."
+          RESTRICT_ON_SEND = LOG_METHODS
+
+          # @!method params_serialization?(node)
+          def_node_matcher :params_serialization?, <<~PATTERN
+            (call (send nil? :params) {:to_s :inspect :to_json :to_yaml} ...)
+          PATTERN
+
+          # @!method required_params?(node)
+          def_node_matcher :required_params?, <<~PATTERN
+            (call (send nil? :params) :require ...)
+          PATTERN
+
+          # @!method safe_params?(node)
+          def_node_matcher :safe_params?, <<~PATTERN
+            (call {(send nil? :params) #required_params?} {:slice :permit :fetch :dig :[]} ...)
+          PATTERN
+
+          def on_send(node)
+            return unless logger_call?(node)
+
+            each_send_in_log(node) do |send_node|
+              add_offense(send_node) if exposed_params?(send_node)
+            end
+          end
+
+          alias_method :on_csend, :on_send
+
+          private
+
+          def exposed_params?(node)
+            raw_params?(node) ? !params_with_method_call?(node) : params_serialization?(node)
+          end
+
+          def params_with_method_call?(params_node)
+            parent = params_node.parent
+            return false unless parent.call_type?
+            # `params.require(:key)` returns the whole nested hash, so it is only safe once narrowed.
+            return safe_params?(parent.parent) if required_params?(parent)
+
+            safe_params?(parent) || params_serialization?(parent)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/{rack/lowercase_header_keys.rb → gusto/lowercase_headers.rb}

@@ -2,7 +2,7 @@
 
 module RuboCop
   module Cop
-    module Rack
+    module Gusto
       # Detects HTTP response headers with uppercase characters.
       # HTTP response header keys should be lowercase for compatibility
       # with HTTP/2 and modern web standards.
@@ -24,7 +24,7 @@ module RuboCop
       #   response.set_header('x-custom', 'value')
       #   response.headers['content-security-policy'] += policy
       #
-      class LowercaseHeaderKeys < Base
+      class LowercaseHeaders < Base
         extend AutoCorrector
 
         MSG = "HTTP response header keys should be lowercase. Use `%{downcased}` instead of `%{original}`."

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Gusto
+      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)
+        #
+        #   # bad - the stub it verifies is itself the offense, and it may have been
+        #   # set up in a shared context this cop cannot see
+        #   expect(Foo).to have_received(: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 - there is no other way to make an enqueue fail. Sidekiq's testing API
+        #   # pushes onto Foo.jobs and offers no failure injection, so a spec covering the
+        #   # rescue around an enqueue has to raise from the stub.
+        #   allow(Foo).to receive(:perform_async).and_raise(StandardError, "redis down")
+        #
+        # @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, nor for
+        #   `have_received`, whose stub lives elsewhere. 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 have_received).freeze
+
+          # Chain modifiers that leave the real `perform_async` reachable, so the example is not
+          # replacing the enqueue with a canned result. `and_raise` belongs here even though it
+          # never calls the original: simulating a failed enqueue is the one thing Sidekiq's
+          # testing API cannot express, so a spec covering the rescue has no other route.
+          ALLOWED_CHAIN = %i(and_call_original and_wrap_original and_raise).freeze
+
+          # @!method stub_perform_async?(node)
+          def_node_matcher :stub_perform_async?, <<~PATTERN
+            (send nil? {:receive :have_received} (sym :perform_async))
+          PATTERN
+
+          def on_send(node)
+            return unless stub_perform_async?(node)
+            # `have_received` only verifies a stub that was installed somewhere else, possibly in a
+            # shared context or support file out of this cop's reach, so it is flagged on sight and
+            # there is nothing local to autocorrect.
+            return add_offense(node) if node.method?(:have_received)
+
+            negative_expectation = false
+            allowed_chain = false
+
+            current = node.parent
+            while current&.call_type?
+              negative_expectation = true if current.method?(:not_to) || current.method?(:to_not)
+              allowed_chain = true if ALLOWED_CHAIN.include?(current.method_name)
+
+              current = current.parent
+            end
+
+            return add_offense(node) if negative_expectation
+            return if allowed_chain
+
+            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
+end