rubocop-dev_doc 0.10.4 → 0.12.0

data/lib/dev_doc/test/lints/no_file_excludes.rb

@@ -16,7 +16,7 @@ module DevDoc
         # this via the per-project override on the `NoFileExcludes` module.
         DEFAULT_ALLOWED_FILES = %w[db/schema.rb].freeze
 
-        GLOB_CHARACTERS = /[*?\[\]{}]/.freeze
+        GLOB_CHARACTERS = /[*?\[\]{}]/
 
         # Sentinel returned by `#offenders` when the `.rubocop.yml` doesn't
         # exist. Distinguishable from `[]` (file present, all good) so the
@@ -37,18 +37,24 @@ module DevDoc
 
           # YAML.safe_load returns nil for an empty file. Rubocop config
           # is a flat top-level hash; `Exclude:` keys live one level down.
-          (YAML.safe_load(@rubocop_yml_path.read) || {}).each_with_object([]) do |(section, value), acc|
-            next unless value.is_a?(Hash)
+          (YAML.safe_load(@rubocop_yml_path.read) || {}).flat_map do |section, value|
+            next [] unless value.is_a?(Hash)
 
-            Array(value['Exclude']).each do |entry|
-              next unless entry.is_a?(String)
-              next if entry.match?(GLOB_CHARACTERS)
-              next if @allowed_files.include?(entry)
-
-              acc << "  #{section}: Exclude includes literal file #{entry.inspect}"
+            literal_excludes(value).map do |entry|
+              "  #{section}: Exclude includes literal file #{entry.inspect}"
             end
           end
         end
+
+        private
+
+        # Literal-path (non-glob, non-allowlisted) entries of one section's
+        # `Exclude:` list.
+        def literal_excludes(section_config)
+          Array(section_config['Exclude']).select do |entry|
+            entry.is_a?(String) && !entry.match?(GLOB_CHARACTERS) && !@allowed_files.include?(entry)
+          end
+        end
       end
 
       # Reject literal-file entries in any `Exclude:` list under
@@ -61,7 +67,7 @@ module DevDoc
       # pattern is acceptable for new code in the same file. That sets the
       # wrong expectation and lets violations multiply.
       #
-      # Inline `# rubocop:disable Cop/Name` at the violation line(s) keeps
+      # An inline `rubocop:disable Cop/Name` directive at the violation line(s) keeps
       # the suppression visible to anyone reading the code AND scopes it to
       # the specific lines — a fresh violation in the same file still gets
       # flagged. The rationale for the suppression lives next to the code it
@@ -80,7 +86,8 @@ module DevDoc
       #   ✔ Visible inline, scoped to the specific line(s)
       #
       #   # db/migrate/20260505035728_create_pr_reviews.rb
-      #   t.jsonb :diff_files, default: [] # rubocop:disable DevDoc/Migration/AvoidColumnDefault
+      #   # rubocop:disable DevDoc/Migration/AvoidColumnDefault -- <reason>
+      #   t.jsonb :diff_files, default: []
       #
       #   ✔ Glob — still acceptable, targets a category not a specific file
       #
@@ -109,19 +116,23 @@ module DevDoc
 
           skip "no #{rubocop_yml_path} found" if result == NoFileExcludesChecker::MissingFile
 
-          assert result.empty?,
-                 "`.rubocop.yml` Exclude lists must contain only globs " \
-                 "(category patterns), not literal file paths. A literal-path " \
-                 "exclude hides the suppression from readers of the file. " \
-                 "Use `# rubocop:disable Cop/Name` at the violation line(s) " \
-                 "instead — visible to readers, scoped to the specific lines.\n\n" \
-                 "Offenders:\n#{result.join("\n")}"
+          assert result.empty?, no_file_excludes_message(result)
         end
 
         private
-          def rubocop_yml_path
-            Rails.root.join('.rubocop.yml')
-          end
+
+        def rubocop_yml_path
+          Rails.root.join('.rubocop.yml')
+        end
+
+        def no_file_excludes_message(offenders)
+          "`.rubocop.yml` Exclude lists must contain only globs " \
+            "(category patterns), not literal file paths. A literal-path " \
+            "exclude hides the suppression from readers of the file. " \
+            "Use `# rubocop:disable Cop/Name` at the violation line(s) " \
+            "instead — visible to readers, scoped to the specific lines.\n\n" \
+            "Offenders:\n#{offenders.join("\n")}"
+        end
       end
     end
   end

data/lib/dev_doc/test/pseudo_i18n_crawler.rb

