rubocop-dev_doc 0.10.2 → 0.10.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6516cd758b54f702561cfd1ce43130ccf46bcfd04d8955bbdf065218019f374a
-  data.tar.gz: f246347aeb2054e19c26844f38057f795a1ee721a30c3c40b8f955d06b6f843a
+  metadata.gz: b11d7c80b04d4ef7ecbff606f3920260773ae1767ffcacab78e99663920ca9d7
+  data.tar.gz: eaae1ebc845ca76bc72a878916d1f096c5495ce16b9238734c823875b0ba2323
 SHA512:
-  metadata.gz: b30977f9056fd77d2a58227e98b2fc6860ad1333a52fb4bb9bf7ea636ab20ebca1ad9187a84a4ca3e14c8f442861ec3c779ddb88d9d940c459483bcf204726e0
-  data.tar.gz: 93ae91781dd10664b18b8e304e9b336485a572bd9a32822af81df3e399fb742420ed1d41612e21e4249eb79cbc53569082468091c8994470f552bf43dd7c7b8d
+  metadata.gz: 0c227078e2a29302744d3b14cd3058f5912b50831221b82d7ab8cb13885ffaf4bca0eb7e8784745bd470533190e6c522d3f69b28f7e64cc18f183d2a39d6dd19
+  data.tar.gz: b7f474e88689ce7bd672e735458b5b8e45c5c47448b44461b673a46b8ac4b74c997ccebf548b02b33460095214c2d6920211ffb621a82eca3e231d8f65898f4d

data/lib/dev_doc/i18n/pseudo_locale.rb

