Руководство по сценариям анализа

CodeGraph поддерживает 21 специализированный сценарий анализа, маршрутизируемый через конвейер предварительной подготовки.

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

Запросы проходят через конвейер LangGraph: классификация намерения → предварительная подготовка → маршрутизация → обработчик сценария → ответ. На этапе предварительной подготовки запрос дополняется данными CPG, после чего направляется в подходящий сценарий. При необходимости сценарий можно выбрать принудительно через context={"scenario_id": "scenario_N"}.

Содержание

Обзор сценариев

# Сценарий Намерение Пример использования
1 Онбординг в кодовую базу onboarding Навигация по кодовой базе для новых разработчиков
2 Аудит безопасности security Комплексный аудит с анализом потоков данных
3 Генерация документации documentation Автоматическая генерация технической документации
4 Разработка функционала feature_dev Поддержка разработки новых функций
5 Рефакторинг refactoring Рекомендации по рефакторингу с анализом влияния
6 Анализ производительности performance Выявление узких мест производительности
7 Покрытие тестами test_coverage Анализ тестового покрытия и рекомендации
8 Проверка соответствия compliance Проверка по OWASP Top 10, CWE и отраслевым требованиям
9 Обзор кода code_review Проверка изменений в PR/MR
10 Межрепозиторный анализ cross_repo Анализ межмодульных зависимостей
11 Анализ архитектуры architecture Выявление нарушений архитектурных ограничений
12 Оценка технического долга tech_debt Количественная оценка технического долга
13 Массовый рефакторинг mass_refactoring Автоматизация массового рефакторинга (миграции API)
14 Реагирование на инциденты ИБ security_incident Расследование инцидентов с рекомендациями
15 Поддержка отладки debugging Помощь в отладке на основе потоков данных
16 Точки входа и поверхность атаки entry_points Анализ поверхности атак и точек входа
17 Редактирование файлов file_editing Точечное редактирование кода на основе AST
18 Оптимизация кода code_optimization Композитный: S02, S05, S06, S11, S12 параллельно (60 с)
19 Проверка по стандартам standards_check Композитный: S08, S17, S18 последовательно (45 с)
20 Анализ зависимостей dependencies Анализ зависимостей и импортов
21 Синхронизация документации interface_docs_sync Покрытие документации по всем интерфейсам

1. Онбординг в кодовую базу

Навигация по кодовой базе для новых разработчиков: поиск определений функций, классов, структур.

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

Объясни архитектуру проекта
Найти метод 'heap_insert'
Где определена функция AbortTransaction?
Показать определение структуры RelFileNode
Найти все методы в файле 'xact.c'

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

python -m src.cli query "Где определена функция heap_insert?"

from src.workflow import MultiScenarioCopilot

copilot = MultiScenarioCopilot()
result = copilot.run("Объясни архитектуру проекта")
print(result['answer'])

2. Аудит безопасности

Комплексный аудит безопасности: обнаружение уязвимостей, анализ потоков данных, граф вызовов, CWE-маппинг.

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

Найди все SQL инъекции
Показать потенциальные переполнения буфера
Найти несанитизированный пользовательский ввод
Проследить путь от пользовательского ввода до выполнения запроса
Какие функции вызывают LWLockAcquire?

Обнаруживаемые шаблоны

  • SQL-инъекция (CWE-89)
  • Переполнение буфера (CWE-120)
  • Инъекция команд (CWE-78)
  • Форматная строка (CWE-134)
  • Переполнение целого числа (CWE-190)

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

python -m src.cli query "Найди уязвимости SQL-инъекций"

from src.workflow import MultiScenarioCopilot

copilot = MultiScenarioCopilot()
result = copilot.run("Найди уязвимости, связанные с SQL-инъекциями")
print(result['answer'])
# Детальные результаты в result['evidence'] и result['metadata']

3. Генерация документации

Автоматическая генерация технической документации из исходного кода.

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

Сгенерируй API документацию
Документируй подсистему транзакций
Создай описание менеджера буферов

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

python -m src.cli query "Документируй подсистему транзакций"

copilot = MultiScenarioCopilot()
result = copilot.run("Документируй подсистему транзакций")
print(result['answer'])

4. Разработка функционала

Поддержка разработки новых функций: рекомендации по размещению, примеры шаблонов, навигация по зависимостям.

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

