rubocop-dev_doc 0.6.0.beta1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dfa7b6778294801c95bb37bb3c15a2c4b30f81e9b915ba3ee548475c4adc9cd4
-  data.tar.gz: 6606b6c2b6745b2c54f63a89a7b3ae1b4ce3bfb60dda96a471dc51e33232e802
+  metadata.gz: 7d3924b0184e741e19b3f29854b6f472a9bd54667ddfef1e59ccc1aa000e5073
+  data.tar.gz: d59338919f825edec8ed8bbc717d26f19782fbc88411d90e1a8e0c110d07235d
 SHA512:
-  metadata.gz: adc4743bfba263e139f6ca4cc5abbc213c427a46081e0aa5bc12be84ae96cc26f5b37eb218707449ca4566e5fca6958534f9581104c0d92c97f83e2ef17003b2
-  data.tar.gz: f8aa2b1f19d0f1a628f86ae58b19ed71ba6c5f508fd3247203909f459fb22deeef7777fc5de17509af04a0e4618aebd95c1b19a6fdf78fe53c72f97db063e261
+  metadata.gz: 606dad217da6a65ddc8eb66040f2f8747be5fed37aa27764f2ae74a2fa2266158e848d780b2ee10a7d690f20832b0c36b3a5b3b16d766c433c99088226b78c8e
+  data.tar.gz: 49cac436e0dfef59326c94b89187c5d6001578972d0faa76f2fca683cfd93b9dc1e5866093351884a49e0ad58cb0f6f768a4711275f57e6bf85d24efc913137f

data/config/default.yml

@@ -31,6 +31,10 @@ DevDoc/Test:
   DocumentationBaseURL: https://github.com/hgani/dev-doc/blob/main/docs/cops
   DocumentationExtension: ".md"
 
+DevDoc/View:
+  DocumentationBaseURL: https://github.com/hgani/dev-doc/blob/main/docs/cops
+  DocumentationExtension: ".md"
+
 DevDoc/Migration/AvoidJsonColumn:
   Description: "Use `jsonb` instead of `json` for column types."
   Enabled: true
@@ -66,14 +70,39 @@ DevDoc/Migration/AvoidNonNull:
     - "db/migrate/*.rb"
     - "db/migrate/**/*.rb"
 
+DevDoc/Migration/AvoidBooleanColumn:
+  Description: "Avoid `boolean` columns; prefer a timestamp, enum, or model method that better models the data."
+  Enabled: true
+  Include:
+    - "db/migrate/*.rb"
+    - "db/migrate/**/*.rb"
+
+DevDoc/Migration/BooleanColumnNotNull:
+  Description: "Boolean columns must carry `null: false` — NULL is outside {true, false}."
+  Enabled: true
+  Include:
+    - "db/migrate/*.rb"
+    - "db/migrate/**/*.rb"
+
 # Intentionally global (no Include) — these patterns are risky in any file, not only migrations.
 # Add project-specific Exclude entries (e.g. db/seeds.rb, lib/tasks/**/*.rb) in your .rubocop.yml
 # for places where bulk operations are intentional and performance-critical.
+#
+# Strict SUPERSET of Rails/SkipsModelValidations: covers all 18 methods that
+# cop flags, plus `delete_all` and `save(validate: false)`, with per-method
+# actionable messages. When enabling this cop, DISABLE the stock one —
+# otherwise every offense needs a disable comment naming both cops:
+#   Rails/SkipsModelValidations:
+#     Enabled: false
+# Use AllowedMethods for skips that are by-design in your project (touch,
+# counter caches) instead of per-site disables.
 DevDoc/Migration/AvoidBypassingValidation:
-  Description: "Avoid methods that bypass validations and callbacks (`update_column`, `update_all`, `insert_all`, etc.)."
+  Description: "Avoid methods that bypass validations and callbacks (`update_column`, `update_all`, `insert_all`, `touch`, etc.). Superset of Rails/SkipsModelValidations — disable that cop when enabling this one."
   Enabled: false
+  AllowedMethods: []
   Exclude:
     - "spec/**/*"
