rubocop-dev_doc 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83da1f7ff50b778721408a7f3713a0708a4749bf0af5e5df9e96810aa7f2be1c
-  data.tar.gz: 6b69c63a8bd53bd6a012acaa46ae7134581dbf2760f5e7627948dcd8b137558f
+  metadata.gz: 51389b117ef5ff9744ada6455ee819b98b221eb789eef110531097ed54a3c7b3
+  data.tar.gz: fbd6bddccbe8b3edcea38a20f901536c6297ae664277d54ae7b35a7b2bccdf88
 SHA512:
-  metadata.gz: 8b79ae456b8c5518023e9b89ba0232dfeb9fc64cb9a53d2e3e0ac18854a2d8b6f96b02e5a2ff3fd0928c19a32e9f5ae5204e3a5c3aa24af566dea1d8c7b24186
-  data.tar.gz: 7ffae58fc78c00ca6abdfab21e3c4517528183c3130e765b2aac198a44b91c2e8b2c9969fc9c3e7bd7c42243d78406f659ea4be94575df28fde2753bb4f22dfa
+  metadata.gz: cad293d67ee400ef543df57dc721baa74d784df7fbcdf2536ef6e6f7475732f8fb6cb8b80a924ff1a210d5bd5ec9cd60eec12a06f2b04b0a1827bab38899fc01
+  data.tar.gz: df1facc84e226e99d256ce256063011c6aeed3d491a7e417c9b2eff7555c1aa7730e46e005a58234e826cb8b87221e1b26b60b0ddeb27515bb7d0b3f129be615

data/config/default.yml

@@ -325,6 +325,10 @@ DevDoc/Style/StringSymbolComparison:
   Description: "Comparing a known-string source (params, request.headers, ENV) to a symbol literal is always false."
   Enabled: true
 
+DevDoc/Style/AvoidSymbolizingBoundaryInput:
+  Description: "Unvalidated `.to_sym` on params/request.headers lets any client value into the symbol domain; allow-list it (glib_allowlist_symbol_param) instead."
+  Enabled: true
+
 DevDoc/Style/LiteralOrInWhenClause:
   Description: "`||`/`&&` between literals in a `when` clause folds to one value — the other literal silently never matches; use comma-separated alternatives."
   Enabled: true
@@ -521,6 +525,30 @@ DevDoc/Test/AvoidUnitTest:
     - "test/**/*.rb"
     - "spec/**/*.rb"
 
+# Closes the fig-leaf hole in the anti-evasion pack: the runtime HTTP lint
+# proves a request was ISSUED, not that the assertions observe it. The base
+# class is an honesty declaration — under the integration base, ALL unit-test
+# idioms flag: controller internals (@controller/assigns/ivar reflection),
+# app-layer instantiation (*Service/*Policy/... — used to compute an expected
+# value it is a CIRCULAR assertion), direct mailer invocation, production
+# helper includes, and mock/stub machinery. Deliberately NOT flagged: model
+# reads (the DB is an outbound edge of the boundary; fixture lookup is setup)
+# and job invocation (jobs are the inbound edge for cron flows). Born from a
+# live 2026-07 evasion by a guard-aware agent (@controller.policy(...) behind
+# a fig-leaf GET); structure transfers between agents and machines, memory
+# doesn't. Honest unit tests declare themselves: Glib::LastResortUnitTest.
+DevDoc/Test/NoUnitIdiomsInIntegrationTests:
+  Description: "Integration tests are boundary tests: one entry point (request/job), assert only observable outputs (status, body, DB, mails). Unit-test idioms belong under Glib::LastResortUnitTest."
+  Enabled: true
+  # ADDITIVE to the cop's built-in baseline (Service, Policy, Form, Presenter,
+  # Serializer, Decorator — DEFAULT_UNIT_CLASS_SUFFIXES, un-droppable by
+  # config). List your app's extra unit-layer suffixes here.
+  UnitClassSuffixes: []
+  Include:
+    - "test/controllers/**/*.rb"
+    - "test/integration/**/*.rb"
+    - "spec/requests/**/*.rb"
+
 DevDoc/Test/RequireGlibIntegrationBase:
   Description: "Integration tests in HTTP-driven directories must subclass the project base (Glib::IntegrationTest) — the raw framework base sidesteps the runtime HTTP lint and the glib plumbing."
   Enabled: true

data/lib/dev_doc/i18n/pseudo_locale.rb

@@ -39,9 +39,12 @@
 # locale can never leak to real users.
 module DevDoc
   module I18n
+    # Pseudo-locale ('en-PSEUDO') machinery for hardcoded-text detection:
+    # wraps every translated string in visible markers so any UNMARKED copy
+    # in a rendered page is, by construction, text that bypassed I18n.
     module PseudoLocale