@@ -1,5 +1,3 @@
-require 'set'
-
 module DevDoc
   module Test
     # Pseudo-localization hardcoded-text crawler.
@@ -96,20 +94,11 @@ module DevDoc
 
         # Prepend the Scanner onto the crawler HTTP client exactly once, no
         # matter how many test classes include the module.
-        unless Glib::JsonCrawler::Http.ancestors.include?(Scanner)
-          Glib::JsonCrawler::Http.prepend(Scanner)
-        end
+        Glib::JsonCrawler::Http.prepend(Scanner) unless Glib::JsonCrawler::Http.ancestors.include?(Scanner)
 
         base.setup do
-          skip 'Set PSEUDO_I18N=1 to run the pseudo-localization scan.' unless ENV['PSEUDO_I18N'] == '1'
-          skip 'en-PSEUDO locale not loaded — is config/initializers/pseudo_locale.rb active?' unless ::I18n.available_locales.include?(:'en-PSEUDO')
-
-          self.class.hits = {}
-          @previous_default_locale = ::I18n.default_locale
-          # The app's set_locale falls back to I18n.default_locale when no
-          # `_lang` param is present (crawler URLs carry none), so this renders
-          # every page in pseudo without touching the crawler's URLs.
-          ::I18n.default_locale = :'en-PSEUDO'
+          skip_unless_pseudo_enabled!
+          enter_pseudo_locale
         end
 
         base.teardown do
@@ -117,6 +106,7 @@ module DevDoc
         end
       end
 
+      # Per-run accumulator surface for the including test class.
       module ClassMethods
         attr_accessor :hits # { url => [ "[key] value", ... ] }
 
@@ -130,31 +120,44 @@ module DevDoc
           @report_dir ||= ::Rails.root.join('test/integration/pseudo_i18n_crawler_test_results').to_s
         end
 
+        def parse_json(body)
+          JSON.parse(body)
+        rescue JSON::ParserError
+          nil
+        end
+
         def scan_body(url, body)
           return unless body.is_a?(String) && body.lstrip.start_with?('{', '[')
 
-          json = begin
-            JSON.parse(body)
-          rescue JSON::ParserError
-            return
-          end
+          json = parse_json(body)
+          return unless json
 
-          walk(json) do |key, value|
-            if value.include?(MARKER)
-              @wrapped = (@wrapped || 0) + 1
-            elsif trivial?(value)
-              next
-            elsif fixture_strings.include?(value.strip)
-              # ActiveRecord display value (record title/name/user copy) that
-              # came straight from the DB — data, not a hardcoded UI string.
-              @data_sourced = (@data_sourced || 0) + 1
-            else
-              @unwrapped = (@unwrapped || 0) + 1
-              (hits[url] ||= []) << "[#{key}] #{value.inspect}"
-            end
+          walk(json) { |key, value| tally(url, key, value) }
+        end
+
+        # Buckets one text-prop value: wrapped (went through t()), trivial
+        # (not copy), data-sourced (verbatim fixture string), or a hardcoded
+        # candidate recorded in `hits`.
+        def tally(url, key, value)
+          if value.include?(MARKER)
+            counters[:wrapped] += 1
+          elsif trivial?(value)
+            nil
+          elsif fixture_strings.include?(value.strip)
+            # ActiveRecord display value (record title/name/user copy) that
+            # came straight from the DB — data, not a hardcoded UI string.
+            counters[:data_sourced] += 1
+          else
+            counters[:unwrapped] += 1
+            (hits[url] ||= []) << "[#{key}] #{value.inspect}"
           end
         end
 
+        # Per-run bucket counts for the DIAG line.
+        def counters
+          @counters ||= Hash.new(0)
+        end
+
         # Verbatim string values from the fixtures. A candidate equal to one of
         # these is an ActiveRecord display value (loaded from the DB, so it
         # never went through t() by design) rather than hardcoded copy, and is
@@ -164,7 +167,7 @@ module DevDoc
         # fixtures contain no ERB so static YAML parsing is exact.
         def fixture_strings
           @fixture_strings ||= Dir[File.join(fixture_dir, '**', '*.yml')].each_with_object(Set.new) do |file, set|
-            data = YAML.safe_load(File.read(file), permitted_classes: [Date, Time], aliases: true)
+            data = YAML.safe_load_file(file, permitted_classes: [Date, Time], aliases: true)
             collect_strings(data, set)
           rescue Psych::Exception
             next
@@ -178,12 +181,15 @@ module DevDoc
           when String
             s = node.strip
             set << s unless s.empty?
