# Matriz de funciones

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`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.json) y la tabla generada está en [`FEATURE_MATRIX.md`](https://github.com/inline0/greph/blob/main/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

```bash
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](https://greph.inline0.dev/es/docs/compatibility/rg) y [Compatibilidad / sg](https://greph.inline0.dev/es/docs/compatibility/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`](https://github.com/inline0/greph/blob/main/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.