Pencarian AST Terindeks

Pencarian AST terindeks adalah versi cache hangat dari Pencarian AST. Panggilan pertama mengekstrak fakta pada tingkat node (nama panggilan, instansiasi, deklarasi kelas, deklarasi metode) ke penyimpanan di disk; panggilan berikutnya menggunakan penyimpanan tersebut untuk melewati file yang jelas tidak mungkin berisi kecocokan struktural. Matcher kemudian memverifikasi ulang kandidat terhadap sumbernya.

Indeks fakta tersedia melalui subperintah greph-index ast-index CLI dan metode facade Greph::buildAstIndex() / Greph::searchAstIndexed(). Indeks ini juga digunakan dalam alur kerja multi-indeks yang telah dimuat dan set berbasis manifes.

Membangun indeks

# 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

Secara default, indeks fakta disimpan di <root>/.greph-ast-index/.

Build yang berhasil mencetak ringkasan satu baris:

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

Keempat penghitung mencatat jumlah file yang ditambahkan, diperbarui, dihapus, dan tidak berubah sejak build terakhir.

Menyegarkan indeks

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

refresh menelusuri ulang akar yang diindeks, mem-parsing ulang file yang berubah, dan hanya menulis ulang baris fakta yang berubah.

Profil siklus hidup berfungsi sama seperti pada indeks teks yang telah dimuat:

• static: tidak pernah memeriksa kesegaran atau mengubah secara otomatis
• manual-refresh: melaporkan status usang di stats, tetapi tidak pernah menyegarkan selama pencarian
• opportunistic-refresh: menyegarkan saat pencarian hanya jika kumpulan perubahan masih cukup kecil
• strict-stale-check: menolak pencarian dengan indeks usang alih-alih menyegarkannya

Membuat kueri pada indeks

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

Sintaks metavariabel sama persis dengan pencarian AST native. Lihat Mode / Pencarian AST untuk tata bahasa lengkap.

Opsi

Cadangan saat indeks tidak tersedia

Secara default, ast-index search menampilkan kesalahan jika tidak ada indeks di lokasi yang diminta. Berikan --fallback scan untuk beralih ke pemindaian AST native. Pengaturan ini cocok untuk alat yang ingin menggunakan pencarian terindeks jika tersedia, tetapi tetap menghasilkan hasil saat indeks belum dibuat.

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

Pencarian multi-indeks

Anda dapat mencari di beberapa indeks AST yang telah dimuat dengan satu perintah dengan mengulangi --index-dir. Ini berguna untuk tata letak seperti WordPress inti beserta plugin atau tema.

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

Saat --show-index-origin diaktifkan, output diawali dengan nama entri indeks yang telah dimuat dan cocok, sehingga Anda dapat mengetahui akar mana yang menghasilkan hasil.

Kumpulan indeks berbasis manifes

Untuk konfigurasi stabil dengan indeks yang telah dimuat, tentukan manifes dan biarkan greph-index set menggunakan indeks yang dikelompokkan:

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

Subperintah set menggunakan penanganan siklus hidup, pemeriksaan data usang, dan diagnostik perencana yang sama seperti penggunaan langsung ast-index.

Diagnostik perencana

--trace-plan menunjukkan cara Greph mempersempit kueri sebelum matcher lengkap dijalankan. Untuk ast-index, biasanya informasi ini mencakup:

• tanda tangan fakta kasar yang diekstrak dari pola
• jumlah indeks yang telah dimuat yang dicari
• jumlah file yang ditolak oleh filter fakta
• jumlah file kandidat yang di-parsing ulang untuk verifikasi struktural yang tepat

Data yang disimpan indeks

Untuk setiap file yang diindeks, ekstraktor fakta AST mencatat satu baris untuk setiap node yang "menarik". Kumpulan jenis fakta mencakup konstruksi yang paling sering menjadi sasaran pola AST:

• Pemanggilan fungsi dan metode (berdasarkan nama yang dipanggil)
• Instansiasi kelas (berdasarkan nama kelas)
• Deklarasi kelas, antarmuka, trait, dan enum (berdasarkan nama)
• Deklarasi fungsi (berdasarkan nama)
• Deklarasi metode (berdasarkan nama dan visibilitas)
• Pernyataan use

Saat kueri diterima, Greph\Ast\AstFactQuery menerjemahkan pola pencarian menjadi tanda tangan fakta kasar (misalnya, "harus berisi new dari kelas apa pun") lalu mengiriskannya dengan penyimpanan fakta. File yang lolos irisan kemudian di-parsing ulang dan dicocokkan dengan pola lengkap.

Artinya, indeks fakta adalah pra-filter, bukan penyimpanan kecocokan dengan fidelitas penuh. Tahap pencocokan tetap mem-parsing sumber, sehingga ketepatan strukturalnya sama dengan pencarian AST native; hanya kumpulan kandidatnya yang lebih kecil.

Kapan menggunakannya

Mode AST terindeks cocok digunakan ketika:

• Anda menjalankan kueri struktural yang sama berulang kali pada basis kode yang sama.
• Pola menargetkan bentuk yang dapat dikenali (nama panggilan, nama kelas, jenis deklarasi) dan disimpan oleh ekstraktor fakta.
• Anda menginginkan latensi lebih rendah daripada mem-parsing ulang setiap file.

Untuk pola yang ciri pembedaannya tidak ada dalam kumpulan fakta (misalnya, ekspresi bersarang kompleks tanpa bagian awal yang dapat dikenali), mode AST yang di-cache biasanya lebih cocok karena melewati tahap parsing sepenuhnya tanpa bergantung pada tanda tangan kasar.

Penggunaan secara terprogram

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 menerima AstSearchOptions yang sama dengan pencarian AST native dan mengembalikan bentuk list<AstMatch> yang sama. Untuk alur multi-indeks atau berbasis manifes, gunakan searchAstIndexedMany(...) dan searchAstIndexedSet(...).