i18n-context-generator 0.4.0 → 0.5.1

data/lib/i18n_context_generator/writers/strings_writer.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../generated_comment'
+
 module I18nContextGenerator
   module Writers
     # Writer that updates iOS .strings files with context comments
@@ -15,6 +17,7 @@ module I18nContextGenerator
       def write(results, source_path)
         return unless File.exist?(source_path)
 
+        original_content = File.binread(source_path)
         # Parse the existing file
         original_file = DotStrings.parse_file(source_path, strict: false)
         results_by_key = results.each_with_object({}) do |result, lookup|
@@ -22,6 +25,7 @@ module I18nContextGenerator
 
           lookup[result.key] = result
         end
+        return false unless results_by_key.values.any? { |result| writable_result?(result) }
 
         # Build new file with updated comments (DotStrings::Item is immutable)
         new_file = DotStrings::File.new
@@ -43,24 +47,31 @@ module I18nContextGenerator
           new_file << new_item
         end
 
-        # Write back to file
-        File.write(source_path, new_file.to_s)
+        rendered = new_file.to_s
+        return false if rendered == original_content
+
+        AtomicFile.replace(source_path, rendered) do |candidate_path|
+          DotStrings.parse_file(candidate_path, strict: true)
+        end
+        true
       end
 
       private
 
       def build_comment(existing_comment, context_description)
-        context_line = "#{@context_prefix}#{context_description}"
+        context_line = sanitize_comment("#{@context_prefix}#{context_description}")
+        context_prefix = sanitize_comment(@context_prefix)
+        GeneratedComment.merge(
+          existing: existing_comment,
+          generated: context_line,
+          prefix: context_prefix,
+          mode: @context_mode,
+          separator: "\n"
+        )
+      end
 
-        if existing_comment.nil? || existing_comment.empty? || @context_mode == 'replace'
-          context_line
-        elsif !@context_prefix.empty? && existing_comment.include?(@context_prefix)
-          # Replace existing context line (idempotent update)
-          existing_comment.gsub(/#{Regexp.escape(@context_prefix)}[^\n]*/, context_line)
-        else
-          # Append context to existing comment
-          "#{existing_comment}\n#{context_line}"
-        end
+      def sanitize_comment(comment)
+        comment.gsub('*/', '* /')
       end
     end
   end

data/lib/i18n_context_generator/writers/swift_writer.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative '../generated_comment'
+require_relative '../localization_syntax'
+
 module I18nContextGenerator
   module Writers
     # Writer that updates comment: parameters in Swift localization calls
@@ -7,20 +10,11 @@ module I18nContextGenerator
     class SwiftWriter
       include Helpers
 
-      SWIFT_STRING_PATTERN = '"(?:\\\\.|[^"\\\\])*"'
       COMMENT_ARGUMENT_PATTERN = /comment:\s*"((?:\\.|[^"\\])*)"/
