rubocop-dev_doc 0.3.1 → 0.5.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 163ac4a232d22f5d731e680d4ae882172570cdcf3085a07be7d6c3195223e365
-  data.tar.gz: a3eae8c77dcb707ddc4875be90255bea2fa33bcaeba370c7aff06436cd045661
+  metadata.gz: e13da0de0c2a17314d72cbe4bbeb9882a0ad1f93e4976d2e0548210af1684073
+  data.tar.gz: 57bf1fb471573aaa8417f3a86f9c4eba84ebc1d71d38d397c7cac2d05607d058
 SHA512:
-  metadata.gz: a605681c5f22058138abe3d8bdcd1e12eb94073f74e02fde30bc1f1df0baa538022b69fe33c4f83279cfaed995e60e5c9a4936de43cad7a89f07105c4b6e7a24
-  data.tar.gz: 0e845bcf2236245a8c4b0289a02d7731e12c9ac0023732f6135127f02f436c78f349012b98bd18127e89cdb4e70736597c2fc5313229ed3faaf572294e847168
+  metadata.gz: c302ad93dcb52860f23365fa361df3c1f593d618c6948b7b113eac124e640687345c2e953eca523777377eb27d7f75b4c177c2029dc5ceb71e7c30e0d52d5fab
+  data.tar.gz: bf88a2042d7dce6169ec7b274c1249b4c291518076f1d26c5d5b9f8c5a95699bcd1e343d27970e8809f7ad91fafe67d1206a553b1e5e162f14c59458cf3b0416

data/config/default.yml

@@ -7,6 +7,10 @@ DevDoc/Auth:
   DocumentationBaseURL: https://github.com/hgani/dev-doc/blob/main/docs/cops
   DocumentationExtension: ".md"
 
+DevDoc/I18n:
+  DocumentationBaseURL: https://github.com/hgani/dev-doc/blob/main/docs/cops
+  DocumentationExtension: ".md"
+
 DevDoc/Migration:
   DocumentationBaseURL: https://github.com/hgani/dev-doc/blob/main/docs/cops
   DocumentationExtension: ".md"
@@ -247,6 +251,17 @@ DevDoc/Rails/AvoidRailsCallbacks:
   Include:
     - "app/models/**/*.rb"
 
+DevDoc/Rails/AvoidLifecycleMethodOverride:
+  Description: "Avoid overriding Rails validation/persistence lifecycle methods (run_validations!, valid?, etc.) to dodge AvoidRailsCallbacks."
+  Enabled: true
+  Include:
+    - "app/models/**/*.rb"
+  Methods:
+    - run_validations!
+    - valid?
+    - invalid?
+    - perform_validations
+
 DevDoc/Rails/ApplicationRecordTransaction:
   Description: "Use `ApplicationRecord.transaction` instead of `SomeModel.transaction` outside model files."
   Enabled: true
@@ -369,3 +384,135 @@ DevDoc/Auth/CurrentUserBranching:
     - "app/controllers/concerns/**/*.rb"
     - "app/views/layouts/**/*"
     - "app/controllers/application_controller.rb"
