rigortype 0.1.10 → 0.1.12

data/plugins/rigor-rails-i18n/lib/rigor/plugin/rails_i18n/analyzer.rb

@@ -0,0 +1,353 @@
+# frozen_string_literal: true
+
+require "did_you_mean"
+require "prism"
+
+module Rigor
+  module Plugin
+    class RailsI18n < Rigor::Plugin::Base
+      # Walks a parsed file's AST looking for `t(...)` /
+      # `I18n.t(...)` / `I18n.translate(...)` calls with a
+      # literal-string first argument. Calls with a non-literal
+      # key (variable, expression) are silently passed through —
+      # the plugin only validates what it can prove statically.
+      #
+      # ## What gets emitted per recognised call
+      #
+      # - `plugin.rails-i18n.translation-call` (info) names the
+      #   key and the locales it resolves in.
+      # - `plugin.rails-i18n.unknown-key` (error) when the key
+      #   is missing from every loaded locale; the message
+      #   includes a did-you-mean suggestion drawn from the
+      #   index.
+      # - `plugin.rails-i18n.missing-locale` (warning) when the
+      #   key resolves in some configured locales but is absent
+      #   from at least one. Suppressed when the call passes
+      #   `default:` (the user has signalled they're aware of
+      #   the partial coverage).
+      # - `plugin.rails-i18n.wrong-interpolation` (error) when
+      #   the call's interpolation hash uses keys that don't
+      #   match the value's `%{var}` placeholders, or omits a
+      #   required placeholder.
+      module Analyzer
+        TRANSLATE_METHODS = %i[t translate].freeze
+
+        # Methods that are always I18n receivers (`I18n.t`,
+        # `::I18n.t`).
+        I18N_RECEIVER_NAMES = %w[I18n ::I18n].freeze
+
+        # Matches controller file paths so lazy keys (`.key`)
+        # can be expanded to `<controller_scope>.<action>.<key>`.
+        # Captures the path segment between `controllers/` and
+        # `_controller.rb` (e.g. `users`, `admin/users`).
+        CONTROLLER_PATH_RE = %r{(?:^|/)controllers/(.+)_controller\.rb$}
+
+        # Reserved option keys — these are recognised by I18n
+        # itself and not treated as interpolation variables.
+        RESERVED_OPTION_KEYS = %i[
+          default scope locale count raise throw fallback
+          fallback_in_progress separator deep_interpolation
+        ].to_set.freeze
+
+        # Key prefixes Rails / `rails-i18n` ship in every
+        # locale by default. Projects whose own locale files
+        # don't redeclare them still get them at runtime (via
+        # the `rails-i18n` gem's bundled locale catalogues).
+        # `t('date.order')` is the canonical Mastodon case —
+        # used by `Settings::Date::Order` and date-of-birth
+        # selects, never authored project-side. Skip
+        # `unknown-key` for these; downstream interpolation
+        # checks have nothing to validate without a leaf entry
+        # so they decline silently too.
+        RAILS_SHIPPED_KEY_PREFIXES = %w[
+          date.
+          time.
+          datetime.
+          support.array.
+          errors.format
+          errors.messages.
+          number.
+          helpers.select.
+          helpers.submit.
+          helpers.label.
+          i18n.transliterate.
+          activerecord.errors.messages.
+          activerecord.errors.models.
+        ].freeze
+
+        Diagnostic = Struct.new(:path, :line, :column, :severity, :rule, :message, keyword_init: true)
+
+        module_function
+
+        def rails_shipped_key?(literal_key)
+          key_str = literal_key.to_s
+          RAILS_SHIPPED_KEY_PREFIXES.any? { |prefix| key_str.start_with?(prefix) }
+        end
+
+        # @param path [String]
+        # @param root [Prism::Node]
+        # @param locale_index [LocaleIndex]
+        # @param configured_locales [Array<String>]
+        # @return [Array<Diagnostic>]
+        def diagnose(path:, root:, locale_index:, configured_locales:)
+          controller_scope = controller_scope_from_path(path)
+          diagnostics = []
+          walk(root) do |call_node, action|
+            raw_key = literal_key_for(call_node)
+            next if raw_key.nil?
+
+            literal_key = expand_key(raw_key, controller_scope: controller_scope, action: action)
+            next if literal_key.nil?
+
+            options = options_hash(call_node)
+            entry = locale_index.find(literal_key)
+            if entry.nil?
+              # CLDR pluralization namespace: the parent key isn't
+              # a leaf, but at least one `.one` / `.other` / etc.
+              # child exists. `t('accounts.posts', count: n)`
+              # resolves through that branch — not a missing key.
+              # Accept silently; downstream interpolation checks
+              # don't apply (no single entry to read placeholders
+              # from).
+              next if locale_index.pluralization_namespace?(literal_key)
+
+              # Rails / rails-i18n ship `date.order`, `time.am`,
+              # `support.array.words_connector`, etc. in every
+              # locale at runtime even when the project's own
+              # locale files don't repeat them. Accept silently
+              # — no leaf entry → no downstream interpolation
+              # check to run.
+              next if rails_shipped_key?(literal_key)
+
+              diagnostics << unknown_key_diagnostic(path, call_node, literal_key, locale_index)
+              next
+            end
+
+            diagnostics << translation_call_info(path, call_node, literal_key, entry)
+            missing_in_locales = locale_index.missing_locales_for(literal_key, configured_locales: configured_locales)
+            diagnostics << missing_locale_diagnostic(path, call_node, literal_key, missing_in_locales) \
+              if !options[:has_default] && !missing_in_locales.empty?
+
+            interpolation_diags = interpolation_diagnostics(path, call_node, literal_key, entry, options)
+            diagnostics.concat(interpolation_diags)
+          end
+          diagnostics
+        end
+
+        # Walks the AST yielding `[call_node, action]` pairs where
+        # `action` is the name of the innermost enclosing `def`
+        # method (or `nil` when the call is at the top level).
+        def walk(node, action: nil, &)
+          return unless node.is_a?(Prism::Node)
+
+          current_action = node.is_a?(Prism::DefNode) ? node.name.to_s : action
+          yield node, current_action if node.is_a?(Prism::CallNode) && translate_call_candidate?(node)
+          node.compact_child_nodes.each { |child| walk(child, action: current_action, &) }
+        end
+
+        # Derives the Rails controller scope from the file path,
+        # e.g. `app/controllers/admin/users_controller.rb` → `admin.users`.
+        # Returns nil for non-controller paths.
+        def controller_scope_from_path(path)
+          m = CONTROLLER_PATH_RE.match(path.to_s)
+          return nil unless m
+
+          m[1].tr("/", ".")
+        end
+
+        # Expands a lazy key (starting with `.`) to its full
+        # dotted path using the controller scope and action name.
+        # Returns the raw key unchanged for absolute keys.
+        # Returns nil for lazy keys outside a controller context
+        # or without an enclosing action — these are silently
+        # skipped to avoid false positives.
+        def expand_key(raw_key, controller_scope:, action:)
+          return raw_key unless raw_key.start_with?(".")
+          return nil unless controller_scope && action
+
+          "#{controller_scope}.#{action}#{raw_key}"
+        end
+
+        def translate_call_candidate?(node)
+          return false unless TRANSLATE_METHODS.include?(node.name)
+          return true if node.receiver.nil?
+
+          receiver_name = constant_receiver_name(node.receiver)
+          I18N_RECEIVER_NAMES.include?(receiver_name)
+        end
+
+        # Extracts the literal-string first argument when
+        # present. Returns nil for variable / expression keys —
+        # those are out of scope for v0.1.0.
+        def literal_key_for(call_node)
+          args = call_node.arguments&.arguments || []
+          return nil if args.empty?
+
+          first = args.first
+          return nil unless first.is_a?(Prism::StringNode)
+
+          first.unescaped
+        end
+
+        # Pulls the interpolation hash from the call's
+        # arguments. The trailing `Hash` argument (or
+        # `Prism::KeywordHashNode`) carries both reserved I18n
+        # options (`default:`, `scope:`, …) and interpolation
+        # variables. Returns:
+        #   {
+        #     :has_default     => bool,
+        #     :all_keys        => Set<Symbol>     (every assoc key in the hash),
+        #     :non_reserved    => Set<Symbol>     (keys NOT in RESERVED_OPTION_KEYS),
+        #     :hash_node       => Prism::Node (or nil)
+        #   }
+        #
+        # Note: a reserved option key (e.g. `count:`) can
+        # also serve as an interpolation value when the
+        # locale's leaf string has `%{count}`. The analyzer
+        # therefore checks the missing-placeholder set
+        # against `all_keys` (so `count:` satisfies a
+        # `%{count}` placeholder) and the
+        # extra-placeholder set against `non_reserved` (so
+        # `default:` / `scope:` are never reported as
+        # extra interpolation arguments).
+        def options_hash(call_node)
+          args = call_node.arguments&.arguments || []
+          last = args.last
+          empty = { has_default: false, all_keys: Set.new, non_reserved: Set.new, hash_node: nil }
+          return empty unless hash_like?(last)
+
+          assoc_keys = collect_assoc_keys(last)
+          all_keys = assoc_keys.to_set
+          non_reserved = assoc_keys.reject { |k| RESERVED_OPTION_KEYS.include?(k) }.to_set
+          {
+            has_default: assoc_keys.include?(:default),
+            all_keys: all_keys,
+            non_reserved: non_reserved,
+            hash_node: last
+          }
+        end
+
+        def hash_like?(node)
+          node.is_a?(Prism::HashNode) || node.is_a?(Prism::KeywordHashNode)
+        end
+
+        def collect_assoc_keys(hash_node)
+          # Both `Prism::HashNode` and `Prism::KeywordHashNode`
+          # expose `#elements`; the conditional was an
+          # accidental no-op carried over from an earlier
+          # draft.
+          hash_node.elements.filter_map do |element|
+            next nil unless element.is_a?(Prism::AssocNode)
+
+            key_node = element.key
+            case key_node
+            when Prism::SymbolNode then key_node.unescaped.to_sym
+            when Prism::StringNode then key_node.unescaped.to_sym
+            end
+          end
+        end
+
+        def translation_call_info(path, call_node, literal_key, entry)
+          location = call_node.location
+          locales_text = entry.locales.sort.join(", ")
+          Diagnostic.new(
+            path: path,
+            line: location.start_line,
+            column: location.start_column + 1,
+            severity: :info,
+            rule: "translation-call",
+            message: "`t('#{literal_key}')` resolves in #{locales_text}"
+          )
+        end
+
+        def unknown_key_diagnostic(path, call_node, literal_key, locale_index)
+          location = call_node.location
+          suggestions = DidYouMean::SpellChecker.new(dictionary: locale_index.keys).correct(literal_key)
+          suggestion_part = suggestions.empty? ? "" : " (did you mean `#{suggestions.first}`?)"
+          Diagnostic.new(
+            path: path,
+            line: location.start_line,
+            column: location.start_column + 1,
+            severity: :error,
+            rule: "unknown-key",
+            message: "missing translation key `#{literal_key}` in any locale#{suggestion_part}"
+          )
+        end
+
+        def missing_locale_diagnostic(path, call_node, literal_key, missing_locales)
+          location = call_node.location
+          locales_text = missing_locales.to_a.sort.join(", ")
+          Diagnostic.new(
+            path: path,
+            line: location.start_line,
+            column: location.start_column + 1,
+            severity: :warning,
+            rule: "missing-locale",
+            message: "`t('#{literal_key}')` is missing from locale(s) #{locales_text}"
+          )
+        end
+
+        def interpolation_diagnostics(path, call_node, literal_key, entry, options)
+          required = entry.all_placeholders
+          all_provided = options[:all_keys].to_set(&:to_s)
+          non_reserved_provided = options[:non_reserved].to_set(&:to_s)
+          missing = required - all_provided
+          extra = non_reserved_provided - required
+          location = call_node.location
+
+          [].tap do |diags|
+            unless missing.empty?
+              diags << Diagnostic.new(
+                path: path,
+                line: location.start_line,
+                column: location.start_column + 1,
+                severity: :error,
+                rule: "wrong-interpolation",
+                message: "`t('#{literal_key}')` expects interpolation #{format_keys(missing)}, " \
+                         "got #{format_keys(non_reserved_provided)}"
+              )
+            end
+
+            unless extra.empty?
+              diags << Diagnostic.new(
+                path: path,
+                line: location.start_line,
+                column: location.start_column + 1,
+                severity: :warning,
+                rule: "extra-interpolation",
+                message: "`t('#{literal_key}')` does not use interpolation #{format_keys(extra)} " \
+                         "(known placeholders: #{format_keys(required)})"
+              )
+            end
+          end
+        end
+
+        def format_keys(set)
+          return "(none)" if set.empty?
+
+          set.to_a.sort.map { |k| "`#{k}`" }.join(", ")
+        end
+
+        def constant_receiver_name(node)
+          case node
+          when Prism::ConstantReadNode then node.name.to_s
+          when Prism::ConstantPathNode then constant_path_name(node)
+          end
+        end
+
+        def constant_path_name(node)
+          parts = []
+          current = node
+          while current.is_a?(Prism::ConstantPathNode)
+            parts.unshift(current.name.to_s)
+            current = current.parent
+          end
+          case current
+          when nil then "::#{parts.join('::')}"
+          when Prism::ConstantReadNode then "#{current.name}::#{parts.join('::')}"
+          end
+        end
+      end
+    end
+  end
+end

