rubocop-dev_doc 0.1.0 → 0.3.0

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

@@ -0,0 +1,345 @@
+require 'yaml'
+require 'fugit'
+
+module DevDoc
+  module Test
+    module Lints
+      # Framework-agnostic check: reads a sidekiq-cron-style `schedules.yml`
+      # and returns a list of offender descriptions for any cron expression
+      # that fires less often than `max_interval_seconds`, and optionally
+      # checks that each job's staleness threshold is greater than the cron
+      # interval.
+      #
+      # Wrapped by the Minitest module `CronSchedule` below — see that
+      # module for the rationale and examples. Tests cover the checker
+      # directly so they don't have to mock a test framework.
+      class CronScheduleChecker
+        # 1 day. Weekly (and longer) crons are always wrong: no staleness
+        # threshold can usefully exceed the cron interval, so a weekly cron
+        # can't be paired with a meaningful self-throttle. Daily cron is the
+        # most generous interval the pattern supports (works for
+        # weekly-desired refreshes like Myki). Hourly+ is always safe.
+        DEFAULT_MAX_INTERVAL_SECONDS = 86_400
+
+        # Sentinel returned by `#offenders` when the schedules file doesn't
+        # exist. Distinguishable from `[]` (file present, all good) so the
+        # Minitest wrapper can `skip` rather than `assert`.
+        MissingFile = Module.new
+
+        # Default constant name to look up in job source files when checking
+        # that the staleness threshold is larger than the cron interval.
+        DEFAULT_STALENESS_CONSTANT = 'STALENESS_THRESHOLD'.freeze
+
+        def initialize(schedules_path, max_interval_seconds: DEFAULT_MAX_INTERVAL_SECONDS)
+          @schedules_path = schedules_path
+          @max_interval_seconds = max_interval_seconds
+        end
+
+        # Returns an Array<String> of offender descriptions (one per
+        # invalid or too-infrequent cron), `[]` if all crons are
+        # compliant, or `MissingFile` if the schedules file doesn't
+        # exist.
+        def offenders
+          return MissingFile unless @schedules_path.exist?
+
+          # YAML.safe_load returns nil for an empty file.
+          (YAML.safe_load(@schedules_path.read) || {}).each_with_object([]) do |(name, opts), acc|
+            next unless opts.is_a?(Hash) && (cron = opts['cron'])
+
+            interval = interval_seconds_for(cron)
+            if interval == :invalid
+              acc << "  #{name}: invalid cron expression (cron: #{cron.inspect})"
+              next
+            end
+            next if interval.nil? || interval <= @max_interval_seconds
+
+            acc << "  #{name}: every #{self.class.format_seconds(interval)} (cron: #{cron.inspect})"
+          end
+        end
+
+        # Checks that each job's staleness threshold constant is strictly
+        # greater than the cron interval. Returns an Array<String> of
+        # offender descriptions, `[]` if all are compliant, or `MissingFile`
+        # if the schedules file doesn't exist.
+        #
+        # Parameters:
+        #   jobs_path   - Pathname/String pointing to `app/jobs/` (or any
+        #                 directory tree to search for job source files).
+        #                 If nil or the path doesn't exist, returns `[]`
+        #                 (nothing to check — silently skipped so projects
+        #                 without job-level constants don't have to opt out).
+        #   constant    - Name of the constant to look up (default:
+        #                 `STALENESS_THRESHOLD`). Projects that use a
+        #                 different convention (e.g. `STALE_AFTER`) can
+        #                 override this.
+        #
+        # The constant value is extracted by grepping the job source files for
+        # the pattern `CONSTANT = <number>.<unit>` (e.g. `1.hour`, `45.minutes`).
+        # Jobs that use a per-record stale? method instead of a job-level
+        # constant produce no constant to inspect and are skipped silently.
+        def staleness_offenders(jobs_path: nil, constant: DEFAULT_STALENESS_CONSTANT)
+          return MissingFile unless @schedules_path.exist?
+          return [] if jobs_path.nil?
+
+          jobs_root = Pathname.new(jobs_path)
+          return [] unless jobs_root.exist?
+
+          (YAML.safe_load(@schedules_path.read) || {}).each_with_object([]) do |(name, opts), acc|
+            next unless opts.is_a?(Hash) && (cron = opts['cron']) && (class_name = opts['class'])
+
+            interval = interval_seconds_for(cron)
+            next if interval == :invalid || interval.nil?
+
+            threshold = staleness_threshold_for(class_name, jobs_root, constant)
+            next if threshold.nil? # no constant found — skip silently
+
+            next if interval < threshold
+
+            acc << "  #{name} (#{class_name}): cron fires every " \
+                   "#{self.class.format_seconds(interval)} but #{constant} is " \
+                   "#{self.class.format_seconds(threshold)} — " \
+                   'cron interval must be strictly less than the staleness threshold'
+          end
+        end
+
+        def self.format_seconds(seconds)
+          return "#{seconds}s" if seconds < 60
+          return "#{seconds / 60}m" if seconds < 3600
+          return "#{seconds / 3600}h" if seconds < 86_400
+
+          "#{seconds / 86_400}d"
+        end
+
+        # Anchored reference for sampling cron fires. A fixed Monday so
+        # weekday-restricted crons behave the same regardless of when the
+        # test suite runs.
+        SAMPLE_ANCHOR = Time.utc(2025, 1, 6).freeze
+
+        # How many consecutive fires to sample. 100 covers:
+        #   - sub-hourly crons (max gap surfaces within minutes)
+        #   - business-hours patterns like `0 9-17 * * *` (overnight gap
+        #     visible after the first day)
+        #   - weekly/monthly (max gap visible within a few cycles)
+        #   - yearly (still gets ≥2 fires)
+        SAMPLE_COUNT = 100
+
+        private
+
+        # Computes the maximum interval (in seconds) between consecutive
+        # fires of a cron expression, sampled from a fixed anchor so the
+        # result is independent of `Time.now`. Returns `:invalid` if
+        # the expression doesn't parse, or nil if it parses but yields
+        # fewer than two fires.
+        def interval_seconds_for(cron_string)
+          cron = parse_in_utc(cron_string)
+          return :invalid unless cron
+
+          fires = []
+          t = SAMPLE_ANCHOR
+          SAMPLE_COUNT.times do
+            t = cron.next_time(t)
+            break if t.nil?
+
+            fires << t
+          end
+
+          return nil if fires.size < 2
+
+          fires.each_cons(2).map { |a, b| (b - a).to_i }.max
+        end
+
+        # We measure the cron's nominal interval, not its wall-clock
+        # interval in the server's local zone. A "daily" cron in a
+        # DST-observing zone really does have a 25h gap twice a year —
+        # but that's not what this lint is asking about. Parsing with
+        # UTC removes DST entirely; if the user already specified a
+        # zone, we honour it.
+        def parse_in_utc(cron_string)
+          Fugit::Cron.parse("#{cron_string} UTC") ||
+            Fugit::Cron.parse(cron_string)
+        end
+
+        # Locates the job source file for `class_name` under `jobs_root`
+        # and extracts the value of `constant` in seconds. Returns nil
+        # if the file or constant is not found, or if the value cannot be
+        # parsed as a simple ActiveSupport::Duration literal.
+        def staleness_threshold_for(class_name, jobs_root, constant)
+          source = job_source(class_name, jobs_root)
+          return nil unless source
+
+          parse_duration_constant(source, constant)
+        end
+
+        # Searches `jobs_root` recursively for a .rb file that defines
+        # `class_name`. Returns the file contents as a String, or nil.
+        def job_source(class_name, jobs_root)
+          # Build the conventional filename (e.g. MyFetchJob → my_fetch_job.rb)
+          # and also search by class name presence as a fallback.
+          expected_file = "#{class_name_to_file(class_name)}.rb"
+
+          # Fast path: try the conventional file name first.
+          Dir.glob(jobs_root.join('**', expected_file)).each do |path|
+            content = File.read(path)
+            return content if content.include?(class_name)
+          end
+
+          # Fallback: search all .rb files for a class definition matching
+          # the name. Useful for non-conventional file layouts.
+          Dir.glob(jobs_root.join('**', '*.rb')).each do |path|
+            content = File.read(path)
+            return content if content.include?("class #{class_name}")
+          end
+
+          nil
+        end
+
+        # Converts CamelCase class name to snake_case filename stem.
+        # E.g. WorkDiaryBackfillJob → work_diary_backfill_job
+        def class_name_to_file(class_name)
+          # Strip leading module namespaces (Foo::BarJob → BarJob)
+          base = class_name.split('::').last.to_s
+          base.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+              .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+              .downcase
+        end
+
+        # Extracts the numeric second value of a simple duration constant
+        # from source text. Handles `<n>.<unit>` ActiveSupport::Duration
+        # literals (e.g. `45.minutes`, `1.hour`, `7.days`).
+        # Returns an Integer number of seconds, or nil if not found/parseable.
+        DURATION_UNITS = {
+          'second' => 1,   'seconds'  => 1,
+          'minute' => 60,  'minutes'  => 60,
+          'hour' => 3600, 'hours' => 3600,
+          'day' => 86_400, 'days' => 86_400,
+          'week' => 604_800, 'weeks' => 604_800
+        }.freeze
+
+        def parse_duration_constant(source, constant)
+          units_pattern = DURATION_UNITS.keys.join('|')
+          pattern = /#{Regexp.escape(constant)}\s*=\s*(\d+(?:\.\d+)?)\.(#{units_pattern})\b/
+
+          match = source.match(pattern)
+          return nil unless match
+
+          value = match[1].to_f
+          unit  = match[2]
+          (value * DURATION_UNITS.fetch(unit)).to_i
+        end
+      end
+
+      # Reject cron schedules that fire less often than once per day
+      # (configurable). Anything weekly or longer is always wrong.
+      #
+      # ## Rationale
+      # Long-interval cron jobs fail catastrophically when missed.
+      # Sidekiq-cron does not replay missed occurrences — if the server is
+      # down at Mon 3am, the next fire is the following Mon 3am. A single
+      # server restart at the wrong moment costs a full interval of
+      # staleness. Same in production: transient Sidekiq issues, deploys,
+      # or scheduler glitches all cause the same outage.
+      #
+      # The recommended pattern is a frequent cron + persisted last-run
+      # timestamp ("self-throttled cron"). Cron fires often; the job
+      # itself decides whether to do the work based on a `fetched_at`-style
+      # column. Fresh? Fast no-op. Stale? Run the actual work. Missed runs
+      # self-heal within the cron interval.
+      #
+      # The cron interval must be strictly less than the job's desired
+      # refresh cadence (its staleness threshold). One missed cron fire
+      # then only adds ≤ 1 cron interval of staleness, never doubling the
+      # cadence.
+      #
+      #   Desired refresh | Right cron                | Wrong cron
+      #   ----------------+---------------------------+-----------
+      #   Weekly          | Daily (or shorter)        | Weekly
+      #   Daily           | Hourly (or shorter)       | Daily
+      #   Hourly          | Every 15 min (or shorter) | Hourly
+      #
+      # Weekly+ crons are always wrong, regardless of staleness threshold:
+      # no useful threshold can exceed the cron interval, so the
+      # self-throttle mechanism can't work. This lint enforces that.
+      # A second test (`test_staleness_threshold_aligned`) also verifies
+      # that each job's `STALENESS_THRESHOLD` constant (or a configurable
+      # name) is strictly greater than the cron interval — catching the
+      # "inverted pattern" where every cron fire does the work because the
+      # threshold is equal to or shorter than the interval.
+      #
+      #   ❌
+      #   myki_fetch:
+      #     cron: "0 3 * * 1"   # weekly — one miss = 7 days stale
+      #     class: MykiFetchJob
+      #
+      #   ✔️
+      #   myki_fetch:
+      #     cron: "0 3 * * *"   # daily; MykiAccount#stale?(7.days) gates work
+      #     class: MykiFetchJob
+      #
+      # See `best_practices/backend/en/08_job.md#cron-schedule-frequency`.
+      #
+      # ## Usage
+      # Include this module in a Minitest test class to get the
+      # `test_no_long_interval_cron` and `test_staleness_threshold_aligned`
+      # methods. To override the cap, redefine `MAX_INTERVAL_SECONDS` on the
+      # test class. To change the constant name searched in job files, redefine
+      # `STALENESS_CONSTANT_NAME`.
+      #
+      #   class CronScheduleTest < ActiveSupport::TestCase
+      #     include DevDoc::Test::Lints::CronSchedule
+      #     # MAX_INTERVAL_SECONDS = 3600  # tighten to 1h
+      #     # STALENESS_CONSTANT_NAME = 'STALE_AFTER'  # different convention
+      #   end
+      module CronSchedule
+        # Default cap. Per-project override: redefine the constant on the
+        # test class that includes this module.
+        MAX_INTERVAL_SECONDS = CronScheduleChecker::DEFAULT_MAX_INTERVAL_SECONDS
+
+        # Name of the constant to look up in job source files. Per-project
+        # override: redefine on the test class that includes this module.
+        STALENESS_CONSTANT_NAME = CronScheduleChecker::DEFAULT_STALENESS_CONSTANT
+
+        def test_no_long_interval_cron
+          max = self.class::MAX_INTERVAL_SECONDS
+          result = CronScheduleChecker
+                   .new(schedules_path, max_interval_seconds: max)
+                   .offenders
+
+          skip "no #{schedules_path} found" if result == CronScheduleChecker::MissingFile
+
+          assert result.empty?,
+                 "Cron schedules must be valid and fire at least every " \
+                 "#{CronScheduleChecker.format_seconds(max)}. Offenders:\n" \
+                 "#{result.join("\n")}\n\n" \
+                 "Use a frequent cron + a persisted staleness check in the job. " \
+                 'See https://github.com/hgani/dev-doc/blob/main/best_practices/backend/en/08_job.md#cron-schedule-frequency'
+        end
+
+        def test_staleness_threshold_aligned
+          constant = self.class::STALENESS_CONSTANT_NAME
+          result = CronScheduleChecker
+                   .new(schedules_path)
+                   .staleness_offenders(jobs_path: jobs_path, constant: constant)
+
+          skip "no #{schedules_path} found" if result == CronScheduleChecker::MissingFile
+
+          assert result.empty?,
+                 "Each job's #{constant} must be strictly greater than its cron " \
+                 "interval (otherwise every cron fire does the work and the " \
+                 "staleness check is useless). Offenders:\n" \
+                 "#{result.join("\n")}\n\n" \
+                 'See https://github.com/hgani/dev-doc/blob/main/best_practices/backend/en/08_job.md#cron-schedule-frequency'
+        end
+
+        private
+
+        def schedules_path
+          Rails.root.join('config/schedules.yml')
+        end
+
+        def jobs_path
+          Rails.root.join('app/jobs')
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,197 @@
+require 'digest'
+require 'pathname'
+
+module DevDoc
+  module Test
+    module Lints
+      # Framework-agnostic check: scans a directory of controller-test
+      # snapshot result dirs (`*_results/*.json`) and reports groups of
+      # byte-identical snapshots within the same dir.
+      #
+      # Wrapped by the Minitest module `DuplicateSnapshot` below — see that
+      # module for the rationale and inline opt-out format. Tests cover the
+      # checker directly so they don't have to mock a test framework.
+      class DuplicateSnapshotChecker
+        # Inline opt-out token. Append to the `test '...' do` line (or a
+        # comment line directly above) of EACH test in an intentionally
+        # duplicate group: `# allow_duplicate_snapshot: <reason>`.
+        MARKER = 'allow_duplicate_snapshot'.freeze
+
+        # Matches a minitest `test '...' do` declaration; captures the quote
+        # (1), the name (2), and the trailing content after `do` (3).
+        TEST_DEFINITION = /^\s*test\s+(["'])(.+?)\1\s+do\b(.*)$/
+
+        # Sentinel returned by `#offenders` when no `*_results` dirs exist,
+        # so the Minitest wrapper can `skip` rather than `assert`.
+        MissingDir = Module.new
+
+        # @param results_root [String, Pathname] dir that contains the
+        #   `*_results/` snapshot dirs (e.g. `test/controllers`).
+        def initialize(results_root)
+          @results_root = Pathname(results_root)
+        end
+
+        # Returns Array<String> of offender descriptions (one per duplicate
+        # group that has at least one un-marked member), `[]` if there are
+        # no unjustified duplicates, or `MissingDir` if there are no
+        # `*_results` dirs at all.
+        def offenders
+          dirs = Dir.glob(@results_root.join('*_results')).select { |d| File.directory?(d) }
+          return MissingDir if dirs.empty?
+
+          dirs.sort.flat_map { |dir| offenders_in(dir) }
+        end
+
+        private
+
+        def offenders_in(dir)
+          files = Dir.glob(File.join(dir, '*.json'))
+          return [] if files.size < 2
+
+          marked = marker_map_for(dir)
+          duplicate_groups(files)
+            .reject { |group| group.all? { |f| marked[File.basename(f, '.json')] } }
+            .map { |group| describe_group(dir, group, marked) }
+        end
+
+        # Groups of byte-identical snapshot files (size >= 2).
+        def duplicate_groups(files)
+          files.group_by { |f| Digest::MD5.hexdigest(File.read(f)) }
+               .values.select { |group| group.size >= 2 }
+        end
+
+        def describe_group(dir, group, marked)
+          rows = group.sort.map do |f|
+            meth = File.basename(f, '.json')
+            "      #{marked[meth] ? '[marked]   ' : '[UNMARKED] '}#{meth}"
+          end
+          "  #{File.basename(dir)}: #{group.size} identical snapshots —\n#{rows.join("\n")}"
+        end
+
+        # Maps each `test '...'` in the dir's sibling test file to whether
+        # it carries the inline opt-out marker. Key is the minitest method
+        # name (`test_` + name with whitespace → `_`), which is also the
+        # snapshot file's basename.
+        def marker_map_for(dir)
+          test_file = test_file_for(dir)
+          return {} unless test_file.exist?
+
+          lines = test_file.readlines
+          (0...lines.size).each_with_object({}) do |i, map|
+            m = lines[i].match(TEST_DEFINITION)
+            next unless m
+
+            map["test_#{m[2].gsub(/\s+/, '_')}"] = marked?(m[3], lines, i)
+          end
+        end
+
+        # A test is marked if the opt-out token appears on its `do` line's
+        # trailing comment, or on the comment line directly above it.
+        def marked?(trailing, lines, index)
+          context = trailing.to_s + (index.positive? ? lines[index - 1] : '')
+          context.include?(MARKER)
+        end
+
+        # Resolve the test file for a `*_results` dir. Usually it's the
+        # same-named sibling (`foo_controller_test_results` →
+        # `foo_controller_test.rb`). But the results dir is written by the test
+        # framework under `test/controllers/` regardless of where the test file
+        # lives — a job/integration test, or a class whose file is named
+        # differently, lands its snapshots here too. When the same-named file is
+        # absent, fall back to locating the class by name anywhere under `test/`,
+        # so the inline marker is always reachable.
+        def test_file_for(dir)
+          base = File.basename(dir).sub(/_results\z/, '')
+          direct = Pathname(File.join(File.dirname(dir), "#{base}.rb"))
+          return direct if direct.exist?
+
+          find_file_defining(camelize(base)) || direct
+        end
+
+        # First test file under the test root that defines the given class.
+        def find_file_defining(class_name)
+          pattern = /^\s*class\s+#{Regexp.escape(class_name)}\b/
+          match = Dir.glob(@results_root.parent.join('**', '*.rb')).find do |f|
+            File.foreach(f).any? { |line| line.match?(pattern) }
+          end
+          Pathname(match) if match
+        end
+
+        def camelize(snake)
+          snake.split('_').map(&:capitalize).join
+        end
+      end
+
+      # Reject byte-identical controller-test snapshots within the same
+      # `*_results` dir.
+      #
+      # ## Rationale
+      # "Test quality" is normally subjective. Two tests serializing the
+      # *exact same* rendered response is an objective, computable proxy for
+      # a redundant or weak test. When `response_assert_equal` snapshots
+      # collide, it's almost always one of:
+      #
+      #   1. **Same scenario tested twice** — should be one test with the
+      #      combined assertions.
+      #   2. **Fixtures don't exercise the difference** — the test claims to
+      #      verify behaviour X, but the inputs all collapse to the same
+      #      rendered state, so it passes without actually testing X. (The
+      #      most dangerous case — green but vacuous.)
+      #   3. **A negative/absence assertion** — a test for "X is NOT shown"
+      #      legitimately renders identically to the baseline. This is the
+      #      one *correct* duplicate; acknowledge it with the inline marker.
+      #
+      # Aggressive by design: a false positive costs only a quick review and
+      # one inline comment, while a silent duplicate hides a real (1) or (2).
+      #
+      # ## Inline opt-out (NOT a central allow-list)
+      # The justification lives next to the test, so it can't rot or detach.
+      # Mark EACH test in an intentionally-duplicate group with
+      # `# allow_duplicate_snapshot: <reason>` — either as a trailing comment on
+      # its `test '...' do` line, or on the comment line directly above it (use
+      # the latter when the test line is already long):
+      #
+      #   test 'index hides the banner' do # allow_duplicate_snapshot: renders like the baseline
+      #     ...
+      #   end
+      #
+      #   # allow_duplicate_snapshot: renders like the baseline
+      #   test 'index hides the banner for a guest who is not in any of the groups' do
+      #     ...
+      #   end
+      #
+      # ## Usage
+      #   class DuplicateSnapshotTest < ActiveSupport::TestCase
+      #     include DevDoc::Test::Lints::DuplicateSnapshot
+      #     # SNAPSHOT_RESULTS_ROOT = 'test/requests'  # override if needed
+      #   end
+      module DuplicateSnapshot
+        def test_no_unjustified_duplicate_snapshots
+          result = DuplicateSnapshotChecker.new(snapshot_results_root).offenders
+          if result == DuplicateSnapshotChecker::MissingDir
+            skip "no snapshot result dirs under #{snapshot_results_root}"
+          end
+
+          assert result.empty?, failure_message(result)
+        end
+
+        private
+
+        def failure_message(result)
+          "Found byte-identical controller-test snapshots. Identical output usually means a " \
+            "redundant or weak test: the same scenario tested twice (merge them), or fixtures that " \
+            "don't actually exercise the difference (strengthen the test). De-duplicate, or — if the " \
+            "duplication is intentional (e.g. a negative/absence assertion that correctly renders like " \
+            "the baseline) — mark EACH test in the group with `# #{DuplicateSnapshotChecker::MARKER}: " \
+            "<reason>`, as a trailing comment on its `test '...' do` line or on the line directly " \
+            "above it.\n\nOffending groups:\n#{result.join("\n")}"
+        end
+
+        def snapshot_results_root
+          root = defined?(self.class::SNAPSHOT_RESULTS_ROOT) ? self.class::SNAPSHOT_RESULTS_ROOT : 'test/controllers'
+          Rails.root.join(root)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,128 @@
+require 'yaml'
+
+module DevDoc
+  module Test
+    module Lints
+      # Framework-agnostic check: reads a `.rubocop.yml`, walks every
+      # `Exclude:` list under each top-level section, and returns offender
+      # descriptions for entries that are literal file paths (no glob
+      # characters) outside the configured allowlist.
+      #
+      # Wrapped by the Minitest module `NoFileExcludes` below — see that
+      # module for the rationale.
+      class NoFileExcludesChecker
+        # File paths universally exempt because they're auto-generated and
+        # nobody reads them like source code. Consumer projects can extend
+        # this via the per-project override on the `NoFileExcludes` module.
+        DEFAULT_ALLOWED_FILES = %w[db/schema.rb].freeze
+
+        GLOB_CHARACTERS = /[*?\[\]{}]/.freeze
+
+        # Sentinel returned by `#offenders` when the `.rubocop.yml` doesn't
+        # exist. Distinguishable from `[]` (file present, all good) so the
+        # Minitest wrapper can `skip` rather than `assert`.
+        MissingFile = Module.new
+
+        def initialize(rubocop_yml_path, allowed_files: DEFAULT_ALLOWED_FILES)
+          @rubocop_yml_path = rubocop_yml_path
+          @allowed_files = allowed_files.to_set
+        end
+
+        # Returns an Array<String> of offender descriptions (one per
+        # literal-path entry in any `Exclude:` list), `[]` if all entries
+        # are globs or allowlisted, or `MissingFile` if the `.rubocop.yml`
+        # doesn't exist.
+        def offenders
+          return MissingFile unless @rubocop_yml_path.exist?
+
+          # 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)
+
+            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}"
+            end
+          end
+        end
+      end
+
+      # Reject literal-file entries in any `Exclude:` list under
+      # `.rubocop.yml`.
+      #
+      # ## Rationale
+      # A literal-path `Exclude:` makes the suppression invisible to anyone
+      # reading the excluded file. They see the violating code, see no
+      # `# rubocop:disable` annotation near it, and reasonably conclude the
+      # 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
+      # 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
+      # describes, so a future reader sees it without having to cross-check
+      # `.rubocop.yml`.
+      #
+      # Globs (`vendor/**/*`, `db/migrate/**/*.rb`, `bin/*`) remain fine
+      # because they target a category, not a file someone might be reading.
+      #
+      #   ❌ Hides the suppression from readers of the file
+      #
+      #   DevDoc/Migration/AvoidColumnDefault:
+      #     Exclude:
+      #       - "db/migrate/20260505035728_create_pr_reviews.rb"
+      #
+      #   ✔ 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
+      #
+      #   ✔ Glob — still acceptable, targets a category not a specific file
+      #
+      #   AllCops:
+      #     Exclude:
+      #       - "vendor/**/*"
+      #
+      # ## Usage
+      # Include this module in a Minitest test class. To allowlist additional
+      # auto-generated literal paths (e.g. a project-specific generated file),
+      # redefine `ALLOWED_FILE_EXCLUDES` on the test class.
+      #
+      #   class RubocopConfigTest < ActiveSupport::TestCase
+      #     include DevDoc::Test::Lints::NoFileExcludes
+      #     # ALLOWED_FILE_EXCLUDES = %w[db/schema.rb Gemfile.lock].freeze
+      #   end
+      module NoFileExcludes
+        # Default allowlist. Per-project override: redefine the constant on
+        # the test class that includes this module.
+        ALLOWED_FILE_EXCLUDES = NoFileExcludesChecker::DEFAULT_ALLOWED_FILES
+
+        def test_no_file_excludes_in_rubocop_yml
+          result = NoFileExcludesChecker
+                   .new(rubocop_yml_path, allowed_files: self.class::ALLOWED_FILE_EXCLUDES)
+                   .offenders
+
+          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")}"
+        end
+
+        private
+          def rubocop_yml_path
+            Rails.root.join('.rubocop.yml')
+          end
+      end
+    end
+  end
+end