aireview 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ceb8f061ed3a8172b46df1af17fa9961282858657aaf347215b42d5824acf7b
-  data.tar.gz: e345026c2323be4af4fa9ff2e00fb552685d9e9aec040a691a347cc063ce9d88
+  metadata.gz: b27b5c59888ddb35675082d95d7e5e79dc1935295ecde9a1e13cdcaf38f24dff
+  data.tar.gz: 6016c5aae6d57475465c707cc2d89dedf07964d402cc1f5a68a6e01dc5f553d1
 SHA512:
-  metadata.gz: 3fbbfb3540d90c6d5cf35bbe5e403ba0d4abc17fab630b464d9a03bd9748563cd3ed11192673ed5bca48e1d01c393b25bd5ad25324c4ccf7c3e4548695d336e0
-  data.tar.gz: 33f0bbba90317654a12835bd8328f6ef58a46b89b7d312aad6da46b76033495d708dc8da6a25772c7b8815811c0cc882878f0a58ac7cf418d0328af29821fe60
+  metadata.gz: bc47e9e8d2c7cece68a02a92594c896f52c5b101c8a639cee9f3c702e010906e5280dbda4282465630162c90b2532debcdca05462c8a1b390987288b150850dc
+  data.tar.gz: 644ad90865170c254b3b844e606f9c0121a2b82a50d7af62ffd70f4bf838bd0a258db367e3a815d899fb8bb628f183d268eee11722d2364bf700734ba463b7a3

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.2.0
+
+- Context budget: `llm.max_prompt_chars` caps the request of each stage,
+  `context.max_*_chars` cap the MR description, the Jira description and
+  comments and the diff. The diff is cut by whole files and hunks, never in
+  the middle of a hunk, and both stages share the same context.
+- Truncation is marked in the prompt and reported in the review: the result
+  line gets a `Partial review` suffix and a `Not reviewed` section lists the
+  files and sections that were left out. `--dry-run` and `--verbose` show the
+  sizes and the coverage.
+- Renames, mode changes and empty new or deleted files are told apart from
+  diffs GitLab did not return (too large, binary, empty without a reason); the
+  latter are reported as not reviewed.
+- Unparsable limits in the environment (`MAX_DIFF_CHARS=oops`) fail with a
+  `ConfigError` instead of silently falling back to the defaults.
+- A run fails with a clear error when not even one hunk fits next to the
+  system prompt, or when the candidates push the Critique request over its
+  limit.
+
+## 0.1.1
+
+- The prompts no longer ask the model to check whether dependency and image
+  versions exist; candidates about nonexistent versions are rejected.
+- An overloaded LLM (503) is retried up to three times with pauses of about
+  2, 5 and 5 minutes instead of two retries of 1.5-2.5 minutes.
+
 ## 0.1.0
 
 Initial release.

data/CONTRIBUTORS.md

