rubocop-dev_doc 0.5.0.beta1 → 0.6.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e13da0de0c2a17314d72cbe4bbeb9882a0ad1f93e4976d2e0548210af1684073
-  data.tar.gz: 57bf1fb471573aaa8417f3a86f9c4eba84ebc1d71d38d397c7cac2d05607d058
+  metadata.gz: dfa7b6778294801c95bb37bb3c15a2c4b30f81e9b915ba3ee548475c4adc9cd4
+  data.tar.gz: 6606b6c2b6745b2c54f63a89a7b3ae1b4ce3bfb60dda96a471dc51e33232e802
 SHA512:
-  metadata.gz: c302ad93dcb52860f23365fa361df3c1f593d618c6948b7b113eac124e640687345c2e953eca523777377eb27d7f75b4c177c2029dc5ceb71e7c30e0d52d5fab
-  data.tar.gz: bf88a2042d7dce6169ec7b274c1249b4c291518076f1d26c5d5b9f8c5a95699bcd1e343d27970e8809f7ad91fafe67d1206a553b1e5e162f14c59458cf3b0416
+  metadata.gz: adc4743bfba263e139f6ca4cc5abbc213c427a46081e0aa5bc12be84ae96cc26f5b37eb218707449ca4566e5fca6958534f9581104c0d92c97f83e2ef17003b2
+  data.tar.gz: f8aa2b1f19d0f1a628f86ae58b19ed71ba6c5f508fd3247203909f459fb22deeef7777fc5de17509af04a0e4618aebd95c1b19a6fdf78fe53c72f97db063e261

data/config/default.yml

@@ -83,11 +83,12 @@ DevDoc/Migration/DateColumnNaming:
     - "db/migrate/**/*.rb"
 
 DevDoc/Migration/AvoidVagueColumnNames:
-  Description: "Avoid vague column names like `status` or `group`. Use more specific names."
+  Description: "Avoid vague column names like `status`, `group`, or `kind`. Use more specific names."
   Enabled: true
   VagueNames:
     - status
     - group
+    - kind
   Include:
     - "db/migrate/*.rb"
     - "db/migrate/**/*.rb"
@@ -150,10 +151,10 @@ DevDoc/Rails/EnumColumnNotNull:
 DevDoc/Rails/NoBlockPredicateOnRelation:
   Description: "Avoid block-form `count`/`reject`/`select`/`find`/`any?` on AR relations; push the predicate into SQL with `.where(...)` or a scope."
   Enabled: true
+  AdditionalNonRelationMethods: []
   Exclude:
     - "spec/**/*"
     - "test/**/*"
-    - "db/seeds.rb"
     - "db/seeds/**/*.rb"
     - "lib/tasks/**/*.rb"
 
@@ -169,6 +170,10 @@ DevDoc/Style/AvoidSend:
   Description: "Avoid `send`/`public_send` with an explicit receiver; prefer direct calls or safer alternatives."
   Enabled: true
 
+DevDoc/Style/PreferPublicSend:
+  Description: "Prefer `public_send` over `send` — visibility-respecting dispatch surfaces typos/misconfig and documents intent."
+  Enabled: true
+
 DevDoc/Style/RepeatedSafeNavigationReceiver:
   Description: "Avoid using `&.` on the same receiver more than once in a method body — assign once and use `.` after."
   Enabled: true
@@ -181,6 +186,10 @@ DevDoc/Style/MinimizeVariableScope:
   Description: "Assign a variable inside the `if` condition that guards it, to keep its scope local to the branch."
   Enabled: true
 
+DevDoc/Style/TapBlockIgnoresValue:
+  Description: "Flag `tap` whose block ignores the yielded value — `tap` is for operating on the receiver, not eliding a temp var."
+  Enabled: true
+
 DevDoc/Style/AvoidHeadResponse:
   Description: "Avoid `head()` with error statuses; delegate error handling to Rails exceptions or model validations."
   Enabled: true
@@ -311,6 +320,14 @@ DevDoc/Rails/StrongParametersExpect:
   Include:
     - "app/controllers/**/*.rb"
 
+DevDoc/Rails/AvoidRawSql:
+  Description: "Avoid raw SQL — prefer the hash/array form, parameterized fragments, or Arel; disable with a reason when raw SQL is genuinely required."
+  Enabled: true
+
+DevDoc/Rails/AvoidOrderingById:
+  Description: "Avoid `order`/`reorder` by `id` as the primary (sole or leftmost) sort — order by a business column, or use `id` only as a secondary tiebreaker."
+  Enabled: true
+
 # `save!` / `update!` raise on persistence failure, which is what
 # we want in jobs/services/rake tasks — silent `false` returns
 # hide bugs. Excluded for controllers, which lean on `save`