data/plugins/rigor-rails-i18n/lib/rigor/plugin/rails_i18n/locale_index.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Rigor
+  module Plugin
+    class RailsI18n < Rigor::Plugin::Base
+      # Frozen catalogue of every dotted key discovered across
+      # all loaded locale files. Each entry tracks the locales
+      # the key appears in and, for each locale, the set of
+      # `%{var}` interpolation placeholders observed in the
+      # leaf string.
+      #
+      # The catalogue is intentionally lossy: it only records
+      # the *presence* of each key per locale and the
+      # placeholder names. The actual translated values are
+      # not retained — the analyzer doesn't need them and
+      # keeping them would bloat the cache slice.
+      class LocaleIndex
+        # `placeholders` is a Hash: `locale_name => Set<String>`.
+        # `array_value` is true when at least one locale's leaf
+        # is an Array (used by `l(time, format:)` and similar).
+        # `value_kinds` is a Hash: `locale_name => Symbol`
+        # (`:string` / `:array` / `:hash`).
+        Entry = Data.define(:dotted_key, :placeholders, :value_kinds) do
+          def locales
+            placeholders.keys
+          end
+
+          def in_locale?(locale)
+            placeholders.key?(locale.to_s)
+          end
+
+          def required_placeholders_for(locale)
+            placeholders.fetch(locale.to_s) { Set.new }
+          end
+
+          # Union of placeholder names across all known
+          # locales — used by the analyzer when no specific
+          # locale is in scope.
+          def all_placeholders
+            placeholders.values.reduce(Set.new) { |acc, set| acc | set }
+          end
+        end
+
+        attr_reader :entries, :locales
+
+        # @param entries [Array<Entry>]
+        # @param locales [Array<String>] all locale names
+        #   that contributed at least one key.
+        def initialize(entries, locales:)
+          @entries = entries.freeze
+          @locales = locales.dup.freeze
+          @by_key = entries.to_h { |e| [e.dotted_key, e] }.freeze
+          freeze
+        end
+
+        # @return [Entry, nil]
+        def find(dotted_key)
+          @by_key[dotted_key.to_s]
+        end
+
+        def known?(dotted_key)
+          @by_key.key?(dotted_key.to_s)
+        end
+
+        # CLDR plural form keys recognised by Ruby I18n. When a
+        # locale defines `accounts.posts.one`, `accounts.posts.other`,
+        # the call `t('accounts.posts', count: n)` resolves into
+        # the matching plural sub-key — the parent `accounts.posts`
+        # is a **pluralization namespace**, not a missing key.
+        # Mastodon hits this on `accounts.posts` /
+        # `accounts.following` / `accounts.followers` for the post,
+        # follow, and follower counts shown on the profile page.
+        PLURAL_SUBKEYS = %w[zero one two few many other].freeze
+
+        # Returns true when the dotted key itself isn't a leaf in
+        # any locale, but at least one of its CLDR plural form
+        # children exists.
+        def pluralization_namespace?(dotted_key)
+          base = dotted_key.to_s
+          PLURAL_SUBKEYS.any? { |sub| @by_key.key?("#{base}.#{sub}") }
+        end
+
+        def empty?
+          @entries.empty?
+        end
+
+        def size
+          @entries.size
+        end
+
+        # All known dotted keys, sorted for stable did-you-mean
+        # output.
+        def keys
+          @by_key.keys.sort
+        end
+
+        # Returns the locales (set of strings) in which a key
+        # is *missing*, given the configured locale list.
+        def missing_locales_for(dotted_key, configured_locales:)
+          entry = find(dotted_key)
+          return configured_locales.to_set if entry.nil?
+
+          configured_locales.to_set - entry.locales.to_set
+        end
+      end
+    end
+  end
+end