-      PSEUDO_LOCALE = 'en-PSEUDO'
-      MARKER = '⟦'
+      PSEUDO_LOCALE = 'en-PSEUDO'.freeze
+      MARKER = '⟦'.freeze
 
       def self.active?
         ENV['PSEUDO_I18N'] == '1'
@@ -79,7 +82,8 @@ module DevDoc
         ::I18n::Backend::Simple.prepend(Backend)
         ::I18n.available_locales |= [PSEUDO_LOCALE.to_sym]
         force_locale!
-        ::Rails.logger.info('[pseudo_locale] en-PSEUDO locale enabled (forced) for hardcoded-text detection') if defined?(::Rails.logger)
+        # &. only because the logger may not be assigned yet this early in boot.
+        ::Rails.logger&.info('[pseudo_locale] en-PSEUDO locale enabled (forced) for hardcoded-text detection')
       end
 
       # Force every request to render in the pseudo locale.
@@ -109,6 +113,22 @@ module DevDoc
         # copy. Accenting these would corrupt strftime (`%A`), number formats.
         SKIP_NAMESPACES = %w[i18n date time datetime number support].freeze
 
+        # Some t() values are not display copy — asset filenames, paths, URLs.
+        # The asset helpers feed these to Vite, which raises on a missing
+        # manifest entry, so accenting them 500s the page. Leave them untouched.
+        #
+        # Note: do NOT treat a bare "/" as a path — display copy legitimately
+        # contains slashes ("Lamp/Bulbs", "Food/Food Scraps"). A real path is an
+        # all-lowercase identifier chain (`shared/layouts/main`, `images/icon`);
+        # copy has capitals or spaces, so it won't match the lowercase-path rule.
+        NON_COPY = %r{
+          \A\s*\z                              # blank
+          | \Ahttps?://                        # url
+          | \A[a-z0-9_]+(?:[/.][a-z0-9_]+)+\z  # lowercase path / dotted id (shared/layouts/main)
+        }x
+
+        ASSET_EXT = /\.(?:png|jpe?g|svg|gif|webp|ico|bmp|css|js|mjs|html?|pdf|woff2?|ttf|otf|mp[34]|json|xml|csv)\z/i
+
         def lookup(locale, key, scope = [], options = ::I18n::EMPTY_HASH)
           return super unless locale.to_s == PSEUDO_LOCALE
 
@@ -136,22 +156,6 @@ module DevDoc
           end
         end
 
-        # Some t() values are not display copy — asset filenames, paths, URLs.
-        # The asset helpers feed these to Vite, which raises on a missing
-        # manifest entry, so accenting them 500s the page. Leave them untouched.
-        #
-        # Note: do NOT treat a bare "/" as a path — display copy legitimately
-        # contains slashes ("Lamp/Bulbs", "Food/Food Scraps"). A real path is an
-        # all-lowercase identifier chain (`shared/layouts/main`, `images/icon`);
-        # copy has capitals or spaces, so it won't match the lowercase-path rule.
-        NON_COPY = %r{
-          \A\s*\z                              # blank
-          | \Ahttps?://                        # url
-          | \A[a-z0-9_]+(?:[/.][a-z0-9_]+)+\z  # lowercase path / dotted id (shared/layouts/main)
-        }x
-
-        ASSET_EXT = /\.(?:png|jpe?g|svg|gif|webp|ico|bmp|css|js|mjs|html?|pdf|woff2?|ttf|otf|mp[34]|json|xml|csv)\z/i
-
         def wrap(str)
           return str if str.match?(NON_COPY) || str.match?(ASSET_EXT)
 

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