+    - "test/**/*"
 
 DevDoc/Migration/DateColumnNaming:
   Description: "Date columns should end with `_on`; datetime columns should end with `_at`."
@@ -285,6 +314,51 @@ DevDoc/Style/StringSymbolComparison:
   Description: "Comparing a known-string source (params, request.headers, ENV) to a symbol literal is always false."
   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
+  # Autocorrect (|| chains of truthy literals -> comma list) deliberately changes
+  # behavior: the dead alternative starts matching. That is the fix, but re-verify
+  # any code that depended on the buggy match — hence unsafe.
+  SafeAutoCorrect: false
+
+DevDoc/Style/RedundantGuardAfterBang:
+  Description: "A nil/presence guard right after assigning from a bang method is dead code — bang methods raise on failure instead of returning nil."
+  Enabled: true
+  # Ruby-core mutator bangs legitimately return nil when nothing changed, so
+  # guarding them is real logic, not a dead guard. Extend this list for any
+  # app-specific bang with deliberate nil-on-no-op semantics (or better, rename
+  # such a method — a nil-returning `!` is itself misleading).
+  AllowedMethods:
+    - gsub!
+    - sub!
+    - strip!
+    - lstrip!
+    - rstrip!
+    - chomp!
+    - chop!
+    - squeeze!
+    - tr!
+    - tr_s!
+    - delete!
+    - delete_prefix!
+    - delete_suffix!
+    - capitalize!
+    - downcase!
+    - upcase!
+    - swapcase!
+    - slice!
+    - uniq!
+    - compact!
+    - flatten!
+    - reject!
+    - select!
+    - filter!
+
+DevDoc/Style/LiteralOperatorInCondition:
+  Description: "`||` between literals in a boolean condition (if/unless/while/until/ternary) folds to one operand, making the condition constant. Flag only — the fix depends on intent. `&&` is left to Lint/LiteralAsCondition."
+  Enabled: true
+
 DevDoc/Test/ResponseAssertEqual:
   Description: "Controller tests that assert on `response.body` should also snapshot the full response with `response_assert_equal`."
   # Enabled by default. A project adopting the gem with an existing backlog will
@@ -363,6 +437,19 @@ DevDoc/Test/AvoidGlibTravelFreeze:
     - "test/**/*.rb"
     - "spec/**/*.rb"
 
+DevDoc/Test/RequireGlibTravelBlock:
+  Description: "`glib_travel` must be called with a block — the bare anchor form leaks frozen time past the test. A bare duration argument (`glib_travel(61.seconds)`) that advances the clock is the accepted non-block form."
+  Enabled: true
+  Include:
+    - "test/**/*.rb"
+    - "spec/**/*.rb"
+
+DevDoc/Test/RequireGlibTravel:
+  Description: "Controller tests must freeze time inside a `glib_travel` (or `glib_travel_freeze`) block — they integrate HTTP, DB, and the clock, so deterministic time is required."
+  Enabled: true
+  Include:
+    - "test/controllers/**/*_test.rb"
+
 DevDoc/Test/AvoidUnitTest:
   Description: "Prefer controller tests; unit tests (`< ActiveSupport::TestCase`) are a rare, justified exception."
   Enabled: true
@@ -370,6 +457,53 @@ DevDoc/Test/AvoidUnitTest:
     - "test/**/*.rb"
     - "spec/**/*.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