@@ -0,0 +1,8 @@
+# Contributors
+
+- [Denis Levenko](https://github.com/DenisDenis9331), author and maintainer.
+- [Sergey Kondrashov](https://github.com/SergoHUH): Ollama support, Jira
+  self-hosted configuration, provider cleanup, prompt refactoring.
+
+Contributions are welcome: open an issue or a pull request at
+https://github.com/DenisDenis9331/aireview.

data/README.md

@@ -162,7 +162,10 @@ To run both stages locally, set `ollama` in both provider variables. The
 address with `/v1` matches the
 [Ollama configuration in RubyLLM](https://rubyllm.com/configuration/#provider-configuration).
 `LLM_TIMEOUT` sets the timeout of every LLM request in seconds; for a slow
-local model it can be raised.
+local model it can be raised. It does not apply to an "overloaded" (503)
+answer from the provider: such a request gets up to four attempts, the
+original one and three retries with pauses of about 2, 5 and 5 minutes, and
+only the failed stage is repeated, not the whole run.
 
 Project rules live in `.aireview.yml`. In YAML the `generate.model` and
 `critique.model` settings are required for each stage and are not inherited
@@ -201,11 +204,18 @@ review_instructions: |
 
 ollama_api_base: http://localhost:11434/v1
 
+context:
+  max_diff_chars: 120000
+  max_mr_description_chars: 8000
+  max_jira_description_chars: 8000
+  max_jira_comment_chars: 2000
+
 llm:
   provider: gemini
   temperature: 0
   timeout: 60
   http_proxy: http://127.0.0.1:8888
+  max_prompt_chars: 400000
   generate:
     provider: gemini
     model: gemini-3.7-flash
@@ -214,8 +224,46 @@ llm:
     provider: ollama
     model: qwen2.5-coder:7b
     temperature: 0
+    max_prompt_chars: 60000
 ```
 
+### Context budget
+
+The request to each stage is capped by `llm.max_prompt_chars` (or
+`LLM_MAX_PROMPT_CHARS`; per stage `llm.generate.max_prompt_chars` /
+`LLM_GENERATE_MAX_PROMPT_CHARS` and the same for `critique`). The limits are in
+characters, not tokens: there is no exact tokenizer for the providers locally,
+and the Ollama window is set on the server where the client cannot see it. As
+a rule of thumb one token is three to four characters, so for a local model
+with `OLLAMA_CONTEXT_LENGTH=8192` set the stage limit to about 20 000
+characters to leave room for the answer.
+
+The MR and Jira context is assembled once per run and shared by both stages,
+so it is sized for the tighter of the two: the Critique stage also has to fit
+its system prompt and a reserve for the candidates. The sections are cut to
+their own limits first, keeping the beginning: `context.max_diff_chars`,
+`context.max_mr_description_chars`, `context.max_jira_description_chars` and
+`context.max_jira_comment_chars` (`MAX_DIFF_CHARS`, `MAX_MR_DESCRIPTION_CHARS`,
+`MAX_JIRA_DESCRIPTION_CHARS`, `MAX_JIRA_COMMENT_CHARS`). Only then is the diff
+cut, and only by whole files and whole hunks: files in the order GitLab returns
+them, a file that does not fit is shown hunk by hunk, everything after it is
+left out, and a single hunk larger than the whole budget is skipped rather
+than cut in the middle. Renames, mode changes and other files without text
+changes are always listed; files whose diff GitLab did not return (too large,
+binary) are listed as well and reported as not reviewed.
+
+Everything that was cut is marked in the prompt, so the model knows that a
+missing requirement or missing code may simply be outside the budget. The
+review reports it too: the result line gets a `Partial review: ...` suffix
+and a `Not reviewed` section lists the files and sections concerned. The
+result itself (`ok` / `needs attention`) is still only about the findings.
+
+When even one hunk cannot fit next to the system prompt, or the candidates
+returned by Generate push the Critique request over its limit, the run stops
+with an error instead of silently reviewing less. Raise the limits or extend
+`ignore_paths`. `--dry-run` prints the sizes of every part and the coverage;
+`--verbose` logs them during a real run.
+
 ## Usage
 
 ```bash
@@ -234,7 +282,7 @@ bundle _2.3.26_ exec bin/aireview review https://gitlab.company.com/team/project
 - `--critique-temperature VALUE` overrides the temperature for the Critique pass only.
 - `--config PATH` points at a specific `.aireview.yml`.
 - `--no-jira` turns off the Jira enrichment even when the MR carries an issue key.
-- `--dry-run` prints the LLM settings and the Generate prompt, plus the Critique prompt unless `--no-critique` is given.
+- `--dry-run` prints the LLM settings, the context sizes and coverage, and the Generate prompt, plus the Critique prompt unless `--no-critique` is given.
 - `--no-critique` skips the second pass and renders the Generate candidates directly.
 - `--review-mode MODE` sets the behaviour when a review has already been published: `update` or `once`.
 - `--force` reviews again even when a review for this state of the MR is already published.
@@ -316,6 +364,7 @@ aireview:
     LLM_HTTP_PROXY: "http://127.0.0.1:8888"
   script:
     - bundle _2.3.26_ exec bin/aireview review "$MR_URL" --verbose
+  timeout: 45m
   retry:
     max: 1
     when:
@@ -323,6 +372,11 @@ aireview:
       - stuck_or_timeout_failure
 ```
 
+`timeout: 45m` is a chosen ceiling, not a guarantee that every retry fits in:
+when the provider is overloaded, one stage can wait up to ~14 minutes of
+pauses plus up to four requests of `LLM_TIMEOUT` each, and there are two
+stages.
+
 Set secrets such as `GITLAB_TOKEN`, `GEMINI_API_KEY` and the optional Jira
 credentials in the GitLab CI/CD variables. If the job should publish the result
 back to the merge request, add `--post` to the review command.
@@ -351,12 +405,38 @@ bundle _2.3.26_ exec rspec spec/secret_scrubber_spec.rb
 
 ## Notes
 
+- The reviewer does not check whether the specified versions of dependencies and images exist: the model's knowledge of releases is outdated, and that is what CI is for. Syntax errors and contradictions with the MR/Jira requirements are checked as usual.
 - The CLI looks for `.aireview.yml` and `.env` walking up from the current working directory, so the project config can be kept in the repository root even when the tool is run from `aireview/`.
+- How Ollama behaves when a request is still larger than its context window is up to the server, not to `aireview`: check the `ollama serve` log for truncation messages on your setup and size `max_prompt_chars` so it does not happen.
+
+## Releasing
+
+Releases are published to RubyGems.org by the `Release` workflow through
+[trusted publishing](https://guides.rubygems.org/trusted-publishing/), so no
+API key is stored anywhere. To cut a release:
+
+1. Bump `Aireview::VERSION` in `lib/aireview/version.rb` and move the
+   `Unreleased` section of `CHANGELOG.md` under the new version.
+2. Commit, then tag the commit with the same version and push the tag:
+
+   ```bash
+   git tag v0.2.0
+   git push github main v0.2.0
+   ```
+
+The workflow refuses to run when the tag does not match `Aireview::VERSION`,
+runs the test suite, builds the gem, pushes it and then creates a GitHub
+release for the tag with the matching `CHANGELOG.md` section as its notes and
+the built `.gem` attached.
 
 ## Changelog
 
 See [CHANGELOG.md](CHANGELOG.md).
 
+## Contributors
+
+See [CONTRIBUTORS.md](CONTRIBUTORS.md).
+
 ## License
 
 [MIT](LICENSE)

data/lib/aireview/cli.rb

@@ -82,7 +82,7 @@ module Aireview
         parser_result: parser_result,
         gitlab_client: gitlab_client,
         merge_request: merge_request,
-        changes_text: render_changes(changes, config),
+        changes: prepare_changes(changes, config),
         jira_issue: maybe_load_jira_issue(config, merge_request, options)
       }
     end
@@ -102,18 +102,18 @@ module Aireview
       [merge_request, changes]
     end
 
-    def render_changes(changes, config)
+    # Дифф уходит дальше по файлам, а не одной строкой: бюджет контекста
+    # режет его по границам файлов и хунков.
+    def prepare_changes(changes, config)
       diff_fetcher = DiffFetcher.new(ignore_paths: config.ignore_paths, logger: @logger)
       filtered_changes = diff_fetcher.filter(changes)
       raise Error, 'No changes left after filtering ignore_paths' if filtered_changes.empty?
 
-      scrubbed_changes = SecretScrubber.new(
+      SecretScrubber.new(
         secret_patterns: config.secret_patterns,
         secret_files: config.secret_files,
         logger: @logger
       ).scrub_changes(filtered_changes)
-
-      diff_fetcher.render(scrubbed_changes)
     end
 
     def execute_review(config, context, options)
@@ -122,7 +122,7 @@ module Aireview
       if options[:dry_run]
         dry_run = pipeline.dry_run_prompts(
           merge_request: context[:merge_request],
-          changes_text: context[:changes_text],
+          changes: context[:changes],
           jira_issue: context[:jira_issue],
           critique: !options[:no_critique]
         )
@@ -135,7 +135,7 @@ module Aireview
 
       review = pipeline.run(
         merge_request: context[:merge_request],
-        changes_text: context[:changes_text],
+        changes: context[:changes],
         jira_issue: context[:jira_issue],
         critique: !options[:no_critique]
       )
@@ -157,7 +157,7 @@ module Aireview
       publisher = Publisher.new(gitlab_client: context[:gitlab_client], logger: @logger)
       prompts = pipeline.dry_run_prompts(
         merge_request: context[:merge_request],
-        changes_text: context[:changes_text],
+        changes: context[:changes],
         jira_issue: context[:jira_issue],
         critique: !options[:no_critique]
       )
@@ -321,27 +321,7 @@ module Aireview
     end
 
     def render_dry_run(dry_run)
-      @out.puts('=== LLM SETTINGS ===')
-      @out.puts("Generate: #{dry_run[:generate_model]} temperature=#{dry_run[:generate_temperature]}")
-      if dry_run[:critique_prompt]
-        @out.puts("Critique: #{dry_run[:critique_model]} temperature=#{dry_run[:critique_temperature]}")
-      else
-        @out.puts('Critique: disabled')
-      end
-      @out.puts
-      @out.puts('=== GENERATE SYSTEM PROMPT ===')
-      @out.puts(dry_run.dig(:generate_prompt, :system_prompt))
-      @out.puts
-      @out.puts('=== GENERATE USER PROMPT ===')
-      @out.puts(dry_run.dig(:generate_prompt, :user_prompt))
-      return unless dry_run[:critique_prompt]
-
-      @out.puts
-      @out.puts('=== CRITIQUE SYSTEM PROMPT ===')
-      @out.puts(dry_run.dig(:critique_prompt, :system_prompt))
-      @out.puts
-      @out.puts('=== CRITIQUE USER PROMPT ===')
-      @out.puts(dry_run.dig(:critique_prompt, :user_prompt))
+      DryRunReport.new(@out).render(dry_run)
     end
 
     def help

data/lib/aireview/config.rb

@@ -4,9 +4,13 @@ require 'pathname'
 require 'yaml'
 require_relative 'errors'
 require_relative 'utils'
+require_relative 'config_limits'
 
 module Aireview
   class Config
+    include ConfigLimits
+    extend ConfigLimits::ClassMethods
+
     DEFAULT_SECRET_FILES = [
       '.env',
       '.env.*',
@@ -21,7 +25,6 @@ module Aireview
     ].freeze
 
     REVIEW_MODES = %w[update once].freeze
-
     DEFAULTS = {
       'review_language' => 'en',
       'review_mode' => 'update',
@@ -35,8 +38,10 @@ module Aireview
       'llm' => {
         'provider' => 'gemini',
         'temperature' => 0,
-        'timeout' => 60
-      }
+        'timeout' => 60,
+        'max_prompt_chars' => ConfigLimits::DEFAULT_MAX_PROMPT_CHARS
+      },
+      'context' => ConfigLimits::CONTEXT_DEFAULTS
     }.freeze
 
     ENV_MAPPING = {
@@ -97,6 +102,7 @@ module Aireview
     def self.env_config(env)
       mapped_env_config(env)
         .merge('llm' => llm_env_config(env))
+        .merge(context_env_config(env))
         .merge(provider_key_env_config(env))
         .merge(generic_api_key_env_config(env))
     end
@@ -113,6 +119,7 @@ module Aireview
         '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'),
         '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? }
@@ -122,7 +129,8 @@ module Aireview
       {
         'provider' => env["LLM_#{stage}_PROVIDER"],
         'model' => env["LLM_#{stage}_MODEL"],
-        'temperature' => parse_float(env["LLM_#{stage}_TEMPERATURE"])
+        'temperature' => parse_float(env["LLM_#{stage}_TEMPERATURE"]),
+        'max_prompt_chars' => parse_integer(env["LLM_#{stage}_MAX_PROMPT_CHARS"], "LLM_#{stage}_MAX_PROMPT_CHARS")
       }.compact
     end
 

data/lib/aireview/config_limits.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Aireview
+  # Лимиты контекста в символах: точного токенизатора для провайдеров локально
+  # нет, а окно Ollama задаётся на сервере и клиенту не видно. Дефолты щедрые,
+  # под конкретную модель их задают в .aireview.yml.
+  module ConfigLimits
+    LLM_STAGES = %w[generate critique].freeze
+    DEFAULT_MAX_PROMPT_CHARS = 400_000
+    CONTEXT_DEFAULTS = {
+      'max_diff_chars' => 120_000,
+      'max_mr_description_chars' => 8_000,
+      '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.
+    def max_prompt_chars(stage)
+      stage = stage.to_s
+      raise ArgumentError, "unknown LLM stage #{stage.inspect}" unless LLM_STAGES.include?(stage)
+
+      positive_integer!(
+        dig('llm', stage, 'max_prompt_chars') || dig('llm', 'max_prompt_chars') || DEFAULT_MAX_PROMPT_CHARS,
+        "llm.#{stage}.max_prompt_chars"
+      )
+    end
+
+    def max_diff_chars
+      context_limit('max_diff_chars')
+    end
+
+    def max_mr_description_chars
+      context_limit('max_mr_description_chars')
+    end
+
+    def max_jira_description_chars
+      context_limit('max_jira_description_chars')
+    end
+
+    def max_jira_comment_chars
+      context_limit('max_jira_comment_chars')
+    end
+
+    private
+
+    def context_limit(key)
+      positive_integer!(dig('context', key) || CONTEXT_DEFAULTS.fetch(key), "context.#{key}")
+    end
+
+    def positive_integer!(value, name)
+      integer = Integer(value, exception: false) if value.is_a?(Integer) || value.is_a?(String)
+      integer = value.to_i if value.is_a?(Float) && value == value.floor
+      return integer if integer.is_a?(Integer) && integer.positive?
+
+      raise ConfigError, "#{name} must be a positive integer, got #{value.inspect}"
+    end
+  end
+end

data/lib/aireview/context_budget.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+require_relative 'errors'
+
+module Aireview
+  # Укладывает контекст ревью в бюджет символов и запоминает, что при этом не
+  # вошло. Секции MR и Jira режутся до своих лимитов с сохранением начала,
+  # дифф по целым файлам, затем по целым хункам; внутри хунка не режем.
+  module ContextBudget
+    # Пути, которые не вошли, перечисляются в конце диффа; список ограничен,
+    # чтобы сам не съел бюджет.
+    NOT_SHOWN_LIST_LIMIT = 20
+    TRAILER_RESERVE_CHARS = 400
+
+    Coverage = Struct.new(
+      :truncated_sections, :files_not_shown, :files_partial, :files_unavailable, :hunks_skipped,
+      keyword_init: true
+    ) do
+      def self.empty
+        new(truncated_sections: [], files_not_shown: [], files_partial: [], files_unavailable: [], hunks_skipped: [])
+      end
+
+      def complete?
+        to_h.values.all?(&:empty?)
+      end
+    end
+
+    Packed = Struct.new(:text, :shown_hunks, :total_hunks, keyword_init: true)
+
+    # Начало важнее конца: требования и критерии приёмки обычно там.
+    def self.truncate_section(text, limit:, label:, coverage:)
+      text = text.to_s
+      return text if text.length <= limit
+
+      coverage.truncated_sections << label
+      "#{text[0, limit]}\n[#{label} truncated: #{limit} of #{text.length} chars shown]"
+    end
+
+    def self.pack_entries(entries, budget:, coverage:)
+      Packer.new(entries, budget: budget, coverage: coverage).pack
+    end
+
+    # Файлы без хунков идут первыми: они дёшевы и всегда полезны для картины
+    # MR. Текстовые файлы идут в порядке GitLab, пока влезают; первый файл,
+    # который не влезает, показывается частично, всё после него не показывается.
+    # Хунк, который не влез бы даже в пустой бюджет, пропускается с пометкой,
+    # а не останавливает раскладку.
+    class Packer
+      def initialize(entries, budget:, coverage:)
+        @non_text, @text = entries.partition { |entry| !entry.text? }
+        @budget = budget
+        @coverage = coverage
+        @total_hunks = @text.sum { |entry| entry.hunks.size }
+      end
+
+      def pack
+        @non_text.each { |entry| @coverage.files_unavailable << entry.path if entry.unavailable? }
+        full = (@non_text + @text).map(&:render).join("\n")
+        return Packed.new(text: full, shown_hunks: @total_hunks, total_hunks: @total_hunks) if full.length <= @budget
+
+        pack_within_limit
+      end
+
+      private
+
+      # Что-то придётся опустить, значит нужен хвост со списком пропущенного.
+      # @used считает весь собранный текст, включая разделители между
+      # файлами: результат не должен выйти за бюджет ни на символ.
+      def pack_within_limit
+        @parts = @non_text.map(&:render)
+        @used = joined_length(@parts)
+        @limit = @budget - TRAILER_RESERVE_CHARS
+        raise_no_room!(:non_text) if @used > @limit
+
+        shown_hunks = pack_text_entries
+        raise_no_room!(:hunks) if shown_hunks.zero? && @total_hunks.positive?
+
+        @parts << not_shown_trailer unless @coverage.files_not_shown.empty?
+        Packed.new(text: @parts.join("\n"), shown_hunks: shown_hunks, total_hunks: @total_hunks)
+      end
+
+      def pack_text_entries
+        shown_hunks = 0
+        stopped = false
+        @text.each do |entry|
+          piece, shown, stopped = stopped ? ['', 0, true] : pack_entry(entry)
+          if shown.zero?
+            @coverage.files_not_shown << entry.path
+            next
+          end
+
+          @parts << piece
+          @used = joined_length(@parts)
+          shown_hunks += shown
+        end
+        shown_hunks
+      end
+
+      # Место под следующий кусок с учётом разделителя перед ним.
+      def remaining
+        @limit - @used - (@parts.empty? ? 0 : 1)
+      end
+
+      # Возвращает [текст, число показанных хунков, остановлена ли раскладка].
+      def pack_entry(entry)
+        full = entry.render
+        return [full, entry.hunks.size, false] if full.length <= remaining
+
+        body, shown, skipped, stopped = pack_hunks(entry)
+        return ['', 0, stopped] if shown.zero?
+
+        skipped.each { |hunk| @coverage.hunks_skipped << {path: entry.path, hunk: hunk} }
+        @coverage.files_partial << {path: entry.path, shown: shown, total: entry.hunks.size}
+        [entry.header + body + partial_marker(entry, shown), shown, stopped]
+      end
+
+      # Место сначала отдаётся хункам, которые можно показать, и только на
+      # остаток добавляются пометки о слишком больших: иначе пометки могли бы
+      # вытеснить единственный подходящий хунк. Факт пропуска в покрытие
+      # попадает независимо от того, есть ли для пометки место.
+      def pack_hunks(entry)
+        base = entry.header.length + partial_marker(entry, 0).length
+        shown = []
+        skipped = []
+        stopped = false
+        used = 0
+        entry.hunks.each_with_index do |hunk, index|
+          if base + hunk.length > @limit
+            skipped << index
+            next
+          end
+          if base + used + hunk.length > remaining
+            stopped = true
+            break
+          end
+
+          shown << index
+          used += hunk.length
+        end
+
+        body = render_hunks(entry, shown: shown, skipped: skipped, room: remaining - base - used)
+        [body, shown.size, skipped.map { |index| index + 1 }, stopped]
+      end
+
+      def render_hunks(entry, shown:, skipped:, room:)
+        marked = skipped.select do |index|
+          marker = skip_marker(entry, index)
+          next false if marker.length > room
+
+          room -= marker.length
+          true
+        end
+        entry.hunks.each_with_index.filter_map do |hunk, index|
+          next hunk if shown.include?(index)
+
+          skip_marker(entry, index) if marked.include?(index)
+        end.join
+      end
+
+      def skip_marker(entry, index)
+        "[hunk #{index + 1} of #{entry.hunks.size} skipped: larger than the context budget]\n"
+      end
+
+      def joined_length(parts)
+        parts.sum(&:length) + [parts.size - 1, 0].max
+      end
+
+      def partial_marker(entry, shown)
+        "[file #{entry.path}: #{shown} of #{entry.hunks.size} hunks shown]\n"
+      end
+
+      def not_shown_trailer
+        paths = @coverage.files_not_shown
+        listed = []
+        paths.first(NOT_SHOWN_LIST_LIMIT).each do |path|
+          break if listed.sum(&:length) + path.length > TRAILER_RESERVE_CHARS / 2
+
+          listed << path
+        end
+        rest = paths.size - listed.size
+        list = listed.join(', ')
+        list += " and #{rest} more" if rest.positive?
+        "[#{paths.size} file(s) not shown: #{list}]\n"
+      end
+
+      def raise_no_room!(reason)
+        detail = if reason == :non_text
+                   'the entries for files without text changes alone exceed it'
+                 else
+                   "not a single hunk fits after #{@used} chars of entries without text changes"
+                 end
+        raise ContextBudgetError,
+              "Diff does not fit into the context budget of #{@budget} chars: #{detail}. " \
+              'Raise llm.max_prompt_chars / context.max_diff_chars, or add paths to ignore_paths.'
+      end
+    end
+  end
+end