i18nlint 1.0.0

data/lib/i18nlint/rule.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "singleton"
+require "i18nlint/rule_helper"
+
+module I18nLint
+  # A registered offence as reported by a rule.
+  FileOffence = Struct.new(:rule, :filepath, :lineno, :text, :message, :highlight, keyword_init: true) do
+    def key = nil
+    def locale = nil
+  end
+  SegmentOffence = Struct.new(*FileOffence.members, :value, :locale, :key, keyword_init: true)
+  CompareSegmentOffence = Struct.new(*SegmentOffence.members, :source_offence, keyword_init: true)
+
+  # Base class for rules to extend.
+  class Rule
+    include RuleHelper
+
+    attr_reader :config, :message
+
+    class << self
+      class RuleClasses < Array; include Singleton; end
+      private_constant :RuleClasses
+
+      def inherited(rule_class)
+        RuleClasses.instance << rule_class
+        super
+      end
+
+      def rule_classes = RuleClasses.instance
+
+      def enabled_by_default? = @enable_by_default.nil? || @enable_by_default
+      def on_init_blocks      = @on_init_blocks ||= []
+
+      def enable_by_default(bool)
+        @enable_by_default = bool
+      end
+
+      def on_init(&block)
+        on_init_blocks << block
+      end
+
+      def rule_key
+        name.to_s.gsub(/^(::)?I18nLint::Rules?::/, "").gsub("::", "/")
+      end
+    end
+
+    def initialize(config = {})
+      @config = config
+      @message = config["Message"] if config.is_a?(Hash)
+      @offences = []
+
+      @exclude = Array((config["Exclude"] if config.is_a?(Hash)))
+      @always_include = @exclude.empty?
+
+      self.class.on_init_blocks.each { |b| instance_exec(&b) }
+    end
+
+    def describe
+      desc = " #{description}" if respond_to?(:description) && description
+      desc ||= " #{self.class.description}" if self.class.respond_to?(:description) && self.class.description
+      "#{self.class.rule_key}#{desc}"
+    end
+
+    def excluded?(filepath)
+      return false if @always_include
+
+      path = Pathname.new(filepath)
+      @exclude.any? { |dir_pattern| path.fnmatch(dir_pattern) }
+    end
+
+    def add_offence(item, message = nil, highlight: nil)
+      case item
+      when File
+        add_file_offence(item, message, highlight:)
+      when Segment
+        add_segment_offence(item, message, highlight:)
+      else
+        raise ArgumentError, "inapplicable offence type #{item.class}: #{item}"
+      end
+    end
+
+    def add_file_offence(file, msg = nil, lineno: nil, source: nil, highlight: nil)
+      @offences << FileOffence.new(
+        rule: describe,
+        filepath: file.filepath,
+        lineno:,
+        text: source, # don't print the whole file contents in the offence
+        message: msg || message,
+        highlight:
+      )
+    end
+
+    def add_segment_offence(segment, msg = nil, highlight: nil)
+      @offences << make_segment_offence(SegmentOffence, segment, describe, msg || message, highlight:)
+    end
+
+    def add_segment_compare_offence(segment, source_segment, msg = nil, src_msg = nil, highlight: nil, # rubocop:disable Metrics/ParameterLists
+                                    source_highlight: nil)
+      desc = describe
+      o = make_segment_offence(CompareSegmentOffence, segment, desc, msg || message, highlight:)
+      o.source_offence = make_segment_offence(SegmentOffence, source_segment, desc, src_msg,
+                                              highlight: source_highlight)
+      @offences << o
+    end
+
+    def take_offences
+      @offences
+    ensure
+      @offences = []
+    end
+
+    private
+
+    def make_segment_offence(offence_class, segment, description, message, highlight:)
+      offence_class.new(
+        rule: description,
+        filepath: segment.filepath,
+        lineno: segment.lineno,
+        locale: segment.locale,
+        key: segment.key,
+        text: segment.text,
+        message:,
+        highlight:
+      )
+    end
+  end
+end