@@ -383,7 +400,21 @@ DevDoc/Auth/CurrentUserBranching:
     - "app/helpers/**/*.rb"
     - "app/controllers/concerns/**/*.rb"
     - "app/views/layouts/**/*"
-    - "app/controllers/application_controller.rb"
+
+DevDoc/I18n/AvoidTitleizeHumanize:
+  Description: "Avoid `.titleize`/`.humanize` for display text; it's English-only and bypasses I18n. Use `t(...)`."
+  # A review aid, not a clean lint: it can't tell a display string from one
+  # used to build a key or a log line. Off by default and `warning` severity;
+  # run it during a localization pass. The flagged methods are configurable
+  # via `Methods:`.
+  Enabled: false
+  Severity: warning
+  Methods:
+    - titleize
+    - humanize
+  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."
@@ -397,9 +428,16 @@ DevDoc/I18n/RequireTranslation:
     - h3
     - h4
     - h5
+    - h6
     - p
     - label
     - markdown
+    - html
+    - button
+    - switch
+    - chip
+    - progressCircle
+    - shareButton
     - fields_text
     - fields_number
     - fields_select
@@ -412,6 +450,13 @@ DevDoc/I18n/RequireTranslation:
     - fields_radioGroup
     - fields_date
     - fields_datetime
+    - fields_upload
+    - dialogs_alert
+    - dialogs_notification
+    - snackbars_alert
+    - snackbars_select
+    - banners_alert
+    - banners_select
   LocalizableKeys:
     - title
     - subtitle
@@ -419,6 +464,12 @@ DevDoc/I18n/RequireTranslation:
     - label
     - placeholder
     - text
+    - message
+    - description
+    - uploadText
+    - leftText
+    - rightText
+    - onLabel
   Include:
     - "app/views/**/*.jbuilder"
     - "app/views/**/*.rb"
@@ -437,46 +488,6 @@ DevDoc/I18n/TranslationKeyPrefix:
     - "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*
@@ -491,9 +502,16 @@ DevDoc/I18n/ReportText:
     - h3
     - h4
     - h5
+    - h6
     - p
     - label
     - markdown
+    - html
+    - button
+    - switch
+    - chip
+    - progressCircle
+    - shareButton
     - fields_text
     - fields_number
     - fields_select
@@ -506,6 +524,13 @@ DevDoc/I18n/ReportText:
     - fields_radioGroup
     - fields_date
     - fields_datetime
+    - fields_upload
+    - dialogs_alert
+    - dialogs_notification
+    - snackbars_alert
+    - snackbars_select
+    - banners_alert
+    - banners_select
   LocalizableKeys:
     - title
     - subtitle
@@ -513,6 +538,12 @@ DevDoc/I18n/ReportText:
     - label
     - placeholder
     - text
+    - message
+    - description
+    - uploadText
+    - leftText
+    - rightText
+    - onLabel
   Include:
     - "app/views/**/*.jbuilder"
     - "app/views/**/*.rb"

data/lib/rubocop/cop/dev_doc/auth/current_user_branching.rb

@@ -56,13 +56,56 @@ module RuboCop
         #
         # ## Allowed paths (Exclude:)
         # By default the cop is silent in:
-        #   app/policies/**/*.rb
+        #   app/policies/**/*.rb          ← auth-dependent checks belong here
         #   app/helpers/**/*.rb
         #   app/controllers/concerns/**/*.rb
-        #   app/views/layouts/**/*
-        #   app/controllers/application_controller.rb
+        #   app/views/layouts/**/*        ← display branching (nav bars, etc.)
         #
