# Матриця можливостей

Матриця можливостей — це згенерований звіт, у якому для кожного підтримуваного прапорця та поведінки зазначено, чи забезпечують нативний інструмент і оболонка 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/uk/docs/compatibility/rg) і [Сумісність / sg](https://greph.inline0.dev/uk/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-інструмент і оболонку поруч та порівнювати результати. Саме це щоразу робить засіб запуску проб під час повторного генерування матриці.