rubocop-dev_doc 0.17.0 → 0.18.0

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

@@ -0,0 +1,243 @@
+require_relative 'text_shape'
+require_relative 'localizable_props'
+
+module RuboCop
+  module Cop
+    module DevDoc
+      module I18n
+        # Warn on any string literal that reads like user-facing copy, wherever
+        # it sits — not only in glib text props.
+        #
+        # ## Rationale
+        # `DevDoc/I18n/RequireTranslation` checks the value of a known text prop
+        # on a known component. Copy escapes it whenever it reaches the screen
+        # by any other route: a ternary or `||` fallback inside the prop
+        # (`text: signed_in ? 'Sign out' : 'Sign in'`), a hash built in a local
+        # and passed in later (`required = { message: 'Required' }`), a model
+        # method that builds select options, a controller error string, a mailer
+        # subject, a constant. Each of those ships English-only text that can
+        # never be translated.
+        #
+        # This cop inspects every `str`/`dstr` node and reports the ones whose
+        # *shape* is prose (two or more words, a capitalised word, or non-ASCII
+        # letters) and whose *position* is not a known non-text one. It skips:
+        #
+        # * identifier-shaped strings — keys, CSS class lists, paths, URLs,
+        #   MIME types, emails, constants, inline CSS, SQL, `strftime` formats;
+        # * `t(...)`/`translate`/`l`/`localize` keys (a literal `default:` is
+        #   still checked — it is the English the user sees when the key is
+        #   missing);
+        # * hash keys, and values under `ExemptKeys` (`styleClass:`,
+        #   `class_name:`, `url:` ...);
+        # * receivers and direct arguments of `ExemptMethods` (SQL builders,
+        #   comparisons, string matching, hash lookups, `require` ...);
+        # * anything inside `DeveloperFacingMethods` (`raise`, `warn`, ...), a
+        #   `logger.*` call, or a call on a `DeveloperFacingReceivers` constant
+        #   (error trackers such as `Rollbar.error`) — exception, log and
+        #   error-report text is for developers;
+        # * `when` conditions, and the parts of regexps and backticks;
+        # * literals `RequireTranslation` already checks (see below).
+        #
+        # An interpolated string is judged by its literal parts, with each
+        # interpolation counted as a word: `"#{count} items"` is prose,
+        # `"#{a}. #{b}"` and `"badge--#{state}"` are not.
+        #
+        # It cannot tell copy a user sees from prose that never leaves the
+        # server, so it is a **review aid**: disabled by default, `warning`
+        # severity. Run it during a localization pass and either localize each
+        # hit or disable it inline with the reason it is not user-facing.
+        #
+        # ## Relationship with RequireTranslation
+        # The two split the work so each literal is reported by exactly one of
+        # them. `RequireTranslation` owns a literal that is the direct value of
+        # a text prop on a watched glib component (`view.p text: 'Welcome'`,
+        # `json.title 'Orders'`) and flags it whatever its shape; this cop
+        # skips those and covers every other position, using that cop's
+        # `WatchedMethods` and `LocalizableKeys` to tell them apart. Two cases
+        # inside a prop stay here because `RequireTranslation` lets them
+        # through: a literal wrapped in a ternary or `||`, and an interpolated
+        # string that also calls `t(...)`
+        # (`text: "#{t('orders.title')} this month"`). Run both during a
+        # localization pass — on its own, this cop does not see literal glib
+        # props.
+        #
+        # NOTE: ERB templates are not parsed by RuboCop, so literal text in
+        # `.html.erb`/`.text.erb` (mailers, layouts) is not checked. Text built
+        # at runtime (`titleize`, `humanize`, ActiveRecord attribute names in
+        # `errors.full_messages`) is not a literal either — see
+        # `DevDoc/I18n/AvoidTitleizeHumanize` for the former.
+        #
+        #   ⚠️ English-only — can't be translated
+        #   view.button text: signed_in ? 'Sign out' : 'Sign in'
+        #   required = { required: { message: 'Required' } }
+        #   render_error 'Could not save the record'
+        #   mail to: user.email, subject: "Welcome, #{user.name}"
+        #
+        #   ✔️ Resolved through I18n
+        #   view.button text: t(signed_in ? 'auth.sign_out' : 'auth.sign_in')
+        #   render_error t('records.save_failed')
+        #
+        # @example
+        #   # warning (fallback branch of a text prop)
+        #   view.button text: signed_in ? 'Sign out' : 'Sign in'
+        #
+        #   # warning (hash built outside the component call)
+        #   required = { required: { message: 'Required' } }
+        #
+        #   # warning (literal words around a translation)
+        #   view.label text: "#{t('orders.title')} this month"
+        #
+        #   # good
+        #   view.button text: t(signed_in ? 'auth.sign_out' : 'auth.sign_in')
+        #
+        #   # good (identifier-shaped)
+        #   view.panels_vertical styleClass: 'card card--active'
+        #
+        #   # good (developer-facing)
+        #   raise ArgumentError, "Unknown step: #{step}"
+        class HardcodedText < Base
+          MSG ='Possible hardcoded text: this string reads like user-facing copy. ' \
+                'Use `t(...)`, or disable inline with the reason it is never shown to a user.'.freeze
+
+          TRANSLATION_METHODS = %i[t translate l localize].freeze
+          LOGGER_METHODS = %i[debug info warn error fatal unknown add log].freeze
+          # Nodes a value passes through on its way to a key or call
+          # (`[a, b]`, `x ? a : b`, `x || a`, `(a)`), so `styleClass: x ? 'a' : 'b'`
+          # is judged by its key just like `styleClass: 'a'`.
+          VALUE_WRAPPERS = %i[array splat if or and begin].freeze
+
+          def on_str(node)
+            return if part_of_enclosing_literal?(node)
+            return if node.source == '__FILE__'
+
+            check(node)
+          end
+
+          def on_dstr(node)
+            return if part_of_enclosing_literal?(node)
+
+            check(node)
+          end
+
+          private
+
+          def check(node)
+            return unless TextShape.prose?(literal_text(node))
+            return if exempt_position?(node)
+            return if checked_by_require_translation?(node)
+
+            add_offense(node)
+          end
+
+          # Adjacent/continued literals and interpolated strings are judged as
+          # a whole at their outermost `dstr`; regexp and backtick contents are
+          # patterns and commands, not copy.
+          def part_of_enclosing_literal?(node)
+            return true if %i[dstr dsym].include?(node.parent&.type)
+
+            node.each_ancestor(:regexp, :xstr).any?
+          end
+
+          def literal_text(node)
+            return node.value.to_s if node.str_type?
+            return TextShape::PLACEHOLDER unless node.dstr_type?
+
+            node.children.map { |child| literal_text(child) }.join
+          end
+
+          def exempt_position?(node)
+            value = outermost_value(node)
+            parent = value.parent
+
+            return true if exempt_pair?(value, parent)
+            return true if exempt_call_position?(value, parent)
+            return true if parent&.when_type? && parent.conditions.include?(value)
+            return true if node.each_ancestor(:in_pattern).any?
+
+            developer_facing?(node)
+          end
+
+          def checked_by_require_translation?(node)
+            # RequireTranslation accepts a string that interpolates `t(...)`,
+            # so the literal words around it are left for this cop.
+            return false if node.dstr_type? && LocalizableProps.translated_interpolation?(node)
+
+            require_translation = config.for_cop('DevDoc/I18n/RequireTranslation')
+            LocalizableProps.inspected_value?(
+              node,
+              require_translation.fetch('WatchedMethods', LocalizableProps::DEFAULT_WATCHED_METHODS),
+              require_translation.fetch('LocalizableKeys', LocalizableProps::DEFAULT_LOCALIZABLE_KEYS)
+            )
+          end
+
+          def outermost_value(node)
+            current = node
+            while (parent = current.parent) && VALUE_WRAPPERS.include?(parent.type)
+              break if parent.if_type? && parent.condition.equal?(current)
+
+              current = parent
+            end
+            current
+          end
+
+          def exempt_pair?(value, parent)
+            return false unless parent&.pair_type?
+            return true if parent.key.equal?(value)
+
+            key = parent.key
+            (key.sym_type? || key.str_type?) && exempt_keys.include?(key.value.to_s)
+          end
+
+          def exempt_call_position?(value, parent)
+            return false unless parent&.call_type?
+            return true if translation_key?(value, parent)
+            return false unless exempt_methods.include?(parent.method_name.to_s)
+
+            parent.receiver.equal?(value) || parent.arguments.any? { |arg| arg.equal?(value) }
+          end
+
+          def translation_key?(value, call)
+            return false unless TRANSLATION_METHODS.include?(call.method_name)
+
+            receiver = call.receiver
+            (receiver.nil? || (receiver.const_type? && receiver.const_name == 'I18n')) &&
+              call.first_argument.equal?(value)
+          end
+
+          def developer_facing?(node)
+            node.each_ancestor(:send, :csend).any? { |call| developer_facing_call?(call) }
+          end
+
+          def developer_facing_call?(call)
+            receiver = call.receiver
+            return developer_facing_methods.include?(call.method_name.to_s) if receiver.nil?
+            return true if receiver.const_type? && developer_facing_receivers.include?(receiver.const_name)
+
+            LOGGER_METHODS.include?(call.method_name) && logger_receiver?(receiver)
+          end
+
+          def logger_receiver?(receiver)
+            (receiver.send_type? || receiver.lvar_type? || receiver.ivar_type?) &&
+              receiver.source.match?(/logger\z/i)
+          end
+
+          def exempt_keys
+            cop_config.fetch('ExemptKeys', [])
+          end
+
+          def exempt_methods
+            cop_config.fetch('ExemptMethods', [])
+          end
+
+          def developer_facing_methods
+            cop_config.fetch('DeveloperFacingMethods', [])
+          end
+
+          def developer_facing_receivers
+            cop_config.fetch('DeveloperFacingReceivers', [])
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -3,7 +3,7 @@ module RuboCop
     module DevDoc
       module I18n
         # Shared traversal for the glib JSON-UI localization cops