Где добавить новую конечную точку API?
Где разместить новую функцию инвалидации кеша?
Найди похожие функции для управления буферами
Покажи примеры шаблонов для подсистемы `executor`

Возможности

  • Оптимальное размещение: Рекомендация файла и ближайшего метода для нового кода
  • Примеры шаблонов: Классификация существующих методов (Инициализация, Обработчик, Запрос, Валидация, Очистка)
  • Оценка уверенности: Насколько описание функции соответствует рекомендуемой подсистеме

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

copilot = MultiScenarioCopilot()
result = copilot.run("Где разместить новую функцию инвалидации кеша?")
print(result['answer'])

Подробные примеры: Сценарий разработки функций.

5. Рефакторинг

Рекомендации по рефакторингу с анализом влияния изменений: мёртвый код, дублирование, выделение методов.

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

Найди неиспользуемые функции
Найди дублирующиеся блоки кода
Запланировать рефакторинг менеджера буферов
Найди функции, которые можно разбить

Обнаруживаемые шаблоны

  • Функции без вызывающих (мёртвый код)
  • Недостижимые блоки кода
  • Дублирование фрагментов кода
  • Длинные функции для выделения методов

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

python -m src.cli query "Найди неиспользуемые функции"

copilot = MultiScenarioCopilot()
result = copilot.run("Найди неиспользуемые функции")
print(result['answer'])
# Данные о мёртвом коде в result['metadata']

6. Анализ производительности

Выявление узких мест: цикломатическая сложность, ресурсоёмкие циклы, многопоточность, шаблоны выделения памяти.

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

Найди N+1 запросы к БД
Найди функции с высокой цикломатической сложностью
Найди паттерны со сложностью O(n²)
Найди состояния гонки
Показать проблемы с порядком блокировок

Анализируемые метрики

  • Цикломатическая сложность
  • Глубина вложенности циклов
  • Длина функций, частота вызовов
  • Шаблоны выделения памяти
  • Потокобезопасность (блокировки, гонки данных)

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

copilot = MultiScenarioCopilot()
result = copilot.run("Найди функции со сложностью > 20")
print(result['answer'])
# Метрики сложности в result['metadata']

7. Покрытие тестами

Анализ тестового покрытия и рекомендации по тестам. Поддерживает импорт данных покрытия из внешних инструментов.

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

Какие функции не покрыты тестами?
Найти непротестированный код
Показать функции без тестов

Импорт данных покрытия

# Импорт JSON-отчёта pytest-cov
python -m src.cli coverage import --file coverage.json --format pytest-cov --db data/projects/postgres.duckdb

# Импорт lcov trace файла
python -m src.cli coverage import --file coverage.lcov --format lcov

# Импорт Cobertura XML (Java/C#)
python -m src.cli coverage import --file coverage.xml --format cobertura --source-root /project

После импорта запрос «Найти непротестированный код» автоматически переключается в гибридный режим, объединяя данные покрытия с эвристическим анализом вызовов тестов.

Рекомендации на основе CPG

  • Покрытие веток: подсчитывает IF/FOR/SWITCH и оценивает необходимые тест-кейсы
  • Граничные значения параметров: сопоставляет типы параметров с рекомендациями (zero, null, empty, max)
  • Пути ошибок: подсчитывает TRY блоки и множественные RETURN

8. Проверка соответствия

Проверка соответствия стандартам: OWASP Top 10, CWE и правилам, зависящим от выбранного домена. Обработчик подстраивается под активный доменный плагин, поэтому набор правил может отличаться для разных типов проектов.

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

Проверь на соответствие OWASP Top 10
Проверь требования к обработке данных
Проверь соответствие стандартам кода

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

python -m src.cli query "Проверь на соответствие OWASP Top 10"

copilot = MultiScenarioCopilot()
result = copilot.run("Проверь на соответствие OWASP Top 10")
print(result['answer'])

9. Обзор кода

Проверка изменений в PR/MR с автоматическим поиском рисков.

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

Проверь этот PR на проблемы
Найди потенциальные ошибки в этом изменении
Проверь наличие нарушений стиля кодирования
Проанализируй покрытие тестами внесённых изменений

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

# Рецензирование через CLI
python -m src.cli review --base-ref HEAD~5

# Демо-скрипт (интерактивный режим)
python examples/demo_patch_review.py --db data/projects/postgres.duckdb --interactive

