Saltar al contenido

Matriz de funciones

Ver como Markdown Editar en GitHub Documentación de d105217

La matriz de funciones es un informe generado que registra, para cada indicador y comportamiento compatibles, si la herramienta nativa y el wrapper Greph producen resultados equivalentes. Es la fuente de referencia para responder a «¿Greph admite esto?».

La matriz se regenera mediante pruebas reales de comandos en un espacio de trabajo determinista de prueba. La evidencia sin procesar está en FEATURE_MATRIX.json y la tabla generada está en FEATURE_MATRIX.md.

Leyenda de estados

Estado Significado
Pass La prueba se ejecutó y coincidió con el comportamiento esperado
Fail La prueba se ejecutó, pero no cumplió el comportamiento esperado
Unavailable El comando del proveedor no estaba disponible en este entorno

Secciones

La matriz se organiza en seis secciones:

  1. Superficie de compatibilidad de rg: cada prueba se ejecuta tanto con el binario original rg como con bin/rg. Ambos deben Pass para que la fila se marque como compatible.
  2. Superficie de compatibilidad de sg: cada prueba se ejecuta tanto con el binario original sg como con bin/sg. Ambos deben Pass para que la fila se marque como compatible.
  3. Superficie exclusiva del wrapper sg: pruebas dirigidas únicamente a bin/sg (funciones adicionales que ofrece el wrapper y que ast-grep no incluye).
  4. Superficie nativa de greph: pruebas que ejercitan bin/greph directamente. No hay ninguna herramienta original con la que comparar; las pruebas verifican el comportamiento esperado en el espacio de trabajo de prueba.
  5. Superficie indexada de greph: pruebas que ejercitan bin/greph-index (compilación, actualización y búsqueda de texto con índices precargados).
  6. Superficie de la biblioteca AST indexada: pruebas que llaman a PHP API (Greph::buildAstIndex(), Greph::searchAstIndexed(), Greph::buildAstCache(), Greph::searchAstCached()) y comprueban la compilación, la búsqueda y la actualización.

Regenerar la matriz

Shell
php bin/feature-matrix

Ejecútelo desde un clon del repositorio con rg y sg en PATH; bin/feature-matrix no forma parte del paquete Composer. Compila el espacio de trabajo de prueba, ejecuta cada prueba de compatibilidad con el binario original (si está instalado) y con el wrapper Greph, registra el resultado estructurado y escribe tanto FEATURE_MATRIX.json como FEATURE_MATRIX.md. Pase --stdout para imprimir Markdown sin escribir ninguno de los archivos.

Los archivos incluidos en el repositorio se regeneran manualmente; CI no los regenera. El conjunto de pruebas PHPUnit que ejecuta CI incluye una prueba que genera la matriz con las herramientas originales marcadas como no disponibles y comprueba la estructura del informe, por lo que el fallo de una sola prueba no hace fallar CI. Regenere la matriz y revise las diferencias antes de una versión.

Contenido de la matriz y de la documentación

La referencia CLI y las páginas Compatibilidad / rg y Compatibilidad / sg describen la superficie prevista. La matriz de funciones registra la superficie verificada, junto con los argumentos exactos de cada prueba.

Si algo está documentado pero no aparece en la matriz, la documentación está desactualizada. Si algo aparece en la matriz pero no está documentado, hay que añadirlo a la documentación. Ambos deben coincidir.

Filas de ejemplo

Compatibilidad de rg (extracto)

Función rg bin/rg Notas
Búsqueda de cadena fija Correcto Correcto Prueba: -F needle single.txt
Búsqueda de cadena fija sin distinguir mayúsculas y minúsculas Correcto Correcto Prueba: -F -i needle single.txt
Búsqueda de palabras completas Correcto Correcto Prueba: -F -w needle words.txt
Filtro glob Correcto Correcto Prueba: --glob *.php function .
Archivos ocultos Correcto Correcto Prueba: --hidden -F secret .
Salida JSON estructurada Correcto Correcto Prueba: --json -F needle single.txt con semántica de eventos ripgrep JSON

Compatibilidad de sg (extracto)

Función sg bin/sg Notas
Búsqueda de patrones con run --pattern Correcto Correcto Prueba: run --pattern array($$$ITEMS) src/App.php
Reescritura mediante run --rewrite Correcto Correcto Prueba: run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] src/App.php
Salida en flujo JSON estructurada Correcto Correcto Prueba: run --json=stream --pattern dispatch($EVENT) src/App.php
Reescritura de todos los resultados Correcto Correcto Prueba: run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] --update-all src/App.php

Para ver la tabla completa, consulte FEATURE_MATRIX.md.

Por qué se basa en pruebas

Una tabla de compatibilidad mantenida a mano acaba desactualizada. El propósito de los wrappers es «sustitúyalos donde antes llamaba a rg o sg y seguirán funcionando», y la única forma de cumplir esa promesa es ejecutar la herramienta original y el wrapper en paralelo y comparar los resultados. El ejecutor de pruebas hace exactamente eso cada vez que se regenera la matriz.