rubocop-dev_doc 0.11.0 → 0.12.0

data/lib/dev_doc/test/pseudo_i18n_crawler.rb

@@ -1,5 +1,3 @@
-require 'set'
-
 module DevDoc
   module Test
     # Pseudo-localization hardcoded-text crawler.
@@ -96,20 +94,11 @@ module DevDoc
 
         # Prepend the Scanner onto the crawler HTTP client exactly once, no
         # matter how many test classes include the module.
-        unless Glib::JsonCrawler::Http.ancestors.include?(Scanner)
-          Glib::JsonCrawler::Http.prepend(Scanner)
-        end
+        Glib::JsonCrawler::Http.prepend(Scanner) unless Glib::JsonCrawler::Http.ancestors.include?(Scanner)
 
         base.setup do
-          skip 'Set PSEUDO_I18N=1 to run the pseudo-localization scan.' unless ENV['PSEUDO_I18N'] == '1'
-          skip 'en-PSEUDO locale not loaded — is config/initializers/pseudo_locale.rb active?' unless ::I18n.available_locales.include?(:'en-PSEUDO')
-
-          self.class.hits = {}
-          @previous_default_locale = ::I18n.default_locale
-          # The app's set_locale falls back to I18n.default_locale when no
-          # `_lang` param is present (crawler URLs carry none), so this renders
-          # every page in pseudo without touching the crawler's URLs.
-          ::I18n.default_locale = :'en-PSEUDO'
+          skip_unless_pseudo_enabled!
+          enter_pseudo_locale
         end
 
         base.teardown do
@@ -117,6 +106,7 @@ module DevDoc
         end
       end
 
+      # Per-run accumulator surface for the including test class.
       module ClassMethods
         attr_accessor :hits # { url => [ "[key] value", ... ] }
 
@@ -130,31 +120,44 @@ module DevDoc
           @report_dir ||= ::Rails.root.join('test/integration/pseudo_i18n_crawler_test_results').to_s
         end
 
+        def parse_json(body)
+          JSON.parse(body)
+        rescue JSON::ParserError
+          nil
+        end
+
         def scan_body(url, body)
           return unless body.is_a?(String) && body.lstrip.start_with?('{', '[')
 
-          json = begin
-            JSON.parse(body)
-          rescue JSON::ParserError
-            return
-          end
+          json = parse_json(body)
+          return unless json
 
-          walk(json) do |key, value|
-            if value.include?(MARKER)
-              @wrapped = (@wrapped || 0) + 1
-            elsif trivial?(value)
-              next
-            elsif fixture_strings.include?(value.strip)
-              # ActiveRecord display value (record title/name/user copy) that
-              # came straight from the DB — data, not a hardcoded UI string.
-              @data_sourced = (@data_sourced || 0) + 1
-            else
-              @unwrapped = (@unwrapped || 0) + 1
-              (hits[url] ||= []) << "[#{key}] #{value.inspect}"
-            end
+          walk(json) { |key, value| tally(url, key, value) }
+        end
+
+        # Buckets one text-prop value: wrapped (went through t()), trivial
+        # (not copy), data-sourced (verbatim fixture string), or a hardcoded
+        # candidate recorded in `hits`.
+        def tally(url, key, value)
+          if value.include?(MARKER)
+            counters[:wrapped] += 1
+          elsif trivial?(value)
+            nil
+          elsif fixture_strings.include?(value.strip)
+            # ActiveRecord display value (record title/name/user copy) that
+            # came straight from the DB — data, not a hardcoded UI string.
+            counters[:data_sourced] += 1
+          else
+            counters[:unwrapped] += 1
+            (hits[url] ||= []) << "[#{key}] #{value.inspect}"
           end
         end
 
+        # Per-run bucket counts for the DIAG line.
+        def counters
+          @counters ||= Hash.new(0)
+        end
+
         # Verbatim string values from the fixtures. A candidate equal to one of
         # these is an ActiveRecord display value (loaded from the DB, so it
         # never went through t() by design) rather than hardcoded copy, and is
@@ -164,7 +167,7 @@ module DevDoc
         # fixtures contain no ERB so static YAML parsing is exact.
         def fixture_strings
           @fixture_strings ||= Dir[File.join(fixture_dir, '**', '*.yml')].each_with_object(Set.new) do |file, set|
-            data = YAML.safe_load(File.read(file), permitted_classes: [Date, Time], aliases: true)
+            data = YAML.safe_load_file(file, permitted_classes: [Date, Time], aliases: true)
             collect_strings(data, set)
           rescue Psych::Exception
             next