-        # Override via `Exclude:` in your `.rubocop.yml`.
+        # Override via `Exclude:` in your `.rubocop.yml`. Note: literal file
+        # paths (e.g. `app/controllers/application_controller.rb`) in
+        # `.rubocop.yml` `Exclude:` lists are flagged by the
+        # `DevDoc::Test::Lints::NoFileExcludes` lint — they hide the
+        # suppression from readers of that file. If `ApplicationController`
+        # needs an exception, use an inline `# rubocop:disable` at the
+        # specific line with a reason.
+        #
+        # ## Before disabling inline, consider the Policy
+        # The Policy exclusion is not accidental — it's the canonical
+        # Rails home for auth-dependent branching. If the flagged line
+        # is an authorization check (`return if @record.accessible_by?(current_user)`,
+        # `if current_user.admin?`, etc.), the right move is almost
+        # always to push that check into a Pundit policy method, not
+        # disable inline. The controller becomes
+        # `return unless policy(@record).access?` — same behaviour,
+        # no `current_user` reference in the controller, and the auth
+        # logic is reusable + testable in isolation.
+        #
+        # Even better: declare `glib_authorize_resource` at the
+        # controller level. glib-web runs the appropriate policy
+        # method before each action automatically, so the per-action
+        # `verify_access` / `authorize @record` line is usually not
+        # needed at all — the controller body no longer references
+        # `current_user` because the auth check has moved out of the
+        # action entirely. See `best_practices/backend/en/05_controller.md`
+        # item #7 for the canonical pattern.
+        #
+        #   ❌ Auth check in the controller — flagged
+        #   def verify_access
+        #     return if @support_question.accessible_by?(current_user)
+        #     # ... token fallback ...
+        #   end
+        #
+        #   ✔️ Same check in the Policy — silently allowed
+        #   # app/policies/support_question_policy.rb
+        #   def access?
+        #     user.present? && record.accessible_by?(user)
+        #   end
+        #
+        #   # in the controller:
+        #   def verify_access
+        #     return if policy(@support_question).access?
+        #     # ... token fallback ...
+        #   end
         #
         # NOTE: The cop does not autocorrect — there is no mechanical fix. The
         # right response depends on developer intent: drop the branch (if auth

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

@@ -0,0 +1,59 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module I18n
+        # Warn when `.titleize` or `.humanize` is used to derive display text.
+        #
+        # ## Rationale
+        # `titleize`/`humanize` turn an identifier into an English phrase
+        # (`'sign_up'.titleize # => 'Sign Up'`). When that result is shown to a
+        # user it bypasses the I18n catalog and can only ever read as English —
+        # it can't be translated. Localize the text with a `t(...)` lookup
+        # instead of transforming a symbol/column name at render time.
+        #
+        # This can't tell a display string from one used to build a key or a
+        # log line, so it is a **review aid**: disabled by default, `warning`
+        # severity, and scoped to view files. Run it during a localization pass.
+        #
+        #   ⚠️ English-only — can't be translated
+        #   view.h1 text: status.titleize
+        #   view.p text: user.role.humanize
+        #
+        #   ✔️ Resolved through I18n
+        #   view.h1 text: t("status.#{status}")
+        #
+        # @example
+        #   # warning
+        #   view.h1 text: status.titleize
+        #
+        #   # warning
+        #   view.p text: model_name.humanize
+        #
+        #   # good
+        #   view.h1 text: t("status.#{status}")
+        class AvoidTitleizeHumanize < Base
+          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
+
+          def on_send(node)
+            return unless forbidden_methods.include?(node.method_name.to_s)
+
+            add_offense(
+              node.loc.selector,
+              message: format(MSG, method: node.method_name)
+            )
+          end
+          alias on_csend on_send
+
+          private
+
+          def forbidden_methods
+            cop_config.fetch('Methods', DEFAULT_METHODS)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,109 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module I18n
+        # Shared traversal for the glib JSON-UI localization cops
+        # (`RequireTranslation`, `ReportText`).
+        #
+        # It locates user-facing text values on watched glib component calls and
+        # hands each `(key, value_node)` to the including cop's
+        # `#inspect_localizable`, which decides whether to report. Three call
+        # shapes are covered:
+        #
+        #   * hash prop:           `view.p text: '...'`
+        #   * nested hash prop:    `view.icon tooltip: { text: '...' }`
+        #   * jbuilder positional: `json.title '...'`
+        #
+        # Nested hashes (and hashes inside arrays, e.g. select options) are
+        # walked to any depth, so a localizable key is found wherever it sits.
+        #
+        # The watched method names and localizable keys are configurable via
+        # `WatchedMethods:` and `LocalizableKeys:`.
+        module LocalizableProps
+          DEFAULT_WATCHED_METHODS = %w[
+            h1 h2 h3 h4 h5 h6 p label markdown html
+            button switch chip progressCircle shareButton
+            fields_text fields_number fields_select fields_password
+            fields_textarea fields_check fields_checkGroup fields_chipGroup
+            fields_timeZone fields_radioGroup fields_date fields_datetime
+            fields_upload
+            dialogs_alert dialogs_notification
+            snackbars_alert snackbars_select
+            banners_alert banners_select
+          ].freeze
+
+          DEFAULT_LOCALIZABLE_KEYS = %w[
+            title subtitle subsubtitle label placeholder text
+            message description uploadText leftText rightText onLabel
+          ].freeze
+
+          TRANSLATION_METHODS = %i[t translate].freeze
+
+          def on_send(node)
+            if watched_methods.include?(node.method_name.to_s)
+              node.arguments.each { |arg| each_localizable(arg) }
+            end
+
+            check_jbuilder_positional(node)
+          end
+          alias on_csend on_send
+
+          private
+
+          # Walk a value, handing every localizable `(key, value)` pair found at
+          # any depth to the cop: top-level hash pairs, nested hashes, and
+          # hashes nested inside arrays (e.g. select options / menu buttons).
+          def each_localizable(node)
+            case node.type
+            when :hash
+              node.pairs.each do |pair|
+                key = pair.key
+                if key.sym_type? && localizable_keys.include?(key.value.to_s)
+                  inspect_localizable(key.value, pair.value)
+                end
+
+                each_localizable(pair.value)
+              end
+            when :array
+              node.children.each { |child| each_localizable(child) }
+            end
+          end
+
+          # jbuilder positional form: `json.title 'Forms'`. The method name is
+          # the key and the first argument is the value. Restricted to the
+          # jbuilder root `json` so ordinary `obj.text('...')` calls aren't
+          # mistaken for localizable props.
+          def check_jbuilder_positional(node)
+            return unless localizable_keys.include?(node.method_name.to_s)
+            return unless json_receiver?(node.receiver)
+
+            value = node.first_argument
+            return unless value
+
+            inspect_localizable(node.method_name, value)
+          end
+
+          def json_receiver?(node)
+            return false unless node
+
+            (node.send_type? && node.method_name == :json && node.receiver.nil?) ||
+              (node.lvar_type? && node.children.first == :json)
+          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/report_text.rb

