Búsqueda indexada de AST

La búsqueda indexada de AST es la versión con caché precargada de la búsqueda de AST. La primera llamada extrae datos de los nodos (nombres de llamadas, instanciaciones, declaraciones de clases y declaraciones de métodos) y los guarda en disco; las llamadas siguientes usan el almacén para omitir archivos que claramente no pueden contener una coincidencia estructural. A continuación, el comparador vuelve a verificar los candidatos con el código fuente.

El índice de datos está disponible mediante el subcomando greph-index ast-index CLI y los métodos de interfaz Greph::buildAstIndex() / Greph::searchAstIndexed(). También se usa en los flujos de trabajo con varios índices precargados y conjuntos respaldados por manifiestos.

Creación del índice

# Full build at the current directory
./vendor/bin/greph-index ast-index build .

# Full build at an explicit root
./vendor/bin/greph-index ast-index build path/to/repo

# Use a non-default index directory
./vendor/bin/greph-index ast-index build . --index-dir /tmp/greph-ast-index

# Build a mutable overlay that can refresh cheaply on demand
./vendor/bin/greph-index ast-index build . \
  --lifecycle opportunistic-refresh \
  --auto-refresh-max-files 32 \
  --auto-refresh-max-bytes 1048576

De forma predeterminada, el índice de datos se guarda en <root>/.greph-ast-index/.

Si la creación finaliza correctamente, se muestra un resumen de una línea:

Built AST index for 2547 files in .greph-ast-index (84931 fact rows, +2547 ~0 -0 =0)

Los cuatro contadores muestran los archivos añadidos, actualizados, eliminados y sin cambios desde la última creación del índice.

Actualización del índice

./vendor/bin/greph-index ast-index refresh .

refresh vuelve a recorrer la raíz indexada, analiza de nuevo los archivos modificados y reescribe solo las filas de datos que han cambiado. La salida usa los mismos cuatro contadores que el índice de texto.

Los perfiles de ciclo de vida funcionan igual que en los índices de texto precargados:

• static: nunca comprueba la vigencia ni modifica el índice automáticamente
• manual-refresh: informa si el índice está desactualizado en stats, pero nunca lo actualiza durante la búsqueda
• opportunistic-refresh: actualiza el índice durante la búsqueda solo si el conjunto de cambios sigue siendo lo bastante pequeño
• strict-stale-check: rechaza las búsquedas con datos desactualizados en lugar de actualizar el índice

Consulta del índice

./vendor/bin/greph-index ast-index search 'new $CLASS()' src
./vendor/bin/greph-index ast-index search '$obj->$method($$$ARGS)' src
./vendor/bin/greph-index ast-index search --json 'array($$$ITEMS)' src
./vendor/bin/greph-index ast-index search -l 'array($$$ITEMS)' src
./vendor/bin/greph-index ast-index search --trace-plan 'new $CLASS()' src

La sintaxis de las metavariables es idéntica a la de la búsqueda de AST nativa. Consulte Modos / Búsqueda de AST para ver la gramática completa.

Opciones

Alternativa si falta el índice

De forma predeterminada, ast-index search genera un error si no hay ningún índice en la ubicación solicitada. Pase --fallback scan para recurrir a un análisis de AST nativo. Esta opción es adecuada para herramientas que buscan con un índice cuando está disponible, pero que también deben mostrar resultados cuando aún no se ha creado.

./vendor/bin/greph-index ast-index search --fallback scan 'new $CLASS()' src

Búsqueda en varios índices

Puede buscar en varios índices de AST precargados con un solo comando si repite --index-dir. Resulta útil para estructuras como un núcleo WordPress junto con un complemento o tema.

./vendor/bin/greph-index ast-index search \
  --index-dir ../wordpress/.greph-ast-index \
  --index-dir ./.greph-ast-index \
  --show-index-origin \
  'new $CLASS()' .

Si se habilita --show-index-origin, la salida incluye como prefijo el nombre de la entrada del índice precargado coincidente, para que pueda ver qué raíz produjo el resultado.

Conjuntos de índices respaldados por manifiestos

Para configuraciones precargadas estables, defina un manifiesto y deje que greph-index set opere con los índices agrupados:

./vendor/bin/greph-index set build
./vendor/bin/greph-index set stats --mode ast-index --dry-refresh
./vendor/bin/greph-index set search --mode ast-index --show-index-origin 'new $CLASS()' .

Los subcomandos de conjuntos comparten la misma gestión del ciclo de vida, las comprobaciones de datos desactualizados y los diagnósticos del planificador que el uso directo de ast-index.

Diagnósticos del planificador

--trace-plan muestra cómo Greph redujo el conjunto de consultas antes de ejecutar el comparador completo. Para ast-index, suele incluir:

• la firma general de datos extraída del patrón
• cuántos índices precargados se buscaron
• cuántos archivos se descartaron con el filtro de datos
• cuántos archivos candidatos se volvieron a analizar para verificar la estructura exacta

Datos que almacena el índice

Para cada archivo indexado, el extractor de datos del AST registra una fila por cada nodo «interesante». El conjunto de tipos de datos abarca las construcciones a las que suelen dirigirse los patrones de AST:

• Llamadas a funciones y métodos (por nombre de llamada)
• Instanciaciones de clases (por nombre de clase)
• Declaraciones de clases, interfaces, traits y enumeraciones (por nombre)
• Declaraciones de funciones (por nombre)
• Declaraciones de métodos (por nombre y visibilidad)
• Instrucciones de uso

Cuando llega una consulta, Greph\Ast\AstFactQuery traduce el patrón de búsqueda a una firma general de datos (por ejemplo, «debe contener un new de cualquier clase») y consulta el almacén de datos. Luego, vuelve a analizar los archivos que superan esa intersección y los compara con el patrón completo.

Esto significa que el índice de datos es un prefiltro, no un almacén de coincidencias exhaustivo. El paso de comparación sigue analizando el código fuente, por lo que la precisión estructural es idéntica a la de la búsqueda de AST nativa; solo se reduce el conjunto de candidatos.

Cuándo usarlo

El modo de AST indexado es adecuado cuando:

• Ejecuta repetidamente las mismas consultas estructurales en la misma base de código.
• Los patrones buscan formas identificables (nombre de llamada, nombre de clase o tipo de declaración) que guarda el extractor de datos.
• Quiere reducir la latencia frente a analizar todos los archivos de nuevo.

Para patrones cuyo rasgo distintivo no forma parte del conjunto de datos (por ejemplo, expresiones anidadas complejas sin una cabecera reconocible), el modo de AST en caché suele ser más adecuado, porque omite por completo el análisis sin depender de una firma general.

Uso programático

use Greph\Greph;
use Greph\Ast\AstSearchOptions;
use Greph\Index\IndexLifecycleProfile;

Greph::buildAstIndex('.', lifecycle: IndexLifecycleProfile::OpportunisticRefresh);

$matches = Greph::searchAstIndexed(
    'new $CLASS()',
    'src',
    new AstSearchOptions(jobs: 4, tracePlan: true),
);

searchAstIndexed acepta el mismo AstSearchOptions que la búsqueda de AST nativa y devuelve la misma estructura de list<AstMatch>. Para flujos con varios índices o respaldados por manifiestos, use searchAstIndexedMany(...) y searchAstIndexedSet(...).