Перейти к содержимому

Совместимость с sg

Просмотреть как Markdown Редактировать на GitHub Документация по d105217

vendor/bin/sg — оболочка совместимости в стиле ast-grep. Она поддерживает наиболее часто используемые флаги ast-grep и использует тот же движок Greph\Ast\AstSearcher, что и vendor/bin/greph -p. Подтвержденный набор возможностей составлен по результатам проверок исходного исполняемого файла sg и опубликован в разделе Дополнительно / Матрица возможностей.

Когда использовать

Используйте оболочку, если:

  • У вас уже есть инструмент, агент или скрипт, который вызывает sg.
  • Вам нужна готовая замена, работающая в средах, где нельзя установить сам ast-grep.
  • Вам нужен удобный интерфейс ast-grep при установке только Composer.

Используйте нативный vendor/bin/greph -p, если:

  • Вы пишете новый код, и вам не нужен формат ast-grep CLI.
  • Вам нужен тот же набор флагов, что и в текстовом режиме (в нативной версии оба режима объединены).

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

Командная оболочка
sg run --pattern PATTERN [options] [path...]
sg scan -p PATTERN [options] [path...]
sg rewrite -p PATTERN -r TEMPLATE [options] [path...]

run — каноническая команда ast-grep. scan и rewrite — псевдонимы только для оболочек, повторяющие распространенный способ использования. Запуск без аргументов выполняет поиск за один проход:

Командная оболочка
./vendor/bin/sg --pattern 'array($$$ITEMS)' src

Паттерны

Синтаксис шаблонов идентичен нативному поиску по AST. Полный справочник см. в разделе Режимы / Поиск по AST.

Командная оболочка
./vendor/bin/sg run --pattern 'array($$$ITEMS)' src
./vendor/bin/sg run --pattern '$obj->$method($$$ARGS)' src
./vendor/bin/sg run --pattern 'new $CLASS()' src

Переписывание

Оболочка поддерживает тот же процесс пробного запуска, интерактивного подтверждения и записи, что и нативное переписывание, с именами флагов ast-grep:

Командная оболочка
# Preview only (default)
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' src

# Apply without confirmation
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' --update-all src

# Confirm each match
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' --interactive src

# Wrapper-only aliases
./vendor/bin/sg rewrite -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src
./vendor/bin/sg rewrite -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --interactive src

Вывод JSON

--json выводит ast-grep в формате JSON. Поддерживаются три стиля:

Командная оболочка
./vendor/bin/sg run --json --pattern 'dispatch($EVENT)' src
./vendor/bin/sg run --json=stream --pattern 'dispatch($EVENT)' src
./vendor/bin/sg run --json=compact --pattern 'dispatch($EVENT)' src
Стиль Формат
--json (по умолчанию pretty) Один красиво отформатированный массив JSON
--json=stream Одно совпадение на строку, разделенные символами новой строки JSON
--json=compact Один компактный массив JSON

Проверенный набор возможностей

Следующие флаги проверены на исходном исполняемом файле sg и включены в матрицу возможностей. Если у флага есть две формы записи (-p и --pattern, --glob и --globs), проверка использует одну из них, а оболочка разбирает обе как один и тот же параметр.

Флаги шаблонов

  • --pattern PATTERN (на верхнем уровне и внутри run)
  • -p PATTERN (псевдоним)
  • --rewrite TEMPLATE
  • -r TEMPLATE
  • --lang NAME, -l NAME

Флаги совпадений

  • --files-with-matches
  • --json (pretty, stream, compact)
  • --update-all, -U

Флаги обхода

  • --no-ignore hidden (объединенная форма)
  • --glob GLOB, --globs GLOB

Флаги исполнителей

  • -j N, --threads N

Принятые без проверки

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

  • --no-ignore само по себе или со значением, отличным от hidden
  • --type NAME, --type-not NAME

Дополнительные параметры оболочки

Оболочка предоставляет несколько вспомогательных возможностей, которых нет в самом ast-grep:

  • Псевдонимы scan и rewrite для run
  • Флаг --hidden (ast-grep включает его в --no-ignore hidden)
  • Псевдоним --dry-run для предварительного просмотра переписываний
  • Процесс подтверждения переписываний с помощью --interactive

Ограничения

Оболочка sg для Greph охватывает возможности структурного поиска и переписывания, используемые большинством инструментов и агентов. Сейчас в ней недоступны следующие функции ast-grep:

  • Файлы правил YAML (--rule, --config)
  • Сканирование на нескольких языках, кроме PHP
  • Преобразователи без шаблонов (--debug-query, --inspect)
  • Интеграция с LSP

Если нужного флага нет, создайте задачу и приложите проверку, выполненную на исходном sg, а также ожидаемый результат.

Соответствие поведению

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