@@ -178,12 +181,15 @@ module DevDoc
           when String
             s = node.strip
             set << s unless s.empty?
+          else
+            # Non-string scalars (numbers, booleans, nil, dates) carry no copy.
           end
         end
 
         def diag
-          "wrapped(localized via t)=#{@wrapped || 0}  data-sourced(fixtures, skipped)=#{@data_sourced || 0}  " \
-            "unwrapped(candidates)=#{@unwrapped || 0}"
+          "wrapped(localized via t)=#{counters[:wrapped]}  " \
+            "data-sourced(fixtures, skipped)=#{counters[:data_sourced]}  " \
+            "unwrapped(candidates)=#{counters[:unwrapped]}"
         end
 
         def walk(node, &blk)
@@ -195,6 +201,9 @@ module DevDoc
             end
           when Array
             node.each { |v| walk(v, &blk) }
+          else
+            # Scalars have no children to walk; string values are handed to
+            # the block by their parent hash above.
           end
         end
 
@@ -208,47 +217,74 @@ module DevDoc
 
       private
 
+      def skip_unless_pseudo_enabled!
+        skip 'Set PSEUDO_I18N=1 to run the pseudo-localization scan.' unless ENV['PSEUDO_I18N'] == '1'
+        return if ::I18n.available_locales.include?(:'en-PSEUDO')
+
+        skip 'en-PSEUDO locale not loaded — is config/initializers/pseudo_locale.rb active?'
+      end
+
+      def enter_pseudo_locale
+        self.class.hits = {}
+        self.class.counters.clear
+        @previous_default_locale = ::I18n.default_locale
+        # The app's set_locale falls back to I18n.default_locale when no
+        # `_lang` param is present (crawler URLs carry none), so this renders
+        # every page in pseudo without touching the crawler's URLs.
+        ::I18n.default_locale = :'en-PSEUDO'
+      end
+
       def crawl_pseudo(user)
         user[:token] = login(user)
 
-        router = Glib::JsonCrawler::Router.new
-        http   = Glib::JsonCrawler::Http.new(self, user, router, inspect_result: true)
-        router.host = HOST
-        router.skip_similar_page = true
-
         ENV['CRAWLER_MODE'] = 'true'
-        router.step(
-          http,
-          'onClick' => {
-            'action' => 'initiate_navigation',
-            'url' => "http://#{HOST}/users/me?format=json&redirect=default"
-          }
-        )
+        start_crawl(user)
       ensure
         ENV['CRAWLER_MODE'] = nil
         logout
         report!(user)
       end
 
+      # Enters the crawl at the logged-in user's landing page; the Router
+      # walks every reachable page from there.
+      def start_crawl(user)
+        router = Glib::JsonCrawler::Router.new
+        http   = Glib::JsonCrawler::Http.new(self, user, router, inspect_result: true)
+        router.host = HOST
+        router.skip_similar_page = true
+
+        entry = { 'action' => 'initiate_navigation',
+                  'url' => "http://#{HOST}/users/me?format=json&redirect=default" }
+        router.step(http, 'onClick' => entry)
+      end
+
       def report!(user)
         hits = self.class.hits
-        report_dir = self.class.report_dir
-        FileUtils.mkdir_p(report_dir)
-        path = File.join(report_dir, "#{user[:email]}.txt")
-
-        lines = []
-        hits.sort.each do |url, values|
-          lines << url
-          values.uniq.each { |v| lines << "    #{v}" }
-          lines << ''
-        end
-        total = hits.values.sum { |v| v.uniq.size }
-        summary = "#{total} hardcoded candidate(s) across #{hits.size} page(s) for #{user[:email]}"
+        summary = report_summary(hits, user)
+        path = write_report(summary, hits, user)
 
-        File.write(path, ([summary, ''] + lines).join("\n"))
         puts "\n[pseudo_i18n] #{summary}\n              report: #{path}"
         puts "[pseudo_i18n] DIAG: #{self.class.diag}"
       end
+
+      # Writes the per-role report file and returns its path.
+      def write_report(summary, hits, user)
+        FileUtils.mkdir_p(self.class.report_dir)
+        path = File.join(self.class.report_dir, "#{user[:email]}.txt")
+        File.write(path, ([summary, ''] + report_lines(hits)).join("\n"))
+        path
+      end
+
+      def report_summary(hits, user)
+        total = hits.values.sum { |v| v.uniq.size }
+        "#{total} hardcoded candidate(s) across #{hits.size} page(s) for #{user[:email]}"
+      end
+
+      def report_lines(hits)
+        hits.sort.flat_map do |url, values|
+          [url] + values.uniq.map { |v| "    #{v}" } + ['']
+        end
+      end
     end
   end
 end

