rubocop-dev_doc 0.2.0 → 0.3.0

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

@@ -0,0 +1,150 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Style
+        # Avoid reading `obj[key]` more than once with the same receiver and
+        # same key in a single method body.
+        #
+        # ## Rationale
+        # When the same bracket read appears in multiple places, two distinct
+        # failure modes open up:
+        #
+        # 1. **Silent typos.** Bracket access returns nil for missing keys;
+        #    nothing raises. Two occurrences of `params[:status]` keep the
+        #    spelling in sync, but if one of them silently becomes
+        #    `params[:stutus]`, the line returns nil and the bug ships. A
+        #    single assignment fixes the spelling in exactly one place — a
+        #    typo there becomes a `NameError`, not a silent nil.
+        #
+        # 2. **Reader ambiguity and mutation risk.** The reader has to verify
+        #    every occurrence really is the same key and that nothing in
+        #    between mutates the hash. Assigning once makes the value a
+        #    stable named thing — and on receivers like `session` or shared
+        #    hashes, it also avoids a real TOCTOU shape where the value can
+        #    change between the guard and the use.
+        #
+        #   ❌
+        #   def show
+        #     @item = Item.lookup_by_slug(params[:slug])
+        #     redirect_to canonical_url(@item) if @item.slug != params[:slug]
+        #   end
+        #
+        #   ✔️
+        #   def show
+        #     slug  = params[:slug]
+        #     @item = Item.lookup_by_slug(slug)
+        #     redirect_to canonical_url(@item) if @item.slug != slug
+        #   end
+        #
+        # The cop only counts reads. `obj[k] = v` is a write (`:[]=`) and is
+        # not compared against bracket reads of the same key.
+        #
+        # ## Exception
+        # Genuine intentional re-reads (e.g. a deliberate second check after
+        # a write that may have mutated the receiver) go through inline
+        # `# rubocop:disable` with a reason.
+        #
+        # NOTE: Receiver and key are compared by source text — `hash['foo']`
+        # and `hash[:foo]` look different to the cop even though they're the
+        # same value on a `HashWithIndifferentAccess` like `params`. That is
+        # a known false negative; the cop will miss that shape rather than
+        # over-fire.
+        #
+        # NOTE: Scope is the enclosing `def`/`defs` body, including nested
+        # blocks. Block parameters are scoped to their block, so the same name
+        # in two sibling blocks (`arr.each { |item| item[:k] }; other.each {
+        # |item| item[:k] }`) is correctly treated as two different bindings,
+        # not a repeat. Reads of the same block param *within one block* are
+        # still flagged. (Numbered/`it` block params are matched textually — a
+        # rare residual false positive; inline-disable if it surfaces.)
+        #
+        # NOTE: Multi-argument bracket calls (`arr[i, len]`, slicing) are
+        # ignored. Only single-argument reads participate.
+        #
+        # @example
+        #   # bad — same key read twice
+        #   def show
+        #     @item = Item.lookup_by_slug(params[:slug])
+        #     redirect_to canonical_url(@item) if @item.slug != params[:slug]
+        #   end
+        #
+        #   # bad — guard-then-use re-reads the receiver
+        #   def session_get(key)
+        #     return nil unless session[key]
+        #     session[key].symbolize_keys
+        #   end
+        #
+        #   # good — assign once
+        #   def session_get(key)
+        #     payload = session[key]
+        #     return nil unless payload
+        #     payload.symbolize_keys
+        #   end
+        #
+        #   # good — different keys, no offense
+        #   def filters
+        #     @search = params[:search]
+        #     @status = params[:status]
+        #   end
+        class RepeatedBracketRead < Base
+          MSG = "Receiver `%<receiver>s[%<key>s]` already read earlier in this method — assign once and reuse.".freeze
+
+          def on_def(node)
+            check_method(node)
+          end
+          alias on_defs on_def
+
+          private
+
+          def check_method(def_node)
+            body = def_node.body
+            return unless body
+
+            seen = {}
+            body.each_descendant(:send) do |send_node|
+              next unless bracket_read?(send_node)
+
+              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
+            end
+          end
+
+          # Block parameters are scoped to their block: the same name read in two
+          # sibling blocks is a *different* binding, not a repeat. Key those reads
+          # by their binding block so they don't collide. Method-call / ivar /
+          # method-local receivers keep a purely textual key.
+          def composite_key(receiver, key_node)
+            key = key_node.source
+            block = binding_block(receiver)
+            block ? "#{block.object_id}|#{receiver.source}|#{key}" : "#{receiver.source}|#{key}"
+          end
+
+          # The nearest enclosing block that binds the receiver as a block
+          # argument, or nil when the receiver is not a block-local variable.
+          def binding_block(receiver)
+            return nil unless receiver.lvar_type?
+
+            name = receiver.children.first
+            receiver.each_ancestor(:block) do |block|
+              return block if block.arguments.any? { |arg| arg.respond_to?(:name) && arg.name == name }
+            end
+            nil
+          end
+
+          def bracket_read?(node)
+            node.method_name == :[] &&
+              node.receiver &&
+              node.arguments.size == 1
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,118 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Style
+        # Avoid using `&.` on the same receiver more than once in a method body.
+        #
+        # ## Rationale
+        # When a receiver appears with `&.` repeatedly across a method, the
+        # reader has to mentally re-evaluate the nil case at every call, and
+        # the *intent* of each `&.` becomes ambiguous — is this call nullable
+        # for a fresh reason, or is the dev just mirroring the earlier `&.`
+        # out of habit? Repetition also propagates nil silently into
+        # downstream comparisons (`current_user&.id == something` evaluates
+        # to `nil == something`, which is false but not for the reason the
+        # reader expects).
+        #
+        # Resolve the nil case once at the top of the method, then use the
+        # local with plain `.`:
+        #
+        #   ❌
+        #   def show?
+        #     current_user&.super_admin? ||
+        #       current_user&.developer?  ||
+        #       current_user&.admin_of_organization?(organization)
+        #   end
+        #
+        #   ✔️ Guard once, then plain calls
+        #   def show?
+        #     return false unless current_user
+        #
+        #     current_user.super_admin? ||
+        #       current_user.developer?  ||
+        #       current_user.admin_of_organization?(organization)
+        #   end
+        #
+        #   ✔️ Alternative — assign-and-test in the condition
+        #   def label
+        #     if (user = current_user)
+        #       "#{user.full_name} <#{user.email}>"
+        #     end
+        #   end
+        #
+        # The cop is policy-safe by design: it does not assume anything
+        # about `current_user` non-nullability or branching semantics — it
+        # only flags repeated `&.` on the same receiver, which is a smell
+        # regardless of whether the receiver is `current_user`, a model
+        # attribute, or a local variable.
+        #
+        # ## Exception
+        # Legitimate cases (e.g. when the repeated calls are conceptually
+        # distinct sources that happen to share source spelling) go through
+        # inline `# rubocop:disable` with a reason.
+        #
+        # NOTE: Receivers are compared by source text — two `&.` calls
+        # share a receiver if their source spelling matches verbatim. The
+        # cop does not perform flow analysis, so a receiver reassigned
+        # between uses is not detected (false negative).
+        #
+        # NOTE: Scope is the enclosing `def`/`defs` body. The cop does not
+        # partition by inner blocks, so the same parameter name reused
+        # across separate block bodies in one method may produce a false
+        # positive — inline-disable with a reason if it surfaces.
+        #
+        # @example
+        #   # bad — same receiver, multiple safe-nav reads
+        #   def card
+        #     name = current_user&.full_name
+        #     email = current_user&.email
+        #   end
+        #
+        #   # bad — same receiver, multiple safe-nav predicates
+        #   def show?
+        #     user&.super_admin? || user&.developer?
+        #   end
+        #
+        #   # good — assign once, then plain calls
+        #   def show?
+        #     return false unless user
+        #
+        #     user.super_admin? || user.developer?
+        #   end
+        #
+        #   # good — single use of safe-nav
+        #   def label
+        #     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
+
+          def on_def(node)
+            check_method(node)
+          end
+          alias on_defs on_def
+
+          private
+
+          def check_method(def_node)
+            body = def_node.body
+            return unless body
+
+            seen = {}
+            body.each_descendant(:csend) do |csend|
+              receiver = csend.receiver
+              next unless receiver
+
+              key = receiver.source
+              if seen[key]
+                add_offense(csend.loc.dot, message: format(MSG, receiver: key))
+              else
+                seen[key] = true
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Test
+        # Flag `glib_travel_freeze` calls in test files — use `glib_travel` instead.
+        #
+        # ## Rationale
+        # `glib_travel_freeze` stops the clock completely, which is not representative
+        # of real-world behavior: in production, time ticks as code executes.
+        # We have had bugs that went undetected in tests because `glib_travel_freeze`
+        # masked timing issues, only to surface in production.
+        #
+        # `glib_travel` advances time normally inside the block — use it instead.
+        # Reserve `glib_travel_freeze` only as a last resort when `glib_travel`
+        # truly cannot work for a specific test, and document why.
+        #
+        # ## 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>
+        #   end
+        #
+        # @example
+        #   # bad
+        #   glib_travel_freeze(Time.current) do
+        #     expect(order.expired?).to be true
+        #   end
+        #
+        #   # bad (non-block form)
+        #   glib_travel_freeze(Time.current)
+        #   expect(order.expired?).to be true
+        #
+        #   # good
+        #   glib_travel(Time.current) do
+        #     expect(order.expired?).to be true
+        #   end
+        class AvoidGlibTravelFreeze < Base
+          MSG = 'Avoid `glib_travel_freeze` — use `glib_travel` instead. ' \
+                'Frozen time masks timing bugs that surface in production. ' \
+                'Use `# rubocop:disable DevDoc/Test/AvoidGlibTravelFreeze` ' \
+                'with a comment explaining why `glib_travel` cannot work for this test.'
+
+          RESTRICT_ON_SEND = %i[glib_travel_freeze].freeze
+
+          def on_send(node)
+            add_offense(node.loc.selector)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Test
+        # Prefer controller tests; flag unit/service tests (`< ActiveSupport::TestCase`).
+        #
+        # ## Rationale
+        # What the user sees and experiences is what matters; internal
+        # implementation does not. A controller test exercises behaviour
+        # end-to-end through the same path a user takes, so it catches the
+        # regressions that actually reach production. A unit/service test is only
+        # needed when a code path genuinely cannot be reached through a
+        # controller test (very rare) — e.g. a search-ranking detail the
+        # controller never exposes.
+        #
+        # This cop flags only the literal `< ActiveSupport::TestCase`
+        # superclass. The blessed blackbox bases —
+        # `ActionDispatch::IntegrationTest`, `Glib::IntegrationTest`,
+        # `ActionMailer::TestCase`, `ActiveJob::TestCase` — are NOT flagged, even
+        # though they inherit from `ActiveSupport::TestCase` transitively.
+        #
+        # ## Escape hatch
+        # When a unit test is genuinely necessary, suppress with a reason that
+        # explains why a controller test can't cover the path. That reason IS the
+        # required justification — keep it specific and reviewable:
+        #
+        #   # rubocop:disable DevDoc/Test/AvoidUnitTest -- search ranking isn't visible through the controller
+        #   class Ai::Retrieval::PgSearchStrategyTest < ActiveSupport::TestCase
+        #     # ...
+        #   end
+        #   # rubocop:enable DevDoc/Test/AvoidUnitTest
+        #
+        # NOTE: The cop matches the *direct* superclass only. A project base
+        # (`class ApplicationServiceTest < ActiveSupport::TestCase`) is flagged
+        # once (justify it there); subclasses of that base are not re-flagged.
+        #
+        # @example
+        #   # bad
+        #   class NoteRenderingTest < ActiveSupport::TestCase
+        #   end
+        #
+        #   # good — exercised through the controller
+        #   class NotesControllerTest < ActionDispatch::IntegrationTest
+        #   end
+        #
+        #   # good — genuinely unit-only, justified with a reason
+        #   # rubocop:disable DevDoc/Test/AvoidUnitTest -- <why a controller test can't cover this>
+        #   class SomeServiceTest < ActiveSupport::TestCase
+        #   end
+        #   # rubocop:enable DevDoc/Test/AvoidUnitTest
+        class AvoidUnitTest < Base
+          MSG = 'Prefer a controller test — unit tests are a rare exception. If a controller test ' \
+                'genuinely cannot cover this path, disable this cop on the class with a reason.'.freeze
+
+          def on_class(node)
+            superclass = node.parent_class
+            return unless superclass&.const_type?
+            return unless superclass.const_name == 'ActiveSupport::TestCase'
+
+            add_offense(superclass)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,179 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Test
+        # Controller tests that assert on the rendered `response.body` should
+        # also snapshot the full response with `response_assert_equal`.
+        #
+        # ## Rationale
+        # `response_assert_equal` (glib-web's `Glib::TestHelpers`) is the most
+        # blackbox assertion available — it snapshots the entire rendered
+        # response, so it catches regressions anywhere in the output, not just
+        # the one substring a targeted assertion happens to check. Per the
+        # testing best practice, happy- and unhappy-path controller tests
+        # should always use it.
+        #
+        # The common slip this cop guards against: a test inspects the rendered
+        # body with `assert_match` / `assert_no_match` / `assert_includes` /
+        # `response.body.scan(...)` but forgets the snapshot. The targeted
+        # assertion documents intent, but on its own it only proves the one
+        # line — collateral changes elsewhere in the response slip through.
+        #
+        #   ❌ Inspects the body, but no snapshot
+        #   test 'index lists the item' do
+        #     get items_url(format: :json)
+        #     assert_response :success
+        #     assert_match 'Widget', response.body
+        #   end
+        #
+        #   ✔️ Keep the focused assertion AND snapshot the whole response
+        #   test 'index lists the item' do
+        #     get items_url(format: :json)
+        #     assert_response :success
+        #     assert_match 'Widget', response.body
+        #     response_assert_equal
+        #   end
+        #
+        # ## What is NOT flagged
+        # - Tests that already call `response_assert_equal`.
+        # - Exception/redirect paths — a test asserting a non-success status
+        #   (`assert_response :not_found`, `:forbidden`, `:redirect`, etc.)
+        #   often has no stable rendered body to snapshot.
+        # - State-change tests that never read `response.body` (e.g.
+        #   `assert_difference 'Model.count'`, mailer assertions). Passing
+        #   `response.body` to a helper like `submit_form(response.body, ...)`
+        #   is not a body assertion and is not flagged.
+        #
+        # ## Inline disable
+        # For the rare happy-path test whose response is genuinely
+        # non-deterministic and cannot be made stable, add a
+        # `rubocop:disable DevDoc/Test/ResponseAssertEqual` comment to the
+        # `test '...' do` line, with a written reason on the next line
+        # (e.g. "chunked response includes a per-run boundary token").
+        #
+        # @example
+        #   # bad
+        #   test 'shows the row' do
+        #     get foo_url(format: :json)
+        #     assert_match 'bar', response.body
+        #   end
+        #
+        #   # good
+        #   test 'shows the row' do
+        #     get foo_url(format: :json)
+        #     assert_match 'bar', response.body
+        #     response_assert_equal
+        #   end
+        class ResponseAssertEqual < Base
+          MSG = 'Asserts on `response.body` but never calls `response_assert_equal`. ' \
+                'Add the snapshot assertion (usually last) — it captures the whole rendered ' \
+                'response, a stronger guard than a targeted body assertion. Exception-path ' \
+                'tests that cannot snapshot may disable this cop with a reason.'.freeze
+
+          # @!method test_block?(node)
+          def_node_matcher :test_block?, <<~PATTERN
+            (block (send nil? :test ...) _args _body)
+          PATTERN
+
+          # @!method response_body_read?(node)
+          def_node_matcher :response_body_read?, <<~PATTERN
+            (send (send nil? :response) {:body :parsed_body})
+          PATTERN
+
+          # @!method calls_snapshot?(node)
+          def_node_search :calls_snapshot?, <<~PATTERN
+            (send nil? :response_assert_equal)
+          PATTERN
+
+          # @!method response_status?(node)
+          def_node_matcher :response_status?, '(send (send nil? :response) :status)'
+
+          # Non-success HTTP statuses (symbol form). A test asserting any of
+          # these is an exception / redirect / empty-body path — no JSON body
+          # to snapshot.
+          NON_SUCCESS_STATUS_SYMBOLS = %i[
+            not_found forbidden unauthorized unprocessable_entity unprocessable_content
+            bad_request conflict gone no_content not_modified redirect moved_permanently
+            found see_other payment_required too_many_requests precondition_failed
+          ].freeze
+
+          def on_block(node)
+            return unless test_block?(node)
+            return unless node.body
+            return if calls_snapshot?(node)
+            return if exempt_from_snapshot?(node)
+            return unless inspects_response_body?(node)
+
+            add_offense(node.send_node.loc.selector)
+          end
+
+          private
+
+          # Exception / redirect / empty-body responses can't (and shouldn't) be
+          # snapshotted. Handles both the `assert_response :symbol` convention
+          # and the numeric `assert_response 404` / `assert_equal 404,
+          # response.status` convention, plus `assert_empty response.body`.
+          def exempt_from_snapshot?(test_node)
+            test_node.each_descendant(:send).any? { |s| non_snapshotable_assertion?(s) }
+          end
+
+          def non_snapshotable_assertion?(send_node)
+            case send_node.method_name
+            when :assert_response then non_success_status?(send_node.first_argument)
+            when :assert_equal then non_success_status_equal?(send_node)
+            when :assert_empty then response_body_read?(send_node.first_argument)
+            else false
+            end
+          end
+
+          # `assert_equal <non-2xx code>, response.status`
+          def non_success_status_equal?(send_node)
+            args = send_node.arguments
+            args.size >= 2 && non_success_status?(args[0]) && response_status?(args[1])
+          end
+
+          # A non-success status: a symbol (`:not_found`) or a numeric code
+          # >= 300 (`404`). 2xx codes are NOT exempt — they should snapshot.
+          def non_success_status?(node)
+            return false unless node
+
+            (node.sym_type? && NON_SUCCESS_STATUS_SYMBOLS.include?(node.value)) ||
+              (node.int_type? && node.value >= 300)
+          end
+
+          # True when the test inspects the response *as JSON*. Three forms count:
+          #   - `response.parsed_body` (any use — it's the JSON-parsed body)
+          #   - `JSON.parse(response.body)` (explicit JSON parse, even if the
+          #     result is stored in a local first)
+          #   - `response.body` directly inside an assertion
+          #     (`assert_match 'x', response.body`)
+          #
+          # Deliberately NOT counted: `response.body` fed to a format-specific
+          # parser (`parse_xlsx`, `CSV.parse`, `Nokogiri…parse`) or a render/submit
+          # helper (`submit_form`) — those are non-JSON or pass-through, and
+          # `response_assert_equal` (JSON-only) can't snapshot them.
+          def inspects_response_body?(test_node)
+            test_node.each_descendant(:send).any? do |read|
+              next false unless response_body_read?(read)
+
+              read.method_name == :parsed_body || asserted?(read) || json_parsed?(read)
+            end
+          end
+
+          # `response.body` / `response.parsed_body` read within an assertion.
+          def asserted?(read)
+            read.each_ancestor(:send).any? { |a| a.method_name.to_s.start_with?('assert') }
+          end
+
+          # `JSON.parse(response.body)` — the JSON constant specifically, so
+          # format-specific parsers (`parse_xlsx`, `CSV.parse`) don't match.
+          def json_parsed?(read)
+            parent = read.parent
+            parent&.send_type? && parent.method_name == :parse &&
+              parent.receiver&.const_type? && parent.receiver.const_name == 'JSON'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/dev_doc/version.rb

@@ -1,5 +1,5 @@
 module RuboCop
   module DevDoc
-    VERSION = "0.1.0".freeze
+    VERSION = "0.3.0".freeze
   end
 end