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은 JSON 형식의 ast-grep을 출력합니다. 세 가지 스타일을 지원합니다.

셸

./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 바이너리를 대상으로 검증되었습니다. 플래그에 두 가지 표기법(-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 형식 등 파서에 중요한 필드의 동등성을 확인합니다.