rubocop-dev_doc 0.17.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 11175a594b0adb68ca20c3e2ff0ef414d1136d55152cd010a8d95ee26601a759
-  data.tar.gz: 460f211f62e554bead8cd267a4c3e918159eccff748d2d03f0f06b56454d025e
+  metadata.gz: 3852833893968d60a5c0c198ffd3a2f34cb524a71998464a27803de2d56b44de
+  data.tar.gz: 1b4f675aa6967bca65d6f706997c06c73fe3b954b4092f6f8586e5c17b1e16b8
 SHA512:
-  metadata.gz: 5b5a9ae0aed54ff1979d4deb8313ef53e0e8b3d831e9d3bbdabaf9c4d9c3897acd7486054cbd012222453c9e6dbcd0054821ea83ddac71c1231bc51d7be6072e
-  data.tar.gz: e6acacc3e7f65769104c90d5043a08c6385983ab6c9f38db8088ff30193044ac1cd6e14b365c1cbf521de52d445b84e9c4312f75e2dcb6ab93370077a8134bed
+  metadata.gz: 3b4be761462f9974fa8caa317e1df9d71ead56160dc4d9d0e7b98407af11a8835f09a888e4b8677448981c6e8e032129312d6e469f7134426714351e594cdc64
+  data.tar.gz: 5aca39f093385aae489a8c1a18fcf43eff4995dd7a5d575d237e5a472a8477457789a9cb201ce5ba09abdc6c49fcbf80fbd761467ee2d46447f5ee943111292f

data/config/default.yml

@@ -199,6 +199,29 @@ DevDoc/Rails/NoCollectionIdsWriterInController:
   Include:
     - "app/controllers/**/*.rb"
 
+# Route params are resource identity (a bad URL SHOULD 404), but a
+# form-submitted attribute fed to a finder turns an expected form state
+# (nothing picked yet) into RecordNotFound, and drags the validity check
+# into the controller. The remedy is assignment: put the id on the model
+# and let its validations render the failure.
+DevDoc/Rails/NoFormParamLookupInController:
+  Description: "A record finder in a controller must not be fed by a form-submitted attribute (`params[:form][:attribute]`, `params.dig(:form, :attribute)`); assign the id to the model and let its validations decide."
+  Enabled: true
+  Include:
+    - "app/controllers/**/*.rb"
+
+# The controller is the assignment bridge, not the validity judge: a
+# controller-side `errors.add` is a validation living in the wrong layer,
+# guarded once for one POST while every other write path skips it. The
+# three delivery shapes (rescue, policy guard, verification bang) are
+# auto-exempted — there the check already lives in the right layer and the
+# line only renders its outcome.
+DevDoc/Rails/NoErrorsAddInController:
+  Description: "Controllers must not write errors onto a model (`record.errors.add`); the rule belongs in a model validation or form-object PORO. Delivery of an outcome from a rescue, policy, or verification method is auto-exempted."
+  Enabled: true
+  Include:
+    - "app/controllers/**/*.rb"
+
 DevDoc/Rails/EnumMustBeSymbolized:
   Description: "Declare enums with `enum_symbolize :foo, { … }` instead of a bare `enum`, so the attribute type is set before the enum and the reader returns a symbol."
   Enabled: true
@@ -240,6 +263,14 @@ DevDoc/Style/AvoidInsecureSend:
   Description: "Avoid insecure dynamic `send`/`public_send` — `send` is always flagged; `public_send` requires a prefix or trusted source (validator/mailer)."
   Enabled: true
 
+DevDoc/Style/PreferAllowlistSymbolParam:
+  Description: "Flag a hand-rolled `find`/`detect` allow-list lookup against params/request.headers; use `glib_allowlist_symbol_param` instead."
+  Enabled: true
+
+DevDoc/Style/InMemoryAssociationFind:
+  Description: "Flag block-form `find`/`detect` on an association declared in the same file; use `find_by` unless the in-memory view is required, or disable with a reason."
+  Enabled: true
+
 DevDoc/Style/PreferPublicSend:
   Description: "Prefer `public_send` over `send` — visibility-respecting dispatch surfaces typos/misconfig and documents intent."
   Enabled: true
