i18n-context-generator 0.4.0 → 0.5.0

data/lib/i18n_context_generator/supplemental_context.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module I18nContextGenerator
+  # Immutable, named evidence supplied in addition to translations and source usages.
+  ContextSource = Data.define(:kind, :name, :content) do
+    def initialize(kind:, name:, content:)
+      super(
+        kind: kind.to_sym,
+        name: name.dup.freeze,
+        content: content.dup.freeze
+      )
+    end
+  end
+
+  # Converts configured text files and caller-provided values into context records.
+  class SupplementalContext
+    class << self
+      def load(files:, runtime:)
+        validate_files!(files)
+        validate_runtime!(runtime)
+
+        file_sources = files.map { |path| load_file(path) }
+        runtime_sources = runtime.map do |name, content|
+          ContextSource.new(
+            kind: :runtime,
+            name: scrub_text(name),
+            content: scrub_text(content)
+          )
+        end
+
+        (file_sources + runtime_sources).freeze
+      end
+
+      private
+
+      def validate_files!(files)
+        return if files.is_a?(Array) && files.all? { |path| path.is_a?(String) && !path.strip.empty? }
+
+        raise Error, 'context_files must be an array of non-empty strings'
+      end
+
+      def validate_runtime!(runtime)
+        raise Error, 'supplemental_context must be a mapping' unless runtime.is_a?(Hash)
+
+        runtime.each do |name, content|
+          raise Error, 'supplemental context name must be a non-empty string' unless
+            name.is_a?(String) && !name.strip.empty?
+          next if content.is_a?(String) && !content.strip.empty?
+
+          raise Error, "supplemental context value for #{name} must be a non-empty string"
+        end
+      end
+
+      def load_file(path)
+        bytes = File.binread(path)
+        raise Error, "context file contains NUL bytes; convert it to UTF-8 text: #{path}" if bytes.include?("\0")
+
+        content = scrub_text(bytes)
+        raise Error, "context file is empty: #{path}" if content.strip.empty?
+
+        ContextSource.new(
+          kind: :file,
+          name: scrub_text(File.basename(path)),
+          content: content
+        )
+      rescue Error
+        raise
+      rescue SystemCallError => e
+        raise Error, "Unable to read context file #{path}: #{e.message}"
+      end
+
+      def scrub_text(value)
+        value.dup.force_encoding(Encoding::UTF_8).scrub
+      end
+    end
+  end
+end