data/lib/i18nlint/rule_helper.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module I18nLint
+  # Various methods to help construct rules.
+  module RuleHelper
+    # For each item in arr_a, find the first comparable item in arr_b and remove them both. Returns the removed items.
+    def xor!(arr_a, arr_b, &compare)
+      compare = xor_comparison_proc(&compare)
+
+      deleted = []
+
+      arr_a.delete_if do |a|
+        if (i = arr_b.find_index { |b| compare[a, b] })
+          deleted << [a, arr_b[i]]
+          arr_b.delete_at(i)
+          next true
+        end
+      end
+
+      [deleted.map(&:first), deleted.map(&:last)]
+    end
+
+    def xor_comparison_proc(&block)
+      if !block_given?
+        proc { |a, b| a == b }
+      elsif block.arity != 2
+        proc { |a, b| block[a] == block[b] }
+      else
+        block
+      end
+    end
+    private :xor_comparison_proc
+
+    def match_with_highlights(string, regex)
+      string.enum_for(:scan, regex).map do |matches|
+        [matches[0], Regexp.last_match.offset(0)]
+      end
+    end
+
+    # Use this to XOR results found using `match_with_highlights`.
+    def xor_highlights!(arr_a, arr_b) = xor!(arr_a, arr_b, &:first)
+
+    def self.included(base) = base.extend ClassMethods
+
+    module ClassMethods # rubocop:disable Style/Documentation
+      def def_segment_comparison(includes_highlights: false, message: nil, source_message: nil, &process_segment)
+        include EasySegmentComparison
+        include includes_highlights ? CompareWithHighlights : CompareNoHighlights
+
+        define_method(:process_message) { message }
+        define_method(:process_source_message) { source_message }
+        define_method(:process_segment, &process_segment)
+      end
+
+      module CompareNoHighlights # rubocop:disable Style/Documentation
+        def compare!(these, source) = xor!(these, source)
+        def process_values(values) = values
+        def process_highlights(_values) = nil
+      end
+
+      module CompareWithHighlights # rubocop:disable Style/Documentation
+        def compare!(these, source) = xor!(these, source, &:first)
+        def process_values(values) = values.map(&:first)
+
+        def process_highlights(values)
+          highlights = values.map(&:last)
+          highlights.empty? ? nil : highlights
+        end
+      end
+
+      module EasySegmentComparison # rubocop:disable Style/Documentation
+        def on_segment_comparison(segment, source_segment)
+          these = process_segment(segment)
+          source = process_segment(source_segment)
+
+          compare!(these, source)
+
+          return if these.empty? && source.empty?
+
+          add_segment_compare_offence(
+            segment, source_segment,
+            string_or_callable(process_message, process_values(these), segment, source_segment),
+            string_or_callable(process_source_message, process_values(source), segment, source_segment),
+            highlight: process_highlights(these), source_highlight: process_highlights(source)
+          )
+        end
+
+        private
+
+        def string_or_callable(val, *args)
+          val = val.call(*args) if val.is_a? Proc
+          val
+        end
+      end
+    end
+  end
+end