@@ -605,6 +636,29 @@ Style/SafeNavigationChainLength:
   Enabled: true
   Max: 1
 
+# Early returns over nesting. Core default is already on; listed here because
+# best_practices/backend/en/01a_defensive_programming.md #2 relies on it (the
+# doc dropped its nested-vs-early-return example in favour of this cop and
+# keeps only the guard-SHAPE guidance the cop cannot judge).
+Style/GuardClause:
+  Enabled: true
+
+# Core default is `MinNameLength: 1`, which never fires. Raised to 3 so a bare
+# `|e|` / `|u|` / `|s|` block parameter is an offense — the reader should not
+# have to infer the type from the receiver (see
+# best_practices/intro/en/01_principle.md, Code Intent). The core AllowedNames
+# for this cop is empty (the `at/by/id/…` list belongs to
+# Naming/MethodParameterName); the one exemption here is `t`, the
+# `create_table do |t|` idiom, which made up half of the hits when this was
+# measured against a consuming app (2026-09-09: 87 offenses, 44 of them `|t|`
+# in db/; the other 43 were real). AllowNamesEndingInNumbers stays at its core
+# default (true), so `emp1` passes; `e1` still fails on length.
+Naming/BlockParameterName:
+  Enabled: true
+  MinNameLength: 3
+  AllowedNames:
+    - t
+
 # `has_X?` reads more naturally than the cop's preferred `X?` in many cases —
 # `has_active_subscription?` vs `active_subscription?`, `has_assignee?(member)`
 # vs `assignee?(member)`. Disabled cross-project so individual `.rubocop.yml`
@@ -696,6 +750,40 @@ DevDoc/Test/NoPersistenceInMailerPreviews:
     - "spec/mailers/previews/**/*.rb"
     - "lib/mailer_previews/**/*.rb"
 
+# A test name containing shell- or regex-significant characters breaks running
+# that single test by name: unquoted `-n name` is mis-parsed by the shell
+# (syntax error, redirect, expansion, substitution), and in the `/name/` regex
+# filter form the regex-significant ones match nothing, so the runner reports
+# 0 runs — which reads as a pass. Every character in the default set has a
+# verified failure in at least one of the two forms (checked against a real
+# minitest single-test run); `? { } / !` are deliberately NOT forbidden — see
+# the cop docstring for their caveats. ForbiddenCharacters must list the same
+# characters, in the same order, as the cop's DEFAULT_FORBIDDEN_CHARACTERS
+# (specs enforce set parity; order keeps runtime messages matching specs).
+DevDoc/Test/TestNameSpecialCharacters:
+  Description: "Test names must not contain characters that break single-test runs (shell mis-parse unquoted; `/name/` regex form runs 0 tests)."
+  Enabled: true
+  ForbiddenCharacters: "()[]*+^$\\&;|<>'\"`"
+  Include:
+    - "test/**/*.rb"
+    - "spec/**/*.rb"
+
+# A bare-class `find_by` in a test returns whichever matching row the database
+# yields first. When the attribute is not unique across the table (an email in
+# a tenant-scoped membership table, a slug that repeats per country) the test
+# binds to a different fixture per seed and fails far from the cause — the
+# observed case reproduced only under one seed and read as a flake.
+# `find_sole_by` raises unless exactly one row matches, turning the assumption
+# into an assertion. `find_by!` autocorrects; `find_by` (nil-returning) does
+# not, because a test may assert the nil — rewrite those to `exists?`.
+# Requires Rails 7.0+ (`find_sole_by`); disable on older consumers.
+DevDoc/Test/PreferFindSoleBy:
+  Description: "In tests, `Model.find_by`/`find_by!` on a bare class must be `find_sole_by` — an unscoped lookup by a non-unique attribute silently picks a row per run. Primary-key lookups and association-scoped receivers are not flagged."
+  Enabled: true
+  Include:
+    - "test/**/*.rb"
+    - "spec/**/*.rb"
+
 DevDoc/Test/RequireUnitTestJustification:
   Description: "Every test file must live in a recognized directory; unit-test directories additionally require a justification header (marker phrase: 'deliberate exception')."
   Enabled: true
