Indexerad AST-sökning

Indexerad AST-sökning är den cacheuppvärmda versionen av AST-sökning. Det första anropet extraherar fakta på nodnivå (anropsnamn, instansieringar, klassdeklarationer och metoddeklarationer) till ett lager på disk. Efterföljande anrop använder lagret för att hoppa över filer som uppenbart inte kan innehålla någon strukturell träff. Matcharen verifierar sedan kandidaterna på nytt mot källkoden.

Faktindexet exponeras via underkommandot greph-index ast-index CLI och fasadmetoderna Greph::buildAstIndex() / Greph::searchAstIndexed(). Det ingår även i arbetsflöden med flera uppvärmda index och manifestbaserade uppsättningar.

Bygga indexet

# 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

Som standard lagras faktindexet i <root>/.greph-ast-index/.

Ett lyckat bygge skriver ut en sammanfattning på en rad:

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

De fyra räknarna visar antalet tillagda, uppdaterade, borttagna och oförändrade filer sedan föregående bygge.

Uppdatera indexet

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

refresh går igenom den indexerade roten på nytt, tolkar ändrade filer igen och skriver endast om de faktarader som har ändrats. Utdata använder samma fyra räknare som textindexet.

Livscykelprofilerna fungerar likadant som för uppvärmda textindex:

• static: kontrollera aldrig aktualiteten eller ändra automatiskt
• manual-refresh: rapportera inaktuellt tillstånd i stats, men uppdatera aldrig under sökning
• opportunistic-refresh: uppdatera vid sökning endast om den ändrade mängden fortfarande är tillräckligt liten
• strict-stale-check: avvisa inaktuella sökningar i stället för att uppdatera

Söka i indexet

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

Syntaxen för metavariabler är identisk med den inbyggda AST-sökningen. Se Lägen / AST-sökning för hela grammatiken.

Alternativ

Återgång när index saknas

Som standard ger ast-index search ett fel om det saknas ett index på den begärda platsen. Ange --fallback scan för att i stället använda en inbyggd AST-genomsökning. Det passar verktyg som vill använda indexerad sökning när den är tillgänglig, men som ändå ska ge resultat innan indexet har byggts.

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

Sökning i flera index

Du kan söka i flera uppvärmda AST-index med ett enda kommando genom att upprepa --index-dir. Detta är användbart för upplägg som WordPress-kärnan plus ett tillägg eller ett 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 är aktiverat får utdata prefix med namnet på den matchande posten i det uppvärmda indexet, så att du ser vilken rot som gav träffen.

Manifestbaserade indexuppsättningar

För stabila uppvärmda konfigurationer kan du definiera ett manifest och låta greph-index set arbeta med de grupperade indexen:

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

Underkommandona för uppsättningar använder samma livscykelhantering, inaktualitetskontroller och planeringsdiagnostik som direkt användning av ast-index.

Planeringsdiagnostik

--trace-plan visar hur Greph begränsade frågan innan den fullständiga matcharen kördes. För ast-index innefattar det vanligtvis:

• den grova faktasignaturen som extraherats från mönstret
• antalet uppvärmda index som genomsöktes
• antalet filer som sorterades bort av faktorfiltret
• antalet kandidater som tolkades på nytt för exakt strukturell verifiering

Vad indexet lagrar

För varje indexerad fil registrerar AST-faktaextraktorn en rad för varje ”intressant” nod. Faktatyperna omfattar de konstruktioner som AST-mönster oftast riktar in sig på:

• Funktions- och metodanrop (efter anropsnamn)
• Klassinstansieringar (efter klassnamn)
• Klass-, gränssnitts-, trait- och enumdeklarationer (efter namn)
• Funktionsdeklarationer (efter namn)
• Metoddeklarationer (efter namn och synlighet)
• Use-satser

När en fråga kommer översätter Greph\Ast\AstFactQuery sökmönstret till en grov faktasignatur (till exempel ”måste innehålla en new av valfri klass”) och söker i faktalagret. Filerna som återstår tolkas sedan på nytt och matchas mot hela mönstret.

Det betyder att faktindexet är ett förfilter, inte ett matchningslager med fullständig återgivning. Matchningssteget tolkar fortfarande källkoden, så den strukturella korrektheten är densamma som vid inbyggd AST-sökning; endast mängden kandidater är mindre.

När du ska använda det

Indexerad AST-sökning passar bäst när:

• Du upprepar samma strukturella frågor mot samma kodbas.
• Mönstren riktar in sig på identifierbara former (anropsnamn, klassnamn, deklarationstyp) som faktaxtraktorn lagrar.
• Du vill minska svarstiden jämfört med att tolka varje fil på nytt.

För mönster vars särskiljande egenskap inte finns i faktamängden (till exempel komplexa nästlade uttryck utan ett igenkännbart huvud) passar det cachade AST-läget oftast bättre, eftersom det hoppar över tolkningssteget helt utan att förlita sig på en grov signatur.

Programmatisk användning

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 accepterar samma AstSearchOptions som inbyggd AST-sökning och returnerar samma form på list<AstMatch>. För flöden med flera index eller manifest använder du searchAstIndexedMany(...) och searchAstIndexedSet(...).