-        # (`RequireTranslation`, `ReportText`).
+        # (`RequireTranslation`).
         #
         # It locates user-facing text values on watched glib component calls and
         # hands each `(key, value_node)` to the including cop's
@@ -23,22 +23,84 @@ module RuboCop
           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
+            fields_text fields_number fields_email fields_url fields_password
+            fields_timer fields_submit fields_textarea fields_richText
+            fields_select fields_dynamicSelect fields_dynamicGroup
+            fields_check fields_checkGroup fields_chipGroup fields_radio
+            fields_radioGroup fields_timeZone fields_date fields_datetime
+            fields_file fields_upload fields_sign fields_location fields_phone
+            fields_otp fields_captcha fields_rating fields_creditCard
+            fields_stripeToken fields_stripeExternalAccount
             dialogs_alert dialogs_notification
             snackbars_alert snackbars_select
             banners_alert banners_select
           ].freeze
 
           DEFAULT_LOCALIZABLE_KEYS = %w[
-            title subtitle subsubtitle label placeholder text
+            title subtitle subsubtitle label placeholder hint text
             message description uploadText leftText rightText onLabel
           ].freeze
 
           TRANSLATION_METHODS = %i[t translate].freeze
 
+          # Whether `node` is a value this traversal hands to the cop: a
+          # localizable key's value on a watched call, at any hash/array depth,
+          # or a jbuilder positional argument. HardcodedText skips these so one
+          # literal isn't reported by both cops.
+          def self.inspected_value?(node, watched_methods, localizable_keys)
+            parent = node.parent
+            return false unless parent
+
+            if parent.pair_type?
+              localizable_pair_value?(parent, node, localizable_keys) &&
+                watched_call_argument?(parent.parent, watched_methods)
+            elsif parent.call_type?
+              jbuilder_positional_value?(parent, node, localizable_keys)
+            else
+              false
+            end
+          end
+
+          def self.localizable_pair_value?(pair, node, localizable_keys)
+            pair.value.equal?(node) && pair.key.sym_type? && localizable_keys.include?(pair.key.value.to_s)
+          end
+
+          def self.jbuilder_positional_value?(call, node, localizable_keys)
+            call.first_argument.equal?(node) && localizable_keys.include?(call.method_name.to_s) &&
+              json_receiver?(call.receiver)
+          end
+
+          # Climbs out of the nested hashes and arrays `each_localizable` walks
+          # into, then checks the call they are an argument of.
+          def self.watched_call_argument?(container, watched_methods)
+            current = container
+            current = current.parent.pair_type? ? current.parent.parent : current.parent while nested_value?(current)
+            call = current.parent
+            return false unless call&.call_type? && watched_methods.include?(call.method_name.to_s)
+
+            call.arguments.any? { |arg| arg.equal?(current) }
+          end
+
+          def self.nested_value?(node)
+            parent = node.parent
+            return false unless parent
+
+            parent.array_type? || (parent.pair_type? && parent.value.equal?(node))
+          end
+
+          def self.translated_interpolation?(node)
+            node.each_descendant(:send, :csend).any? do |call|
+              TRANSLATION_METHODS.include?(call.method_name)
+            end
+          end
+
+          def self.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 on_send(node)
             node.arguments.each { |arg| each_localizable(arg) } if watched_methods.include?(node.method_name.to_s)
 
