rubocop-gusto 11.9.0 → 11.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae5d8c5b6e24aaf92ff21ac52781b6e6ad098d4893a0051b530d372bd6fee0d3
-  data.tar.gz: f95be1484e3291a03aa5fb2e337b18fcdcf48cb4762422bc0fc39bed4550ef6c
+  metadata.gz: 389e8e8a7531fb3ad32c281f658bc51fa59c0c65707599089e7c45f0b8cddf19
+  data.tar.gz: 3c9654b75327dc9420e107dc43fff4ac94b32586639f9a925794c98eb95d4e0d
 SHA512:
-  metadata.gz: 5c773623cef1e70d0289490fd8409a30d05ce91c0051ac29f7be5946849d8d3087ca9edb26b90e54cb14b9afe99c26fa712063810be1ba74252010ac32d26706
-  data.tar.gz: a0e8c1775d2850925cdda007713667410a2ab32f60b73f928f372bfa24ec4fa4ab2a707466aca9ef10ce4b5e61407e0c3a9752b489ae9c9e5a8f0f92bfa57533
+  metadata.gz: 5d116ac3f0047391c0d9e6fc17fab5849ce6a67bcd1681ef5050c9dcf501801fe97ad6f59f3a7f31f505babe20a718e2b6ff61a7fadfd306fdc4073366ad6db5
+  data.tar.gz: 7ab7f1cebafc19303cadff84e8091b8f52f196edb9cac54add0c2acc8719bf6420a5a8f7a2fbe4aaeae13d95747c72a16c8a5e1e1380004328e8e05f4f3916b5

data/CHANGELOG.md

@@ -3,6 +3,26 @@
 - 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.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))
+
 ## [11.9.0](https://github.com/Gusto/rubocop-gusto/compare/v11.8.1...v11.9.0) (2026-09-24)
 
 

data/config/gusto_cops.yml

@@ -32,9 +32,14 @@ Gusto/DescribedClassConstantReference:
     - '**/spec/**/*'
 
 Gusto/DiscouragedGem:
-  Description: 'Flags installation of discouraged gems in Gemfiles and gemspecs.'
-  Enabled: false
-  Gems: {}
+  Description: 'Flags discouraged gems in Gemfiles and gemspecs, including ones pulled in transitively per the lockfile.'
+  Enabled: true
+  Include:
+    - '**/*.gemspec'
+    - '**/Gemfile'
+    - '**/gems.rb'
+  Gems:
+    ostruct: "OpenStruct is officially discouraged (slow, and defeats method caching); use Struct, Data, a Hash, or T::Struct. See https://forum.exercism.org/t/openstruct-is-now-officially-discouraged/17490"
 
 Gusto/ExecuteMigration:
   Description: "Don't use `execute` in migrations. Use a backfill rake task instead."
@@ -193,6 +198,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:
@@ -215,6 +225,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/rails.yml

@@ -11,10 +11,6 @@ AllCops:
   TargetRubyVersion: <%= RbConfig::CONFIG['RUBY_API_VERSION'] %>
 
 Gusto/DiscouragedGem:
-  Enabled: true
-  Include:
-    - '**/*.gemspec'
-    - '**/Gemfile'
   Gems:
     timecop: "Use Rails' time helpers (e.g., freeze_time, travel_to) instead of Timecop."
 

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

@@ -1,27 +1,57 @@
 # frozen_string_literal: true
 
+require "bundler"
+require "digest"
+
 module RuboCop
   module Cop
     module Gusto
-      # 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.
+      # Flag installation of discouraged gems (e.g. ostruct) in Gemfiles and gemspecs. The
+      # discouraged gems and advice about alternatives are configured under `Gems:`.
+      #
+      # When a Gemfile has a lockfile beside it, discouraged gems pulled in transitively are
+      # flagged on the line of the Gemfile dependency that pulls them in, so each existing case
+      # can be exempted with its own inline `rubocop:todo` and any new one still fails.
       #
-      # @example Gems: { timecop: "Use Rails' time helpers instead of Timecop." }
+      # @example Gems: { ostruct: "Use Struct or Data instead of OpenStruct." }
       #   # bad
-      #   gem "timecop"
+      #   gem "ostruct"
       #
-      #   # good
-      #   # Use Rails' time helpers (freeze_time, travel_to) instead.
+      #   # bad - Gemfile.lock resolves slack-ruby-client -> gli -> ostruct
+      #   gem "slack-ruby-client"
       class DiscouragedGem < Base
         MSG = "Avoid using the '%{gem}' gem. %{advice}"
+        MSG_TRANSITIVE = "Avoid using the '%{gem}' gem, pulled in via %{path}. %{advice}"
+        MSG_UNREADABLE_LOCKFILE = "Could not parse %{lockfile} to check for discouraged gems."
+        LOCKFILES = { "Gemfile" => "Gemfile.lock", "gems.rb" => "gems.locked" }.freeze
 
         RESTRICT_ON_SEND = %i(gem add_dependency add_development_dependency).freeze
 
+        # @!method gem_declaration(node)
+        def_node_matcher :gem_declaration, "(send nil? :gem ({str sym} $_) ...)"
+
+        # @!method gemspec_declaration?(node)
+        def_node_matcher :gemspec_declaration?, "(send nil? :gemspec ...)"
+
+        def on_new_investigation
+          return if discouraged_gems.empty? || processed_source.ast.nil?
+
+          lockfile = lockfile_path
+          check_lockfile(lockfile) if lockfile && ::File.file?(lockfile)
+        end
+
         def on_send(node)
           check_gem_usage(node)
         end
 
+        # Asked once per run, so only a lockfile-only change at the project root busts the cache.
+        def external_dependency_checksum
+          lockfiles = LOCKFILES.values.select { |path| ::File.file?(path) }
+          return if lockfiles.empty?
+
+          Digest::SHA256.hexdigest(lockfiles.map { |path| ::File.read(path) }.join)
+        end
+
         private
 
         def check_gem_usage(node)
@@ -32,6 +62,84 @@ module RuboCop
           # No autocorrect: removing dependencies is a project decision.
         end
 
