Revieko PR ревью — Быстрый старт

Этот документ объясняет, как быстро читать PR-коммент Revieko и какие действия выбрать: принять, запросить правку, упростить, изолировать изменение или углубиться в полный отчёт.

1) Что такое отчёт Revieko

Revieko — это радар для ревью, который подсвечивает места, где PR нетипично меняет структуру/поведение относительно привычного “рисунка” репозитория.

В отчёте есть три независимых слоя сигнала:

Structure — форма кода (ветвления, вложенность, “разрывы паттерна”, хвосты).
Semantic (effects/taint) — где в диффе появляются side-effects (NET_IO/DB/FILE_IO/EXEC/LOG) и рядом какие источники (USER_INPUT/SECRET/...).
Control — режимы пути исполнения (условия, error-ветки, return-хвосты, init/cleanup).

Важное: это не SAST и не баг-файндер. Инструмент не “доказывает” ошибку — он помогает сфокусировать внимание ревьюера.

2) Два уровня выдачи: PR-коммент vs Full report

Обычно в GitHub вы видите:

2.1. PR-коммент (короткий)

Содержит:

общий статус (Status, risk_level, ci_status, analysis full/partial),
struct_risk,
top-N hotspots (по важности),
per-file structural risk,
ссылки на Full report: Markdown / JSON.

2.2. Full report (по ссылке)

Нужен, когда:

PR большой и хочется “всё”,
нужно проверить детали (effects/taint/control/invariants),
analysis=partial и важно понять, что именно было пропущено,
нужно работать “как с артефактом” (Markdown рядом с diff’ом или JSON для автоматизации).

Top-N hotspots в PR-комменте — это лимит вывода, а не ограничение понимания. Это “первые по приоритету” участки, чтобы не превращать комментарий в простыню.

3) Алгоритм чтения PR-коммента за 3–5 минут (строгий порядок)

Шаг 1. 15 секунд: общий сигнал

Смотрите сразу 4 поля:

risk_level (low|medium|high)
struct_risk (0–100)
ci_status (ok|warn|fail)
analysis (full|partial)

Быстрое правило:

risk_level=high → почти всегда идём в hotspots и главный файл.
analysis=full → весь код, который CodeGuard умеет анализировать в этом репозитории (на текущем этапе — Python), был обработан.
analysis=partial → в PR есть файлы вне профиля анализа (например, YAML/CSV/Markdown и т.п.), и по ним CodeGuard не делал анализ. Python-часть PR при этом обработана полностью.

Шаг 2. 30 секунд: “какой файл главный”

Откройте Per-file structural risk и ответьте:

какой файл даёт основную долю риска?
риск сосредоточен в одном файле или размазан?

Если один файл тащит всё — ревью ускоряется: начинайте с него.

Шаг 3. 2 минуты: top-3 / top-5 hotspots

Откройте Top hotspots и пройдитесь по первым 3–5 строкам.

Для каждого hotspot ответьте:

Что это за место? (строки, контекст в диффе)
Почему оно может быть нетипичным? (kind)
Насколько срочно? (score — приоритет просмотра)

Если в колонках Effects / Taint / Control что-то есть — начинайте с них. Это обычно более “прикладной” риск, чем чистая форма кода.

Шаг 4. 30 секунд: выбрать действие

После просмотра нескольких hotspots вы должны выбрать один из путей:

✅ Accept (и при необходимости пояснить контекст)
🔧 Simplify (упростить участок/снизить “архитектурную массу”)
📦 Isolate (вынести новую подсистему/алгоритм в отдельный модуль/слой)
🧪 Add tests / invariants (если изменение меняет режимы/математику/контракты)
🔎 Open Full report (если сигнал сильный, но контекст непонятен / анализ partial)

4) Как интерпретировать ключевые поля (по делу)

4.1. `risk_level` и `struct_risk`

struct_risk — число 0–100: “насколько структура выбивается”.
risk_level — дискретный уровень для быстрого решения.

Как читать:

low → обычно достаточно убедиться, что hotspots не содержат неприятных effects/taint.
medium → почти всегда смотрим top-3 hotspots.
high → смотрим главный файл + top hotspots и решаем: simplify/isolate/обосновать.

4.2. `ci_status`

Это сигнал для CI/дашборда:

ok → инструмент не видит проблемных пороговых ситуаций.
warn → “обязательно посмотри глазами”.
fail → в строгом режиме CI это может блокировать (зависит от политики проекта).

4.3. `analysis: full|partial`

full → CodeGuard проанализировал весь поддерживаемый код в PR (на текущем этапе — Python).
partial → PR содержит изменения в файлах, которые CodeGuard не анализирует (не-код/неподдерживаемые расширения). В этом режиме отчёт “частичный” не потому, что Python разобран не до конца, а потому что часть PR лежит вне области анализа.

Правило ревью:

для Python-части ориентируйся на hotspots и per-file risk;
для непрофильных файлов просто ревьюи diff обычным способом (чеклистом проекта), без ожидания сигналов CodeGuard.

4.4. Hotspot: `kind` и `score`

kind — тип локальной аномалии (что именно “не похоже на норму”).
score — приоритет (какое место смотреть раньше), а не “вероятность бага”.

Типовые kind (интуитивно):

struct_pattern_break — “вставили нетипичный структурный рисунок” (часто это новые сущности/паттерны/стиль).
depth_spike — “слишком выросла вложенность/условность”.
control_outlier — “перегреты пути исполнения” (условия/ошибки/return-хвосты).
mixed — смесь факторов.

5) Решение “что делать дальше” (короткая матрица)

Сценарий A: `risk_level=low`, `ci_status=ok`, `analysis=full`

Обычно:

быстро пробежать top hotspots (1–3),
проверить, нет ли эффектных хвостов/taint,
принять PR.

Сценарий B: `risk_level=medium` или `ci_status=warn`

Обычно:

просмотреть top-3 / top-5 hotspots,
если изменения “стилистические/структурные” — предложить упрощение,
если изменения алгоритмические — потребовать объяснение + тест.

Сценарий C: `risk_level=high`

Минимум:

открыть главный файл из Per-file structural risk,
пройти top hotspots,
выбрать: Simplify или Isolate (чаще всего),
либо Accept + explain (если изменение осознанно и покрыто).

Сценарий D: `analysis=partial`

Обычно означает, что PR содержит файлы вне области анализа (например, YAML/CSV/Markdown).

Что делать:

Python-часть ревьюим по CodeGuard (per-file risk → top hotspots).
Непрофильные файлы (конфиги/данные/доки) ревьюим вручную по стандартам проекта.

6) Что писать в PR-обсуждении (короткие шаблоны)

6.1. Accept + explain (изменение осознанное)

“CodeGuard подсветил нетипичное усложнение в <участок>. Это сделано для <цель>. Добавлены/обновлены тесты <...> и комментарий к контракту.”

6.2. Simplify (снижаем когнитивную нагрузку)

“В этом месте появляется структурный разрыв относительно стиля репозитория. Предлагаю переписать как <простая функция/без lambda/без генератора>, чтобы сохранить предсказуемость кода.”

6.3. Isolate (новая подсистема/паттерн/алгоритм)

“Похоже на внедрение новой мини-архитектуры/алгоритма. Давайте вынесем в отдельный модуль/класс с явным интерфейсом и короткой документацией, чтобы изменение было локализовано.”

6.4. Add tests / invariants (меняется поведение)

“Изменение меняет режим/математику/контракт. Нужны тесты на <инвариант/крайние случаи/стабильность> или явный флаг конфигурации.”

7) Мини-пример (как “прочитать” High risk за 60 секунд)

Если вы видите:

Status: High risk
struct_risk: 69.49
control_risk_level: low
hotspots: много struct_pattern_break

Интерпретация:

сигнал не про “ветвления/ошибки”, а про внедрение нетипичных структурных паттернов;
начните с top-3 hotspots и ответьте: “это новая архитектурная идея (тогда isolate/обосновать) или случайное усложнение (тогда simplify)?”

8) Когда Quickstart недостаточно

Переходите к Full report, если:

PR большой, и вам нужно понять картину по файлам целиком,
есть Effects/Taint/Control и нужно оценить безопасность/границы/контракты,
analysis=partial,
изменения выглядят как новая подсистема или новый режим работы.

9) Ссылки на следующие документы

REPORT_FIELDS_REFERENCE — справочник всех полей отчёта (подробно).
REVIEW_PLAYBOOKS — плейбуки (high struct, high control, effects/taint, partial).
CASE_STUDIES — разборы реальных PR (как принимать решения на примерах).

Revieko Вики