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

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

Потвърден обхват

Следните флагове са проверени спрямо оригиналния двоичен файл 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), а не на потока от байтове.