i18n-context-generator 0.4.0 → 0.5.1

data/lib/i18n_context_generator/config/schema.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+require_relative '../localization_syntax'
+
+module I18nContextGenerator
+  class Config
+    # Typed registry for client-facing configuration. CLI metadata and sample
+    # configuration defaults are derived from these definitions.
+    module Schema
+      VERSION = 1
+      DOCUMENT_KEYS = %w[
+        schema_version translations source context llm processing cache output swift privacy workflow
+      ].freeze
+      SECTION_KEYS = {
+        'source' => %w[paths ignore],
+        'context' => %w[files],
+        'llm' => %w[provider model endpoint],
+        'processing' => %w[
+          concurrency context_lines max_matches_per_key max_prompt_chars discovery_mode platform
+        ],
+        'cache' => %w[enabled directory],
+        'output' => %w[path format stdout write_back write_back_to_code context_prefix context_mode],
+        'swift' => %w[functions],
+        'privacy' => %w[include_file_paths include_translation_comments redact_prompts],
+        'workflow' => %w[stage]
+      }.freeze
+
+      Definition = Data.define(:name, :type, :default, :values, :yaml_path, :cli) do
+        def initialize(name:, type:, default:, values:, yaml_path:, cli:)
+          default.freeze if default.respond_to?(:freeze)
+          super(
+            name: name,
+            type: type,
+            default: default,
+            values: values&.freeze,
+            yaml_path: yaml_path&.freeze,
+            cli: cli&.freeze
+          )
+        end
+
+        def cli?
+          !cli.nil?
+        end
+
+        def cli_name
+          cli.fetch(:name, name)
+        end
+
+        def thor_options
+          options = { desc: help_description }
+          options[:aliases] = cli[:aliases] if cli[:aliases]
+          options[:type] = cli.fetch(:type) { Schema.thor_type(type) }
+          options[:enum] = values if values
+          options[:repeatable] = true if cli[:repeatable]
+          options
+        end
+
+        private
+
+        def help_description
+          return cli[:description] unless cli[:show_default]
+
+          label = cli[:default_note]&.then { |note| format(note, default) }
+          label ||= cli[:quote_default] ? default.inspect : default.to_s
+          "#{cli[:description]} (default: #{label})"
+        end
+      end
+
+      DEFINITIONS = [
+        Definition.new(name: :config, type: :string, default: nil, values: nil, yaml_path: nil,
+                       cli: { aliases: '-c', description: 'Path to config file (.i18n-context-generator.yml)' }),
+        Definition.new(name: :schema_version, type: :integer, default: VERSION, values: [VERSION],
+                       yaml_path: ['schema_version'], cli: nil),
+        Definition.new(name: :translations, type: :array, default: [], values: nil, yaml_path: ['translations'],
+                       cli: { name: :translation, type: :string, repeatable: true, aliases: '-t',
+                              description: 'Translation file (repeat for multiple files)' }),
+        Definition.new(name: :source_paths, type: :array, default: ['.'], values: nil, yaml_path: %w[source paths],
+                       cli: { name: :source, type: :string, repeatable: true, aliases: '-s',
+                              description: 'Source file or directory (repeat for multiple paths)' }),
+        Definition.new(name: :ignore_patterns, type: :array, default: [], values: nil, yaml_path: %w[source ignore], cli: nil),
+        Definition.new(name: :context_files, type: :array, default: [], values: nil, yaml_path: %w[context files],
+                       cli: { name: :context_file, type: :string, repeatable: true,
+                              description: 'Supplemental context file (repeat for multiple files)' }),
+        Definition.new(name: :provider, type: :string, default: 'anthropic',
+                       values: %w[anthropic openai openai_compatible], yaml_path: %w[llm provider],
+                       cli: { aliases: '-p', description: 'LLM provider', show_default: true }),
+        Definition.new(name: :model, type: :string, default: nil, values: nil, yaml_path: %w[llm model],
+                       cli: { aliases: '-m', description: 'LLM model to use (provider default when omitted)' }),
+        Definition.new(name: :endpoint, type: :string, default: nil, values: nil, yaml_path: %w[llm endpoint],
+                       cli: { description: 'Explicit OpenAI-compatible Responses API endpoint' }),
+        Definition.new(name: :concurrency, type: :integer, default: 5, values: nil, yaml_path: %w[processing concurrency],
+                       cli: { description: 'Number of concurrent requests', show_default: true }),
+        Definition.new(name: :context_lines, type: :integer, default: 15, values: nil, yaml_path: %w[processing context_lines], cli: nil),
+        Definition.new(name: :max_matches_per_key, type: :integer, default: 3, values: nil,
+                       yaml_path: %w[processing max_matches_per_key], cli: nil),
+        Definition.new(name: :max_prompt_chars, type: :integer, default: 50_000, values: nil,
+                       yaml_path: %w[processing max_prompt_chars],
+                       cli: { description: 'Maximum characters sent per LLM prompt', show_default: true }),
+        Definition.new(name: :discovery_mode, type: :string, default: 'auto', values: %w[auto translations source],
+                       yaml_path: %w[processing discovery_mode],
+                       cli: { description: 'How to discover entries: auto, translations, or source', show_default: true }),
+        Definition.new(name: :platform, type: :string, default: nil, values: %w[ios android], yaml_path: %w[processing platform],
+                       cli: { description: 'Explicit platform override: ios or android' }),
+        Definition.new(name: :output_path, type: :string, default: nil, values: nil, yaml_path: %w[output path],
+                       cli: { name: :output, aliases: '-o', description: 'Output file path (.csv or .json; format inferred when omitted)' }),
+        Definition.new(name: :output_format, type: :string, default: 'csv', values: %w[csv json], yaml_path: %w[output format],
+                       cli: { name: :format, aliases: '-f', description: 'Output format', show_default: true,
+                              default_note: 'inferred from output path; fallback %s' }),
+        Definition.new(name: :output_stdout, type: :boolean, default: false, values: nil,
+                       yaml_path: %w[output stdout],
+                       cli: { name: :stdout, description: 'Write structured CSV or JSON to stdout' }),
+        Definition.new(name: :write_back, type: :boolean, default: false, values: nil, yaml_path: %w[output write_back],
+                       cli: { description: 'Write context back to translation files (.strings, .xcstrings, strings.xml)',
+                              show_default: true }),
+        Definition.new(name: :write_back_to_code, type: :boolean, default: false, values: nil,
+                       yaml_path: %w[output write_back_to_code],
+                       cli: { description: 'Write context back to Swift source code comment: parameters', show_default: true }),
+        Definition.new(name: :context_prefix, type: :string, default: 'Context: ', values: nil, yaml_path: %w[output context_prefix],
+                       cli: { description: 'Prefix for generated context comments', show_default: true, quote_default: true }),
+        Definition.new(name: :context_mode, type: :string, default: 'replace', values: %w[replace append], yaml_path: %w[output context_mode],
+                       cli: { description: 'How to handle existing comments: replace or append', show_default: true }),
+        Definition.new(name: :swift_functions, type: :array, default: LocalizationSyntax::DEFAULT_SWIFT_FUNCTIONS,
+                       values: nil, yaml_path: %w[swift functions], cli: nil),
+        Definition.new(name: :cache_enabled, type: :boolean, default: false, values: nil, yaml_path: %w[cache enabled],
+                       cli: { name: :cache, description: 'Enable caching of successful LLM results', show_default: true }),
+        Definition.new(name: :cache_dir, type: :string, default: '.i18n-context-generator-cache', values: nil,
+                       yaml_path: %w[cache directory],
+                       cli: { description: 'Cache directory', show_default: true }),
+        Definition.new(name: :dry_run, type: :boolean, default: false, values: nil, yaml_path: nil,
+                       cli: { description: 'Show what would be processed without calling the LLM' }),
+        Definition.new(name: :key_filter, type: :string, default: nil, values: nil, yaml_path: nil,
+                       cli: { name: :key, aliases: '-k', type: :string, repeatable: true,
+                              description: 'Key filter pattern (repeatable, supports * wildcard)' }),
+        Definition.new(name: :print_config, type: :boolean, default: false, values: nil, yaml_path: nil,
+                       cli: { description: 'Print the resolved configuration and exit' }),
+        Definition.new(name: :workflow_stage, type: :string, default: 'apply',
+                       values: %w[check plan preview_diff apply], yaml_path: %w[workflow stage], cli: nil),
+        Definition.new(name: :diff_base, type: :string, default: nil, values: nil, yaml_path: nil,
+                       cli: { description: 'Only process keys changed since this git ref (e.g., main, origin/main)' }),
+        Definition.new(name: :diff_head, type: :string, default: 'HEAD', values: nil, yaml_path: nil,
+                       cli: { description: 'Compare --diff-base to this git ref', show_default: true }),
+        Definition.new(name: :start_key, type: :string, default: nil, values: nil, yaml_path: nil,
+                       cli: { description: 'Start processing from this key (inclusive)' }),
+        Definition.new(name: :end_key, type: :string, default: nil, values: nil, yaml_path: nil,
+                       cli: { description: 'Stop processing at this key (inclusive)' }),
+        Definition.new(name: :include_file_paths, type: :boolean, default: false, values: nil,
+                       yaml_path: %w[privacy include_file_paths],
+                       cli: { description: 'Include full source file paths in LLM prompts', show_default: true }),
+        Definition.new(name: :include_translation_comments, type: :boolean, default: true, values: nil,
+                       yaml_path: %w[privacy include_translation_comments],
+                       cli: { description: 'Include translation file comments in LLM prompts', show_default: true }),
+        Definition.new(name: :redact_prompts, type: :boolean, default: true, values: nil, yaml_path: %w[privacy redact_prompts],
+                       cli: { description: 'Best-effort redact likely secrets and PII from LLM prompts', show_default: true })
+      ].freeze
+
+      BY_NAME = DEFINITIONS.to_h { |definition| [definition.name, definition] }.freeze
+
+      module_function
+
+      def definition(name)
+        BY_NAME.fetch(name)
+      end
+
+      def thor_type(type)
+        { string: :string, integer: :numeric, boolean: :boolean }.fetch(type)
+      end
+
+      def default(name)
+        value = definition(name).default
+        value.is_a?(Array) || value.is_a?(Hash) || value.is_a?(String) ? value.dup : value
+      end
+
+      def values(name)
+        definition(name).values
+      end
+
+      def cli_definitions
+        DEFINITIONS.select(&:cli?)
+      end
+
+      def configured?(yaml, name)
+        path = definition(name).yaml_path
+        return false unless path
+
+        parent = path[0...-1].reduce(yaml) { |value, key| value.is_a?(Hash) ? value[key] : nil }
+        parent.is_a?(Hash) && parent.key?(path.last)
+      end
+
+      def value(yaml, name)
+        return default(name) unless configured?(yaml, name)
+
+        definition(name).yaml_path.reduce(yaml) { |value, key| value.fetch(key) }
+      end
+
+      def validate_document!(yaml, path:)
+        explicit_version = yaml.key?('schema_version')
+        version = yaml.fetch('schema_version', VERSION)
+        raise Error, "Invalid config #{path}: unsupported schema_version #{version.inspect}; expected #{VERSION}" unless version == VERSION
+
+        unknown_messages = []
+        unknown_top_level = yaml.keys - DOCUMENT_KEYS
+        unknown_messages << "unknown top-level keys: #{unknown_top_level.join(', ')}" if unknown_top_level.any?
+
+        SECTION_KEYS.each do |section, allowed_keys|
+          value = yaml[section]
+          next unless value.is_a?(Hash)
+
+          unknown = value.keys - allowed_keys
+          next if unknown.empty?
+
+          unknown_messages << "unknown #{section} keys: #{unknown.join(', ')}"
+        end
+
+        if unknown_messages.any?
+          details = unknown_messages.join('; ')
+          raise Error, "Invalid config #{path}: #{details}" if explicit_version
+
+          warn "Warning: #{details} ignored in unversioned config #{path}; add schema_version: #{VERSION} to enable strict validation"
+        end
+
+        VERSION
+      end
+    end
+  end
+end