copilot = MultiScenarioCopilot()
result = copilot.run("Проверь изменения в модуле executor")
print(result['answer'])

10. Межрепозиторный анализ

Анализ межмодульных зависимостей, дублирование между репозиториями.

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

Найди дублирующийся код между репо A и B
Покажи межмодульные зависимости

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

copilot = MultiScenarioCopilot()
result = copilot.run("Найди дублирующийся код между репо A и B")
print(result['answer'])

11. Анализ архитектуры

Выявление нарушений архитектурных ограничений, анализ подсистем, слоёв и зависимостей.

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

Найди циклические зависимости
Отобразить архитектуру подсистем
Показать границы слоёв
Найти нарушения архитектуры
Покажи диаграмму подсистем

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

copilot = MultiScenarioCopilot()
result = copilot.run("Отобразить архитектуру PostgreSQL")
print(result['answer'])
# Данные о подсистемах в result['metadata'] и result['subsystems']

12. Оценка технического долга

Количественная оценка технического долга.

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

Оцени технический долг модуля
Найти код с чрезмерной связанностью
Показать модули, требующие рефакторинга
Определить участки, сложные в сопровождении

Признаки долга

  • Высокая сложность
  • Глубокая вложенность
  • Длинные функции
  • Сильная связанность
  • Отсутствие обработки ошибок

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

copilot = MultiScenarioCopilot()
result = copilot.run("Найти участки с техническим долгом")
print(result['answer'])
# Данные о долге в result['metadata']

13. Массовый рефакторинг

Автоматизация массового рефакторинга: миграции API, переименования.

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

План миграции с v1 на v2 API
Переименуй функцию X в Y во всех файлах

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

copilot = MultiScenarioCopilot()
result = copilot.run("План миграции с v1 на v2 API")
print(result['answer'])

14. Реагирование на инциденты ИБ

Расследование инцидентов безопасности: трассировка путей вызовов, анализ CVE, расчёт радиуса поражения, Mermaid-диаграммы путей атаки.

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

Проанализируй CVE-2024-XXXX
Найти все кодовые пути, затронутые этой уязвимостью
Проследить пути атаки к уязвимой функции
Найти точки входа, которые ведут к parse_query
Определить затронутые функции

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

copilot = MultiScenarioCopilot()
result = copilot.run("Проследить влияние уязвимости в parse_query")
print(result['answer'])

# Пути атаки в метаданных
for path in result['metadata'].get('attack_paths', []):
    print(f"{path.entry_point} -> {path.vulnerability} (цепочка: {path.chain_length})")

15. Поддержка отладки

Помощь в отладке на основе потоков данных.

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

Найди все места с elog(ERROR)
Покажи потенциальные взаимные блокировки
Найди отсутствующие захваты блокировок

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

copilot = MultiScenarioCopilot()
result = copilot.run("Найди все места с elog(ERROR)")
print(result['answer'])

16. Точки входа и поверхность атаки

Анализ поверхности атак: точки входа API, экспортированные функции, hook-функции.

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

Какие функции принимают пользовательский ввод?
Найти все экспортированные функции
Показать основные точки входа API
Найти функции-перехватчики (hook-функции)

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

copilot = MultiScenarioCopilot()
result = copilot.run("Найти точки входа API")
print(result['answer'])
# Данные о точках входа в result['metadata']

17. Редактирование файлов

Точечное редактирование кода на основе AST.

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

Переименуй функцию X в Y во всех файлах

18. Оптимизация кода (композитный)

Комплексная оптимизация: композитный сценарий, запускающий подсценарии S02, S05, S06, S11, S12 параллельно (таймаут 60 с).

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

Оптимизируй модуль авторизации

19. Проверка по стандартам (композитный)

Проверка кода по эталонным стандартам: композитный сценарий, запускающий S08, S17, S18 последовательно (таймаут 45 с).

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

Проверь код на соответствие стандартам проекта

20. Анализ зависимостей

Анализ зависимостей и импортов: граф зависимостей модулей.

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

Покажи дерево зависимостей модуля
Какие модули зависят от модуля storage?
Найди циклические зависимости

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

copilot = MultiScenarioCopilot()
result = copilot.run("Покажи зависимости модуля transaction")
print(result['answer'])
# Данные о зависимостях в result['metadata']

21. Синхронизация документации по интерфейсам