@@ -0,0 +1,43 @@
+module DevDoc
+  module Test
+    module Lints
+      # Cop-inventory tripwire: every DevDoc cop the installed gem registers
+      # must be MENTIONED BY FULL NAME in the project's `.rubocop.yml` —
+      # enabled, disabled-with-reason, or a commented adoption-TODO all count.
+      # A mention proves a reviewed decision; a cop nobody has named is a cop
+      # nobody has decided about.
+      #
+      # ## Why offenses alone can't guard this
+      # A new cop WITH offenses announces itself by failing rubocop. Two
+      # shapes stay silent forever without this check:
+      # - Cops shipped `Enabled: false` (review aids) never produce an
+      #   offense, so no run ever surfaces them.
+      # - Zero-offense auto-enables that need PROJECT configuration to bite
+      #   (AllowedMethods / RolePredicates-style lists) run at weak gem
+      #   defaults while looking like coverage.
+      # Agent memory and human habit don't transfer between machines; a
+      # suite-failing check does.
+      #
+      # ## Usage
+      # This file holds only the pure, Rails-free core (so the gem's own spec
+      # suite can load it). Projects require the test-class wrapper instead,
+      # from the test helper (Rails test env):
+      #
+      #   require 'dev_doc/test/lints/cop_drift_test'
+      module CopDriftCheck
+        COP_NAME = %r{^(DevDoc/[A-Za-z0-9]+/[A-Za-z0-9]+):}
+
+        module_function
+
+        # Pure core, spec-covered: which registered cops does the config text
+        # never mention? Boundary-aware match — a plain substring check would
+        # let a cop whose name PREFIXES another mentioned cop pass for free
+        # (RequireGlibTravel riding on RequireGlibTravelBlock).
+        def unmentioned_cops(show_cops_output, config_text)
+          registered = show_cops_output.scan(COP_NAME).flatten.uniq
+          registered.reject { |cop| config_text.match?(/#{Regexp.escape(cop)}(?![A-Za-z0-9])/) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+require 'dev_doc/test/lints/cop_drift_check'
+
+# Suite-failing tripwire (see DevDoc::Test::Lints::CopDriftCheck for the
+# doctrine): fails until every registered DevDoc cop is mentioned by full
+# name in the project's .rubocop.yml.
+#
+# Require from the project's test helper (Rails test env):
+#
+#   require 'dev_doc/test/lints/cop_drift_test'
+#
+# The superclass reference is deliberately UNGUARDED: consumers are Rails
+# projects, so if ActiveSupport isn't loaded yet the require fails loudly
+# (fix the require order) instead of silently skipping the tripwire.
+# Opt out of a single run with SKIP_COP_DRIFT=1.
+class DevDocCopDriftTest < ActiveSupport::TestCase
+  def test_every_dev_doc_cop_is_mentioned_in_rubocop_yml
+    skip 'opted out via SKIP_COP_DRIFT' if ENV['SKIP_COP_DRIFT'] == '1'
+
+    output = `bundle exec rubocop --show-cops 2>/dev/null`
+    assert output.match?(DevDoc::Test::Lints::CopDriftCheck::COP_NAME),
+           'no DevDoc cops parsed from `rubocop --show-cops` — did the command fail, ' \
+           'or is the rubocop-dev_doc plugin not loaded in .rubocop.yml?'
+
+    unmentioned = DevDoc::Test::Lints::CopDriftCheck.unmentioned_cops(output, project_rubocop_config)
+    assert_empty unmentioned, drift_message(unmentioned)
+  end
+
+  private
+
+  def project_rubocop_config
+    Rails.root.join('.rubocop.yml').read
+  end
+
+  def drift_message(unmentioned)
+    'The installed rubocop-dev_doc registers cops that .rubocop.yml never mentions — ' \
+      'a gem release shipped new cops nobody adopted or declined. Run an adoption wave ' \
+      "(measure, triage, enable) or decline each BY NAME with a reasoned comment:\n  " \
+      "#{unmentioned.join("\n  ")}"
+  end
+end

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

@@ -4,6 +4,73 @@ require 'fugit'
 module DevDoc
   module Test
     module Lints
+      # Locates a job class's source file under a jobs directory and reads a
+      # duration constant (e.g. `STALENESS_THRESHOLD = 1.hour`) from it.
+      # Split out of CronScheduleChecker: file location + duration parsing is
+      # a self-contained concern with no knowledge of cron.
+      module JobDurationConstant
+        # Seconds per unit for `<n>.<unit>` ActiveSupport::Duration literals
+        # (e.g. `45.minutes`, `1.hour`, `7.days`).
+        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
+
+        module_function
+
+        # Returns the constant's value in seconds, or nil if the job file or
+        # constant is not found, or the value isn't a simple duration literal.
+        def read(class_name, jobs_root, constant)
+          source = job_source(class_name, jobs_root)
+          return nil unless source
+
+          parse_duration(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)
+          # Fast path: the conventional file name (MyFetchJob → my_fetch_job.rb).
+          expected_file = "#{class_name_to_file(class_name)}.rb"
+          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 matching class definition.
+          # 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
+
+        def parse_duration(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
+
+          (match[1].to_f * DURATION_UNITS.fetch(match[2])).to_i
+        end
+      end
+
       # 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
@@ -42,19 +109,7 @@ module DevDoc
         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
+          schedule_entries.filter_map { |name, cron, _opts| interval_offense(name, cron) }
         end
 
         # Checks that each job's staleness threshold constant is strictly
@@ -79,26 +134,12 @@ module DevDoc
         # 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'])
+          jobs_root = jobs_path && Pathname.new(jobs_path)
+          return [] unless jobs_root&.exist?
 
-            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'
+          schedule_entries.filter_map do |name, cron, opts|
+            staleness_offense(name, cron, opts['class'], jobs_root, constant)
           end
         end
 
@@ -125,6 +166,44 @@ module DevDoc
 
         private
 
+        # Parses the schedules file into [name, cron, opts] triples, skipping
+        # entries without a cron. YAML.safe_load returns nil for an empty file.
+        def schedule_entries
+          (YAML.safe_load(@schedules_path.read) || {}).filter_map do |name, opts|
+            next unless opts.is_a?(Hash) && (cron = opts['cron'])
+
+            [name, cron, opts]
+          end
+        end
+
+        # Offender description for one schedule entry, or nil if compliant.
+        def interval_offense(name, cron)
+          interval = interval_seconds_for(cron)
+          return "  #{name}: invalid cron expression (cron: #{cron.inspect})" if interval == :invalid
+          return nil if interval.nil? || interval <= @max_interval_seconds
+
+          "  #{name}: every #{self.class.format_seconds(interval)} (cron: #{cron.inspect})"
+        end
+
+        # Offender description for one schedule entry whose job's staleness
+        # constant is not strictly greater than the cron interval, or nil if
+        # compliant. Jobs without a parseable constant are skipped silently
+        # (they may use a per-record stale? method instead).
+        def staleness_offense(name, cron, class_name, jobs_root, constant)
+          return nil unless class_name
+
+          interval = interval_seconds_for(cron)
+          return nil if interval == :invalid || interval.nil?
+
+          threshold = JobDurationConstant.read(class_name, jobs_root, constant)
+          return nil if threshold.nil? || interval < threshold
+
+          "  #{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
+
         # 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
@@ -134,6 +213,14 @@ module DevDoc
           cron = parse_in_utc(cron_string)
           return :invalid unless cron
 
+          fires = sample_fires(cron)
+          return nil if fires.size < 2
+
+          fires.each_cons(2).map { |a, b| (b - a).to_i }.max
+        end
+
+        # Up to SAMPLE_COUNT consecutive fire times from the fixed anchor.
+        def sample_fires(cron)
           fires = []
           t = SAMPLE_ANCHOR
           SAMPLE_COUNT.times do
@@ -142,10 +229,7 @@ module DevDoc
 
             fires << t
           end
-
-          return nil if fires.size < 2
-
-          fires.each_cons(2).map { |a, b| (b - a).to_i }.max
+          fires
         end
 
         # We measure the cron's nominal interval, not its wall-clock
@@ -158,74 +242,6 @@ module DevDoc
           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
@@ -306,12 +322,7 @@ module DevDoc
 
           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'
+          assert result.empty?, long_interval_message(max, result)
         end
 
         def test_staleness_threshold_aligned
@@ -322,12 +333,7 @@ module DevDoc
 
           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'
+          assert result.empty?, staleness_message(constant, result)
         end
 
         private
@@ -339,6 +345,22 @@ module DevDoc
         def jobs_path
           Rails.root.join('app/jobs')
         end
+
+        def long_interval_message(max, offenders)
+          "Cron schedules must be valid and fire at least every " \
+            "#{CronScheduleChecker.format_seconds(max)}. Offenders:\n" \
+            "#{offenders.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 staleness_message(constant, offenders)
+          "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" \
+            "#{offenders.join("\n")}\n\n" \
+            'See https://github.com/hgani/dev-doc/blob/main/best_practices/backend/en/08_job.md#cron-schedule-frequency'
+        end
       end
     end
   end

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

@@ -172,6 +172,10 @@ module DevDoc
       #     # SNAPSHOT_RESULTS_ROOT = 'test/requests'  # override if needed
       #   end
       module DuplicateSnapshot
+        # Default snapshot-dir root. Per-project override: redefine the
+        # constant on the test class that includes this module.
+        SNAPSHOT_RESULTS_ROOT = 'test/controllers'.freeze
+
         def test_no_unjustified_duplicate_snapshots
           result = DuplicateSnapshotChecker.new(snapshot_results_root).offenders
           if result == DuplicateSnapshotChecker::MissingDir
@@ -194,8 +198,7 @@ module DevDoc
         end
 
         def snapshot_results_root
-          root = defined?(self.class::SNAPSHOT_RESULTS_ROOT) ? self.class::SNAPSHOT_RESULTS_ROOT : 'test/controllers'
-          Rails.root.join(root)
+          Rails.root.join(self.class::SNAPSHOT_RESULTS_ROOT)
         end
       end
     end

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

@@ -54,6 +54,11 @@ module DevDoc
           enforced by DevDoc/Test/RequireUnitTestJustification. Relocating assertions
           into the mailer-preview harness only pins the mailer itself — a request test
           must still prove the controller feeds it (params -> Mailer.with(...)).
+          NEVER bolt on a throwaway request just to silence this lint: a fig-leaf
+          GET whose response nothing asserts against is the disguise the companion
+          cop (DevDoc/Test/NoUnitIdiomsInIntegrationTests) polices. HTTP is not the
+          only entry point — cron-driven flows are legitimately exercised by
+          invoking their JOB and asserting its observable outputs.
         MSG
 
         def before_setup

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