aireview 0.3.0 → 2.0.0

data/lib/aireview/config_layers.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+require_relative 'stages'
+require_relative 'utils'
+
+module Aireview
+  # Configuration layers in ascending priority: built-in values, image
+  # defaults (AIREVIEW_DEFAULTS), the project's .aireview.yml, env, CLI. The
+  # layer name is shown by --dry-run, so that it is clear where a model came from.
+  module ConfigLayers
+    Layer = Struct.new(:name, :path, :data, keyword_init: true)
+
+    BUILT_IN_LAYER = 'built-in'
+    DATA_LAYER = 'config'
+    IMAGE_LAYER = 'image defaults'
+    FILE_LAYER = '.aireview.yml'
+    ENV_LAYER = 'env'
+    CLI_LAYER = 'cli'
+
+    # The name of the layer a value came from; nil — not set anywhere.
+    def source_of(*keys)
+      layer_of(*keys)&.name
+    end
+
+    # A stage setting resolved layer by layer: in every layer, top down, the
+    # stage value (llm.<stage>.<key>) first, then the shared one (llm.<key>).
+    # A stage value from the image defaults must not beat a shared value from
+    # the project or the environment: LLM_PROVIDER=ollama must switch both stages.
+    def stage_setting(stage, key)
+      layer = stage_setting_layer(stage, key)
+      layer && (Utils.dig(layer.data, 'llm', stage.to_s, key) || Utils.dig(layer.data, 'llm', key))
+    end
+
+    def stage_setting_layer(stage, key)
+      stage = stage.to_s
+      @layers.reverse.find do |layer|
+        !Utils.dig(layer.data, 'llm', stage, key).nil? || !Utils.dig(layer.data, 'llm', key).nil?
+      end
+    end
+
+    def stage_provider_source(stage)
+      stage_setting_layer(stage, 'provider')&.name
+    end
+
+    # In pool mode the stage model is set by the start or the pool itself, the reserves by the pool.
+    def stage_model_source(stage)
+      stage = stage.to_s
+      return source_of('llm', stage, 'model') unless routing.pool_stage?(stage)
+      return source_of('llm', stage, 'start') if routing.start_used?(stage)
+
+      source_of('llm', 'models')
+    end
+
+    def stage_fallbacks_source(stage)
+      stage = stage.to_s
+      routing.pool_stage?(stage) ? source_of('llm', 'models') : source_of('llm', stage, 'fallbacks')
+    end
+
+    # The stage start came from a layer below the one that set the pool: the
+    # image defaults versus the project's LLM_MODELS.
+    def start_inherited?(stage)
+      start_layer = layer_of('llm', stage.to_s, 'start')
+      models_layer = layer_of('llm', 'models')
+      !!(start_layer && models_layer && @layers.index(start_layer) < @layers.index(models_layer))
+    end
+
+    # Configuration and plan warnings; the CLI and --dry-run print them.
+    def warnings
+      STAGES.flat_map { |stage| stage_provider_warnings(stage) } + routing.warnings
+    end
+
+    # The paths of the file layers, for --dry-run.
+    def layer_paths
+      @layers.select(&:path).to_h { |layer| [layer.name, layer.path] }
+    end
+
+    # A reserve without a provider inherits the stage provider. When a
+    # project overrode the provider above the layer that set the reserves,
+    # the inherited reserves silently become "models" of the new provider.
+    def stage_provider_warnings(stage)
+      stage = stage.to_s
+      inherited = inherited_fallback_names(stage)
+      return [] if inherited.empty?
+
+      provider_layer = stage_setting_layer(stage, 'provider')
+      fallbacks_layer = layer_of('llm', stage, 'fallbacks')
+      return [] unless provider_layer && fallbacks_layer
+      return [] if @layers.index(provider_layer) <= @layers.index(fallbacks_layer)
+
+      provider = public_send("#{stage}_provider")
+      ["#{stage}: provider #{provider.inspect} comes from #{provider_layer.name}, " \
+       "but fallbacks without an explicit provider come from #{fallbacks_layer.name} " \
+       "and now inherit it: #{inherited.join(', ')}"]
+    end
+
+    private
+
+    def layer_of(*keys)
+      @layers.reverse.find { |layer| !Utils.dig(layer.data, *keys).nil? }
+    end
+
+    def inherited_fallback_names(stage)
+      Array(dig('llm', stage, 'fallbacks')).filter_map do |item|
+        next item.to_s if item.is_a?(String)
+        next unless item.is_a?(Hash) && Aireview::Utils.blank?(item['provider'])
+
+        item['model'].to_s
+      end
+    end
+  end
+end

