rubocop-dev_doc 0.3.0 → 0.5.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd15873d6ee53104760162aa0e5cced9dd69ef1297a70a014dd5643b9404703c
-  data.tar.gz: 25d0fa51436912d008625752269ff09ef93e78c14d6d1a941295c6afa47795b4
+  metadata.gz: e13da0de0c2a17314d72cbe4bbeb9882a0ad1f93e4976d2e0548210af1684073
+  data.tar.gz: 57bf1fb471573aaa8417f3a86f9c4eba84ebc1d71d38d397c7cac2d05607d058
 SHA512:
-  metadata.gz: 516d5742aa468568e3884d779649164761f982391be0c5f7e5df474d64a933cf71148fe1fddb433c5cf1cd577debd7aadcb16bf22893963d721a3661a1f0fff0
-  data.tar.gz: 69a643cf2335d6c7bb365a4a2f8513e9a66d09a6cddb2bec5e44df861ebcb906de51d17fbbd1b591388c651c2f1cb662de5e5a887df7f11db3c9885e9d6ae597
+  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
@@ -348,12 +363,17 @@ Rails/HasManyOrHasOneDependent:
   Enabled: true
 
 DevDoc/Auth/LoadResourceCurrentUserGuard:
-  Description: "Require a `return unless current_user` guard before using `current_user` inside `glib_load_resource`, and forbid `current_user&.`."
+  Description: "Require a `return unless current_user` (or `assert_current_user_present`) guard before using `current_user` inside `glib_load_resource`, and forbid `current_user&.`."
   Enabled: true
   # LoadResourceMethodNames: list of method names where the guard rule applies.
   # Extend if your project uses a different lifecycle hook name.
   LoadResourceMethodNames:
     - glib_load_resource
+  # CurrentUserAssertionMethodNames: calls that raise when current_user is nil
+  # (e.g. glib's assert_current_user_present). A call to one before the first
+  # current_user use satisfies the guard. Add custom assertion helpers here.
+  CurrentUserAssertionMethodNames:
+    - assert_current_user_present
 
 DevDoc/Auth/CurrentUserBranching:
   Description: "Avoid branching on `current_user` / `user_signed_in?` in page-specific code. Use shared layouts or an inline disable with a reason for genuinely dual-state pages."
@@ -364,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/auth/load_resource_current_user_guard.rb

@@ -36,6 +36,24 @@ module RuboCop
         #     end
         #   end
         #
+        # glib's `assert_current_user_present` raises when `current_user` is nil,
+        # so it guarantees non-nil just as well as the early return — and any
+        # `raise` guard works like the `return` form:
+        #
+        #   ✔️
+        #   def glib_load_resource
+        #     assert_current_user_present
+        #
+        #     @post = current_user.posts.find(params[:id])
+        #   end
+        #
+        #   ✔️
+        #   def glib_load_resource
+        #     raise UnauthorizedError unless current_user
+        #
+        #     @post = current_user.posts.find(params[:id])
+        #   end
+        #
         #   ❌ Safe navigation — hides the pre-auth nil risk
         #   def glib_load_resource
         #     @post = current_user&.posts&.find(params[:id])
@@ -51,6 +69,13 @@ module RuboCop
         # method names where the guard rule applies. Projects standardising on a
         # different lifecycle method can add it here.
         #
+        # `CurrentUserAssertionMethodNames` (default:
+        # `[assert_current_user_present]`) — calls that raise when `current_user`
+        # is nil. A call to one of these before the first `current_user` use
+        # satisfies the guard. Add project-specific assertion helpers here. NOTE:
+        # the cop trusts the named method to actually raise on nil — a configured
+        # name that doesn't will turn into a false negative.
+        #
         # NOTE: The cop performs structural analysis of the method body and does
         # not track aliasing. If you assign `current_user` to a local variable
         # and then call methods on that variable, the cop will not flag it —
@@ -73,16 +98,32 @@ module RuboCop
         #
         #     @post = current_user.posts.find(params[:id])
         #   end
+        #
+        #   # good — guarded with the glib assertion (raises when nil)
+        #   def glib_load_resource
+        #     assert_current_user_present
+        #
+        #     @post = current_user.posts.find(params[:id])
+        #   end
         class LoadResourceCurrentUserGuard < Base
           MSG_SAFE_NAV = 'Avoid `current_user&.` inside `%<method>s` — use ' \
                          '`return unless current_user` then `current_user.` instead.'.freeze
           MSG_MISSING_GUARD = '`current_user` is used without a prior ' \
