i18nlint 1.0.0

data/lib/i18nlint/enumerator.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require_relative "cloneable_struct"
+require_relative "yaml_with_lines"
+
+module I18nLint
+  File = CloneableStruct.new(:filepath, :parsed, :raw, keyword_init: true) do
+    def initialize(...)
+      super
+      @ext = ::File.extname(filepath)
+      @is_ruby = @ext == ".rb"
+      @is_yaml = @ext == ".yml" || @ext == ".yaml"
+      @is_json = @ext == ".json"
+    end
+
+    def ruby? = @is_ruby
+    def yaml? = @is_yaml
+    def json? = @is_json
+  end
+
+  Segment = CloneableStruct.new(:file, :lineno, :key, :text, :value, :locale, :source_locale, keyword_init: true) do
+    def filepath = file.filepath
+
+    def source?
+      locale.to_s == source_locale.to_s
+    end
+  end
+
+  # Using an I18n backend to load and parse the files ensures consistency in syntactical restrictions. We're overloading
+  # so we can capture line numbers where possible.
+  class Loader < ::I18n::Backend::Simple
+    # We don't need to store the translations.
+    def store_translations(...); end
+
+    def load_yml(...)
+      ::I18n::Backend.const_set(:YAML, YamlWithLines)
+      super
+    ensure
+      ::I18n::Backend.send(:remove_const, :YAML)
+    end
+  end
+
+  # Yields each parsed file and segment by `:each_file` and `:each_segment` respectively. `:each` is not supported.
+  class Enumerator
+    attr_reader :source_locale
+
+    def initialize(filepaths, source_locale:)
+      @filepaths = Dir[*Array(filepaths).map(&:to_s)]
+      @source_locale = source_locale
+
+      @i18n_loader = Loader.new
+
+      @files = {}
+    end
+
+    def num_files
+      @filepaths.size
+    end
+
+    def each_file
+      return to_enum(__method__) { @filepaths.size } unless block_given?
+
+      @filepaths.each do |filepath|
+        yield @files[filepath] ||= File.new(
+          filepath:,
+          parsed: @i18n_loader.send(:load_file, filepath),
+          raw: ::File.read(filepath)
+        )
+      end
+    end
+
+    def each_segment(file: nil)
+      return to_enum(__method__, file:) unless block_given?
+
+      each_file do |i18n_file|
+        next if file && i18n_file != file
+
+        YamlWithLines.walk(i18n_file.parsed, yield_hash_when:) do |(locale, *key_parts), text, line_start, _line_end|
+          text, value = determine_text_and_value(text)
+          yield Segment.new(file: i18n_file, lineno: line_start, key: key_parts.join("."), text:, value:,
+                            locale:, source_locale:)
+        end
+      end
+    end
+
+    private
+
+    def yield_hash_when
+      proc do |hash|
+        hash_key?(hash, :one) && (hash_key?(hash, :few) || hash_key?(hash, :many) || hash_key?(hash, :other))
+      end
+    end
+
+    def hash_key?(hash, key)
+      hash.key?(key.to_s) || hash.key?(key.to_sym)
+    end
+
+    def determine_text_and_value(text)
+      if text.is_a?(String)
+        [text, nil]
+      else
+        [nil, text]
+      end
+    end
+  end
+end

data/lib/i18nlint/error.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module I18nLint
+  class Error < StandardError; end
+
+  class ErrorOnFile < Error # rubocop:disable Style/Documentation
+    def initialize(file, cause)
+      super("on file #{file.filepath}:\n  #{cause.class}: #{cause.message}")
+    end
+  end
+
+  class ErrorOnSegment < Error # rubocop:disable Style/Documentation
+    def initialize(segment, cause)
+      super("on segment #{segment.key} at #{segment.filepath}:#{segment.lineno}:\n  #{cause.class}: #{cause.message}")
+    end
+  end
+
+  class ErrorOnSegmentComparison < Error # rubocop:disable Style/Documentation
+    def initialize(segment, source_segment, cause)
+      super("on segment #{segment.key} at #{segment.filepath}:#{segment.lineno} " \
+            "compared to #{source_segment.key} at #{source_segment.filepath}:#{source_segment.lineno}:" \
+            "\n  #{cause.class}: #{cause.message}")
+    end
+  end
+end

