rubocop-dev_doc 0.1.0 → 0.3.0

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

@@ -0,0 +1,102 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Style
+        # Avoid `**options`-style kwargs in method signatures; use explicit keyword args.
+        #
+        # ## Rationale
+        # Keyword args raise `ArgumentError` on typos, are self-labeled at the
+        # call site, and get IDE autocomplete. Options hashes (via `**opts`)
+        # silently swallow misspelled keys, hide what's accepted, and depend on
+        # doc/source-reading to use correctly.
+        #
+        #   ❌ Options hash — typos pass silently
+        #   def configure(name:, **options)
+        #     title = options[:title]
+        #     color = options[:color]
+        #   end
+        #   configure(name: 'x', titel: 'wrong')   # silently ignored — title is nil
+        #
+        #   ✔️ Keyword args — typo raises immediately
+        #   def configure(name:, title: nil, color: nil)
+        #   end
+        #   configure(name: 'x', titel: 'wrong')   # ArgumentError: unknown keyword: :titel
+        #
+        # Pure-forwarding kwargs are exempt — when the only use of the kwrestarg
+        # is to splat it into another call, there is no options-hash behaviour:
+        #
+        #   ✔️ Pure forwarding — exempt
+        #   def foo(**args)
+        #     other(**args)
+        #   end
+        #
+        # Anonymous double-splat (`**`) is also always exempt.
+        #
+        # @example
+        #   # bad
+        #   def configure(name:, **options)
+        #     options[:title]
+        #   end
+        #
+        #   # good
+        #   def configure(name:, title: nil, color: nil)
+        #   end
+        #
+        #   # good (pure forwarding)
+        #   def foo(**args)
+        #     other(**args)
+        #   end
+        class AvoidOptionsHash < Base
+          MSG = 'Use keyword arguments instead of `**%<name>s` — ' \
+                'typos in keyword args raise `ArgumentError`; options hashes swallow them silently.'.freeze
+
+          def on_def(node)
+            check_method(node)
+          end
+          alias on_defs on_def
+
+          private
+
+          def check_method(node)
+            kwrestarg = find_kwrestarg(node)
+            return unless kwrestarg
+
+            kwrest_name = kwrestarg.node_parts[0]
+            return if kwrest_name.nil?
+
+            body = node.body
+            return if pure_forwarding?(body, kwrest_name)
+
+            add_offense(kwrestarg, message: format(MSG, name: kwrest_name))
+          end
+
+          def find_kwrestarg(node)
+            args_node = node.arguments
+            args_node.each_child_node(:kwrestarg).first
+          end
+
+          def pure_forwarding?(body, kwrest_name)
+            return true if body.nil?
+
+            lvar_refs = collect_lvar_refs(body, kwrest_name)
+            return true if lvar_refs.empty?
+
+            lvar_refs.all? { |lvar| under_kwsplat?(lvar) }
+          end
+
+          def collect_lvar_refs(node, name)
+            refs = []
+            node.each_descendant(:lvar) do |lvar|
+              refs << lvar if lvar.node_parts[0] == name
+            end
+            refs
+          end
+
+          def under_kwsplat?(node)
+            node.parent&.kwsplat_type?
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -2,14 +2,16 @@ module RuboCop
   module Cop
     module DevDoc
       module Style
-        # Avoid `send` and `public_send` with an explicit receiver.
+        # Avoid dynamic `send` and `public_send` with an explicit receiver.
         #
         # ## Rationale
         # `send()` can call *any* method, including destructive ones like
-        # `destroy`. When the method name is dynamic, this is a real risk — a
-        # crafted parameter can invoke methods the developer never intended to
-        # expose. If `send()` is unavoidable, add safeguards to restrict which
-        # methods can be called.
+        # `destroy`. The risk is specifically with **dynamic** method names —
+        # when the argument is a variable or interpolated string, a crafted
+        # value could invoke methods the developer never intended to expose.
+        #
+        # **Literal symbol arguments are exempt** — the method name is fixed at
+        # code-write time and visible to reviewers, equivalent to a direct call.
         #
         # ## Safer alternatives
         #