+  RequiredBase: Glib::IntegrationTest
+  LegacyBases:
+    - ActionDispatch::IntegrationTest
+  Include:
+    - "test/controllers/**/*_test.rb"
+    - "test/integration/**/*_test.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
+  MarkerPhrase: "deliberate exception"
+  # Total classification — Include deliberately covers ALL test files so a test
+  # can't dodge enforcement by being placed in an invented directory. Note
+  # AvoidUnitTest's base-class heuristic is evadable when a project's universal
+  # test base already descends from ActionDispatch::IntegrationTest — this cop
+  # plus the runtime lint DevDoc::Test::Lints::HttpDrivenControllerTests (which
+  # guarantees everything under test/controllers/ actually drives HTTP) close
+  # that hole from both sides:
+  #   - ExemptDirectories: otherwise-enforced or accepted integration-shaped
+  #     homes. Inheriting a unit base (UnitBaseClasses) there is still an
+  #     offense — a unit test parked in an exempt directory would dodge both the
+  #     header rule and the runtime lint (which only reaches integration-base
+  #     descendants).
+  #   - UnitTestDirectories: allowed only with the justification header.
+  #   - Anything else (including test/ root): flagged as unrecognized — adding a
+  #     new test home is a reviewed config change, not an implicit act.
+  UnitBaseClasses:
+    - Glib::LastResortUnitTest
+  UnitTestDirectories:
+    - models
+    - services
+    - helpers
+  ExemptDirectories:
+    - controllers
+    - integration
+    - jobs
+    - mailers
+    - channels
+    - system
+    - linters
+    - tasks
+  Include:
+    - "test/**/*_test.rb"
+
 Naming/PredicatePrefix:
   Enabled: false
 
@@ -411,11 +545,28 @@ DevDoc/I18n/AvoidTitleizeHumanize:
   Severity: warning
   Methods:
     - titleize
+    - titlecase # ActiveSupport's documented alias of titleize — not a dodge
     - humanize
   Include:
     - "app/views/**/*.jbuilder"
     - "app/views/**/*.rb"
 
+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.
+  # fields_hidden is exempt out of the box: no label/placeholder to hardcode,
+  # and hidden fields (echoed tokens, dynamic-group indexes, forced values)
+  # are the dominant legitimate raw-`name:` users. Autocorrect is unsafe: it
+  # drops the `model` segment (prop: binds to the FORM's model) and leaves
+  # sibling label:/placeholder: for manual removal.
+  Enabled: false
+  SafeAutoCorrect: false
+  ExemptFieldMethods:
+    - fields_hidden
+  Include:
+    - "app/views/**/*.jbuilder"
+    - "app/views/**/*.rb"
+
 DevDoc/I18n/RequireTranslation:
   Description: "Localize user-facing strings in glib JSON-UI props; pass `t(...)` instead of a hardcoded string."
   Enabled: false

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

@@ -17,6 +17,10 @@ module DevDoc
         # duplicate group: `# allow_duplicate_snapshot: <reason>`.
         MARKER = 'allow_duplicate_snapshot'.freeze
 
+        # A bare marker with no reason is mechanics without policy — the
+        # reason is the reviewable part, so it is mandatory.
+        MARKER_WITH_REASON = /#{MARKER}\s*:\s*\S/
+
         # 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(.*)$/
@@ -86,10 +90,12 @@ module DevDoc
         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.
+        # trailing comment, or on the comment line directly above it. The
+        # token only counts WITH a reason (`allow_duplicate_snapshot: <why>`)
+        # — a bare marker still fails, so the opt-out cannot be cargo-culted.
         def marked?(trailing, lines, index)
           context = trailing.to_s + (index.positive? ? lines[index - 1] : '')
-          context.include?(MARKER)
+          context.match?(MARKER_WITH_REASON)
         end
 
         # Resolve the test file for a `*_results` dir. Usually it's the

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