data/lib/i18nlint/highlighters/below_line.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module I18nLint
+  module Highlighters
+    # Indicate slices in string. A 'slice' here is a tuple of character positions, e.g. '01234' and [1, 3] gives '123'.
+    module BelowLine
+      class << self
+        def indicate(str, *slices, messages: [])
+          slices = slices.sort
+          messages = messages.dup
+
+          has_messages = !messages.empty?
+
+          ensure_tuples_of(Integer, *slices)
+
+          # Go line-by-line to add indicators if needed, then join at the end.
+          to_enum(:highlight_per_line, str, *slices).map do |line, slices_in_this_line|
+            next line if slices_in_this_line.empty?
+
+            indicators_line = make_indicators_line("^", slices_in_this_line,
+                                                   (messages.shift(slices_in_this_line.size) if has_messages))
+
+            "#{line.chomp}\n#{indicators_line}#{"\n" if line.end_with?("\n")}"
+          end.join
+        end
+
+        private
+
+        def ensure_tuples_of(type, *objects)
+          return if objects.all? { _1.is_a?(Array) && _1.map(&:class) == [type, type] }
+
+          raise ArgumentError,
+                "must be given 1 or more tuples of #{type}, but was called with #{objects.map(&:inspect).join(", ")}"
+        end
+
+        def highlight_per_line(str, *slices)
+          str.lines.reduce([0, []]) do |(checked, line_slices), line|
+            line_length = line.chomp.length # ignore newlines so it doesn't look like we're indicating empty space
+
+            slices.delete_if do |a, b|
+              next if a > (limit = checked + line_length)
+
+              # Adjust the slice so it's local to this line rather than the str as a whole.
+              line_slices << [(a - checked).clamp(0, line_length), (b - checked).clamp(0, line_length)]
+              true if b <= limit
+            end
+
+            yield [line, line_slices]
+
+            [checked + line.length, []]
+          end
+        end
+
+        def make_indicators_line(char, slices, messages)
+          line = make_line_of(char, *slices)
+          return line if messages.nil?
+
+          "#{line} #{messages.map { |m| m.nil? ? "<nil>" : m }.join("; ")}".rstrip
+        end
+
+        def make_line_of(char, *slices)
+          (" " * slices.last[1]).tap do |line|
+            slices.each do |slice|
+              line[slice[0]...slice[1]] = char * (slice[1] - slice[0])
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/i18nlint/highlighters/colour.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module I18nLint
+  module Highlighters
+    # Colour slices in string. A 'slice' here is a tuple of character positions, e.g. '01234' and [1, 3] gives '123'.
+    module Colour
+      class << self
+        def bold(str)
+          "\e[1m#{str}\e[0m"
+        end
+
+        def highlight(str)
+          "\e[30;43m#{str}\e[0m"
+        end
+
+        def indicate(str, *slices)
+          ensure_tuples_of(Integer, *slices)
+
+          str = str.dup
+
+          slices.sort.reverse.each do |slice|
+            str[slice[0]...slice[1]] = highlight(str[slice[0]...slice[1]])
+          end
+
+          str
+        end
+
+        private
+
+        def ensure_tuples_of(type, *objects)
+          return if objects.all? { _1.is_a?(Array) && _1.map(&:class) == [type, type] }
+
+          raise ArgumentError, "must be given 1 or more tuples of #{type}, but was called with #{objects.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/i18nlint/highlighters.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "i18nlint/highlighters/below_line"
+require "i18nlint/highlighters/colour"
+
+module I18nLint
+  # Decide how to highlight a string.
+  module Highlighters
+    def self.indicate(text, *range)
+      if $stdout.isatty
+        Colour.indicate(text, *range)
+      else
+        BelowLine.indicate(text, *range)
+      end
+    end
+  end
+end

