i18n-context-generator 0.4.0 → 0.5.0

data/lib/i18n_context_generator/changed_location.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module I18nContextGenerator
+  # A line in a Git diff, including the revision side needed by review clients.
+  #
+  # `fallback_line` identifies a corresponding line in the head revision. It is
+  # useful when a removed translator comment needs a right-side suggestion anchor.
+  ChangedLocation = Data.define(:file, :line, :side, :fallback_line) do
+    def initialize(file:, line:, side: :right, fallback_line: nil)
+      normalized_side = side.to_s.downcase.to_sym
+      raise ArgumentError, "Unsupported diff side: #{side}" unless %i[left right].include?(normalized_side)
+
+      super(
+        file: file.to_s,
+        line: Integer(line),
+        side: normalized_side,
+        fallback_line: fallback_line && Integer(fallback_line)
+      )
+    end
+
+    def self.parse(value)
+      return value if value.is_a?(self)
+
+      match = /\A(.+):(\d+)\z/.match(value.to_s)
+      raise ArgumentError, "Invalid changed location: #{value.inspect}" unless match
+
+      new(file: match[1], line: match[2], side: :right)
+    end
+
+    def left?
+      side == :left
+    end
+
+    def right?
+      side == :right
+    end
+
+    def review_side
+      side.to_s.upcase
+    end
+
+    def to_s
+      "#{file}:#{line}"
+    end
+
+    def to_h
+      {
+        file: file,
+        line: line,
+        side: side,
+        fallback_line: fallback_line
+      }
+    end
+  end
+end

data/lib/i18n_context_generator/cli.rb

@@ -1,10 +1,39 @@
 # frozen_string_literal: true
 
 require 'thor'
+require_relative 'config'
 
 module I18nContextGenerator
+  # Configuration inspection commands kept separate from extraction options.
+  class ConfigCommand < Thor
+    def self.exit_on_failure?
+      true
+    end
+
+    desc 'validate [PATH]', 'Validate a client configuration file'
+    def validate(path = '.i18n-context-generator.yml')
+      Config.from_file(path).validate!
+      say "Configuration is valid (schema version #{Config::Schema::VERSION}): #{path}"
+    rescue I18nContextGenerator::Error => e
+      warn "Error: #{e.message}"
+      exit 1
+    end
+  end
+
   # Thor-based CLI entry point for the i18n-context-generator command.
   class CLI < Thor
+    register ConfigCommand, 'config', 'config SUBCOMMAND', 'Inspect or validate configuration'
+
+    def self.extraction_options
+      Config::Schema.cli_definitions.each do |definition|
+        option definition.cli_name, **definition.thor_options
+      end
+      option :translations, type: :string, hide: true,
+                            desc: 'Deprecated: comma-separated translation files'
+      option :keys, type: :string, hide: true,
+                    desc: 'Deprecated: comma-separated key filters'
+    end
+
     def self.exit_on_failure?
       true
     end
@@ -28,51 +57,35 @@ module I18nContextGenerator
         # Use config file
         i18n-context-generator extract --config .i18n-context-generator.yml
     DESC