+
+DevDoc/I18n/RequireTranslation:
+  Description: "Localize user-facing strings in glib JSON-UI props; pass `t(...)` instead of a hardcoded string."
+  Enabled: false
+  # WatchedMethods: glib component builder methods whose hash props carry
+  # user-facing text. LocalizableKeys: the prop names checked on those calls.
+  # Extend both if your project adds custom components or text props.
+  WatchedMethods:
+    - h1
+    - h2
+    - h3
+    - h4
+    - h5
+    - p
+    - label
+    - markdown
+    - fields_text
+    - fields_number
+    - fields_select
+    - fields_password
+    - fields_textarea
+    - fields_check
+    - fields_checkGroup
+    - fields_chipGroup
+    - fields_timeZone
+    - fields_radioGroup
+    - fields_date
+    - fields_datetime
+  LocalizableKeys:
+    - title
+    - subtitle
+    - subsubtitle
+    - label
+    - placeholder
+    - text
+  Include:
+    - "app/views/**/*.jbuilder"
+    - "app/views/**/*.rb"
+
+DevDoc/I18n/TranslationKeyPrefix:
+  Description: "Translation keys must start with an allowed namespace prefix (e.g. `hotel.`, `general.`)."
+  Enabled: false
+  # AllowedPrefixes is project-specific, so it defaults to empty and the cop is
+  # a no-op until configured. Matches `t`, `translate`, and `I18n.t`. Only
+  # statically-literal keys are checked; dynamic/interpolated keys are skipped.
+  AllowedPrefixes: []
+  Include:
+    - "app/views/**/*.jbuilder"
+    - "app/views/**/*.rb"
+    - "app/controllers/**/*.rb"
+    - "app/mailers/**/*.rb"
+    - "app/helpers/**/*.rb"
+
+DevDoc/I18n/UnverifiedTranslation:
+  Description: "Warn when a glib text prop is set from a non-literal value that isn't a `t(...)` call — it may be an unlocalized string."
+  # A review aid, not a clean lint: it can't tell a stashed literal from
+  # dynamic data (`user.name`) or a translation reached via a variable. Off by
+  # default and `info` severity — run it during a localization pass. Mirrors
+  # RequireTranslation's WatchedMethods/LocalizableKeys.
+  Enabled: false
+  Severity: info
+  WatchedMethods:
+    - h1
+    - h2
+    - h3
+    - h4
+    - h5
+    - p
+    - label
+    - markdown
+    - fields_text
+    - fields_number
+    - fields_select
+    - fields_password
+    - fields_textarea
+    - fields_check
+    - fields_checkGroup
+    - fields_chipGroup
+    - fields_timeZone
+    - fields_radioGroup
+    - fields_date
+    - fields_datetime
+  LocalizableKeys:
+    - title
+    - subtitle
+    - subsubtitle
+    - label
+    - placeholder
+    - text
+  Include:
+    - "app/views/**/*.jbuilder"
+    - "app/views/**/*.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
+    - p
+    - label
+    - markdown
+    - fields_text
+    - fields_number
+    - fields_select
+    - fields_password
+    - fields_textarea
+    - fields_check
+    - fields_checkGroup
+    - fields_chipGroup
+    - fields_timeZone
+    - fields_radioGroup
+    - fields_date
+    - fields_datetime
+  LocalizableKeys:
+    - title
+    - subtitle
+    - subsubtitle
+    - label
+    - placeholder
+    - text
+  Include:
+    - "app/views/**/*.jbuilder"
+    - "app/views/**/*.rb"

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

