Geïndexeerd AST-zoeken

Geïndexeerd AST-zoeken is de versie van AST-zoeken met een opgewarmde cache. Bij de eerste aanroep worden feiten op knooppuntniveau (aanroepnamen, instanties, klassendeclaraties en methodedeclaraties) geëxtraheerd en opgeslagen op schijf. Bij volgende aanroepen gebruikt de opslag deze feiten om bestanden over te slaan die duidelijk geen structurele match kunnen bevatten. Vervolgens controleert de matcher de kandidaten opnieuw aan de hand van de broncode.

De feitenindex is beschikbaar via de subopdracht greph-index ast-index CLI en de facademethoden Greph::buildAstIndex() / Greph::searchAstIndexed(). De index wordt ook gebruikt bij zoekworkflows met meerdere opgewarmde indexen en met sets op basis van manifesten.

De index bouwen

# 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 feitenindex wordt standaard opgeslagen op <root>/.greph-ast-index/.

Na een geslaagde build wordt een samenvatting van één regel weergegeven:

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

De vier tellers geven het aantal toegevoegde, bijgewerkte, verwijderde en ongewijzigde bestanden sinds de vorige build weer.

De index vernieuwen

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

refresh doorloopt de geïndexeerde root opnieuw, parseert gewijzigde bestanden opnieuw en herschrijft alleen de feitenrijen die zijn veranderd. De uitvoer gebruikt dezelfde vier tellers als de tekstindex.

Levenscyclusprofielen werken hetzelfde als bij opgewarmde tekstindexen:

• static: controleert nooit automatisch of de index actueel is en wijzigt deze nooit automatisch
• manual-refresh: meldt een verouderde status in stats, maar vernieuwt de index nooit tijdens het zoeken
• opportunistic-refresh: vernieuwt de index tijdens het zoeken alleen als de gewijzigde set klein genoeg is
• strict-stale-check: weigert verouderde zoekopdrachten in plaats van de index te vernieuwen

De index doorzoeken

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

De syntaxis voor metavariabelen is identiek aan die van native AST-zoekopdrachten. Zie Modi / AST Search voor de volledige grammatica.

Opties

Terugvaloptie bij ontbrekende index

Standaard geeft ast-index search een foutmelding als er op de gevraagde locatie geen index bestaat. Geef --fallback scan door om in plaats daarvan terug te vallen op een native AST-scan. Dit is de juiste instelling voor tools die geïndexeerd zoeken willen gebruiken wanneer dat beschikbaar is, maar ook resultaten moeten geven als de index nog niet is opgebouwd.

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

Zoeken in meerdere indexen

Je kunt met één opdracht in meerdere opgewarmde AST-indexen zoeken door --index-dir meerdere keren op te geven. Dit is handig voor indelingen zoals WordPress-core met daarnaast een plugin of thema.

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

Wanneer --show-index-origin is ingeschakeld, wordt de uitvoer voorafgegaan door de naam van de overeenkomende opgewarmde indexvermelding, zodat je kunt zien welke root de treffer heeft opgeleverd.

Indexsets op basis van manifesten

Definieer voor stabiele opgewarmde configuraties een manifest en laat greph-index set de gegroepeerde indexen doorzoeken:

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

De set-subopdrachten hanteren dezelfde levenscyclusafhandeling, verouderingscontroles en plannerd diagnostiek als rechtstreeks gebruik van ast-index.

Plannerd diagnostiek

--trace-plan laat zien hoe Greph de query heeft beperkt voordat de volledige matcher werd uitgevoerd. Voor ast-index omvat dit doorgaans:

• de grove feitenhandtekening die uit het patroon is gehaald
• het aantal doorzochte opgewarmde indexen
• het aantal bestanden dat door het feitenfilter is afgewezen
• het aantal kandidaatbestanden dat opnieuw is geparseerd voor exacte structurele verificatie

Wat de index opslaat

Voor elk geïndexeerd bestand registreert de AST-feitenextractor één rij per 'interessant' knooppunt. De soorten feiten omvatten de constructies waarop AST-patronen zich het vaakst richten:

• Functie- en methodeaanroepen (op basis van de aangeroepen naam)
• Klasse-instanties (op basis van de klassenaam)
• Declaraties van klassen, interfaces, traits en enums (op basis van de naam)
• Functiedeclaraties (op basis van de naam)
• Methodedeclaraties (op basis van de naam en zichtbaarheid)
• Use-statements

Wanneer er een query binnenkomt, vertaalt Greph\Ast\AstFactQuery het zoekpatroon naar een grove feitenhandtekening (bijvoorbeeld: 'moet een new van een willekeurige klasse bevatten') en doorsnijdt die met de feitenopslag. De overgebleven bestanden worden opnieuw geparseerd en aan het volledige patroon getoetst.

Dit betekent dat de feitenindex een prefilter is, geen volledige matchopslag. Tijdens het matchen wordt de broncode nog steeds geparseerd. De structurele nauwkeurigheid is dus identiek aan die van native AST-zoekopdrachten; alleen de kandidaatset is kleiner.

Wanneer gebruik je deze?

De geïndexeerde AST-modus is geschikt wanneer:

• Je dezelfde structurele zoekopdrachten herhaaldelijk uitvoert op dezelfde codebase.
• De patronen herkenbare vormen hebben (aanroepnaam, klassenaam, soort declaratie) die door de feitenextractor worden opgeslagen.
• Je minder vertraging wilt dan bij het opnieuw parsen van elk bestand.

Voor patronen waarvan het onderscheidende kenmerk niet in de feitenset staat (bijvoorbeeld complexe geneste expressies zonder herkenbare kop) is de gecachte AST-modus meestal geschikter. Deze slaat de parseerstap volledig over zonder op een grove handtekening te vertrouwen.

Programmatisch gebruik

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 accepteert dezelfde AstSearchOptions als native AST-zoekopdrachten en retourneert hetzelfde list<AstMatch>-formaat. Gebruik voor workflows met meerdere indexen of op manifesten gebaseerde sets searchAstIndexedMany(...) en searchAstIndexedSet(...).