data/lib/aireview/config_limits.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
+require_relative 'stages'
 
 module Aireview
-  # Лимиты контекста в символах: точного токенизатора для провайдеров локально
-  # нет, а окно Ollama задаётся на сервере и клиенту не видно. Дефолты щедрые,
-  # под конкретную модель их задают в .aireview.yml.
+  # Context limits in characters: there is no exact local tokenizer for the
+  # providers, and the Ollama window is set on the server, invisible to the
+  # client. The defaults are generous; a specific model gets its own in
+  # .aireview.yml.
   module ConfigLimits
-    LLM_STAGES = %w[generate critique].freeze
     DEFAULT_MAX_PROMPT_CHARS = 400_000
     CONTEXT_DEFAULTS = {
       'max_diff_chars' => 120_000,
@@ -13,41 +14,15 @@ module Aireview
       'max_jira_description_chars' => 8_000,
       'max_jira_comment_chars' => 2_000
     }.freeze
-    CONTEXT_ENV = {
-      'max_diff_chars' => 'MAX_DIFF_CHARS',
-      'max_mr_description_chars' => 'MAX_MR_DESCRIPTION_CHARS',
-      'max_jira_description_chars' => 'MAX_JIRA_DESCRIPTION_CHARS',
-      'max_jira_comment_chars' => 'MAX_JIRA_COMMENT_CHARS'
-    }.freeze
-
-    module ClassMethods
-      def context_env_config(env)
-        context = CONTEXT_ENV.each_with_object({}) do |(key, env_key), config|
-          value = parse_integer(env[env_key], env_key)
-          config[key] = value unless value.nil?
-        end
-        context.empty? ? {} : {'context' => context}
-      end
-
-      # Лимит, который не разобрался, нельзя молча заменять дефолтом: запрос
-      # уйдёт в модель с окном, которого у неё нет.
-      def parse_integer(value, name)
-        return nil if Aireview::Utils.blank?(value)
-
-        Integer(value.to_s, 10)
-      rescue ArgumentError
-        raise ConfigError, "#{name} must be an integer, got #{value.inspect}"
-      end
-    end
-
-    # Лимит всего запроса стадии в символах: системный промпт плюс контекст
-    # (для критика ещё и кандидаты). Наследуется из llm как model/temperature.
+    # The limit of the whole stage request in characters: the system prompt
+    # plus the context (plus the candidates for Critique). Inherited from llm
+    # like model/temperature.
     def max_prompt_chars(stage)
       stage = stage.to_s
-      raise ArgumentError, "unknown LLM stage #{stage.inspect}" unless LLM_STAGES.include?(stage)
+      raise ArgumentError, "unknown LLM stage #{stage.inspect}" unless STAGES.include?(stage)
 
       positive_integer!(
-        dig('llm', stage, 'max_prompt_chars') || dig('llm', 'max_prompt_chars') || DEFAULT_MAX_PROMPT_CHARS,
+        stage_setting(stage, 'max_prompt_chars') || DEFAULT_MAX_PROMPT_CHARS,
         "llm.#{stage}.max_prompt_chars"
       )
     end