Проверка покрытия документации по всем интерфейсам CodeGraph. Обнаруживает сущности кода (эндпоинты, команды, инструменты, методы) и сравнивает их с существующей markdown-документацией для выявления незадокументированных сущностей, устаревшей документации и расхождений сигнатур.

Поддерживаемые интерфейсы

REST API, CLI, MCP, ACP, gRPC, WebSocket — 6 интерфейсов с настраиваемыми путями и маппингом файлов документации.

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

Проверь покрытие документации
Какие эндпоинты не задокументированы?
Найди устаревшую документацию
Покажи отчёт docs sync для REST API и CLI

Категории дрифта

  • UNDOCUMENTED: Сущность есть в коде, но отсутствует в документации
  • STALE: Документация описывает сущность, которой больше нет в коде
  • OUTDATED: Обе существуют, но параметры/сигнатуры расходятся
  • COVERED: Корректно задокументировано

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

CLI

# Полный отчёт (markdown)
python -m src.cli docs-sync --db data/projects/codegraph.duckdb

# CI-режим (код выхода 1, если покрытие ниже порога)
python -m src.cli docs-sync --check --format json

# Фильтрация по интерфейсам
python -m src.cli docs-sync --interfaces rest_api,cli --language ru

REST API

POST /api/v1/documentation/sync
{
  "interfaces": ["rest_api", "cli"],
  "language": "ru",
  "output_format": "markdown"
}

MCP

codegraph_docs_sync(interfaces="rest_api,cli", language="ru", output_format="json")

Программное использование

from src.workflow.scenarios.interface_docs_sync_composite import InterfaceDocsSyncRunner

runner = InterfaceDocsSyncRunner(db_path="data/projects/codegraph.duckdb")
result = runner.run()
print(result.markdown)
print(f"Покрытие: {result.coverage_ratio:.1%}")

Композитные рабочие процессы

Помимо нумерованных сценариев, CodeGraph предоставляет композитные рабочие процессы, оркестрирующие несколько сценариев вместе.

Композитный аудит

Запускает 9 подсценариев параллельно (таймаут 600 с) по 12 измерениям качества. Формирует комплексный отчёт аудита с дедупликацией результатов и снижением ложных срабатываний.

python -m src.cli audit --db data/projects/postgres.duckdb --language ru --format json

Валидация пользовательских историй

Проверяет пользовательские истории со статусом «Готово» на соответствие 4 интерфейсам (REST, CLI, MCP, gRPC). Убеждается, что каждая «Готовая» история имеет соответствующую реализацию в коде.

python -m src.cli.import_commands dogfood validate-stories

Структурный поиск шаблонов (функция CLI)

Поиск кода, соответствующего структурным шаблонам с CPG-ограничениями (поток данных, граф вызовов, типы, доменные аннотации). Это функция CLI/API, а не нумерованный сценарий рабочего процесса.

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

Найти непроверенные возвращаемые значения
Найти malloc без free
Показать функции с анти-паттернами обработки ошибок
Найти конструирование SQL-запросов без параметризации
Найти все функции с цикломатической сложностью > 20

Типы шаблонов

  • Синтаксические: CST-шаблоны tree-sitter с метапеременными ($VAR, $$ARGS, $_)
  • С CPG-ограничениями: Шаблоны с ограничениями на поток данных, граф вызовов, типы и домен
  • YAML-правила: Предопределённые правила в configs/rules/ (190 правил для 14 языков)

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

CLI

# Ad-hoc поиск шаблона
python -m src.cli patterns search "malloc($x)" --lang c

# Сканирование по всем правилам
python -m src.cli patterns scan

# Сканирование по конкретному правилу
python -m src.cli patterns scan --rule unchecked-return

# Генерация правила из описания
python -m src.cli patterns generate "найти непроверенные возвращаемые значения" --lang c

# Автоисправление (предпросмотр)
python -m src.cli patterns fix --dry-run

Комбинирование сценариев

Запуск нескольких сценариев вместе:

from src.workflow import MultiScenarioCopilot

copilot = MultiScenarioCopilot()

# Принудительный выбор сценария через контекст
result = copilot.run(
    "Проанализировать модуль executor",
    context={"scenario_id": "scenario_2"}  # безопасность
)
print(f"Ответ: {result['answer']}")
print(f"Доказательства: {result['evidence']}")

# Или запустите композитный аудит по всем измерениям
# python -m src.cli audit --db PATH

Следующие шаги