CLI ревью собирает находки для сравнения коммитов, подготовленных к коммиту изменений или выбранных файлов. В отчёте рецензент получает позиции в исходниках, категории и серьёзность находок, а также состояние графа. Сопоставьте эти данные с изменением и результатами тестов, затем примите решение по ревью.
Перед началом
Подготовьте окружение Python и локальную конфигурацию по руководству CLI. Выполняйте команды ниже в PowerShell из корня репозитория CodeGraph. Нужны существующий CPG репозитория и доступный сервис GoCPG gRPC.
Замените обозначения в кавычках на путь к CPG, ссылку Git, пути исходников относительно репозитория и выбранные пути отчётов. Сначала создайте каталог для результатов. Используйте новое имя файла, чтобы после ошибки не принять старый отчёт за результат текущего запуска.
Выберите одну область ревью
Сравните базовую ревизию с текущим коммитом HEAD. Этот режим не включает незакоммиченные изменения рабочего дерева:
python -m src.cli review --db "<cpg-path>" --base-ref "<git-ref>" --format markdown
Проверьте изменения, подготовленные к коммиту:
python -m src.cli review --db "<cpg-path>" --staged --format json --output-file "<report.json>"
Проверьте выбранные файлы:
python -m src.cli review --db "<cpg-path>" --files "<file-one>" "<file-two>" --format sarif --output-file "<report.sarif>"
Доступны форматы --format {markdown,json,sarif}. Проверьте флаги установленной версии через
python -m src.cli review --help.
Выберите один способ ограничения области. Если передать несколько, для находок качества --files имеет приоритет над --staged, а --staged — над --base-ref. Анализ безопасности выполняется только при наличии --base-ref и отсутствии --no-security. Ревью только подготовленных изменений или файлов не запускает проверку безопасности, даже без --no-security.
Для машинной обработки JSON или SARIF используйте --output-file: стандартный вывод также содержит сообщения о ходе работы. --sarif-file записывает дополнительный файл SARIF только тогда, когда основной формат отличается от sarif.
Прочитайте результат
- Подтвердите базовую и конечную ревизии и фактически изменённые файлы.
- Проверьте место в исходниках, категорию, серьёзность и обоснование каждой находки.
- Отделите предположение от подтверждённого дефекта; воспроизведите находки высокого риска.
- Зафиксируйте ложные срабатывания и пробелы в проверке.
- До решения выполните тесты и проверки правил репозитория.
--no-security выбирает ревью качества кода. Запишите выбранную область, находки и результаты тестов в материалы ревью; рецензент использует их для решения по изменению.
Код завершения 1 может означать ошибку анализа или записи, а также критичные находки или находки высокой серьёзности в готовом отчёте. Код 0 означает, что таких находок не зарегистрировано. При этом могут оставаться находки средней или низкой серьёзности и неполный анализ. В JSON проверьте metadata.status, metadata.degradation_reasons, metadata.changed_file_paths, metadata.freshness и findings. Убедитесь, что новый файл отчёта создан и разбирается как JSON.
После ошибки запроса или анализа безопасности список находок может оказаться пустым. Неверная базовая ревизия тоже может дать пустой список изменённых файлов. Прочитайте предупреждения и отдельно проверьте сравнение Git: пустой список не доказывает отсутствие дефектов.
Обновлением графа управляет review_pipeline.auto_reparse в локальной конфигурации. При значении по умолчанию prompt ревью откладывает обновление. Значение auto запускает обновление через GoCPG, если граф доступен и отставание превышает review_pipeline.stale_threshold_commits (по умолчанию 0). В JSON проверьте metadata.refresh.required, metadata.refresh.attempted и metadata.refresh.status. После успешного обновления ревью повторно запрашивает свежесть графа и записывает её в metadata.freshness.
metadata.freshness.fresh показывает, затрагивают ли изменения после построения графа файлы, включённые в CPG. commits_behind показывает отставание ревизии графа от HEAD в коммитах. Поэтому граф может иметь fresh=true при ненулевом отставании, если включённые в него файлы не изменились. Сопоставьте область графа с файлами текущего ревью.
Прочитайте JSON в PowerShell
После команды с --format json --output-file "<report.json>" подставьте тот же путь в пример:
$report = Get-Content "<report.json>" -Raw | ConvertFrom-Json
$report | Select-Object project_name, base_ref, total_findings | Format-List
$report.metadata | Select-Object status, changed_file_paths, degradation_reasons, freshness | Format-List
$report.findings | Select-Object file, line, type, severity, message | Format-List
Первый блок вывода показывает проект, базовую ревизию и число находок. Следующий показывает состояние анализа, выбранные файлы, причины неполноты и свежесть графа. Затем выводится список находок с путём, строкой, категорией, серьёзностью и сообщением. Для ревью выбранных файлов base_ref пустой; сравните changed_file_paths с аргументами --files. При пустом findings список находок тоже пуст — область и состояние анализа остаются в metadata.
Восстановление
- Пустое сравнение: проверьте базовую ревизию, состояние подготовленных изменений и выбранные файлы.
- Устаревший граф: обновите проект до принятия находок, полученных по графу.
No CPG database found: передайте правильный путь через--db; CLI не определяет его автоматически.- Неподдерживаемый формат: проверьте
--helpустановленной версии. - Тайм-аут или неполный результат: сохраните предупреждения. Повторите проверку после устранения причины или сужения области.
Справочные материалы
Настройте автоматическую проверку изменений по руководству по хукам.