data/lib/aireview/config_loader.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+require_relative 'stages'
+require 'logger'
+require 'pathname'
+require 'yaml'
+require_relative 'errors'
+require_relative 'utils'
+require_relative 'model_candidate'
+require_relative 'config_layers'
+require_relative 'config_limits'
+require_relative 'config'
+
+module Aireview
+  # Builds a Config from layers: built-in values, image defaults
+  # (AIREVIEW_DEFAULTS), the project's .aireview.yml (searched upwards from
+  # cwd), env. Everything that knows environment variable names and file
+  # formats lives here; Config only answers questions about merged data.
+  module ConfigLoader
+    ENV_MAPPING = {
+      'gitlab_url' => 'GITLAB_URL',
+      'gitlab_token' => 'GITLAB_TOKEN',
+      'jira_url' => 'JIRA_URL',
+      'jira_login' => 'JIRA_LOGIN',
+      'jira_password' => 'JIRA_PASSWORD',
+      'review_language' => 'REVIEW_LANGUAGE',
+      'review_mode' => 'REVIEW_MODE',
+      'llm_api_base' => 'LLM_API_BASE',
+      'ollama_api_base' => 'OLLAMA_API_BASE',
+      'llm_http_proxy' => 'LLM_HTTP_PROXY'
+    }.freeze
+    PROVIDER_KEY_MAPPING = {'gemini' => 'GEMINI_API_KEY'}.freeze
+    PROVIDER_KEYS_MAPPING = {'gemini' => 'GEMINI_API_KEYS'}.freeze
+    CONTEXT_ENV = {
+      'max_diff_chars' => 'MAX_DIFF_CHARS',
+      'max_mr_description_chars' => 'MAX_MR_DESCRIPTION_CHARS',
+      'max_jira_description_chars' => 'MAX_JIRA_DESCRIPTION_CHARS',
+      'max_jira_comment_chars' => 'MAX_JIRA_COMMENT_CHARS'
+    }.freeze
+    LLM_ENV = %w[
+      LLM_PROVIDER LLM_TEMPERATURE LLM_TIMEOUT LLM_MAX_PROMPT_CHARS LLM_TIME_BUDGET LLM_OVERLOADED_QUARANTINE
+      LLM_MODELS LLM_CRITIQUE_RANK LLM_CRITIQUE_ALLOW_WEAKER
+    ].freeze
+    LLM_STAGE_ENV_SUFFIXES = %w[PROVIDER MODEL TEMPERATURE MAX_PROMPT_CHARS FALLBACK_MODEL START].freeze
+    IMAGE_DEFAULTS_ENV = 'AIREVIEW_DEFAULTS'
+
+    module_function
+
+    def load(config_path: nil, cwd: Dir.pwd, env: ENV, logger: Logger.new($stderr))
+      load_dotenv(cwd)
+
+      file_path = config_path ? File.expand_path(config_path, cwd) : discover_file(cwd, '.aireview.yml')
+      layers = [
+        ConfigLayers::Layer.new(name: ConfigLayers::BUILT_IN_LAYER, data: Config::DEFAULTS),
+        image_defaults_layer(env),
+        file_layer(file_path),
+        ConfigLayers::Layer.new(name: ConfigLayers::ENV_LAYER, data: env_config(env))
+      ].compact
+
+      Config.new(config_path: File.file?(file_path) ? file_path : nil, logger: logger, layers: layers)
+    end
+
+    # Every environment variable the loader reads. The CI template passes
+    # them into the container by name: a project variable missing from this
+    # list never reaches the review.
+    def env_names
+      stage_env = STAGES.flat_map do |stage|
+        LLM_STAGE_ENV_SUFFIXES.map { |suffix| "LLM_#{stage.upcase}_#{suffix}" }
+      end
+      [
+        *ENV_MAPPING.values, *PROVIDER_KEY_MAPPING.values, *PROVIDER_KEYS_MAPPING.values, 'LLM_API_KEY',
+        *LLM_ENV, *stage_env, *CONTEXT_ENV.values
+      ].uniq
+    end
+
+    def load_dotenv(cwd)
+      require 'dotenv'
+      dotenv_path = discover_file(cwd, '.env')
+      Dotenv.load(dotenv_path) if File.file?(dotenv_path)
+    rescue LoadError
+      nil
+    end
+
+    def discover_file(cwd, basename)
+      current = Pathname.new(cwd).expand_path
+
+      loop do
+        candidate = current.join(basename)
+        return candidate.to_s if candidate.file?
+
+        break if current.root?
+
+        current = current.parent
+      end
+
+      File.join(cwd, basename)
+    end
+
+    # Image defaults: the Dockerfile sets the path through AIREVIEW_DEFAULTS.
+    # A path that is set but missing means a broken image; better to learn
+    # that at once.
+    def image_defaults_layer(env)
+      path = env[IMAGE_DEFAULTS_ENV]
+      return nil if Aireview::Utils.blank?(path)
+      raise ConfigError, "#{IMAGE_DEFAULTS_ENV} points to a missing file: #{path}" unless File.file?(path)
+
+      ConfigLayers::Layer.new(name: ConfigLayers::IMAGE_LAYER, path: path, data: read_yaml(path))
+    end
+
+    def file_layer(file_path)
+      return nil unless File.file?(file_path)
+
+      ConfigLayers::Layer.new(name: ConfigLayers::FILE_LAYER, path: file_path, data: read_yaml(file_path))
+    end
+
+    def read_yaml(path)
+      Aireview::Utils.normalize_hash(YAML.load_file(path) || {})
+    end
+
+    def env_config(env)
+      mapped_env_config(env)
+        .merge('llm' => Aireview::Utils.deep_merge(llm_env_config(env), pool_env_config(env)))
+        .merge(context_env_config(env))
+        .merge(provider_key_env_config(env))
+        .merge(provider_keys_env_config(env))
+        .merge(generic_api_key_env_config(env))
+    end
+
+    def mapped_env_config(env)
+      ENV_MAPPING.each_with_object({}) do |(key, env_key), config|
+        value = env[env_key]
+        config[key] = value unless Aireview::Utils.blank?(value)
+      end
+    end
+
+    def llm_env_config(env)
+      {
+        'provider' => env['LLM_PROVIDER'],
+        'temperature' => parse_float(env['LLM_TEMPERATURE']),
+        'timeout' => parse_float(env['LLM_TIMEOUT']),
+        'max_prompt_chars' => parse_integer(env['LLM_MAX_PROMPT_CHARS'], 'LLM_MAX_PROMPT_CHARS'),
+        'time_budget' => parse_integer(env['LLM_TIME_BUDGET'], 'LLM_TIME_BUDGET'),
+        'overloaded_quarantine' => parse_integer(env['LLM_OVERLOADED_QUARANTINE'], 'LLM_OVERLOADED_QUARANTINE'),
+        'generate' => llm_stage_env_config(env, 'GENERATE'),
+        'critique' => llm_stage_env_config(env, 'CRITIQUE')
+      }.compact.reject { |key, value| %w[generate critique].include?(key) && value.empty? }
+    end
+
+    def llm_stage_env_config(env, stage)
+      {
+        'provider' => env["LLM_#{stage}_PROVIDER"],
+        'model' => env["LLM_#{stage}_MODEL"],
+        'temperature' => parse_float(env["LLM_#{stage}_TEMPERATURE"]),
+        'max_prompt_chars' => parse_integer(env["LLM_#{stage}_MAX_PROMPT_CHARS"], "LLM_#{stage}_MAX_PROMPT_CHARS"),
+        'fallbacks' => fallback_models_env_config(env, stage)
+      }.compact
+    end
+
+    # LLM_GENERATE_FALLBACK_MODEL=gemini-3.8-flash (or a comma-separated
+    # list) — the provider is separated by a slash because Ollama tags contain a colon.
+    def fallback_models_env_config(env, stage)
+      value = env["LLM_#{stage}_FALLBACK_MODEL"]
+      return nil if Aireview::Utils.blank?(value)
+
+      value.split(',').map(&:strip).reject(&:empty?).map { |item| ModelCandidate.parse_item(item) }
+    end
+
+    # LLM_MODELS=gemini/gemini-3.8-flash,gemini/gemini-3.7-flash;
+    # LLM_GENERATE_START / LLM_CRITIQUE_START — a model from the pool;
+    # LLM_CRITIQUE_RANK, LLM_CRITIQUE_ALLOW_WEAKER=true|false.
+    def pool_env_config(env)
+      models = env['LLM_MODELS'].to_s.split(',').map(&:strip).reject(&:empty?).map do |item|
+        ModelCandidate.parse_item(item)
+      end
+      {
+        'models' => models.empty? ? nil : models,
+        'generate' => {'start' => env['LLM_GENERATE_START']}.compact,
+        'critique' => {
+          'start' => env['LLM_CRITIQUE_START'],
+          'rank' => env['LLM_CRITIQUE_RANK'],
+          'allow_weaker' => parse_boolean(env['LLM_CRITIQUE_ALLOW_WEAKER'], 'LLM_CRITIQUE_ALLOW_WEAKER')
+        }.compact
+      }.compact.reject { |_, value| value.is_a?(Hash) && value.empty? }
+    end
+
+    def context_env_config(env)
+      context = CONTEXT_ENV.each_with_object({}) do |(key, env_key), config|
+        value = parse_integer(env[env_key], env_key)
+        config[key] = value unless value.nil?
+      end
+      context.empty? ? {} : {'context' => context}
+    end
+
+    def provider_key_env_config(env)
+      PROVIDER_KEY_MAPPING.each_with_object({}) do |(provider, env_key), config|
+        value = env[env_key]
+        config["#{provider}_api_key"] = value unless Aireview::Utils.blank?(value)
+      end
+    end
+
+    def provider_keys_env_config(env)
+      PROVIDER_KEYS_MAPPING.each_with_object({}) do |(provider, env_key), config|
+        keys = env[env_key].to_s.split(',').map(&:strip).reject(&:empty?)
+        config["#{provider}_api_keys"] = keys unless keys.empty?
+      end
+    end
+
+    def generic_api_key_env_config(env)
+      api_key = env['LLM_API_KEY']
+      return {} if Aireview::Utils.blank?(api_key)
+
+      {'llm_api_key' => api_key}
+    end
+
+    def parse_float(value)
+      return nil if Aireview::Utils.blank?(value)
+
+      Float(value)
+    rescue ArgumentError
+      nil
+    end
+
+    # A limit that failed to parse must not silently fall back to the
+    # default: the request would go to a model with a window it does not have.
+    def parse_integer(value, name)
+      return nil if Aireview::Utils.blank?(value)
+
+      Integer(value.to_s, 10)
+    rescue ArgumentError
+      raise ConfigError, "#{name} must be an integer, got #{value.inspect}"
+    end
+
+    def parse_boolean(value, name)
+      return nil if Aireview::Utils.blank?(value)
+      return true if %w[true 1 yes].include?(value.to_s.downcase)
+      return false if %w[false 0 no].include?(value.to_s.downcase)
+
+      raise ConfigError, "#{name} must be true or false, got #{value.inspect}"
+    end
+  end
+end

