Структурный поиск шаблонов — самостоятельная локальная CLI-возможность на базе GoCPG. Это не сценарий 21: текущий Scenario 21 — interface documentation sync. Руководство охватывает поиск AST-шаблонов, сканирование YAML-правилами, просмотр результатов, генерацию правил и явно подтверждённые изменения для известной базы CPG.
Предварительные условия и область
Каждая команда scan, search, list, stats или fix требует явный --db PATH: CLI не заимствует скрытый активный проект. Сохраните ревизию исходников, по которой построен CPG, идентификатор базы, выбранные каталоги и идентификатор правила, язык, фильтры файлов и версию GoCPG.
Поддерживаемый встроенный источник правил — gocpg/configs/rules/. Не фиксируйте в постоянно актуальном тексте число правил или языков: оно зависит от ревизии. Если состав пакета важен, передайте точный каталог через --rules.
Поиск и сканирование без изменения исходников
Выполните ad hoc поиск AST-шаблона:
python -m src.cli patterns search "malloc($SIZE)" --lang c --db PATH
Запустите проверенный пакет правил и сохраните SARIF:
python -m src.cli patterns scan --db PATH --rules gocpg/configs/rules/c --format sarif --output results.sarif
search возвращает ограниченный набор совпадений до --max-results. scan применяет YAML-правила и в ходе анализа может обновить таблицы результатов в выбранном CPG. Эти команды не меняют исходники. Сохраните находки, диагностику, хеши правил и связь ревизии CPG с исходниками.
Сначала выполните предпросмотр
patterns fix изменяет файлы, если не указан --dry-run. Начинайте с той же базы, корня исходников, каталога и идентификатора правила, а также файловой области, которую собираетесь подтвердить:
python -m src.cli patterns fix --db PATH --rules gocpg/configs/rules/autofix --input SOURCE_ROOT --dry-run
Предпросмотр печатает затронутые файлы, строки, диагностику и diff, если их вернул backend. CLI также вычисляет preview_digest по проверенной области. Остановитесь, если ревизия изменилась, путь выходит за SOURCE_ROOT, пакет правил отличается или данных предпросмотра недостаточно для оценки.
Подтвердите, примените и проверьте
После фиксации предпросмотра и точной области повторите команду без --dry-run:
python -m src.cli patterns fix --db PATH --rules gocpg/configs/rules/autofix --input SOURCE_ROOT
CLI запрашивает разрешение через ApprovalEngine; если этот маршрут недоступен в интерактивном терминале, используется явный вопрос оператору. Отказ, EOF или ошибка approval не должны превращаться в неявное согласие.
Резервные копии включены по умолчанию и используют файлы .bak, если их поддерживает rewrite-backend GoCPG. Параметр --no-backup намеренно ослабляет восстановление и допустим только при отдельно принятых свидетельствах version control и rollback. Успешный результат требует fix_applied для каждого возвращённого изменения; неподтверждённый результат закрывается отказом.
После применения изучите diff системы контроля версий, выполните целевые тесты и статические проверки, сопоставьте каждый файл с подтверждённым предпросмотром. Backup хранит копию для восстановления; транзакционный откат выполняется средствами version control. Восстанавливайте файлы из проверенного состояния после разрешения точных путей.
Другие CLI-операции
python -m src.cli patterns list --db PATH
python -m src.cli patterns stats --db PATH
python -m src.cli patterns generate "найди непроверенные возвращаемые значения" --lang c --output rule.yaml
Сгенерированное правило проходит ревью и тесты до использования. generate может обращаться к LLM и требовать настроенный доступ к модели; синтаксис, точность и безопасность правила проверяйте отдельно.
Граница runtime-поверхности
Прежние REST- и MCP-поверхности структурного поиска removed. Используйте описанный CLI. Не публикуйте примеры выведенных /api/v1/patterns/... и не выводите наличие MCP-команды изменения из находок, доступных в других функциях.
Контракт источников
src/cli/analysis_commands/patterns_command.py— регистрация CLI, явная база, предпросмотр, approval, backup и подтверждение применения;src/services/cpg/query_mixins/pattern_queries.py— чтение сохранённых правил, находок и статистики;src/services/gocpg/core/models.py— текущие модели запроса и результата scan;gocpg/configs/rules/— поддерживаемые rule packs в репозитории;gocpg/pkg/storage/duckdb/schema.go— таблицы правил и результатов.