rubocop-dev_doc 0.2.0 → 0.3.1

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

@@ -0,0 +1,129 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Style
+        # Flag `def` / `define_method` whose enclosing scope chain does not
+        # include a `class` or `module` body — the method lands on `Object`.
+        #
+        # ## Rationale
+        # A `def` not inside an explicit `class` or `module` body defines a
+        # method on `Object`, even when it visually looks scoped. The most common
+        # failure mode is inside Rake's `namespace` block:
+        #
+        #   ❌ Two rake files both define `build_load_plan` — whichever file
+        #      loads second silently wins. Tests for one task call the other
+        #      task's helper logic without warning.
+        #   namespace :faqs do
+        #     def build_load_plan(fixtures, by_slug)
+        #       ...
+        #     end
+        #   end
+        #
+        #   ✔️ Wrapped in a real Ruby scope — no collision risk.
+        #   module FaqsLoader
+        #     extend self
+        #
+        #     def build_load_plan(fixtures, by_slug)
+        #       ...
+        #     end
+        #   end
+        #
+        # Core's `Style/TopLevelMethodDefinition` catches literal top-level
+        # `def` (not inside any block) but misses the rake `namespace` pattern
+        # because the `def` is technically inside a `block` node. This cop
+        # subsumes that case — disable `Style/TopLevelMethodDefinition` when
+        # this cop is enabled to avoid double-flagging.
+        #
+        # ## Allowlist
+        # Some DSLs legitimately define methods inside blocks where the block's
+        # receiver is not `Object` (`Struct.new`, `Class.new`, `Module.new`).
+        # Configure `SafeDSLReceivers` to extend the allowlist.
+        #
+        # @example
+        #   # bad — literal top-level def
+        #   def helper_method
+        #   end
+        #
+        #   # bad — inside a rake namespace (lands on Object)
+        #   namespace :faqs do
+        #     def build_load_plan(fixtures, by_slug)
+        #     end
+        #   end
+        #
+        #   # good — inside an explicit module
+        #   module FaqsLoader
+        #     extend self
+        #
+        #     def build_load_plan(fixtures, by_slug)
+        #     end
+        #   end
+        #
+        #   # good — inside an explicit class
+        #   class FaqsImporter
+        #     def import
+        #     end
+        #   end
+        #
+        #   # good — Struct.new block (allowlisted by default)
+        #   Point = Struct.new(:x, :y) do
+        #     def distance
+        #     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`). ' \
+                'Methods defined here land on `Object` and can silently collide across files.'.freeze
+
+          DEFAULT_SAFE_DSL_RECEIVERS = %w[Struct Class Module].freeze
+
+          def on_def(node)
+            add_offense(node.loc.keyword) unless enclosed_in_class_or_module?(node)
+          end
+          alias on_defs on_def
+
+          def on_send(node)
+            return unless node.method_name == :define_method
+            return if enclosed_in_class_or_module?(node)
+
+            add_offense(node.loc.selector)
+          end
+
+          private
+
+          def enclosed_in_class_or_module?(node)
+            node.each_ancestor.any? do |ancestor|
+              next true if ancestor.class_type? || ancestor.module_type?
+              next true if safe_dsl_block?(ancestor)
+
+              false
+            end
+          end
+
+          # A `block` node is safe when its method call receiver is an
+          # allowlisted DSL (Struct.new, Class.new, Module.new, etc.)
+          def safe_dsl_block?(node)
+            return false unless node.block_type?
+
+            send_node = node.send_node
+            receiver  = send_node.receiver
+
+            return false if receiver.nil?
+
+            safe_receivers.any? do |safe|
+              receiver_matches?(receiver, safe)
+            end
+          end
+
+          def receiver_matches?(receiver, safe_name)
+            # Handles `Struct`, `Class`, `Module` (const nodes)
+            receiver.const_type? && receiver.short_name.to_s == safe_name
+          end
+
+          def safe_receivers
+            DEFAULT_SAFE_DSL_RECEIVERS + Array(cop_config.fetch('SafeDSLReceivers', []))
+          end
+        end
+      end
+    end
+  end
+end

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