data/lib/aireview/context_budget.rb

@@ -2,12 +2,13 @@
 require_relative 'errors'
 
 module Aireview
-  # Укладывает контекст ревью в бюджет символов и запоминает, что при этом не
-  # вошло. Секции MR и Jira режутся до своих лимитов с сохранением начала,
-  # дифф по целым файлам, затем по целым хункам; внутри хунка не режем.
+  # Fits the review context into a character budget and remembers what was
+  # left out. The MR and Jira sections are cut to their limits keeping the
+  # beginning, the diff by whole files, then by whole hunks; a hunk is never
+  # cut inside.
   module ContextBudget
-    # Пути, которые не вошли, перечисляются в конце диффа; список ограничен,
-    # чтобы сам не съел бюджет.
+    # The paths that did not fit are listed at the end of the diff; the list
+    # is capped so that it does not eat the budget itself.
     NOT_SHOWN_LIST_LIMIT = 20
     TRAILER_RESERVE_CHARS = 400
 
@@ -26,7 +27,8 @@ module Aireview
 
     Packed = Struct.new(:text, :shown_hunks, :total_hunks, keyword_init: true)
 
-    # Начало важнее конца: требования и критерии приёмки обычно там.
+    # The beginning matters more than the end: requirements and acceptance
+    # criteria usually live there.
     def self.truncate_section(text, limit:, label:, coverage:)
       text = text.to_s
       return text if text.length <= limit
