rubocop-dev_doc 0.2.0 → 0.3.0

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

@@ -0,0 +1,171 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Route
+        # Avoid custom `member` / `collection` actions; model them as RESTful
+        # sub-resources instead.
+        #
+        # ## Rationale
+        # Follow Rails' standard REST principles as much as possible. A resource
+        # exposes seven standard actions (`index`, `show`, `new`, `create`,
+        # `edit`, `update`, `destroy`); anything declared through a `member` or
+        # `collection` block is a custom verb bolted onto the resource. Each one
+        # is better expressed as its own RESTful sub-resource — the action then
+        # reads as a noun being created/destroyed, scopes cleanly under Pundit
+        # policies, and keeps every controller a thin CRUD controller.
+        #
+        #   ❌ POST /products/3/activate
+        #   resources :products, only: [:show] do
+        #     member { post :activate }
+        #   end
+        #
+        #   ✔️ POST /products/3/activations  (create an activation)
+        #   resources :products, only: [:show] do
+        #     resources :activations, only: [:create]
+        #   end
+        #
+        #   ✔️ a mode on the standard edit/update, when it's really one resource
+        #   PATCH /products/3?mode=activate
+        #
+        # A reversible pair (`activate` / `deactivate`, `lock` / `unlock`,
+        # `archive` / `restore`) maps naturally onto `create` / `destroy` of one
+        # sub-resource.
+        #
+        # ## Exception
+        # The doc says "as much as possible" — some custom actions are genuinely
+        # awkward to model as a sub-resource (a multi-step wizard step, a
+        # non-CRUD report endpoint). For those, disable the cop on the line with
+        # a written reason, e.g.:
+        #
+        #   member do
+        #     # rubocop:disable DevDoc/Route/NoCustomActions
+        #     get :balance # multi-step finalize wizard; not a persisted resource
+        #     # rubocop:enable DevDoc/Route/NoCustomActions
+        #   end
+        #
+        # This cop flags every form a custom resource action takes:
+        #   - inside a `member` / `collection` block
+        #   - the inline `on: :member` / `on: :collection` option
+        #     (`get :activate, on: :member`)
+        #   - a bare verb directly inside a `resources` / `resource` block,
+        #     which Rails treats as a collection route (`resources :x do
+        #     get :search end`)
+        #   - a bare verb inside a `concern` block (its routes are mixed into
+        #     resources, so a custom verb there is a custom resource action)
+        #
+        # `constraints` / `defaults` wrappers between the verb and its resource
+        # are transparent — a custom action nested inside them is still caught.
+        #
+        # NOTE: Stand-alone non-resource routes (`get 'sitemap.xml'`,
+        # `get 'proxy'`) and verbs scoped by a `namespace` / `scope` block are
+        # not resourceful, and are intentionally left alone. A custom action
+        # written as a flat top-level route (`get 'photos/search', to:
+        # 'photos#search'`) is indistinguishable from such a route and cannot be
+        # flagged without false positives — that case is left to review.
+        #
+        # @example
+        #   # bad
+        #   resources :products, only: [:show] do
+        #     member do
+        #       post :activate
+        #       post :deactivate
+        #     end
+        #   end
+        #
+        #   # good
+        #   resources :products, only: [:show] do
+        #     resources :activations, only: %i[create destroy]
+        #   end
+        class NoCustomActions < Base
+          MSG = 'Custom `%<context>s` action `%<verb>s %<name>s`. Model it as a RESTful ' \
+                'sub-resource (e.g. `resources :activations, only: [:create]`) instead. ' \
+                'Disable with a reason if a custom action is genuinely unavoidable.'.freeze
+
+          RESTRICT_ON_SEND = %i[get post patch put delete match].freeze
+
+          MEMBER_OR_COLLECTION = %i[member collection].freeze
+          RESOURCEFUL = %i[resources resource].freeze
+          # Wrappers that add conditions but do not change whether the verb is a
+          # resource action — walk through them to find the real context.
+          TRANSPARENT_WRAPPERS = %i[constraints defaults].freeze
+
+          def on_send(node)
+            context = routing_context(node)
+            return unless context
+
+            add_offense(
+              node.loc.selector,
+              message: format(MSG, context: context, verb: node.method_name, name: action_name(node))
+            )
+          end
+
+          private
+
+          # The routing context that makes this verb a custom resource action,
+          # or nil if it is a stand-alone route. Shapes that count:
+          #   - inside a `member` / `collection` block (at any depth)
+          #   - the inline `on: :member` / `on: :collection` / `on: :new` option
+          #   - a bare verb whose nearest non-transparent enclosing block is
+          #     `resources` / `resource` (a collection route) or `concern`
+          # `constraints` / `defaults` wrappers are transparent (walked through);
+          # a `namespace` / `scope` block turns the verb into a stand-alone route
+          # and stops the search.
+          def routing_context(node)
+            inline = inline_on_context(node)
+            return inline if inline
+
+            sends = enclosing_routing_sends(node)
+
+            # `member` / `collection` mark a custom action at any nesting depth.
+            explicit = sends.find { |s| MEMBER_OR_COLLECTION.include?(s.method_name) }
+            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) }
+            return unless decider
+
+            return 'collection' if RESOURCEFUL.include?(decider.method_name)
+
+            'concern' if decider.method_name == :concern
+          end
+
+          # The block call-sends enclosing this node, innermost first, limited to
+          # DSL blocks with no explicit receiver. Covers `do...end`, `{}`, and
+          # numbered (`_1`) / `it` block forms.
+          def enclosing_routing_sends(node)
+            node.each_ancestor(:block, :numblock, :itblock).filter_map do |b|
+              send = b.children.first
+              send if send.send_type? && send.receiver.nil?
+            end
+          end
+
+          # The value of an inline `on:` option (`:member` / `:collection` /
+          # `:new`) as a string, or nil when absent. `on:` is only ever used to
+          # attach a custom action to a resource.
+          def inline_on_context(node)
+            options = node.arguments.find(&:hash_type?)
+            return unless options
+
+            pair = options.pairs.find { |p| p.key.sym_type? && p.key.value == :on }
+            return unless pair
+
+            pair.value.sym_type? ? pair.value.value.to_s : 'member'
+          end
+
+          # Display name for the action: the leading symbol/string argument
+          # (`:activate`, `'weeks/:start_date'`), or `?` when it can't be read.
+          def action_name(node)
+            arg = node.first_argument
+            return '?' unless arg
+
+            case arg.type
+            when :sym then ":#{arg.value}"
+            when :str then "'#{arg.value}'"
+            else '?'
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+require 'active_support/inflector'
+
+module RuboCop
+  module Cop
+    module DevDoc
+      module Route
+        # Use a plural name for `resources` and a singular name for `resource`.
+        #
+        # ## Rationale
+        # Follow Rails' standard REST conventions. A plural `resources` maps to a
+        # collection (`/products`), so its name should be plural; a singular
+        # `resource` maps to a single implicit-id resource (`/profile`), so its
+        # name should be singular. Mismatched number reads against every Rails
+        # convention and produces awkward path/helper names.
+        #
+        #   ❌ resources :product   # => /product
+        #   ❌ resource  :sessions  # singular resource, plural name
+        #
+        #   ✔️ resources :products  # => /products
+        #   ✔️ resource  :session   # => /session
+        #
+        # The check uses ActiveSupport's inflector, so irregular and uncountable
+        # nouns are handled (`resources :people`, `resources :fish` are fine).
+        #
+        # ## Exception
+        # A project with custom inflections (`config/initializers/inflections.rb`)
+        # the bundled inflector doesn't know about may be misjudged. Disable the
+        # cop on that line with a reason.
+        #
+        # @example
+        #   # bad
+        #   resources :product
+        #   resource :sessions
+        #
+        #   # good
+        #   resources :products
+        #   resource :session
+        class ResourceNameNumber < Base
+          MSG = '`%<method>s` should name a %<number>s resource — use `:%<expected>s`.'.freeze
+
+          RESTRICT_ON_SEND = %i[resources resource].freeze
+
+          def on_send(node)
+            node.arguments.each do |arg|
+              name = name_of(arg)
+              next unless name
+
+              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)
+              )
+            end
+          end
+
+          private
+
+          # The resource name as a string, for symbol or string arguments only
+          # (skips the options hash, blocks, etc.).
+          def name_of(arg)
+            arg.value.to_s if arg.sym_type? || arg.str_type?
+          end
+
+          def expected_name(method, name)
+            method == :resources ? ActiveSupport::Inflector.pluralize(name) : ActiveSupport::Inflector.singularize(name)
+          end
+
+          def number_word(method)
+            method == :resources ? 'plural' : 'singular'
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -36,17 +36,28 @@ module RuboCop
         #   ✔️ Restricted — only methods with the prefix can be called
         #   obj.send("export_#{method_name}")
         #
+        # 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)
-        #   obj.send("export_#{x}")
+        #
+        #   # 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
+        #   # 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 dynamic `%<method>s` — use bracket notation for model attributes, " \
@@ -55,10 +66,26 @@ module RuboCop
 
           def on_send(node)
             return if node.receiver.nil?
-            return if node.first_argument&.sym_type?
+
+            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