@@ -915,6 +1003,159 @@ DevDoc/I18n/AvoidTitleizeHumanize:
     - "app/views/**/*.jbuilder"
     - "app/views/**/*.rb"
 
+DevDoc/I18n/HardcodedText:
+  Description: "Warn on any string literal that reads like user-facing copy, in any position — not only glib text props. Use `t(...)`."
+  # A review aid, not a clean lint: it judges strings by shape (prose vs
+  # identifier) and position, so it cannot tell copy a user sees from prose
+  # that never leaves the server. Off by default and `warning` severity; run
+  # it during a localization pass alongside RequireTranslation, which is
+  # precise for glib props but blind to ternary/`||` fallbacks, hashes built in
+  # locals, controller/model/mailer strings and constants.
+  Enabled: false
+  Severity: warning
+  # ExemptKeys: hash keys whose values are never copy (style, routing, model
+  # metadata, i18n plumbing). Every value under them is skipped.
+  ExemptKeys:
+    - styleClass
+    - styleClasses
+    - style
+    - class
+    - id
+    - targetId
+    - name
+    - url
+    - href
+    - src
+    - path
+    - partial
+    - template
+    - layout
+    - controller
+    - action
+    - as
+    - format
+    - content_type
+    - mime_type
+    - accept
+    - class_name
+    - source_type
+    - foreign_key
+    - primary_key
+    - table_name
+    - inverse_of
+    - scope
+    - locale
+  # ExemptMethods: string receivers and direct arguments of these are
+  # patterns, SQL, lookup keys or formats rather than copy.
+  ExemptMethods:
+    - "where"
+    - "rewhere"
+    - "not"
+    - "or"
+    - "having"
+    - "order"
+    - "reorder"
+    - "group"
+    - "select"
+    - "joins"
+    - "left_joins"
+    - "from"
+    - "pluck"
+    - "pick"
+    - "find_by_sql"
+    - "count_by_sql"
+    - "exec_query"
+    - "execute"
+    - "sql"
+    - "sanitize_sql"
+    - "sanitize_sql_array"
+    - "sanitize_sql_for_conditions"
+    - "=="
+    - "!="
+    - "==="
+    - "eql?"
+    - "equal?"
+    - "=~"
+    - "!~"
+    - "include?"
+    - "in?"
+    - "start_with?"
+    - "end_with?"
+    - "match?"
+    - "match"
+    - "casecmp"
+    - "casecmp?"
+    - "gsub"
+    - "gsub!"
+    - "sub"
+    - "sub!"
+    - "tr"
+    - "tr_s"
+    - "delete"
+    - "delete_prefix"
+    - "delete_suffix"
+    - "split"
+    - "squeeze"
+    - "partition"
+    - "rpartition"
+    - "[]"
+    - "[]="
+    - "dig"
+    - "fetch"
+    - "key?"
+    - "has_key?"
+    - "slice"
+    - "except"
+    - "values_at"
+    - "fetch_values"
+    - "send"
+    - "public_send"
+    - "__send__"
+    - "respond_to?"
+    - "const_get"
+    - "const_defined?"
+    - "instance_variable_get"
+    - "instance_variable_set"
+    - "attribute"
+    - "require"
+    - "require_relative"
+    - "load"
+    - "autoload"
+    - "strftime"
+    - "strptime"
+    - "parse"
+    - "header"
+    - "set_header"
+    - "add_header"
+    - "image_url"
+    - "image_path"
+    - "image_tag"
+    - "asset_url"
+    - "asset_path"
+  # DeveloperFacingMethods: receiver-less calls whose whole subtree is
+  # developer-facing (exception and console text). `logger.*` calls are
+  # always skipped.
+  DeveloperFacingMethods:
+    - raise
+    - fail
+    - warn
+    - abort
+    - puts
+    - print
+    - p
+    - pp
+  # DeveloperFacingReceivers: constants whose every call reports to developers
+  # (error trackers), so string arguments to them are never copy.
+  DeveloperFacingReceivers:
+    - Rollbar
+    - Sentry
+    - Honeybadger
+    - Bugsnag
+    - Airbrake
+  Include:
+    - "app/**/*.rb"
+    - "app/**/*.jbuilder"
+
 DevDoc/View/PreferPropOverName:
   Description: "Bind form fields to model attributes with `prop:` (i18n-resolved label/placeholder) instead of a raw `name: 'model[attr]'` with hardcoded text."
   # Disabled by default (new department) — enable per consumer .rubocop.yml.
