# Matriz de recursos

A matriz de recursos é um relatório gerado que registra, para cada sinalizador e comportamento compatível, se a ferramenta nativa e o wrapper Greph produzem resultados equivalentes. Ela é a fonte confiável para responder a perguntas como "Greph oferece suporte a isto?".

A matriz é regenerada com sondagens de comandos reais em um espaço de trabalho de teste determinístico. As evidências brutas ficam em [`FEATURE_MATRIX.json`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.json) e a tabela renderizada fica em [`FEATURE_MATRIX.md`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.md).

## Legenda de status

| Status | Significado |
|---|---|
| `Pass` | A sondagem foi executada e correspondeu ao comportamento esperado |
| `Fail` | A sondagem foi executada, mas não correspondeu ao comportamento esperado |
| `Unavailable` | O comando do provedor não estava disponível neste ambiente |

## Seções

A matriz está organizada em seis seções:

1. **Compatibilidade com rg**: cada sondagem é executada tanto no binário upstream `rg` quanto em `bin/rg`. Ambos precisam `Pass` para que a linha seja marcada como compatível.
2. **Compatibilidade com sg**: cada sondagem é executada tanto no binário upstream `sg` quanto em `bin/sg`. Ambos precisam `Pass` para que a linha seja marcada como compatível.
3. **Superfície exclusiva do wrapper sg**: sondagens que visam apenas `bin/sg` (recursos extras expostos pelo wrapper que ast-grep não oferece).
4. **Superfície nativa do greph**: sondagens que exercitam diretamente `bin/greph`. Não há ferramenta upstream para comparar; as sondagens verificam o comportamento esperado no espaço de trabalho de teste.
5. **Superfície indexada do greph**: sondagens que exercitam `bin/greph-index` (compilação, atualização e pesquisa de texto aquecida).
6. **Superfície da biblioteca de AST indexada**: sondagens que chamam PHP API (`Greph::buildAstIndex()`, `Greph::searchAstIndexed()`, `Greph::buildAstCache()`, `Greph::searchAstCached()`) e verificam a compilação, a pesquisa e a atualização.

## Regenerar a matriz

```bash
php bin/feature-matrix
```

Execute a partir de um clone do repositório com `rg` e `sg` no `PATH`; `bin/feature-matrix` não faz parte do pacote Composer. Ele compila o espaço de trabalho de teste, executa cada sondagem de compatibilidade com o binário upstream (se estiver instalado) e com o wrapper Greph, registra o resultado estruturado e grava tanto `FEATURE_MATRIX.json` quanto `FEATURE_MATRIX.md`. Passe `--stdout` para exibir o Markdown sem gravar nenhum dos arquivos.

Os arquivos versionados são regenerados manualmente; o CI não os regenera. A suíte PHPUnit executada pelo CI inclui um teste que gera a matriz com as ferramentas upstream marcadas como indisponíveis e verifica a estrutura do relatório, para que uma única sondagem que comece a falhar não faça o CI falhar. Regenere a matriz e revise as diferenças antes de uma versão.

## O que fica na matriz e o que fica na documentação

A referência CLI e as páginas [Compatibilidade / rg](https://greph.inline0.dev/pt/docs/compatibility/rg) e [Compatibilidade / sg](https://greph.inline0.dev/pt/docs/compatibility/sg) descrevem a superfície *pretendida*. A matriz de recursos registra a superfície *verificada*, com os argumentos exatos das sondagens ao lado de cada linha.

Se algo está documentado, mas não aparece na matriz, a documentação está desatualizada. Se algo consta na matriz, mas não está documentado, é preciso complementar a documentação. Ambos devem corresponder.

## Exemplos de linhas

### Compatibilidade com rg (trecho)

| Recurso | rg | bin/rg | Observações |
|---|---|---|---|
| Pesquisa de cadeia fixa | Passou | Passou | Sondagem: `-F needle single.txt` |
| Pesquisa de cadeia fixa sem distinção entre maiúsculas e minúsculas | Passou | Passou | Sondagem: `-F -i needle single.txt` |
| Pesquisa de palavra inteira | Passou | Passou | Sondagem: `-F -w needle words.txt` |
| Filtro glob | Passou | Passou | Sondagem: `--glob *.php function .` |
| Arquivos ocultos | Passou | Passou | Sondagem: `--hidden -F secret .` |
| Saída estruturada JSON | Passou | Passou | Sondagem: `--json -F needle single.txt` com semântica de eventos ripgrep JSON |

### Compatibilidade com sg (trecho)

| Recurso | sg | bin/sg | Observações |
|---|---|---|---|
| Pesquisa de padrões com `run --pattern` | Passou | Passou | Sondagem: `run --pattern array($$$ITEMS) src/App.php` |
| Reescrita via `run --rewrite` | Passou | Passou | Sondagem: `run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] src/App.php` |
| Saída de fluxo estruturado JSON | Passou | Passou | Sondagem: `run --json=stream --pattern dispatch($EVENT) src/App.php` |
| Reescrita de todos os itens | Passou | Passou | Sondagem: `run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] --update-all src/App.php` |

Para a tabela completa, consulte [`FEATURE_MATRIX.md`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.md).

## Por que usar sondagens

Uma tabela de compatibilidade mantida manualmente fica desatualizada. O objetivo dos wrappers é "substituí-los onde você costumava chamar `rg` ou `sg`, e eles continuam funcionando"; a única forma de cumprir essa promessa é executar a ferramenta upstream e o wrapper lado a lado e comparar os resultados. O executor de sondagens faz exatamente isso cada vez que a matriz é regenerada.