data/lib/rubocop/cop/dev_doc/auth/load_resource_current_user_guard.rb

@@ -274,11 +274,11 @@ module RuboCop
           # `raise`/`fail`. A multi-statement branch (a `begin`) counts when its
           # LAST statement does.
           def branch_exits?(branch)
+            branch = branch.children.last if branch&.begin_type?
             return false unless branch
 
-            branch = branch.children.last if branch.begin_type?
-            branch&.return_type? ||
-              (branch&.send_type? && branch.receiver.nil? && %i[raise fail].include?(branch.method_name))
+            branch.return_type? ||
+              (branch.send_type? && branch.receiver.nil? && %i[raise fail].include?(branch.method_name))
           end
         end
       end

data/lib/rubocop/cop/dev_doc/i18n/localizable_props.rb

@@ -40,9 +40,7 @@ module RuboCop
           TRANSLATION_METHODS = %i[t translate].freeze
 
           def on_send(node)
-            if watched_methods.include?(node.method_name.to_s)
-              node.arguments.each { |arg| each_localizable(arg) }
-            end
+            node.arguments.each { |arg| each_localizable(arg) } if watched_methods.include?(node.method_name.to_s)
 
             check_jbuilder_positional(node)
           end
@@ -56,19 +54,22 @@ module RuboCop
           def each_localizable(node)
             case node.type
             when :hash
-              node.pairs.each do |pair|
-                key = pair.key
-                if key.sym_type? && localizable_keys.include?(key.value.to_s)
-                  inspect_localizable(key.value, pair.value)
-                end
-
-                each_localizable(pair.value)
-              end
+              node.pairs.each { |pair| walk_pair(pair) }
             when :array
               node.children.each { |child| each_localizable(child) }
+            else
+              # Any other node type (literal, send, variable…) can't contain
+              # localizable key-value pairs.
             end
           end
 
+          def walk_pair(pair)
+            key = pair.key
+            inspect_localizable(key.value, pair.value) if key.sym_type? && localizable_keys.include?(key.value.to_s)
+
+            each_localizable(pair.value)
+          end
+
           # jbuilder positional form: `json.title 'Forms'`. The method name is
           # the key and the first argument is the value. Restricted to the
           # jbuilder root `json` so ordinary `obj.text('...')` calls aren't

data/lib/rubocop/cop/dev_doc/i18n/translation_key_prefix.rb

@@ -74,6 +74,9 @@ module RuboCop
             when :dstr
               first = node.children.first
               first&.str_type? ? first.value : nil
+            else
+              # Fully dynamic key (variable, send…) — nil is this method's
+              # documented "statically unknown" return.
             end
           end
 

data/lib/rubocop/cop/dev_doc/migration/date_column_naming.rb

@@ -62,6 +62,9 @@ module RuboCop
               return if name.end_with?('_at')
 
               add_offense(col_name_node, message: format(DATETIME_MSG, name: name))
+            else
+              # add_column funnels every column type here; only date/time
+              # types carry a suffix naming rule.
             end
           end
         end

data/lib/rubocop/cop/dev_doc/rails/avoid_bypassing_validation.rb

@@ -125,8 +125,9 @@ module RuboCop
           private
 
           def receiver_shape_matches?(node)
-            return node.receiver&.const_type? if CONST_RECEIVER_ONLY.include?(node.method_name)
-            return !node.receiver&.const_type? if NON_CONST_RECEIVER_ONLY.include?(node.method_name)
+            const_receiver = node.receiver&.const_type?
+            return const_receiver if CONST_RECEIVER_ONLY.include?(node.method_name)
+            return !const_receiver if NON_CONST_RECEIVER_ONLY.include?(node.method_name)
 
             true
           end

data/lib/rubocop/cop/dev_doc/rails/avoid_lifecycle_method_override.rb

@@ -44,8 +44,8 @@ module RuboCop
         #    run — something `validate` can't express), disable this cop inline
         #    with a written justification:
         #
-        #      def run_validations! # rubocop:disable DevDoc/Rails/AvoidLifecycleMethodOverride
-        #        # Reason: <explanation>
+        #      # rubocop:disable DevDoc/Rails/AvoidLifecycleMethodOverride -- <explanation>
+        #      def run_validations!
         #        with_access { super }
         #      end
         #