@@ -0,0 +1,168 @@
+# Pseudo-localization backend — a hardcoded-text detector.
+#
+# When installed (see PseudoLocale.install!), an extra locale `en-PSEUDO`
+# becomes available. Every string resolved through Rails `t()` is returned as
+# its real English value, accented and wrapped in `⟦ ⟧` markers, e.g.
+#
+#     t('energies.show.title')  # "Monthly Statement"
+#       --> rendered under en-PSEUDO -->  "⟦Móñţĥļý Šţáţéméñţ⟧"
+#
+# Render any page under the pseudo locale and scan the output: any user-facing
+# text WITHOUT the `⟦ ⟧` markers never went through `t()` and is therefore a
+# hardcoded-string candidate — regardless of whether it came from a view,
+# helper, concern, module, or service object.
+#
+# ---------------------------------------------------------------------------
+# Per-project integration
+# ---------------------------------------------------------------------------
+# This gem is a `:development, :test`-only dependency, so it is NOT loaded in
+# production and this file is only required when detection mode is on. The
+# project initializer requires it and installs the backend under PSEUDO_I18N=1:
+#
+#   # config/initializers/pseudo_locale.rb
+#   if ENV['PSEUDO_I18N'] == '1'
+#     require 'dev_doc/i18n/pseudo_locale'
+#     DevDoc::I18n::PseudoLocale.install!
+#   end
+#
+# `mark` (below) is called from production code paths to flag externally-managed
+# strings for the scanner. Because this gem is absent in production, call it
+# through a null-guard so it degrades to the identity when the gem is not
+# loaded — the value is untouched anyway when detection mode is off:
+#
+#   def pseudo_mark(value)
+#     return value unless defined?(DevDoc::I18n::PseudoLocale)
+#     DevDoc::I18n::PseudoLocale.mark(value)
+#   end
+#
+# Guarded behind PSEUDO_I18N, so normal dev/prod is untouched and the fake
+# locale can never leak to real users.
+module DevDoc
+  module I18n
+    module PseudoLocale
+      PSEUDO_LOCALE = 'en-PSEUDO'
+      MARKER = '⟦'
+
+      def self.active?
+        ENV['PSEUDO_I18N'] == '1'
+      end
+
+      # Marks an externally-managed string — CMS content, assessment-YAML
+      # values, or a chosen ActiveRecord display value — so the hardcoded-text
+      # scanner treats it as already-handled and skips it. Returns the string
+      # untouched when detection mode is off, so it is safe on production paths
+      # (call it through a null-guard; see the header comment).
+      def self.mark(value)
+        return value unless active?
+        return value unless value.is_a?(String) && !value.empty?
+
+        value.include?(MARKER) ? value : "#{MARKER}#{value}⟧"
+      end
+
+      # Letter map — readable but unmistakably "transformed".
+      MAP = {
+        'a' => 'á', 'b' => 'ƀ', 'c' => 'ç', 'd' => 'ð', 'e' => 'é', 'f' => 'ƒ',
+        'g' => 'ĝ', 'h' => 'ĥ', 'i' => 'í', 'j' => 'ĵ', 'k' => 'ķ', 'l' => 'ļ',
+        'm' => 'ɱ', 'n' => 'ñ', 'o' => 'ö', 'p' => 'þ', 'q' => 'ɋ', 'r' => 'ŕ',
+        's' => 'š', 't' => 'ţ', 'u' => 'ü', 'v' => 'ṽ', 'w' => 'ŵ', 'x' => 'ӿ',
+        'y' => 'ý', 'z' => 'ž',
+        'A' => 'Á', 'B' => 'Ɓ', 'C' => 'Ç', 'D' => 'Ð', 'E' => 'É', 'F' => 'Ƒ',
+        'G' => 'Ĝ', 'H' => 'Ĥ', 'I' => 'Í', 'J' => 'Ĵ', 'K' => 'Ķ', 'L' => 'Ļ',
+        'M' => 'Ṁ', 'N' => 'Ñ', 'O' => 'Ö', 'P' => 'Þ', 'Q' => 'Ɋ', 'R' => 'Ŕ',
+        'S' => 'Š', 'T' => 'Ţ', 'U' => 'Ü', 'V' => 'Ṽ', 'W' => 'Ŵ', 'X' => 'Ӿ',
+        'Y' => 'Ý', 'Z' => 'Ž'
+      }.freeze
+
+      # Wires the pseudo backend into I18n and forces every request to render in
+      # it. Idempotent — safe to call once from the project initializer.
+      def self.install!
+        ::I18n::Backend::Simple.prepend(Backend)
+        ::I18n.available_locales |= [PSEUDO_LOCALE.to_sym]
+        force_locale!
+        ::Rails.logger.info('[pseudo_locale] en-PSEUDO locale enabled (forced) for hardcoded-text detection') if defined?(::Rails.logger)
+      end
+
+      # Force every request to render in the pseudo locale.
+      #
+      # Without this, an app's `default_url_options` typically derives the URL
+      # locale via `I18n.locale.to_s.split('-')[0]` ("en-PSEUDO" -> "en"), so
+      # every link and redirect the app generates carries `locale=en`;
+      # `set_locale` then honours that param and renders plain English — the
+      # pseudo transform never fires on any navigated page. Overriding
+      # `set_locale` here pins the locale regardless of the incoming param,
+      # which is exactly what a "render everything pseudo" detection mode wants.
+      def self.force_locale!
+        ::Rails.application.config.to_prepare do
+          ApplicationController.class_eval do
+            private
+
+            def set_locale
+              ::I18n.locale = DevDoc::I18n::PseudoLocale::PSEUDO_LOCALE.to_sym
+            end
+          end
+        end
+      end
+
+      # I18n backend override: resolves the real English entry, then accents it.
+      module Backend
+        # Namespaces whose values are format directives / structural data, not
+        # copy. Accenting these would corrupt strftime (`%A`), number formats.
+        SKIP_NAMESPACES = %w[i18n date time datetime number support].freeze
+
+        def lookup(locale, key, scope = [], options = ::I18n::EMPTY_HASH)
+          return super unless locale.to_s == PSEUDO_LOCALE
+
+          # Resolve the real English entry (template, before interpolation).
+          real = super(:en, key, scope, options)
+          return real if real.nil? || skip?(key, scope)
+
+          pseudoize(real)
+        end
+
+        private
+
+        def skip?(key, scope)
+          head = Array(scope).first || key.to_s[/\A[^.]+/]
+          SKIP_NAMESPACES.include?(head.to_s)
+        end
+
+        # Recurses so pluralization hashes ({ one:, other: }) and arrays work.
+        def pseudoize(value)
+          case value
+          when String then wrap(value)
+          when Hash   then value.transform_values { |v| pseudoize(v) }
+          when Array  then value.map { |v| pseudoize(v) }
+          else value
+          end
+        end
+
+        # Some t() values are not display copy — asset filenames, paths, URLs.
+        # The asset helpers feed these to Vite, which raises on a missing
+        # manifest entry, so accenting them 500s the page. Leave them untouched.
+        #
+        # Note: do NOT treat a bare "/" as a path — display copy legitimately
+        # contains slashes ("Lamp/Bulbs", "Food/Food Scraps"). A real path is an
+        # all-lowercase identifier chain (`shared/layouts/main`, `images/icon`);
+        # copy has capitals or spaces, so it won't match the lowercase-path rule.
+        NON_COPY = %r{
+          \A\s*\z                              # blank
+          | \Ahttps?://                        # url
+          | \A[a-z0-9_]+(?:[/.][a-z0-9_]+)+\z  # lowercase path / dotted id (shared/layouts/main)
+        }x
+
+        ASSET_EXT = /\.(?:png|jpe?g|svg|gif|webp|ico|bmp|css|js|mjs|html?|pdf|woff2?|ttf|otf|mp[34]|json|xml|csv)\z/i
+
+        def wrap(str)
+          return str if str.match?(NON_COPY) || str.match?(ASSET_EXT)
+
+          # Split on %{name} placeholders (captured), accent only the literal
+          # segments so interpolation variables and their data stay intact.
+          body = str.split(/(%\{[^}]+\})/).each_with_index.map do |part, i|
+            i.odd? ? part : part.chars.map { |c| MAP[c] || c }.join
+          end.join
+          "⟦#{body}⟧"
+        end
+      end
+    end
+  end
+end