@@ -76,7 +138,7 @@ module RuboCop
           # 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)
+            return unless LocalizableProps.json_receiver?(node.receiver)
 
             value = node.first_argument
             return unless value
@@ -84,18 +146,6 @@ module RuboCop
             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

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

@@ -14,12 +14,13 @@ module RuboCop
         #
         # 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.
+        # form (`json.title '...'`) are all checked. Plain strings with no
+        # letters (blank, `'0'`, `'2025'`, `'%'`, `'-'`) are ignored — there is
+        # nothing in them to translate. An interpolated string is flagged even
+        # then: its literal portions are hardcoded copy (`"Hi #{name}"`) or a
+        # format that can differ by locale (`"#{n}%"`, `"#{a}, #{b}"`) —
+        # 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:`.
@@ -73,20 +74,15 @@ module RuboCop
             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.
+          # A plain string literal is hardcoded copy when it has a letter. 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 !LocalizableProps.translated_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
+            node.value.match?(/\p{L}/)
           end
         end
       end

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

@@ -0,0 +1,94 @@
+module RuboCop
+  module Cop
+    module DevDoc
+      module I18n
+        # Decides whether a string literal's text reads like prose (copy a user
+        # could see) or like an identifier (a key, CSS class list, path, URL,
+        # constant, inline CSS, SQL or format string). Used by
+        # `DevDoc/I18n/HardcodedText`.
+        #
+        # Interpolations (`#{...}`) and format directives (`%<x>s`, `%{x}`,
+        # `%Y`) are replaced by PLACEHOLDER before judging: each counts as one
+        # word toward "two or more words" but contributes no letters, so
+        # `"#{n} items"` is prose while `"#{a}. #{b}"` and `"badge--#{x}"` are
+        # not.
+        module TextShape
+          PLACEHOLDER = "␀".freeze
+
+          FORMAT_DIRECTIVE = /%(?:<\w+>[a-z]|\{\w+\}|[-_0^#]?[a-zA-Z])/
+          HTML_TAG = %r{</?[a-zA-Z][^<>]*>}
+          HTML_ENTITY = /&#?\w+;/
+
+          LITERAL_WORD = /\p{L}{2,}/
+          NON_ASCII_LETTER = /(?=\p{L})[^\p{ASCII}]/
+          WORDISH = /\p{L}|␀/
+          CAPITALISED_WORD = /\A\p{Lu}\p{Ll}[\p{Ll}'’]*[.!?:…]?\z/
+
+          URL = %r{\A(?:[a-z][a-z0-9+.-]*://|mailto:|tel:|www\.)\S*\z}i
+          PATH = %r{\A[^\s/]*/\S*\z}
+          EMAIL = /\A[^\s@]+@[^\s@]+\z/
+          # Tailwind arbitrary values (`bg-[#0A2A9E]`) may hold uppercase hex,
+          # and `!` marks an important modifier at either end (`!px-4`, `px-4!`).
+          IDENTIFIER_TOKEN = %r{\A!?(?:[a-z0-9_.:\-\[\]#/?=&*␀]|-\[[^\]\s]*\])+!?\z}
+          IDENTIFIER_SEPARATOR = %r{[-_./:#]}
+          CONSTANT_PATH = /\A[A-Z]\w*(?:::[A-Z]\w*)+\z/
+          SCREAMING_TOKEN = /\A[A-Z0-9_\-␀]+\z/
+          CAMEL_CASE_TOKEN = /\A(?:[a-z]+|[A-Z][a-z0-9]+)(?:[A-Z][a-z0-9]*)+\z/
+          SINGLE_TOKEN_NON_TEXT = [
+            URL, PATH, EMAIL, IDENTIFIER_TOKEN, CONSTANT_PATH, SCREAMING_TOKEN, CAMEL_CASE_TOKEN
+          ].freeze
+
+          CSS_DECLARATIONS = /\A(?:\s*[a-z-]+\s*:\s*[^;:]+;)+\s*(?:[a-z-]+\s*:\s*[^;:]+)?\s*\z/
+          SQL = /
+            \b(?:SELECT|INSERT\s+INTO|DELETE\s+FROM|WHERE|JOIN|COALESCE|ILIKE|ORDER\s+BY|GROUP\s+BY|
+            IS\s+(?:NOT\s+)?NULL|CASE\s+WHEN|ASC|DESC)\b
+            | (?:=|<>|!=|>=|<=|\bLIKE|\bIN)\s*\(?\s*(?:\?|:\w)
+            | ->>?
+            | \b(?:COUNT|SUM|AVG|MIN|MAX|CAST|DATE|DATE_DIFF|DATE_TRUNC|FORMAT_DATE|EXTRACT|NULLIF)\(
+            | (?:\)|\b[a-z0-9_]\w*)\s+AS\s+(?:[a-z_]\w*|␀)
+            | \b(?:AND|OR)\s+\(?\s*[a-z_][\w.]*\s*(?:[=<>!]|\b(?:IS|IN|LIKE|ILIKE|BETWEEN)\b)
+          /x
+
+          module_function
+
+          def prose?(raw)
+            text = normalize(raw)
+            return false unless text.match?(LITERAL_WORD) || text.match?(NON_ASCII_LETTER)
+            return false if non_text?(text)
+
+            tokens = text.split
+            return tokens.count { |token| token.match?(WORDISH) } >= 2 if tokens.size >= 2
+
+            text.match?(CAPITALISED_WORD) || text.match?(NON_ASCII_LETTER)
+          end
+
+          def normalize(raw)
+            raw.gsub(FORMAT_DIRECTIVE, PLACEHOLDER)
+               .gsub(HTML_TAG, ' ')
+               .gsub(HTML_ENTITY, ' ')
+               .strip
+          end
+
+          def non_text?(text)
+            return true if text.match?(SQL)
+            return true if text.match?(CSS_DECLARATIONS) && (text.include?(';') || text.match?(/\A[a-z]+-[a-z]/))
+
+            tokens = text.split
+            return SINGLE_TOKEN_NON_TEXT.any? { |pattern| text.match?(pattern) } if tokens.size == 1
+
+            identifier_list?(tokens)
+          end
+
+          # A CSS class list or similar: every token lowercase and
+          # identifier-shaped, at least one with a separator (`card card--active`).
+          # A plain lowercase phrase (`not yet submitted`) has no separator and
+          # stays prose.
+          def identifier_list?(tokens)
+            tokens.all? { |token| token.match?(IDENTIFIER_TOKEN) } &&
+              tokens.any? { |token| token.match?(IDENTIFIER_SEPARATOR) }
+          end
+        end
+      end
+    end
+  end
+end