@@ -0,0 +1,92 @@
+module DevDoc
+  module Test
+    module Lints
+      # Runtime guarantee that every test under `test/controllers/` actually
+      # drives the app through HTTP. Include into the project's base
+      # integration test class (a descendant of ActionDispatch::IntegrationTest):
+      #
+      #   Glib::IntegrationTest.include DevDoc::Test::Lints::HttpDrivenControllerTests
+      #
+      # ## Rationale
+      # Best practice (see AvoidUnitTest) prefers controller tests because they
+      # exercise the wiring a user actually hits. Static enforcement keyed on
+      # base class or file name is trivially evaded — and observed evasions by
+      # AI agents include: naming files ambiguously, mixing unit tests into
+      # controller test files, and inheriting the integration base class so the
+      # `< ActiveSupport::TestCase` heuristic never fires.
+      #
+      # This lint closes those holes by keying on *observed behavior*:
+      # `ActionDispatch::Integration::Runner#process` is the single choke point
+      # every request helper funnels through (`get`/`post`/... — no matter how
+      # deeply wrapped in `log_user_in`-style helpers), so "issued at least one
+      # request" is checked per test, not per file. A unit test cannot pass it
+      # by renaming, relocating within the file, or subclassing anything.
+      #
+      # There is deliberately NO opt-out flag: a test that never issues a
+      # request does not belong under `test/controllers/`. Move it to the
+      # matching directory (`test/models/`, `test/jobs/`, ...) with the
+      # justification header your project's conventions require
+      # (see DevDoc/Test/RequireUnitTestJustification).
+      module HttpDrivenControllerTests
+        CONTROLLER_TEST_PATH = %r{(\A|/)test/controllers/}
+
+        MESSAGE = <<~MSG.freeze
+          %<location>s lives under test/controllers/ but never issued an HTTP request —
+          it is a unit test in controller-test clothing. Convert it to drive the app
+          through a request (the bugs live in the wiring), or move it to the directory
+          matching what it exercises (test/models/, test/jobs/, ...) with a documented
+          justification header.
+        MSG
+
+        def before_setup
+          @__dev_doc_http_request_count = 0
+          super
+        end
+
+        # ActionDispatch::Integration::Runner defines the verb helpers on the
+        # test case; each delegates to integration_session.process. Overriding
+        # the verbs here (the module sits ahead of Runner in the MRO) sees every
+        # request no matter how deeply wrapped in project helpers —
+        # `follow_redirect!` also funnels through these.
+        %i[get post patch put delete head options].each do |verb|
+          define_method(verb) do |*args, **kwargs, &block|
+            @__dev_doc_http_request_count = @__dev_doc_http_request_count.to_i + 1
+            super(*args, **kwargs, &block)
+          end
+        end
+
+        def after_teardown
+          super
+        ensure
+          __dev_doc_check_http_driven
+        end
+
+        private
+
+        def __dev_doc_check_http_driven
+          return unless __dev_doc_controller_test?
+          return if skipped? || !passed? # don't mask the test's own failure
+          return if @__dev_doc_http_request_count.to_i.positive?
+
+          raise Minitest::Assertion, format(MESSAGE, location: __dev_doc_test_location)
+        end
+
+        def __dev_doc_controller_test?
+          (__dev_doc_source_file || '') =~ CONTROLLER_TEST_PATH
+        end
+
+        # The file the test method is defined in — robust against shared helpers
+        # because `test '...'` macros define the method at their call site.
+        def __dev_doc_source_file
+          method(name).source_location&.first
+        rescue NameError
+          nil
+        end
+
+        def __dev_doc_test_location
+          "#{self.class}##{name} (#{__dev_doc_source_file})"
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/dev_doc/i18n/avoid_titleize_humanize.rb

@@ -35,7 +35,9 @@ module RuboCop
           MSG = 'Avoid `.%<method>s` for display text: the result is ' \
                 'English-only and bypasses I18n. Use `t(...)` instead.'.freeze
 
-          DEFAULT_METHODS = %w[titleize humanize].freeze
+          # titlecase is ActiveSupport's documented alias of titleize — same
+          # English-only output, so it must not be an alias-shaped dodge.
+          DEFAULT_METHODS = %w[titleize titlecase humanize].freeze
 
           def on_send(node)
             return unless forbidden_methods.include?(node.method_name.to_s)

data/lib/rubocop/cop/dev_doc/i18n/translation_key_prefix.rb

@@ -45,7 +45,9 @@ module RuboCop
           MSG = 'Translation key `%<key>s` must start with an allowed ' \
                 'prefix: %<prefixes>s.'.freeze
 
-          RESTRICT_ON_SEND = %i[t translate].freeze
+          # t!/translate! are public I18n API (raise instead of returning the
+          # missing-translation marker) — same lookup, same prefix rule.
+          RESTRICT_ON_SEND = %i[t translate t! translate!].freeze
 
           def on_send(node)
             prefixes = allowed_prefixes

data/lib/rubocop/cop/dev_doc/migration/avoid_boolean_column.rb