+          else
+            # Non-string scalars (numbers, booleans, nil, dates) carry no copy.
           end
         end
 
         def diag
-          "wrapped(localized via t)=#{@wrapped || 0}  data-sourced(fixtures, skipped)=#{@data_sourced || 0}  " \
-            "unwrapped(candidates)=#{@unwrapped || 0}"
+          "wrapped(localized via t)=#{counters[:wrapped]}  " \
+            "data-sourced(fixtures, skipped)=#{counters[:data_sourced]}  " \
+            "unwrapped(candidates)=#{counters[:unwrapped]}"
         end
 
         def walk(node, &blk)
@@ -195,6 +201,9 @@ module DevDoc
             end
           when Array
             node.each { |v| walk(v, &blk) }
+          else
+            # Scalars have no children to walk; string values are handed to
+            # the block by their parent hash above.
           end
         end
 
@@ -208,47 +217,74 @@ module DevDoc
 
       private
 
+      def skip_unless_pseudo_enabled!
+        skip 'Set PSEUDO_I18N=1 to run the pseudo-localization scan.' unless ENV['PSEUDO_I18N'] == '1'
+        return if ::I18n.available_locales.include?(:'en-PSEUDO')
+
+        skip 'en-PSEUDO locale not loaded — is config/initializers/pseudo_locale.rb active?'
+      end
+
+      def enter_pseudo_locale
+        self.class.hits = {}
+        self.class.counters.clear
+        @previous_default_locale = ::I18n.default_locale
+        # The app's set_locale falls back to I18n.default_locale when no
+        # `_lang` param is present (crawler URLs carry none), so this renders
+        # every page in pseudo without touching the crawler's URLs.
+        ::I18n.default_locale = :'en-PSEUDO'
+      end
+
       def crawl_pseudo(user)
         user[:token] = login(user)
 
-        router = Glib::JsonCrawler::Router.new
-        http   = Glib::JsonCrawler::Http.new(self, user, router, inspect_result: true)
-        router.host = HOST
-        router.skip_similar_page = true
-
         ENV['CRAWLER_MODE'] = 'true'
-        router.step(
-          http,
-          'onClick' => {
-            'action' => 'initiate_navigation',
-            'url' => "http://#{HOST}/users/me?format=json&redirect=default"
-          }
-        )
+        start_crawl(user)
       ensure
         ENV['CRAWLER_MODE'] = nil
         logout
         report!(user)
       end
 
+      # Enters the crawl at the logged-in user's landing page; the Router
+      # walks every reachable page from there.
+      def start_crawl(user)
+        router = Glib::JsonCrawler::Router.new
+        http   = Glib::JsonCrawler::Http.new(self, user, router, inspect_result: true)
+        router.host = HOST
+        router.skip_similar_page = true
+
+        entry = { 'action' => 'initiate_navigation',
+                  'url' => "http://#{HOST}/users/me?format=json&redirect=default" }
+        router.step(http, 'onClick' => entry)
+      end
+
       def report!(user)
         hits = self.class.hits
-        report_dir = self.class.report_dir
-        FileUtils.mkdir_p(report_dir)
-        path = File.join(report_dir, "#{user[:email]}.txt")
-
-        lines = []
-        hits.sort.each do |url, values|
-          lines << url
-          values.uniq.each { |v| lines << "    #{v}" }
-          lines << ''
-        end
-        total = hits.values.sum { |v| v.uniq.size }
-        summary = "#{total} hardcoded candidate(s) across #{hits.size} page(s) for #{user[:email]}"
+        summary = report_summary(hits, user)
+        path = write_report(summary, hits, user)
 
-        File.write(path, ([summary, ''] + lines).join("\n"))
         puts "\n[pseudo_i18n] #{summary}\n              report: #{path}"
         puts "[pseudo_i18n] DIAG: #{self.class.diag}"
       end
+
+      # Writes the per-role report file and returns its path.
+      def write_report(summary, hits, user)
+        FileUtils.mkdir_p(self.class.report_dir)
+        path = File.join(self.class.report_dir, "#{user[:email]}.txt")
+        File.write(path, ([summary, ''] + report_lines(hits)).join("\n"))
+        path
+      end
+
+      def report_summary(hits, user)
+        total = hits.values.sum { |v| v.uniq.size }
+        "#{total} hardcoded candidate(s) across #{hits.size} page(s) for #{user[:email]}"
+      end
+
+      def report_lines(hits)
+        hits.sort.flat_map do |url, values|
+          [url] + values.uniq.map { |v| "    #{v}" } + ['']
+        end
+      end
     end
   end
 end

