Revieko Вики

Revieko — Справочник по отчету (Summary / Full report / JSON)

Этот документ — справочник по полям отчётов Revieko: что означает каждое поле, где оно встречается (PR-коммент / Full report / JSON), как его интерпретировать и какие типовые причины у “странных” значений.

Сначала прочитай: docs/PR_REVIEW_QUICKSTART.md (маршрут чтения за 3–5 минут).

Здесь — именно словарь полей.

0) Контекст: какие “отчёты” бывают

В GitHub PR обычно есть два уровня выдачи:

1. PR-коммент (Summary)

   Короткий: статусы, top-N hotspots, per-file structural risk, ссылки на Full report.

2. Full report (Markdown / JSON)

   Полный артефакт: таблицы, дополнительные секции, служебные поля, лимиты анализа.

1) Нотации и договорённости

1.1. Риски и шкалы

• _risk ∈ [0,100] — нормализованные оценки, удобные для порогов и “светофора”.
• _risk_level ∈ {low, medium, high} — дискретизация для быстрого решения.
• Плотности вида _density ∈ [0,1] — доля “сигнальных” токенов/эффектов в выбранной области.

1.2. Локации и строки

• В Markdown-отчётах локация hotspots обычно вида:path/to/file.py:LINE_START-LINE_END
• В JSON обычно:
  • file_path
  • line_start / line_end (1-based)
• В PR-режиме линии трактуются как “строки в новой версии файла” (после применения diff).

1.3. Поля могут быть пустыми

Колонки Effects / Taint / Control в hotspots могут быть пустыми, если:

• соответствующий канал отключён в конфиге/версии,
• эвристики ничего не отметили в этом конкретном окне,
• анализ был partial и кусок не попал в разбор.

2) Summary (PR-коммент): поля и смысл

Типичный заголовок:

• Status: High risk
• struct_risk: 69.49
• hotspots: 10
• ci_status: warn
• control_risk_level: low
• analysis: full|partial

Ниже — расшифровка.

2.1. Status (человеческий статус)

Где: Summary / Full report (Markdown)

Тип: string (обычно Low/Medium/High risk)

Смысл: человекочитаемая “выжимка” по риску/CI-политике.

Практически Status обычно согласован с risk_level + ci_status, но это именно “лейбл”.

2.2. risk_level

Где: Full report (Markdown), часто в JSON (зависит от режима CLI/интеграции)

Тип: enum: low | medium | high

Смысл: дискретный уровень структурного риска (для быстрого решения “копать или нет”).

Типовая интерпретация:

• low: структурно похоже на типичный код репозитория.
• medium: стоит глянуть hotspots.
• high: заметная структурная аномалия — почти всегда ручной просмотр.

2.3. struct_risk

Где: Summary / Full report (Markdown)

Тип: float 0..100

Смысл: глобальный структурный риск для объекта анализа (PR/diff).

Важно:

• В PR-репорте это “общий” риск по diff.
• Детализация по файлам — в Per-file structural risk.

В JSON-репортах аналог обычно называется global_struct_risk.

2.4. hotspots (count)

Где: Summary (короткий коммент)

Тип: int

Смысл: сколько hotspots показано в этом комментарии.

Важно:

• Это не “покрытие” и не “сколько аномалий всего”. Это количество выведенных hotspots (top-N), ограниченное политикой вывода.

2.5. ci_status

Где: Summary / Full report (Markdown), иногда JSON

Тип: enum: ok | warn | fail

Смысл: сигнал для CI/интеграции (как отображать/гейтить).

Типовая политика:

• ok: пороги не превышены.
• warn: есть что посмотреть (soft gate).
• fail: строгий режим (hard gate) — зависит от настройки.

2.6. control_risk_level

Где: Summary / Full report (Markdown), JSON (если включён control-канал)

Тип: enum: low | medium | high

Смысл: дискретный уровень “контрольной сложности” (условия / error-path / return-tail).

Интуиция:

• low: ветвления/ошибки/return-хвосты выглядят нормально.
• high: условия и/или error-ветки и/или хвосты перегреты → читать трудно, легко ошибиться.

2.7. analysis: full|partial

Где: Summary / Full report (Markdown)

Тип: enum: full | partial

Смысл: покрытие отчётом поддерживаемых типов файлов.

• full → весь поддерживаемый код в PR проанализирован (на текущем этапе — Python).
• partial → в PR есть изменения в файлах, которые CodeGuard не анализирует (например, YAML/CSV/Markdown и т.п.). Python-файлы при этом анализируются полностью; “partial” относится к PR как целому.