@@ -929,10 +1170,17 @@ DevDoc/View/PreferPropOverName:
   # credit-card fields capture transient credentials that must never bind to
   # a persisted model, and dynamic-group names are array-param structural keys
   # with no label/placeholder to derive.
+  # fields_file (deprecated field class) posts a raw upload the controller
+  # often parses and discards (CSV imports, server-side processing) — its
+  # prop: machinery calls `.attached?` on the bound model value, so a
+  # conversion of a non-attachment param raises at render and the unsafe
+  # autocorrect would produce exactly that. Attachment-backed uploads belong
+  # on fields_upload, which binds prop: fine.
   ExemptFieldMethods:
     - fields_hidden
     - fields_creditCard
     - fields_dynamicGroup
+    - fields_file
   Include:
     - "app/views/**/*.jbuilder"
     - "app/views/**/*.rb"
@@ -961,17 +1209,35 @@ DevDoc/I18n/RequireTranslation:
     - shareButton
     - fields_text
     - fields_number
-    - fields_select
+    - fields_email
+    - fields_url
     - fields_password
+    - fields_timer
+    - fields_submit
     - fields_textarea
+    - fields_richText
+    - fields_select
+    - fields_dynamicSelect
+    - fields_dynamicGroup
     - fields_check
     - fields_checkGroup
     - fields_chipGroup
-    - fields_timeZone
+    - fields_radio
     - fields_radioGroup
+    - fields_timeZone
     - fields_date
     - fields_datetime
+    - fields_file
     - fields_upload
+    - fields_sign
+    - fields_location
+    - fields_phone
+    - fields_otp
+    - fields_captcha
+    - fields_rating
+    - fields_creditCard
+    - fields_stripeToken
+    - fields_stripeExternalAccount
     - dialogs_alert
     - dialogs_notification
     - snackbars_alert
@@ -984,6 +1250,7 @@ DevDoc/I18n/RequireTranslation:
     - subsubtitle
     - label
     - placeholder
+    - hint
     - text
     - message
     - description
@@ -1021,62 +1288,35 @@ DevDoc/Rails/NoManualRecordInvalid:
   Include:
     - "app/models/**/*.rb"
 
