Pular para o conteúdo

Matriz de recursos

Ver como Markdown Editar no GitHub Documentação em d105217

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 e a tabela renderizada fica em 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

Shell
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 e Compatibilidade / 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.

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.