data/lib/i18n_context_generator/config/serialization.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module I18nContextGenerator
+  class Config
+    # Secret-free, versioned representation used by --print-config and clients.
+    module Serialization
+      def to_h
+        {
+          'schema_version' => @schema_version,
+          'translations' => serialized_translations,
+          'source' => {
+            'paths' => @source_paths,
+            'ignore' => @ignore_patterns
+          },
+          'context' => {
+            'files' => @context_files
+          },
+          'llm' => {
+            'provider' => @provider,
+            'model' => @model,
+            'endpoint' => @endpoint
+          }.compact,
+          'processing' => {
+            'discovery_mode' => @discovery_mode,
+            'platform' => @platform,
+            'concurrency' => @concurrency,
+            'context_lines' => @context_lines,
+            'max_matches_per_key' => @max_matches_per_key,
+            'max_prompt_chars' => @max_prompt_chars
+          }.compact,
+          'cache' => {
+            'enabled' => !@no_cache,
+            'directory' => @cache_dir
+          },
+          'output' => {
+            'format' => @output_format,
+            'path' => (@output_path unless @output_stdout),
+            'stdout' => @output_stdout,
+            'write_back' => @write_back,
+            'write_back_to_code' => @write_back_to_code,
+            'context_prefix' => @context_prefix,
+            'context_mode' => @context_mode
+          }.compact,
+          'swift' => { 'functions' => @swift_functions },
+          'privacy' => {
+            'include_file_paths' => @include_file_paths,
+            'include_translation_comments' => @include_translation_comments,
+            'redact_prompts' => @redact_prompts
+          },
+          'workflow' => { 'stage' => @workflow_stage }
+        }
+      end
+
+      private
+
+      def serialized_translations
+        @translations.map do |path|
+          locale = @translation_locales[path]
+          locale ? { 'path' => path, 'locale' => locale } : path
+        end
+      end
+    end
+  end
+end