-DevDoc/I18n/ReportText:
-  Description: "Report every user-facing glib text prop — hardcoded and already-localized — to collect all possible texts."
-  # A tooling aid, not a lint: unlike RequireTranslation it fires on *every*
-  # text value (including `t(...)` calls) so you can sweep the codebase and
-  # collect the full list of user-facing strings. Off by default and `info`
-  # severity. Mirrors RequireTranslation's WatchedMethods/LocalizableKeys.
-  Enabled: false
-  Severity: info
-  WatchedMethods:
-    - h1
-    - h2
-    - h3
-    - h4
-    - h5
-    - h6
-    - p
-    - label
-    - markdown
-    - html
-    - button
-    - switch
-    - chip
-    - progressCircle
-    - shareButton
-    - fields_text
-    - fields_number
-    - fields_select
-    - fields_password
-    - fields_textarea
-    - fields_check
-    - fields_checkGroup
-    - fields_chipGroup
-    - fields_timeZone
-    - fields_radioGroup
-    - fields_date
-    - fields_datetime
-    - fields_upload
-    - dialogs_alert
-    - dialogs_notification
-    - snackbars_alert
-    - snackbars_select
-    - banners_alert
-    - banners_select
-  LocalizableKeys:
-    - title
-    - subtitle
-    - subsubtitle
-    - label
-    - placeholder
-    - text
-    - message
-    - description
-    - uploadText
-    - leftText
-    - rightText
-    - onLabel
+# Strict superset of Lint/SuppressedException at its default settings — disable
+# the stock cop when enabling this one (see the cop docstring). Modifier
+# rescues stay out of scope: Style/RescueModifier owns them.
+DevDoc/Style/NoSilentRescue:
+  Description: "A rescue body must re-raise, report the failure (a logger/error-monitor call), or state a justification — never swallow it silently."
+  Enabled: true
   Include:
-    - "app/views/**/*.jbuilder"
-    - "app/views/**/*.rb"
+    - "app/**/*.rb"
+    - "lib/**/*.rb"
+  JustificationMarker: "silent-rescue:"
+  ReportingMethods:
+    - "log"
+    - "warn"
+    - "error"
+    - "errors"
+    - "exception"
+    - "fatal"
+    - "critical"
+    - "notify"
+    - "notice"
+    - "report"
+    - "capture"
+    - "track"
+    - "instrument"
+    - "monitor"
+    - "alert"
+    - "breadcrumb"
+    - "handle"
+
+DevDoc/Style/UseGLog:
+  Description: "Route logging through GLog (glib-web) — flag Rails.logger.<any> and Rollbar's reporting methods (error/warning/info/debug/critical/log) outside the facade; Rollbar.configure and other setup calls are not reporting."
+  Enabled: true

data/config/obsoletion.yml

@@ -1,5 +1,9 @@
-# Cop renames across rubocop-dev_doc versions. RuboCop surfaces these as
-# actionable "has been renamed" errors when a project's config or inline
-# directives use the old name.
+# Cop renames and removals across rubocop-dev_doc versions. RuboCop surfaces
+# these as actionable "has been renamed"/"has been removed" errors when a
+# project's config or inline directives use the old name.
 renamed:
   DevDoc/Migration/AvoidBypassingValidation: DevDoc/Rails/AvoidBypassingValidation
+
+removed:
+  DevDoc/I18n/ReportText:
+    alternatives: DevDoc/I18n/HardcodedText

data/lib/dev_doc/i18n/tasks.rb

