# sg 호환성

`vendor/bin/sg`은 ast-grep 스타일 호환 래퍼입니다. 가장 흔히 사용하는 `ast-grep` 플래그를 받아들이고 `vendor/bin/greph -p`에서 사용하는 것과 같은 `Greph\Ast\AstSearcher` 엔진을 재사용합니다. 검증된 기능 범위는 업스트림 `sg` 바이너리를 대상으로 한 프로브 실행 결과를 바탕으로 재현했으며 [고급 / 기능 매트릭스](https://greph.inline0.dev/ko/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/ko/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 배열 |

## 검증된 기능 범위

다음 플래그는 [기능 매트릭스](https://greph.inline0.dev/ko/docs/advanced/feature-matrix)에서 업스트림 `sg` 바이너리를 대상으로 검증되었습니다. 플래그에 두 가지 표기법(`-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/ko/docs/advanced/feature-matrix)의 프로브는 바이트 스트림 자체가 아니라 파일 경로, 줄 번호, 캡처된 코드, 캡처 항목, JSON 형식 등 파서에 중요한 필드의 동등성을 확인합니다.