+        def lockfile_path
+          file_path = processed_source.file_path.to_s
+          lockfile = LOCKFILES[::File.basename(file_path)]
+          ::File.join(::File.dirname(file_path), lockfile) if lockfile
+        end
+
+        def check_lockfile(lockfile)
+          parser = ::Bundler::LockfileParser.new(::File.read(lockfile))
+        rescue ::Bundler::LockfileError
+          add_offense(fallback_location, message: format(MSG_UNREADABLE_LOCKFILE, lockfile: ::File.basename(lockfile)))
+        else
+          graph = dependency_graph(parser.specs)
+          declared = declared_gems
+          paths_by_location = Hash.new { |hash, location| hash[location] = [] }
+          parser.dependencies.each_key do |root|
+            discouraged_paths(root, graph).each do |path|
+              # A declared discouraged gem is already flagged by on_send.
+              next if path.one? && declared.key?(root)
+
+              paths_by_location[declared.fetch(root) { fallback_location }] << path
+            end
+          end
+          # RuboCop keeps only the first offense per location, so they are combined.
+          paths_by_location.each do |location, paths|
+            add_offense(location, message: paths.map { |path| message_for_path(path) }.join(" "))
+          end
+        end
+
+        # Platform-specific specs share a name, so their dependencies are merged.
+        def dependency_graph(specs)
+          specs.each_with_object({}) do |spec, graph|
+            (graph[spec.name] ||= []).concat(spec.dependencies.map(&:name)).uniq!
+          end
+        end
+
+        # Breadth-first, so each discouraged gem is reported via its shortest path from root.
+        def discouraged_paths(root, graph)
+          parents = { root => nil }
+          queue = [root]
+          found = []
+          until queue.empty?
+            name = queue.shift
+            found << name if discouraged_gems.include?(name)
+            graph.fetch(name, []).each do |dependency|
+              next if parents.key?(dependency)
+
+              parents[dependency] = name
+              queue << dependency
+            end
+          end
+          found.map { |name| path_to(name, parents) }
+        end
+
+        def path_to(name, parents)
+          path = [name]
+          path.unshift(parents[path.first]) while parents[path.first]
+          path
+        end
+
+        def declared_gems
+          processed_source.ast.each_node(:send).with_object({}) do |node, declared|
+            name = gem_declaration(node)
+            declared[name.to_s] ||= node if name
+          end
+        end
+
+        # Dependencies that come from a gemspec, eval_gemfile, or similar have no `gem` line.
+        def fallback_location
+          processed_source.ast.each_node(:send).find { |node| gemspec_declaration?(node) } ||
+            processed_source.buffer.line_range(1)
+        end
+
+        def message_for_path(path)
+          return message_for(path.first) if path.one?
+
+          format(MSG_TRANSITIVE, gem: path.last, path: path.join(" -> "), advice: advice_for(path.last))
+        end
+
         def discouraged_gems
           @discouraged_gems ||= gems_config.keys.map(&:to_s)
         end

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

@@ -22,7 +22,15 @@ module RuboCop
       # In a list, a literal sitting beside a real `record.id` also qualifies on its own: you
       # would write another `record.id` if you wanted one that exists. That matters because
       # those groups are usually named for the plural ("with multiple bank account IDs") rather
-      # than for the gap.
+      # than for the gap. Several literals each correct to their own negative (`-1`, `-2`), so
+      # the count the example asserts is preserved. A list only reads as record ids when every
+      # member is one: `['story', '123', '']` enumerates the shapes an id parser must reject,
+      # so its numeric member is a format, not a primary key.
+      #
+      # The description vocabulary is wider than "does not exist" on purpose. "Invalid company
+      # id", "belongs to another company" and "for a different employee" are, in practice,
+      # how specs name an id that matches no row -- and a positive literal there collides with
+      # the example's own record as soon as the counter reaches it.
       #
       # Five shapes are deliberately not offenses, because in none of them can the counter reach
       # the literal, or a single replacement would change what the example asserts:
@@ -91,14 +99,13 @@ module RuboCop
           (does|do|did)\s*n[o']?t\s+exist | \bnot\s+exist |
           \bnot\s+found\b | (cannot|can\s*not|can't|couldn't)\s+be\s+found |
           is\s*n[o']?t\s+found | non-?\s?existent | no\s+such |
-          invalid\s+\w*\s*\bid\b | \bid\b\s+is\s+invalid |
+          invalid\s+(\w+\s+)?ids?\b | \bids?\s+(is|are)\s+invalid |
           does\s*n[o']?t\s+belong | not\s+belong\s+to | unauthorized\s+access |
           (another|other|different)\s+(account|company|customer|employee|member|org|person|user)
         /xi
 
         NOT_FOUND = /RecordNotFound/
         NOT_FOUND_STATUS = /\A:?(not_found|404)\z/
-        BUILDERS = %i(build build! build_list build_stubbed build_stubbed_list create create! create_list).freeze
         DEFAULT_MAX_ID = 1_000_000
 
         # @!method let_definition(node)
@@ -147,19 +154,32 @@ module RuboCop
           register(literal)
         end
 
-        # Only a lone literal qualifies. Two would both correct to `-1`, and a duplicated id in
-        # a list collapses on lookup, changing the count the example asserts.
         def check_id_list(node, name, array)
-          literals = array.children.select { |item| collidable_id(item) }
-          return unless literals.one?
+          return if format_fixture?(array)
 
+          literals = array.children.select { |item| collidable_id(item) }
           group = enclosing_example_group(node)
-          return unless list_qualifies?(array, group)
+          return if literals.empty? || !list_qualifies?(array, group)
+
+          register_list(literals, group, name)
+        end
 
-          literal = literals.first
-          return if group && built_with?(group, name, collidable_id(literal))
+        # Each literal gets its own negative: a duplicated id collapses on lookup, which would
+        # change the count the example asserts.
+        def register_list(literals, group, name)
+          literals.each_with_index do |literal, index|
+            next if group && built_with?(group, name, collidable_id(literal))
 
-          register(literal)
+            register(literal, -(index + 1))
+          end
+        end
+
+        # `['story', 'story-', '123', '']` lists the shapes an id parser has to reject, so its
+        # numeric member is a format, not a primary key.
+        def format_fixture?(array)
+          array.children.any? do |item|
+            item.type?(:str, :sym) && Integer(item.value.to_s, exception: false).nil?
+          end
         end
 
         def list_qualifies?(array, group)
@@ -168,9 +188,9 @@ module RuboCop
           !group.nil? && absent_context?(group)
         end
 
-        def register(literal)
+        def register(literal, replacement = -1)
           add_offense(literal) do |corrector|
-            corrector.replace(literal, literal.str_type? ? "'-1'" : "-1")
+            corrector.replace(literal, literal.str_type? ? "'#{replacement}'" : replacement.to_s)
           end
         end
 
@@ -228,6 +248,12 @@ module RuboCop
             (any_block (send nil? {:let :let!} (sym $_) ...) _ $_)
           PATTERN
 
+          # @!method builder_calls(node)
+          def_node_search :builder_calls, <<~PATTERN
+            $(send _ {:build :build! :build_list :build_pair :build_stubbed :build_stubbed_list
+                      :create :create! :create_list :create_pair} ...)
+          PATTERN
+
           def initialize(group, max_id)
             @group = group
             @max_id = max_id
@@ -240,9 +266,11 @@ module RuboCop
           # A group that builds a record carrying this id means the row is meant to exist, so
           # the absence the group describes is about something else.
           def builds?(name, value)
-            group.each_descendant(:send).any? do |send_node|
-              BUILDERS.include?(send_node.method_name) &&
-                send_node.each_descendant.any? { |arg| references?(arg, name) || same_id_value?(arg, value) }
+            builder_calls(group).any? do |call|
+              factory = factory_name(call)
+              call.each_descendant(:send, :pair).any? do |node|
+                references?(node, name) || own_attribute?(node, factory, value)
+              end
             end
           end
 
@@ -307,11 +335,23 @@ module RuboCop
             node.send_type? && node.receiver.nil? && node.method?(name)
           end
 
-          # `create(:evaluation, company_id: 1)` beside `let(:company_id) { 1 }` builds the row
-          # this id selects, even though the example inlined the literal rather than the `let`.
-          def same_id_value?(node, value)
-            node.pair_type? && node.key.type?(:sym, :str) &&
-              node.key.value.to_s.match?(ID_NAME) && collidable_id(node.value) == value
+          def factory_name(call)
+            first_argument = call.first_argument
+            first_argument.value.to_s if first_argument&.sym_type?
+          end
+
+          # The built record carries the id when the key is its own primary key, or when the
+          # attribute is named for the factory, as in `create(:card, corepro_card_id: 123)`. A key
+          # naming another table is a foreign key: `create(:evaluation, company_id: 1)` points at
+          # the companies row the example says is absent rather than creating it, so it is not
+          # treated as building it.
+          def own_attribute?(node, factory, value)
+            return false unless node.pair_type? && node.key.type?(:sym, :str)
+
+            key = node.key.value.to_s
+            return false unless key.match?(ID_NAME) && collidable_id(node.value) == value
+
+            key == "id" || (!factory.nil? && key.include?(factory))
           end
 
           def own_lets(node, found = [])

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Gusto
+      # Flags calls to `Timeout.timeout`.
+      #
+      # `Timeout.timeout` stops its block by calling `Thread#raise` from a
+      # watcher thread, so the exception can land on any line of the block,
+      # including inside an `ensure` clause or halfway through a database write
+      # or a connection checkout. That can leak locks, return a half-read socket
+      # to a pool, or leave records partially updated. There is no safe way to
+      # interrupt an arbitrary block of code; see
+      # https://jvns.ca/blog/2015/11/27/why-rubys-timeout-is-dangerous-and-thread-dot-raise-is-terrifying/
+      #
+      # Instead, use the timeout the waiting operation itself supports, which
+      # fails at a known point: `Net::HTTP#read_timeout`, a database
+      # `statement_timeout`, `IO#timeout=`, `Queue#pop(timeout:)`, or a deadline
+      # checked with `Process.clock_gettime(Process::CLOCK_MONOTONIC)`.
+      #
+      # `Timeout` is a constant, so it is never nil and safe navigation
+      # (`Timeout&.timeout`) is never used; the cop only handles `on_send`.
+      #
+      # @example
+      #   # bad
+      #   Timeout.timeout(5) { http.get(path) }
+      #   ::Timeout.timeout(5, MyError) { do_work }
+      #
+      #   # good
+      #   http.read_timeout = 5
+      #   http.get(path)
+      class TimeoutTimeout < Base
+        MSG = "Avoid `Timeout.timeout`; it interrupts the block with `Thread#raise` at an arbitrary point. " \
+              "Use the timeout option of the operation being waited on instead, " \
+              "such as `Net::HTTP#read_timeout` or a database `statement_timeout`."
+        RESTRICT_ON_SEND = %i(timeout).freeze
+
+        # @!method timeout_timeout?(node)
+        def_node_matcher :timeout_timeout?, <<~PATTERN
+          (send (const {nil? cbase} :Timeout) :timeout ...)
+        PATTERN
+
+        def on_send(node)
+          add_offense(node) if timeout_timeout?(node)
+        end
+      end
+    end
+  end
+end

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

@@ -13,8 +13,8 @@ module RuboCop
       # side effect even when unreferenced, so it cannot simply be deleted. Only plain `let` is
       # handled here.
       #
-      # Detection is file-scoped: a `let` referenced only from another file (through a shared
-      # example or an included test harness) cannot be seen, so the cop stays conservative and
+      # By default detection is file-scoped: a `let` referenced only from another file (through a
+      # shared example or an included test harness) cannot be seen, so the cop stays conservative and
       # prefers false negatives over false positives:
       # - a name defined more than once in the file by `let`/`let!`/`subject` (an override /
       #   `super` chain, including a `subject` that overrides a `let` of the same name) is never
@@ -42,6 +42,23 @@ module RuboCop
       # realistically only deletes distinctively-named dead lets; it is not a complete dead-`let`
       # finder.
       #
+      # `PerExampleGroup: true` scopes detection to example groups instead. A `let` is live only where
+      # code running in its group could read it: a reference in its own group, an enclosing group or
+      # a nested one, never a sibling. A reference is a bare call or a call on the example itself
+      # (`self.x`, `->(example) { example.x }`); hash keys and factory, stub and lookup arguments are
+      # not. Each definition of an overridden name is judged on its own, and a `let!` reads its own
+      # name. Shared groups and helper methods defined under `spec/support/**` (and in the
+      # `spec/*_helper.rb` files beside it) are resolved, following the groups and helpers they use
+      # in turn, so an include or helper call protects only the names that code could read. Harnesses
+      # `config` registers by metadata (`include_context`, `include`, hooks) count where the lineage's
+      # metadata, the type inferred from the directory, or metadata derived for the file selects
+      # them. A reflective call reads the names its target could hold: a pattern for an
+      # interpolated name. Anything the cop cannot resolve still protects every `let` in its lineage.
+      # `LocalContextIncludes` names include methods that evaluate a sibling `context.rb` (or
+      # `<name>_context.rb`), which is then resolved the same way.
+      #
+      # `Cascade: true` also flags a `let` read only from unreferenced `let`s (including its own block).
+      #
       # @example
       #   # bad (name never referenced -- deleted, the block never runs)
       #   let(:unused) { create(:thing) }
@@ -64,13 +81,57 @@ module RuboCop
         # the called name cannot be known, so the whole file is left untouched.
         DYNAMIC_DISPATCH_METHODS = %i(send public_send __send__ try try! method public_method respond_to?).freeze
         FRAMEWORK_LET_PATTERN = /\b(?:let!?|subject)\s*\(?\s*:([A-Za-z_]\w*[!?]?)/
+        HOOK_METHODS = %i(before after around prepend_before append_before prepend_after append_after).freeze
+        HOOK_SCOPES = %i(each example all context suite).freeze
         # Identifier-shaped tokens inside a string/heredoc literal. A `let` whose name appears only
         # inside string text -- e.g. a binding or column referenced in raw SQL/GraphQL the spec
         # later executes -- counts as referenced, so it is not deleted.
         IDENTIFIER_IN_STRING = /[A-Za-z_]\w*[!?]?/
+        # Methods whose literal arguments name factories, traits, stubbed methods or hash keys, never a
+        # `let`.
+        INERT_SYMBOL_METHODS = %i(
+          receive have_received create build build_stubbed create_list build_list attributes_for create_pair build_pair
+          [] []= fetch dig key? has_key? delete
+        ).freeze
         MSG = "Remove unreferenced `let(:%{name})` -- its name is never used, so the block never runs."
+        # Includes whose block defines a nested example group; `include_context`/`include_examples`
+        # evaluate their block in the including group itself.
+        NESTING_INCLUDES = %i(it_behaves_like it_should_behave_like).freeze
+        RESOLVABLE_INCLUDES = %i(it_behaves_like it_should_behave_like include_examples include_context).freeze
         RESTRICT_ON_SEND = %i(let).freeze
+        SHARED_GROUP_METHODS = %i(shared_examples shared_examples_for shared_context).freeze
         SUPPORT_FILES_GLOB = "**/spec/support/**/*.rb"
+        INCLUDED_CONTEXT = ::RuboCop::AST::NodePattern.new("(send _ :include_context ({str sym} $_) ...)")
+        INCLUDED_MODULE = ::RuboCop::AST::NodePattern.new("(send _ :include (const _ $_) ...)")
+        REGEXP_NEW = ::RuboCop::AST::NodePattern.new("(send (const {nil? cbase} :Regexp) :new (str $_))")
+        # Harness condition for configuration that applies to every example group, metadata or not.
+        UNCONDITIONAL = [:__unconditional__, nil].freeze
+        # The `type` rspec-rails infers from a spec's directory (`infer_spec_type_from_file_location!`).
+        INFERRED_TYPES = {
+          controller: "controllers", helper: "helpers", job: "jobs", mailer: "mailers", model: "models",
+          request: "(?:requests|integration|api)", routing: "routing", view: "views", feature: "features",
+          system: "system", mailbox: "mailboxes", channel: "channels", generator: "generator",
+        }.transform_values { |dir| %r(spec/#{dir}/) }.freeze
+
+        # The names some code could read: literal names, patterns for names it builds by
+        # interpolation (`try("#{prefix}_include")`), and whether it dispatches to names its inputs
+        # carry (`hash.each_key { |key| send(key) }`), which hash keys and the like can supply.
+        Reads = Struct.new(:names, :patterns, :inputs) do
+          def self.empty
+            new(Set.new, [], false)
+          end
+
+          def include?(name)
+            names.include?(name) || patterns.any? { |pattern| pattern.match?(name.to_s) }
+          end
+
+          def merge!(other)
+            names.merge(other.names)
+            patterns.concat(other.patterns)
+            self.inputs ||= other.inputs
+            self
+          end
+        end
 
         # The name symbol of any definition (`let`/`let!`/`subject`) in any block form -- used to
         # count how many times a name is defined, so override / `super` chains (including a
@@ -80,11 +141,26 @@ module RuboCop
           (any_block (send nil? %DEFINITION_METHODS (sym $_) ...) ...)
         PATTERN
 
+        # @!method lazy_let?(node)
+        def_node_matcher :lazy_let?, <<~PATTERN
+          (any_block (send nil? :let (sym _) ...) ...)
+        PATTERN
+
+        # @!method subject_name(node)
+        def_node_matcher :subject_name, <<~PATTERN
+          (any_block (send nil? {:subject :subject!} (sym $_) ...) ...)
+        PATTERN
+
+        # @!method eager_let_name(node)
+        def_node_matcher :eager_let_name, <<~PATTERN
+          (any_block (send nil? :let! (sym $_) ...) ...)
+        PATTERN
+
         class << self
           # Names defined as `let`/`subject` anywhere under `spec/support/**`. Computed once per
           # process (lazily, after boot) and shared across every file the cop inspects.
           def framework_let_names
-            @framework_let_names ||= scan_framework_let_names(support_file_paths)
+            @framework_let_names ||= scan_framework_let_names(support_files)
           end
 
           # Enumerate `spec/support/**/*.rb`. No git dependency: some environments (e.g. a build
@@ -94,6 +170,19 @@ module RuboCop
             ::Dir.glob(SUPPORT_FILES_GLOB)
           end
 
+          def support_files
+            @support_files ||= support_file_paths
+          end
+
+          # The support files plus the `spec/*_helper.rb` files beside each `spec/support` directory,
+          # which define helpers the same way.
+          def indexed_files
+            helpers = support_files.filter_map { |path| path[%r{\A(?:.*/)?spec/(?=support/)}] }.uniq.flat_map do |spec_dir|
+              ::Dir.glob(::File.join(spec_dir, "*_helper.rb"))
+            end
+            support_files + helpers
+          end
+
           def scan_framework_let_names(paths)
             paths.each_with_object(Set.new) do |path, names|
               extract_let_names(read_source(path), names)
@@ -110,6 +199,331 @@ module RuboCop
 
             ::File.read(path, encoding: "UTF-8")
           end
+
+          # Every name the code behind a shared group (`kind` `:groups`), a helper method (`:defs`) or a
+          # module (`:modules`) defined under `spec/support/**` could read, or `nil` when that cannot be
+          # bounded. That code is followed through the groups it includes and the helpers it calls.
+          # Unbounded when a group is not defined there, or the code dispatches through a name it
+          # computes, or includes a group by a name we cannot resolve.
+          def support_reads(kind, name, processed_source)
+            @support_reads ||= {}
+            key = [kind, name]
+            return @support_reads[key] if @support_reads.key?(key)
+
+            index = support_index(processed_source)
+            @support_reads[key] = reads_from(index[kind][name], index)
+          end
+
+          def support_helper?(name, processed_source)
+            support_index(processed_source)[:defs].key?(name)
+          end
+
+          # Everything the harnesses whose conditions `provided` metadata meets could read: shared
+          # groups, modules and `config` hooks registered for that metadata. `provided` holds
+          # `[key, value]` pairs, a `nil` value standing for one we cannot know.
+          def harness_reads(provided, processed_source)
+            index = support_index(processed_source)
+            provided = provided.to_set | [UNCONDITIONAL, [:file_path, nil]]
+            provided |= index[:derived].filter_map { |pair, filter| pair if derived_applies?(filter, provided, processed_source.file_path.to_s) }
+            active = index[:harnesses].keys.select { |condition| condition_met?(condition, provided) }.to_set
+            @harness_reads ||= {}
+            return @harness_reads[active] if @harness_reads.key?(active)
+
+            @harness_reads[active] = active.flat_map { |condition| index[:harnesses][condition] }.uniq.reduce(Reads.empty) do |reads, target|
+              found = harness_target_reads(target, index, processed_source)
+              break unless found
+
+              reads.merge!(found)
+            end
+          end
+
+          # Whether a `define_derived_metadata` filter matches this file: a literal `file_path:` regexp is
+          # tested, a metadata filter checked against `provided`; anything else is assumed to match.
+          def derived_applies?(filter, provided, path)
+            kind, value = filter
+            case kind
+            when :path then value.match?(path)
+            when :metadata then value.all? { |condition| condition_met?(condition, provided) }
+            else true
+            end
+          end
+
+          # A condition with no value asks only for its key; a provided value we cannot know meets any.
+          def condition_met?(condition, provided)
+            key, value = condition
+            provided.any? { |provided_key, provided_value| provided_key == key && (value.nil? || provided_value.nil? || provided_value == value) }
+          end
+
+          # A module no support file defines comes from a gem, which cannot read spec `let`s.
+          def harness_target_reads(target, index, processed_source)
+            kind, name = target
+            case kind
+            when :chunk then reads_from([name], index)
+            when :modules then index[:modules].key?(name) ? support_reads(:modules, name, processed_source) : Reads.empty
+            else support_reads(kind, name, processed_source)
+            end
+          end
+
+          def local_context_reads(path, processed_source)
+            @local_context_reads ||= {}
+            return @local_context_reads[path] if @local_context_reads.key?(path)
+
+            ast = parse(read_source(path), path, processed_source) if ::File.file?(path)
+            @local_context_reads[path] = (reads_from([scan(ast)], support_index(processed_source)) if ast)
+          end
+
+          def reads_from(chunks, index)
+            return unless chunks
+
+            pending = chunks.dup
+            seen = Set.new.compare_by_identity
+            reads = Reads.empty
+            while (chunk = pending.shift)
+              next unless seen.add?(chunk)
+              return if chunk[:opaque] || chunk[:includes].any? { |included| !index[:groups].key?(included) }
+
+              reads.names.merge(chunk[:names])
+              reads.patterns.concat(chunk[:patterns])
+              reads.inputs ||= chunk[:inputs]
+              chunk[:includes].each { |included| pending.concat(index[:groups][included]) }
+              chunk[:calls].each { |call| pending.concat(index[:defs].fetch(call, [])) }
+            end
+            reads
+          end
+
+          def support_index(processed_source)
+            @support_index ||= indexed_files.each_with_object(empty_index) do |path, index|
+              ast = parse(read_source(path), path, processed_source)
+              index_definitions(ast, index) if ast
+            end
+          end
+
+          def empty_index
+            { groups: {}, defs: {}, modules: {}, harnesses: Hash.new { |hash, key| hash[key] = [] }, derived: Set.new }
+          end
+
+          def parse(source, path, processed_source)
+            ::RuboCop::ProcessedSource.new(source, processed_source.ruby_version, path, parser_engine: processed_source.parser_engine).ast
+          end
+
+          # Indexes each shared group, helper method and module by name, scanned on its own, and each
+          # harness `config` registers by the metadata keys that pull it in.
+          def index_definitions(ast, index)
+            ast.each_node(:any_block, :def, :module, :send) do |node|
+              case node.type
+              when :def
+                (index[:defs][node.method_name] ||= []) << scan(node) if helper_method?(node)
+              when :module
+                (index[:modules][node.identifier.short_name] ||= []).concat(inclusion_hooks(node))
+              when :send
+                index_registration(node, index)
+              else
+                index_block(node, index)
+              end
+            end
+          end
+
+          def index_block(block, index)
+            send_node = block.send_node
+            name = literal_name(send_node.first_argument)
+            if name && SHARED_GROUP_METHODS.include?(send_node.method_name)
+              (index[:groups][name] ||= []) << scan(block)
+              metadata_conditions(send_node.arguments.drop(1)).each { |condition| index[:harnesses][condition] << [:groups, name] } if send_node.arguments.size > 1
+            elsif config_call?(send_node) && HOOK_METHODS.include?(send_node.method_name)
+              conditions = metadata_conditions(send_node.arguments.reject { |arg| arg.sym_type? && HOOK_SCOPES.include?(arg.value) })
+              conditions.each { |condition| index[:harnesses][condition] << [:chunk, scan(block)] }
+            elsif config_call?(send_node) && send_node.method?(:define_derived_metadata)
+              index_derived(block, index)
+            end
+          end
+
+          # The metadata a `define_derived_metadata` block assigns (`metadata[:key] = value`), which can
+          # be present without the spec writing it.
+          def index_derived(block, index)
+            filter = derived_filter(block.send_node.arguments)
+            block.each_node(:send) do |node|
+              index[:derived] << [[node.first_argument.value, literal_value(node.last_argument)], filter] if node.method?(:[]=) && node.first_argument.sym_type?
+            end
+          end
+
+          def derived_filter(args)
+            return [:always] if args.empty?
+
+            path = args.first.pairs.find { |pair| pair.key.sym_type? && pair.key.value == :file_path } if args.one? && args.first.hash_type?
+            return [:path, literal_regexp(path.value)] if path && literal_regexp(path.value)
+            return [:metadata, metadata_conditions(args)] unless path
+
+            [:unknown]
+          end
+
+          def literal_regexp(node)
+            return node.to_regexp if node.regexp_type? && node.children.all? { |part| part.type?(:str, :regopt) }
+
+            (source = REGEXP_NEW.match(node)) && ::Regexp.new(source)
+          end
+
+          def index_registration(node, index)
+            return unless config_call?(node)
+
+            target = registration_target(node)
+            metadata_conditions(node.arguments.drop(1)).each { |condition| index[:harnesses][condition] << target } if target
+          end
+
+          def registration_target(node)
+            if (name = INCLUDED_CONTEXT.match(node)) then [:groups, name.to_s]
+            elsif (name = INCLUDED_MODULE.match(node)) then [:modules, name]
+            end
+          end
+
+          def config_call?(send_node)
+            !send_node.receiver.nil? && !send_node.receiver.self_type? && !send_node.receiver.const_type?
+          end
+
+          # `[key, value]` metadata pairs written as arguments: `:key` asks for the key, `key: value` for
+          # the value (`nil` when it is not a literal).
+          def metadata_conditions(args)
+            conditions = args.flat_map do |arg|
+              if arg.sym_type? then [[arg.value, nil]]
+              elsif arg.hash_type? then arg.pairs.select { |pair| pair.key.sym_type? }.map { |pair| [pair.key.value, literal_value(pair.value)] }
+              else []
+              end
+            end
+            conditions.empty? ? [UNCONDITIONAL] : conditions
+          end
+
+          def literal_value(node)
+            return node.true_type? if node.boolean_type?
+
+            node.value if node.type?(:sym, :str)
+          end
+
+          # What including a module runs on its own: its `included`/`extended` hooks. Its other methods
+          # only read what they read when called, and calls are followed as helpers.
+          def inclusion_hooks(module_node)
+            module_node.each_node(:any_block, :defs).select { |node| node.method?(:included) || node.method?(:extended) }.map { |hook| scan(hook) }
+          end
+
+          # What code under `root` reads: its symbols (except factory/stub ones and hash keys), bare
+          # calls and string tokens; the helpers it calls and groups it includes, to follow; and the
+          # patterns of names it builds for dynamic dispatch, or `opaque` when it builds them some
+          # other way.
+          def scan(root)
+            chunk = { calls: Set.new, names: Set.new, includes: [], patterns: [], opaque: false, inputs: false }
+            inert = Set.new
+            root.each_node do |node|
+              case node.type
+              when :sym then (inert_symbol?(node) ? inert : chunk[:names]) << node.value
+              when :str then (inert_symbol?(node) ? inert : chunk[:names]).merge(string_tokens(node))
+              when :send, :csend then scan_call(node, chunk)
+              end
+            end
+            chunk[:names].merge(inert) if chunk[:inputs]
+            chunk
+          end
+
+          def scan_call(node, chunk)
+            if node.receiver.nil?
+              chunk[:calls] << node.method_name
+              chunk[:names] << node.method_name if node.arguments.empty?
+              scan_include(node, chunk) if include_method?(node.method_name)
+            end
+            case (read = dispatch_read(node))
+            when Regexp then chunk[:patterns] << read
+            when :inputs then chunk[:inputs] = true
+            when :unbounded then chunk[:opaque] = true
+            end
+          end
+
+          def scan_include(node, chunk)
+            name = literal_name(node.first_argument)
+            name && RESOLVABLE_INCLUDES.include?(node.method_name) ? chunk[:includes] << name : chunk[:opaque] = true
+          end
+
+          # A method a spec could call bare: defined at the top level, in a block, or in a module that
+          # can be mixed into example groups -- not an instance method of some class.
+          def helper_method?(def_node)
+            !def_node.each_ancestor(:class, :sclass, :module).first&.type?(:class, :sclass)
+          end
+
+          def include_method?(method_name)
+            ::RuboCop::RSpec::Language.config.fetch("Includes", {}).values.flatten.include?(method_name.to_s)
+          end
+
+          def literal_name(node)
+            node.value.to_s if node&.type?(:str, :sym)
+          end
+
+          # A symbol or string that cannot name a `let`: a hash key, or a factory, trait, stubbed method
+          # or hash lookup name.
+          def inert_symbol?(node)
+            parent = node.parent
+            return parent.key.equal?(node) if parent.pair_type?
+
+            parent.send_type? && INERT_SYMBOL_METHODS.include?(parent.method_name) && parent.arguments.any? { |arg| arg.equal?(node) }
+          end
+
+          def dynamic_target?(node)
+            return false unless DYNAMIC_DISPATCH_METHODS.include?(node.method_name)
+
+            target = node.first_argument
+            !target.nil? && !target.type?(:sym, :str)
+          end
+
+          # What a reflective call that can reach a `let` (no receiver, or `self`) reads beyond its
+          # literal names: nothing for a literal target; `:inputs` when the target is a parameter, a
+          # variable assigned only literals, or a bare call returning one, so any literal could
+          # supply the name; a pattern when it interpolates around literal text; `:unbounded`
+          # otherwise.
+          def dispatch_read(node)
+            return unless DYNAMIC_DISPATCH_METHODS.include?(node.method_name) && (node.receiver.nil? || node.receiver.self_type?)
+
+            target = node.first_argument
+            return if target.nil? || target.type?(:sym, :str)
+            return :inputs if literal_valued?(target)
+
+            target.type?(:dstr, :dsym) ? interpolation_pattern(target) : :unbounded
+          end
+
+          def literal_valued?(node)
+            case node.type
+            when :lvar
+              node.each_ancestor.to_a.last.each_node(:lvasgn).none? do |assignment|
+                assignment.name == node.children.first && !assignment.expression&.type?(:sym, :str)
+              end
+            when :send then node.receiver.nil? && node.arguments.empty?
+            else false
+            end
+          end
+
+          def interpolation_pattern(node)
+            parts = node.children.map { |part| part.str_type? ? ::Regexp.escape(part.value) : (literal_alternatives(part) || "\\w*") }
+            return :unbounded unless node.children.any?(&:str_type?)
+
+            ::Regexp.new("\\A#{parts.join}[!?]?\\z")
+          end
+
+          # `(?:a|b)` for an interpolated block parameter bound by iterating a literal array or hash.
+          def literal_alternatives(part)
+            variable = part.children.first
+            return unless part.children.one? && variable.lvar_type?
+
+            block = variable.each_ancestor(:block).find { |ancestor| ancestor.argument_list.first&.name == variable.children.first }
+            values = literal_collection(block.receiver) if block
+            "(?:#{values.map { |value| ::Regexp.escape(value) }.join('|')})" if values
+          end
+
+          def literal_collection(node)
+            return unless node&.type?(:array, :hash)
+
+            elements = node.hash_type? ? node.keys : node.children
+            elements.map { |element| element.value.to_s } if elements.all? { |element| element.type?(:sym, :str) }
+          end
+
+          # A string with invalid encoding (e.g. a deliberate bad-UTF-8 test fixture) cannot contain
+          # an identifier-shaped reference and would raise on `scan`, so it yields none.
+          def string_tokens(node)
+            node.value.valid_encoding? ? node.value.scan(IDENTIFIER_IN_STRING).map(&:to_sym) : []
+          end
         end
 
         def on_send(node)
@@ -131,20 +545,243 @@ module RuboCop
 
         private
 
-        # A lazy `let` is exempt from deletion whenever file-scoped analysis cannot prove its name
-        # is dead: its name is a framework-reserved contract (e.g. `cop_config`), the file
-        # dispatches through a name we cannot resolve statically, it consumes shared examples, the
-        # `let` is lexically inside a shared-example definition, its name is a `spec/support/**`
-        # framework contract, it is overridden by another definition of the same name, or it is
-        # referenced somewhere in the file.
         def exempt_from_deletion?(name, block)
           FRAMEWORK_RESERVED_NAMES.include?(name) ||
-            dynamic_dispatch? ||
-            consumes_shared_examples? ||
+            (!per_example_group? && dynamic_dispatch?) ||
             within_shared_definition?(block) ||
-            self.class.framework_let_names.include?(name) ||
-            overridden?(name) ||
-            referenced?(name)
+            !dead_lets.include?(block)
+        end
+
+        def per_example_group?
+          cop_config.fetch("PerExampleGroup", false)
+        end
+
+        def cascade?
+          cop_config.fetch("Cascade", false)
+        end
+
+        def local_context_includes
+          @local_context_includes ||= Array(cop_config["LocalContextIncludes"]).to_set(&:to_sym)
+        end
+
+        def dead_lets
+          @dead_lets ||= begin
+            dead = find_dead(identity_set)
+            while cascade? && (next_dead = find_dead(dead)).size > dead.size
+              dead = next_dead
+            end
+            dead
+          end
+        end
+
+        def find_dead(dead)
+          identity_set.merge(lazy_lets.reject { |let| live?(let, dead) })
+        end
+
+        def identity_set
+          Set.new.compare_by_identity
+        end
+
+        def live?(let, dead)
+          name = let.send_node.first_argument.value
+          scope = scope_of(let)
+          exposed_to_reader?(name, scope) ||
+            exposed_to_harness?(name, scope) ||
+            redefined?(name) ||
+            referenced_in_lineage?(name, let, scope, dead)
+        end
+
+        def exposed_to_reader?(name, scope)
+          reader_sites.any? do |site_scope, reads|
+            lineage?(site_scope, scope) &&
+              (reads.nil? || reads.include?(name) || (reads.inputs && inert_references.fetch(name, []).any? { |inert_scope| lineage?(inert_scope, site_scope) }))
+          end
+        end
+
+        # Hash keys and factory, stub and lookup arguments, by name and scope: not references, but a
+        # reader that dispatches to names its inputs carry could be handed one.
+        def inert_references
+          @inert_references ||= processed_source.ast.each_node(:sym, :str).each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |node, refs|
+            next unless self.class.inert_symbol?(node)
+
+            (node.sym_type? ? [node.value] : self.class.string_tokens(node)).each { |name| refs[name] << scope_of(node) }
+          end
+        end
+
+        # By file, a name also defined as a `let`/`subject` under `spec/support/**` likely overrides a
+        # contract some harness reads. Per example group, the harnesses that metadata in the lineage
+        # pulls in are resolved and only their reads count.
+        def exposed_to_harness?(name, scope)
+          return self.class.framework_let_names.include?(name) unless per_example_group?
+
+          reads = self.class.harness_reads(provided_metadata(scope), processed_source)
+          reads.nil? || reads.include?(name)
+        end
+
+        # The metadata examples in the lineage of `scope` carry: written on its groups, plus the
+        # `type` rspec-rails infers from the file's directory. A bare `:key` reads as `key: true`.
+        def provided_metadata(scope)
+          written = metadata_scopes.select { |group| lineage?(group, scope) }.flat_map do |group|
+            group.send_node.arguments.drop(1).flat_map do |arg|
+              next [[arg.value, true]] if arg.sym_type?
+
+              arg.hash_type? ? arg.pairs.select { |pair| pair.key.sym_type? }.map { |pair| [pair.key.value, self.class.literal_value(pair.value)] } : []
+            end
+          end
+          written + inferred_type
+        end
+
+        def inferred_type
+          @inferred_type ||= INFERRED_TYPES.filter_map { |type, directory| [:type, type] if processed_source.file_path.to_s.match?(directory) }
+        end
+
+        def redefined?(name)
+          per_example_group? ? subject_names.include?(name) : overridden?(name)
+        end
+
+        def referenced_in_lineage?(name, let, scope, dead)
+          references.fetch(name, []).any? do |reference_scope, container|
+            next false if cascade? && (container.equal?(let) || dead.include?(container))
+
+            lineage?(reference_scope, scope)
+          end
+        end
+
+        # Two scopes share a lineage when one encloses the other: a reference in an enclosing group runs
+        # in every nested example, and a reference in a nested group resolves outward to the definition.
+        # `nil` is file-wide and shares a lineage with everything.
+        def lineage?(scope, other)
+          scope.nil? || other.nil? || scope.equal?(other) ||
+            scope.each_ancestor(:any_block).any? { |ancestor| ancestor.equal?(other) } ||
+            other.each_ancestor(:any_block).any? { |ancestor| ancestor.equal?(scope) }
+        end
+
+        # The innermost example group (or block passed to an include such as `it_behaves_like`)
+        # enclosing the node, or `nil` for file-wide: outside any group, inside a shared-group
+        # definition (its body runs wherever it is included), or when scoping per group is off.
+        def scope_of(node)
+          return unless per_example_group?
+
+          ancestors = node.each_ancestor(:any_block).to_a
+          return if ancestors.any? { |ancestor| shared_group?(ancestor) }
+
+          ancestors.find { |ancestor| example_group?(ancestor) || nesting_include?(ancestor) }
+        end
+
+        def nesting_include?(block)
+          block.receiver.nil? && NESTING_INCLUDES.include?(block.method_name)
+        end
+
+        def lazy_lets
+          @lazy_lets ||= identity_set.merge(processed_source.ast.each_node(:any_block).select { |node| lazy_let?(node) })
+        end
+
+        def subject_names
+          @subject_names ||= processed_source.ast.each_node(:any_block).filter_map { |node| subject_name(node) }.to_set
+        end
+
+        # Every place code could read a let other than by naming it, as `[scope, Reads]` (`nil` when
+        # unbounded): shared-group includes and, per example group, calls to helper methods defined
+        # under `spec/support/**` and reflective calls that build the name they dispatch to.
+        def reader_sites
+          @reader_sites ||= processed_source.ast.each_node(:send).filter_map do |node|
+            if include?(node)
+              [scope_of(node.block_node || node), included_reads(node)]
+            elsif per_example_group?
+              group_reader_site(node)
+            end
+          end
+        end
+
+        def group_reader_site(node)
+          if node.receiver.nil? && self.class.support_helper?(node.method_name, processed_source)
+            [scope_of(node), self.class.support_reads(:defs, node.method_name, processed_source)]
+          elsif (read = self.class.dispatch_read(node))
+            [scope_of(node), dispatch_reads(read)]
+          end
+        end
+
+        def dispatch_reads(read)
+          case read
+          when ::Regexp then Reads.new(Set.new, [read], false)
+          when :inputs then Reads.new(Set.new, [], true)
+          end
+        end
+
+        def included_reads(node)
+          return unless per_example_group?
+          return local_context_reads(node) if local_context_includes.include?(node.method_name)
+          return unless RESOLVABLE_INCLUDES.include?(node.method_name)
+
+          group = self.class.literal_name(node.first_argument)
+          return unless group
+          # A group defined in this file is read through its body's references, which count file-wide.
+          return Reads.empty if local_shared_groups.include?(group)
+
+          self.class.support_reads(:groups, group, processed_source)
+        end
+
+        # A local-context include evaluates a sibling `context.rb`, or `<name>_context.rb` when named.
+        def local_context_reads(node)
+          name = self.class.literal_name(node.first_argument)
+          return if node.first_argument && !name
+
+          path = ::File.join(::File.dirname(processed_source.file_path), name ? "#{name}_context.rb" : "context.rb")
+          self.class.local_context_reads(path, processed_source)
+        end
+
+        def local_shared_groups
+          @local_shared_groups ||= processed_source.ast.each_node(:any_block).filter_map do |node|
+            self.class.literal_name(node.send_node.first_argument) if shared_group?(node)
+          end.to_set
+        end
+
+        def metadata_scopes
+          @metadata_scopes ||= processed_source.ast.each_node(:any_block).select do |node|
+            example_group?(node) && node.send_node.arguments.drop(1).any? { |arg| arg.type?(:sym, :hash) }
+          end
+        end
+
+        # Every reference to a name, keyed by name, as `[scope, enclosing lazy let]` pairs. A name is
+        # referenced where it is called bare (`foo`), appears as a symbol (`:foo`) other than a
+        # definition's own name argument, or appears as an identifier-shaped token inside any
+        # string/heredoc literal. The symbol and string cases cover indirect invocation --
+        # `send(:foo)` / `send("foo")`, a `:foo` listed in a data table the spec later dispatches on,
+        # or a binding named only inside raw SQL/GraphQL text -- which static analysis cannot
+        # otherwise follow. A `let!` references its own name from its own scope, since its eager
+        # hook calls it before every example there.
+        def references
+          @references ||= processed_source.ast.each_node(:sym, :str, :call, :any_block).each_with_object(Hash.new { |hash, key| hash[key] = [] }) do |node, refs|
+            reference_names(node).each { |name| refs[name] << [scope_of(node), (enclosing_lazy_let(node) if cascade?)] }
+          end
+        end
+
+        def reference_names(node)
+          case node.type
+          when :sym then definition_name_argument?(node) || (per_example_group? && self.class.inert_symbol?(node)) ? [] : [node.value]
+          when :str then per_example_group? && self.class.inert_symbol?(node) ? [] : self.class.string_tokens(node)
+          when :send, :csend then node.arguments.empty? && example_receiver?(node.receiver) ? [node.method_name] : []
+          else Array(eager_let_name(node))
+          end
+        end
+
+        # A call reaches a `let` when it has no receiver, or, per example group, when its receiver may be
+        # the example itself: `self`, or a block parameter (`->(example) { example.payroll }`).
+        def example_receiver?(receiver)
+          return true if receiver.nil?
+          return false unless per_example_group?
+
+          receiver.self_type? || (receiver.lvar_type? && block_parameter?(receiver))
+        end
+
+        def block_parameter?(lvar)
+          lvar.each_ancestor(:any_block).any? do |block|
+            block.respond_to?(:argument_list) && block.argument_list.any? { |argument| argument.name == lvar.children.first }
+          end
+        end
+
+        def enclosing_lazy_let(node)
+          node.each_ancestor(:any_block).find { |ancestor| lazy_lets.include?(ancestor) }
         end
 
         # Delete the `let` block, plus:
@@ -193,14 +830,12 @@ module RuboCop
           sibling
         end
 
+        # Per example group, a shared group nested in an example group is only visible to this file, so
+        # its `let`s are judged file-wide like any other; a top-level one may be included elsewhere.
         def within_shared_definition?(node)
-          node.each_ancestor(:any_block).any? { |ancestor| shared_group?(ancestor) }
-        end
-
-        def consumes_shared_examples?
-          return @consumes_shared_examples unless @consumes_shared_examples.nil?
-
-          @consumes_shared_examples = processed_source.ast.each_node(:call).any? { |send_node| include?(send_node) }
+          node.each_ancestor(:any_block).any? do |ancestor|
+            shared_group?(ancestor) && !(per_example_group? && ancestor.each_ancestor(:any_block).any? { |outer| example_group?(outer) })
+          end
         end
 
         # True when the file reflectively dispatches through a name we cannot resolve statically --
@@ -210,12 +845,7 @@ module RuboCop
         def dynamic_dispatch?
           return @dynamic_dispatch unless @dynamic_dispatch.nil?
 
-          @dynamic_dispatch = processed_source.ast.each_node(:call).any? do |send_node|
-            next false unless DYNAMIC_DISPATCH_METHODS.include?(send_node.method_name)
-
-            target = send_node.first_argument
-            target && !target.sym_type? && !target.str_type?
-          end
+          @dynamic_dispatch = processed_source.ast.each_node(:call).any? { |node| self.class.dynamic_target?(node) }
         end
 
         def overridden?(name)
@@ -229,33 +859,6 @@ module RuboCop
           end
         end
 
-        def referenced?(name)
-          referenced_names.include?(name)
-        end
-
-        # A name is "referenced" if it is called as a bare method (`foo`), appears as a symbol
-        # literal (`:foo`) other than the let/subject's own name argument, or appears as an
-        # identifier-shaped token inside any string/heredoc literal. The symbol and string cases
-        # cover indirect invocation -- `send(:foo)` / `send("foo")`, a `:foo`/`"foo"` listed in a
-        # data table the spec later dispatches on, or a binding named only inside raw SQL/GraphQL
-        # text the spec executes -- which file-scoped analysis cannot otherwise follow. (Tokenizing
-        # string bodies, rather than matching the whole string, keeps a `let` referenced only from
-        # inside a multi-word heredoc from being deleted.) Interpolated-string *dispatch* is handled
-        # separately by `dynamic_dispatch?`, which exempts the whole file.
-        def referenced_names
-          @referenced_names ||= processed_source.ast.each_node(:sym, :str, :call).each_with_object(Set.new) do |node, names|
-            if node.sym_type?
-              names << node.value unless definition_name_argument?(node)
-            elsif node.str_type?
-              # A string with invalid encoding (e.g. a deliberate bad-UTF-8 test fixture) cannot
-              # contain an identifier-shaped reference and would raise on `scan`, so skip it.
-              node.value.scan(IDENTIFIER_IN_STRING) { |token| names << token.to_sym } if node.value.valid_encoding?
-            elsif node.receiver.nil? && node.arguments.empty?
-              names << node.method_name
-            end
-          end
-        end
-
         def definition_name_argument?(sym_node)
           parent = sym_node.parent
           parent.send_type? && parent.receiver.nil? && DEFINITION_METHODS.include?(parent.method_name)

data/lib/rubocop/gusto/version.rb

@@ -2,6 +2,6 @@
 
 module RuboCop
   module Gusto
-    VERSION = "11.9.0"
+    VERSION = "11.10.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-gusto
 version: !ruby/object:Gem::Version
-  version: 11.9.0
+  version: 11.10.0
 platform: ruby
 authors:
 - Gusto Engineering
@@ -194,6 +194,7 @@ files:
 - lib/rubocop/cop/gusto/smart_todo_team.rb
 - lib/rubocop/cop/gusto/sorbet/predicate_boolean_return.rb
 - lib/rubocop/cop/gusto/sudden_associations.rb
+- lib/rubocop/cop/gusto/timeout_timeout.rb
 - lib/rubocop/cop/gusto/toplevel_constants.rb
 - lib/rubocop/cop/gusto/unreferenced_let.rb
 - lib/rubocop/cop/gusto/use_paint_not_colorize.rb