@@ -0,0 +1,135 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Migration
+        # Avoid `boolean` columns; prefer an alternative that better models
+        # the data.
+        #
+        # ## Rationale
+        # A boolean column collapses a domain into exactly two states, but
+        # most "is X?" questions are richer than that in practice. The
+        # constraint pushes developers past the path-of-least-resistance
+        # `add_column :boolean` toward a shape that captures what the data
+        # actually means.
+        #
+        # The question to ask before reaching for `t.boolean` is:
+        # "what does NULL mean here?" — and if the answer is "unset" or
+        # "not yet decided", that semantic should be explicit in the
+        # schema, not silently smuggled in as a third boolean state.
+        #
+        # Consider the alternatives in order:
+        #
+        # ### 1. Timestamp — when the flag implies a moment in time
+        # If the boolean answers "did X happen?", a timestamp gives both
+        # the answer (`approved_at.present?`) AND the moment it happened
+        # (`approved_at`), for free. A boolean gives only the first.
+        #
+        #   ❌ `approved` loses the moment of approval
+        #   add_column :submissions, :approved, :boolean
+        #
+        #   ✔️ `approved_at` answers both "is it approved?" and "when?"
+        #   add_column :submissions, :approved_at, :datetime
+        #
+        # This pattern dominates the codebase (`published_at`, `deleted_at`,
+        # `archived_at`, `completed_at`, etc.) for good reason.
+        #
+        # ### 2. Enum — when "unset" is a meaningful state, or a third
+        # value is plausible
+        # An enum with an explicit "no_X_needed" value models "unset"
+        # honestly. NULL is outside an enum's domain (a type violation),
+        # so the column can carry `null: false` without controversy — see
+        # `DevDoc/Rails/EnumColumnNotNull`.
+        #
+        #   ❌ nullable boolean; nil is a silent third state
+        #   add_column :checklists, :approval_required, :boolean
+        #
+        #   ✔️ enum; "unset" is explicit, null: false is justified
+        #   # rubocop:disable DevDoc/Migration/AvoidNonNull -- enum
+        #   add_column :checklists, :approval_requirement, :integer, null: false
+        #   # rubocop:enable DevDoc/Migration/AvoidNonNull
+        #
+        #   class Checklist < ApplicationRecord
+        #     enum :approval_requirement, { no_approval_needed: 0, approval_by_admins: 1 }
+        #   end
+        #
+        # ### 3. Model method — when the flag is derived from other data
+        # If the answer can be computed from existing columns or
+        # associations, do not store it. A method keeps the source of
+        # truth singular.
+        #
+        #   ❌ denormalises role into a column
+        #   add_column :users, :is_admin, :boolean
+        #
+        #   ✔️ derived from `role`
+        #   class User < ApplicationRecord
+        #     def admin?
+        #       role == "admin"
+        #     end
+        #   end
+        #
+        # ### 4. Boolean — only when none of the above apply
+        # A genuine binary preference with no meaningful third state
+        # (e.g. `auto_renew`, `communication_allowed`). Inline-disable
+        # this cop with a brief `-- boolean` reason. The column MUST also
+        # carry `null: false` — enforced by the sibling cop
+        # `DevDoc/Migration/BooleanColumnNotNull`.
+        #
+        #   ✔️ true binary preference, justified
+        #   # rubocop:disable DevDoc/Migration/AvoidBooleanColumn -- true binary preference; user opt-in
+        #   add_column :service_subscriptions, :auto_renew, :boolean, null: false
+        #   # rubocop:enable DevDoc/Migration/AvoidBooleanColumn
+        #
+        # NOTE: This cop catches `t.boolean`, `add_column ..., :boolean`,
+        # and `change_column ..., :boolean` (a type change to boolean).
+        # `change_column_type` migrations to a non-boolean type are not
+        # flagged — that is the cleanup direction.
+        #
+        # NOTE: This cop is deliberately NOT timestamp-aware. It cannot
+        # tell whether a `:datetime` column would have been a better fit;
+        # that judgment is the developer's at review time. The role of
+        # this cop is to force the moment of judgment, not to make it.
+        #
+        # @example
+        #   # bad
+        #   add_column :users, :is_admin, :boolean
+        #
+        #   # bad
+        #   t.boolean :approved
+        #
+        #   # good (timestamp alternative)
+        #   add_column :submissions, :approved_at, :datetime
+        #
+        #   # good (enum alternative)
+        #   add_column :checklists, :approval_requirement, :integer
+        #
+        #   # good (justified boolean)
+        #   # rubocop:disable DevDoc/Migration/AvoidBooleanColumn -- true binary preference
+        #   add_column :service_subscriptions, :auto_renew, :boolean, null: false
+        #   # rubocop:enable DevDoc/Migration/AvoidBooleanColumn
+        class AvoidBooleanColumn < Base
+          MSG = 'Avoid `boolean` columns; consider a timestamp (approved_at), enum, or model method. ' \
+                'If a boolean is genuinely the right shape, disable this cop with a brief `-- boolean` reason ' \
+                'and ensure the column carries `null: false` (see DevDoc/Migration/BooleanColumnNotNull).'.freeze
+
+          def_node_matcher :boolean_column?, <<~PATTERN
+            (send _ {:boolean} ...)
+          PATTERN
+
+          def_node_matcher :add_column_boolean?, <<~PATTERN
+            (send _ :add_column _ _ (sym :boolean) ...)
+          PATTERN
+
+          def_node_matcher :change_column_to_boolean?, <<~PATTERN
+            (send _ :change_column _ _ (sym :boolean) ...)
+          PATTERN
+
+          def on_send(node)
+            return unless boolean_column?(node) || add_column_boolean?(node) || change_column_to_boolean?(node)
+
+            add_offense(node)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/dev_doc/migration/avoid_bypassing_validation.rb

