Используйте этот сценарий, когда нужно изменить структуру кода и сохранить поведение продукта. CodeGraph показывает область влияния, помогает сравнить данные до и после правки и оформить решение по результатам проверки.
Результат
В конце у вас должны быть:
- выбранный символ и зафиксированная базовая ревизия;
- отчёт о влиянии и аудит без записи до изменения;
- небольшая правка, выполненная в обычном редакторе;
- результаты тестов и линтера проекта;
- обновлённый CPG и данные проверки после изменения;
- явное решение: оставить правку, доработать её или откатить.
Код завершения проверяйте вместе с отчётом: он не подтверждает неизменность поведения. Для этого нужны тесты, линтер и ревью.
Предварительные условия
Подготовьте локальное окружение Python по руководству CLI. Выполняйте команды из корня репозитория CodeGraph в PowerShell. Для анализа влияния нужен доступный GoCPG gRPC: одного файла CPG недостаточно. Пример задаёт условные значения; замените их точными данными выбранного проекта и существующим именем метода. Подготовьте CPG для исходной ревизии по разделу «Подготовка проекта», чтобы сравнивать влияние до и после правки.
- Репозиторий уже импортирован в CodeGraph.
- В рабочем дереве находятся только те изменения, которые вы собираетесь проверять.
- Известны команды тестов и линтера проекта.
- Известен путь к DuckDB, который показывает информация о проекте.
В примерах используются переменные PowerShell: так безопаснее работать с путями, содержащими пробелы.
$ProjectName = "my-project"
$RepoPath = "D:\src\my-project"
$CpgDb = "D:\codegraph-data\my-project.duckdb"
$BaseRef = "origin/main"
$Symbol = "qualified_symbol_name"
python -m src.cli projects info $ProjectName
Убедитесь, что показанные пути к исходникам и DuckDB относятся именно к изменяемому репозиторию. При несовпадении остановитесь.
1. Зафиксируйте исходное состояние
Сохраните Git-ревизию и состав текущих изменений штатными средствами контроля версий. Затем выполните детерминированный аудит без записи:
python -m src.cli audit --db $CpgDb --source-path $RepoPath --profile ci_fast --format json --skip-llm-conclusion --skip-persistence
Флаг --skip-persistence запрещает диагностическому запуску обновлять проекции аудита. Если рефакторинг проходит управляемый процесс, сохраните вывод в системе доказательств задачи. Без параметра вывода команда не создаёт файл отчёта.
2. Ограничьте область влияния
До правки проанализируйте выбранный символ:
python -m src.cli impact $Symbol --db $CpgDb --max-depth 5 --format json
Читайте поля отчёта по направлению связи:
| Поле | Что показывает | Как использовать |
|---|---|---|
direct_callers |
Функции, которые непосредственно вызывают выбранный метод | Проверьте совместимость их вызовов с изменением |
transitive_callers |
Вызывающие функции на следующих уровнях графа, без прямых вызывающих | Выберите сценарии и точки входа для регрессионной проверки |
affected_methods |
Функции, которые выбранный метод вызывает прямо или через другие функции | Изучите зависимости изменяемого кода |
impact_score |
Нормированная оценка связности от 0 до 1 | Сравните исходный и обновлённый графы с одинаковой глубиной обхода и настройками импорта |
impact_score учитывает уникальные вызывающие и вызываемые функции. Их число делится на 10% общего числа методов проекта; результат ограничен единицей. Для метода с более чем 100 прямыми вызывающими расчёт использует прямые связи вместо полного транзитивного обхода. Сохраните вместе с оценкой списки функций и параметр --max-depth, чтобы сравнение было понятным.
Обход ограничен глубиной и числом результатов. По умолчанию запрос в каждом направлении возвращает до 1000 имён для прямых связей и до 3000 для транзитивных, с сортировкой по имени. Оценка использует связи, вошедшие в эти результаты. При сравнении отчётов сохраняйте одинаковые лимиты обхода: увеличение --max-depth меняет глубину, а не допустимое число результатов.
Если список пуст, проверьте точное имя символа, базу проекта, импорт языка и актуальность CPG. После обновления контекста повторите команду и сопоставьте найденные связи с исходниками.
Разделите работу, если область затрагивает чужую зону ответственности, публичный API, схему хранения, авторизацию или критическую точку входа за пределами одобренной задачи.
3. Выполните одну локальную правку
Измените код в обычном редакторе. Не смешивайте поведенчески нейтральный рефакторинг с новой функцией. Переименование, обновление зависимости, изменение API и алгоритма не должны попадать в один срез.
Сразу запустите профильные тесты и линтер проекта. Если проверка не прошла, верните заведомо рабочую версию штатными средствами контроля версий либо исправьте минимальный проблемный срез.
4. Обновите граф
Отчёт о влиянии использует импортированный CPG. После изменения исходников обновите его. Команда ниже записывает базу: согласуйте её с владельцами других процессов и остановите конфликтующие операции до запуска:
python -m src.cli cpg --path $RepoPath --output $CpgDb
Указывайте только базу, показанную для этого проекта. Если в вашей установке импорт выполняется другим одобренным процессом, используйте его, а перед повторным анализом ещё раз проверьте информацию о проекте.
5. Проверьте изменённый срез
Запустите единую проверку относительно зафиксированной базы:
python -m src.cli review --db $CpgDb --base-ref $BaseRef --format markdown
Затем повторите анализ влияния:
python -m src.cli impact $Symbol --db $CpgDb --max-depth 5 --format json
Второй отчёт должен объяснять ожидаемое структурное изменение и не добавлять неожиданных вызывающих символов, проблем безопасности или посторонних файлов. Если правка влияет на проектные метрики качества, повторите аудит без записи.
Таблица решений
| Доказательства | Решение |
|---|---|
| Профильные тесты и линтер прошли, влияние осталось в одобренной области, критичные замечания проверки устранены | Оставить срез и приложить доказательства |
| Символ не найден или CPG устарел | Обновить контекст проекта и повторить анализ |
| Появились новые вызывающие символы, публичные поверхности или чувствительные пути | Остановиться и запросить расширенную проверку |
| Изменилось поведение или потребовалась правка критериев приёмки | Переклассифицировать работу в продуктовое изменение |
| Не прошли тесты, линтер или проверка | Исправить минимальный срез либо откатить его через систему контроля версий |
Что сохранить как доказательства
Зафиксируйте имя проекта, ревизию исходников, base ref, идентичность CPG, точные команды и коды завершения, значимые поля отчётов, результаты тестов и итоговое решение человека.
Диагностика
impact analysis requires explicit --db: передайте путь DuckDB из projects info.- Для известного символа нет вызывающих: проверьте квалифицированное имя и обновите CPG.
- В review попали посторонние файлы: проверьте base ref и область рабочей задачи.
- Аудит изменяет операционное состояние: повторите запуск с
--skip-persistence. - Результаты между запусками различаются: до сравнения сверьте ревизию, путь к базе, актуальность импорта и конфигурацию.
См. также импорт проекта, проверку кода и сценарий 09: проверка кода.