Перейти до вмісту

Сумісність із 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 виводить дані JSON у формі ast-grep. Підтримуються три стилі:

Командна оболонка
./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), а не потоку байтів.