Сценарий 09: Обзор кода

Автоматический обзор кода для запросов на слияние, патчей и локальных изменений с использованием CPG-анализа, handler-based быстрого пути и LLM fallback.

Содержание¶

• Быстрый старт
• Как это работает
• Двухфазная архитектура
• Определение намерений
• Фаза handler’ов
• 4 handler’а
• ReviewReportFormatter
• Фаза LLM
• 3 агента
• CallGraphAnalyzer и графовые инсайты
• ReviewPipeline (автономный)
• Архитектура конвейера
• Scope-aware фильтрация
• SARIF-вывод
• Модели данных
• Использование CLI
• Оценка риска изменений
• Обнаружение влияния на интерфейсы
• Примеры запросов
• Связанное

Быстрый старт¶

# Выберите сценарий обзора кода
/select 09

Или через CLI:

# Проверка изменений относительно базового рефа
python -m src.cli review --base-ref HEAD~3

# Проверка проиндексированных изменений
python -m src.cli review --staged

# Проверка с выводом в SARIF
python -m src.cli review --base-ref main --format sarif --sarif-file results.sarif

Как это работает¶

Двухфазная архитектура¶

S09 использует стандартную двухфазную архитектуру: фаза 1 на основе handler’ов (без LLM) и фаза 2 с LLM fallback:

Запрос -> CodeReviewIntentDetector.detect()
  |
  Фаза 1: integrate_handlers(state)
    -> HandlerRegistry("code_review") -> подбор handler'а по intent
    -> handler.handle() -> ReviewReportFormatter -> ответ
    |
    handled=True  -> возврат форматированного результата (без LLM)
    handled=False -> Фаза 2
  |
  Фаза 2: code_review_workflow() [LLM fallback]
    -> 3 агента (PRAnalyzer, ContextAggregator, ReviewReporter)
    -> CallGraphAnalyzer (зона поражения)
    -> PromptRegistry -> LLMInterface.generate() -> ответ

code_review_workflow() в src/workflow/scenarios/code_review.py сначала вызывает integrate_handlers(state). Если handler сработал (handled=True), результат возвращается без LLM. Иначе выполняется полный LLM-workflow с 3 агентами и графовым анализом.

Дополнительно CodeGraph предоставляет автономный ReviewPipeline (src/review/pipeline.py) для CLI-обзора через python -m src.cli review, независимо от LangGraph-оркестратора.

Определение намерений¶

CodeReviewIntentDetector(IntentDetector) в code_review_handlers/intent_detector.py определяет 4 intent’а, отсортированных по приоритету:

Fallback: general_review (confidence=0.5), когда ни один паттерн не совпал.

Сопоставление ключевых слов через keyword_match_morphological() для поддержки русской морфологии.

Фаза handler’ов¶

4 handler’а¶

code_review_handlers/workflow.py регистрирует 4 handler’а в HandlerRegistry("code_review"):

Все handler’ы наследуют CodeReviewHandler(BaseHandler).

CallerAnalysisHandler обнаруживает запросы по caller/callee через двуязычные ключевые слова (EN: caller, callee, who calls, called by; RU: вызывающие, кто вызывает). Выполняет 2-hop транзитивный поиск для оценки полной зоны поражения.

PRImpactHandler извлекает изменённые файлы через git diff --name-only {base_ref} HEAD. Поддерживаемые расширения: .py, .go, .ts, .js, .c, .h, .java, .kt, .cs, .php.

ReviewReportFormatter¶

ReviewReportFormatter в code_review_handlers/formatters/ форматирует результаты handler’ов: - Бейджи риска изменений (critical/high/medium/low) - Индикаторы влияния на интерфейсы - Визуализация цепочки вызывающих - Поддержка локализации (EN/RU)

Фаза LLM¶

3 агента¶

Когда ни один handler не сработал, code_review_workflow() выполняет полный LLM-конвейер с 3 агентами из src/code_review/review_agents.py:

Конвейер: 1. PRAnalyzer анализирует изменённые файлы и обнаруживает зависимости 2. ContextAggregator собирает CPG-контекст для изменённых методов 3. ReviewReporter генерирует финальный отчёт обзора 4. Список доказательств строится из находок и оценок риска 5. PromptRegistry.get_agent_prompt("code_review", ...) формирует промпт 6. LLMInterface().generate() генерирует финальный ответ

