aireview 0.3.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 394d2acbc7ed98d03e3a1f87e61fd9f07e1985b40ad47e4086fce47e5a18f5be
-  data.tar.gz: 85598cb2c2e81f95ff59e40bb5d2cef47d4813caf49f0ef318cf5931651adbf7
+  metadata.gz: 3f326ae1b11f59f7c447e8f128ab94845ef1543b0b377753f053fd4f69e03bad
+  data.tar.gz: c5908173ca8020a0563b6d4ee1fd4d8ce4ebe609fda7ded26d5b7eb40c84dda1
 SHA512:
-  metadata.gz: c45f78bc422def8e2392499ba1dc0e7f87e67183bad8b9e9a29b3b242512caf0a006511922ad32f6a237d6e971578861a86ebb5107790e86e4c3e34598d9c6e6
-  data.tar.gz: fb33990e5743821e8bef7900241ff6b5b7d7f575d3a22ac3eb645990c7050e792d46927c71d401ab659e200366e23acacb9d4f62eef6c74e70e78e7a76bc9111
+  metadata.gz: 2de9b7dd7e6caaa440287339d03eed843dfdb73010ae8cf6a01dea4e9348e3b072fc4fb61a55bf30eb4ed324e857ff883e35e31b711bc542cb8d1495645041bc
+  data.tar.gz: 5f0867f71415c019c03d99bd2215fc7f7ef7cadf98ab8b0db91e6eb98af54cfae3787b848c7611fc371cfa19cc94acd55e170047f094d8543f5c77f258e3313d