@@ -39,11 +41,11 @@ module Aireview
       Packer.new(entries, budget: budget, coverage: coverage).pack
     end
 
-    # Файлы без хунков идут первыми: они дёшевы и всегда полезны для картины
-    # MR. Текстовые файлы идут в порядке GitLab, пока влезают; первый файл,
-    # который не влезает, показывается частично, всё после него не показывается.
-    # Хунк, который не влез бы даже в пустой бюджет, пропускается с пометкой,
-    # а не останавливает раскладку.
+    # Files without hunks go first: they are cheap and always useful for the
+    # picture of the MR. Text files go in GitLab order while they fit; the
+    # first file that does not fit is shown partially, everything after it is
+    # not shown. A hunk that would not fit even into an empty budget is
+    # skipped with a mark instead of stopping the layout.
     class Packer
       def initialize(entries, budget:, coverage:)
         @non_text, @text = entries.partition { |entry| !entry.text? }
@@ -62,9 +64,9 @@ module Aireview
 
       private
 
-      # Что-то придётся опустить, значит нужен хвост со списком пропущенного.
-      # @used считает весь собранный текст, включая разделители между
-      # файлами: результат не должен выйти за бюджет ни на символ.
+      # Something has to be left out, so a trailer listing the skipped paths
+      # is needed. @used counts the whole assembled text, separators between
+      # files included: the result must not exceed the budget by a character.
       def pack_within_limit
         @parts = @non_text.map(&:render)
         @used = joined_length(@parts)