-      private_constant :SWIFT_STRING_PATTERN, :COMMENT_ARGUMENT_PATTERN
-
-      # Default patterns for Swift localization functions
-      # Each pattern should capture: (prefix)(key)(middle)(comment_value)(suffix)
-      DEFAULT_FUNCTIONS = %w[
-        NSLocalizedString
-        String(localized:
-        Text(
-      ].freeze
+      private_constant :COMMENT_ARGUMENT_PATTERN
 
       def initialize(functions: nil, context_prefix: 'Context: ', context_mode: 'replace')
-        @functions = functions || DEFAULT_FUNCTIONS
+        @localization_syntax = LocalizationSyntax.new(swift_functions: functions)
         @context_prefix = context_prefix
         @context_mode = context_mode
       end
@@ -61,7 +55,7 @@ module I18nContextGenerator
         end
 
         if updated && content != original_content
-          File.write(path, content)
+          AtomicFile.replace(path, content)
           true
         else
           false
@@ -72,46 +66,17 @@ module I18nContextGenerator
 
       # Update comment for a specific key in the content
       def update_comment_for_key(content, key, description)
-        escaped_key = Regexp.escape(key)
-
-        @functions.each do |func|
-          # Build pattern based on function type
-          pattern = build_pattern_for_function(func, escaped_key)
-          next unless pattern
-
+        @localization_syntax.swift_writer_patterns(key).each do |pattern|
           # Try to match and replace
           content = content.gsub(pattern) do |match|
-            update_match(match, func, key, description)
+            update_match(match, description)
           end
         end
 
         content
       end
 
-      def build_pattern_for_function(func, escaped_key)
-        comment_pattern = "comment:\\s*#{SWIFT_STRING_PATTERN}"
-
-        case func
-        when 'NSLocalizedString'
-          # NSLocalizedString("key", comment: "...")
-          # NSLocalizedString("key", value: "...", comment: "...")
-          # NSLocalizedString("key", tableName: "...", comment: "...")
-          Regexp.new("NSLocalizedString\\(\\s*\"#{escaped_key}\"[^)]*#{comment_pattern}[^)]*\\)", Regexp::MULTILINE)
-        when 'String(localized:'
-          # String(localized: "key", comment: "...")
-          Regexp.new("String\\(\\s*localized:\\s*\"#{escaped_key}\"[^)]*#{comment_pattern}[^)]*\\)", Regexp::MULTILINE)
-        when 'Text('
-          # Text("key", comment: "...")
-          # Text(LocalizedStringKey("key"), comment: "...")
-          Regexp.new("Text\\([^)]*\"#{escaped_key}\"[^)]*#{comment_pattern}[^)]*\\)", Regexp::MULTILINE)
-        else
-          # Custom function - assume pattern like: func("key", ..., comment: "...")
-          escaped_func = Regexp.escape(func)
-          Regexp.new("#{escaped_func}\\([^)]*\"#{escaped_key}\"[^)]*#{comment_pattern}[^)]*\\)", Regexp::MULTILINE)
-        end
-      end
-
-      def update_match(match, _func, _key, new_comment)
+      def update_match(match, new_comment)
         # Replace the comment value while preserving the rest of the call
         match.gsub(COMMENT_ARGUMENT_PATTERN) do |_comment_match|
           existing_comment = unescape_swift_string(Regexp.last_match(1))
@@ -122,16 +87,13 @@ module I18nContextGenerator
 
       def build_final_comment(existing_comment, new_context)
         context_line = "#{@context_prefix}#{new_context}"
-
-        if existing_comment.nil? || existing_comment.empty? || @context_mode == 'replace'
-          context_line
-        elsif !@context_prefix.empty? && existing_comment.include?(@context_prefix)
-          # Update existing context line (idempotent)
-          existing_comment.gsub(/#{Regexp.escape(@context_prefix)}[^\n]*/, context_line)
-        else
-          # Append context to existing comment
-          "#{existing_comment} #{context_line}"
-        end
+        GeneratedComment.merge(
+          existing: existing_comment,
+          generated: context_line,
+          prefix: @context_prefix,
+          mode: @context_mode,
+          separator: ' '
+        )
       end
 
       def escape_swift_string(str)

data/lib/i18n_context_generator/writers/xcstrings_writer.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative '../generated_comment'
+
+module I18nContextGenerator
+  module Writers
+    # Updates developer comments in Apple string catalogs while leaving every
+    # localization and extraction attribute intact.
+    class XcstringsWriter
+      include Helpers
+
+      def initialize(context_prefix: 'Context: ', context_mode: 'replace')
+        @context_prefix = context_prefix
+        @context_mode = context_mode
+      end
+
+      def write(results, source_path)
+        return unless File.exist?(source_path)
+
+        original = File.binread(source_path)
+        document = XcstringsDocument.new(original, path: source_path)
+        catalog = document.catalog
+        Parsers::XcstringsParser.validate_catalog!(catalog, path: source_path)
+        results_by_key = results.each_with_object({}) do |result, lookup|
+          next unless result_matches_source_path?(result, source_path)
+          next unless writable_result?(result)
+
+          lookup[result.key] = result
+        end
+        return false if results_by_key.empty?
+
+        comments_by_key = catalog.fetch('strings').each_with_object({}) do |(key, entry), comments|
+          result = results_by_key[key]
+          next unless result
+
+          comments[key] = GeneratedComment.merge(
+            existing: entry['comment'],
+            generated: "#{@context_prefix}#{result.description}",
+            prefix: @context_prefix,
+            mode: @context_mode,
+            separator: "\n"
+          )
+        end
+        rendered = document.with_comments(comments_by_key)
+        return false if rendered == original
+
+        AtomicFile.replace(source_path, rendered) do |candidate_path|
+          candidate = Oj.load_file(candidate_path, mode: :strict)
+          Parsers::XcstringsParser.validate_catalog!(candidate, path: candidate_path)
+        end
+        true
+      rescue Oj::ParseError => e
+        raise Error, "Failed to parse Apple string catalog #{source_path}: #{e.message}"
+      end
+    end
+  end
+end

data/lib/i18n_context_generator/xcstrings_document.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'oj'
+
+module I18nContextGenerator
+  # Structural index for an Apple string catalog that retains byte offsets in
+  # the original JSON. It lets write-back edit only owned comment values and
+  # lets diff handling map revision-specific line numbers without reformatting.
+  class XcstringsDocument
+    Member = Data.define(:key, :key_start, :key_end, :value_start, :value_end, :separator)
+    BYTE = {
+      backslash: '\\'.ord,
+      close_array: ']'.ord,
+      close_object: '}'.ord,
+      colon: ':'.ord,
+      comma: ','.ord,
+      newline: "\n".ord,
+      open_array: '['.ord,
+      open_object: '{'.ord,
+      quote: '"'.ord
+    }.freeze
+    JSON_WHITESPACE_BYTES = ["\t".ord, "\n".ord, "\r".ord, ' '.ord].freeze
+    PRIMITIVE_TERMINATOR_BYTES = [
+      BYTE[:comma],
+      BYTE[:close_object],
+      BYTE[:close_array],
+      *JSON_WHITESPACE_BYTES
+    ].freeze
+    private_constant :BYTE, :JSON_WHITESPACE_BYTES, :PRIMITIVE_TERMINATOR_BYTES
+
+    attr_reader :catalog
+
+    def initialize(content, path:)
+      @content = content
+      @path = path
+      @catalog = Oj.load(content, mode: :strict)
+      @line_starts = [0]
+      content.each_byte.with_index { |byte, index| @line_starts << (index + 1) if byte == BYTE[:newline] }
+      @root_members = object_members(skip_whitespace(0))
+      strings_member = @root_members.find { |member| member.key == 'strings' }
+      strings_object = strings_member && byte_at(strings_member.value_start) == BYTE[:open_object]
+      raise TypeError, 'strings must be a mapping' unless strings_object
+
+      @strings_member = strings_member
+      @entry_members = object_members(strings_member.value_start)
+      @entries_by_key = @entry_members.to_h { |member| [member.key, member] }
+    rescue Oj::ParseError, TypeError => e
+      raise Error, "Failed to parse Apple string catalog #{path}: #{e.message}"
+    end
+
+    def line_index
+      @entry_members.each_with_object({}) do |member, index|
+        start_line = line_number(member.key_start)
+        end_line = line_number(member.value_end - 1)
+        (start_line..end_line).each { |line| index[line] = member.key }
+      end
+    end
+
+    def with_comments(comments_by_key)
+      edits = comments_by_key.filter_map do |key, comment|
+        entry_member = @entries_by_key[key]
+        next unless entry_member && byte_at(entry_member.value_start) == BYTE[:open_object]
+        next if @catalog.dig('strings', key, 'comment') == comment
+
+        comment_edit(entry_member, comment)
+      end
+      return @content if edits.empty?
+
+      original_encoding = @content.encoding
+      rendered = @content.b
+      edits.sort_by(&:first).reverse_each do |start_offset, end_offset, replacement|
+        rendered[start_offset...end_offset] = replacement.b
+      end
+      rendered.force_encoding(original_encoding)
+    end
+
+    private
+
+    def comment_edit(entry_member, comment)
+      children = object_members(entry_member.value_start)
+      existing = children.find { |member| member.key == 'comment' }
+      encoded_comment = JSON.generate(comment)
+      return [existing.value_start, existing.value_end, encoded_comment] if existing
+
+      insert_comment_edit(entry_member, children, encoded_comment)
+    end
+
+    def insert_comment_edit(entry_member, children, encoded_comment)
+      separator = children.first&.separator || entry_member.separator
+      if inline_member?(entry_member)
+        insertion_point = entry_member.value_start + 1
+        rendered_comment = "\"comment\"#{separator}#{encoded_comment}"
+        rendered_comment = "#{rendered_comment}," unless children.empty?
+        return [insertion_point, insertion_point, rendered_comment]
+      end
+
+      entry_indent = line_indent(entry_member.key_start)
+      child_indent = children.empty? ? "#{entry_indent}#{indent_unit}" : line_indent(children.first.key_start)
+      child_indent = "#{entry_indent}#{indent_unit}" unless child_indent.match?(/\A\s*\z/)
+      rendered_comment = "#{child_indent}\"comment\"#{separator}#{encoded_comment}"
+
+      if children.empty?
+        interior_start = entry_member.value_start + 1
+        interior_end = entry_member.value_end - 1
+        replacement = "#{newline}#{rendered_comment}#{newline}#{entry_indent}"
+        [interior_start, interior_end, replacement]
+      else
+        insertion_point = entry_member.value_start + 1
+        [insertion_point, insertion_point, "#{newline}#{rendered_comment},"]
+      end
+    end
+
+    def inline_member?(member)
+      !line_indent(member.key_start).match?(/\A[ \t]*\z/)
+    end
+
+    def indent_unit
+      @indent_unit ||= begin
+        strings_indent = line_indent(@strings_member.key_start)
+        block_entry = @entry_members.find { |member| !inline_member?(member) }
+        entry_indent = line_indent(block_entry&.key_start || @strings_member.key_start)
+        difference = entry_indent.delete_prefix(strings_indent)
+        difference.empty? || !difference.match?(/\A[ \t]*\z/) ? '  ' : difference
+      end
+    end
+
+    def newline
+      @newline ||= @content.include?("\r\n") ? "\r\n" : "\n"
+    end
+
+    def line_indent(offset)
+      following_line = @line_starts.bsearch_index { |line_start| line_start > offset }
+      line_start = following_line ? @line_starts.fetch(following_line - 1) : @line_starts.last
+      byte_slice(line_start, offset)
+    end
+
+    def line_number(offset)
+      @line_starts.bsearch_index { |line_start| line_start > offset } || @line_starts.length
+    end
+
+    def object_members(object_start)
+      raise TypeError, "expected object at byte #{object_start}" unless byte_at(object_start) == BYTE[:open_object]
+
+      members = []
+      cursor = skip_whitespace(object_start + 1)
+      return members if byte_at(cursor) == BYTE[:close_object]
+
+      loop do
+        key_start = cursor
+        key_end = string_end(key_start)
+        key = JSON.parse(byte_slice(key_start, key_end))
+        cursor = skip_whitespace(key_end)
+        raise TypeError, "expected ':' at byte #{cursor}" unless byte_at(cursor) == BYTE[:colon]
+
+        cursor = skip_whitespace(cursor + 1)
+        value_start = cursor
+        value_end = value_end(value_start)
+        members << Member.new(
+          key: key,
+          key_start: key_start,
+          key_end: key_end,
+          value_start: value_start,
+          value_end: value_end,
+          separator: byte_slice(key_end, value_start)
+        )
+        cursor = skip_whitespace(value_end)
+        break if byte_at(cursor) == BYTE[:close_object]
+
+        raise TypeError, "expected ',' at byte #{cursor}" unless byte_at(cursor) == BYTE[:comma]
+
+        cursor = skip_whitespace(cursor + 1)
+      end
+
+      members
+    end
+
+    def value_end(start_offset)
+      case byte_at(start_offset)
+      when BYTE[:quote]
+        string_end(start_offset)
+      when BYTE[:open_object]
+        collection_end(start_offset, BYTE[:open_object], BYTE[:close_object])
+      when BYTE[:open_array]
+        collection_end(start_offset, BYTE[:open_array], BYTE[:close_array])
+      else
+        primitive_end(start_offset)
+      end
+    end
+
+    def string_end(start_offset)
+      cursor = start_offset + 1
+      escaped = false
+      while cursor < @content.bytesize
+        byte = byte_at(cursor)
+        if escaped
+          escaped = false
+        elsif byte == BYTE[:backslash]
+          escaped = true
+        elsif byte == BYTE[:quote]
+          return cursor + 1
+        end
+        cursor += 1
+      end
+      raise TypeError, "unterminated string at byte #{start_offset}"
+    end
+
+    def collection_end(start_offset, opening, closing)
+      depth = 0
+      cursor = start_offset
+      while cursor < @content.bytesize
+        byte = byte_at(cursor)
+        case byte
+        when BYTE[:quote]
+          cursor = string_end(cursor)
+          next
+        when opening
+          depth += 1
+        when closing
+          depth -= 1
+          return cursor + 1 if depth.zero?
+        end
+        cursor += 1
+      end
+      raise TypeError, "unterminated collection at byte #{start_offset}"
+    end
+
+    def primitive_end(start_offset)
+      cursor = start_offset
+      cursor += 1 while cursor < @content.bytesize && !PRIMITIVE_TERMINATOR_BYTES.include?(byte_at(cursor))
+      cursor
+    end
+
+    def skip_whitespace(offset)
+      cursor = offset
+      cursor += 1 while cursor < @content.bytesize && JSON_WHITESPACE_BYTES.include?(byte_at(cursor))
+      cursor
+    end
+
+    def byte_at(offset)
+      @content.getbyte(offset)
+    end
+
+    def byte_slice(start_offset, end_offset)
+      @content.byteslice(start_offset...end_offset)
+    end
+  end
+end

data/lib/i18n_context_generator/xml_scanner.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module I18nContextGenerator
+  # Small stateful XML scanning helpers for line-oriented diff and location code.
+  # This is intentionally not an XML parser; it only removes comments while
+  # preserving the remaining text and line boundaries.
+  module XmlScanner
+    module_function
+
+    def without_comments(line, state)
+      remaining = line.to_s
+      visible = +''
+      contained_comment = false
+
+      loop do
+        if state[:inside_comment]
+          contained_comment = true
+          comment_end = remaining.index('-->')
+          return [visible, contained_comment] unless comment_end
+
+          state[:inside_comment] = false
+          remaining = remaining[(comment_end + 3)..].to_s
+        else
+          comment_start = remaining.index('<!--')
+          unless comment_start
+            visible << remaining
+            return [visible, contained_comment]
+          end
+
+          visible << remaining[0...comment_start]
+          contained_comment = true
+          state[:inside_comment] = true
+          remaining = remaining[(comment_start + 4)..].to_s
+        end
+      end
+    end
+  end
+end

data/lib/i18n_context_generator.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+module I18nContextGenerator
+  class Error < StandardError; end
+end
+
 require 'yaml'
 require 'csv'
 require 'digest'
@@ -10,27 +14,39 @@ require 'tty-progressbar'
 require 'dotstrings'
 
 require_relative 'i18n_context_generator/version'
+require_relative 'i18n_context_generator/path_policy'
+require_relative 'i18n_context_generator/file_classifier'
+require_relative 'i18n_context_generator/supplemental_context'
+require_relative 'i18n_context_generator/apple_string_literal'
+require_relative 'i18n_context_generator/changed_location'
+require_relative 'i18n_context_generator/localization_syntax'
+require_relative 'i18n_context_generator/generated_comment'
+require_relative 'i18n_context_generator/android_resource'
+require_relative 'i18n_context_generator/xcstrings_document'
 require_relative 'i18n_context_generator/config'
 require_relative 'i18n_context_generator/parsers/base'
 require_relative 'i18n_context_generator/parsers/json_parser'
 require_relative 'i18n_context_generator/parsers/yaml_parser'
 require_relative 'i18n_context_generator/parsers/strings_parser'
+require_relative 'i18n_context_generator/parsers/xcstrings_parser'
 require_relative 'i18n_context_generator/parsers/android_xml_parser'
 require_relative 'i18n_context_generator/searcher'
 require_relative 'i18n_context_generator/llm/client'
 require_relative 'i18n_context_generator/llm/anthropic'
 require_relative 'i18n_context_generator/llm/openai'
+require_relative 'i18n_context_generator/llm/openai_compatible'
 require_relative 'i18n_context_generator/writers/helpers'
+require_relative 'i18n_context_generator/writers/result_serialization'
+require_relative 'i18n_context_generator/writers/atomic_file'
+require_relative 'i18n_context_generator/writers/preview'
 require_relative 'i18n_context_generator/writers/csv_writer'
 require_relative 'i18n_context_generator/writers/json_writer'
 require_relative 'i18n_context_generator/writers/strings_writer'
+require_relative 'i18n_context_generator/writers/xcstrings_writer'
 require_relative 'i18n_context_generator/writers/android_xml_writer'
 require_relative 'i18n_context_generator/writers/swift_writer'
 require_relative 'i18n_context_generator/cache'
 require_relative 'i18n_context_generator/git_diff'
 require_relative 'i18n_context_generator/platform_validator'
+require_relative 'i18n_context_generator/run_metrics'
 require_relative 'i18n_context_generator/context_extractor'
-
-module I18nContextGenerator
-  class Error < StandardError; end
-end