بحث AST المخزّن مؤقتًا

بحث AST المخزّن مؤقتًا هو وضع مكمّل للذاكرة المؤقتة المُحمّاة من فهرس الحقائق. فبدلًا من تخزين الحقائق المستخرجة وإعادة تحليل الملفات المطابقة، تخزن الذاكرة المؤقتة الأشجار المحللة بعد تسلسلها على القرص. وتزيل الاستعلامات اللاحقة تسلسل هذه الأشجار وتشغّل المطابق عليها مباشرةً، متخطيةً مسار PHP-Parser بالكامل.

تتوفر الذاكرة المؤقتة ضمن الأمر الفرعي greph-index ast-cache CLI وطرائق الواجهة Greph::buildAstCache() / Greph::searchAstCached(). كما تدعم البحث متعدد الفهارس والبحث في المجموعات المدعومة بالبيانات الوصفية.

إنشاء الذاكرة المؤقتة

# 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

تُخزّن الذاكرة المؤقتة افتراضيًا في <root>/.greph-ast-cache/. ويكون إنشاؤها عادةً الأبطأ بين أوضاع الفهرسة الثلاثة، لأن كل ملف يجب تحليله مرة واحدة.

يعرض الإنشاء الناجح ملخصًا في سطر واحد:

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

عادةً ما يكون عدد الأشجار المخزنة مؤقتًا أقل قليلًا من عدد الملفات، لأن الملفات التي يتعذر تحليلها (ويُتخطاها بصمت) لا تُنشئ مدخلًا في الذاكرة المؤقتة. مرّر --strict-parse في أمر البحث لإظهار أخطاء التحليل بدلًا من ذلك.

تحديث الذاكرة المؤقتة

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

يعيد refresh اجتياز الجذر المفهرس، ويعيد تحليل الملفات المتغيرة، ويعيد كتابة الأشجار المخزنة مؤقتًا التي تغيّرت فقط.

تطابق ملفات تعريف دورة الحياة الأوضاع المُحمّاة الأخرى:

• static: لا يتحقق من حداثة البيانات أو يغيّرها تلقائيًا مطلقًا
• manual-refresh: يعرض حالة التقادم في stats، لكنه لا يحدّث أثناء البحث مطلقًا
• opportunistic-refresh: يحدّث أثناء البحث فقط عندما تكون مجموعة الملفات المتغيرة دون الحدود المضبوطة
• strict-stale-check: يرفض عمليات البحث عن البيانات المتقادمة بدلًا من تحديثها

الاستعلام في الذاكرة المؤقتة

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

مجموعة الخيارات مطابقة لمجموعة ast-index search، بما في ذلك --fallback scan للتعامل مع غياب الذاكرة المؤقتة.

البحث في ذاكرة مؤقتة متعددة الفهارس

كرّر --index-dir للبحث في عدة ذاكرات مؤقتة مُحمّاة باستدعاء واحد:

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

مجموعات الذاكرة المؤقتة المدعومة بالبيانات الوصفية

إذا كنت تحتفظ بالفعل بمجموعات مُحمّاة مسماة، فيمكن للملف نفسه أن يوجّه بحث AST المخزّن مؤقتًا:

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

تشخيصات المخطِّط

يعرض --trace-plan قرارات مخطِّط AST المخزّن مؤقتًا إلى stderr، ومنها:

• أي الذاكرات المؤقتة المُحمّاة جرى البحث فيها
• ما إذا كان منطق تحديث البيانات المتقادمة قد عمل
• أعداد الملفات المرشحة بعد تضييق نطاق الملفات
• عدد الأشجار المخزنة مؤقتًا التي أُزيل تسلسلها للمطابقة البنيوية الدقيقة

الذاكرة المؤقتة مقابل فهرس الحقائق

يسرّع كلا الوضعين بحث AST، لكن كلًا منهما محسّن لنمط مختلف من العمل.

عمليًا، يوفر فهرس الحقائق أسرع استعلام بارد، بينما توفر ذاكرة التخزين المؤقت أسرع استعلام دافئ. استخدم ما يناسب عبء العمل لديك، أو أنشئ كليهما ودع أدواتك تختار.

الاستخدام البرمجي

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),
);

يقبل searchAstCached قيم AstSearchOptions نفسها التي يقبلها بحث AST الأصلي، ويعيد بنية list<AstMatch> نفسها. والفرق الوحيد هو تجاوز مسار المحلل للملفات الموجودة بالفعل في ذاكرة التخزين المؤقت. لتدفقات العمل متعددة الفهارس أو المدعومة ببيان، استخدم searchAstCachedMany(...) وsearchAstCachedSet(...).

متى تستخدمه

يكون وضع AST المخزّن مؤقتًا هو الخيار المناسب عندما:

• تُجري استعلامات بنيوية متكررة على قاعدة الشيفرة نفسها.
• كان عنق الزجاجة في مرات التشغيل السابقة هو PHP-Parser (ويظهر في ملفات الأداء على هيئة وقت مستغرق في المحلل المعجمي والمحلل).
• يمكنك تخصيص مساحة القرص اللازمة لمخزن الشجرة المتسلسلة.

إذا كانت استعلاماتك تصيب عادةً جزءًا صغيرًا من قاعدة الشيفرة وتتركز المطابقات حول أسماء استدعاءات أو أصناف يسهل تمييزها، فعادةً ما يكون فهرس الحقائق أنسب. أما إذا شملت استعلاماتك نطاقًا واسعًا من قاعدة الشيفرة وكان بإمكانك تحمل تكلفة التحليل لمرة واحدة، فذاكرة التخزين المؤقت هي الأفضل.