بحث AST المفهرس

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

يتوفر فهرس الحقائق ضمن الأمر الفرعي greph-index ast-index CLI وطرائق الواجهة Greph::buildAstIndex() / Greph::searchAstIndexed(). كما يشارك في مسارات العمل المُحمّاة متعددة الفهارس والمجموعات المدعومة بالبيانات الوصفية.

إنشاء الفهرس

# 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

يُخزّن فهرس الحقائق افتراضيًا في <root>/.greph-ast-index/.

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

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

تتتبّع العدادات الأربعة الملفات المضافة والمحدّثة والمحذوفة وغير المتغيرة منذ آخر إنشاء للفهرس.

تحديث الفهرس

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

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

تعمل ملفات تعريف دورة الحياة بالطريقة نفسها المستخدمة مع فهارس النصوص المُحمّاة:

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

الاستعلام في الفهرس

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

صياغة المتغيرات الوصفية مطابقة لصياغتها في بحث AST الأصلي. راجع الأوضاع / بحث AST للاطلاع على القواعد كاملة.

الخيارات

الرجوع عند غياب الفهرس

افتراضيًا، يُصدر ast-index search خطأً عند عدم وجود فهرس في الموقع المطلوب. مرّر --fallback scan للرجوع إلى فحص AST أصلي. وهذا الخيار مناسب للأدوات التي تريد استخدام البحث المفهرس عند توفره، مع استمرار عرض النتائج إذا لم يُنشأ الفهرس بعد.

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

البحث عبر فهارس متعددة

يمكنك البحث في عدة فهارس AST مُحمّاة بأمر واحد بتكرار --index-dir. وهذا مفيد لتخطيطات مثل WordPress مع إضافة مكوّن إضافي أو سمة.

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

عند تفعيل --show-index-origin، تُسبق النتائج باسم مدخل الفهرس المُحمّى المطابق، لتتمكن من معرفة الجذر الذي أظهر النتيجة.

مجموعات الفهارس المدعومة بالبيانات الوصفية

لإعدادات مُحمّاة مستقرة، عرّف ملفًا للبيانات الوصفية ودع greph-index set يعمل على الفهارس المجمّعة:

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

تستخدم الأوامر الفرعية للمجموعة معالجة دورة الحياة وفحوصات التقادم وتشخيصات المخطِّط نفسها المستخدمة عند تشغيل ast-index مباشرةً.

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

يعرض --trace-plan كيفية تضييق Greph نطاق الاستعلام قبل تشغيل المطابق الكامل. وبالنسبة إلى ast-index، يشمل ذلك عادةً:

• توقيع الحقائق التقريبي المستخرج من النمط
• عدد الفهارس المُحمّاة التي جرى البحث فيها
• عدد الملفات التي استبعدها مرشح الحقائق
• عدد الملفات المرشحة التي أُعيد تحليلها للتحقق البنيوي الدقيق

ما الذي يخزنه الفهرس

يسجل مستخرج حقائق AST صفًا لكل عقدة «مهمة» في كل ملف مفهرس. وتشمل أنواع الحقائق البنى التي تستهدفها أنماط AST عادةً:

• استدعاءات الدوال والأساليب (حسب الاسم المستدعى)
• إنشاء كائنات الفئات (حسب اسم الفئة)
• إعلانات الفئات والواجهات والسمات والتعدادات (حسب الاسم)
• إعلانات الدوال (حسب الاسم)
• إعلانات الأساليب (حسب الاسم ومستوى الظهور)
• عبارات الاستيراد

عند وصول استعلام، يحوّل Greph\Ast\AstFactQuery نمط البحث إلى توقيع حقائق تقريبي (مثلًا: «يجب أن يتضمن new من أي فئة») ويبحث في مخزن الحقائق عن الملفات المطابقة. ثم يعيد تحليل الملفات التي تجتاز المطابقة ويقارنها بالنمط الكامل.

هذا يعني أن فهرس الحقائق مرشح أولي، وليس مخزنًا للمطابقات كاملة الدقة. تظل خطوة المطابقة تحلل المصدر، لذا تبقى الدقة البنيوية مطابقة لبحث AST الأصلي؛ والاختلاف الوحيد هو صغر مجموعة المرشحين.

متى تستخدمه

يُعد وضع AST المفهرس مناسبًا عندما:

• تُجري الاستعلامات البنيوية نفسها على قاعدة الأكواد نفسها مرارًا.
• تستهدف الأنماط أشكالًا يمكن تحديدها (اسم الاستدعاء أو اسم الفئة أو نوع الإعلان) يخزنها مستخرج الحقائق.
• تريد تقليل زمن الاستجابة مقارنةً بإعادة تحليل كل ملف.

بالنسبة إلى الأنماط التي لا تظهر ميزتها المميزة في مجموعة الحقائق (مثل التعبيرات المتداخلة المعقدة التي لا رأس معروفًا لها)، يكون وضع AST المخزّن مؤقتًا عادةً أنسب، لأنه يتخطى خطوة التحليل بالكامل دون الاعتماد على توقيع تقريبي.

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

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 وسيطات AstSearchOptions نفسها التي يقبلها بحث AST الأصلي، ويعيد بنية list<AstMatch> نفسها. لمسارات العمل متعددة الفهارس أو المدعومة بالبيانات الوصفية، استخدم searchAstIndexedMany(...) وsearchAstIndexedSet(...).