@@ -0,0 +1,112 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module I18n
+        # Report every user-facing text in a glib JSON-UI text prop — both
+        # hardcoded strings and already-localized `t(...)` calls.
+        #
+        # ## Rationale
+        # `DevDoc/I18n/RequireTranslation` flags only *hardcoded* strings; it
+        # stays silent once a value is localized. This cop is the opposite: it
+        # fires on **every** text value, localized or not, so you can sweep a
+        # codebase and collect the full list of user-facing strings (e.g. to
+        # seed a translation catalog or audit coverage).
+        #
+        # It is a tooling aid, not a lint — **disabled by default** and runs at
+        # `info` severity. Run it during a localization pass; it is not meant
+        # for every commit.
+        #
+        # Both the hardcoded form (`view.p text: 'Welcome'`) and the localized
+        # form (`view.p text: t('home.welcome')`) are reported. Blank/whitespace
+        # strings and pure dynamic values (`user.name`) carry no static text and
+        # are skipped — see `DevDoc/I18n/UnverifiedTranslation` for those.
+        #
+        # The watched method names and localizable keys are configurable via
+        # `WatchedMethods:` and `LocalizableKeys:`.
+        #
+        #   📋 Reported — hardcoded text
+        #   view.p text: 'Welcome'
+        #
+        #   📋 Reported — localized text
+        #   view.p text: t('home.welcome')
+        #
+        # @example
+        #   # info (hardcoded text)
+        #   view.p text: 'Welcome'
+        #
+        #   # info (localized text — still reported)
+        #   view.p text: t('home.welcome')
+        #
+        #   # info (interpolated string)
+        #   view.p text: "Hi #{name}"
+        #
+        #   # ignored (blank — no text)
+        #   view.fields_text label: ''
+        #
+        #   # ignored (pure dynamic — no static text)
+        #   view.p text: user.name
+        class ReportText < Base
+          MSG = 'Text for `%<key>s:`: review/collect this for localization.'.freeze
+
+          DEFAULT_WATCHED_METHODS = %w[
+            h1 h2 h3 h4 h5 p label markdown
+            fields_text fields_number fields_select fields_password
+            fields_textarea fields_check fields_checkGroup fields_chipGroup
+            fields_timeZone fields_radioGroup fields_date fields_datetime
+          ].freeze
+
+          DEFAULT_LOCALIZABLE_KEYS = %w[
+            title subtitle subsubtitle label placeholder text
+          ].freeze
+
+          TRANSLATION_METHODS = %i[t translate].freeze
+
+          def on_send(node)
+            return unless watched_methods.include?(node.method_name.to_s)
+
+            node.arguments.each do |arg|
+              next unless arg.hash_type?
+
+              arg.pairs.each { |pair| check_pair(pair) }
+            end
+          end
+          alias on_csend on_send
+
+          private
+
+          def check_pair(pair)
+            key = pair.key
+            return unless key.sym_type?
+            return unless localizable_keys.include?(key.value.to_s)
+            return unless text?(pair.value)
+
+            add_offense(pair.value, message: format(MSG, key: key.value))
+          end
+
+          # Any value that carries static user-facing text: a non-blank string
+          # literal, an interpolated string, or a translation call. Blank strings
+          # and pure dynamic values (`user.name`) carry no text and are skipped.
+          def text?(node)
+            return true if node.dstr_type?
+            return !node.value.strip.empty? if node.str_type?
+
+            translation_call?(node)
+          end
+
+          def translation_call?(node)
+            (node.send_type? || node.csend_type?) &&
+              TRANSLATION_METHODS.include?(node.method_name)
+          end
+
+          def watched_methods
+            cop_config.fetch('WatchedMethods', DEFAULT_WATCHED_METHODS)
+          end
+
+          def localizable_keys
+            cop_config.fetch('LocalizableKeys', DEFAULT_LOCALIZABLE_KEYS)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,116 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module I18n
+        # Flag hardcoded user-facing strings in glib JSON-UI component props.
+        #
+        # ## Rationale
+        # Glib components render text from props like `text:`, `label:`, and
+        # `title:`. Passing a string literal ships untranslatable copy — it can
+        # never be localized and bypasses the I18n catalog. Pass `t('...')` (or
+        # any non-literal) so the text resolves through the locale files.
+        #
+        # Only the hash form is checked (`view.p text: '...'`). Empty/whitespace
+        # strings are ignored — they carry no user-facing text. An interpolated
+        # string (`"Hi #{name}"`) is flagged because its literal portions are
+        # still hardcoded copy — unless it interpolates a `t(...)` (or
+        # `translate`/`I18n.t`) call, which is treated as positive localization
+        # and left alone.
+        #
+        # The watched method names and localizable keys are configurable via
+        # `WatchedMethods:` and `LocalizableKeys:`.
+        #
+        #   ❌ Hardcoded — can't be translated
+        #   view.p text: 'Welcome'
+        #   view.fields_text label: 'Email'
+        #
+        #   ✔️ Resolved through I18n
+        #   view.p text: t('home.welcome')
+        #   view.fields_text label: t('user.email')
+        #   view.p text: "#{t('home.welcome')}, #{user.name}"
+        #
+        # @example
+        #   # bad
+        #   view.p text: 'Welcome'
+        #
+        #   # bad
+        #   view.fields_text label: 'Email'
+        #
+        #   # bad (interpolation, but no translation call)
+        #   view.p text: "Hi #{name}"
+        #
+        #   # good
+        #   view.p text: t('home.welcome')
+        #
+        #   # good (interpolates a translation call)
+        #   view.p text: "#{t('home.greeting')} #{user.name}"
+        #
+        #   # good (non-literal — not flagged)
+        #   view.p text: user.name
+        class RequireTranslation < Base
+          MSG = 'Localize this string: pass `t(...)` instead of a hardcoded ' \
+                'string for `%<key>s:`.'.freeze
+
+          DEFAULT_WATCHED_METHODS = %w[
+            h1 h2 h3 h4 h5 p label markdown
+            fields_text fields_number fields_select fields_password
+            fields_textarea fields_check fields_checkGroup fields_chipGroup
+            fields_timeZone fields_radioGroup fields_date fields_datetime
+          ].freeze
+
+          DEFAULT_LOCALIZABLE_KEYS = %w[
+            title subtitle subsubtitle label placeholder text
+          ].freeze
+
+          TRANSLATION_METHODS = %i[t translate].freeze
+
+          def on_send(node)
+            return unless watched_methods.include?(node.method_name.to_s)
+
+            node.arguments.each do |arg|
+              next unless arg.hash_type?
+
+              arg.pairs.each { |pair| check_pair(pair) }
+            end
+          end
+          alias on_csend on_send
+
+          private
+
+          def check_pair(pair)
+            key = pair.key
+            return unless key.sym_type?
+            return unless localizable_keys.include?(key.value.to_s)
+            return unless hardcoded_string?(pair.value)
+
+            add_offense(pair.value, message: format(MSG, key: key.value))
+          end
+
+          # A plain string literal is hardcoded copy unless it's blank. A `dstr`
+          # (interpolated string) is hardcoded copy too — unless it interpolates
+          # a translation call, which counts as positive localization.
+          def hardcoded_string?(node)
+            return !localized_interpolation?(node) if node.dstr_type?
+            return false unless node.str_type?
+
+            !node.value.strip.empty?
+          end
+
+          def localized_interpolation?(node)
+            node.each_descendant(:send, :csend).any? do |call|
+              TRANSLATION_METHODS.include?(call.method_name)
+            end
+          end
+
+          def watched_methods
+            cop_config.fetch('WatchedMethods', DEFAULT_WATCHED_METHODS)
+          end
+
+          def localizable_keys
+            cop_config.fetch('LocalizableKeys', DEFAULT_LOCALIZABLE_KEYS)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,89 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module I18n
+        # Require translation keys to start with an allowed namespace prefix.
+        #
+        # ## Rationale
+        # A flat translation catalog drifts into collisions and dead keys.
+        # Requiring every `t(...)` key to start with an agreed namespace (e.g.
+        # `hotel.`, `general.`) keeps the locale files organized and makes it
+        # obvious which feature owns a key.
+        #
+        # The allowed prefixes are project-specific, so `AllowedPrefixes:`
+        # defaults to empty and the cop does nothing until a project configures
+        # it. Matches `t`, `translate`, and `I18n.t` (the receiver is ignored).
+        #
+        # Only statically-literal keys are checked. A key built from
+        # interpolation (`t("#{prefix}.foo")`) or a variable (`t(key)`) can't be
+        # verified and is skipped. A key that begins with a literal segment
+        # (`t("hotel.#{id}")`) is checked against that leading segment.
+        #
+        #   ❌ No recognized prefix
+        #   t('welcome.title')
+        #
+        #   ✔️ Namespaced
+        #   t('general.welcome.title')
+        #   t('hotel.rooms.heading')
+        #
+        # @example AllowedPrefixes: ['hotel.', 'general.']
+        #   # bad
+        #   t('welcome.title')
+        #
+        #   # bad (lazy key has no namespace)
+        #   t('.title')
+        #
+        #   # good
+        #   t('hotel.rooms.heading')
+        #
+        #   # good (variable suffix, literal prefix is checked)
+        #   t("general.#{key}")
+        #
+        #   # not checked (fully dynamic key)
+        #   t("#{prefix}.title")
+        class TranslationKeyPrefix < Base
+          MSG = 'Translation key `%<key>s` must start with an allowed ' \
+                'prefix: %<prefixes>s.'.freeze
+
+          RESTRICT_ON_SEND = %i[t translate].freeze
+
+          def on_send(node)
+            prefixes = allowed_prefixes
+            return if prefixes.empty?
+
+            key_node = node.first_argument
+            return unless key_node
+
+            leading = leading_literal(key_node)
+            return if leading.nil?
+            return if prefixes.any? { |prefix| leading.start_with?(prefix) }
+
+            add_offense(key_node, message: format(MSG, key: key_node.source, prefixes: prefixes_display(prefixes)))
+          end
+
+          private
+
+          # The statically-known leading portion of the key, or nil when the key
+          # is dynamic (a variable, or a string that begins with interpolation).
+          def leading_literal(node)
+            case node.type
+            when :str then node.value
+            when :sym then node.value.to_s
+            when :dstr
+              first = node.children.first
+              first&.str_type? ? first.value : nil
+            end
+          end
+
+          def allowed_prefixes
+            Array(cop_config['AllowedPrefixes'])
+          end
+
+          def prefixes_display(prefixes)
+            prefixes.map { |prefix| "`#{prefix}`" }.join(', ')
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,106 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module I18n
+        # Warn when a glib text prop is set from a non-literal value that isn't
+        # a `t(...)` call — it may be an unlocalized string.
+        #
+        # ## Rationale
+        # `DevDoc/I18n/RequireTranslation` only catches string literals written
+        # at the call site. A value passed through a variable or method
+        # (`label: label_text`) escapes it — the literal could be one hop away.
+        # This cop flags those values so a human can confirm they resolve
+        # through I18n.
+        #
+        # It can't tell a stashed literal from genuinely dynamic data
+        # (`user.name`) or a translation reached via a variable, so it's a
+        # review aid, not a clean lint: it's **disabled by default** and runs at
+        # `info` severity. Run it during a localization pass, not on every
+        # commit. Values that are obviously translated (`t(...)`, `translate`,
+        # `I18n.t`) are excluded; literals are left to `RequireTranslation`.
+        #
+        #   ⚠️ Can't be verified — confirm it's localized
+        #   view.fields_text label: label_text
+        #   view.p text: user.name
+        #
+        #   ✔️ Obviously localized — not flagged
+        #   view.p text: t('home.welcome')
+        #
+        # @example
+        #   # warning (non-literal — may be unlocalized)
+        #   view.fields_text label: label_text
+        #
+        #   # warning (attribute — may be unlocalized)
+        #   view.p text: user.name
+        #
+        #   # good (obviously localized — not flagged)
+        #   view.p text: t('home.welcome')
+        #
+        #   # ignored (literal — handled by RequireTranslation)
+        #   view.p text: 'Welcome'
+        class UnverifiedTranslation < Base
+          MSG = 'Possibly unlocalized: `%<key>s:` is set from a non-literal. ' \
+                'Use `t(...)` if this is user-facing text.'.freeze
+
+          DYNAMIC_TYPES = %i[lvar ivar send csend].freeze
+          TRANSLATION_METHODS = %i[t translate].freeze
+
+          DEFAULT_WATCHED_METHODS = %w[
+            h1 h2 h3 h4 h5 p label markdown
+            fields_text fields_number fields_select fields_password
+            fields_textarea fields_check fields_checkGroup fields_chipGroup
+            fields_timeZone fields_radioGroup fields_date fields_datetime
+          ].freeze
+
+          DEFAULT_LOCALIZABLE_KEYS = %w[
+            title subtitle subsubtitle label placeholder text
+          ].freeze
+
+          def on_send(node)
+            return unless watched_methods.include?(node.method_name.to_s)
+
+            node.arguments.each do |arg|
+              next unless arg.hash_type?
+
+              arg.pairs.each { |pair| check_pair(pair) }
+            end
+          end
+          alias on_csend on_send
+
+          private
+
+          def check_pair(pair)
+            key = pair.key
+            return unless key.sym_type?
+            return unless localizable_keys.include?(key.value.to_s)
+            return unless unverified?(pair.value)
+
+            add_offense(pair.value, message: format(MSG, key: key.value))
+          end
+
+          # A value we can neither confirm nor deny is localized: a variable or
+          # method result (but not an obvious `t(...)`/`translate` call). String
+          # and other literals are excluded — those are RequireTranslation's job.
+          def unverified?(node)
+            return false unless DYNAMIC_TYPES.include?(node.type)
+
+            !translation_call?(node)
+          end
+
+          def translation_call?(node)
+            (node.send_type? || node.csend_type?) &&
+              TRANSLATION_METHODS.include?(node.method_name)
+          end
+
+          def watched_methods
+            cop_config.fetch('WatchedMethods', DEFAULT_WATCHED_METHODS)
+          end
+
+          def localizable_keys
+            cop_config.fetch('LocalizableKeys', DEFAULT_LOCALIZABLE_KEYS)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/dev_doc/rails/avoid_lifecycle_method_override.rb