@@ -0,0 +1,68 @@
+# Rake tasks wrapping the commands in docs/localization.md, so a project runs
+# `bin/rails dev_doc:i18n:scan` instead of copying long rubocop invocations.
+#
+# Loaded by DevDoc::Railtie (lib/dev_doc/railtie.rb) in projects that bundle
+# the gem with `require: 'dev_doc/railtie'`.
+#
+# Tasks (paths default to `app`; pass several as `[app/views,app/mailers]`):
+#
+#   bin/rails dev_doc:i18n:scan[paths]       Recipe A — hardcoded text
+#   bin/rails dev_doc:i18n:rekey[paths]      Recipe B — keys to move
+#
+# Each task accepts OUT=<file> to save the findings instead of printing
+# them (Recipe C hands that file to an AI assistant), and exit with rubocop's
+# status: 0 clean, 1 findings, 2 error.
+require 'rake'
+require 'fileutils'
+
+module DevDoc
+  module I18n
+    # `dev_doc:i18n:*` rake tasks: the localization recipes' commands, runnable
+    # from a project that bundles the gem.
+    module Tasks
+      extend Rake::DSL
+
+      HARDCODED_COPS = %w[
+        DevDoc/I18n/RequireTranslation
+        DevDoc/I18n/HardcodedText
+        DevDoc/I18n/AvoidTitleizeHumanize
+      ].freeze
+      RUBOCOP_TASKS = {
+        scan: [HARDCODED_COPS, 'List hardcoded user-facing text (Recipe A)'],
+        rekey: [%w[DevDoc/I18n/TranslationKeyPrefix], 'List lazy keys and keys outside AllowedPrefixes (Recipe B)']
+      }.freeze
+      DEFAULT_PATHS = %w[app].freeze
+
+      def self.define
+        namespace :dev_doc do
+          namespace :i18n do
+            RUBOCOP_TASKS.each do |name, (cops, summary)|
+              desc "#{summary}; OUT=<file> saves the findings"
+              task(name) { |_t, args| run_rubocop(cops, args.to_a) }
+            end
+          end
+        end
+      end
+
+      def self.rubocop_args(cops, paths, out: nil)
+        args = %w[--format clang]
+        # --out binds to the --format before it, so it must follow it directly.
+        args += ['--out', out] if out
+        args + ['--only', cops.join(','), *(paths.empty? ? DEFAULT_PATHS : paths)]
+      end
+
+      def self.run_rubocop(cops, paths)
+        require 'rubocop'
+
+        out = ENV.fetch('OUT', '')
+        out = nil if out.empty?
+        FileUtils.mkdir_p(File.dirname(out)) if out
+        status = RuboCop::CLI.new.run(rubocop_args(cops, paths, out: out))
+        puts "Findings written to #{out}" if out && status != 2
+        exit(status) unless status.zero?
+      end
+    end
+  end
+end
+
+DevDoc::I18n::Tasks.define

data/lib/dev_doc/railtie.rb

@@ -0,0 +1,19 @@
+# Registers dev-doc's rake tasks in a Rails app. Projects name this file as the
+# gem's require instead of `require: false`:
+#
+#   group :development, :test do
+#     gem 'rubocop-dev_doc', require: 'dev_doc/railtie'
+#   end
+#
+# Booting the app loads only this Railtie; RuboCop itself is loaded when a task
+# runs, so app boot stays as light as with `require: false`.
+require 'rails/railtie'
+
+module DevDoc
+  # Loads the `dev_doc:*` rake tasks when Rails loads the app's tasks.
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      require 'dev_doc/i18n/tasks'
+    end
+  end
+end

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

@@ -77,6 +77,8 @@ module DevDoc
         def __dev_doc_response_body
           response&.body.to_s
         rescue StandardError
+          # silent-rescue: the canary check must never fail on an unreadable
+          # response body; an empty body simply carries no markers to match.
           ''
         end
 

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

@@ -103,6 +103,8 @@ module DevDoc
         def __dev_doc_source_file
           method(name).source_location&.first
         rescue NameError
+          # silent-rescue: an unresolvable test-method name means the source
+          # file is unknown; the location line renders without it.
           nil
         end
 

data/lib/dev_doc/test/pseudo_i18n_crawler.rb

@@ -123,6 +123,8 @@ module DevDoc
         def parse_json(body)
           JSON.parse(body)
         rescue JSON::ParserError
+          # silent-rescue: non-JSON bodies are expected here — scan_body only
+          # wants the parseable ones and skips the rest.
           nil
         end
 
@@ -170,6 +172,9 @@ module DevDoc
             data = YAML.safe_load_file(file, permitted_classes: [Date, Time], aliases: true)
             collect_strings(data, set)
           rescue Psych::Exception
+            # silent-rescue: an unparsable fixture is skipped; its strings
+            # then count as noise candidates instead of exclusions, which
+            # shows up in the report rather than hiding anything.
             next
           end
         end