Indekseret AST-søgning

Indekseret AST-søgning er en version af AST-søgning med opvarmet cache. Ved det første kald udtrækkes fakta på nodeniveau (kaldnavne, instansieringer, klasseerklæringer og metodeerklæringer) til et lager på disken. Efterfølgende kald bruger lageret til at springe filer over, som tydeligvis ikke kan indeholde et strukturelt match. Matcheren verificerer derefter kandidaterne igen mod kildekoden.

Faktaindekset er tilgængeligt via underkommandoen greph-index ast-index CLI og facademetoderne Greph::buildAstIndex() / Greph::searchAstIndexed(). Det indgår også i arbejdsgange med opvarmede indekser og manifestbaserede sæt.

Oprettelse af indekset

# 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

Faktaindekset gemmes som standard på <root>/.greph-ast-index/.

En vellykket oprettelse udskriver en oversigt på én linje:

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

De fire tællere viser antallet af tilføjede, opdaterede, slettede og uændrede filer siden sidste oprettelse.

Opdatering af indekset

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

refresh gennemgår den indekserede rod igen, parser ændrede filer på ny og omskriver kun de faktarækker, der er ændret. Outputtet bruger de samme fire tællere som tekstindekset.

Livscyklusprofiler fungerer på samme måde som for opvarmede tekstindekser:

• static: kontrollér aldrig automatisk, om dataene er aktuelle, og foretag aldrig automatiske ændringer
• manual-refresh: rapportér forældet tilstand i stats, men opdatér aldrig under søgning
• opportunistic-refresh: opdatér under søgning, kun hvis det ændrede filsæt stadig er billigt nok at behandle
• strict-stale-check: afvis forældede søgninger i stedet for at opdatere

Forespørgsler i indekset

./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

Syntaksen for metavariabler er identisk med den i native AST-søgning. Se Tilstande / AST-søgning for hele grammatikken.

Indstillinger

Fallback, når indekset mangler

Som standard melder ast-index search en fejl, hvis der ikke findes noget indeks på den ønskede placering. Angiv --fallback scan for i stedet at falde tilbage til en native AST-scanning. Det er den rette indstilling til værktøjer, der skal bruge indekseret søgning, når den er tilgængelig, men stadig vise resultater, hvis indekset endnu ikke er oprettet.

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

Søgning i flere indekser

Du kan søge i flere opvarmede AST-indekser med én kommando ved at gentage --index-dir. Det er nyttigt til layouts som WordPress-kerne plus et plugin eller et tema.

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

Når --show-index-origin er aktiveret, sættes navnet på det matchende opvarmede indeks foran outputtet, så du kan se, hvilken rod der gav resultatet.

Manifestbaserede indekssæt

Til stabile opsætninger med opvarmede indekser kan du definere et manifest og lade greph-index set arbejde med de grupperede indekser:

./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()' .

Sætunderkommandoerne deler den samme livscyklusstyring, kontrol af forældede data og diagnostik fra planlæggeren som direkte brug af ast-index.

Diagnostik fra planlæggeren

--trace-plan viser, hvordan Greph indsnævrede forespørgslen, før den fulde matcher blev kørt. For ast-index omfatter det typisk:

• den grove faktasignatur, der blev udtrukket fra mønsteret
• hvor mange opvarmede indekser der blev søgt i
• hvor mange filer der blev afvist af faktasøgningsfilteret
• hvor mange kandidatfiler der blev parset på ny for præcis strukturel verifikation

Hvad indekset gemmer

Faktageneratoren til AST gemmer en række for hver "interessant" node i hver indekseret fil. Faktaene dækker de typer konstruktioner, som AST-mønstre oftest retter sig mod:

• Funktions- og metodekald (efter kaldt navn)
• Klasseinstansieringer (efter klassenavn)
• Erklæringer af klasser, interfaces, traits og enums (efter navn)
• Funktionserklæringer (efter navn)
• Metodeerklæringer (efter navn og synlighed)
• Use-udsagn

Når en forespørgsel modtages, oversætter Greph\Ast\AstFactQuery søgemønsteret til en grov faktasignatur (for eksempel "skal indeholde en new af en vilkårlig klasse") og gennemgår faktalageret. Filerne, der overlever denne filtrering, parses derefter på ny og matches mod hele mønsteret.

Det betyder, at faktaindekset er et prefilter, ikke et matchlager, der gengiver alt nøjagtigt. Matchtrinnet parser stadig kildekoden, så den strukturelle korrekthed er identisk med native AST-søgning; det er kun kandidatsættet, der er mindre.

Hvornår skal den bruges

Indekseret AST-tilstand er det rette værktøj, når:

• Du kører gentagne gange de samme strukturelle forespørgsler mod den samme kodebase.
• Mønstrene retter sig mod genkendelige former (kaldnavn, klassenavn, deklarationstype), som faktageneratoren gemmer.
• Du ønsker lavere forsinkelse end ved at parse hver fil igen.

For mønstre, hvor det afgørende kendetegn ikke indgår i faktasættet (for eksempel komplekse indlejrede udtryk uden et genkendeligt hoved), passer cachelagret AST-tilstand som regel bedre, fordi den helt springer parsing over uden at være afhængig af en grov signatur.

Programmatisk brug

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 accepterer samme AstSearchOptions som native AST-søgning og returnerer samme list<AstMatch>-struktur. Brug searchAstIndexedMany(...) og searchAstIndexedSet(...) til arbejdsgange med flere indekser eller manifestbaserede sæt.