data/lib/rubocop/cop/dev_doc/rails/avoid_rails_callbacks.rb

@@ -86,8 +86,8 @@ module RuboCop
         # genuine exception, disable this cop inline with a written
         # justification — expect pushback in review:
         #
-        #   after_create :some_callback # rubocop:disable DevDoc/Rails/AvoidRailsCallbacks
-        #   # Reason: <explanation>
+        #   # rubocop:disable DevDoc/Rails/AvoidRailsCallbacks -- <explanation>
+        #   after_create :some_callback
         #
         # Both the symbol form and the block form are flagged:
         #
@@ -136,7 +136,7 @@ module RuboCop
             add_offense(node.loc.selector, message: format(MSG, method: node.method_name))
           end
 
-          def on_block(node) # rubocop:disable InternalAffairs/NumblockHandler
+          def on_block(node)
             send_node = node.send_node
             return unless CALLBACKS.include?(send_node.method_name)
 

data/lib/rubocop/cop/dev_doc/rails/enum_column_not_null.rb

@@ -86,7 +86,9 @@ module RuboCop
 
           def enum_column(klass, name)
             table = schema.table_by(name: table_name(klass))
-            table&.columns&.find { |c| c.name == name.to_s }
+            return nil unless table
+
+            table.columns.find { |c| c.name == name.to_s }
           end
 
           def class_node(node)

data/lib/rubocop/cop/dev_doc/route/no_custom_actions.rb

@@ -121,7 +121,10 @@ module RuboCop
             return explicit.method_name.to_s if explicit
 
             # Otherwise the nearest block that isn't a transparent wrapper decides.
-            decider = sends.find { |s| !TRANSPARENT_WRAPPERS.include?(s.method_name) }
+            decider_context(sends.find { |s| !TRANSPARENT_WRAPPERS.include?(s.method_name) })
+          end
+
+          def decider_context(decider)
             return unless decider
 
             return 'collection' if RESOURCEFUL.include?(decider.method_name)

data/lib/rubocop/cop/dev_doc/route/resource_name_number.rb

@@ -48,13 +48,14 @@ module RuboCop
               expected = expected_name(node.method_name, name)
               next if expected == name
 
-              add_offense(
-                arg,
-                message: format(MSG, method: node.method_name, number: number_word(node.method_name), expected: expected)
-              )
+              add_offense(arg, message: offense_message(node.method_name, expected))
             end
           end
 
+          def offense_message(method_name, expected)
+            format(MSG, method: method_name, number: number_word(method_name), expected: expected)
+          end
+
           private
 
           # The resource name as a string, for symbol or string arguments only

data/lib/rubocop/cop/dev_doc/route/resources_require_only.rb

@@ -43,14 +43,13 @@ module RuboCop
           RESTRICT_ON_SEND = %i[resources resource].freeze
 
           def on_send(node)
-            has_only = key_present?(node, :only)
-            has_except = key_present?(node, :except)
+            return if key_present?(node, :only)
 
-            return if has_only
+            has_except = key_present?(node, :except)
             return if has_except && !require_only?
 
             name = node.first_argument&.value || '?'
-            msg = has_except && require_only? ? MSG_REQUIRE_ONLY : MSG
+            msg = has_except ? MSG_REQUIRE_ONLY : MSG
             add_offense(node.loc.selector, message: format(msg, method: node.method_name, name: name))
           end
 

data/lib/rubocop/cop/dev_doc/style/avoid_symbolizing_boundary_input.rb