@@ -95,12 +97,12 @@ module Aireview
         shown_hunks
       end
 
-      # Место под следующий кусок с учётом разделителя перед ним.
+      # Room for the next piece, the separator before it included.
       def remaining
         @limit - @used - (@parts.empty? ? 0 : 1)
       end
 
-      # Возвращает [текст, число показанных хунков, остановлена ли раскладка].
+      # Returns [text, number of shown hunks, whether the layout stopped].
       def pack_entry(entry)
         full = entry.render
         return [full, entry.hunks.size, false] if full.length <= remaining
@@ -113,10 +115,10 @@ module Aireview
         [entry.header + body + partial_marker(entry, shown), shown, stopped]
       end
 
-      # Место сначала отдаётся хункам, которые можно показать, и только на
-      # остаток добавляются пометки о слишком больших: иначе пометки могли бы
-      # вытеснить единственный подходящий хунк. Факт пропуска в покрытие
-      # попадает независимо от того, есть ли для пометки место.
+      # Room goes first to the hunks that can be shown, and only the remainder
+      # to the marks about oversized ones: otherwise the marks could push out
+      # the only fitting hunk. The skip is recorded in the coverage whether
+      # or not there is room for the mark.
       def pack_hunks(entry)
         base = entry.header.length + partial_marker(entry, 0).length
         shown = []

data/lib/aireview/context_builder.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 require_relative 'utils'
 require_relative 'errors'
+require_relative 'stages'
 require_relative 'secret_scrubber'
 require_relative 'diff_fetcher'
 require_relative 'context_budget'
@@ -15,14 +16,13 @@ module Aireview
     }.freeze
     CHANGES_HEADER = "Changes:\n"
     CANDIDATES_HEADER = "\n\nCandidates JSON from Generate:\n"
-    # Резерв под кандидатов в промпте критика: три кандидата по ~1 500
-    # символов. Оценка, не гарантия; фактический размер проверяется перед
-    # отправкой.
+    # Room for the candidates in the Critique prompt: three candidates of
+    # ~1,500 characters. An estimate, not a guarantee; the actual size is
+    # checked before sending.
     CANDIDATES_RESERVE_CHARS = 4_500
-    STAGES = %i[generate critique].freeze
 
-    # Контекст одного прогона: обе стадии получают одинаковые MR, Jira и дифф,
-    # усечённые один раз под самую тесную из стадий.
+    # The context of one run: both stages get the same MR, Jira and diff,
+    # truncated once for the tightest of the stages.
     Context = Struct.new(:user_prompt, :diff_text, :coverage, :sizes, keyword_init: true)
 
     def initialize(config:, logger: Logger.new($stderr))
@@ -53,16 +53,16 @@ module Aireview
     end
 
     def build_generate_prompt(context)
-      check_stage_size!(:generate, system_prompt(:generate), context.user_prompt)
+      check_stage_size!('generate', system_prompt('generate'), context.user_prompt)
     end
 
     def build_critique_prompt(context, candidates_json:)
       user = "#{context.user_prompt}#{CANDIDATES_HEADER}#{scrub_text(candidates_json)}"
-      check_stage_size!(:critique, system_prompt(:critique), user)
+      check_stage_size!('critique', system_prompt('critique'), user)
     end
 
     def system_prompt(stage)
-      template = stage.to_sym == :critique ? CRITIQUE_PROMPT_TEMPLATE : GENERATE_PROMPT_TEMPLATE
+      template = stage.to_s == 'critique' ? CRITIQUE_PROMPT_TEMPLATE : GENERATE_PROMPT_TEMPLATE
       extras = []
       if Aireview::Utils.present?(@config.review_instructions)
         extras << "Additional project instructions:\n#{scrub_text(@config.review_instructions.strip)}"