data/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## 2.0.0
+
+Breaking: the review key of a shared pool includes the pool order and the
+critique policy; a single chain without reserves gets three requests instead
+of a seventeen-minute schedule; `LLM_PROVIDER` no longer re-targets models
+that carry an explicit provider.
+
+- Defaults shipped in the image: `config/defaults.yml` is a configuration
+  layer between the built-in values and the project's `.aireview.yml`,
+  enabled by `AIREVIEW_DEFAULTS` (set in the Dockerfile). A project needs no
+  model names; `--dry-run` prints the layer every setting came from and
+  warns when inherited reserves silently change provider.
+- Shared model pool: `llm.models` (`LLM_MODELS`) in order of priority,
+  `generate.start`, `critique.rank: not_below_generate|any` and
+  `critique.allow_weaker`. Generate walks the pool round from its start;
+  Critique takes the first live model not below the one that answered in
+  Generate, never weaker unless allowed. A stage with a `model` of its own
+  keeps an independent chain.
+- Router: an overloaded model or a timeout gets one short retry, then a
+  quarantine (`llm.overloaded_quarantine`, `LLM_OVERLOADED_QUARANTINE`,
+  120 s) and the next model; the walk goes round the pool once every model
+  has been tried, waiting for the nearest quarantine to end. Three requests
+  per model per stage, counted across keys and including the JSON repair;
+  the last model has no special schedule. A model the provider does not
+  have (retired, a typo, not pulled into Ollama) is excluded for the run
+  instead of failing it; a bare 404 stays fatal.
+- An invalid result that the same model cannot repair excludes that model
+  for the stage and restarts the stage on the next model with the original
+  request; Critique keeps the candidates already obtained.
+- `aireview models check`: two probe requests per model with the production
+  schemas and validation, statuses `ok / missing / invalid / unverified /
+  failed / skipped`, `--strict` turns a skipped (unreachable) Ollama into a
+  failure. Meant for release pipelines and schedules.
+- `templates/review.gitlab-ci.yml`: a job template projects include with
+  `ref: stable`; every config variable is passed into the container by name.
+- The log names the model that answered each stage and its place in the
+  chain; the report notes a critique that ran on a weaker model.
+- Fixed: with `json` 3.0 every provider answer failed to parse
+  (`Faraday::ParsingError`, "wrong number of arguments") — `faraday` 2.14.4
+  in the lockfile. The suite did not catch it because it stubs the network;
+  `aireview models check` did.
+- Internals: routing plans (`StageChains`, `ModelPool`) and the router's
+  `ModelState` are objects, `ConfigLoader` owns loading and env parsing,
+  `ResultParser` parses LLM results, `LlmClient` makes one request while
+  the router retries. Specs run against the real RubyLLM classes.
+
 ## 0.3.0
 
 - Fallback models per stage (`llm.<stage>.fallbacks`,

data/README.md

@@ -49,8 +49,10 @@ installed, replace it with plain `aireview`.
 
 ## Configuration
 
-Secrets live in environment variables or in a local `.env` file. In `.env` the
-Generate and Critique models are set explicitly:
+Secrets live in environment variables or in a local `.env` file. The models of
+both stages come from the defaults shipped in the Docker image (see "Defaults
+shipped in the image"); outside the image they are set in `.env` or
+`.aireview.yml`:
 
 ```bash
 GITLAB_URL=https://gitlab.company.com
@@ -91,6 +93,88 @@ If only the LLM traffic has to go through a proxy, set `LLM_HTTP_PROXY` or
 `llm.http_proxy`. That configures RubyLLM only; requests to GitLab and Jira
 keep going directly.
 
+### Defaults shipped in the image
+
+Models, timeouts and the report language are baked into the image as
+`config/defaults.yml`; inside the image `AIREVIEW_DEFAULTS` points at it. A
+project in an organization has nothing to configure: no `.aireview.yml`, no
+variables with model names. Changing the model for every project is one
+edit of that file and a new image release. Outside the image the variable is
+unset and the layer does not exist, so local runs are unaffected; point
+`AIREVIEW_DEFAULTS` at any file to get the same layer elsewhere. The
+defaults define a shared pool of five Gemini models (see "Shared model
+pool"): Generate starts from a mid-range model and goes round the pool,
+Critique takes the strongest live model not below the one Generate answered
+with; every model of the pool is confirmed by `aireview models check` on
+release.
+
+The configuration layers, weakest first:
+
+1. built-in values (`Config::DEFAULTS`);
+2. image defaults — the file from `AIREVIEW_DEFAULTS`; no variable, no layer;
+3. the project's `.aireview.yml`;
+4. environment variables (`LLM_GENERATE_MODEL` and the rest);
+5. CLI flags (`--generate-model`, `--critique-model`, the temperatures).
+
+Layers merge by key, so a project overrides only what it needs — with two
+caveats about the pool:
+
+- a `llm.generate.model` of its own (in YAML or `LLM_GENERATE_MODEL`) **takes
+  the stage out of the pool**: its chain is that model plus its own
+  `fallbacks`, if any; the image models are not picked up for that stage and
+  the critique rank rule does not apply. To change only the starting model
+  while staying in the pool, set `llm.generate.start` / `LLM_GENERATE_START`
+  — or replace the whole pool through `llm.models` / `LLM_MODELS`;
+- every pool model in the image carries an explicit provider (`gemini`), so
+  `LLM_PROVIDER=ollama` on its own does not move the Gemini pool to Ollama:
+  it only changes the default provider of models without one. A project on
+  Ollama sets its own models — its own pool (`LLM_MODELS=ollama/qwen2.5-coder:7b,…`)
+  or per-stage `model`s.
+
+The shared settings `llm.temperature`, `llm.max_prompt_chars` and the default
+provider `llm.provider` (env: `LLM_TEMPERATURE`, `LLM_MAX_PROMPT_CHARS`,
+`LLM_PROVIDER`) apply to the stages layer by layer: a stage value from the
+image defaults does not beat a shared value from the project or the
+environment, while within one layer the stage value still wins. For stages
+on their own chains the `fallbacks` array is replaced as a whole when given
+explicitly; `fallbacks: []` removes the reserves; a reserve without a
+`provider` of its own inherits the stage provider — if a project overrode the
+stage provider (`LLM_GENERATE_PROVIDER=ollama`) while inherited reserves
+without an explicit provider remain in the chain, they silently become
+"models" of the new provider. `--dry-run` warns about that and prints, for
+every model, the layer it came from:
+
+```
+=== LLM SETTINGS ===
+Config: image defaults /app/config/defaults.yml, .aireview.yml /app/.aireview.yml
+Generate: gemini-3.7-flash temperature=0.1 (model from image defaults, provider from image defaults)
+  fallbacks: gemini/gemini-3.6-flash -> ... (fallbacks from image defaults)
+Critique: qwen2.5-coder:7b temperature=0 (model from .aireview.yml, provider from .aireview.yml)
+Time budget: 1800s, overloaded quarantine: 120s
+```
+
+In pool mode the model source is the layer that set the stage `start` or the
+`llm.models` list itself; `--critique-model` with a pool model shows up as
+`model from cli`.
+
+An `AIREVIEW_DEFAULTS` that points at a missing file is a configuration
+error: such an image was built wrong, and failing at once beats reviewing
+with the wrong models. Keys and tokens never live in `config/defaults.yml`.
+
+Changing the default models or the pool order changes the review key (see "A
+single comment per merge request"). What happens to open MRs depends on
+`review_mode`: in `update` the review re-runs on the next push to the MR, in
+`once` (as in the CI template) only on a job Retry. In `update` this is a
+one-off burst of requests to the provider — better not to ship such a
+release at peak hours.
+
+No model is probed before a review: there are no test requests to five
+models per MR, availability is learned from the working requests — the first
+Generate request is the probe, and what the router learns it remembers until
+the end of the run (see "Fallback models and keys"). The separate smoke test
+of every model with both schemas (`aireview models check`) runs on an image
+release and on a schedule, not on MRs.
+
 ### Local Ollama
 
 Install Ollama following the
@@ -169,15 +253,16 @@ address with `/v1` matches the
 local model it can be raised, but not without limit: a hung request holds
 the job for exactly that long while a fallback model sits idle. An
 "overloaded" (503) answer from the provider or a timeout does not fail the
-run right away: without a fallback model such a request gets up to five
-attempts, the original one and four retries with pauses of about 2, 5, 5 and
-5 minutes; with a fallback model, one short retry and a switch (see
-"Fallback models and keys"). 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
-from the base `llm` settings. `llm.provider` is used as the default when
+run right away: the model gets one short retry (~30 s), then goes into
+quarantine for two minutes while the request goes to the next model;
+without a fallback model the router waits for the quarantine to end and
+tries once more. Three requests per model per stage in total (see "Fallback
+models and keys"). Only the failed stage is repeated, not the whole run.
+
+Project rules live in `.aireview.yml`. The `generate.model` and
+`critique.model` settings are not inherited from the base `llm` settings: a
+review does not start when a stage has no model in the image defaults, the
+YAML or the environment. `llm.provider` is used as the default when
 `generate.provider` or `critique.provider` is not set:
 
 ```yaml
@@ -300,31 +385,119 @@ fallback model and a provider can have a fallback key:
   forbid circumventing its limits regardless of the project's billing. Keys
   live only in the environment, never in `.aireview.yml`.
 
+#### Shared model pool
+
+Instead of two independent chains a single pool can be configured:
+`llm.models` in order of priority (the first is the preferred one for
+Critique). Generate goes through the pool from `generate.start` downwards
+and round again; Critique takes the first live model **not below the one
+that actually answered in Generate** (`critique.rank: not_below_generate`,
+the default), with self-critique by the same model as the last permitted
+option. "Above" and "below" are positions in the list, they are not derived
+from model names:
+
+```yaml
+llm:
+  provider: gemini
+  models:                          # order = priority for Critique
+    - gemini-3.8-flash
+    - gemini-3.7-flash
+    - gemini-3.6-flash
+    - provider: ollama
+      model: qwen2.5-coder:7b
+      max_prompt_chars: 20000
+  generate:
+    start: gemini-3.7-flash        # Generate starts here, then downwards and round
+  critique:
+    rank: not_below_generate       # or any — the chains are independent
+    allow_weaker: false            # true — go below when nothing above is alive
+```
+
+Environment equivalents: `LLM_MODELS=gemini/gemini-3.8-flash,gemini/gemini-3.7-flash,…`,
+`LLM_GENERATE_START`, `LLM_CRITIQUE_START`, `LLM_CRITIQUE_RANK`,
+`LLM_CRITIQUE_ALLOW_WEAKER`. The rules:
+
+- no permitted live model for Critique and `allow_weaker: false` — the run
+  fails, candidates are not published without a critique; with
+  `allow_weaker: true` Critique goes below Generate and the report gets a
+  "Critique ran on a model weaker than Generate" line;
+- a stage with a `model` of its own (in YAML, the environment or
+  `--generate-model` with a model outside the pool) does not use the pool:
+  its chain is independent and the rank rule does not apply, as with
+  `rank: any`; `--generate-model` / `--critique-model` with a model **from**
+  the pool bring the stage back into the pool and make that model the start
+  (the stage's own `model` and `fallbacks` are reset), with a model outside
+  the pool — a single chain without reserves;
+- a project that replaces the whole pool (`llm.models` in YAML or
+  `LLM_MODELS`) need not repeat `start`: a start inherited from the image
+  that the new pool does not contain is replaced by the first model of the
+  new pool with a warning in the log. A start set in the same layer as the
+  pool or above it must be in the pool — a typo there stays a configuration
+  error;
+- `critique.start` goes first only when the rank permits it; a start below
+  the model that answered in Generate is skipped with a warning when
+  `allow_weaker` is off — it does not bypass the ban on a weaker critique;
+- the review key (see "A single comment per merge request") includes the
+  whole pool together with the critique policy: its order decides which
+  model checks the findings, not just what to fall back to. Reordering the
+  pool, changing `start`, `rank` or `allow_weaker` — a new key, open MRs are
+  re-reviewed on the next push; moving from per-stage chains to the pool —
+  the same, once;
+- `--dry-run` prints the chains of both stages and a `Critique rule: …` line.
+
 What happens on which error:
 
 | Error | Reaction |
 |---|---|
-| Daily quota (`quotaId` like `…PerDay…` in Google's answer) | No retries: the next key on the same model. The "key + model" pair is remembered until the end of the run so that Critique and the JSON repair do not hit it again. Out of keys: the next model with the first key. |
-| Per-minute limit (429 with a "retry in N s" hint) | Retry after the hinted delay; one retry while there is somewhere to switch to, up to three on the last route. Then the next key, then the next model. |
-| Overloaded (503) or timeout | One short retry (~30 s) and the next model with the same key. The last model in the chain gets the full 2/5/5/5 minute schedule. |
-| Other API errors (schema, context length, auth) | The run fails right away: a fallback model would answer the same. |
-
-All of this is bounded by a time budget for the LLM part of the run:
-`llm.time_budget` / `LLM_TIME_BUDGET`, 1800 seconds by default. A pause that
-does not fit into the remainder is skipped and the request timeout is capped
-by the remainder; when the time is up, the run fails with an error listing
-everything that was tried. Because of this keep `LLM_TIMEOUT` around 120–300
-seconds: one hung request must not eat the whole budget.
+| Daily quota (`quotaId` like `…PerDay…` in Google's answer) | No retries: the next key on the same model. The "key + model" pair is remembered until the end of the run so that Critique and the JSON repair do not hit it again. Out of keys: the model is excluded until the end of the run, the request goes to the next one. |
+| Per-minute limit (429 with a "retry in N s" hint) | One retry after the hinted delay, then the next key. Out of keys: the model is quarantined for the hinted time, the request goes to the next one. |
+| Overloaded (503) or timeout | One short retry (~30 s), then a quarantine of `llm.overloaded_quarantine` / `LLM_OVERLOADED_QUARANTINE` (120 s by default) and the next model with the same key. |
+| The provider has no such model (the answer text names the model: retired, a typo, not pulled into Ollama) | No retries: the model is excluded until the end of the run, the request goes to the next one. A bare 404 without such text is fatal: a wrong `LLM_API_BASE` answers the same, and the next model will not help. |
+| An invalid result (not JSON, not the schema, foreign ids in the verdicts) — and still invalid after one repair by the same model | The model is excluded for this stage, the stage starts over on the next model with the original request. For Critique the candidates already obtained are kept, Generate is not repeated. |
+| Other API errors (context length, auth) | The run fails right away: a fallback model would answer the same. |
+
+The chain is walked round: once every model has been tried, the router
+returns to those whose quarantine has expired; when all are quarantined, it
+waits for the nearest release. The last model in the list is nothing
+special, nobody gets a long retry schedule. Two limits keep the walk
+finite:
+
+- **three requests per model per stage** (`MAX_ATTEMPTS_PER_MODEL`). Every
+  request sent counts regardless of its outcome, including the short retry
+  and the JSON repair; the keys of one model share one counter, a quarantine
+  does not reset it. Out of requests — the model leaves the stage; a JSON
+  repair without requests left is not sent, and the result counts as invalid
+  (see the table). When every model of the stage is out or excluded, the
+  stage ends at once, quarantines are not waited for;
+- **the time budget** of the LLM part of the run: `llm.time_budget` /
+  `LLM_TIME_BUDGET`, 1800 seconds by default. A pause or a quarantine wait
+  that does not fit into the remainder is skipped, the request timeout is
+  capped by the remainder; when the time is up, the run fails with an error
+  listing everything that was tried. Because of this keep `LLM_TIMEOUT`
+  around 120–300 seconds: one hung request must not eat the whole budget.
+
+**A single chain** — one model without reserves, typically Ollama on its own
+box — behaves differently from earlier versions: instead of seventeen minutes
+of waiting (retries after 2, 5, 5 and 5 minutes) the model gets three
+requests — the original, a short retry after ~30 s and one more after the
+two-minute quarantine; after the third failure the stage fails. A timeout is
+a failure too, and a quarantine will not help a slow model: it only
+lengthens the pause between attempts. A slow local model needs an
+`LLM_TIMEOUT` with room for the largest request and an `LLM_TIME_BUDGET`
+that fits three such requests with their pauses; `LLM_OVERLOADED_QUARANTINE`
+is about a model that is temporarily overloaded and should come back.
 
 The review key (see "A single comment per merge request") is computed from
 the configured primary model, not from the one that answered: a review made
 by a fallback model is not rewritten on the next push without changes in the
-MR, and adding a fallback model to the config does not re-run the review on
-every open MR. When a stage went to a fallback model, the report ends with a
-`Fallback model used: critique — …` line. A key switch stays in the log only,
-and key values never reach the log. `--dry-run` prints the model chains and
-the number of keys per provider, `--no-fallbacks` leaves one model and one
-key per stage.
+MR, and adding a fallback model to a per-stage chain does not re-run the
+review on every open MR. When a stage went to a fallback model, the report
+ends with a `Fallback model used: critique — …` line; the log names, for
+every stage, the model that answered and its place in the chain
+(`model=gemini/gemini-3.6-flash (2/5)`). A key switch stays in the log only,
+and key values never reach the log. `--dry-run` prints the model chains, the
+number of keys per provider, the time budget and the quarantine length;
+`--no-fallbacks` leaves one model and one key per stage.
 
 ### Checking that findings point at the diff
 
@@ -373,6 +546,42 @@ bundle _2.3.26_ exec bin/aireview review https://gitlab.company.com/team/project
 - `--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.
 
+### Checking the models
+
+```bash
+bundle _2.3.26_ exec bin/aireview models check
+bundle _2.3.26_ exec bin/aireview models check --config .aireview.yml --strict --verbose
+```
+
+Every model of both stage chains gets two small requests — one with the
+production Generate schema and one with the Critique schema — on a tiny
+synthetic MR, with the same system prompts as a review. The answer goes
+through the same validation as in a run (JSON shape, candidate and verdict
+ids). The provider's catalog is not consulted: "the model is listed" does
+not mean "our request with the schema passes on it". There are no reserves,
+retries or quarantine here — this is a check, not a review; only a
+per-minute limit gets one retry after the provider's hint.
+
+```
+Checking 5 model(s) with the generate and critique schemas
+gemini/gemini-3.7-flash          generate ok (4.6s)
+gemini/gemini-3.7-flash          critique ok (6.9s)
+gemini/gemini-3.6-flash          generate unverified: This model is currently experiencing high demand. …
+gemini/gemini-9.9-nope           generate missing: models/gemini-9.9-nope is not found for API version v1beta, …
+ollama/qwen2.5-coder:7b          generate skipped: Connection refused
+Result: 6 ok, 1 unverified, 2 missing, 2 skipped -> FAILED
+```
+
+Statuses: `ok` — an answer matching the schema; `missing` — the provider
+has no such model (retired, a typo, not pulled into Ollama); `invalid` — it
+answered, but not by the schema; `unverified` — the provider could not
+answer right now (overload, quota, timeout), the model is not at fault but
+not confirmed either; `failed` — other API errors; `skipped` — Ollama is
+unreachable where the check runs (a CI runner has none). The exit code is 0
+only when every model is `ok` or `skipped`; with `--strict` — only `ok`: on
+a box where Ollama must be running, an unreachable Ollama is a failed check,
+not a skip.
+
 ### A single comment per merge request
 
 With `--post` the review is not published as a new note every time; it updates
@@ -473,6 +682,46 @@ local HTTP proxy (`wireproxy`, for instance) before `aireview` starts and point
 GitLab and Jira stay on direct connections while RubyLLM goes through the
 tunnel.
 
+### Including the job template
+
+Instead of copying the job into every project, it lives in this repository
+as `templates/review.gitlab-ci.yml`. A project's `.gitlab-ci.yml` keeps only:
+
+```yaml
+include:
+  - project: your-group/aireview
+    ref: stable
+    file: /templates/review.gitlab-ci.yml
+```
+
+The template is written for shell-executor runners (the image runs through
+`docker run` with secrets passed by name) and carries `[skip review]`,
+`resource_group`, `allow_failure` and `REVIEW_MODE=once`. Models come from
+the image defaults, `.aireview.yml` is mounted into the container only when
+the project has one. The job runs in the `.post` stage — it exists in every
+pipeline, so a project does not declare `stages`; to move the review to
+another stage, add `aireview: {stage: review}` to the project file. Every
+variable the config reads (`Config.env_names`: models, providers, reserves,
+temperatures, limits, `OLLAMA_API_BASE` and so on) is passed into the
+container by name, so a project can override anything through its CI/CD
+variables — for instance, swap an unavailable model with `LLM_CRITIQUE_MODEL`
+without waiting for an image release.
+
+Secrets stay CI/CD variables **of the project**: group variables are readable
+by any merge request of any project in the group.
+
+The `stable` branch is managed: the copy of the template there pins
+`AIREVIEW_IMAGE_TAG` to a verified release. Updating or rolling back every
+project that includes the template is one edit of `stable`. A project can
+pin another version by overriding `AIREVIEW_IMAGE_TAG` in its `variables`.
+
+A release of the image is: tag → `aireview models check` on the image
+defaults (an API error or an answer off the schema for any model stops the
+pipeline, the image is not built, the previous version stays in the
+registry) → build and push → set the new tag in `stable`. The same check on
+a schedule (once a day) is the early signal that the provider retired a
+model — otherwise the first to learn about it is a live MR.
+
 ## Docker
 
 ```bash

data/config/defaults.yml

@@ -0,0 +1,47 @@
+# Defaults baked into the aireview image. This layer sits between the
+# built-in values and the project's .aireview.yml: a project overrides
+# anything here, the environment and CLI flags override the project. No
+# keys live here.
+#
+# One shared pool of models (see README, "Shared model pool"): the order is
+# the priority for Critique, the first model is the preferred one. Generate
+# starts at generate.start and goes down the list and round again; Critique
+# takes the first live model not below the one that answered in Generate
+# and never goes lower.
+#
+# Every model carries an explicit provider: a model without one inherits
+# llm.provider, and a project that switched it to ollama would otherwise get
+# "Ollama models" with Gemini names.
+#
+# Model names come from the Gemini catalog (GET /v1beta/models), text models
+# without "preview" in the name only; each one is confirmed by
+# `aireview models check` with both schemas (2026-09-18).
+
+review_language: en
+
+llm:
+  provider: gemini
+  temperature: 0
+  # Three attempts per model × timeout is the ceiling for one hung model:
+  # 300 s meant 15 minutes, 180 s means 9.
+  timeout: 180
+  time_budget: 1800
+  overloaded_quarantine: 120
+  models:
+    - provider: gemini
+      model: gemini-3.8-flash
+    - provider: gemini
+      model: gemini-3.7-flash
+    - provider: gemini
+      model: gemini-3.6-flash
+    - provider: gemini
+      model: gemini-3.5-flash
+    - provider: gemini
+      model: gemini-3.5-flash-lite
+  generate:
+    start: gemini-3.7-flash
+    temperature: 0.1
+  critique:
+    rank: not_below_generate
+    allow_weaker: false
+    temperature: 0

data/lib/aireview/candidate_checker.rb

@@ -3,11 +3,12 @@ require 'logger'
 require 'set'
 
 module Aireview
-  # Механическая проверка привязки кандидата к коду по тому диффу, который
-  # реально ушёл в модель: файл, строка, цитата. Проверяется привязка, а не
-  # сам баг: ненайденная цитата — повод критику присмотреться, не
-  # доказательство выдумки. Файл, которого нет среди изменений MR, — другое
-  # дело: такого кандидата проверять нечем, он отбрасывается.
+  # A mechanical check that a candidate points at the code, against the diff
+  # the model actually saw: file, line, quote. The anchoring is checked, not
+  # the bug itself: a quote that is not found is a reason for Critique to
+  # look closer, not proof of a fabrication. A file that is not among the MR
+  # changes is a different matter: there is nothing to check such a
+  # candidate against, it is dropped.
   class CandidateChecker
     HUNK_HEADER = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/
     FILE_HEADER = %r{^diff --git a/(.+?) b/(.+)$}
@@ -15,12 +16,12 @@ module Aireview
     NOTE_LINE_RESET = 'line was outside the shown hunks and has been reset to null'
     NOTE_NOT_VERIFIED = 'file shown partially or without a diff, location not verified'
 
-    # Один файл из контекста: диапазоны строк нового файла по показанным
-    # хункам и нормализованный текст каждого хунка для поиска цитаты —
-    # отдельно новая сторона (контекст + добавленные строки) и старая
-    # (контекст + удалённые), чтобы многострочная цитата из одной версии
-    # файла находилась целиком. Хунки не склеиваются: между ними пропущенный
-    # код, и цитата через границу хунка — не цитата.
+    # One file of the context: the new-file line ranges of the shown hunks
+    # and the normalized text of every hunk for the quote search — the new
+    # side (context + added lines) and the old side (context + removed
+    # lines) separately, so that a multi-line quote from one version of the
+    # file is found whole. Hunks are not glued together: there is skipped
+    # code between them, and a quote across a hunk boundary is not a quote.
     Section = Struct.new(:ranges, :hunks, :partial, keyword_init: true) do
       def include?(quote)
         hunks.any? { |hunk| hunk[:new_text].include?(quote) || hunk[:old_text].include?(quote) }
@@ -34,9 +35,9 @@ module Aireview
       @sections = parse_sections(diff_text.to_s)
     end
 
-    # Возвращает кандидатов с пометками: note для критика, quote_missing для
-    # отчёта, line сброшена в null, если не подтвердилась. Кандидаты с файлом
-    # не из MR отброшены.
+    # Returns the candidates with marks: a note for Critique, quote_missing
+    # for the report, line reset to null when it was not confirmed.
+    # Candidates with a file outside the MR are dropped.
     def check(candidates)
       candidates.filter_map do |candidate|
         id = value(candidate, 'id')
@@ -85,10 +86,10 @@ module Aireview
       NOTE_QUOTE_NOT_FOUND
     end
 
-    # Дифф уже собран под бюджет: у показанного частично файла хунков может
-    # не хватать, у файла без диффа хунков нет вовсе. Заголовки --- / +++
-    # бывают только между заголовком файла и первым @@; внутри хунка строка
-    # «+++ x» — это добавленный код «++ x».
+    # The diff is already packed to the budget: a partially shown file may
+    # lack hunks, a file without a diff has none at all. The --- / +++
+    # headers occur only between the file header and the first @@; inside a
+    # hunk a "+++ x" line is the added code "++ x".
     def parse_sections(diff_text)
       sections = {}
       section = nil
@@ -108,8 +109,8 @@ module Aireview
       normalize_hunks(sections)
     end
 
-    # Хунк без новых строк (удаление, @@ -1 +0,0 @@) диапазона не даёт:
-    # строки 0 в новом файле нет.
+    # A hunk without new lines (a deletion, @@ -1 +0,0 @@) gives no range:
+    # there is no line 0 in the new file.
     def start_hunk(section, header)
       start = header[1].to_i
       length = header[2] ? header[2].to_i : 1
@@ -142,8 +143,9 @@ module Aireview
       partial.each { |path| sections[path]&.partial = true }
     end
 
-    # Сначала точное совпадение: каталоги a/ и b/ бывают настоящими. Префикс
-    # из заголовка диффа снимается только если точного пути в MR нет.
+    # An exact match first: a/ and b/ directories can be real. The prefix
+    # from the diff header is stripped only when the exact path is not in
+    # the MR.
     def resolve_path(path)
       path = path.to_s.strip
       return path if @mr_paths.include?(path)