-    option :config, aliases: '-c', desc: 'Path to config file (.i18n-context-generator.yml)'
-    option :translations, aliases: '-t', desc: 'Translation file(s), comma-separated'
-    option :source, aliases: '-s', desc: 'Source directory(ies) to search, comma-separated'
-    option :output, aliases: '-o', desc: 'Output file path (CSV written only if specified)'
-    option :format, aliases: '-f', enum: %w[csv json], desc: 'Output format (default: csv)'
-    option :provider, aliases: '-p', enum: %w[anthropic openai], desc: 'LLM provider (default: anthropic)'
-    option :model, aliases: '-m', desc: 'LLM model to use'
-    option :keys, aliases: '-k', desc: 'Filter keys (comma-separated patterns, supports * wildcard)'
-    option :discovery_mode, type: :string, enum: %w[auto translations source],
-                            desc: 'How to discover entries: auto, translations, or source (default: auto)'
-    option :concurrency, type: :numeric, desc: 'Number of concurrent requests (default: 5)'
-    option :dry_run, type: :boolean, desc: 'Show what would be processed without calling LLM'
-    option :cache, type: :boolean, desc: 'Enable caching of LLM results'
-    option :write_back, type: :boolean,
-                        desc: 'Write context back to source translation files (.strings, strings.xml)'
-    option :write_back_to_code, type: :boolean,
-                                desc: 'Write context back to Swift source code comment: parameters'
-    option :diff_base, type: :string, desc: 'Only process keys changed since this git ref (e.g., main, origin/main)'
-    option :context_prefix, type: :string,
-                            desc: 'Prefix for context comments (default: "Context: ", use empty string for none)'
-    option :context_mode, type: :string, enum: %w[replace append],
-                          desc: 'How to handle existing comments: replace or append (default: replace)'
-    option :start_key, type: :string, desc: 'Start processing from this key (inclusive)'
-    option :end_key, type: :string, desc: 'Stop processing at this key (inclusive)'
-    option :include_file_paths, type: :boolean,
-                                desc: 'Include full source file paths in LLM prompts (default: false)'
-    option :include_translation_comments, type: :boolean,
-                                          desc: 'Include translation file comments in LLM prompts (default: true)'
-    option :redact_prompts, type: :boolean,
-                            desc: 'Redact likely secrets and PII from LLM prompts (default: true)'
+    extraction_options
 
     def extract
-      validate_options!
-      config = Config.load(options)
-      validate_api_key!(provider: config.provider, dry_run: config.dry_run)
-      validate_diff_base!(base_ref: config.diff_base) if config.diff_base
-      extractor = ContextExtractor.new(config)
-      extractor.run
-      fail_if_extraction_errors!(extractor)
-    rescue I18nContextGenerator::Error => e
-      say_error "Error: #{e.message}"
-      exit 1
-    rescue Interrupt
-      say "\nInterrupted"
-      exit 130
+      run_workflow(nil)
+    end
+
+    desc 'check', 'Validate and check source usage without calling the LLM'
+    extraction_options
+    def check
+      run_workflow('check')
+    end
+
+    desc 'plan', 'Show selected keys and destinations without calling the LLM'
+    extraction_options
+    def plan
+      run_workflow('plan')
+    end
+
+    map 'preview-diff' => :preview_diff
+    desc 'preview-diff', 'Generate and preview write-back patches without modifying files'
+    extraction_options
+    def preview_diff
+      run_workflow('preview_diff')
+    end
+
+    desc 'apply', 'Generate context and apply the configured destinations'
+    extraction_options
+    def apply
+      run_workflow('apply')
     end
 
     desc 'init', 'Create a sample config file'
@@ -99,20 +112,52 @@ module I18nContextGenerator
 
     private
 
+    def run_workflow(stage)
+      validate_options!
+      warn_deprecated_list_options!
+      config = Config.load(options)
+      config.merge_cli(workflow_stage: stage) if stage
+      config.validate!
+      if config.print_config
+        puts YAML.dump(config.to_h)
+        return
+      end
+      validate_destination!(config)
+      validate_api_key!(provider: config.provider, dry_run: config.dry_run) unless %w[check plan].include?(config.workflow_stage)
+      validate_diff_range!(base_ref: config.diff_base, head_ref: config.diff_head) if config.diff_base
+      extractor = ContextExtractor.new(config)
+      extractor.run
+      fail_if_extraction_errors!(extractor)
+    rescue I18nContextGenerator::Error => e
+      say_error "Error: #{e.message}"
+      exit 1
+    rescue Interrupt
+      say "\nInterrupted"
+      exit 130
+    end
+
     def validate_options!
-      return if options[:config] && File.exist?(options[:config])
+      return if options[:print_config]
+      return if options[:config]
 
-      return if options[:translations]
+      return if options[:translation] || options[:translations]
       return if options[:discovery_mode] == 'source' && options[:source]
 
-      say_error 'Error: --translations (-t) is required unless using a config file or --discovery-mode source with --source'
+      say_error 'Error: --translation (-t) is required unless using a config file or --discovery-mode source with --source'
       exit 1
     end
 
+    def warn_deprecated_list_options!
+      say_error 'Warning: --translations is deprecated; repeat --translation instead.' if options[:translations]
+      say_error 'Warning: --keys is deprecated; repeat --key instead.' if options[:keys]
+    end
+
     def validate_api_key!(provider: nil, dry_run: nil)
       return if dry_run.nil? ? options[:dry_run] : dry_run
 
       provider ||= options[:provider] || 'anthropic'
