본문으로 건너뛰기

기능 매트릭스

Markdown으로 보기 GitHub에서 수정 문서 위치 d105217

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

매트릭스는 결정론적 픽스처 작업 공간에서 실제 명령 프로브를 실행해 다시 생성됩니다. 원시 증거는 FEATURE_MATRIX.json에, 렌더링된 표는 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())를 호출하고 빌드, 검색 및 새로 고침을 확인합니다.

매트릭스 다시 생성

셸
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 및 호환성 / 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을 참조하세요.

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

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