data/lib/i18nlint/rules/built_in/duplicates.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module I18nLint
+  module Rules
+    module BuiltIn
+      # Check for duplicate segment keys across all given files. Differing load order determines which duplicate segment
+      # is the last added to the I18n store, so don't bother reporting on that; just highlight all the duplicates.
+      class Duplicates < Rule
+        enable_by_default true
+
+        # Track every segment key. Add offence when any key is encountered twice or more. Ensure the first occurrence is
+        # offended, and only once.
+        on_init do
+          @keys = Set.new
+          @offended_first_occurrence = Hash.new { |h, locale| h[locale] = {} }
+        end
+        attr_reader :keys, :offended_first_occurrence
+
+        def on_segment(segment)
+          check_file_duplicates(segment)
+
+          first_occurrence = recorded_first_occurrence(segment)
+          return if first_occurrence == true
+
+          add_segment_offence(first_occurrence) if first_occurrence
+          add_segment_offence(segment)
+        end
+
+        private
+
+        def recorded_first_occurrence(segment)
+          if keys.add?([segment.locale, segment.key])
+            offended_first_occurrence[segment.locale][segment.key] = segment
+            return true
+          end
+
+          offended_first_occurrence[segment.locale].delete(segment.key)
+        end
+
+        def check_file_duplicates(segment)
+          dupes = YamlWithLines.dupe_segments_by_file.dig(segment.file.filepath, "#{segment.locale}.#{segment.key}")
+          return unless dupes
+
+          add_segment_offence(segment, "duplicate of line #{(dupes - [segment.lineno]).join(", ")}")
+        end
+      end
+    end
+  end
+end