data/lib/rubocop/cop/dev_doc/auth/current_user_branching.rb

@@ -1,3 +1,5 @@
+require_relative "current_user_branching_helpers"
+
 module RuboCop
   module Cop
     module DevDoc
@@ -43,16 +45,63 @@ module RuboCop
         # ## Patterns flagged
         # - `if current_user` / `unless current_user` (block or modifier) where
         #   the body is non-empty and is not a bare `return` (bare returns are
-        #   the nil-guard pattern covered by LoadResourceCurrentUserGuard).
+        #   the nil-guard pattern covered by LoadResourceCurrentUserGuard; the
+        #   exemption covers every nil-test spelling of the guard —
+        #   `return if current_user.nil?`, `return unless
+        #   current_user.present?`, `return if !current_user`).
         # - `if user_signed_in?` / `unless user_signed_in?` (any form).
-        # - `if current_user&.foo` and other safe-nav uses of `current_user`
-        #   as a condition. The `&.` is itself a confession that the dev
-        #   expects `current_user` to be nil sometimes — i.e., it's the same
-        #   anti-pattern as `if current_user`, just in disguise: when
-        #   `current_user` is nil the csend returns nil → branch is dead for
-        #   anonymous visitors, exactly what the cop prevents.
+        # - The evasion spellings — all equivalent to the bare form and all
+        #   measured in the wild once the bare form was policed:
+        #   `current_user.present?` / `.blank?` / `.nil?`, `!current_user`,
+        #   `!user_signed_in?`, and boolean combinations
+        #   (`current_user && x`, `user_signed_in? || y`).
+        # - ANY method chain rooted at `current_user` used as a condition —
+        #   both `current_user&.admin?` and plain `current_user.admin?`. The
+        #   `&.` is a confession that the dev expects nil; the plain chain is
+        #   a role/ownership check that belongs in the policy (see below).
         # - Ternaries: `current_user ? a : b`, `user_signed_in? ? a : b`.
         # - Hash/argument values: `authenticated: user_signed_in?`.
+        # - ALIASES: a local/instance variable assigned from `current_user`
+        #   in the same file inherits every rule above — `@user =
+        #   current_user` followed by `if @user.admin?` is the same branch
+        #   laundered, and it flags identically. Only PURE aliases are
+        #   tracked: every assignment to the name must be an unconditional
+        #   `= current_user` (case dispatch counts as unconditional). A
+        #   conditional assignment or a second source makes the variable a
+        #   genuinely nilable/general resource holder — branching on it is
+        #   resource-presence logic, not auth state. Taint is per-file only:
+        #   an ivar assigned in the controller and read in a view is not
+        #   tracked — pair this cop with the receiver-agnostic
+        #   `DevDoc/Auth/RolePredicateOutsidePolicy`, which closes that gap
+        #   for the known role predicates.
+        #
+        # ## AllowedMethods — classifying data reads
+        # The first method called on `current_user` (or a tainted alias) in a
+        # condition is CLASSIFIED: entries in `AllowedMethods` are data reads
+        # (`current_user.errors.any?`, an MFA-configured flag) and pass;
+        # everything else — role predicates and methods nobody has classified
+        # yet — flags. The list is a closed set on purpose: every new reader
+        # used in a condition forces a reviewed "data or permission?" decision
+        # in `.rubocop.yml` rather than slipping through. The
+        # universally-generic baseline (errors, id, email, persisted?,
+        # new_record? — `DEFAULT_ALLOWED_METHODS`) is built into the cop and
+        # cannot be un-configured; the yml list is purely ADDITIVE, so
+        # projects list only their own readers:
+        #
+        #   DevDoc/Auth/CurrentUserBranching:
+        #     AllowedMethods:
+        #       - otp_required_for_login
+        #
+        # ## Moving a decision to the policy — query by PURPOSE
+        # The policy move is only complete when the policy owns the
+        # role->behavior rule, not just the role's spelling. Export a
+        # decision-shaped query (`auto_approve?`, `initiation_blocked_for_admin?`,
+        # or an `authorize` block) and call THAT from page code. A generic role
+        # getter (`def user_is_admin? = current_user&.admin?`) re-opens the
+        # scattering: every call site invents its own rule again, one policy
+        # door down. If your policies must expose such getters as internal
+        # building blocks, list their names in the companion cop's
+        # RolePredicates so page code cannot call them.
         #
         # ## Allowed paths (Exclude:)
         # By default the cop is silent in:
