# Indeksēta AST meklēšana

Indeksētā AST meklēšana ir [AST meklēšanas](https://greph.inline0.dev/lv/docs/modes/ast) uzsildītās kešatmiņas versija. Pirmajā izsaukumā mezglu līmeņa fakti (izsaukumu nosaukumi, instancēšana, klašu deklarācijas, metožu deklarācijas) tiek izgūti un saglabāti diskā; turpmākajos izsaukumos krātuve palīdz izlaist failus, kuros nevar būt strukturālas atbilstības. Pēc tam atbilstības meklētājs atkārtoti pārbauda kandidātus avota kodā.

Faktu indekss ir pieejams apakškomandā `greph-index ast-index` CLI un fasādes metodēs `Greph::buildAstIndex()` / `Greph::searchAstIndexed()`. Tas tiek izmantots arī uzsildītās vairāku indeksu un uz manifestiem balstītās kopu darbplūsmās.

## Indeksa izveide

```bash
# 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
```

Pēc noklusējuma faktu indekss tiek glabāts mapē `<root>/.greph-ast-index/`.

Pēc veiksmīgas izveides tiek parādīts kopsavilkums vienā rindā:

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

Četri skaitītāji uzrāda pievienotos, atjauninātos, dzēstos un nemainītos failus kopš pēdējās izveides.

## Indeksa atsvaidzināšana

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

`refresh` atkārtoti pārlūko indeksēto saknes mapi, atkārtoti parsē mainītos failus un pārraksta tikai mainītos faktu ierakstus. Izvadē tiek izmantoti tie paši četri skaitītāji, kas teksta indeksam.

Dzīves cikla profili darbojas tāpat kā uzsildītie teksta indeksi:

- `static`: nekad automātiski nepārbauda datu aktualitāti un neveic izmaiņas
- `manual-refresh`: ziņo par novecojušu stāvokli `stats`, bet meklēšanas laikā nekad neveic atsvaidzināšanu
- `opportunistic-refresh`: atsvaidzina tikai tad, ja mainīto failu kopa joprojām ir pietiekami maza
- `strict-stale-check`: novecojušu datu gadījumā atsvaidzināšanas vietā noraida meklēšanu

## Vaicājumi indeksā

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

Metamainīgo sintakse ir tāda pati kā vietējā AST meklēšanā. Pilnu gramatiku skatiet sadaļā [Režīmi / AST meklēšana](https://greph.inline0.dev/lv/docs/modes/ast).

### Opcijas

| Karodziņš | Nozīme |
|---|---|
| `--lang NAME` | AST valoda. Noklusējums: `php` |
| `-j N`, `--jobs N` | Paralēlo darbplūsmu skaits |
| `-l`, `--files-with-matches` | Norādīt tikai atbilstošos failus |
| `--glob GLOB` | Iekļaut tikai failus, kuru ceļi atbilst GLOB |
| `--type NAME` / `--type-not NAME` | Failu tipu filtrs |
| `--json` | Izvadīt JSON formāta datus |
| `--no-ignore` | Ignorēt `.gitignore` un `.grephignore` |
| `--hidden` | Iekļaut slēptos failus |
| `--strict-parse` | Parsēšanas kļūdas gadījumā nevis izlaist to, bet pārtraukt darbību |
| `--fallback MODE` | Ja nav indeksa: `fail` (noklusējums) vai `scan` |
| `--index-dir DIR` | Izmantot citu indeksa mapi |
| `--trace-plan` | Izvadīt uzsildītās AST plānotāja diagnostikas datus uz `stderr` |
| `--show-index-origin` | Vairāku indeksu vai kopas režīmā pievienot izvades sākumā atbilstošā indeksa marķējumu |

### Rezerves režīms, ja trūkst indeksa

Pēc noklusējuma `ast-index search` parāda kļūdu, ja pieprasītajā vietā nav indeksa. Lai tā vietā veiktu vietējo AST skenēšanu, norādiet `--fallback scan`. Tas ir piemērots iestatījums rīkiem, kas vēlas izmantot indeksēto meklēšanu, kad tā ir pieejama, bet joprojām saņemt rezultātus, ja indekss vēl nav izveidots.

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

### Vairāku indeksu meklēšana

Vienā komandā varat meklēt vairākos uzsildītos AST indeksos, atkārtoti norādot `--index-dir`. Tas noder tādiem izkārtojumiem kā WordPress kodols kopā ar spraudni vai tēmu.

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

Ja ir iespējots `--show-index-origin`, izvades sākumā tiek pievienots atbilstošā uzsildītā indeksa ieraksta nosaukums, lai redzētu, kura saknes mape atrada atbilstību.

### Uz manifestiem balstītas indeksu kopas

Lai izveidotu stabilas uzsildītās vides, definējiet manifestu un lieciet `greph-index set` darboties ar grupētajiem indeksiem:

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

Kopu apakškomandās tiek izmantota tā pati dzīves cikla pārvaldība, novecojušu datu pārbaudes un plānotāja diagnostika, kas tiešā `ast-index` izmantošanā.

### Plānotāja diagnostika

`--trace-plan` parāda, kā Greph sašaurināja vaicājumu pirms pilnā atbilstības meklētāja palaišanas. `ast-index` tas parasti ietver:

- no parauga izgūto aptuveno faktu parakstu
- meklēto uzsildīto indeksu skaitu
- faktu filtra noraidīto failu skaitu
- to kandidātfailu skaitu, kas atkārtoti parsēti precīzai strukturālai pārbaudei

## Ko glabā indekss

Katrai indeksētajai datnei AST faktu izgūšanas process saglabā ierakstu par katru "interesanto" mezglu. Faktu veidi aptver konstrukcijas, kuras AST paraugi visbiežāk meklē:

- Funkciju un metožu izsaukumi (pēc izsauktā nosaukuma)
- Klašu instancēšana (pēc klases nosaukuma)
- Klašu, interfeisu, traītu un enum tipu deklarācijas (pēc nosaukuma)
- Funkciju deklarācijas (pēc nosaukuma)
- Metožu deklarācijas (pēc nosaukuma un redzamības)
- Use priekšraksti

Kad pienāk vaicājums, `Greph\Ast\AstFactQuery` pārvērš meklēšanas paraugu aptuvenā faktu parakstā (piemēram, "jāsatur `new` jebkurai klasei") un atlasa atbilstošos ierakstus faktu krātuvē. Pēc tam atlikušie faili tiek atkārtoti parsēti un salīdzināti ar pilno paraugu.

Tas nozīmē, ka faktu indekss ir *priekšfiltrs*, nevis pilnas precizitātes atbilstību krātuve. Atbilstības pārbaudes laikā avota kods joprojām tiek parsēts, tāpēc strukturālā precizitāte ir tāda pati kā vietējā AST meklēšanā; mazāks ir tikai kandidātu kopums.

## Kad to izmantot

Indeksētais AST režīms ir piemērots, ja:

- Atkārtoti palaižat tos pašus strukturālos vaicājumus vienā un tajā pašā koda bāzē.
- Paraugos tiek meklētas identificējamas formas (izsaukuma nosaukums, klases nosaukums, deklarācijas veids), ko saglabā faktu izgūšanas process.
- Vēlaties samazināt aizturi, salīdzinot ar katra faila atkārtotu parsēšanu.

Ja paraugu atšķirošā pazīme nav faktu kopā (piemēram, sarežģītas ligzdotas izteiksmes bez atpazīstama sākuma), [kešotais AST režīms](https://greph.inline0.dev/lv/docs/indexed/cache) parasti ir piemērotāks, jo tas pilnībā izlaiž parsēšanu un nepaļaujas uz aptuvenu parakstu.

## Izmantošana programmā

```php
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` pieņem tādu pašu `AstSearchOptions` kā vietējā AST meklēšana un atgriež tādas pašas formas `list<AstMatch>`. Vairāku indeksu vai uz manifestiem balstītām darbplūsmām izmantojiet `searchAstIndexedMany(...)` un `searchAstIndexedSet(...)`.