Compatibilità con sg

vendor/bin/sg è un wrapper di compatibilità in stile ast-grep. Accetta i flag ast-grep più usati e riutilizza lo stesso motore Greph\Ast\AstSearcher usato da vendor/bin/greph -p. Le funzionalità verificate, riprodotte da test con il binario upstream sg, sono riportate in Avanzate / Matrice delle funzionalità.

Quando usarlo

Usa il wrapper quando:

• Hai uno strumento, un agente o uno script esistente che invoca già sg.
• Vuoi un sostituto compatibile che funzioni in ambienti in cui non puoi installare direttamente ast-grep.
• Vuoi la praticità di ast-grep con un'installazione che supporta solo Composer.

Usa vendor/bin/greph -p nativo quando:

• Stai scrivendo nuovo codice e non ti serve la struttura ast-grep CLI.
• Vuoi lo stesso set di flag della modalità testuale (il binario nativo unifica entrambe).

Utilizzo

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

run è il verbo canonico di ast-grep. scan e rewrite sono alias disponibili solo nei wrapper, che riproducono l'uso comune. Funziona anche un'invocazione senza argomenti per una ricerca singola:

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

Pattern

La grammatica dei pattern è identica a quella della ricerca AST nativa. Per il riferimento completo, consulta Modalità / Ricerca 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

Riscritture

Il wrapper supporta lo stesso flusso di lavoro di esecuzione di prova, interattivo e di scrittura della riscrittura nativa, con i nomi dei flag 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

Output JSON

--json genera ast-grep strutturati in JSON. Sono supportati tre stili:

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

Funzionalità verificate

I seguenti flag sono verificati rispetto al binario upstream sg nella matrice delle funzionalità. Quando un flag ha due forme (-p e --pattern, --glob e --globs), il test ne usa una e il wrapper le interpreta entrambe come la stessa opzione.

Flag dei pattern

• --pattern PATTERN (al livello superiore e all'interno di run)
• -p PATTERN (alias)
• --rewrite TEMPLATE
• -r TEMPLATE
• --lang NAME, -l NAME

Flag delle corrispondenze

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

Flag di scansione

• --no-ignore hidden (forma combinata)
• --glob GLOB, --globs GLOB

Flag dei worker

• -j N, --threads N

Accettati senza test

Il wrapper accetta anche i seguenti flag, che non sono ancora coperti dai test della matrice delle funzionalità:

• --no-ignore da solo oppure con un valore diverso da hidden
• --type NAME, --type-not NAME

Funzioni aggiuntive del wrapper

Il wrapper espone alcune funzioni che ast-grep non offre:

• Alias scan e rewrite per run
• Flag --hidden (ast-grep lo integra in --no-ignore hidden)
• Alias --dry-run per l'anteprima della riscrittura
• Flusso di conferma della riscrittura --interactive

Limitazioni

Il wrapper Greph sg copre le funzionalità di ricerca strutturale e riscrittura usate dalla maggior parte degli strumenti e degli agenti. Al momento non espone le seguenti funzionalità ast-grep:

• File di regole YAML (--rule, --config)
• Scansione multilingue oltre a PHP
• Trasformatori non basati su pattern (--debug-query, --inspect)
• Integrazione LSP

Se ti manca un flag, segnala il problema indicando il test eseguito su sg upstream e l'output previsto.

Parità di comportamento

Il wrapper punta alla parità di comportamento, non a quella byte per byte. L'output è semanticamente equivalente, ma può differire in dettagli estetici. I test usati per la matrice delle funzionalità verificano l'equivalenza dei campi rilevanti per il parser (percorso del file, numero di riga, codice acquisito, acquisizioni, struttura JSON), non del flusso di byte.