rubocop-dev_doc 0.5.0 → 0.6.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2076123d07503e775a29287eafcd8dc9d8cf6e344eeb4b462d29120fdef12879
-  data.tar.gz: 910414d217e37c808b7626add2b876d24f6ef214a725b373e86dc736acb24ff7
+  metadata.gz: dfa7b6778294801c95bb37bb3c15a2c4b30f81e9b915ba3ee548475c4adc9cd4
+  data.tar.gz: 6606b6c2b6745b2c54f63a89a7b3ae1b4ce3bfb60dda96a471dc51e33232e802
 SHA512:
-  metadata.gz: 7681307dae1b8d09d0344c199d4be497bc4c986b4314711ae39550d7d8ced8d8b811d07d98997f8e3fc85d294e6fde1b97c8cb6cdc3c33a40ad3074cda985d62
-  data.tar.gz: a047b648abfcaeb1842158a562c17028601a2f24c67e1f0aa2cdc548377cccd1658dae4b6b68cee1cb4906275a59822f2870160380e71cb5d730c04ce5d44196
+  metadata.gz: adc4743bfba263e139f6ca4cc5abbc213c427a46081e0aa5bc12be84ae96cc26f5b37eb218707449ca4566e5fca6958534f9581104c0d92c97f83e2ef17003b2
+  data.tar.gz: f8aa2b1f19d0f1a628f86ae58b19ed71ba6c5f508fd3247203909f459fb22deeef7777fc5de17509af04a0e4618aebd95c1b19a6fdf78fe53c72f97db063e261

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"
@@ -396,3 +400,150 @@ DevDoc/Auth/CurrentUserBranching:
     - "app/helpers/**/*.rb"
     - "app/controllers/concerns/**/*.rb"
     - "app/views/layouts/**/*"
+
+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."
+  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
+    - h6
+    - p
+    - label
+    - markdown
+    - html
+    - button
+    - switch
+    - chip
+    - progressCircle
+    - shareButton
+    - fields_text
+    - fields_number
+    - fields_select
+    - fields_password
+    - fields_textarea
+    - fields_check
+    - fields_checkGroup
+    - fields_chipGroup
+    - fields_timeZone
+    - fields_radioGroup
+    - fields_date
+    - fields_datetime
+    - fields_upload
+    - dialogs_alert
+    - dialogs_notification
+    - snackbars_alert
+    - snackbars_select
+    - banners_alert
+    - banners_select
+  LocalizableKeys:
+    - title
+    - subtitle
+    - subsubtitle
+    - label
+    - placeholder
+    - text
+    - message
+    - description
+    - uploadText
+    - leftText
+    - rightText
+    - onLabel
+  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/ReportText:
+  Description: "Report every user-facing glib text prop — hardcoded and already-localized — to collect all possible texts."
+  # A tooling aid, not a lint: unlike RequireTranslation it fires on *every*
+  # text value (including `t(...)` calls) so you can sweep the codebase and
+  # collect the full list of user-facing strings. Off by default and `info`
+  # severity. Mirrors RequireTranslation's WatchedMethods/LocalizableKeys.
+  Enabled: false
+  Severity: info
+  WatchedMethods:
+    - h1
+    - h2
+    - h3
+    - h4
+    - h5
+    - h6
+    - p
+    - label
+    - markdown
+    - html
+    - button
+    - switch
+    - chip
+    - progressCircle
+    - shareButton
+    - fields_text
+    - fields_number
+    - fields_select
+    - fields_password
+    - fields_textarea
+    - fields_check
+    - fields_checkGroup
+    - fields_chipGroup
+    - fields_timeZone
+    - fields_radioGroup
+    - fields_date
+    - fields_datetime
+    - fields_upload
+    - dialogs_alert
+    - dialogs_notification
+    - snackbars_alert
+    - snackbars_select
+    - banners_alert
+    - banners_select
+  LocalizableKeys:
+    - title
+    - subtitle
+    - subsubtitle
+    - label
+    - placeholder
+    - text
+    - message
+    - description
+    - uploadText
+    - leftText
+    - rightText
+    - onLabel
+  Include:
+    - "app/views/**/*.jbuilder"
+    - "app/views/**/*.rb"

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

@@ -0,0 +1,76 @@
+require_relative 'localizable_props'
+
+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.
+        #
+        # 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
+          include LocalizableProps
+
+          MSG = 'Text for `%<key>s:`: review/collect this for localization.'.freeze
+
+          private
+
+          def inspect_localizable(key, value)
+            return unless text?(value)
+
+            add_offense(value, message: format(MSG, key: key))
+          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
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,95 @@
+require_relative 'localizable_props'
+
+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.
+        #
+        # 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.
+        #
+        # 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'
+        #   view.icon tooltip: { text: 'Share' }
+        #   json.title 'Forms'
+        #
+        #   ✔️ 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 (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}"
+        #
+        #   # 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
+          include LocalizableProps
+
+          MSG = 'Localize this string: pass `t(...)` instead of a hardcoded ' \
+                'string for `%<key>s:`.'.freeze
+
+          private
+
+          def inspect_localizable(key, value)
+            return unless hardcoded_string?(value)
+
+            add_offense(value, message: format(MSG, key: key))
+          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
+        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/dev_doc/version.rb

@@ -1,5 +1,5 @@
 module RuboCop
   module DevDoc
-    VERSION = "0.5.0".freeze
+    VERSION = "0.6.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.5.0
+  version: 0.6.0.beta1
 platform: ruby
 authors:
 - dev-doc contributors
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-27 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,11 @@ 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/avoid_titleize_humanize.rb
+- lib/rubocop/cop/dev_doc/i18n/localizable_props.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/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
@@ -137,12 +139,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
@@ -157,8 +157,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: []