@@ -0,0 +1,107 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module Rails
+        # Avoid overriding Rails validation/persistence *lifecycle* methods in
+        # model files (`run_validations!`, `valid?`, etc.).
+        #
+        # ## Rationale
+        # `DevDoc/Rails/AvoidRailsCallbacks` bans the callback DSL so lifecycle
+        # behaviour stays visible at explicit call sites. Overriding a lifecycle
+        # method is a loophole — it reproduces the same hidden control flow
+        # without tripping that cop:
+        #
+        #   # Flagged by AvoidRailsCallbacks:
+        #   before_validation :do_something
+        #
+        #   # NOT flagged by it — but functionally identical, and worse:
+        #   def run_validations!
+        #     do_something
+        #     super
+        #   end
+        #
+        # `def run_validations!; do_something; super; end` is a
+        # `before_validation :do_something` in disguise, and it's strictly worse:
+        #
+        # - **Silent on typo.** Misspell the method name (drop the `!`, or
+        #   `run_validatons!`) and it's just a never-called method — no load-time
+        #   error, no override in effect, behaviour silently reverts to stock
+        #   Rails. The callback DSL fails loudly (`NoMethodError`) on a mistyped
+        #   macro or symbol, caught by the first test that validates.
+        # - **More obscure.** Overriding an internal Rails method hides the
+        #   lifecycle hook even more than the DSL it's avoiding.
+        #
+        # This cop pairs with (it does not replace) `AvoidRailsCallbacks`: the two
+        # cover the two ways to inject lifecycle behaviour — the DSL, and the
+        # override.
+        #
+        # ## What to do instead
+        # 1. Prefer an explicit method at the call site (e.g. `save_with_*`) that
+        #    makes the behaviour visible, or a plain `validate :some_check` where
+        #    a validation-time check is all you need.
+        # 2. If an override is genuinely required (e.g. a model whose validators
+        #    read access-gated attributes and must wrap the *entire* validation
+        #    run — something `validate` can't express), disable this cop inline
+        #    with a written justification:
+        #
+        #      def run_validations! # rubocop:disable DevDoc/Rails/AvoidLifecycleMethodOverride
+        #        # Reason: <explanation>
+        #        with_access { super }
+        #      end
+        #
+        # ## Not airtight
+        # A determined dodge can still `prepend` a module, `alias_method`, or use
+        # `method_missing`. This cop raises the bar and makes the documented path
+        # (inline disable + justification) the easy one; it does not seal every
+        # hole.
+        #
+        # ## Configuration
+        # The flagged methods are configurable via `Methods`. The default is the
+        # validation-lifecycle set — the cleanest 1:1 substitute for the
+        # validation callbacks `AvoidRailsCallbacks` bans, with the least
+        # false-positive noise. Projects that also want to guard persistence
+        # verbs can add `save`/`save!`/`create`/`update`/`destroy` etc.
+        #
+        # @example
+        #   # bad
+        #   def run_validations!
+        #     normalize
+        #     super
+        #   end
+        #
+        #   # bad
+        #   def valid?(context = nil)
+        #     toggle_access { super }
+        #   end
+        #
+        #   # good — an explicit method / a plain validation declaration
+        #   validate :assert_consistent
+        #
+        #   # good — a non-lifecycle override is fine
+        #   def to_param
+        #     slug
+        #   end
+        class AvoidLifecycleMethodOverride < Base
+          MSG = 'Avoid overriding the Rails lifecycle method `%<method>s` — it hides ' \
+                'callback-like control flow and silently no-ops if mistyped. Prefer an ' \
+                'explicit method or a `validate` declaration; if an override is genuinely ' \
+                'required, disable this cop inline with a written justification.'.freeze
+
+          DEFAULT_METHODS = %w[run_validations! valid? invalid? perform_validations].freeze
+
+          def on_def(node)
+            return unless flagged_methods.include?(node.method_name)
+
+            add_offense(node.loc.name, message: format(MSG, method: node.method_name))
+          end
+
+          private
+
+          def flagged_methods
+            @flagged_methods ||= Array(cop_config['Methods'] || DEFAULT_METHODS).map(&:to_sym)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/cop/dev_doc/rails/strong_parameters_expect.rb