@@ -34,26 +36,56 @@ module RuboCop
         #   ✔️ Restricted — only methods with the prefix can be called
         #   obj.send("export_#{method_name}")
         #
-        # **c) For known methods — call directly instead of via `send`.**
+        # NOTE: A prefix narrows the callable surface but does not eliminate it —
+        # an attacker-controlled suffix can still reach any method sharing the
+        # prefix (e.g. `"export_#{x}"` could hit `export_and_destroy`). Use the
+        # narrowest prefix that fits, and prefer an explicit whitelist when the
+        # set of targets is small.
         #
         # @example
-        #   # bad
+        #   # bad — dynamic method name from a variable
         #   @user.send(method_name)
         #   obj.public_send(action)
         #
-        #   # good
+        #   # bad — interpolation with no static prefix restricts nothing
+        #   obj.send("#{x}")
+        #   obj.send("#{x}_run")
+        #
+        #   # good — literal symbol: method name is statically visible
+        #   instance.send(:private_helper, arg)
+        #
+        #   # good — bracket notation for model attributes
         #   @user[attribute_name]
+        #
+        #   # good — static prefix restricts the callable methods
         #   obj.send("export_#{method_name}")
         class AvoidSend < Base
-          MSG = 'Avoid `%<method>s` with an explicit receiver. ' \
-                'Use bracket notation for model attributes, or restrict callable methods with a prefix.'.freeze
+          MSG = "Avoid dynamic `%<method>s` — use bracket notation for model attributes, " \
+                "or a prefix (`obj.send(\"export_\#{x}\")`) to restrict callable methods.".freeze
           RESTRICT_ON_SEND = %i[send public_send].freeze
 
           def on_send(node)
             return if node.receiver.nil?
 
+            arg = node.first_argument
+            return if arg&.sym_type?
+            return if prefixed_dynamic_method?(arg)
+
             add_offense(node.loc.selector, message: format(MSG, method: node.method_name))
           end
+
+          private
+
+          # A dynamic string/symbol that begins with a static prefix (e.g.
+          # `"export_#{x}"`) restricts the callable surface to methods sharing
+          # that prefix, so it is exempt. Pure interpolation (`"#{x}"`) or a
+          # trailing prefix (`"#{x}_run"`) restricts nothing and is still flagged.
+          def prefixed_dynamic_method?(arg)
+            return false unless arg&.type?(:dstr, :dsym)
+
+            first = arg.children.first
+            first&.str_type? && !first.value.empty?
+          end
         end
       end
     end

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

