Към съдържанието

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

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