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

Руководитель технической группы планирует и координирует масштабные миграции символов/API в кодовой базе.

Содержание

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

# Выберите сценарий массового рефакторинга
/select 13

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

Архитектура (S13 и S05)

S13 (mass_refactoring_workflow) — это псевдоним для refactoring_workflow(state, mode="mass_migration"), определённого в src/workflow/scenarios/refactoring/workflow.py. Он разделяет пакет рефакторинга с S05:

Рабочий процесс Режим Назначение
refactoring_workflow (S05) code_smells (по умолчанию) Обнаружение запахов кода, мёртвый код
large_scale_refactoring_workflow large_scale Массовый рефакторинг с анализом ROI
mass_refactoring_workflow (S13) mass_migration Миграции символов/API и переименования

При mode="mass_migration" рабочий процесс передаёт управление напрямую в mass_migration_workflow() из mass_migration.py (921 строка), минуя Phase 1 на основе обработчиков, используемую S05.

S13 использует двухэтапный подход:

Запрос -> Извлечение символов (5 regex-паттернов)
  |
  Этап 1: Приоритетные CPG-запросы (4 уровня) + Запросы по категориям (9 типов)
  |         -> Сбор целевых функций из CPG (без LLM)
  |
  Этап 2: LLM генерирует план рефакторинга на основе найденных символов
  |         -> Запасной вариант: _build_fallback_answer() при недоступности LLM

Извлечение символов

Рабочий процесс извлекает целевые символы из запроса пользователя с помощью 5 regex-паттернов, проверяемых по порядку:

# Паттерн Пример совпадения Regex
1 “rename X to Y” rename heap_open to table_open \brename\s+(\w+)\s+to\s+(\w+)
2 Имена snake_case heap_open, table_close \b([a-z][a-z0-9]*(?:_[a-z0-9]+)+)\b
3 Имена CamelCase ExecProcNode, FunctionCall \b([A-Z][a-zA-Z0-9]+)\b
4 “keyword to X” references to palloc (?:references?\s+to\|usages?\s+of)\s*(\w+)
5 “X calls” heap_open calls ([a-z_]+)\s+(?:calls?\|usages?)

Общеупотребительные слова (find, all, update, rename и т.д.) исключаются из сопоставления через множество COMMON_WORDS.

Категории миграции

После извлечения символов рабочий процесс запрашивает CPG для функций в 9 категориях миграции:

# Категория Ключевые слова Источник из плагина
1 Executor exec, node, rename sql_patterns["query_execution"]
2 Memory memory, alloc get_memory_functions_from_plugin()
3 Table/Heap table, open sql_patterns["file_operations"]
4 Error error compliance_patterns["error_functions"]
5 Lock lock, tranche get_lock_functions_from_plugin()
6 Cache cache, deprecated sql_patterns["catalog_cache"]
7 Assert assert, macro compliance_patterns["assert_macros"]
8 Slot/Tuple slot, tuple, attr refactoring_targets["slot"]
9 FunctionCall functioncall, call refactoring_targets["functioncall"]

Каждая категория формирует SQL-запрос к nodes_method с соединением edges_call для поиска функций, ранжированных по количеству вызывающих.

Приоритетные запросы

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

Приоритет Категория Метод
1 Slot/Tuple get_tuple_slot_functions_from_plugin(), упорядочивание через CASE
2 Макросы Assert m.name LIKE 'Assert%'
3 FunctionCall refactoring_targets из плагина
4 Обновление сигнатур get_memory_functions_from_plugin(), морфологический матчинг EN+RU

Приоритет 4 поддерживает русские ключевые слова (сигнатура, параметр) через keyword_match_morphological().

Категоризация по сложности

Найденные символы категоризируются по сложности рефакторинга на основе количества вызывающих:

Категория Количество вызывающих Уровень риска
Простые переименования (simple renames) <= min_callers Низкий
Изменения сигнатур (signature modifications) min_callers < count <= high_complexity Средний
Сложные рефакторинги (complex refactors) > high_complexity Высокий

Пороговые значения настраиваются через get_unified_config().thresholds.

Агенты рефакторинга

S13 использует четыре агента рефакторинга совместно с S05, расположенных в src/refactoring/agents/:

TechnicalDebtDetector

TechnicalDebtDetector(cpg_service=None) — обнаруживает запахи кода через библиотеку паттернов.

  • detect_all_smells(limit_per_pattern) — запуск всех паттернов, сортировка по серьёзности
  • calculate_debt_metrics(findings) — вычисление коэффициента долга и метрик трудозатрат
  • detect_pattern(pattern, limit) — запуск одного паттерна

DeadCodeDetector

DeadCodeDetector(cpg_service=None) — специализированный детектор с 13 паттернами мёртвого кода:

DEAD_CODE, DEPRECATED_MARKER, DISABLED_CODE_BLOCK, EMPTY_STUB, ERROR_ONLY_FUNCTION, UNREACHABLE_AFTER_RETURN, ORPHAN_COMPONENT, UNUSED_VARIABLE, DEAD_ASSIGNMENT, INVARIANT_DEAD_CODE, DEAD_CALLBACK, SINGLE_CALLER_FUNCTION, TEST_ONLY_FUNCTION.

  • detect_all(limit_per_pattern) — запуск всех 13 паттернов
  • detect_patterns(patterns, limit_per_pattern) — запуск конкретных паттернов
  • get_summary(findings) — сводная статистика

