aireview 0.2.1 → 2.0.0

data/lib/aireview/config_fallbacks.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+require_relative 'stages'
+require_relative 'errors'
+require_relative 'utils'
+require_relative 'model_candidate'
+require_relative 'stage_chains'
+require_relative 'model_pool'
+
+module Aireview
+  # Reserves for when the primary model is down or a key is out of quota:
+  # the routing plan (see StageChains and ModelPool) and the list of keys
+  # per provider. Models are set in .aireview.yml or the environment, keys
+  # only in the environment.
+  module ConfigFallbacks
+    KEYLESS_PROVIDERS = %w[ollama].freeze
+    DEFAULT_TIME_BUDGET = 1_800
+    DEFAULT_OVERLOADED_QUARANTINE = 120
+
+    # The routing plan is built once: a shared pool when llm.models is set,
+    # independent stage chains otherwise. A stage with a model of its own
+    # inside the pool is an independent chain.
+    def routing
+      @routing ||= build_routing
+    end
+
+    def stage_chain(stage)
+      routing.chain(stage)
+    end
+
+    # Keys in order of preference; a single nil for a keyless provider, so
+    # that walking the chain does not depend on the provider.
+    def provider_api_keys(provider)
+      provider = provider.to_s
+      return [nil] if KEYLESS_PROVIDERS.include?(provider)
+
+      keys = Array(@data["#{provider}_api_keys"]).compact
+      keys = [provider_api_key(provider)].compact if keys.empty?
+      fallbacks_disabled? ? keys.first(1) : keys
+    end
+
+    def fallbacks_disabled?
+      @data['fallbacks_disabled'] == true
+    end
+
+    def fallback_names(stage)
+      stage_chain(stage).drop(1).map(&:to_s)
+    end
+
+    # Only the number of keys per provider, for --dry-run; the values never
+    # leave.
+    def api_key_counts(stages)
+      providers = stages.flat_map { |stage| stage_chain(stage).map(&:provider) }.uniq
+      providers.reject { |provider| KEYLESS_PROVIDERS.include?(provider.to_s) }
+        .to_h { |provider| [provider, provider_api_keys(provider).size] }
+    end
+
+    # The ceiling for all LLM requests of the run, pauses between attempts
+    # included: the chain of reserves must not eat the whole CI job.
+    def llm_time_budget
+      positive_integer!(dig('llm', 'time_budget') || DEFAULT_TIME_BUDGET, 'llm.time_budget')
+    end
+
+    # For how many seconds an overloaded or hung model is skipped before the
+    # router tries it again.
+    def overloaded_quarantine
+      positive_integer!(dig('llm', 'overloaded_quarantine') || DEFAULT_OVERLOADED_QUARANTINE,
+                        'llm.overloaded_quarantine')
+    end
+
+    def require_models!
+      missing = []
+      missing << 'llm.generate.model (or LLM_GENERATE_MODEL)' if Aireview::Utils.blank?(generate_model)
+      missing << 'llm.critique.model (or LLM_CRITIQUE_MODEL)' if Aireview::Utils.blank?(critique_model)
+      raise ConfigError, "LLM models are required: #{missing.join(', ')}" unless missing.empty?
+    end
+
+    # The plan is built whole (pool and critique policy validated) before the
+    # first request, not in Critique after a paid-for Generate.
+    def require_llm_configuration!
+      require_models!
+      routing
+
+      missing_keys = STAGES.flat_map do |stage|
+        providers = stage_chain(stage).map(&:provider).uniq.reject { |provider| provider_keys_present?(provider) }
+        providers.map { |provider| "#{stage}: API key is required for provider #{provider.inspect}" }
+      end
+      raise ConfigError, missing_keys.join(', ') unless missing_keys.empty?
+    end
+
+    private
+
+    def build_routing
+      settings = STAGES.to_h { |stage| [stage, stage_settings(stage)] }
+      models = Array(dig('llm', 'models'))
+      return StageChains.build(settings, only_primary: fallbacks_disabled?) if models.empty?
+
+      own = settings.select { |_, stage_settings| Aireview::Utils.present?(stage_settings[:model]) }
+      ModelPool.new(
+        items: models, provider: llm_provider,
+        limits: STAGES.to_h { |stage| [stage, max_prompt_chars(stage)] },
+        starts: STAGES.to_h { |stage| [stage, dig('llm', stage, 'start')] },
+        inherited_starts: STAGES.select { |stage| start_inherited?(stage) },
+        rank: dig('llm', 'critique', 'rank'), allow_weaker: dig('llm', 'critique', 'allow_weaker'),
+        own_chains: StageChains.build(own, only_primary: fallbacks_disabled?), only_primary: fallbacks_disabled?
+      )
+    end
+
+    def stage_settings(stage)
+      {
+        provider: stage_setting(stage, 'provider') || llm_provider,
+        model: dig('llm', stage, 'model'),
+        fallbacks: dig('llm', stage, 'fallbacks'),
+        max_prompt_chars: max_prompt_chars(stage)
+      }
+    end
+
+    def provider_keys_present?(provider)
+      return true if ConfigFallbacks::KEYLESS_PROVIDERS.include?(provider.to_s)
+
+      provider_api_keys(provider).any? { |key| Aireview::Utils.present?(key) }
+    end
+  end
+end

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 = []