# sg-Kompatibilität

`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](https://greph.inline0.dev/de/docs/advanced/feature-matrix) 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

```bash
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:

```bash
./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](https://greph.inline0.dev/de/docs/modes/ast).

```bash
./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:

```bash
# 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:

```bash
./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](https://greph.inline0.dev/de/docs/advanced/feature-matrix) ü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](https://greph.inline0.dev/de/docs/advanced/feature-matrix) kontrollieren die Gleichwertigkeit der parserrelevanten Felder (Dateipfad, Zeilennummer, erfasster Code, Erfassungen, JSON-Format), nicht des Bytestroms.