data/plugins/rigor-rails-i18n/lib/rigor/plugin/rails_i18n/locale_loader.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+require_relative "locale_index"
+
+module Rigor
+  module Plugin
+    class RailsI18n < Rigor::Plugin::Base
+      # Walks `locale_search_paths` for `.yml` / `.yaml`
+      # files, reads each through the trusted IoBoundary,
+      # parses with `YAML.safe_load`, and folds the resulting
+      # nested hash into a flat `dotted_key => Entry` table.
+      #
+      # The top-level YAML key is the locale (`en:`, `ja:`,
+      # …). Anything underneath is recursively flattened into
+      # dotted keys (`users.welcome`, `errors.messages.blank`,
+      # …). For each leaf string, `%{var}` placeholders are
+      # extracted via a simple regex.
+      #
+      # Files that fail to parse are skipped with a load-error
+      # diagnostic surfaced through the plugin's error
+      # channel. Non-Hash YAML roots (e.g. a top-level
+      # sequence) are also skipped — the format is locale-keyed
+      # by convention.
+      class LocaleLoader
+        PLACEHOLDER_RE = /%\{(?<name>[^}]+)\}/
+
+        # Errno classes that indicate "this file is not
+        # readable as a YAML locale" — swallowed so a single
+        # bad path doesn't take down the rest of the index.
+        IO_ERRORS = [Errno::ENOENT, Errno::EACCES, Errno::EISDIR].freeze
+
+        LoadError = Struct.new(:path, :message, keyword_init: true)
+
+        attr_reader :load_errors
+
+        def initialize(io_boundary:, search_paths:)
+          @io_boundary = io_boundary
+          @search_paths = search_paths
+          @load_errors = []
+        end
+
+        # @return [LocaleIndex]
+        def load
+          per_key = {} # dotted_key => { locale => Set<String> }
+          per_key_kinds = {} # dotted_key => { locale => :string|:array|:hash }
+          locales = Set.new
+
+          locale_files.each do |path|
+            contents = read_safely(path)
+            next if contents.nil?
+
+            parsed = parse_yaml_safely(path, contents)
+            next unless parsed.is_a?(Hash)
+
+            parsed.each do |locale, tree|
+              locale = locale.to_s
+              locales << locale
+              flatten_tree(tree, []).each do |dotted_key, value|
+                placeholders = (per_key[dotted_key] ||= {})
+                placeholders[locale] = extract_placeholders(value)
+                kinds = (per_key_kinds[dotted_key] ||= {})
+                kinds[locale] = classify_kind(value)
+              end
+            end
+          end
+
+          entries = per_key.map do |dotted_key, placeholder_map|
+            LocaleIndex::Entry.new(
+              dotted_key: dotted_key,
+              placeholders: placeholder_map.freeze,
+              value_kinds: per_key_kinds[dotted_key].freeze
+            )
+          end
+          LocaleIndex.new(entries, locales: locales.to_a.sort)
+        end
+
+        private
+
+        def read_safely(path)
+          @io_boundary.read_file(path)
+        rescue Plugin::AccessDeniedError, *IO_ERRORS
+          nil
+        end
+
+        def parse_yaml_safely(path, contents)
+          YAML.safe_load(contents, aliases: true, permitted_classes: [Symbol])
+        rescue Psych::SyntaxError => e
+          @load_errors << LoadError.new(path: path, message: "YAML syntax error: #{e.message}")
+          nil
+        end
+
+        def locale_files
+          @search_paths.flat_map do |root|
+            absolute = File.expand_path(root)
+            next [] unless File.directory?(absolute)
+
+            Dir.glob(File.join(absolute, "**", "*.{yml,yaml}"))
+          end.sort
+        end
+
+        # Recursively walks the per-locale subtree, yielding
+        # `[dotted_key, leaf_value]` pairs. Hash leaves are
+        # *not* recorded as entries themselves — only their
+        # descendants — but every leaf scalar / array IS
+        # recorded.
+        def flatten_tree(node, breadcrumbs)
+          case node
+          when Hash
+            node.flat_map do |k, v|
+              flatten_tree(v, breadcrumbs + [k.to_s])
+            end
+          else
+            [[breadcrumbs.join("."), node]]
+          end
+        end
+
+        def extract_placeholders(value)
+          case value
+          when String then value.scan(PLACEHOLDER_RE).flatten.to_set
+          when Array then value.map { |v| extract_placeholders(v) }.reduce(Set.new) { |a, s| a | s }
+          else Set.new
+          end
+        end
+
+        def classify_kind(value)
+          case value
+          when String then :string
+          when Array then :array
+          when Hash then :hash
+          else :scalar
+          end
+        end
+      end
+    end
+  end
+end