Практика:

• partial не надо трактовать как “Python разобран наполовину”.
• partial означает: “часть PR лежит вне области анализа и должна ревьюиться вручную”.

3) Per-file structural risk (таблица)

Где: Summary / Full report (Markdown)

Смысл: вклад каждого файла в общий structural-риск.

Колонки:

• File — путь
• Risk — структурный риск файла (0..100)

Как читать:

• “Один файл тащит всё” → начните ревью с него.
• Риск размазан → вероятно, PR меняет “слой” или стиль сразу в нескольких местах.

В JSON аналог: file_struct_risk: { "path": number, ... }

4) Hotspots: поля строки и как их понимать

Hotspot = локальный участок строк, который выглядит нетипично.

4.1. Поля hotspots в Markdown (таблица)

Типичная строка:

Расшифровка колонок:

Location

• путь и диапазон строк: file.py:START-END

Kind

Тип: enum

Обычно:

• struct_pattern_break — “слом типичного структурного рисунка” в окне (нетипичные маркеры IF/LOOP/RETURN/..., новые “паттерны”, смена стиля).
• depth_spike — локально аномальная вложенность.
• control_outlier — окно перегрето по control-режимам (условия/error/return).
• mixed — нет одного доминанта, но окно всё равно выбивается.

Score

Тип: float (ранжирование)

Смысл: приоритет просмотра (чем больше — тем выше в списке).

Важно:

• score — не вероятность бага и не абсолютная “оценка качества”.
• Он нужен, чтобы сортировать hotspots внутри одного отчёта.

Effects

Тип: string / метка / краткая подсказка

Смысл: семантическая подсказка про side-effects (если semantic-канал включён и что-то найдено).

Обычно эффекты (уровень токенов/фрагментов):

• LOG, DB, FILE_IO, NET_IO, EXEC (и т.п.)

Taint

Тип: string / метка / краткая подсказка

Смысл: источники данных рядом (если включено):

• USER_INPUT — входные данные
• SECRET — потенциальные секреты
• CONST — константы

Control

Тип: string / метка / краткая подсказка

Смысл: контрольный контекст окна:

• BRANCH_COND, ERROR_PATH, RETURN_PATH, INIT_PATH, CLEANUP_PATH, NORMAL

4.2. Поля hotspots в JSON

Обычно:

• file_path: string
• line_start, line_end: int (1-based)
• segment_id: string (например, hunk_0)
• segment_kind: enum (diff_hunk, full_file, …)
• kind: enum
• score: float
• (опционально) effect_hint, taint_hint, control_hint

5) Control summary: таблица и поля

Где: Full report (Markdown) и JSON (если включён control-канал)

5.1. Control summary (Markdown)

В PR-репорте может быть таблица:

Смысл:

• overall — общий control-риск для файла (обычно агрегат/максимум).
• branch_cond — риск ветвлений/условий.
• error_path — риск error-веток.
• return_path — риск “return/raise-хвостов”.

5.2. Control summary (JSON): типовые поля control_summary.per_file[path]

Полевая модель (часто встречается как “пер-файл агрегаты”):

Доли control-режимов

• control_share_branch_cond
• control_share_error_path
• control_share_return_path
• control_share_init_path
• control_share_cleanup_path

Complexity-метрики по режимам

• control_*_complexity_mean
• control_*_complexity_max

Cross-метрики “control × effects”

• branch_cond_effect_density
• error_path_effect_density
• return_path_effect_density

Control-риски (0..100)

• branch_cond_risk
• error_path_risk
• return_path_risk
• overall_control_risk

5.3. Как читать “сильный сигнал” в control-слое

Примеры:

• branch_cond_risk высокий + branch_cond_effect_density > 0 → в условиях происходит IO/NET/DB/LOG (часто подозрительно и плохо читается).
• error_path_risk высокий + error_path_effect_density высокий → обработчики ошибок делают много эффектов.
• return_path_risk высокий + return_path_effect_density высокий → “перед возвратом” происходит эффектная логика (меняет поведение на выходе).

6) Semantic layer: effect_summary, file_semantic_risk, taint

Если semantic-канал включён, в JSON (и иногда в Markdown) появляются поля, связанные с эффектами и “опасными” потоками.

6.1. effect_summary

Где: JSON, иногда Full report (Markdown)

Смысл: агрегаты по эффектам/taint.