@@ -14,6 +14,17 @@ module RuboCop
         # reason why existing records may be invalid. If there is, fix those
         # records first rather than bypassing validation.
         #
+        # ## Relationship with Rails/SkipsModelValidations
+        # This cop is a strict SUPERSET of the stock `Rails/SkipsModelValidations`
+        # (it covers every method that cop flags, plus `delete_all` and
+        # `save(validate: false)`), with per-method actionable messages instead
+        # of a generic one. Consumer projects should enable THIS cop and disable
+        # `Rails/SkipsModelValidations` — running both forces every disable
+        # comment to name two cops for the same offense. Methods that skip
+        # validations BY DESIGN in your domain (e.g. `touch`, counter-cache
+        # maintenance) can be permitted wholesale via `AllowedMethods` rather
+        # than disabled per site.
+        #
         #   ❌ Bypasses validation — hides data integrity issues
         #   Faq.where(purpose: nil).update_all(purpose: :intro)
         #
@@ -45,31 +56,88 @@ module RuboCop
           MESSAGES = {
             update_column: 'Avoid `update_column`; it bypasses validations. Use `save!` instead.',
             update_columns: 'Avoid `update_columns`; it bypasses validations. Use `save!` instead.',
+            update_attribute: 'Avoid `update_attribute`; it bypasses validations (the singular is not ' \
+                              'a validating `update`). Use `update!` instead.',
             update_all: 'Avoid `update_all`; it bypasses validations. Use `save!` in a loop instead.',
+            insert: 'Avoid `insert`; it bypasses validations. Use `create!` instead, ' \
+                    'or `# rubocop:disable` with a reason if a raw insert is intentional.',
+            insert!: 'Avoid `insert!`; it bypasses validations (the bang is about duplicate keys, ' \
+                     'not validity). Use `create!` instead.',
             insert_all: 'Avoid `insert_all`; it bypasses validations. Use `create!` in a loop, ' \
                         'or `# rubocop:disable` with a reason if bulk-insert is intentional.',
+            upsert: 'Avoid `upsert`; it bypasses validations. Use `create!`/`update!` instead, ' \
+                    'or `# rubocop:disable` with a reason if a raw upsert is intentional.',
             upsert_all: 'Avoid `upsert_all`; it bypasses validations. Use `create!`/`update!` in a loop, ' \
                         'or `# rubocop:disable` with a reason if bulk-upsert is intentional.',
+            toggle!: 'Avoid `toggle!`; it saves without validations. Use `toggle(...).save!` instead.',
+            increment!: 'Avoid `increment!`; it writes without validations. Use `increment(...).save!` instead.',
+            decrement!: 'Avoid `decrement!`; it writes without validations. Use `decrement(...).save!` instead.',
+            increment_counter: 'Avoid `increment_counter`; it issues a direct UPDATE that bypasses validations ' \
+                               'and callbacks. Use the record with `save!`, or `AllowedMethods` for deliberate ' \
+                               'counter-cache maintenance.',
+            decrement_counter: 'Avoid `decrement_counter`; it issues a direct UPDATE that bypasses validations ' \
+                               'and callbacks. Use the record with `save!`, or `AllowedMethods` for deliberate ' \
+                               'counter-cache maintenance.',
+            update_counters: 'Avoid `update_counters`; it issues a direct UPDATE that bypasses validations ' \
+                             'and callbacks. Use the record with `save!`, or `AllowedMethods` for deliberate ' \
+                             'counter-cache maintenance.',
+            touch: 'Avoid `touch`; it writes timestamps without validations or save callbacks. Use `save!` ' \
+                   '(`updated_at` updates automatically), or `AllowedMethods` if bare timestamp bumps are ' \
+                   'accepted in this project.',
+            touch_all: 'Avoid `touch_all`; it issues a bulk UPDATE that bypasses validations and callbacks. ' \
+                       'Iterate with `save!`, or `# rubocop:disable` with a reason if a bulk timestamp bump ' \
+                       'is intentional.',
+            insert_all!: 'Avoid `insert_all!`; it bypasses validations (the bang is about duplicate keys, ' \
+                         'not validity). Use `create!` in a loop, or `# rubocop:disable` with a reason if ' \
+                         'bulk-insert is intentional.',
             delete_all: 'Avoid `delete_all`; it bypasses callbacks. Use `destroy_all` to run callbacks, ' \
                         'or `# rubocop:disable` with a reason if bulk-delete is intentional.'
           }.freeze
 
           SAVE_MSG = 'Avoid `save(validate: false)`; it bypasses validations. Use `save!` instead.'.freeze
 