data/lib/i18n_context_generator/translation_comment_index.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative 'xml_scanner'
+require_relative 'apple_string_literal'
+
+module I18nContextGenerator
+  # Associates translator-comment lines with the translation entry that follows.
+  # Diff consumers use this to treat comment-only edits as entry changes while
+  # retaining the exact changed comment line for review placement.
+  class TranslationCommentIndex
+    def initialize(file_path = nil, format:, content: nil)
+      @file_path = file_path
+      @format = format
+      @content = content || File.binread(file_path)
+      @key_lines = {}
+    end
+
+    def key_at(line_number)
+      entries[line_number]
+    end
+
+    def line_for_key(key)
+      entries
+      @key_lines[key]
+    end
+
+    private
+
+    def entries
+      @entries ||= case @format
+                   when :strings then strings_entries
+                   when :xml then xml_entries
+                   else {}
+                   end
+    end
+
+    def strings_entries
+      entries = {}
+      pending_lines = []
+      inside_comment = false
+
+      @content.each_line.with_index(1) do |line, line_number|
+        content = line
+
+        if inside_comment
+          pending_lines << line_number
+          comment_end = content.index('*/')
+          next unless comment_end
+
+          inside_comment = false
+          content = content[(comment_end + 2)..].to_s
+        elsif (comment_start = content.index(%r{\A\s*/\*}))
+          pending_lines << line_number
+          comment_end = content.index('*/', comment_start + 2)
+          unless comment_end
+            inside_comment = true
+            next
+          end
+          content = content[(comment_end + 2)..].to_s
+        elsif content.lstrip.start_with?('//')
+          pending_lines << line_number
+          next
+        end
+
+        if (key = strings_key_from(content))
+          @key_lines[key] ||= line_number
+          pending_lines.each { |comment_line| entries[comment_line] = key }
+          pending_lines.clear
+        elsif !content.strip.empty?
+          pending_lines.clear
+        end
+      end
+
+      entries
+    end
+
+    def strings_key_from(content)
+      AppleStringLiteral.assignment_key(content)
+    end
+
+    def xml_entries
+      entries = {}
+      pending_lines = []
+      pending_tag = nil
+      pending_tag_line = nil
+      comment_state = {}
+
+      @content.each_line.with_index(1) do |line, line_number|
+        visible, contained_comment = XmlScanner.without_comments(line, comment_state)
+        pending_lines << line_number if contained_comment
+
+        if pending_tag
+          pending_tag << visible
+        elsif (tag_start = visible.index(/<(?:string-array|plurals|string)\b/))
+          pending_tag = visible[tag_start..]
+          pending_tag_line = line_number
+        elsif !visible.strip.empty?
+          pending_lines.clear
+        end
+
+        next unless pending_tag&.include?('>')
+
+        if (key = resource_name_from(pending_tag))
+          @key_lines[key] ||= pending_tag_line
+          pending_lines.each { |comment_line| entries[comment_line] = key }
+        end
+        pending_lines.clear
+        pending_tag = nil
+        pending_tag_line = nil
+      end
+
+      entries
+    end
+
+    def resource_name_from(tag)
+      return unless tag.match?(/<(?:string-array|plurals|string)\b/)
+
+      tag[/\bname\s*=\s*(["'])(.*?)\1/m, 2]
+    end
+  end
+end

data/lib/i18n_context_generator/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module I18nContextGenerator
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

data/lib/i18n_context_generator/writers/android_xml_writer.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative '../android_resource'
+require_relative '../generated_comment'
+
 module I18nContextGenerator
   module Writers
     # Writer that updates Android strings.xml files with context comments
@@ -15,8 +18,10 @@ module I18nContextGenerator
       def write(results, source_path)
         return unless File.exist?(source_path)
 
+        original_content = File.binread(source_path)
         lines = File.readlines(source_path, encoding: 'UTF-8')
         results_by_key = build_results_lookup(results, source_path)
+        return false unless results_by_key.values.any? { |result| writable_result?(result) }
 
         output_lines = []
         i = 0
@@ -27,11 +32,11 @@ module I18nContextGenerator
           # Only write comments on <string> elements, not <plurals> or <string-array>.
           # Plural/array parent comments would use a single child's description which
           # is misleading for the resource as a whole.
-          # Match the opening <string name="..."> tag — works for both single-line and
-          # multi-line string elements.
-          if (match = line.match(/^(\s*)<string\s+name="([^"]+)"/))
-            indent = match[1]
-            key = match[2]
+          # Match the complete opening tag so attribute order, quote style, and
+          # multiline attributes do not affect write-back.
+          if (element = string_element_at(lines, i))
+            indent = element[:indent]
+            key = element[:key]
             result = results_by_key[key]
 
             insert_context_comment(output_lines, indent, result.description) if writable_result?(result)
@@ -41,11 +46,34 @@ module I18nContextGenerator
           i += 1
         end
 
-        File.write(source_path, output_lines.join)
+        rendered = output_lines.join
+        return false if rendered == original_content
+
+        AtomicFile.replace(source_path, rendered) do |candidate_path|
+          REXML::Document.new(File.read(candidate_path, encoding: 'UTF-8'))
+        end
+        true
       end
 
       private
 
+      def string_element_at(lines, index)
+        start_match = lines[index].match(/^(\s*)<string(?=\s|>)/)
+        return unless start_match
+
+        opening_tag_lines = []
+        lines[index..].each do |line|
+          opening_tag_lines << line
+          break if line.include?('>')
+        end
+        opening_tag = opening_tag_lines.join
+        opening_tag = opening_tag.split('>', 2).first
+        name_match = opening_tag.match(/\bname\s*=\s*(["'])(.*?)\1/m)
+        return unless name_match
+
+        { indent: start_match[1], key: name_match[2] }
+      end
+
       # Build a lookup that maps base resource names to results.
       # For plural keys like "post_likes_count:one", maps "post_likes_count" to a result.
       # For array keys like "days_of_week[0]", maps "days_of_week" to a result.
@@ -57,7 +85,7 @@ module I18nContextGenerator
         results.sort_by(&:key).each do |r|
           next if source_path && !result_matches_source_path?(r, source_path)
 
-          base = r.key.sub(/:[a-z]+$/, '').sub(/\[\d+\]$/, '')
+          base = AndroidResource.base_key(r.key)
           lookup[base] ||= r
           lookup[r.key] ||= r
         end
@@ -65,7 +93,7 @@ module I18nContextGenerator
       end
 
       def insert_context_comment(output_lines, indent, description)
-        context_text = "#{@context_prefix}#{escape_comment(description)}"
+        context_text = escape_comment("#{@context_prefix}#{description}")
 
         if output_lines.any? && output_lines.last.match?(/^\s*<!--.*-->\s*$/)
           existing_match = output_lines.last.match(/^\s*<!--\s*(.*?)\s*-->\s*$/)
@@ -90,19 +118,17 @@ module I18nContextGenerator
       # so we always treat the preceding comment as replaceable — the user accepted
       # this trade-off by choosing an empty prefix.
       def managed_comment?(comment)
-        @context_prefix.empty? || comment.include?(@context_prefix)
+        GeneratedComment.managed?(comment, prefix: escaped_context_prefix)
       end
 
       def build_comment(existing_comment, context_text)
-        if existing_comment.nil? || existing_comment.empty? || @context_mode == 'replace'
-          context_text
-        elsif !@context_prefix.empty? && existing_comment.include?(@context_prefix)
-          # Replace existing context line (idempotent update)
-          existing_comment.gsub(/#{Regexp.escape(@context_prefix)}[^\n]*/, context_text)
-        else
-          # Append context to existing comment
-          "#{existing_comment} #{context_text}"
-        end
+        GeneratedComment.merge(
+          existing: existing_comment,
+          generated: context_text,
+          prefix: escaped_context_prefix,
+          mode: @context_mode,
+          separator: ' '
+        )
       end
 
       def escape_comment(text)
@@ -112,6 +138,10 @@ module I18nContextGenerator
           .gsub("\n", ' ')
           .strip
       end
+
+      def escaped_context_prefix
+        escape_comment(@context_prefix)
+      end
     end
   end
 end

data/lib/i18n_context_generator/writers/atomic_file.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'tempfile'
+require 'fileutils'
+
+module I18nContextGenerator
+  module Writers
+    # Safely replaces an existing file after optionally validating the candidate.
+    class AtomicFile
+      class << self
+        def replace(path, content)
+          original_mode = File.stat(path).mode & 0o7777
+          directory = File.dirname(File.expand_path(path))
+          basename = File.basename(path)
+          temporary_file = Tempfile.new([".#{basename}.", '.tmp'], directory)
+          temporary_path = temporary_file.path
+
+          begin
+            temporary_file.binmode
+            temporary_file.write(content)
+            temporary_file.flush
+            temporary_file.fsync
+            temporary_file.chmod(original_mode)
+            temporary_file.close
+
+            yield temporary_path if block_given?
+
+            File.rename(temporary_path, path)
+          ensure
+            temporary_file.close unless temporary_file.closed?
+            FileUtils.rm_f(temporary_path)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/i18n_context_generator/writers/csv_writer.rb

@@ -4,30 +4,55 @@ module I18nContextGenerator
   module Writers
     # Writes extraction results to a CSV file.
     class CsvWriter
-      HEADERS = %w[key text description ui_element tone max_length locations error].freeze
+      include ResultSerialization
+
+      HEADERS = %w[
+        schema_version key source_file translation_key text description ui_element
+        tone max_length confidence ambiguity_reason locations changed_locations
+        changed_location_groups changed_translation_locations status cache_hit
+        request_count input_tokens output_tokens retries error
+      ].freeze
       DANGEROUS_CSV_PREFIX = /\A[ \t\r\n]*[=+\-@]/
 
-      def write(results, path)
-        CSV.open(path, 'w') do |csv|
-          csv << HEADERS
-
-          results.sort_by(&:key).each do |result|
-            csv << [
-              sanitize_cell(result.key),
-              sanitize_cell(result.text),
-              sanitize_cell(result.description),
-              sanitize_cell(result.ui_element),
-              sanitize_cell(result.tone),
-              result.max_length,
-              sanitize_cell(result.locations.join(';')),
-              sanitize_cell(result.error)
-            ]
-          end
-        end
+      def write(results, path, output: $stdout, **_options)
+        return write_rows(CSV.new(output), results) if path == '-'
+
+        CSV.open(path, 'w') { |csv| write_rows(csv, results) }
       end
 
       private
 
+      def write_rows(csv, results)
+        csv << HEADERS
+
+        results.sort_by { |result| result_sort_key(result) }.each do |result|
+          csv << [
+            OUTPUT_SCHEMA_VERSION,
+            sanitize_cell(result.key),
+            sanitize_cell(result.source_file),
+            sanitize_cell(result.translation_key),
+            sanitize_cell(result.text),
+            sanitize_cell(result.description),
+            sanitize_cell(result.ui_element),
+            sanitize_cell(result.tone),
+            result.max_length,
+            sanitize_cell(result.confidence),
+            sanitize_cell(result.ambiguity_reason),
+            sanitize_cell(Oj.dump(serialize_locations(result.locations), mode: :compat)),
+            sanitize_cell(Oj.dump(serialize_locations(result.changed_locations), mode: :compat)),
+            sanitize_cell(Oj.dump(serialize_location_groups(result.changed_location_groups), mode: :compat)),
+            sanitize_cell(Oj.dump(serialize_locations(result.changed_translation_locations), mode: :compat)),
+            result.status,
+            result.cache_hit,
+            result.request_count,
+            result.input_tokens,
+            result.output_tokens,
+            result.retries,
+            sanitize_cell(result.error)
+          ]
+        end
+      end
+
       def sanitize_cell(value)
         return value unless value.is_a?(String)
         return value unless value.match?(DANGEROUS_CSV_PREFIX)

data/lib/i18n_context_generator/writers/helpers.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative '../path_policy'
+require_relative '../file_classifier'
+
 module I18nContextGenerator
   module Writers
     # Shared utilities for writer classes (description filtering, file discovery).
@@ -10,6 +13,7 @@ module I18nContextGenerator
 
       def writable_result?(result)
         return false unless result&.description
+        return false if result.respond_to?(:actionable?) && !result.actionable?
         return false unless result.error.nil?
         return false if result.description.strip.empty?
 
@@ -23,35 +27,9 @@ module I18nContextGenerator
       end
 
       def find_swift_files(path, ignore_patterns: [])
-        files = if File.file?(path) && path.end_with?('.swift')
-                  [path]
-                elsif File.directory?(path)
-                  Dir.glob(File.join(path, '**', '*.swift'))
-                else
-                  []
-                end
-
-        filter_ignored_paths(files, ignore_patterns)
-      end
-
-      private
-
-      def filter_ignored_paths(paths, ignore_patterns)
-        compiled_patterns = ignore_patterns.map { |pattern| glob_to_regex(pattern) }
-        paths.reject { |path| ignored_path?(path, compiled_patterns) }.sort
-      end
-
-      def ignored_path?(path, compiled_patterns)
-        compiled_patterns.any? { |pattern| pattern.match?(path) }
-      end
-
-      def glob_to_regex(glob_pattern)
-        regex_str = Regexp.escape(glob_pattern)
-                          .gsub('\*\*/', '(.*/)?')
-                          .gsub('\*\*', '.*')
-                          .gsub('\*', '[^/]*')
-                          .gsub('\?', '.')
-        Regexp.new("(?:^|/)#{regex_str}(?:$|/)")
+        PathPolicy.new(ignore_patterns: ignore_patterns, roots: [path])
+                  .files([path]) { |file| FileClassifier.swift_source?(file) }
+                  .sort
       end
     end
   end

data/lib/i18n_context_generator/writers/json_writer.rb

@@ -6,28 +6,53 @@ module I18nContextGenerator
   module Writers
     # Writes extraction results to a JSON file.
     class JsonWriter
-      def write(results, path)
-        output = {
+      include ResultSerialization
+
+      def write(results, path, metrics: nil, output: $stdout)
+        document = {
+          schema_version: OUTPUT_SCHEMA_VERSION,
           generated_at: Time.now.iso8601,
           version: I18nContextGenerator::VERSION,
           total: results.size,
-          entries: results.sort_by(&:key).map do |result|
+          metrics: metrics&.to_h,
+          entries: results.sort_by { |result| result_sort_key(result) }.map do |result|
             {
               key: result.key,
+              source_file: result.source_file,
+              translation_key: result.translation_key,
               text: result.text,
               context: {
                 description: result.description,
                 ui_element: result.ui_element,
                 tone: result.tone,
-                max_length: result.max_length
+                max_length: result.max_length,
+                confidence: result.confidence,
+                ambiguity_reason: result.ambiguity_reason
+              },
+              locations: serialize_locations(result.locations),
+              changed_locations: serialize_locations(result.changed_locations),
+              changed_location_groups: serialize_location_groups(result.changed_location_groups),
+              changed_translation_locations: serialize_locations(result.changed_translation_locations),
+              status: result.status,
+              telemetry: {
+                cache_hit: result.cache_hit,
+                request_count: result.request_count,
+                input_tokens: result.input_tokens,
+                output_tokens: result.output_tokens,
+                retries: result.retries
               },
-              locations: result.locations,
               error: result.error
             }
           end
         }
 
-        File.write(path, Oj.dump(output, indent: 2, mode: :compat))
+        rendered = Oj.dump(document, indent: 2, mode: :compat)
+        if path == '-'
+          output.write(rendered)
+          output.write("\n") unless rendered.end_with?("\n")
+        else
+          File.write(path, rendered)
+        end
       end
     end
   end

data/lib/i18n_context_generator/writers/preview.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'pathname'
+require 'tempfile'
+
+module I18nContextGenerator
+  module Writers
+    # Renders a writer against a temporary copy and returns a Git-style patch
+    # without mutating the original file.
+    class Preview
+      class << self
+        def render(path)
+          extension = File.extname(path)
+          candidate = Tempfile.new(['i18n-context-preview-', extension])
+          candidate.binmode
+          candidate.write(File.binread(path))
+          candidate.close
+
+          yield candidate.path
+          return nil if File.binread(candidate.path) == File.binread(path)
+
+          unified_diff(path, candidate.path)
+        ensure
+          candidate&.close!
+        end
+
+        private
+
+        def unified_diff(original_path, candidate_path)
+          stdout, stderr, status = Open3.capture3(
+            'git', 'diff', '--no-index', '--no-prefix', '--', original_path, candidate_path
+          )
+          unless [0, 1].include?(status.exitstatus)
+            detail = stderr.strip
+            detail = 'git diff --no-index failed' if detail.empty?
+            raise Error, "Unable to render preview for #{original_path}: #{detail}"
+          end
+
+          sanitize_headers(stdout, original_path)
+        rescue SystemCallError => e
+          raise Error, "Unable to render preview for #{original_path}: #{e.message}"
+        end
+
+        def sanitize_headers(diff, original_path)
+          display_path = display_path_for(original_path)
+          in_hunk = false
+          diff.lines.map do |line|
+            in_hunk = true if line.start_with?('@@ ')
+            if !in_hunk && line.start_with?('diff --git ')
+              "diff --git a/#{display_path} b/#{display_path}\n"
+            elsif !in_hunk && line.start_with?('--- ')
+              "--- a/#{display_path}\n"
+            elsif !in_hunk && line.start_with?('+++ ')
+              "+++ b/#{display_path}\n"
+            else
+              line
+            end
+          end.join
+        end
+
+        def display_path_for(original_path)
+          clean_path = Pathname.new(original_path).cleanpath
+          return clean_path.to_s unless clean_path.absolute?
+
+          directory = File.dirname(clean_path.to_s)
+          stdout, _stderr, status = Open3.capture3('git', 'rev-parse', '--show-toplevel', chdir: directory)
+          if status.success?
+            relative = clean_path.relative_path_from(Pathname.new(stdout.strip)).cleanpath.to_s
+            return relative unless relative == '..' || relative.start_with?('../')
+          end
+
+          clean_path.basename.to_s
+        rescue ArgumentError, SystemCallError
+          clean_path.basename.to_s
+        end
+      end
+    end
+  end
+end

data/lib/i18n_context_generator/writers/result_serialization.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module I18nContextGenerator
+  module Writers
+    # Stable machine-output encoding shared by JSON and CSV writers.
+    module ResultSerialization
+      OUTPUT_SCHEMA_VERSION = 1
+
+      private
+
+      def result_sort_key(result)
+        [result.source_file.to_s, result.translation_key.to_s, result.key]
+      end
+
+      def serialize_locations(locations)
+        Array(locations).map { |location| serialize_location(location) }
+      end
+
+      def serialize_location_groups(groups)
+        Array(groups).map { |group| serialize_locations(group) }
+      end
+
+      def serialize_location(location)
+        return location unless location.is_a?(ChangedLocation)
+
+        location.to_h.transform_values { |value| value.is_a?(Symbol) ? value.to_s : value }
+      end
+    end
+  end
+end