data/lib/i18nlint/linter.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module I18nLint
+  # Run rules over the given files.
+  class Linter
+    attr_reader :offences, :source_locale
+
+    def initialize(filepaths:, source_locale:)
+      @offences = []
+      @enum = Enumerator.new(filepaths, source_locale:)
+      @source_locale = source_locale
+    end
+
+    def num_files
+      enum.num_files
+    end
+
+    def tick_each_file(&block)
+      @tick_each_file = make_tick_proc(block)
+    end
+
+    def tick_each_comparison(&block)
+      @tick_each_comparison = make_tick_proc(block)
+    end
+
+    def run
+      each_file do |i18n_file|
+        tick(@tick_each_file, Registry.rules.sum do |rule|
+          next 0 if rule.excluded?(i18n_file.filepath)
+
+          rule.on_file(i18n_file.clone)
+          each_segment(file: i18n_file) do |segment|
+            rule.on_segment(segment.clone)
+          end
+          rule.take_offences.tap { offences.concat(_1) }.size
+        end)
+      end
+    end
+
+    def run_comparison
+      each_segment_comparison do |segment, source_segment|
+        tick(@tick_each_comparison, Registry.rules.sum do |rule|
+          next 0 if rule.excluded?(segment.file.filepath)
+
+          rule.on_segment_comparison(segment.clone, source_segment.clone)
+          rule.take_offences.tap { offences.concat(_1) }.size
+        end)
+      end
+    end
+
+    def each_file(&)
+      enum.each_file do |file|
+        yield file
+      rescue Error # coming from a segment?
+        raise
+      rescue StandardError => e
+        raise ErrorOnFile.new file, e
+      end
+    end
+
+    def each_segment(file: nil, &)
+      enum.each_segment(file:) do |segment|
+        yield segment
+      rescue StandardError => e
+        raise ErrorOnSegment.new segment, e
+      end
+    end
+
+    def each_segment_comparison(&)
+      comparisons = ComparisonMap.new(source_locale)
+      # Slurp all the files first, so we can separate the source segments from translation segments.
+      each_segment { comparisons.add(_1) }
+      comparisons.freeze
+      comparisons.each do |segment, source_segment|
+        yield [segment, source_segment]
+      rescue StandardError => e
+        raise ErrorOnSegmentComparison.new segment, source_segment, e
+      end
+    end
+
+    private
+
+    attr_reader :enum
+
+    def tick(block, num_offences)
+      return if block.nil?
+
+      block.call(num_offences)
+    end
+
+    def make_tick_proc(block)
+      if block.arity.zero?
+        ->(_num_offences) { block.call }
+      else
+        block
+      end
+    end
+
+    # Store segments then enumerate them compared to the source_locale.
+    class ComparisonMap
+      def initialize(source_locale)
+        @source_locale = source_locale.downcase
+        @hash = Hash.new do |h, k|
+          next if h.frozen?
+
+          h[k] = Hash.new do |h, k|
+            next if h.frozen?
+
+            h[k] = []
+          end
+        end
+      end
+
+      attr_reader :source_locale
+
+      include Enumerable
+
+      def each(&)
+        ::Enumerator.new do |yielder|
+          each_segment do |segment|
+            each_source(segment.key) do |source_segment|
+              yielder << [segment, source_segment]
+            end
+          end
+        end.each(&)
+      end
+
+      def add(segment)
+        @hash[segment.locale.downcase.to_sym][segment.key] << segment
+      end
+
+      def freeze
+        super
+        @hash.freeze
+        @hash.each_value do |level2|
+          level2.freeze
+          level2.each_value(&:freeze)
+        end
+      end
+
+      private
+
+      def each_segment(&block)
+        @hash.except(source_locale.to_sym).each_value do |per_key|
+          per_key.each_value do |segments|
+            segments.each(&block)
+          end
+        end
+      end
+
+      def each_source(key, &)
+        @hash.dig(source_locale.to_sym, key)&.each(&)
+      end
+    end
+  end
+end