-          RESTRICT_ON_SEND = %i[update_column update_columns update_all insert_all upsert_all delete_all save].freeze
+          RESTRICT_ON_SEND = (MESSAGES.keys + %i[save]).freeze
+
+          # insert/insert!/upsert are AR *class-level* APIs (User.insert(...)),
+          # while `insert` on a non-const receiver is everyday Array#insert —
+          # flag only the const-receiver form to avoid false positives.
+          CONST_RECEIVER_ONLY = %i[insert insert! upsert].freeze
+
+          # The inverse for touch: the AR form is instance-level
+          # (`record.touch`), while a const receiver is `FileUtils.touch` or
+          # similar — not an ActiveRecord write at all.
+          NON_CONST_RECEIVER_ONLY = %i[touch].freeze
 
           def on_send(node)
+            return if allowed_methods.include?(node.method_name.to_s)
+
             if node.method?(:save)
               return unless save_with_validate_false?(node)
 
               add_offense(node.loc.selector, message: SAVE_MSG)
             else
+              return unless receiver_shape_matches?(node)
+
               add_offense(node.loc.selector, message: MESSAGES[node.method_name])
             end
           end
 
           private
 
+          def receiver_shape_matches?(node)
+            return node.receiver&.const_type? if CONST_RECEIVER_ONLY.include?(node.method_name)
+            return !node.receiver&.const_type? if NON_CONST_RECEIVER_ONLY.include?(node.method_name)
+
+            true
+          end
+
+          # Methods a project accepts wholesale as by-design validation skips
+          # (e.g. `touch`, counter-cache maintenance) — configure in
+          # .rubocop.yml instead of scattering per-site disables.
+          def allowed_methods
+            cop_config.fetch('AllowedMethods', []).map(&:to_s)
+          end
+
           def save_with_validate_false?(node)
             node.arguments.any? do |arg|
               next unless arg.hash_type?