# Матрица возможностей

Матрица возможностей — это сгенерированный отчет, в котором для каждого поддерживаемого флага и поведения указано, выдают ли нативный инструмент и оболочка 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
```

Запустите из клона репозитория, где на `PATH` установлены `rg` и `sg`; `bin/feature-matrix` не входит в пакет Composer. Скрипт создает тестовое рабочее пространство, выполняет каждую проверку совместимости с исходным двоичным файлом (если он установлен) и оболочкой Greph, записывает структурированный результат и сохраняет `FEATURE_MATRIX.json` и `FEATURE_MATRIX.md`. Передайте `--stdout`, чтобы вывести Markdown, не записывая ни один из файлов.

Зафиксированные файлы формируются вручную; CI не обновляет их автоматически. Набор тестов PHPUnit, запускаемый в CI, включает проверку, которая создает матрицу с пометками об отсутствии исходных инструментов и проверяет структуру отчета. Поэтому сбой одной проверки не приводит к сбою CI. Перед выпуском заново сформируйте матрицу и проверьте изменения.

## Что входит в матрицу, а что — в документацию

Справочник CLI и страницы [Совместимость / rg](https://greph.inline0.dev/ru/docs/compatibility/rg) и [Совместимость / sg](https://greph.inline0.dev/ru/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` и продолжить работу». Единственный способ выполнить это обещание — запускать исходный инструмент и оболочку рядом, а затем сравнивать результаты. Именно это делает программа проверок при каждой генерации матрицы.