rubocop-dev_doc 0.11.0 → 0.12.0

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

@@ -102,17 +102,21 @@ module RuboCop
 
             seen = {}
             body.each_descendant(:send) do |send_node|
-              next unless bracket_read?(send_node)
+              track_bracket_read(send_node, seen)
+            end
+          end
+
+          def track_bracket_read(send_node, seen)
+            return unless bracket_read?(send_node)
 
-              receiver = send_node.receiver
-              key = send_node.first_argument
-              composite = composite_key(receiver, key)
+            receiver = send_node.receiver
+            key = send_node.first_argument
+            composite = composite_key(receiver, key)
 
-              if seen[composite]
-                add_offense(send_node.loc.selector, message: format(MSG, receiver: receiver.source, key: key.source))
-              else
-                seen[composite] = true
-              end
+            if seen[composite]
+              add_offense(send_node.loc.selector, message: format(MSG, receiver: receiver.source, key: key.source))
+            else
+              seen[composite] = true
             end
           end
 

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

@@ -85,7 +85,8 @@ module RuboCop
         #     current_user&.full_name
         #   end
         class RepeatedSafeNavigationReceiver < Base
-          MSG = "Receiver `%<receiver>s` already used with `&.` earlier in this method — assign once and use `.` after.".freeze
+          MSG = "Receiver `%<receiver>s` already used with `&.` earlier in this method — " \
+                "assign once and use `.` after.".freeze
 
           def on_def(node)
             check_method(node)
@@ -99,16 +100,18 @@ module RuboCop
             return unless body
 
             seen = {}
-            body.each_descendant(:csend) do |csend|
-              receiver = csend.receiver
-              next unless receiver
+            body.each_descendant(:csend) { |csend| track_receiver(csend, seen) }
+          end
+
+          def track_receiver(csend, seen)
+            receiver = csend.receiver
+            return unless receiver
 
-              key = receiver.source
-              if seen[key]
-                add_offense(csend.loc.dot, message: format(MSG, receiver: key))
-              else
-                seen[key] = true
-              end
+            key = receiver.source
+            if seen[key]
+              add_offense(csend.loc.dot, message: format(MSG, receiver: key))
+            else
+              seen[key] = true
             end
           end
         end

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

@@ -11,16 +11,23 @@ module RuboCop
         # Strings and symbols are not equal in Ruby, and string-typed values
         # arrive from boundaries the developer doesn't control: HTTP params,
         # request headers, ENV. Comparing one of these directly against a
-        # symbol literal is a guaranteed bug. Convert at the boundary instead
-        # — see `best_practices/backend/en/01a_defensive_programming.md` item 7.
+        # symbol literal is a guaranteed bug. Allow-list into a symbol at the
+        # boundary instead — see
+        # `best_practices/backend/en/01a_defensive_programming.md` item 7.
         #
         #   ❌
         #   if params[:status] == :draft   # always false
         #
-        #   ✔ Convert at the boundary, then compare
-        #   @filter_status = params[:status]&.to_sym
+        #   ✔ Allow-list into a symbol at the boundary, then compare
+        #   @filter_status = glib_allowlist_symbol_param(params[:status], STATUSES, default: :draft)
         #   if @filter_status == :draft
         #
+        # A bare `&.to_sym` conversion would also fix the always-false bug,
+        # but it lets ANY client value into the symbol domain — the sibling
+        # `DevDoc/Style/AvoidSymbolizingBoundaryInput` flags exactly that.
+        # The two cops are a complementary pair: this one polices comparing
+        # without converting; that one polices converting without validating.
+        #
         # ## Sources detected
         # - `params[…]`
         # - `request.headers[…]`
@@ -39,12 +46,13 @@ module RuboCop
         #   request.headers['X-Mode'] != :debug
         #
         #   # good
-        #   params[:status]&.to_sym == :draft
+        #   glib_allowlist_symbol_param(params[:status], STATUSES, default: :draft) == :draft
         #   ENV['MODE'] == 'production'
         class StringSymbolComparison < Base
           MSG = 'Comparing string-typed `%<source>s` to a symbol literal is always false. ' \
-                'Convert at the boundary with `&.to_sym` or compare against a string instead ' \
-                '(see backend/01a_defensive_programming.md item 7).'.freeze
+                'Allow-list it into a symbol at the boundary ' \
+                '(`glib_allowlist_symbol_param(value, ALLOWED, default:)`) or compare against ' \
+                'a string instead (see backend/01a_defensive_programming.md item 7).'.freeze
 
           RESTRICT_ON_SEND = %i[== !=].freeze
 