@@ -139,9 +188,21 @@ module RuboCop
         #     ...
         #   end
         class CurrentUserBranching < Base
-          MSG = 'Avoid branching on auth state in page code. ' \
-                'If this page serves both anonymous and signed-in users, ' \
-                'add an inline disable with a reason.'.freeze
+          include CurrentUserBranchingHelpers
+
+          MSG = 'Branching on auth state in page code — decide what this branch really is: ' \
+                'auth is required here -> the anonymous branch is dead code, delete it; ' \
+                'a role/ownership check -> move the DECISION into the Pundit policy and ' \
+                'query it by purpose (`policy(record).auto_approve?`, `can?(:update, x)`) ' \
+                '— do NOT export a generic role getter (`user_is_admin?`) from the policy: ' \
+                'that centralizes only the spelling while every call site keeps its own ' \
+                'role->behavior rule; a plain data read (not permission-related) -> ' \
+                'classify the method in AllowedMethods; genuinely dual-state -> move the ' \
+                'branching to a layout/helper (excluded paths — PRESENTATION branching ' \
+                'only, keyed on entity-scoped facts, never smuggled permission logic) or ' \
+                'split anonymous/signed-in partials. Aliasing (`user = current_user`) ' \
+                'does not exempt any of this. Only a small, local branch on a genuinely ' \
+                'dual-state PAGE warrants an inline disable with a reason.'.freeze
 
           AUTH_METHODS = %i[current_user user_signed_in?].freeze
 
@@ -152,9 +213,17 @@ module RuboCop
             add_offense(if_offense_location(node))
           end
 
-          # `value: user_signed_in?` — condition passed as a value.
+          # `value: user_signed_in?` — the BOOLEAN auth state passed as data,
+          # which smuggles the branch to the consumer/client. Deliberately
+          # limited to `user_signed_in?`: bare `current_user` passed as data
+          # (`requested_by: current_user`, `model: current_user`,
+          # `x.user == current_user`) is actorship recording or identity
+          # comparison, not branching — flagging it measured 44 noise
+          # offenses / 0 finds on a mature codebase.
+          VALUE_FLAGGED_METHODS = %i[user_signed_in?].freeze
+
           def on_send(node)
-            return unless auth_method_call?(node)
+            return unless VALUE_FLAGGED_METHODS.include?(node.method_name) && node.receiver.nil?
             return unless used_as_value?(node)
 
             add_offense(node.loc.selector)
@@ -166,46 +235,6 @@ module RuboCop
             node.if_type? && auth_condition?(node.condition)
           end
 
-          def auth_condition?(condition)
-            return false unless condition
-
-            if condition.send_type?
-              AUTH_METHODS.include?(condition.method_name) && condition.receiver.nil?
-            elsif condition.csend_type?
-              # `current_user&.foo` — the safe-nav is itself the auth check;
-              # `bare_current_user_condition?` won't match (it requires send),
-              # so guard-return forms like `return unless current_user&.admin?`
-              # correctly stay flagged.
-              receiver = condition.receiver
-              receiver&.send_type? &&
-                receiver.method_name == :current_user &&
-                receiver.receiver.nil?
-            else
-              false
-            end
-          end
-
-          # `return unless current_user` (and similar bare guards) should not
-          # be flagged — they are the correct pattern handled by
-          # LoadResourceCurrentUserGuard. Detect: an if whose condition is bare
-          # `current_user` and one branch is a bare `return` (no arguments).
-          def bare_return_guard?(node)
-            condition = node.condition
-            return false unless bare_current_user_condition?(condition)
-
-            bare_return_branch?(node.else_branch) || bare_return_branch?(node.if_branch)
-          end
-
-          def bare_current_user_condition?(condition)
-            condition&.send_type? &&
-              condition.method_name == :current_user &&
-              condition.receiver.nil?
-          end
-
-          def bare_return_branch?(branch)
-            branch&.return_type? && branch.children.empty?
-          end
-
           # `if`/`unless` keyword forms have `loc.keyword`; ternary `?:` nodes
           # have `loc.question` instead. Fall back to the condition source range.
           def if_offense_location(node)
@@ -219,12 +248,6 @@ module RuboCop
             end
           end
 
-          # Is this send node an auth method call (`current_user`, `user_signed_in?`)
-          # on no receiver?
-          def auth_method_call?(node)
-            AUTH_METHODS.include?(node.method_name) && node.receiver.nil?
-          end
-
           # Is the send node used as a value (argument to another send, pair
           # value in a hash, etc.) rather than already caught as a branch condition?
           def used_as_value?(node)