data/lib/dev_doc/test/pseudo_i18n_crawler.rb

@@ -0,0 +1,254 @@
+require 'set'
+
+module DevDoc
+  module Test
+    # Pseudo-localization hardcoded-text crawler.
+    #
+    # Reuses the glib-web JSON-UI crawler (per-role login + fixtures + full
+    # reachability) but renders every page under the `en-PSEUDO` locale and
+    # reports any localizable text prop that comes back WITHOUT the `⟦ ⟧`
+    # marker — i.e. user-facing text that bypassed Rails `t()` and is therefore
+    # a hardcoded-string candidate, no matter which view/helper/concern/module/
+    # service emitted it. See dev_doc/i18n/pseudo_locale.rb.
+    #
+    # Unlike the golden-file JSON-UI crawler this does NOT assert the page log
+    # (the accented pseudo output would never match committed baselines); it
+    # drives the router directly and only collects unwrapped text.
+    #
+    # ------------------------------------------------------------------------
+    # Per-project integration
+    # ------------------------------------------------------------------------
+    # Include this module in a single integration test and supply the project's
+    # own login credentials as `test` cases. The host class must also include
+    # `Glib::TestHelpers` (for HOST / login / logout) and load fixtures. The
+    # pseudo backend must be installed — see dev_doc/i18n/pseudo_locale.rb.
+    #
+    #   # test/integration/pseudo_i18n_crawler_test.rb
+    #   require 'test_helper'
+    #   require 'dev_doc/test/pseudo_i18n_crawler'
+    #
+    #   class PseudoI18nCrawlerTest < ActionDispatch::IntegrationTest
+    #     include Glib::TestHelpers
+    #     include DevDoc::Test::PseudoI18nCrawler
+    #
+    #     self.fixture_paths = ['test/fixtures']
+    #     fixtures :all
+    #
+    #     test 'crawl superadmin' do
+    #       crawl_pseudo(email: 'super@admin.com', password: 'password', device: 'web', version: nil)
+    #     end
+    #   end
+    #
+    # Run with the pseudo backend enabled:
+    #
+    #   PSEUDO_I18N=1 bin/rails test test/integration/pseudo_i18n_crawler_test.rb
+    #
+    # Findings are printed and written to
+    # test/integration/pseudo_i18n_crawler_test_results/<email>.txt
+    module PseudoI18nCrawler
+      MARKER = '⟦'.freeze
+
+      # Mirrors the cop's DEFAULT_LOCALIZABLE_KEYS — keep in sync with
+      # lib/rubocop/cop/dev_doc/i18n/localizable_props.rb. The crawler can only
+      # flag hardcoded text on keys it walks, so any key the cop treats as
+      # localizable (message/description on dialogs & banners, uploadText on
+      # fields_upload, on/left/rightText on switch & toggles) must be listed.
+      TEXT_KEYS = %w[
+        title
+        subtitle
+        subsubtitle
+        label
+        placeholder
+        text
+        message
+        description
+        uploadText
+        leftText
+        rightText
+        onLabel
+      ].to_set
+
+      # The test class that included the module — the prepended Scanner (a
+      # single module shared across the Http class) dispatches scan results
+      # back to it.
+      class << self
+        attr_accessor :host_class
+      end
+
+      # Scan every crawled JSON-UI response as it is fetched.
+      module Scanner
+        # Signature must mirror Glib::JsonCrawler::Http#fetch for the
+        # prepend/super override to work, so the boolean positional arg can't
+        # become a kwarg.
+        def fetch(method, url, action, params = {}, inspect_result = true) # rubocop:disable Style/OptionalBooleanParameter
+          result = super
+          if method == :get
+            rec = instance_variable_get(:@content_history)&.last
+            PseudoI18nCrawler.host_class.scan_body(url, rec[:response]) if rec && rec[:url] == url
+          end
+          result
+        end
+      end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+        PseudoI18nCrawler.host_class = base
+
+        # Prepend the Scanner onto the crawler HTTP client exactly once, no
+        # matter how many test classes include the module.
+        unless Glib::JsonCrawler::Http.ancestors.include?(Scanner)
+          Glib::JsonCrawler::Http.prepend(Scanner)
+        end
+
+        base.setup do
+          skip 'Set PSEUDO_I18N=1 to run the pseudo-localization scan.' unless ENV['PSEUDO_I18N'] == '1'
+          skip 'en-PSEUDO locale not loaded — is config/initializers/pseudo_locale.rb active?' unless ::I18n.available_locales.include?(:'en-PSEUDO')
+
+          self.class.hits = {}
+          @previous_default_locale = ::I18n.default_locale
+          # The app's set_locale falls back to I18n.default_locale when no
+          # `_lang` param is present (crawler URLs carry none), so this renders
+          # every page in pseudo without touching the crawler's URLs.
+          ::I18n.default_locale = :'en-PSEUDO'
+        end
+
+        base.teardown do
+          ::I18n.default_locale = @previous_default_locale if @previous_default_locale
+        end
+      end
+
+      module ClassMethods
+        attr_accessor :hits # { url => [ "[key] value", ... ] }
+
+        # Directory of the fixtures scanned to filter out AR display values.
+        def fixture_dir
+          @fixture_dir ||= ::Rails.root.join('test/fixtures').to_s
+        end
+
+        # Where per-role reports are written.
+        def report_dir
+          @report_dir ||= ::Rails.root.join('test/integration/pseudo_i18n_crawler_test_results').to_s
+        end
+
+        def scan_body(url, body)
+          return unless body.is_a?(String) && body.lstrip.start_with?('{', '[')
+
+          json = begin
+            JSON.parse(body)
+          rescue JSON::ParserError
+            return
+          end
+
+          walk(json) do |key, value|
+            if value.include?(MARKER)
+              @wrapped = (@wrapped || 0) + 1
+            elsif trivial?(value)
+              next
+            elsif fixture_strings.include?(value.strip)
+              # ActiveRecord display value (record title/name/user copy) that
+              # came straight from the DB — data, not a hardcoded UI string.
+              @data_sourced = (@data_sourced || 0) + 1
+            else
+              @unwrapped = (@unwrapped || 0) + 1
+              (hits[url] ||= []) << "[#{key}] #{value.inspect}"
+            end
+          end
+        end
+
+        # Verbatim string values from the fixtures. A candidate equal to one of
+        # these is an ActiveRecord display value (loaded from the DB, so it
+        # never went through t() by design) rather than hardcoded copy, and is
+        # excluded to cut the bulk of the AR noise. Exact match only — a
+        # hardcoded string that happens to equal a fixture value would be
+        # skipped too, an acceptable trade for ~85% less noise. Built once;
+        # fixtures contain no ERB so static YAML parsing is exact.
+        def fixture_strings
+          @fixture_strings ||= Dir[File.join(fixture_dir, '**', '*.yml')].each_with_object(Set.new) do |file, set|
+            data = YAML.safe_load(File.read(file), permitted_classes: [Date, Time], aliases: true)
+            collect_strings(data, set)
+          rescue Psych::Exception
+            next
+          end
+        end
+
+        def collect_strings(node, set)
+          case node
+          when Hash  then node.each_value { |v| collect_strings(v, set) }
+          when Array then node.each { |v| collect_strings(v, set) }
+          when String
+            s = node.strip
+            set << s unless s.empty?
+          end
+        end
+
+        def diag
+          "wrapped(localized via t)=#{@wrapped || 0}  data-sourced(fixtures, skipped)=#{@data_sourced || 0}  " \
+            "unwrapped(candidates)=#{@unwrapped || 0}"
+        end
+
+        def walk(node, &blk)
+          case node
+          when Hash
+            node.each do |k, v|
+              blk.call(k, v) if TEXT_KEYS.include?(k) && v.is_a?(String)
+              walk(v, &blk)
+            end
+          when Array
+            node.each { |v| walk(v, &blk) }
+          end
+        end
+
+        # Skip values that are not copy: blank, no letters (numbers/units/
+        # symbols), or ALL_CAPS code identifiers. Tune as real noise surfaces.
+        def trivial?(str)
+          s = str.strip
+          s.empty? || !s.match?(/[A-Za-z]/) || s.match?(/\A[A-Z0-9_]+\z/)
+        end
+      end
+
+      private
+
+      def crawl_pseudo(user)
+        user[:token] = login(user)
+
+        router = Glib::JsonCrawler::Router.new
+        http   = Glib::JsonCrawler::Http.new(self, user, router, inspect_result: true)
+        router.host = HOST
+        router.skip_similar_page = true
+
+        ENV['CRAWLER_MODE'] = 'true'
+        router.step(
+          http,
+          'onClick' => {
+            'action' => 'initiate_navigation',
+            'url' => "http://#{HOST}/users/me?format=json&redirect=default"
+          }
+        )
+      ensure
+        ENV['CRAWLER_MODE'] = nil
+        logout
+        report!(user)
+      end
+
+      def report!(user)
+        hits = self.class.hits
+        report_dir = self.class.report_dir
+        FileUtils.mkdir_p(report_dir)
+        path = File.join(report_dir, "#{user[:email]}.txt")
+
+        lines = []
+        hits.sort.each do |url, values|
+          lines << url
+          values.uniq.each { |v| lines << "    #{v}" }
+          lines << ''
+        end
+        total = hits.values.sum { |v| v.uniq.size }
+        summary = "#{total} hardcoded candidate(s) across #{hits.size} page(s) for #{user[:email]}"
+
+        File.write(path, ([summary, ''] + lines).join("\n"))
+        puts "\n[pseudo_i18n] #{summary}\n              report: #{path}"
+        puts "[pseudo_i18n] DIAG: #{self.class.diag}"
+      end
+    end
+  end
+end

data/lib/rubocop/dev_doc/version.rb

@@ -1,5 +1,5 @@
 module RuboCop
   module DevDoc
-    VERSION = "0.10.2".freeze
+    VERSION = "0.10.4".freeze
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubocop-dev_doc
 version: !ruby/object:Gem::Version
-  version: 0.10.2
+  version: 0.10.4
 platform: ruby
 authors:
 - dev-doc contributors
@@ -88,11 +88,13 @@ extra_rdoc_files: []
 files:
 - config/default.yml
 - config/obsoletion.yml
+- lib/dev_doc/i18n/pseudo_locale.rb
 - lib/dev_doc/test/best_practice_lints.rb
 - lib/dev_doc/test/lints/cron_schedule.rb
 - lib/dev_doc/test/lints/duplicate_snapshot.rb
 - lib/dev_doc/test/lints/http_driven_controller_tests.rb
 - lib/dev_doc/test/lints/no_file_excludes.rb
+- lib/dev_doc/test/pseudo_i18n_crawler.rb
 - 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