data/lib/rubocop/cop/dev_doc/test/avoid_glib_travel_freeze.rb

@@ -17,8 +17,8 @@ module RuboCop
         # ## Escape hatch
         # Disable per-line with a comment explaining why `glib_travel` doesn't work:
         #
-        #   glib_travel_freeze(time) do  # rubocop:disable DevDoc/Test/AvoidGlibTravelFreeze
-        #     # Reason: <explanation>
+        #   # rubocop:disable DevDoc/Test/AvoidGlibTravelFreeze -- <explanation>
+        #   glib_travel_freeze(time) do
         #   end
         #
         # @example

data/lib/rubocop/cop/dev_doc/test/no_unit_idioms_in_integration_tests.rb

@@ -0,0 +1,134 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Test
+        # Integration tests must be BOUNDARY tests: exercise one entry point
+        # (an HTTP request, or a job for cron-driven flows with no HTTP
+        # surface) and assert only its observable outputs — response status
+        # and body, database state, delivered/enqueued mail. Unit-test idioms
+        # under the integration base class are dishonest by construction: the
+        # base class is a declaration of WHAT KIND of test this is, and the
+        # runtime/static lints trust that declaration.
+        #
+        # ## What flags, and why
+        # - `@controller`, `assigns`, `instance_variable_get`: reaching into
+        #   request-internal state the boundary is supposed to hide.
+        # - `FooService.new` / `FooPolicy.new` (any suffix in
+        #   `UnitClassSuffixes`): instantiating app-layer objects to test or
+        #   query them directly. When used to COMPUTE an expected value, this
+        #   is a circular assertion — the test asks production code what to
+        #   expect, so a bug in that code passes its own test. Pin literals
+        #   or fixture facts instead.
+        # - `FooMailer.with(...)` and any other direct mailer invocation:
+        #   manufacture mail through the flow that actually sends it, then
+        #   read `deliveries`.
+        # - `include FooHelper`: importing production helpers to compute
+        #   expectations — circular, same as above (`*TestHelper` modules are
+        #   exempt).
+        # - `Minitest::Mock`, `.stub(...)`, `require 'minitest/mock'`:
+        #   mock/stub machinery is unit-test tooling by definition.
+        #
+        # ## What deliberately does NOT flag
+        # - Model reads (`Organization.last`, `Member.find_by!`, counts,
+        #   attribute readers): the database is an OUTBOUND edge of the
+        #   boundary — asserting persisted state is the point — and fixture
+        #   lookup is setup.
+        # - Job classes (`FooJob.new`, `perform_now`, `perform_enqueued_jobs`):
+        #   jobs are an INBOUND edge — the entry point for cron flows.
+        #
+        # ## The honesty rule
+        # If the property cannot be observed at any boundary, the test is a
+        # unit test. Declare it: `Glib::LastResortUnitTest` in an exempt
+        # directory with a justification header. An observed evasion (2026-07,
+        # a guard-aware agent bolting a GET onto direct policy assertions)
+        # is why this cop assumes disguise rather than accident. Do not
+        # disable this cop.
+        class NoUnitIdiomsInIntegrationTests < Base
+          MSG = '`%<ref>s` is a unit-test idiom inside an integration test. A boundary test ' \
+                'exercises one entry point (HTTP request, or a job for cron flows) and asserts ' \
+                'only its observable outputs (status, body, DB state, mails). Computing an ' \
+                'expectation with production code is a CIRCULAR assertion (the code grades its ' \
+                'own homework); instantiating app objects or reaching into the controller is ' \
+                'unit testing in disguise, and a bolted-on request does not change what it is. ' \
+                'Be honest about what this test is: assert through the boundary, or declare a ' \
+                'real unit test (Glib::LastResortUnitTest + exempt directory + justification ' \
+                'header). Do not disable this cop.'.freeze
+
+          CONTROLLER_INTERNALS = %i[assigns instance_variable_get].freeze
+          HELPER_EXEMPT = /TestHelper\z|MailerTester\z/
+          MOCK_REQUIRES = ['minitest/mock'].freeze
+
+          # Baseline lives in code (config lists are droppable; see
+          # CurrentUserBranching's DEFAULT_ALLOWED_METHODS for the incident
+          # that taught this). The yml key ADDS suffixes, it cannot remove
+          # these.
+          DEFAULT_UNIT_CLASS_SUFFIXES = %w[Service Policy Form Presenter Serializer Decorator].freeze
+
+          def on_ivar(node)
+            return unless node.children.first == :@controller
+
+            add_offense(node, message: format(MSG, ref: '@controller'))
+          end
+
+          def on_send(node)
+            ref = offense_ref(node)
+            return unless ref
+
+            add_offense(node, message: format(MSG, ref: ref))
+          end
+
+          private
+
+          def offense_ref(node)
+            return node.method_name.to_s if CONTROLLER_INTERNALS.include?(node.method_name)
+            return "#{node.receiver.const_name}.new" if unit_class_instantiation?(node)
+            return "#{node.receiver.const_name}.#{node.method_name}" if mailer_invocation?(node)
+            return "include #{node.first_argument.const_name}" if helper_include?(node)
+
+            mock_machinery_ref(node)
+          end
+
+          def unit_class_instantiation?(node)
+            node.method_name == :new && receiver_const_suffix?(node, unit_class_suffixes)
+          end
+
+          def mailer_invocation?(node)
+            receiver_const_suffix?(node, ['Mailer'])
+          end
+
+          def helper_include?(node)
+            return false unless node.method_name == :include && node.first_argument&.const_type?
+
+            name = node.first_argument.const_name
+            name.end_with?('Helper') && !name.match?(HELPER_EXEMPT)
+          end
+
+          def mock_machinery_ref(node)
+            return 'Minitest::Mock' if receiver_const_suffix?(node, ['Minitest::Mock']) || minitest_mock_const?(node)
+            return 'stub' if node.method_name == :stub && node.receiver
+            return "require 'minitest/mock'" if mock_require?(node)
+
+            nil
+          end
+
+          def minitest_mock_const?(node)
+            node.method_name == :new && node.receiver&.const_type? && node.receiver.const_name == 'Minitest::Mock'
+          end
+
+          def mock_require?(node)
+            node.method_name == :require && node.first_argument&.str_type? &&
+              MOCK_REQUIRES.include?(node.first_argument.value)
+          end
+
+          def receiver_const_suffix?(node, suffixes)
+            node.receiver&.const_type? && suffixes.any? { |suffix| node.receiver.const_name.end_with?(suffix) }
+          end
+
+          def unit_class_suffixes
+            DEFAULT_UNIT_CLASS_SUFFIXES + cop_config.fetch('UnitClassSuffixes', []).map(&:to_s)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/dev_doc/plugin.rb

