Руководство по сценариям рабочих процессов

Руководство по сценариям рабочих процессов

CodeGraph поддерживает 21 специализированный сценарий анализа.

Содержание

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

# Сценарий Пример использования
1 Онбординг в кодовую базу Навигация по кодовой базе для новых разработчиков
2 Аудит безопасности Комплексный аудит с анализом потоков данных
3 Генерация документации Автоматическая генерация технической документации
4 Разработка функционала Поддержка разработки новых функций
5 Рефакторинг Рекомендации по рефакторингу с анализом влияния
6 Анализ производительности Выявление узких мест производительности
7 Покрытие тестами Анализ тестового покрытия и рекомендации
8 Проверка соответствия 152-ФЗ, ГОСТ Р 56939, OWASP
9 Обзор кода Автоматизированное рецензирование PR/MR
10 Межрепозиторный анализ Анализ межмодульных зависимостей
11 Анализ архитектуры Выявление нарушений архитектурных ограничений
12 Оценка технического долга Количественная оценка технического долга
13 Массовый рефакторинг Автоматизация массового рефакторинга (миграции API)
14 Реагирование на инциденты ИБ Расследование инцидентов с рекомендациями
15 Поддержка отладки Помощь в отладке на основе потоков данных
16 Точки входа и поверхность атаки Анализ поверхности атак и точек входа
17 Редактирование файлов Точечное редактирование кода на основе AST
18 Оптимизация кода Комплексная оптимизация (безопасность, рефакторинг, архитектура)
19 Проверка по стандартам Проверка кода по эталонным стандартам
20 Анализ зависимостей Анализ зависимостей и импортов
21 Структурный поиск шаблонов Поиск шаблонов кода с CPG-ограничениями

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

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

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

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

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

from src.workflow import MultiScenarioCopilot

copilot = MultiScenarioCopilot()
result = copilot.run("Объясни архитектуру проекта", scenario="onboarding")

print(result['answer'])

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

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

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

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

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

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

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

from src.workflow import MultiScenarioCopilot

copilot = MultiScenarioCopilot()
result = copilot.run("Найди уязвимости, связанные с SQL-инъекциями")

for vuln in result['vulnerabilities']:
    print(f"CWE-{vuln['cwe']}: {vuln['description']}")
    print(f"  Файл: {vuln['file']}:{vuln['line']}")
    print(f"  Уровень серьёзности: {vuln['severity']}")

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

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

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

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

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

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

print(result['documentation'])
# Документация в формате Markdown

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

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

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

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

Возможности

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

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

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

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

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

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

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

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

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

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

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

copilot = MultiScenarioCopilot()
result = copilot.run("Найди неиспользуемые функции")

for dead in result['dead_code']:
    print(f"Не используется: {dead['name']} в {dead['file']}")

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

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

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

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

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

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

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

copilot = MultiScenarioCopilot()
result = copilot.run("Найди функции со сложностью > 20")

for func in result['complex_functions']:
    print(f"{func['name']}: complexity={func['complexity']}")

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. Проверка соответствия

Проверка соответствия стандартам: 152-ФЗ, ГОСТ Р 56939, OWASP Top 10.

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

Проверь на соответствие OWASP Top 10
Проверь код на соответствие 152-ФЗ
Проверь соответствие ГОСТ Р 56939

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

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

9. Обзор кода

Автоматизированное рецензирование кода (PR/MR).

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

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

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

python demo_patch_review.py --patch changes.diff

Или программно:

copilot = MultiScenarioCopilot()
result = copilot.run("Проверь изменения в path/to/changes.diff")

for finding in result['findings']:
    print(f"{finding['severity']}: {finding['description']}")

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

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

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

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

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

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

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

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

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

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

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

copilot = MultiScenarioCopilot()
result = copilot.run("Отобразить архитектуру PostgreSQL")

for subsystem in result['subsystems']:
    print(f"{subsystem['name']}: {subsystem['description']}")

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

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

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

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

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

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

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

copilot = MultiScenarioCopilot()
result = copilot.run("Найти участки с техническим долгом")

for debt in result['debt_items']:
    print(f"{debt['location']}: {debt['type']} (серьёзность: {debt['severity']})")

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")

# Пути атаки от точек входа до уязвимости
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")

for entry in result['entry_points']:
    print(f"Точка входа: {entry['name']} ({entry['type']})")

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

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

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

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

18. Оптимизация кода

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

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

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

19. Проверка по стандартам

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

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

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

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

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

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

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

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

copilot = MultiScenarioCopilot()
result = copilot.run("Покажи зависимости модуля transaction")

for dep in result['dependencies']:
    print(f"{dep['from']} -> {dep['to']}")

21. Структурный поиск шаблонов

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

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

Найти непроверенные возвращаемые значения
Найти 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("Найти непроверенные возвращаемые значения", scenario="pattern_search")

for finding in result.get('findings', []):
    print(f"{finding['rule_id']}: {finding['file']}:{finding['line']}")
    print(f"  {finding['message']}")

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

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

from src.workflow import MultiScenarioCopilot

copilot = MultiScenarioCopilot()

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

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

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