rubocop-dev_doc 0.16.0 → 0.18.0

data/lib/dev_doc/test/lints/domain_class_base.rb

@@ -0,0 +1,138 @@
+require 'pathname'
+
+module DevDoc
+  module Test
+    module Lints
+      # Runtime check: every CLASS defined by a file under `app/models/`
+      # (excluding `concerns/`) must descend from one of the project's domain
+      # base classes. Runs with the app loaded, so real ancestry is checked —
+      # intermediate family bases and indirect inheritance resolve correctly,
+      # which is exactly what a per-file static cop cannot do.
+      #
+      # Wrapped by the Minitest module `DomainClassBase` below — see that
+      # module for the rationale.
+      class DomainClassBaseChecker
+        # The three-way rule (best_practices/backend/en/03_model.md item 9):
+        # persisted -> ApplicationRecord; table-less but form-backed ->
+        # ApplicationModel; plain domain logic -> PlainModel.
+        DEFAULT_BASE_CLASS_NAMES = %w[ApplicationRecord ApplicationModel PlainModel].freeze
+
+        def initialize(project_root, base_class_names: DEFAULT_BASE_CLASS_NAMES, allowed_paths: [])
+          @project_root = Pathname(project_root)
+          @base_class_names = base_class_names
+          @allowed_paths = allowed_paths
+        end
+
+        # Returns an Array<String> of offender descriptions, or `[]` when
+        # every model class descends from an allowed base. Modules are skipped:
+        # the three-way rule classifies CLASSES — namespaces, function-bag
+        # modules, and concerns carry no instance state to classify.
+        def offenders
+          bases = @base_class_names.map(&:constantize)
+
+          model_files.filter_map do |path|
+            constant = constant_for(path)
+            next if constant.nil? # module or namespace-only file
+            next if bases.any? { |base| constant <= base }
+
+            "  #{relative(path)}: #{constant.name} < #{constant.superclass.name} — #{hint_for(constant)}"
+          end
+        end
+
+        private
+
+        def model_files
+          Dir.glob(@project_root.join('app/models/**/*.rb')).reject do |path|
+            relative = relative(path)
+            relative.start_with?('app/models/concerns/') ||
+              @allowed_paths.any? { |allowed| relative.start_with?(allowed) }
+          end
+        end
+
+        # Zeitwerk guarantees the file defines the constant its path names, so
+        # deriving it from the path (rather than parsing the source) is exact,
+        # and nested helper classes (e.g. error classes inside a model) are
+        # never enumerated.
+        def constant_for(path)
+          name = relative(path).delete_prefix('app/models/').delete_suffix('.rb').camelize
+          constant = name.constantize
+          constant.is_a?(Class) ? constant : nil
+        end
+
+        def hint_for(constant)
+          if constant.include?(ActiveModel::Model)
+            'it includes ActiveModel::Model, so inherit ApplicationModel instead'
+          else
+            'inherit PlainModel (or ApplicationRecord/ApplicationModel if it persists or backs a form)'
+          end
+        end
+
+        def relative(path)
+          Pathname(path).relative_path_from(@project_root).to_s
+        end
+      end
+
+      # Domain-class base tripwire: every class under `app/models/` must be one
+      # of the project's three kinds — persisted (ApplicationRecord),
+      # form-backed (ApplicationModel), or plain domain logic (PlainModel).
+      #
+      # ## Rationale
+      # The three-way rule (backend/03_model.md item 9) makes the author
+      # classify each domain class at creation time; the base's docstring then
+      # states the contract that kind carries. Static analysis cannot enforce
+      # totality — RuboCop sees one file at a time, so it cannot resolve
+      # whether `class Foo < SomeFamilyBase` ultimately reaches an allowed
+      # base. This lint checks real ancestry with the app loaded, so
+      # intermediate bases resolve and the rule is enforced literally.
+      # `Rails/ApplicationRecord` and `DevDoc/Rails/ApplicationModelBase`
+      # remain useful beside it for editor-time feedback on the two common
+      # direct mistakes.
+      #
+      # NOTE: Limitations:
+      # - Only classes whose files live under `app/models/` are checked; a
+      #   domain class parked elsewhere is invisible (placement itself is the
+      #   orchestration taxonomy's reviewer-owned residual).
+      # - Modules are skipped by design (namespaces, function-bag modules,
+      #   concerns) — the rule classifies classes.
+      #
+      # ## Usage
+      # Include this module in a Minitest test class (Rails test env) in a
+      # project whose three bases exist. Override the constants on the test
+      # class to rename bases or exempt a sanctioned file:
+      #
+      #   class DomainClassBaseTest < ActiveSupport::TestCase
+      #     include DevDoc::Test::Lints::DomainClassBase
+      #     # DOMAIN_BASE_CLASS_NAMES = %w[ApplicationRecord ApplicationModel PlainModel].freeze
+      #     # ALLOWED_DOMAIN_CLASS_PATHS = %w[app/models/legacy/].freeze
+      #   end
+      module DomainClassBase
+        # Defaults. Per-project override: redefine the constants on the test
+        # class that includes this module.
+        DOMAIN_BASE_CLASS_NAMES = DomainClassBaseChecker::DEFAULT_BASE_CLASS_NAMES
+        ALLOWED_DOMAIN_CLASS_PATHS = [].freeze
+
+        def test_every_model_class_descends_from_a_domain_base
+          offenders = DomainClassBaseChecker.new(
+            Rails.root,
+            base_class_names: self.class::DOMAIN_BASE_CLASS_NAMES,
+            allowed_paths: self.class::ALLOWED_DOMAIN_CLASS_PATHS
+          ).offenders
+
+          assert offenders.empty?, domain_class_base_message(offenders)
+        end
+
+        private
+
+        def domain_class_base_message(offenders)
+          "Classes under app/models must descend from one of " \
+            "#{self.class::DOMAIN_BASE_CLASS_NAMES.join(' / ')} — the three-way rule " \
+            "(backend/03_model.md item 9): persisted -> ApplicationRecord, form-backed " \
+            "-> ApplicationModel, plain domain logic -> PlainModel. If a class is a " \
+            "sanctioned exception, add its path to ALLOWED_DOMAIN_CLASS_PATHS on the " \
+            "including test class with a comment.\n\n" \
+            "Offenders:\n#{offenders.join("\n")}"
+        end
+      end
+    end
+  end
+end

data/lib/dev_doc/test/lints/http_driven_controller_tests.rb

@@ -103,6 +103,8 @@ module DevDoc
         def __dev_doc_source_file
           method(name).source_location&.first
         rescue NameError
+          # silent-rescue: an unresolvable test-method name means the source
+          # file is unknown; the location line renders without it.
           nil
         end
 

data/lib/dev_doc/test/pseudo_i18n_crawler.rb

@@ -123,6 +123,8 @@ module DevDoc
         def parse_json(body)
           JSON.parse(body)
         rescue JSON::ParserError
+          # silent-rescue: non-JSON bodies are expected here — scan_body only
+          # wants the parseable ones and skips the rest.
           nil
         end
 
@@ -170,6 +172,9 @@ module DevDoc
             data = YAML.safe_load_file(file, permitted_classes: [Date, Time], aliases: true)
             collect_strings(data, set)
           rescue Psych::Exception
+            # silent-rescue: an unparsable fixture is skipped; its strings
+            # then count as noise candidates instead of exclusions, which
+            # shows up in the report rather than hiding anything.
             next
           end
         end

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