コンテンツへスキップ

sg互換性

Markdownとして表示 GitHubで編集 ドキュメント: d105217

vendor/bin/sgはast-grep形式の互換ラッパーです。よく使われるast-grepフラグを受け付け、vendor/bin/greph -pが使うものと同じGreph\Ast\AstSearcherエンジンを再利用します。検証済みの機能範囲は、上流のsgバイナリに対するプローブ実行結果をもとに再現しており、詳細 / 機能マトリクスに掲載しています。

使用する場面

次のような場合にラッパーを使ってください。

  • すでにsgを呼び出しているツール、エージェント、スクリプトがある。
  • ast-grep自体をインストールできない環境で使える、差し替え可能なツールが必要である。
  • Composerのみのインストールでast-grepの使い勝手を得たい。

次の場合はネイティブの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を出力します。次の3つの形式に対応しています。

シェル
./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 1行につき1件の一致を出力する、改行区切りのJSON
--json=compact コンパクトな単一JSON配列

検証済みの機能範囲

以下のフラグは、機能マトリクスで上流のsgバイナリを使って検証済みです。フラグに2種類の表記（-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自体にはない便利な機能がいくつかあります。

  • runの別名scanとrewrite
  • --hiddenフラグ（ast-grepでは--no-ignore hiddenに統合）
  • --dry-run書き換えプレビューの別名
  • --interactive書き換えの確認フロー

制限事項

Grephのsgラッパーは、多くのツールやエージェントが使う構造検索と書き換えの機能をカバーします。現在、次のast-grep機能は公開されていません。

  • YAMLルールファイル（--rule、--config）
  • PHP以外の複数言語スキャン
  • パターンを使わない変換器（--debug-query、--inspect）
  • LSP連携

未対応のフラグが見つかった場合は、上流のsgに対して実行したプローブと期待される出力を添えて課題を報告してください。

動作の互換性

このラッパーが目指すのは動作の互換性であり、バイト単位の一致ではありません。出力は意味的に同等ですが、見た目の細部は異なる場合があります。機能マトリクスのプローブでは、バイト列ではなくパーサーが参照するフィールド（ファイルパス、行番号、キャプチャされたコード、キャプチャ、JSON形式）の同等性を確認します。