@@ -0,0 +1,116 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Style
+        # Flag `.to_sym` (including `&.to_sym`, and through laundering hops
+        # like `.presence`/`.to_s`/`.downcase`) chained directly onto an
+        # attacker-controlled boundary source: `params[...]` (also `.dig`,
+        # `.fetch`, `.require`) or `request.headers[...]`.
+        #
+        # ## Rationale
+        # A bare `.to_sym` lets ANY client-supplied value cross into the symbol
+        # domain, where downstream `case`/`==` dispatch treats it as known
+        # vocabulary. The allow-list is the missing DECISION: which values do
+        # we recognise, and what happens to the rest? Skipping it also mints a
+        # symbol per novel value (the classic symbol-DoS vector; GC reclaims
+        # dynamic symbols since Ruby 2.2, so today this is churn rather than a
+        # hard leak — the vocabulary laundering is the real bug).
+        #
+        # Resolve the value through the glib-web helper, which only ever
+        # returns a symbol already in the allow-list:
+        #
+        #   ❌
+        #   @mode = params[:mode]&.to_sym || :active
+        #
+        #   ✔️ (glib-web >= 5.1.2)
+        #   @mode = glib_allowlist_symbol_param(params[:mode], MODES, default: :active)
+        #
+        # When recognised inputs must map to differently-spelled symbols
+        # (e.g. `'spring-promo'` → `:spring_promo`), use an explicit
+        # `case`-when at the boundary instead — same allow-list property.
+        #
+        # ## Sources detected
+        # - `params[…]`, `params.dig(…)`, `params.fetch(…)`, `params.require(…)`
+        # - `request.headers[…]`
+        #
+        # `ENV[…]` is deliberately NOT a source here (unlike the sibling
+        # `DevDoc/Style/StringSymbolComparison`): ENV is operator-controlled,
+        # not attacker-reachable, and `.to_sym` on boot-time config is
+        # legitimate where the controller helper doesn't even exist.
+        #
+        # ## Relationship with DevDoc/Style/StringSymbolComparison
+        # Complementary pair over the same boundary doctrine: that cop flags
+        # comparing an UNCONVERTED string source against a symbol (always
+        # false); this cop flags CONVERTING without validating. The sanctioned
+        # exit from both is the allow-list helper.
+        #
+        # ## Limitations
+        # Only the direct form is caught. Once the value flows through a
+        # helper method (`report_params[:x]`) or a local/instance variable,
+        # static analysis loses the boundary and review has to catch it.
+        # Laundering transforms (`.presence`, `.to_s`, `.strip`,
+        # `.downcase`, `.upcase`, `.squish`) do NOT reset the trail — they
+        # transform, they don't validate.
+        #
+        # @example
+        #   # bad
+        #   @mode = params[:mode]&.to_sym || :active
+        #   @theme = request.headers['X-Theme']&.to_sym
+        #   @segment = params[:segment].presence&.to_sym
+        #   @sort = params[:sort].to_s.downcase.to_sym
+        #
+        #   # good
+        #   @mode = glib_allowlist_symbol_param(params[:mode], MODES, default: :active)
+        class AvoidSymbolizingBoundaryInput < Base
+          MSG = 'Unvalidated `.to_sym` on `%<source>s` lets any client value into the symbol ' \
+                'domain (and mints a symbol per novel value). Allow-list it instead: ' \
+                '`glib_allowlist_symbol_param(value, ALLOWED, default:)`. Laundering through ' \
+                '`.to_s`/`.presence`/`.downcase` is not validation.'.freeze
+
+          RESTRICT_ON_SEND = %i[to_sym].freeze
+
+          # String-preserving transforms that commonly sit between the boundary
+          # read and the `.to_sym` — they launder the value, not validate it,
+          # so the chain is still an offense.
+          TRANSFORM_HOPS = %i[presence to_s strip downcase upcase squish].freeze
+
+          def_node_matcher :params_access?, <<~PATTERN
+            (send (send nil? :params) {:[] :dig :fetch :require} ...)
+          PATTERN
+
+          def_node_matcher :request_headers_access?, <<~PATTERN
+            (send (send _ :headers) :[] _)
+          PATTERN
+
+          def on_send(node)
+            source = boundary_source_in(node.receiver)
+            return unless source
+
+            add_offense(node, message: format(MSG, source: source.source))
+          end
+          alias on_csend on_send
+
+          private
+
+          # The boundary source at the bottom of the receiver chain, walking
+          # through any number of laundering transforms. Returns nil for
+          # anything else (locals, `action_name`, helper-method results) so
+          # those don't false-positive.
+          def boundary_source_in(node)
+            while node
+              return node if boundary_source?(node)
+              return nil unless node.send_type? || node.csend_type?
+              return nil unless TRANSFORM_HOPS.include?(node.method_name)
+
+              node = node.receiver
+            end
+          end
+
+          def boundary_source?(node)
+            params_access?(node) || request_headers_access?(node)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/dev_doc/style/case_else_decision.rb

@@ -15,7 +15,8 @@ module RuboCop
         #
         # 1. **Fall-through genuinely happens in normal operation** — add
         #    `else` with a comment stating WHY it is correct (requires
-        #    `Style/EmptyElse` to be disabled).
+        #    `Style/EmptyElse` with `AllowComments: true`, which keeps that
+        #    cop's guard against comment-less empty elses).
         # 2. **A non-match is a bug and continuing is unsafe** — `else raise`
         #    (fail fast; unexpected enum/mode values must not proceed).
         # 3. **A non-match is a bug but users can safely continue** — report