data/lib/i18nlint/railtie.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module I18nLint
+  # Allow this library to gain I18n configuration from a Rails app.
+  class Railtie < ::Rails::Railtie
+    rake_tasks do
+      desc "Lint your I18n"
+      task :i18nlint, [:filepaths] => [:environment] do |_t, args|
+        source_locale = Rails.application.config.i18n.default_locale
+
+        filepaths = args[:filepaths]
+        filepaths ||= I18n.load_path.select { _1.start_with?(Rails.root.to_s) }
+
+        require "i18nlint/cli"
+        I18nLint::CLI.run(["--source=#{source_locale}", *filepaths])
+      end
+    end
+  end
+end

data/lib/i18nlint/registry.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module I18nLint
+  # Collect rules.
+  class Registry
+    @rules = []
+
+    LINT_METHODS = %i[
+      on_file
+      on_segment
+      on_segment_comparison
+    ].freeze
+    private_constant :LINT_METHODS
+
+    # Avoid custom rules that will never get used.
+    class WillNeverRun < NotImplementedError
+      attr_reader :rule_class
+
+      def initialize(instance)
+        @rule_class = instance.class
+        super("Rule #{rule_class} will not be used: it must respond to at least one of " \
+              "#{LINT_METHODS.map(&:inspect).join(", ")}")
+      end
+    end
+
+    class << self
+      attr_reader :rules
+
+      def register_rule(rule_class, config = {})
+        rule = rule_class.new(config)
+        enforce_rule_shape(rule)
+        rules << rule
+        rule
+      end
+
+      private
+
+      def enforce_rule_shape(rule)
+        has_methods = false
+        LINT_METHODS.each do |m|
+          if rule.respond_to?(m)
+            has_methods = true
+            next
+          end
+
+          rule.singleton_class.define_method(m) { |*| nil }
+        end
+
+        raise WillNeverRun, rule unless has_methods
+      end
+    end
+  end
+end