-                              '`return unless current_user` guard in `%<method>s`. ' \
+                              '`return unless current_user` (or `assert_current_user_present`) ' \
+                              'guard in `%<method>s`. ' \
                               'This method runs before the policy, so `current_user` may be nil.'.freeze
 
-          # Methods that test current_user for nil — not calls that risk NoMethodError.
+          # Predicates safe to call on a nil `current_user` — a `current_user.nil?`
+          # etc. is not itself an unguarded use that risks NoMethodError.
           NIL_CHECK_METHODS = %i[nil? blank? present? empty?].freeze
 
+          # Predicates split by polarity, so a guard's exit branch can be matched
+          # to the path on which `current_user` is nil. `present?` is a PRESENCE
+          # check (reversed from `nil?`/`blank?`), so `unless current_user.present?`
+          # is a valid guard while `if current_user.present?` is not.
+          ABSENCE_CHECK_METHODS = %i[nil? blank? empty?].freeze
+          PRESENCE_CHECK_METHODS = %i[present?].freeze
+
           def on_def(node)
             check_load_resource_method(node)
           end
@@ -94,6 +135,10 @@ module RuboCop
             Array(cop_config.fetch('LoadResourceMethodNames', ['glib_load_resource'])).map(&:to_sym)
           end
 
+          def current_user_assertion_method_names
+            Array(cop_config.fetch('CurrentUserAssertionMethodNames', ['assert_current_user_present'])).map(&:to_sym)
+          end
+
           def load_resource_method?(method_name)
             load_resource_method_names.include?(method_name.to_sym)
           end
@@ -122,42 +167,30 @@ module RuboCop
 
           # `current_user&.something` — always an offense regardless of guards.
           def safe_nav_on_current_user?(node)
-            node.csend_type? && current_user_receiver?(node)
+            node.csend_type? && bare_current_user?(node.receiver)
           end
 
-          # `current_user.something` where `something` is not a nil check and
-          # no dominating guard protects the call.
+          # `current_user.something` where `something` is not a nil check and no
+          # dominating guard protects the call — i.e. not inside an `if current_user`
+          # then-branch and not preceded by a guard statement in its enclosing `begin`.
           def unguarded_current_user_call?(node)
             return false unless node.send_type?
-            return false unless current_user_receiver?(node)
-            return false if nil_check_method?(node.method_name)
-
-            !dominated_by_guard?(node)
-          end
-
-          # Does the direct receiver of `node` resolve to bare `current_user`?
-          def current_user_receiver?(node)
-            recv = node.receiver
-            recv&.send_type? && recv.method_name == :current_user && recv.receiver.nil?
-          end
+            return false unless bare_current_user?(node.receiver)
+            return false if NIL_CHECK_METHODS.include?(node.method_name)
 
-          def nil_check_method?(method_name)
-            NIL_CHECK_METHODS.include?(method_name)
+            !(inside_current_user_branch?(node) || preceded_by_guard?(node))
           end
 
-          # Returns true if `node` is protected by a `current_user` nil-guard via:
-          # 1. Being inside an `if current_user` then-branch, OR
-          # 2. Having a preceding guard-return statement in its nearest enclosing
-          #    `begin` sequence (handles flat sequences AND nested `when` branches).
-          def dominated_by_guard?(node)
-            inside_current_user_branch?(node) || preceded_by_guard?(node)
+          # True if `node` is a bare `current_user` send (no receiver).
+          def bare_current_user?(node)
+            node&.send_type? && node.method_name == :current_user && node.receiver.nil?
           end
 
           # Walk ancestor `if` nodes and return true when `node` is inside the
           # then-branch of an `if current_user` (not the else-branch).
           def inside_current_user_branch?(node)
             node.each_ancestor(:if) do |if_node|
-              next unless current_user_truthy_condition?(if_node.condition)
+              next unless bare_current_user?(if_node.condition)
 
               if_br = if_node.if_branch
               return true if if_br && (if_br.equal?(node) || descendant_by_identity?(if_br, node))
@@ -186,42 +219,66 @@ module RuboCop
             root.each_descendant.any? { |d| d.equal?(descendant) }
           end
 