data/lib/rubocop/cop/dev_doc/style/minimize_variable_scope.rb

@@ -83,21 +83,28 @@ module RuboCop
 
             siblings = parent.children
             nxt = siblings[siblings.index(asgn) + 1]
-            nxt if nxt&.if_type? && !nxt.ternary? && !nxt.modifier_form? && nxt.if?
+            nxt if plain_if?(nxt)
+          end
+
+          # A statement-form `if` (not a ternary, modifier, or unless).
+          def plain_if?(node)
+            node&.if_type? && !node.ternary? && !node.modifier_form? && node.if?
           end
 
           # `if x` or `if x.present?` — a truthiness check on the assigned var.
           def truthiness_check?(condition, name)
             return false unless condition
+            return condition.children.first == name if condition.lvar_type?
 
-            if condition.lvar_type?
-              condition.children.first == name
-            elsif condition.send_type? && TRUTHY_PREDICATES.include?(condition.method_name)
-              recv = condition.receiver
-              recv&.lvar_type? && recv.children.first == name
-            else
-              false
-            end
+            truthy_predicate_on?(condition, name)
+          end
+
+          # `x.present?`-style: a truthy predicate whose receiver is the var.
+          def truthy_predicate_on?(condition, name)
+            return false unless condition.send_type? && TRUTHY_PREDICATES.include?(condition.method_name)
+
+            recv = condition.receiver
+            recv&.lvar_type? && recv.children.first == name
           end
 
           # Every read of `name` in the enclosing scope sits inside the if's
@@ -109,12 +116,15 @@ module RuboCop
             return false unless single_plain_assignment?(scope, name, asgn)
             return false if rebinds_name?(scope, name)
 
+            reads_confined_to?(if_node, reads(scope, name))
+          end
+
+          # Read at least once in the true branch, and every read sits inside
+          # the if's condition or that branch.
+          def reads_confined_to?(if_node, refs)
             true_branch = if_node.if_branch
             return false unless true_branch
-
-            refs = reads(scope, name)
-            in_branch = refs.select { |r| within?(r, true_branch) }
-            return false if in_branch.empty?
+            return false if refs.none? { |r| within?(r, true_branch) }
 
             refs.all? { |r| within?(r, if_node.condition) || within?(r, true_branch) }
           end

data/lib/rubocop/cop/dev_doc/style/no_unscoped_method_definitions.rb

@@ -69,6 +69,13 @@ module RuboCop
         #     def distance
         #     end
         #   end
+        #
+        #   # good — RSpec example group (class_exec'd onto a generated
+        #   # example-group class, so the def does NOT land on Object)
+        #   RSpec.describe Thing do
+        #     def build_thing
+        #     end
+        #   end
         class NoUnscopedMethodDefinitions < Base
           MSG = 'Define methods inside an explicit `module` or `class`, not at the top level ' \
                 'or inside a DSL block (e.g. Rake `namespace`). ' \
@@ -78,6 +85,14 @@ module RuboCop
           # new class exactly like Struct.
           DEFAULT_SAFE_DSL_RECEIVERS = %w[Struct Data Class Module].freeze
 
+          # RSpec example-group blocks are class_exec'd onto a generated
+          # example-group class, so a `def` inside them lands on that class —
+          # not Object. Method-specific (unlike the receiver allowlist above)
+          # because a def inside e.g. `RSpec.configure` DOES land on Object.
+          RSPEC_EXAMPLE_GROUP_METHODS = %i[
+            describe shared_examples shared_examples_for shared_context
+          ].freeze
+
           def on_def(node)
             add_offense(node.loc.keyword) unless enclosed_in_class_or_module?(node)
           end
@@ -110,12 +125,18 @@ module RuboCop
             receiver  = send_node.receiver
 
             return false if receiver.nil?
+            return true if rspec_example_group_block?(send_node, receiver)
 
             safe_receivers.any? do |safe|
               receiver_matches?(receiver, safe)
             end
           end
 
+          def rspec_example_group_block?(send_node, receiver)
+            receiver_matches?(receiver, 'RSpec') &&
+              RSPEC_EXAMPLE_GROUP_METHODS.include?(send_node.method_name)
+          end
+
           def receiver_matches?(receiver, safe_name)
             # Handles `Struct`, `Class`, `Module` (const nodes)
             receiver.const_type? && receiver.short_name.to_s == safe_name