@@ -0,0 +1,158 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Style
+        # Assign a variable inside the `if` condition that guards it, so the
+        # variable's scope is the branch that actually uses it.
+        #
+        # ## Rationale
+        # When a local is assigned and then immediately gated by a truthiness
+        # check, hoisting the assignment to its own line widens its scope to the
+        # whole method and separates the binding from the guard. Folding the
+        # assignment into the condition (with parentheses) keeps the variable
+        # local to the branch that uses it and reads as one thought.
+        #
+        #   ❌
+        #   token = params[:token]
+        #   if token
+        #     authenticate(token)
+        #   end
+        #
+        #   ✔️
+        #   if (token = params[:token])
+        #     authenticate(token)
+        #   end
+        #
+        # Parentheses around the assignment silence Ruby's "assignment in
+        # condition" warning and signal the assignment is intentional.
+        #
+        # ## When it fires
+        # Only when the assigned variable is used **only** inside the guarding
+        # `if` — its condition plus the true branch — and is read at least once
+        # in that branch. If the variable is read in the `else` branch or after
+        # the block, folding wouldn't narrow its scope, so the cop leaves it.
+        #
+        # ## Exception
+        # When the assigned expression is long, inlining it into the condition
+        # hurts readability more than the scope-narrowing helps. Keep the
+        # two-line form and inline-`disable` with a reason.
+        #
+        # NOTE: Conservative by design — it skips reassigned variables, `op_asgn`
+        # (`+=`, `||=`), compound/comparison conditions, and scopes containing a
+        # nested `def` or a block that rebinds the same name. Those are left
+        # un-flagged rather than risk a wrong rewrite.
+        #
+        # @example
+        #   # bad
+        #   user = account.users.find_by(id: params[:id])
+        #   if user
+        #     redirect_to user
+        #   end
+        #
+        #   # good
+        #   if (user = account.users.find_by(id: params[:id]))
+        #     redirect_to user
+        #   end
+        class MinimizeVariableScope < Base
+          MSG = "Assign `%<name>s` inside the `if` condition " \
+                "(`if (%<name>s = ...)`) so its scope is the branch that uses it.".freeze
+
+          # Truthiness-shaped predicates we fold. Comparisons (`x == 1`) are
+          # deliberately excluded — folding those reads as assignment-in-condition.
+          TRUTHY_PREDICATES = %i[present? any? presence].freeze
+
+          def on_lvasgn(node)
+            name, value = *node
+            return unless value
+
+            if_node = guarding_if(node)
+            return unless if_node
+            return unless truthiness_check?(if_node.condition, name)
+            return unless confined_to_if?(node, if_node, name)
+
+            add_offense(node.loc.name, message: format(MSG, name: name))
+          end
+
+          private
+
+          # The `if` immediately following this assignment as the next statement
+          # in the same body (not a ternary or modifier-if).
+          def guarding_if(asgn)
+            parent = asgn.parent
+            return unless parent&.begin_type?
+
+            siblings = parent.children
+            nxt = siblings[siblings.index(asgn) + 1]
+            nxt if nxt&.if_type? && !nxt.ternary? && !nxt.modifier_form? && nxt.if?
+          end
+
+          # `if x` or `if x.present?` — a truthiness check on the assigned var.
+          def truthiness_check?(condition, name)
+            return false unless condition
+
+            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
+          end
+
+          # Every read of `name` in the enclosing scope sits inside the if's
+          # condition or true branch, it's read at least once in that branch,
+          # and nothing reassigns or rebinds the name.
+          def confined_to_if?(asgn, if_node, name)
+            scope = enclosing_scope(asgn)
+            return false unless scope
+            return false unless single_plain_assignment?(scope, name, asgn)
+            return false if rebinds_name?(scope, name)
+
+            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?
+
+            refs.all? { |r| within?(r, if_node.condition) || within?(r, true_branch) }
+          end
+
+          def enclosing_scope(node)
+            node.each_ancestor(:def, :defs, :block, :numblock, :itblock).first
+          end
+
+          def reads(scope, name)
+            scope.each_descendant(:lvar).select { |n| n.children.first == name }
+          end
+
+          # Exactly one `name = ...` (our node) and no `op_asgn`/`or_asgn`/
+          # `and_asgn` touching it.
+          def single_plain_assignment?(scope, name, asgn)
+            lvasgns = scope.each_descendant(:lvasgn).select { |n| n.children.first == name }
+            return false unless lvasgns.size == 1 && lvasgns.first.equal?(asgn)
+
+            scope.each_descendant(:op_asgn, :or_asgn, :and_asgn).none? do |n|
+              target = n.children.first
+              target.respond_to?(:children) && target.children.first == name
+            end
+          end
+
+          # A nested `def`/`defs` (separate scope) or a block re-binding `name`
+          # would make the read analysis unreliable — bail.
+          def rebinds_name?(scope, name)
+            scope.each_descendant(:def, :defs).any? ||
+              scope.each_descendant(:block).any? do |blk|
+                blk.arguments.any? { |a| a.respond_to?(:name) && a.name == name }
+              end
+          end
+
+          def within?(node, container)
+            node.equal?(container) || node.each_ancestor.any? { |a| a.equal?(container) }
+          end
+        end
+      end
+    end
+  end
+end

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