# 기능 매트릭스

기능 매트릭스는 지원되는 각 플래그와 동작에 대해 기본 도구와 Greph 래퍼가 동일한 출력을 생성하는지 기록하는 생성된 보고서입니다. "Greph가 이 기능을 지원하나요?"라는 질문에 대한 기준 자료입니다.

매트릭스는 결정론적 픽스처 작업 공간에서 실제 명령 프로브를 실행해 다시 생성됩니다. 원시 증거는 [`FEATURE_MATRIX.json`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.json)에, 렌더링된 표는 [`FEATURE_MATRIX.md`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.md)에 있습니다.

## 상태 범례

| 상태 | 의미 |
|---|---|
| `Pass` | 프로브가 실행되어 예상 동작과 일치함 |
| `Fail` | 프로브가 실행됐지만 예상 동작을 충족하지 못함 |
| `Unavailable` | 이 환경에 제공자 명령이 없음 |

## 섹션

매트릭스는 여섯 섹션으로 구성됩니다:

1. **rg 호환성 범위**: 각 프로브를 업스트림 `rg` 바이너리와 `bin/rg` 모두에 실행합니다. 행을 지원됨으로 표시하려면 둘 다 `Pass`해야 합니다.
2. **sg 호환성 범위**: 각 프로브를 업스트림 `sg` 바이너리와 `bin/sg` 모두에 실행합니다. 행을 지원됨으로 표시하려면 둘 다 `Pass`해야 합니다.
3. **sg 래퍼 전용 범위**: `bin/sg`만 대상으로 하는 프로브입니다(래퍼가 제공하지만 ast-grep 자체에는 없는 추가 기능).
4. **기본 greph 범위**: `bin/greph`을 직접 실행하는 프로브입니다. 비교할 업스트림 도구가 없으므로 픽스처 작업 공간에서 예상 동작을 확인합니다.
5. **인덱스 greph 범위**: `bin/greph-index`을 실행하는 프로브입니다(빌드, 새로 고침 및 워밍된 텍스트 검색).
6. **인덱스 AST 라이브러리 범위**: PHP API(`Greph::buildAstIndex()`, `Greph::searchAstIndexed()`, `Greph::buildAstCache()`, `Greph::searchAstCached()`)를 호출하고 빌드, 검색 및 새로 고침을 확인합니다.

## 매트릭스 다시 생성

```bash
php bin/feature-matrix
```

`rg` 및 `sg`이 `PATH`에 설치된 저장소 클론에서 실행하세요. `bin/feature-matrix`는 Composer 패키지에 포함되지 않습니다. 픽스처 작업 공간을 만들고, 설치된 경우 업스트림 바이너리 및 Greph 래퍼에 대해 각 호환성 프로브를 실행하며, 구조화된 결과를 기록하고 `FEATURE_MATRIX.json` 및 `FEATURE_MATRIX.md`을 작성합니다. 파일을 쓰지 않고 Markdown을 출력하려면 `--stdout`을 전달하세요.

커밋된 파일은 수동으로 다시 생성하며 CI는 이를 다시 생성하지 않습니다. CI에서 실행하는 PHPUnit 모음에는 업스트림 도구를 사용할 수 없는 것으로 표시해 매트릭스를 생성하고 보고서 형식을 확인하는 테스트가 포함됩니다. 따라서 단일 프로브의 실패로 CI가 실패하지는 않습니다. 릴리스 전에 매트릭스를 다시 생성하고 변경 사항을 검토하세요.

## 매트릭스와 문서의 내용

CLI 참조 페이지와 [호환성 / rg](https://greph.inline0.dev/ko/docs/compatibility/rg) 및 [호환성 / sg](https://greph.inline0.dev/ko/docs/compatibility/sg) 페이지는 *의도된* 범위를 설명합니다. 기능 매트릭스는 각 행에 정확한 프로브 인수를 표시해 *검증된* 범위를 기록합니다.

문서에 있지만 매트릭스에 없는 내용은 문서가 오래된 것입니다. 매트릭스에 있지만 문서에 없는 내용은 문서에 보완해야 합니다. 두 내용은 일치해야 합니다.

## 예시 행

### rg 호환성(발췌)

| 기능 | rg | bin/rg | 참고 |
|---|---|---|---|
| 고정 문자열 검색 | 통과 | 통과 | 프로브: `-F needle single.txt` |
| 대소문자를 구분하지 않는 고정 문자열 검색 | 통과 | 통과 | 프로브: `-F -i needle single.txt` |
| 전체 단어 검색 | 통과 | 통과 | 프로브: `-F -w needle words.txt` |
| 글로브 필터 | 통과 | 통과 | 프로브: `--glob *.php function .` |
| 숨김 파일 | 통과 | 통과 | 프로브: `--hidden -F secret .` |
| 구조화된 JSON 출력 | 통과 | 통과 | JSON ripgrep 이벤트 의미 체계를 사용하는 프로브: `--json -F needle single.txt` |

### sg 호환성(발췌)

| 기능 | sg | bin/sg | 참고 |
|---|---|---|---|
| `run --pattern`을 사용하는 패턴 검색 | 통과 | 통과 | 프로브: `run --pattern array($$$ITEMS) src/App.php` |
| `run --rewrite`을 통한 재작성 | 통과 | 통과 | 프로브: `run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] src/App.php` |
| 구조화된 JSON 스트림 출력 | 통과 | 통과 | 프로브: `run --json=stream --pattern dispatch($EVENT) src/App.php` |
| 전체 업데이트 재작성 | 통과 | 통과 | 프로브: `run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] --update-all src/App.php` |

전체 표는 [`FEATURE_MATRIX.md`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.md)을 참조하세요.

## 프로브 기반 접근 방식의 이유

직접 관리하는 호환성 표는 시간이 지나며 실제 상태와 달라집니다. 래퍼의 목적은 "예전에 `rg` 또는 `sg`을 호출하던 자리에 래퍼를 넣어도 계속 작동"하게 하는 것입니다. 이 약속을 지키려면 업스트림 도구와 래퍼를 나란히 실제로 실행하고 결과를 비교해야 합니다. 매트릭스를 다시 생성할 때마다 프로브 실행기가 바로 이 작업을 수행합니다.