# sg 兼容性

`vendor/bin/sg` 是一个 ast-grep 风格的兼容包装器。它接受最常用的 `ast-grep` 标志，并复用 `vendor/bin/greph -p` 所用的同一 `Greph\Ast\AstSearcher` 引擎。经验证的功能范围根据对上游 `sg` 二进制文件的探测运行结果复现，并收录于 [高级 / 功能矩阵](https://greph.inline0.dev/zh/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/zh/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` 会输出 JSON 结构的 ast-grep。支持三种样式：

```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` | 每行一个匹配项，以换行符分隔的 JSON |
| `--json=compact` | 单个紧凑的 JSON 数组 |

## 已验证的功能范围

以下标志已针对上游 `sg` 二进制文件进行验证，详见[功能矩阵](https://greph.inline0.dev/zh/docs/advanced/feature-matrix)。对于有两种写法的标志（`-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 本身不具备的辅助功能：

- `scan` 和 `rewrite` 是 `run` 的别名
- `--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/zh/docs/advanced/feature-matrix) 使用的探测会检查解析相关字段（文件路径、行号、捕获的代码、捕获内容、JSON 结构）是否等效，而非比较字节流。