Zum Inhalt springen

sg-Kompatibilität

Als Markdown anzeigen Auf GitHub bearbeiten Dokumentation zu d105217

vendor/bin/sg ist ein Kompatibilitätswrapper im Stil von ast-grep. Er akzeptiert die am häufigsten verwendeten ast-grep-Optionen und verwendet dieselbe Engine Greph\Ast\AstSearcher wie vendor/bin/greph -p. Die geprüfte Funktionsabdeckung wurde anhand von Testläufen mit der Upstream-Binärdatei sg ermittelt und ist unter Erweitert / Funktionsmatrix dokumentiert.

Wann du ihn verwenden solltest

Verwende den Wrapper, wenn:

  • Du bereits ein Tool, einen Agenten oder ein Skript hast, das sg aufruft.
  • Du einen direkten Ersatz suchst, der auch in Umgebungen funktioniert, in denen du ast-grep selbst nicht installieren kannst.
  • Du die Bedienung von ast-grep mit einer Installation nur über Composer nutzen möchtest.

Verwende das native vendor/bin/greph -p, wenn:

  • Du neuen Code schreibst und nicht die ast-grep-Form CLI benötigst.
  • Du denselben Optionssatz wie im Textmodus verwenden möchtest (die native Binärdatei vereint beide Modi).

Verwendung

Shell
sg run --pattern PATTERN [options] [path...]
sg scan -p PATTERN [options] [path...]
sg rewrite -p PATTERN -r TEMPLATE [options] [path...]

run ist das kanonische ast-grep-Verb. scan und rewrite sind nur im Wrapper verfügbare Aliase, die der üblichen Verwendung entsprechen. Ein Aufruf ohne Argumente funktioniert als einmalige Suche:

Shell
./vendor/bin/sg --pattern 'array($$$ITEMS)' src

Muster

Die Mustersyntax ist identisch mit der nativen AST-Suche. Die vollständige Referenz findest du unter Modi / AST-Suche.

Shell
./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

Umschreibungen

Der Wrapper unterstützt denselben Ablauf mit Probelauf, interaktiver Bestätigung und Schreiben wie die native Umschreibung, verwendet dabei aber die Optionsnamen von ast-grep:

Shell
# 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-Ausgabe

--json gibt JSON im ast-grep-Format aus. Drei Stile werden unterstützt:

Shell
./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
Stil Format
--json (Standard: pretty) Ein einzelnes formatiertes JSON-Array
--json=stream Eine Übereinstimmung pro Zeile, durch Zeilenumbrüche getrennte JSON-Daten
--json=compact Ein einzelnes kompaktes JSON-Array

Geprüfte Funktionsabdeckung

Die folgenden Optionen wurden anhand der Upstream-Binärdatei sg in der Funktionsmatrix überprüft. Hat eine Option zwei Schreibweisen (-p und --pattern, --glob und --globs), verwendet die Prüfung eine davon; der Wrapper verarbeitet beide als dieselbe Option.

Musteroptionen

  • --pattern PATTERN (auf oberster Ebene und innerhalb von run)
  • -p PATTERN (Alias)
  • --rewrite TEMPLATE
  • -r TEMPLATE
  • --lang NAME, -l NAME

Optionen für Übereinstimmungen

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

Optionen für den Dateibaum

  • --no-ignore hidden (Kurzform)
  • --glob GLOB, --globs GLOB

Worker-Optionen

  • -j N, --threads N

Ohne Prüfung akzeptiert

Der Wrapper akzeptiert außerdem die folgenden Optionen, die bisher jedoch nicht durch eine Prüfung in der Funktionsmatrix abgedeckt sind:

  • --no-ignore allein oder mit einem anderen Wert als hidden
  • --type NAME, --type-not NAME

Zusätzliche Wrapper-Optionen

Der Wrapper bietet einige Hilfsoptionen, die ast-grep selbst nicht hat:

  • Die Aliase scan und rewrite für run
  • Option --hidden (ast-grep integriert dies in --no-ignore hidden)
  • Alias --dry-run für die Vorschau von Umschreibungen
  • --interactive-Ablauf zur Bestätigung von Umschreibungen

Einschränkungen

Der sg-Wrapper von Greph deckt die strukturelle Suche und Umschreibung ab, die von den meisten Tools und Agenten verwendet wird. Die folgenden ast-grep-Funktionen stellt er derzeit nicht bereit:

  • YAML-Regeldateien (--rule, --config)
  • Scans in mehreren Sprachen über PHP hinaus
  • Nichtmuster-Transformatoren (--debug-query, --inspect)
  • LSP-Integration

Wenn dir eine fehlende Option auffällt, erstelle ein Issue mit der Prüfung, die du gegen Upstream-sg ausgeführt hast, und der erwarteten Ausgabe.

Verhaltensgleichheit

Der Wrapper zielt auf Verhaltensgleichheit, nicht auf Byte-Gleichheit. Die Ausgabe ist semantisch gleichwertig, kann sich aber in optischen Details unterscheiden. Die Prüfungen der Funktionsmatrix kontrollieren die Gleichwertigkeit der parserrelevanten Felder (Dateipfad, Zeilennummer, erfasster Code, Erfassungen, JSON-Format), nicht des Bytestroms.