Indeksoitu AST-haku

Indeksoitu AST-haku on AST-haun lämminvälimuistiversio. Ensimmäinen kutsu poimii solmutason faktat (kutsujen nimet, instansioinnit, luokkailmoitukset ja metodien ilmoitukset) levyllä olevaan tallennukseen. Seuraavilla kutsuilla tallennusta käytetään ohittamaan tiedostot, joissa ei selvästikään voi olla rakenteellista osumaa. Tämän jälkeen hakusovitin tarkistaa ehdokkaat uudelleen lähdekoodista.

Faktaindeksi on käytettävissä alikomennolla greph-index ast-index CLI sekä julkisivun metodeilla Greph::buildAstIndex() / Greph::searchAstIndexed(). Se kuuluu myös lämpimiin usean indeksin työnkulkuihin ja manifestiin perustuviin indeksijoukkoihin.

Indeksin rakentaminen

# 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

Faktaindeksi tallennetaan oletusarvoisesti polkuun <root>/.greph-ast-index/.

Onnistuneesta rakentamisesta tulostetaan yksirivinen yhteenveto:

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

Neljä laskuria kertovat edellisen rakennuskerran jälkeen lisättyjen, päivitettyjen, poistettujen ja muuttumattomina säilyneiden tiedostojen määrän.

Indeksin päivittäminen

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

refresh käy indeksoidun juurihakemiston uudelleen läpi, jäsentää muuttuneet tiedostot uudelleen ja kirjoittaa uudelleen vain muuttuneet faktarivit. Tulosteessa käytetään samoja neljää laskuria kuin teksti-indeksissä.

Elinkaariprofiilit toimivat samoin kuin lämpimissä teksti-indekseissä:

• static: älä koskaan tarkista ajantasaisuutta tai muuta automaattisesti
• manual-refresh: ilmoita vanhentuneesta tilasta komennossa stats, mutta älä koskaan päivitä haun aikana
• opportunistic-refresh: päivitä haun aikana vain, jos muuttunut joukko on yhä riittävän pieni
• strict-stale-check: hylkää vanhentuneet haut päivittämisen sijaan

Indeksin kyselyt

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

Metamuuttujien syntaksi on sama kuin alkuperäisessä AST-haussa. Kielioppi kokonaisuudessaan löytyy kohdasta Tilat / AST-haku.

Asetukset

Vararatkaisu puuttuvalle indeksille

Oletusarvoisesti ast-index search antaa virheen, jos pyydetystä sijainnista ei löydy indeksiä. Käytä --fallback scan-valitsinta, jos haluat tehdä sen sijaan alkuperäisen AST-skannauksen. Tämä sopii työkaluille, jotka käyttävät indeksoitua hakua, kun se on saatavilla, mutta joiden pitäisi silti tuottaa tuloksia ennen indeksin rakentamista.

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

Haku useasta indeksistä

Voit hakea useista lämpimistä AST-indekseistä yhdellä komennolla toistamalla --index-dir-valitsimen. Tämä sopii esimerkiksi asetteluihin, joissa WordPress-ytimen lisäksi on lisäosa tai teema.

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

Kun --show-index-origin on käytössä, tulosteen eteen lisätään osuvan lämpimän indeksimerkinnän nimi, jotta näet, mistä juurihakemistosta osuma löytyi.

Manifestiin perustuvat indeksijoukot

Määritä vakaita lämpimiä kokoonpanoja varten manifesti ja anna greph-index set-komennon käsitellä ryhmiteltyjä indeksejä:

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

Joukon alikomennot käyttävät samaa elinkaaren käsittelyä, vanhentuneisuuden tarkistuksia ja suunnittelijan diagnostiikkaa kuin suora ast-index-käyttö.

Suunnittelijan diagnostiikka

--trace-plan näyttää, miten Greph rajasi kyselyä ennen täyden hakusovittimen käynnistymistä. Komennossa ast-index tämä sisältää tavallisesti seuraavat tiedot:

• kuviosta poimittu karkea faktatunniste
• haettujen lämpimien indeksien määrä
• faktasuodattimen hylkäämien tiedostojen määrä
• täsmällistä rakenteellista tarkistusta varten uudelleen jäsennettyjen ehdokastiedostojen määrä

Indeksin sisältö

AST-faktojen poimija tallentaa jokaisesta indeksoidusta tiedostosta rivin kutakin "kiinnostavaa" solmua kohti. Faktatyyppeihin kuuluvat rakenteet, joita AST-kuvioilla etsitään yleisimmin:

• Funktio- ja metodikutsut (kutsutun nimen mukaan)
• Luokkien instansioinnit (luokan nimen mukaan)
• Luokka-, rajapinta-, trait- ja enum-määritykset (nimen mukaan)
• Funktiomääritykset (nimen mukaan)
• Metodimääritykset (nimen ja näkyvyyden mukaan)
• Use-lauseet

Kun kysely saapuu, Greph\Ast\AstFactQuery muuntaa hakukuvion karkeaksi faktatunnisteeksi (esimerkiksi "sisältää oltava minkä tahansa luokan new") ja hakee faktatallennuksesta tunnisteen perusteella. Tämän jälkeen jäljelle jääneet tiedostot jäsennetään uudelleen ja sovitetaan koko kuvioon.

Faktaindeksi on siis esisuodatin, ei täsmällisiä osumia tallentava tietovarasto. Osumien tarkistusvaihe jäsentää lähdekoodin edelleen, joten rakenteellinen oikeellisuus vastaa alkuperäistä AST-hakua; ainoastaan ehdokkaiden joukko on pienempi.

Milloin sitä kannattaa käyttää

Indeksoitu AST-tila sopii, kun:

• teet toistuvasti samoja rakenteellisia kyselyjä samalle koodikannalle.
• kuviot kohdistuvat tunnistettaviin muotoihin (kutsun nimi, luokan nimi tai määrityksen tyyppi), jotka faktaindeksi tallentaa.
• haluat vähentää viivettä kaikkien tiedostojen uudelleenjäsentämiseen verrattuna.

Jos kuvion erottava piirre ei kuulu faktajoukkoon (esimerkiksi monimutkaiset sisäkkäiset lausekkeet, joiden alkua ei voi tunnistaa), välimuistissa oleva AST-tila sopii yleensä paremmin. Se ohittaa jäsennysvaiheen kokonaan eikä ole karkean tunnisteen varassa.

Käyttö ohjelmallisesti

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 hyväksyy samat AstSearchOptions-arvot kuin alkuperäinen AST-haku ja palauttaa samassa list<AstMatch>-muodossa. Usean indeksin tai manifestiin perustuvissa työnkuluissa käytä komentoja searchAstIndexedMany(...) ja searchAstIndexedSet(...).