data/lib/i18n_context_generator/config/validation.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require 'uri'
+require_relative '../file_classifier'
+
+module I18nContextGenerator
+  class Config
+    # Validates the fully resolved configuration before extraction starts.
+    module Validation
+      BOOLEAN_OPTIONS = %i[
+        no_cache dry_run write_back write_back_to_code include_file_paths
+        include_translation_comments redact_prompts output_stdout print_config
+      ].freeze
+      OPTIONAL_STRING_OPTIONS = %i[
+        model endpoint output_path diff_base diff_head start_key end_key platform
+      ].freeze
+      TRANSLATION_DIFF_EXTENSIONS = %w[.strings .xcstrings .xml].freeze
+
+      def validate!
+        errors = []
+        validate_collections(errors)
+        validate_scalars(errors)
+        validate_domains(errors)
+        validate_provider_endpoint(errors)
+        validate_configured_paths(errors)
+        validate_output(errors)
+        validate_cache(errors)
+        validate_diff_support(errors)
+        validate_write_back(errors)
+
+        raise Error, "Invalid configuration: #{errors.join('; ')}" if errors.any?
+
+        self
+      end
+
+      private
+
+      def validate_collections(errors)
+        validate_string_array(errors, :translations, @translations)
+        validate_string_array(errors, :source_paths, @source_paths, allow_empty: false)
+        validate_string_array(errors, :ignore_patterns, @ignore_patterns)
+        validate_string_array(errors, :context_files, @context_files)
+        validate_string_array(errors, :swift_functions, @swift_functions)
+        errors << 'supplemental_context must map non-empty string names to non-empty string values' unless
+          valid_supplemental_context?
+        errors << 'key_filter must be a non-empty string or an array of non-empty strings' unless
+          @key_filter.nil? || valid_key_filter?(@key_filter)
+
+        errors << 'source_line_filter must be a mapping' if @source_line_filter && !@source_line_filter.is_a?(Hash)
+        return if @translation_locales.is_a?(Hash) && @translation_locales.all? do |path, locale|
+          path.is_a?(String) && locale.is_a?(String) && !locale.strip.empty?
+        end
+
+        errors << 'translation locales must map file paths to non-empty locale names'
+      end
+
+      def validate_scalars(errors)
+        validate_integer(errors, :concurrency, @concurrency, minimum: 1)
+        validate_integer(errors, :context_lines, @context_lines, minimum: 0)
+        validate_integer(errors, :max_matches_per_key, @max_matches_per_key, minimum: 1)
+        validate_integer(errors, :max_prompt_chars, @max_prompt_chars, minimum: 2_000)
+
+        BOOLEAN_OPTIONS.each do |name|
+          value = instance_variable_get(:"@#{name}")
+          errors << "#{name} must be true or false" unless [true, false].include?(value)
+        end
+
+        OPTIONAL_STRING_OPTIONS.each do |name|
+          value = instance_variable_get(:"@#{name}")
+          next if value.nil? || (value.is_a?(String) && !value.strip.empty?)
+
+          errors << "#{name} must be a non-empty string"
+        end
+        errors << 'context_prefix must be a string' unless @context_prefix.is_a?(String)
+        errors << 'cache_dir must be a non-empty string' unless @cache_dir.is_a?(String) && !@cache_dir.strip.empty?
+      end
+
+      def validate_domains(errors)
+        errors << "schema_version must be #{Schema::VERSION}" unless @schema_version == Schema::VERSION
+        validate_inclusion(errors, :provider, @provider, VALID_PROVIDERS)
+        validate_inclusion(errors, :output_format, @output_format, VALID_OUTPUT_FORMATS)
+        validate_inclusion(errors, :context_mode, @context_mode, VALID_CONTEXT_MODES)
+        validate_inclusion(errors, :discovery_mode, @discovery_mode, VALID_DISCOVERY_MODES)
+        validate_inclusion(errors, :workflow_stage, @workflow_stage, Schema.values(:workflow_stage))
+        validate_inclusion(errors, :platform, @platform, VALID_PLATFORMS) unless @platform.nil?
+        errors << 'preview_diff requires write_back or write_back_to_code' if @workflow_stage == 'preview_diff' && !@write_back && !@write_back_to_code
+        errors << 'preview_diff cannot write structured output' if @workflow_stage == 'preview_diff' && @output_path
+      end
+
+      def validate_provider_endpoint(errors)
+        if @provider == 'openai_compatible'
+          errors << 'openai_compatible provider requires an explicit model' if @model.nil?
+          if @endpoint.nil?
+            errors << 'openai_compatible provider requires llm.endpoint'
+          else
+            validate_endpoint_uri(errors)
+          end
+        elsif @endpoint
+          errors << 'llm.endpoint is supported only with the openai_compatible provider'
+        end
+      end
+
+      def validate_endpoint_uri(errors)
+        uri = URI.parse(@endpoint)
+        valid_scheme = %w[http https].include?(uri.scheme)
+        errors << 'llm.endpoint must be an absolute HTTP(S) URL' unless valid_scheme && uri.host
+        errors << 'llm.endpoint must not contain credentials, a query, or a fragment' if uri.userinfo || uri.query || uri.fragment
+
+        loopback_hosts = %w[localhost 127.0.0.1 ::1]
+        normalized_host = uri.hostname&.downcase
+        errors << 'plain HTTP llm.endpoint is allowed only for a loopback host' if uri.scheme == 'http' && !loopback_hosts.include?(normalized_host)
+      rescue URI::InvalidURIError
+        errors << 'llm.endpoint must be an absolute HTTP(S) URL'
+      end
+
+      def validate_configured_paths(errors)
+        if string_array?(@translations)
+          @translations.each do |path|
+            errors << "translation file not found: #{path}" unless File.file?(path)
+          end
+          validate_translation_locales(errors)
+        end
+
+        return unless string_array?(@source_paths)
+
+        @source_paths.each do |path|
+          errors << "source path not found: #{path}" unless File.exist?(path)
+        end
+
+        return unless string_array?(@context_files)
+
+        @context_files.each do |path|
+          if !File.file?(path)
+            errors << "context file not found: #{path}"
+          elsif !File.readable?(path)
+            errors << "context file is not readable: #{path}"
+          end
+        end
+      end
+
+      def validate_translation_locales(errors)
+        return unless @translation_locales.is_a?(Hash)
+
+        @translation_locales.each_key do |path|
+          errors << "translation locale references an unconfigured file: #{path}" unless @translations.include?(path)
+          next if %w[.yml .yaml].include?(File.extname(path).downcase)
+
+          errors << "translation locale is supported only for YAML files: #{path}"
+        end
+      end
+
+      def validate_output(errors)
+        errors << 'output.path and output.stdout cannot both be configured' if @output_destination_conflict
+        return if @output_stdout
+        return unless @output_path.is_a?(String)
+
+        extension = File.extname(@output_path).downcase
+        if !extension.empty? && !VALID_OUTPUT_EXTENSIONS.key?(extension)
+          errors << "output path extension must be .csv or .json: #{@output_path}"
+        elsif VALID_OUTPUT_EXTENSIONS[extension] && VALID_OUTPUT_EXTENSIONS[extension] != @output_format
+          errors << "output format #{@output_format} does not match #{extension} path"
+        end
+
+        parent = File.expand_path(File.dirname(@output_path))
+        if File.directory?(@output_path)
+          errors << "output path is a directory: #{@output_path}"
+        elsif !File.directory?(parent)
+          errors << "output directory not found: #{File.dirname(@output_path)}"
+        elsif !File.writable?(parent)
+          errors << "output directory is not writable: #{File.dirname(@output_path)}"
+        elsif File.exist?(@output_path) && !File.writable?(@output_path)
+          errors << "output file is not writable: #{@output_path}"
+        end
+      end
+
+      def validate_cache(errors)
+        return if @no_cache || !@cache_dir.is_a?(String) || @cache_dir.strip.empty?
+        return unless File.exist?(@cache_dir) && !File.directory?(@cache_dir)
+
+        errors << "cache directory path is not a directory: #{@cache_dir}"
+      end
+
+      def validate_diff_support(errors)
+        return unless @diff_base.is_a?(String) && translation_backed_diff?
+        return unless string_array?(@translations)
+
+        unsupported = @translations.reject do |path|
+          TRANSLATION_DIFF_EXTENSIONS.include?(File.extname(path).downcase)
+        end
+        return if unsupported.empty?
+
+        errors << "diff_base is not supported for translation formats: #{unsupported.join(', ')}"
+      end
+
+      def validate_write_back(errors)
+        return unless @write_back
+
+        if !string_array?(@translations) || @translations.empty?
+          errors << 'write_back requires at least one translation file'
+        else
+          unsupported = @translations.reject { |path| supported_translation_write_back?(path) }
+          errors << "write_back is not supported for: #{unsupported.join(', ')}" if unsupported.any?
+        end
+      end
+
+      def validate_string_array(errors, name, value, allow_empty: true)
+        return if string_array?(value) && (allow_empty || value.any?)
+
+        requirement = allow_empty ? 'an array of non-empty strings' : 'a non-empty array of strings'
+        errors << "#{name} must be #{requirement}"
+      end
+
+      def string_array?(value)
+        value.is_a?(Array) && value.all? { |item| item.is_a?(String) && !item.strip.empty? }
+      end
+
+      def valid_key_filter?(value)
+        (value.is_a?(String) && !value.strip.empty?) || (string_array?(value) && value.any?)
+      end
+
+      def valid_supplemental_context?
+        @supplemental_context.is_a?(Hash) && @supplemental_context.all? do |name, value|
+          name.is_a?(String) && !name.strip.empty? &&
+            value.is_a?(String) && !value.strip.empty?
+        end
+      end
+
+      def validate_integer(errors, name, value, minimum:)
+        return if value.is_a?(Integer) && value >= minimum
+
+        errors << "#{name} must be an integer greater than or equal to #{minimum}"
+      end
+
+      def validate_inclusion(errors, name, value, allowed)
+        return if allowed.include?(value)
+
+        errors << "#{name} must be one of: #{allowed.join(', ')}"
+      end
+
+      def translation_backed_diff?
+        @discovery_mode == 'translations' || (@discovery_mode == 'auto' && @translations&.any?)
+      end
+
+      def supported_translation_write_back?(path)
+        !FileClassifier.translation_platform(path).nil?
+      end
+    end
+  end
+end