data/lib/i18nlint/rules/built_in/interpolations.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module I18nLint
+  module Rules
+    module BuiltIn
+      # Check I18n interpolations like %{key}.
+      class Interpolations < Rule
+        enable_by_default true
+
+        on_init do
+          interpolation_patterns =
+            if ::I18n.config.respond_to?(:interpolation_patterns)
+              ::I18n.config.interpolation_patterns
+            else
+              # This is one union-ed regexp, so we have to split it so we can edit each part individually below.
+              ::I18n::INTERPOLATION_PATTERN.source.split(/\|(?=\(\?[-mix]{1,4}:?)/).map do |source|
+                source.match(/\(\?[-mix]{1,4}:?(.*)\)/)[1]
+              end
+            end
+
+          @i18n_interpolation_pattern_allowing_whitespace = Regexp.union(interpolation_patterns.map do |regex|
+            regex = regex.source if regex.is_a?(Regexp)
+            Regexp.new regex.gsub(/^\\?./, '\0\\s*')
+                            .gsub(/\\?.$/, '\\s*\0')
+                            .gsub(/\\?[<{]/, '\0\\s*')
+          end)
+        end
+
+        attr_reader :i18n_interpolation_pattern_allowing_whitespace
+
+        # Look for the configured I18n interpolation pattern with possible spaces inside it; any found that aren't in
+        # the known interpolations are an offence.
+        def on_segment(segment)
+          expected                 = match_with_highlights(segment.text, ::I18n::INTERPOLATION_PATTERN)
+          with_possible_whitespace = match_with_highlights(segment.text, i18n_interpolation_pattern_allowing_whitespace)
+
+          xor_highlights!(with_possible_whitespace, expected)
+
+          return if with_possible_whitespace.empty?
+
+          add_segment_offence(segment, "broken", highlight: with_possible_whitespace.map(&:last))
+        end
+
+        # Compare interpolations against source; anything extra or missing is an offence.
+        def_segment_comparison(
+          includes_highlights: true,
+          message: lambda do |matches, segment, _source|
+            "extra in #{segment.locale}: #{matches.join("; ")}" unless matches.empty?
+          end,
+          source_message: lambda do |matches, segment, _source|
+            "missing in #{segment.locale}: #{matches.join("; ")}" unless matches.empty?
+          end
+        ) do |segment|
+          match_with_highlights(segment.text, ::I18n::INTERPOLATION_PATTERN)
+        end
+      end
+    end
+  end
+end

data/lib/i18nlint/rules/built_in/match.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module I18nLint
+  module Rules
+    module BuiltIn
+      # Helper methods for reporting offences for a pattern configuration.
+      module MatchPattern
+        def self.included(base)
+          base.on_init do
+            next unless config.is_a?(Hash) && config["Pattern"]
+
+            options = Regexp::IGNORECASE if config["CaseSensitive"] == false
+            @pattern = Regexp.new(config["Pattern"], options)
+          end
+        end
+
+        attr_reader :pattern
+
+        def description = pattern.inspect
+      end
+
+      # Report when a Regexp pattern matches against an individual segment.
+      class MatchSegment < Rule
+        def self.rule_key = "match-segment"
+        enable_by_default true
+
+        include MatchPattern
+
+        def on_segment(segment)
+          return unless pattern
+
+          segment.text.scan(pattern) do |_match|
+            add_segment_offence(segment, nil, highlight: [Regexp.last_match.offset(0)])
+          end
+        end
+      end
+
+      # Report when a Regexp pattern matches against an individual segment as compared to itself in the source locale.
+      class MismatchToSource < Rule
+        def self.rule_key = "mismatch-to-source"
+        enable_by_default true
+
+        include MatchPattern
+
+        def on_segment_comparison(segment, source_segment)
+          return unless pattern
+
+          mismatches = enum_for(:each_mismatch, segment.text, source_segment.text).to_a
+          return if mismatches.none?
+
+          add_segment_compare_offence(
+            segment, source_segment,
+            "Found #{mismatches.size == 1 ? "mismatch" : "mismatches"} to the source #{source_segment.locale.upcase}",
+            highlight: mismatches.filter_map(&:highlight),
+            source_highlight: mismatches.filter_map(&:source_highlight)
+          )
+        end
+
+        private
+
+        def scan(text)
+          text.enum_for(:scan, pattern).map { Scan.new(_1, Regexp.last_match.offset(0)) }
+        end
+        Scan = Struct.new(:match, :highlight)
+        private_constant :Scan
+
+        def reduce(trans, source)
+          trans.delete_if do |scan|
+            if (i = source.find_index { _1.match == scan.match })
+              source.delete_at(i)
+              next true
+            end
+          end
+        end
+
+        def scan_and_reduce(trans, source)
+          trans = scan(trans) # 🏳️‍⚧️🏳️‍🌈🫶
+          source = scan(source)
+          reduce(trans, source)
+
+          [trans, source]
+        end
+
+        def each_mismatch(trans, source)
+          trans, source = scan_and_reduce(trans, source)
+
+          trans_tally = trans.map(&:match).tally
+          source_tally = source.map(&:match).tally
+
+          trans.each  { |scan| yield mismatch_from_tallies(scan.match, trans_tally, source_tally, scan.highlight, nil) }
+          source.each { |scan| yield mismatch_from_tallies(scan.match, trans_tally, source_tally, nil, scan.highlight) }
+        end
+
+        def mismatch_from_tallies(match, trans_tally, source_tally, highlight, source_highlight)
+          Mismatch.new(match, trans_tally[match] || 0, source_tally[match] || 0, highlight, source_highlight)
+        end
+        Mismatch = Struct.new(:match, :actual_count, :expected_count, :highlight, :source_highlight)
+        private_constant :Mismatch
+      end
+
+      # Report when a Regexp pattern matches against a whole I18n file.
+      class MatchFile < Rule
+        def self.rule_key = "match-file"
+        enable_by_default true
+
+        include MatchPattern
+
+        def on_file(file)
+          return unless pattern
+
+          file.raw.scan(pattern) do
+            source, lineno, offset_adjust = source_for_match(Regexp.last_match, file.raw)
+            highlight = Regexp.last_match.offset(0).map { _1 - offset_adjust }
+            add_file_offence(file, nil, lineno:, source:, highlight:)
+          end
+        end
+
+        def source_for_match(match, raw)
+          end_of_match = match.offset(0)[1]
+          n = 0
+          lines = []
+          raw.lines.each do |line|
+            break if n >= end_of_match
+
+            lines << line
+            n += line.length
+          end
+
+          [lines.last, lines.size, n - lines.last.size]
+        end
+      end
+    end
+  end
+end

data/lib/i18nlint/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module I18nLint
+  VERSION = "1.0.0"
+end