# Матрица на функциите

Матрицата на функциите е генериран отчет, който за всеки поддържан флаг и всяко поведение записва дали нативният инструмент и обвивката 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**: всяка проба се изпълнява както спрямо двоичния файл на upstream `rg`, така и спрямо `bin/rg`. И двете трябва да `Pass`, за да бъде редът отбелязан като поддържан.
2. **Повърхност за съвместимост с sg**: всяка проба се изпълнява както спрямо двоичния файл на upstream `sg`, така и спрямо `bin/sg`. И двете трябва да `Pass`, за да бъде редът отбелязан като поддържан.
3. **Повърхност само за обвивката sg**: проби, насочени само към `bin/sg` (допълнителни функции, които обвивката предлага, а ast-grep няма).
4. **Нативна повърхност на greph**: проби, които упражняват директно `bin/greph`. Няма upstream инструмент за сравнение; пробите проверяват очакваното поведение в тестовото работно пространство.
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. Скриптът създава тестовото работно пространство, изпълнява всяка проба за съвместимост спрямо upstream двоичния файл (ако е инсталиран) и обвивката Greph, записва структурирания резултат и създава както `FEATURE_MATRIX.json`, така и `FEATURE_MATRIX.md`. Подайте `--stdout`, за да изведете Markdown, без да записвате нито един от двата файла.

Файловете в хранилището се генерират ръчно; CI не ги генерира отново. Наборът PHPUnit, който CI изпълнява, включва тест за генериране на матрицата при маркирани като недостъпни upstream инструменти и проверка на структурата на отчета, така че отказът на една проба да не проваля CI. Генерирайте отново матрицата и прегледайте разликите преди издание.

## Какво влиза в матрицата и какво — в документацията

Справочникът CLI и страниците [Съвместимост / rg](https://greph.inline0.dev/bg/docs/compatibility/rg) и [Съвместимост / sg](https://greph.inline0.dev/bg/docs/compatibility/sg) описват *предвидената* повърхност. Матрицата на функциите записва *проверената* повърхност, като точните аргументи на пробата са посочени до всеки ред.

Ако нещо е документирано, но липсва от матрицата, документацията е остаряла. Ако нещо присъства в матрицата, но не е документирано, документацията трябва да бъде допълнена. Двете трябва да съвпадат.

## Примерни редове

### Съвместимост с rg (откъс)

| Функция | rg | bin/rg | Бележки |
|---|---|---|---|
| Търсене с фиксиран низ | Успех | Успех | Проба: `-F needle single.txt` |
| Търсене с фиксиран низ без разлика между главни и малки букви | Успех | Успех | Проба: `-F -i needle single.txt` |
| Търсене на цели думи | Успех | Успех | Проба: `-F -w needle words.txt` |
| Филтър за glob | Успех | Успех | Проба: `--glob *.php function .` |
| Скритите файлове | Успех | Успех | Проба: `--hidden -F secret .` |
| Структуриран изход JSON | Успех | Успех | Проба: `--json -F needle single.txt` със семантика на събитията ripgrep JSON |

### Съвместимост с 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`, и те да продължат да работят; единственият начин това обещание да се спази е действително да изпълнявате upstream инструмента и обвивката един до друг и да сравнявате резултатите. Стартиращият пробите механизъм прави точно това при всяко генериране на матрицата.