Перейти до вмісту

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

Переглянути як Markdown Редагувати на GitHub Документація для d105217

Матриця можливостей — це згенерований звіт, у якому для кожного підтримуваного прапорця та поведінки зазначено, чи забезпечують нативний інструмент і оболонка Greph еквівалентний результат. Це першоджерело для відповідей на запитання «чи підтримує Greph цю можливість?».

Матриця генерується повторно за результатами реальних проб команд на детермінованому робочому просторі з тестовими даними. Необроблені дані зберігаються в FEATURE_MATRIX.json, а відображена таблиця — у 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()) і перевіряють створення, пошук та оновлення.

Повторне генерування матриці

Командна оболонка
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 і Сумісність / 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, і все працюватиме», а єдиний спосіб дотримати цю обіцянку — запускати upstream-інструмент і оболонку поруч та порівнювати результати. Саме це щоразу робить засіб запуску проб під час повторного генерування матриці.