+      return if provider == 'openai_compatible'
+
       env_var = case provider
                 when 'anthropic' then 'ANTHROPIC_API_KEY'
                 when 'openai' then 'OPENAI_API_KEY'
@@ -126,17 +171,30 @@ module I18nContextGenerator
       exit 1
     end
 
-    def validate_diff_base!(base_ref: options[:diff_base])
+    def validate_destination!(config)
+      return if %w[check plan].include?(config.workflow_stage)
+      return if config.dry_run
+      return if config.output_path || config.write_back || config.write_back_to_code
+
+      raise Error, 'A non-dry extraction requires --output, --write-back, or --write-back-to-code'
+    end
+
+    def validate_diff_range!(base_ref: options[:diff_base], head_ref: options[:diff_head] || 'HEAD')
       unless GitDiff.available?
         say_error 'Error: --diff-base requires a git repository'
         exit 1
       end
 
-      git_diff = GitDiff.new(base_ref: base_ref)
-      return if git_diff.base_ref_exists?
+      git_diff = GitDiff.new(base_ref: base_ref, head_ref: head_ref)
+      unless git_diff.base_ref_exists?
+        say_error "Error: git ref '#{base_ref}' not found"
+        say_error 'Try: origin/main, main, or a specific commit SHA'
+        exit 1
+      end
+      return if git_diff.head_ref_exists?
 
-      say_error "Error: git ref '#{base_ref}' not found"
-      say_error 'Try: origin/main, main, or a specific commit SHA'
+      say_error "Error: git ref '#{head_ref}' not found"
+      say_error 'Try: HEAD, a branch name, or a specific commit SHA'
       exit 1
     end
 
@@ -152,12 +210,16 @@ module I18nContextGenerator
     end
 
     def sample_config
+      schema = Config::Schema
+      swift_functions = schema.default(:swift_functions).map { |function| "    - #{function.inspect}" }.join("\n")
+
       <<~YAML
         # i18n-context-generator configuration
         # Extract translation context from mobile app source code
+        schema_version: #{schema.default(:schema_version)}
 
         # Translation files to process
-        # Supported formats: .strings (iOS), strings.xml (Android), .json, .yml
+        # Supported formats: .strings/.xcstrings (iOS), strings.xml (Android), .json, .yml
         translations:
           # iOS example
           - path: ios/MyApp/Resources/Localizable.strings
@@ -165,63 +227,88 @@ module I18nContextGenerator
           # Android example
           # - path: android/app/src/main/res/values/strings.xml
 
+          # YAML locale roots are stripped only when configured explicitly
+          # - path: config/translations.yml
+          #   locale: en
+
         # Source code directories to search
         source:
           paths:
             - ios/MyApp/
             # - android/app/src/main/java/
+          # These entries extend the built-in dependency, build, and test ignores.
           ignore:
-            - "**/Pods/**"
-            - "**/build/**"
             - "**/*.generated.*"
-            - "**/*Tests*"
+
+        # Optional free-form reference material included in every LLM request.
+        context:
+          files: []
+          # - GLOSSARY.md
+          # - docs/localization-style.md
 
         # LLM configuration
         llm:
-          provider: anthropic
-          model: claude-sonnet-4-6
+          provider: #{schema.default(:provider)}
+          # model: provider-specific default
+          # For provider: openai_compatible, set an explicit model and endpoint.
+          # endpoint: http://127.0.0.1:11434/v1/responses
           # API key is read from the matching provider env var
           # (ANTHROPIC_API_KEY or OPENAI_API_KEY)
 
         # Processing options
         processing:
+          # Optional explicit platform override: ios or android
+          # platform: ios
           # Discovery mode: auto, translations, or source
-          discovery_mode: auto
-          concurrency: 5
-          context_lines: 15
-          max_matches_per_key: 3
+          discovery_mode: #{schema.default(:discovery_mode)}
+          concurrency: #{schema.default(:concurrency)}
+          context_lines: #{schema.default(:context_lines)}
+          max_matches_per_key: #{schema.default(:max_matches_per_key)}
+          # Hard character limit for each prompt; oversized context is truncated
+          max_prompt_chars: #{schema.default(:max_prompt_chars)}
+
+        # Optional local cache. Only successful results are cached.
+        cache:
+          enabled: #{schema.default(:cache_enabled)}
+          directory: #{schema.default(:cache_dir)}
+
+        # Default workflow for programmatic/config-file runs.
+        workflow:
+          stage: #{schema.default(:workflow_stage)}
 
         # Output configuration
         output:
-          format: csv
+          format: #{schema.default(:output_format)}
           path: translation-context.csv
-          # Set to true to write context comments back to translation files (.strings, strings.xml)
-          write_back: false
+          # Write the selected CSV/JSON format to stdout instead of a file.
+          stdout: #{schema.default(:output_stdout)}
+          # Set to true to write context comments back to translation files
+          # (.strings, .xcstrings, strings.xml)
+          write_back: #{schema.default(:write_back)}
           # Set to true to write context back to Swift source code comment: parameters
-          write_back_to_code: false
+          write_back_to_code: #{schema.default(:write_back_to_code)}
           # Prefix for context comments (use empty string for no prefix)
-          # context_prefix: "Context: "
+          # context_prefix: #{schema.default(:context_prefix).inspect}
           # How to handle existing comments: "replace" or "append"
-          # context_mode: replace
+          # context_mode: #{schema.default(:context_mode)}
 
-        # Swift-specific configuration for write_back_to_code
+        # Swift-specific extraction and write-back configuration
         swift:
-          # Localization functions to update (default shown)
+          # Custom entries extend the built-in localization functions (defaults shown)
           functions:
-            - NSLocalizedString
-            - "String(localized:"
-            - "Text("
+        #{swift_functions}
             # Add custom functions like:
             # - "MyLocalizedString("
 
         # Prompt privacy controls
         privacy:
           # Include full source paths in prompts sent to the LLM (default: false)
-          include_file_paths: false
+          include_file_paths: #{schema.default(:include_file_paths)}
           # Include translation file comments in prompts (default: true)
-          include_translation_comments: true
-          # Redact likely secrets, URLs, and emails before sending prompts (default: true)
-          redact_prompts: true
+          include_translation_comments: #{schema.default(:include_translation_comments)}
+          # Best-effort redact likely secrets, URLs, and emails before sending prompts.
+          # Source snippets still leave the machine when using a remote provider.
+          redact_prompts: #{schema.default(:redact_prompts)}
       YAML
     end
   end

data/lib/i18n_context_generator/config/cli_values.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module I18nContextGenerator
+  class Config
+    # Normalizes repeatable singular CLI values while retaining explicit legacy
+    # comma-list support.
+    module CliValues
+      def cli_path_list(values, legacy: nil)
+        repeatable = Array(values).filter_map do |value|
+          normalized = value.to_s.strip
+          normalized unless normalized.empty?
+        end
+        (repeatable + split_legacy_list(legacy)).uniq
+      end
+
+      def cli_key_filters(values, legacy: nil)
+        repeatable = Array(values).filter_map do |value|
+          normalized = value.to_s.strip
+          normalized unless normalized.empty?
+        end
+        repeatable + split_legacy_list(legacy)
+      end
+
+      private
+
+      def split_legacy_list(value)
+        Array(value).flat_map { |item| item.to_s.split(',') }
+                    .map(&:strip)
+                    .reject(&:empty?)
+      end
+    end
+  end
+end

data/lib/i18n_context_generator/config/defaults.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module I18nContextGenerator
+  class Config
+    # Built-in source exclusions and their additive merge policy.
+    module Defaults
+      def default_ignore_patterns
+        [
+          '**/node_modules/**',
+          '**/vendor/**',
+          '**/.git/**',
+          '**/build/**',
+          '**/dist/**',
+          '**/*.min.js',
+          '**/*.test.*',
+          '**/*.spec.*',
+          '**/Pods/**',
+          '**/Carthage/**',
+          '**/.build/**',
+          '**/DerivedData/**',
+          '**/*Tests.swift',
+          '**/*Tests.kt',
+          '**/*Test.java',
+          '**/*Test.kt'
+        ]
+      end
+
+      def merge_ignore_patterns(patterns)
+        return patterns unless patterns.is_a?(Array)
+
+        (default_ignore_patterns + patterns).compact.uniq
+      end
+    end
+  end
+end