CallGraphAnalyzer и графовые инсайты¶

После завершения 3 агентов CallGraphAnalyzer(cpg) из src/analysis выполняет графовый анализ зоны поражения:

• Влияние изменений: Для каждого изменённого метода вызывает find_all_callers() и analyze_impact() для определения затронутых методов
• Затронутые методы: Строит транзитивное замыкание вызывающих до 2 hop — методы, которые могут сломаться при некорректном изменении
• Оценка риска: Комбинирует количество вызывающих, вызываемых и принадлежность к интерфейсному слою в оценку риска

Графовые инсайты сохраняются в state["metadata"]["graph_insights"]:

ReviewPipeline (автономный)¶

Архитектура конвейера¶

ReviewPipeline в src/review/pipeline.py — автономный конвейер (отдельно от LangGraph-сценария), оркестрирующий полный цикл CLI-обзора:

detect_project -> check_cpg_status -> load_scope -> get_changed_files
     -> quality_analysis -> security_analysis -> aggregate -> format_output

Ключевые компоненты: - ReviewAggregator (src/review/aggregator.py): объединяет находки качества и безопасности, применяет scope-aware фильтрацию - ReviewReport (src/review/models.py): генерирует вывод в форматах markdown, JSON и SARIF 2.1.0 - SecurityPRReview: опциональный анализ безопасности для изменённых файлов (отключается через --no-security)

Scope-aware фильтрация¶

Когда CPG построен с исключёнными директориями (частичный scope), ReviewAggregator применяет scope-aware фильтрацию:

• Понижение мёртвого кода: находки мёртвого кода понижены до info, помечены scope_limited (вызывающие могут существовать в исключённых модулях)
• Понижение зоны поражения: находки зоны поражения понижены до info, помечены scope_limited
• Подавление тестов: тестовые находки полностью подавлены при include_tests=false
• Сложность/Безопасность: не затронуты (метрики per-method и реальное обнаружение уязвимостей)

При активной фильтрации в отчёт добавляется дисклеймер (ParseScope.scope_disclaimer).

SARIF-вывод¶

ReviewPipeline поддерживает вывод в SARIF 2.1.0 для интеграции со вкладками безопасности GitHub/GitLab и плагинами IDE:

python -m src.cli review --base-ref main --format sarif --sarif-file results.sarif

Коды возврата: 0 = чисто или только medium/low, 1 = обнаружены critical или high.

Модели данных¶

Ключевые модели из src/review/models.py:

Использование CLI¶

Полная справка по python -m src.cli review:

# Проверка изменений относительно базового рефа
python -m src.cli review --base-ref HEAD~3

# Проверка проиндексированных изменений
python -m src.cli review --staged

# Проверка конкретных файлов
python -m src.cli review --files src/api/main.py src/auth.py

# Без анализа безопасности
python -m src.cli review --no-security

# Вывод в JSON
python -m src.cli review --base-ref main --format json

# Вывод в SARIF
python -m src.cli review --base-ref main --format sarif --sarif-file results.sarif

# Запись вывода в файл
python -m src.cli review --base-ref HEAD~5 --output-file review.md

Оценка риска изменений¶

Каждый изменённый метод получает оценку риска (0.0–1.0) на основе 4 факторов:

Уровни: critical (≥0.8), high (≥0.6), medium (≥0.4), low (<0.4).

Обнаружение влияния на интерфейсы¶

При изменении файлов в интерфейсных слоях обзор кода определяет, какие интерфейсы затронуты:

Интерфейсные слои:
  CLI        -> src/cli/
  REST API   -> src/api/routers/
  MCP        -> src/mcp/tools/, src/mcp/
  ACP        -> src/acp/server/, src/acp/

Примеры запросов¶

Какова зона поражения этого изменения?
Проверь мои последние 3 коммита
Оцени риск изменений в src/api/
Кто вызывает этот метод и что сломается?
Покажи влияние изменения сигнатуры функции
Расставь приоритеты находок обзора
Какие зависимости затронуты этим PR?

Связанное¶

• Аудит безопасности — Глубокий анализ безопасности (ReviewPipeline включает проход безопасности)
• Покрытие тестами — Анализ покрытия кода тестами
• Рефакторинг — Качество кода и мёртвый код
• Композитные рабочие процессы — Оркестрация сценариев
• Интеграция Claude Code и Git — Хуки проверки кода