effect_summary.per_file[path] (по файлам)

Типовые метрики:

• effect_density_tail ∈ [0,1]

  Доля “эффектных” токенов (NET/DB/FILE/EXEC/LOG) в хвосте файла/сегмента.

  Интуиция: ближе к 1 → хвост “плотно эффектный”.

• dangerous_flow_score ∈ [0,1]

  Грубый сигнал, что USER_INPUT проходит рядом с эффектами (NET_IO/DB/EXEC/LOG).

  > 0 → найден хотя бы один потенциально опасный соседний flow.

• secret_leak_score ∈ [0,1]

  Грубый сигнал, что SECRET встречается рядом с LOG / NET_IO.

  > 0 → возможная утечка секретов.

effect_summary.global

Максимумы/агрегаты по всем файлам отчёта — быстрый ответ “есть ли вообще effect-активность”.

6.2. file_semantic_risk и file_semantic_risk_level

Где: JSON

Тип:

• file_semantic_risk[path] ∈ [0,100]
• file_semantic_risk_level[path] ∈ {low, medium, high}

Смысл: repo-aware оценка “семантического” риска файла (эффектный хвост + suspicious flow + поправка по истории).

Частое правило приоритизации:

• высокий struct_risk и высокий file_semantic_risk по одному и тому же файлу → файл почти всегда стоит ревьюить вручную “в первую очередь”.

6.3. taint (как интерпретировать)

Taint-метки обычно не “про безопасность”, а про источники данных рядом:

• USER_INPUT → важно смотреть, куда дальше идёт значение (особенно рядом с NET/DB/EXEC/LOG)
• SECRET → важно смотреть, нет ли рядом логирования/сети

7) Invariants / rule violations (если включены правила)

Если подключены командные правила (семантические инварианты), отчёт может содержать:

• invariant_violations: список нарушений
  • правило/идентификатор
  • локация
  • краткое объяснение

Это самый “жёсткий” и понятный слой:

правило нарушено → вот место → исправляем или осознанно исключаем.

8) Coverage & scope: что означает “partial analysis”

8.1. Почему отчёт может быть partial

analysis=partial означает: в PR есть файлы вне профиля анализа (на текущем этапе CodeGuard заточен под Python-код). Примеры: YAML, CSV, Markdown, ассеты, данные, конфиги и т.п.

8.2. Как правильно читать partial

• Для Python-части: отчёт полноценный (per-file risk, hotspots и т.д.).
• Для непрофильных файлов: CodeGuard молчит, потому что не анализирует их.

8.3. Что делать ревьюеру

• Ревьюить Python по отчёту (сначала top hotspots).
• Ревьюить непрофильные файлы вручную: корректность формата, обратная совместимость, миграции, соответствие стандартам проекта, безопасность секретов в конфиге и т.д.

8.4. Что делать продуктово (если нужно)

Если проекту важно, чтобы YAML/Markdown/CSV тоже проходили “автоматический радар”, это отдельный roadmap: подключать анализаторы для новых типов/языков и расширять scope.

9) Метаданные и служебные поля

В зависимости от интеграции/версии могут присутствовать:

• Generated / timestamp (в Markdown шапке)
• repo_root, pr_number (в JSON)
• ссылки Markdown / JSON (в Summary)
• expires_at_unix_s (в Summary, если ссылки на Full report имеют срок действия) Unix time (секунды), когда токенизированная ссылка/артефакт может истечь.

10) Маппинг имён: Markdown ↔ JSON (часто путают)

• Markdown struct_risk (в PR Summary/Full report)

  ≈ JSON global_struct_risk

• Markdown “Per-file structural risk”

  ≈ JSON file_struct_risk

• Markdown “Hotspots” (таблица top-N)

  ≈ JSON hotspots (может быть шире/полнее в полном артефакте)

• Markdown analysis: full|partial

  ⇐ выводится из analysis_limits + fallback/ограничений

11) Быстрые ответы на “странные” значения

Почему control_summary везде 0.0?

• control-канал выключен,
• или в этом PR control-режимы не выбиваются,
• или анализ partial и нужные куски не попали.

Почему Effects/Taint пустые в hotspots?

• semantic-канал выключен,
• или эвристики не нашли сигналов в данном окне,
• или отчёт в “reviewer mode” показывает только структурные hotspots.

Почему hotspots “только 10”, но я уверен, что “аномалий больше”?

• это лимит вывода top-N в PR-комменте; открывайте Full report (Markdown/JSON).