Перейти к содержимому

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

Просмотреть как 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

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

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

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

Справочник CLI и страницы Совместимость / rg и Совместимость / 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.

Зачем нужны проверки

Таблица совместимости, которую обновляют вручную, со временем устаревает. Смысл оболочек в том, чтобы «подставить их вместо rg или sg и продолжить работу». Единственный способ выполнить это обещание — запускать исходный инструмент и оболочку рядом, а затем сравнивать результаты. Именно это делает программа проверок при каждой генерации матрицы.