# Gyorsítótárazott AST-keresés

A gyorsítótárazott AST-keresés a [tényindex](https://greph.inline0.dev/hu/docs/indexed/ast) kiegészítő, bemelegített gyorsítótáras módja. A kinyert tények tárolása és az egyező fájlok újraelemzése helyett a gyorsítótár sorosított, elemzett fákat tárol a lemezen. A következő lekérdezések deszerializálják a fákat, és közvetlenül futtatják az egyeztetőt, így a PHP-Parser folyamat teljes egészében kimarad.

A gyorsítótár a `greph-index ast-cache` CLI alparancs és a `Greph::buildAstCache()` / `Greph::searchAstCached()` homlokzatmetódusok alatt érhető el. Több indexben végzett keresést és jegyzék által kezelt készletkeresést is támogat.

## A gyorsítótár létrehozása

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

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

# Build a cache that may refresh automatically for small changes
./vendor/bin/greph-index ast-cache build . \
  --lifecycle opportunistic-refresh \
  --auto-refresh-max-files 32 \
  --auto-refresh-max-bytes 1048576
```

A gyorsítótár alapértelmezés szerint itt tárolódik: `<root>/.greph-ast-cache/`. A gyorsítótár felépítése jellemzően a három indexmód közül a leglassabb, mert minden fájlt egyszer elemezni kell.

A sikeres létrehozás egyetlen soros összefoglalót ír ki:

```text
Built AST cache for 2547 files in .greph-ast-cache (2541 cached trees, +2541 ~0 -0 =0)
```

A gyorsítótárazott fák száma általában valamivel kisebb a fájlok számánál, mert az elemzési hibát okozó, csendben kihagyott fájlokhoz nem jön létre gyorsítótár-bejegyzés. Ha azt szeretné, hogy az elemzési hibák megjelenjenek, adja meg a `--strict-parse` kapcsolót a keresési parancsnál.

## A gyorsítótár frissítése

```bash
./vendor/bin/greph-index ast-cache refresh .
```

A `refresh` újra bejárja az indexelt gyökérkönyvtárat, újraelemzi a módosult fájlokat, és csak az áthelyezett gyorsítótárazott fákat írja újra.

Az életciklus-profilok megegyeznek a többi bemelegített módéval:

- `static`: soha nem ellenőrzi automatikusan az aktualitást, és nem módosít automatikusan
- `manual-refresh`: jelzi az elavult állapotot a `stats` kimenetében, de keresés közben soha nem frissít
- `opportunistic-refresh`: keresés közben csak akkor frissít, ha a módosult fájlok száma a beállított küszöb alatt van
- `strict-stale-check`: frissítés helyett elutasítja az elavult gyorsítótárral végzett kereséseket

## Lekérdezés a gyorsítótárban

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

A kapcsolókészlet megegyezik a [`ast-index search`](https://greph.inline0.dev/hu/docs/indexed/ast#querying-the-index) kapcsolóival, beleértve a hiányzó gyorsítótárakhoz tartozó `--fallback scan` kapcsolót is.

### Keresés több gyorsítótárban

A `--index-dir` ismételt megadásával egy hívásban több bemelegített gyorsítótárban is kereshet:

```bash
./vendor/bin/greph-index ast-cache search \
  --index-dir ../wordpress/.greph-ast-cache \
  --index-dir ./.greph-ast-cache \
  --show-index-origin \
  'array($$$ITEMS)' .
```

### Jegyzék által kezelt gyorsítótár-készletek

Ha már használ elnevezett, bemelegített készleteket, ugyanaz a jegyzék a gyorsítótárazott AST-keresést is vezérelheti:

```bash
./vendor/bin/greph-index set build --mode ast-cache
./vendor/bin/greph-index set stats --mode ast-cache --dry-refresh
./vendor/bin/greph-index set search --mode ast-cache --show-index-origin 'array($$$ITEMS)' .
```

### Tervezői diagnosztika

A `--trace-plan` a gyorsítótárazott AST tervezői döntéseit a `stderr` fájlba írja, többek között a következőket:

- mely bemelegített gyorsítótárakban történt keresés
- lefutott-e az elavultságot kezelő frissítési logika
- a fájlszintű szűkítés utáni jelöltfájl-számok
- a pontos strukturális egyezéshez deszerializált gyorsítótárazott fák száma

## Gyorsítótár és tényindex

Mindkét mód gyorsítja az AST-keresést, de eltérő munkafolyamatokra van optimalizálva.

| Szempont | Tényindex (`ast-index`) | Gyorsítótár (`ast-cache`) |
|---|---|---|
| Mi tárolódik | Kinyert tények (hívásnevek, osztálynevek, deklarációk) | Sorosított elemzett fák |
| Felépítés költsége | Alacsonyabb | Magasabb (mindent elemez) |
| Felépítés mérete | Kisebb | Nagyobb |
| Lekérdezési útvonal | Szűrés tények alapján, majd a jelöltek elemzése és illesztése | Fa visszafejtése, majd illesztés |
| Erre a legjobb | Felismerhető fejű minták (hívásnév, osztálynév) | Strukturális, nem név szerinti megkülönböztető jeggyel rendelkező minták |
| Erre a legrosszabb | Változó metaváltozóval kezdődő minták | Hideg lekérdezések olyan fán, amely már nem fér el az OS lapgyorsítótárában |

A gyakorlatban a tényindex teszi lehetővé a leggyorsabb hideg lekérdezést, a gyorsítótár pedig a leggyorsabb bemelegített lekérdezést. Válassza azt, amelyik illik a munkaterheléséhez, vagy építse fel mindkettőt, és hagyja, hogy az eszköz kiválassza a megfelelőt.

## Programozott használat

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

Greph::buildAstCache('.', lifecycle: IndexLifecycleProfile::Static);

$matches = Greph::searchAstCached(
    'array($$$ITEMS)',
    'src',
    new AstSearchOptions(jobs: 4, tracePlan: true),
);
```

A `searchAstCached` ugyanazt a `AstSearchOptions` fogadja el, mint a natív AST-keresés, és ugyanolyan alakú `list<AstMatch>` eredményt ad vissza. Csak annyi a különbség, hogy a már gyorsítótárazott fájloknál kimarad az elemzési folyamat. Több indexet vagy jegyzékfájlt használó munkafolyamatokhoz használja a `searchAstCachedMany(...)` és a `searchAstCachedSet(...)` lehetőséget.

## Mikor használja

A gyorsítótárazott AST-mód a megfelelő eszköz, ha:

- Ugyanazon a kódbázison ismételten futtat strukturális lekérdezéseket.
- A korábbi futások szűk keresztmetszete a PHP-Parser volt (a profilokban a lexerrel és az elemzővel töltött idő látható).
- Rendelkezésére áll a szerializált fához szükséges lemezterület.

Ha a lekérdezései általában a kódbázis kis részét érintik, és a találatok felismerhető hívásnevek vagy osztálynevek köré csoportosulnak, a [tényindex](https://greph.inline0.dev/hu/docs/indexed/ast) általában jobb választás. Ha a lekérdezések a kódbázis nagy részét érintik, és belefér az egyszeri elemzés költsége, a gyorsítótár a jobb.