@@ -1,3 +1,5 @@
+require_relative 'localizable_props'
+
 module RuboCop
   module Cop
     module DevDoc
@@ -19,7 +21,7 @@ module RuboCop
         # 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.
+        # are skipped.
         #
         # The watched method names and localizable keys are configurable via
         # `WatchedMethods:` and `LocalizableKeys:`.
@@ -46,41 +48,16 @@ module RuboCop
         #   # 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
+          include LocalizableProps
 
-          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
+          MSG = 'Text for `%<key>s:`: review/collect this for localization.'.freeze
 
           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)
+          def inspect_localizable(key, value)
+            return unless text?(value)
 
-            add_offense(pair.value, message: format(MSG, key: key.value))
+            add_offense(value, message: format(MSG, key: key))
           end
 
           # Any value that carries static user-facing text: a non-blank string
@@ -92,19 +69,6 @@ module RuboCop
 
             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

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

@@ -1,3 +1,5 @@
+require_relative 'localizable_props'
+
 module RuboCop
   module Cop
     module DevDoc
@@ -10,10 +12,12 @@ module RuboCop
         # 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
+        # Hash props (`view.p text: '...'`), nested hash props
+        # (`view.icon tooltip: { text: '...' }`) and the jbuilder positional
+        # form (`json.title '...'`) are all checked. 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.
         #
@@ -23,6 +27,8 @@ module RuboCop
         #   ❌ Hardcoded — can't be translated
         #   view.p text: 'Welcome'
         #   view.fields_text label: 'Email'
+        #   view.icon tooltip: { text: 'Share' }
+        #   json.title 'Forms'
         #
         #   ✔️ Resolved through I18n
         #   view.p text: t('home.welcome')
@@ -36,6 +42,12 @@ module RuboCop
         #   # bad
         #   view.fields_text label: 'Email'
         #
+        #   # bad (nested hash prop)
+        #   view.icon tooltip: { text: 'Share' }
+        #
+        #   # bad (jbuilder positional)
+        #   json.title 'Forms'
+        #
         #   # bad (interpolation, but no translation call)
         #   view.p text: "Hi #{name}"
         #
@@ -48,42 +60,17 @@ module RuboCop
         #   # good (non-literal — not flagged)
         #   view.p text: user.name
         class RequireTranslation < Base
+          include LocalizableProps
+
           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)
+          def inspect_localizable(key, value)
+            return unless hardcoded_string?(value)
 
-            add_offense(pair.value, message: format(MSG, key: key.value))
+            add_offense(value, message: format(MSG, key: key))
           end
 
           # A plain string literal is hardcoded copy unless it's blank. A `dstr`
@@ -101,14 +88,6 @@ module RuboCop
               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