# sg互換性

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

## 使用する場面

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

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

次の場合はネイティブの`vendor/bin/greph -p`を使ってください。

- 新しいコードを書く際に、ast-grepのCLI形式に合わせる必要がない。
- テキストモードと同じフラグセットを使いたい（ネイティブバイナリでは両方が統一されています）。

## 使い方

```bash
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`は、一般的な使い方に合わせたラッパー専用の別名です。引数なしの呼び出しで単発の検索ができます。

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

## パターン

パターン文法はネイティブのAST検索と同じです。詳しいリファレンスは[モード / AST検索](https://greph.inline0.dev/ja/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
```

## 書き換え

このラッパーは、ネイティブの書き換えと同じく、ドライラン、対話形式、書き込みのワークフローをサポートしています。フラグ名は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出力

`--json`はast-grep形式のJSONを出力します。次の3つの形式に対応しています。

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

| 形式 | 出力形状 |
|---|---|
| `--json`（デフォルトの`pretty`） | 整形済みの単一JSON配列 |
| `--json=stream` | 1行につき1件の一致を出力する、改行区切りのJSON |
| `--json=compact` | コンパクトな単一JSON配列 |

## 検証済みの機能範囲

以下のフラグは、[機能マトリクス](https://greph.inline0.dev/ja/docs/advanced/feature-matrix)で上流の`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`に対して実行したプローブと期待される出力を添えて課題を報告してください。

## 動作の互換性

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