-          # True if `stmt` is a guard-return on `current_user`:
-          #   return unless current_user      — condition: current_user, one branch: (return)
-          #   return if current_user.nil?     — condition: current_user.nil?, one branch: (return)
-          #   return if current_user.blank?   — condition: current_user.blank?, one branch: (return)
+          # True if `stmt` guarantees `current_user` is non-nil for everything
+          # that follows it — either:
           #
-          # The parser gem swaps `if_branch`/`else_branch` for `unless`-modifier
-          # forms, so we check BOTH branches for a bare `return` rather than
-          # assuming which side it falls on.
+          # 1. a bare call to a configured assertion helper (default
+          #    `assert_current_user_present`), which raises when nil; or
+          # 2. an early-exit guard whose branch returns OR raises:
+          #      return unless current_user      raise ... unless current_user
+          #      return if current_user.nil?     raise ... if current_user.blank?
           def guard_statement?(stmt)
-            return false unless stmt.if_type?
-
-            condition = stmt.condition
-            return false unless current_user_truthy_condition?(condition) ||
-                                current_user_nil_condition?(condition)
+            assertion_guard_call?(stmt) || exit_guard_statement?(stmt)
+          end
 
-            return_node?(stmt.if_branch) || return_node?(stmt.else_branch)
+          # A bare call (nil receiver) to a "raise when current_user is nil"
+          # helper, e.g. glib's `assert_current_user_present`.
+          def assertion_guard_call?(stmt)
+            stmt.send_type? && stmt.receiver.nil? &&
+              current_user_assertion_method_names.include?(stmt.method_name)
           end
 
-          # Condition is bare `current_user` (truthy check).
-          def current_user_truthy_condition?(condition)
-            condition&.send_type? &&
-              condition.method_name == :current_user &&
-              condition.receiver.nil?
+          # A `return`/`raise` guard whose exit happens on the NIL path — the only
+          # polarity that actually protects later `current_user` use:
+          #   `... unless current_user`     exits via the else branch
+          #   `... if current_user.nil?`    exits via the if branch
+          # (Ruby models an `if`/`unless` modifier as an `if` node with an empty
+          # opposite branch, so we tie the required exit to the condition polarity.
+          # This rejects inverted guards like `return if current_user`.)
+          # A `return`/`raise` guard is valid only when the branch that runs while
+          # `current_user` is nil exits. `if_branch` is the written body regardless
+          # of `if`/`unless`, so combine the condition's polarity with the keyword to
+          # pick that branch. This rejects inverted guards (`return if current_user`).
+          def exit_guard_statement?(stmt)
+            return false unless stmt.if_type?
+
+            polarity = condition_polarity(stmt.condition)
+            return false unless polarity
+
+            body_runs_when_nil = polarity == (stmt.unless? ? :presence : :absence)
+            branch_exits?(body_runs_when_nil ? stmt.if_branch : stmt.else_branch)
           end
 
-          # Condition is `current_user.nil?` or `current_user.blank?`.
-          def current_user_nil_condition?(condition)
-            return false unless condition&.send_type?
-            return false unless NIL_CHECK_METHODS.include?(condition.method_name)
+          # :presence — condition truthy when current_user is present (`current_user`,
+          #   `current_user.present?`); :absence — truthy when absent (`.nil?`/`.blank?`/
+          #   `.empty?`); nil — not a current_user condition.
+          def condition_polarity(condition)
+            return :presence if bare_current_user?(condition)
+            return unless condition&.send_type? && bare_current_user?(condition.receiver)
+            return :presence if PRESENCE_CHECK_METHODS.include?(condition.method_name)
 
-            recv = condition.receiver
-            recv&.send_type? && recv.method_name == :current_user && recv.receiver.nil?
+            :absence if ABSENCE_CHECK_METHODS.include?(condition.method_name)
           end
 
-          def return_node?(node)
-            node&.return_type?
+          # True if `branch` terminates on entry via an early `return` or a bare
+          # `raise`/`fail`. A multi-statement branch (a `begin`) counts when its
+          # LAST statement does.
+          def branch_exits?(branch)
+            return false unless branch
+
+            branch = branch.children.last if branch.begin_type?
+            branch&.return_type? ||
+              (branch&.send_type? && branch.receiver.nil? && %i[raise fail].include?(branch.method_name))
           end
         end
       end

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.0".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.0
+  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: []