ImpactAnalyzer

ImpactAnalyzer(cpg_service=None) — анализирует влияние изменений на зависимости.

  • analyze_method_impact(method_name, filename) — вызывающие, вызываемые, оценка влияния
  • analyze_bulk_impact(findings, limit) — пакетный анализ нескольких находок

RefactoringPlanner

RefactoringPlanner() — создаёт приоритизированные планы рефакторинга с оценкой ROI.

  • create_refactoring_plan(findings, impact_analyses) — задачи с приоритетом 1-10
  • generate_report(findings, impact_analyses, tasks) — RefactoringReport

Ключевые модели данных (src/refactoring/agents/models.py): - CodeSmellFinding — обнаруженный запах кода (severity, category, method_name, effort_hours) - DeadCodeFinding — экземпляр мёртвого кода (detection_type, confidence, line_count) - ImpactAnalysis — анализ влияния (impact_score, risk_level, direct_dependents) - RefactoringTask — задача рефакторинга (priority 1-10, effort_hours, refactoring_steps) - RefactoringReport — полный отчёт (total_smells, by_severity, total_effort_hours)

Доменно-независимая архитектура

S13 загружает все данные миграции из доменных плагинов, никогда не используя жёстко закодированные символы. Шесть вспомогательных функций из src/workflow/_plugin_helpers.py предоставляют данные:

Функция Возвращает
get_refactoring_patterns_from_plugin() Целевые паттерны рефакторинга
get_sql_query_patterns_from_plugin() SQL-паттерны (executor, table, cache)
get_memory_functions_from_plugin() Функции работы с памятью
get_lock_functions_from_plugin() Функции блокировок/синхронизации
get_compliance_patterns_from_plugin() Паттерны ошибок и assert
get_tuple_slot_functions_from_plugin() Функции доступа к slot/tuple

Дополнительно DomainPluginV3 предоставляет get_migration_keywords() (соответствие категорий и ключевых слов) и get_migration_descriptions() (соответствие категорий и описаний), используемые генератором запасного ответа.

При недоступности LLM функция _build_fallback_answer() генерирует структурированный отчёт, используя описания из плагина, организованные по совпавшим категориям миграции.

Анализ рисков

CallGraphAnalyzer и радиус поражения

Рабочий процесс рефакторинга (общий для S05/S13) использует CallGraphAnalyzer(cpg) из src/analysis/ для оценки рисков:

  • find_all_callers(method_name, max_depth) — транзитивная цепочка вызывающих
  • find_all_callees(method_name, max_depth) — транзитивная цепочка вызываемых
  • analyze_impact(method_name) — оценка влияния

Радиус поражения (blast radius) = общее число вызывающих + вызываемых. Методы классифицируются: - Безопасно для рефакторинга: радиус < порога blast_radius_medium - Низкий риск: < caller_count_medium - Средний риск: < caller_count_high - Высокий риск: >= caller_count_high

Риск по центральности посредничества

DependencyAnalyzer(cpg).identify_architectural_chokepoints() вычисляет центральность посредничества (betweenness centrality) для каждого метода. Методы выше порогового значения перцентиля compliance_score_high отмечаются как критические архитектурные узкие места — их рефакторинг требует особой осторожности, так как через них проходит множество путей выполнения кода.

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

# Массовый рефакторинг символа
python -m src.cli query "Rename all instances of heap_open to table_open"

# Поиск целей миграции
python -m src.cli query "Find all ExecProcNode references for rename"

# Миграция API работы с памятью
python -m src.cli query "Plan mass refactoring of memory allocation functions"

# Изменения сигнатур
python -m src.cli query "Find functions with signature changes needed"

# Стандартизация макросов Assert
python -m src.cli query "Find all Assert macro usages for standardization"

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

  • «Переименовать все вхождения [старое_имя] в [новое_имя]»
  • «Найти все ссылки на [функцию] для массового рефакторинга»
  • «Спланировать массовый рефакторинг функций выделения памяти»
  • «Найти функции, требующие изменения сигнатуры»
  • «Найти все использования макроса Assert для стандартизации»
  • «Показать паттерны доступа к слотам/кортежам для рефакторинга»
  • «Найти паттерны FunctionCall для модернизации»
  • «Спланировать миграцию функций блокировок»
  • «Найти все использования функций кэша для выведения из эксплуатации»
  • «Показать функции обработки ошибок для миграции»

S13 vs S05 vs S12: S13 специализируется на масштабных миграциях символов/API — переименование функций, обновление сигнатур и модернизация API по всей кодовой базе. S05 фокусируется на обнаружении запахов кода, мёртвого кода и дубликатов с формированием задач рефакторинга. S12 фокусируется на измерении и приоритизации технического долга. Все три разделяют инфраструктуру агентов рефакторинга (TechnicalDebtDetector, DeadCodeDetector, ImpactAnalyzer, RefactoringPlanner), но обслуживают разные сценарии использования.