data/lib/i18nlint/rspec/expect_offence.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "tempfile"
+
+module I18nLint
+  module RSpec
+    # Include in RSpec example groups to get rule assertions.
+    module ExpectOffence
+      def self.included(base)
+        base.let(:rule) { ::I18nLint::Registry.register_rule(*[described_class, (config if defined?(config))].compact) }
+      end
+
+      extend ::RSpec::Matchers::DSL
+
+      matcher :cause_offence do |expected|
+        diffable
+        supports_block_expectations
+
+        chain(:type) { @type = _1 }
+        chain(:did_you_mean) { @opposite_assertion = _1 }
+
+        define_method(:source) { @source ||= expected.lines.grep_v(/^\s*\^+ ?/).join }
+
+        def matches_offences?
+          @actual, @offences = @actual.call(source)
+          actual == expected
+        end
+
+        match              { matches_offences? && !@offences.empty? }
+        match_when_negated { matches_offences? && @offences.empty? }
+
+        failure_message do
+          if source == expected
+            return "No offence highlights have been given#{", and none were found" if @offences.empty?}. " \
+                   "Did you mean `#{@opposite_assertion}`?"
+          end
+
+          "expected offences to match#{", but there were none" if @offences.empty?}"
+        end
+
+        failure_message_when_negated do
+          if source != expected
+            return "Offence highlights have been given#{", but no offences found" if @offences.empty?}. " \
+                   "Did you mean `#{@opposite_assertion}`?"
+          end
+
+          "expected no #{@type} offences"
+        end
+      end
+
+      def expect_file_offence(expected_highlights, filepath)
+        expect { |source| on_file(filepath, source) }.to cause_offence(expected_highlights)
+          .type(:file).did_you_mean(:expect_no_file_offences)
+      end
+
+      def expect_no_file_offences(expected_highlights, filepath)
+        expect { |source| on_file(filepath, source) }.not_to cause_offence(expected_highlights)
+          .type(:file).did_you_mean(:expect_file_offence)
+      end
+
+      def expect_segment_offence(expected_highlights, lineno = nil, locale: nil)
+        expect { |source| on_segment(source, lineno:, locale:) }.to cause_offence(expected_highlights)
+          .type(:segment).did_you_mean(:expect_no_segment_offences)
+      end
+
+      def expect_no_segment_offences(expected_highlights, lineno = nil, locale: nil)
+        expect { |source| on_segment(source, lineno:, locale:) }.not_to cause_offence(expected_highlights)
+          .type(:segment).did_you_mean(:expect_segment_offence)
+      end
+
+      def expect_comparison_offence(expected_translation, expected_source, locale:, source_locale:)
+        expect { |combined| on_comparison(*compare_split(combined), locale:, source_locale:) }
+          .to cause_offence(compare_combine(expected_translation, expected_source))
+          .type(:segment).did_you_mean(:expect_no_comparison_offences)
+      end
+
+      def expect_no_comparison_offences(expected_translation, expected_source, locale:, source_locale:)
+        expect { |combined| on_comparison(*compare_split(combined), locale:, source_locale:) }
+          .not_to cause_offence(compare_combine(expected_translation, expected_source))
+          .type(:segment).did_you_mean(:expect_comparison_offence)
+      end
+
+      def on_file(filepath, contents)
+        rule.on_file(make_file(filepath, contents))
+        offences = rule.take_offences
+        [highlight_offences(contents, offences), offences]
+      end
+
+      def on_segment(source, lineno: nil, locale: nil, key: nil, filepath: nil)
+        rule.on_segment(make_segment(source, lineno:, locale:, key:, filepath:))
+        offences = rule.take_offences
+        [highlight_offences(source, offences), offences]
+      end
+
+      def on_comparison(translation, source, locale: nil, source_locale: nil)
+        rule.on_segment_comparison make_segment(translation, locale:), make_segment(source, locale: source_locale)
+        offences = rule.take_offences
+        [
+          compare_combine(
+            highlight_offences(translation, offences),
+            highlight_offences(source, offences.map(&:source_offence))
+          ), offences
+        ]
+      end
+
+      DUMMY_FILE = ::I18nLint::File.new(filepath: "<none>")
+
+      JOINER = "\n---\n"
+
+      private
+
+      def compare_combine(translation, source) = [translation.chomp, source].join(JOINER)
+      def compare_split(combined)              = combined.split(JOINER)
+
+      def highlight_offences(content, offences)
+        highlighted, unhighlighted = offences.partition(&:highlight)
+
+        highlight_messages = highlighted.each_with_object({}) { |o, h| o.highlight.each { h[_1] = o.message } }
+
+        actual = ::I18nLint::Highlighters::BelowLine.indicate(content, *highlight_messages.keys,
+                                                              messages: highlight_messages.values)
+
+        other = unhighlighted.filter_map(&:message).map(&:inspect).join("; ")
+        actual.prepend "^ Offences without highlights: #{other}\n" unless other.empty?
+
+        actual
+      end
+
+      def make_file(filepath, contents)
+        file = Tempfile.create([filepath, ::File.extname(filepath)])
+        file.tap { _1.write(contents) }.tap(&:rewind)
+        ::I18nLint::Enumerator.new([file.path], source_locale: nil).each_file.first.tap { _1.filepath = filepath }
+      end
+
+      def make_segment(text, lineno: nil, locale: nil, key: nil, filepath: nil)
+        file = filepath ? ::I18nLint::File.new(filepath:) : DUMMY_FILE
+        ::I18nLint::Segment.new(text:, file:, lineno:, locale:, key:)
+      end
+    end
+  end
+end