@@ -120,15 +120,21 @@ module RuboCop
           end
 
           # Build the replacement for `params.require(:key).permit(*args)`.
-          # Symbol args stay as-is; hash args are wrapped in `{ }` since they
-          # need explicit braces when placed inside an array literal.
+          # Symbol args stay as-is; hash args need explicit braces when placed
+          # inside the `expect` array literal.
           def build_require_permit_replacement(params_node, key, permit_args)
             inner = permit_args.map { |arg| permit_arg_source(arg) }.join(', ')
             "#{params_node.source}.expect(#{key}: [#{inner}])"
           end
 
+          # A hash arg written WITHOUT braces (the trailing-kwargs form,
+          # `permit(:a, b: [1])`) has a brace-less source, so add them. A hash
+          # arg written WITH explicit braces (`permit(:a, { b: [1] })`) already
+          # includes them in its source — wrapping again would emit `{ {...} }`.
           def permit_arg_source(arg)
-            arg.hash_type? ? "{ #{arg.source} }" : arg.source
+            return arg.source unless arg.hash_type?
+
+            arg.braces? ? arg.source : "{ #{arg.source} }"
           end
         end
       end

data/lib/rubocop/dev_doc/version.rb

@@ -1,5 +1,5 @@
 module RuboCop
   module DevDoc