@@ -72,10 +72,11 @@ module Aireview
       [template, *extras].join("\n\n")
     end
 
-    # Проверка перед отправкой: если кандидаты вышли за резерв и запрос не
-    # помещается, это ошибка, а не повод молча резать контекст, который
-    # генератор уже видел.
+    # A check before sending: when the candidates exceed the reserve and the
+    # request does not fit, that is an error, not a reason to silently cut
+    # the context Generate has already seen.
     def check_stage_size!(stage, system, user)
+      stage = stage.to_s
       limit = @config.max_prompt_chars(stage)
       total = system.length + user.length
       if total > limit
@@ -89,10 +90,10 @@ module Aireview
 
     private
 
-    # Минимум по стадиям: контекст один на прогон, поэтому он должен
-    # помещаться в каждую из них вместе с её системным промптом и резервом.
+    # The minimum over the stages: the context is one per run, so it must fit
+    # into each of them together with its system prompt and reserve.
     def context_budget(critique:)
-      stages = critique ? STAGES : [:generate]
+      stages = critique ? STAGES : ['generate']
       budgets = stages.to_h { |stage| [stage, stage_budget(stage)] }
       stage, budget = budgets.min_by { |_, value| value }
       return budget if budget.positive?
@@ -104,7 +105,7 @@ module Aireview
     end
 
     def stage_budget(stage)
-      reserve = stage == :critique ? CANDIDATES_RESERVE_CHARS + CANDIDATES_HEADER.length : 0
+      reserve = stage == 'critique' ? CANDIDATES_RESERVE_CHARS + CANDIDATES_HEADER.length : 0
       @config.max_prompt_chars(stage) - system_prompt(stage).length - reserve
     end
 
@@ -152,7 +153,7 @@ module Aireview
     end
 
     def context_sizes(fixed:, packed:, budget:, diff_budget:, critique:)
-      stages = critique ? STAGES : [:generate]
+      stages = critique ? STAGES : ['generate']
       {
         context_budget: budget,
         diff_budget: diff_budget,

data/lib/aireview/diff_fetcher.rb

@@ -7,13 +7,14 @@ module Aireview
     DIFF_UNAVAILABLE = '[diff not available]'
     BINARY_DIFF = /\ABinary files .* differ/
 
-    # Один файл из ответа GitLab: заголовок, хунки и что с ним можно делать.
+    # One file from the GitLab answer: the header, the hunks and what can be done with it.
     # kind:
-    #   :text            есть хунки, код можно проверить;
-    #   :no_text_changes переименование, смена режима, пустой файл: проверять
-    #                    нечего;
-    #   :unavailable     GitLab не отдал дифф (too_large, бинарник, пустой
-    #                    дифф без причины): код есть, но проверить его не удалось.
+    #   :text            there are hunks, the code can be checked;
+    #   :no_text_changes a rename, a mode change, an empty file: nothing to
+    #                    check;
+    #   :unavailable     GitLab did not return the diff (too_large, a binary,
+    #                    an empty diff without a reason): the code exists,
+    #                    but could not be checked.
     class Entry
       attr_reader :path, :kind, :header, :hunks
 
@@ -49,9 +50,9 @@ module Aireview
 
       private
 
-      # Пустой дифф без объяснимой причины (переименование, смена режима,
-      # пустой новый или удалённый файл) считаем недоступным: код есть, но
-      # GitLab его не отдал.
+      # An empty diff without an explainable reason (a rename, a mode change,
+      # an empty new or deleted file) counts as unavailable: the code exists,
+      # but GitLab did not return it.
       def classify(change, diff)
         return :unavailable if change['too_large']
         return :unavailable if diff.match?(BINARY_DIFF)
@@ -67,8 +68,8 @@ module Aireview
         modes.none?(&:nil?) && modes.uniq.size == 2
       end
 
-      # Хунки режем по заголовкам @@; текст до первого @@ (или дифф без них,
-      # например заглушка про секретный файл) считается одним хунком.
+      # Hunks are split at the @@ headers; the text before the first @@ (or a
+      # diff without any, such as the secret-file placeholder) counts as one hunk.
       def split_hunks(diff)
         diff = "#{diff}\n" unless diff.end_with?("\n")
         pieces = diff.split(/^(?=@@ )/)