@@ -1,5 +1,7 @@
 module RuboCop
   module DevDoc
+    # lint_roller entry point: tells RuboCop where this gem's cops and
+    # default configuration live.
     class Plugin < LintRoller::Plugin
       def about
         LintRoller::About.new(

data/lib/rubocop/dev_doc/version.rb

@@ -1,5 +1,5 @@
 module RuboCop
   module DevDoc
-    VERSION = "0.11.0".freeze
+    VERSION = "0.12.0".freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-dev_doc
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - dev-doc contributors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-10 00:00:00.000000000 Z
+date: 2026-07-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -90,6 +90,8 @@ files:
 - config/obsoletion.yml
 - lib/dev_doc/i18n/pseudo_locale.rb
 - lib/dev_doc/test/best_practice_lints.rb
+- lib/dev_doc/test/lints/cop_drift_check.rb
+- lib/dev_doc/test/lints/cop_drift_test.rb
 - lib/dev_doc/test/lints/cron_schedule.rb
 - lib/dev_doc/test/lints/duplicate_snapshot.rb
 - lib/dev_doc/test/lints/http_driven_controller_tests.rb
@@ -137,6 +139,7 @@ files:
 - lib/rubocop/cop/dev_doc/style/avoid_head_response.rb
 - lib/rubocop/cop/dev_doc/style/avoid_insecure_send.rb
 - lib/rubocop/cop/dev_doc/style/avoid_options_hash.rb
+- lib/rubocop/cop/dev_doc/style/avoid_symbolizing_boundary_input.rb
 - lib/rubocop/cop/dev_doc/style/case_else_decision.rb
 - lib/rubocop/cop/dev_doc/style/literal_operator_in_condition.rb
 - lib/rubocop/cop/dev_doc/style/literal_or_in_when_clause.rb
@@ -152,6 +155,7 @@ files:
 - lib/rubocop/cop/dev_doc/test/avoid_unit_test.rb
 - lib/rubocop/cop/dev_doc/test/justification_header.rb
 - lib/rubocop/cop/dev_doc/test/no_persistence_in_mailer_previews.rb
+- lib/rubocop/cop/dev_doc/test/no_unit_idioms_in_integration_tests.rb
 - lib/rubocop/cop/dev_doc/test/require_glib_integration_base.rb
 - lib/rubocop/cop/dev_doc/test/require_glib_travel.rb
 - lib/rubocop/cop/dev_doc/test/require_glib_travel_block.rb