-    VERSION = "0.3.1".freeze
+    VERSION = "0.5.0.beta1".freeze
   end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-dev_doc
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.5.0.beta1
 platform: ruby
 authors:
 - dev-doc contributors
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-11 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -80,8 +79,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.0'
-description:
-email:
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -94,6 +91,10 @@ files:
 - lib/rubocop-dev_doc.rb
 - lib/rubocop/cop/dev_doc/auth/current_user_branching.rb
 - lib/rubocop/cop/dev_doc/auth/load_resource_current_user_guard.rb
+- lib/rubocop/cop/dev_doc/i18n/report_text.rb
+- lib/rubocop/cop/dev_doc/i18n/require_translation.rb
+- lib/rubocop/cop/dev_doc/i18n/translation_key_prefix.rb
+- lib/rubocop/cop/dev_doc/i18n/unverified_translation.rb
 - lib/rubocop/cop/dev_doc/migration/amount_column_in_cents.rb
 - lib/rubocop/cop/dev_doc/migration/avoid_bypassing_validation.rb
 - lib/rubocop/cop/dev_doc/migration/avoid_column_default.rb
@@ -107,6 +108,7 @@ files:
 - lib/rubocop/cop/dev_doc/migration/require_primary_key.rb
 - lib/rubocop/cop/dev_doc/migration/require_timestamps.rb
 - lib/rubocop/cop/dev_doc/rails/application_record_transaction.rb
+- lib/rubocop/cop/dev_doc/rails/avoid_lifecycle_method_override.rb
 - lib/rubocop/cop/dev_doc/rails/avoid_rails_callbacks.rb
 - lib/rubocop/cop/dev_doc/rails/bang_save_in_transaction.rb
 - lib/rubocop/cop/dev_doc/rails/enum_column_not_null.rb
@@ -132,12 +134,10 @@ files:
 - lib/rubocop/dev_doc.rb
 - lib/rubocop/dev_doc/plugin.rb
 - lib/rubocop/dev_doc/version.rb
-homepage:
 licenses: []
 metadata:
   default_lint_roller_plugin: RuboCop::DevDoc::Plugin
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -152,8 +152,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.6
-signing_key:
+rubygems_version: 4.0.6
 specification_version: 4
 summary: RuboCop cops enforcing dev-doc best practices
 test_files: []