# مصفوفة الميزات

مصفوفة الميزات تقرير مُنشأ يسجل، لكل خيار وسلوك مدعوم، ما إذا كانت الأداة الأصلية وغلاف Greph ينتجان مخرجات متكافئة. وهي المرجع المعتمد للإجابة عن أسئلة مثل «هل يدعم Greph هذا؟».

تُعاد توليد المصفوفة من اختبارات أوامر فعلية على مساحة عمل اختبارية ثابتة. توجد الأدلة الخام في [`FEATURE_MATRIX.json`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.json)، والجدول المعروض في [`FEATURE_MATRIX.md`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.md).

## دليل الحالات

| الحالة | المعنى |
|---|---|
| `Pass` | نُفذ الاختبار الاستقصائي وطابق السلوك المتوقع |
| `Fail` | نُفذ الاختبار الاستقصائي لكنه لم يحقق السلوك المتوقع |
| `Unavailable` | الأمر المزوّد غير متاح في هذه البيئة |

## الأقسام

تتألف المصفوفة من ستة أقسام:

1. **نطاق توافق rg**: يُجرى كل اختبار استقصائي على كل من الملف التنفيذي الأصلي `rg` و`bin/rg`. يجب أن يحققا `Pass` معًا ليُصنّف الصف على أنه مدعوم.
2. **نطاق توافق sg**: يُجرى كل اختبار استقصائي على كل من الملف التنفيذي الأصلي `sg` و`bin/sg`. يجب أن يحققا `Pass` معًا ليُصنّف الصف على أنه مدعوم.
3. **نطاق خاص بغلاف sg**: اختبارات تستهدف `bin/sg` فقط، أي الميزات الإضافية التي يتيحها الغلاف ولا تتوفر في ast-grep نفسه.
4. **نطاق greph الأصلي**: اختبارات تستدعي `bin/greph` مباشرة. لا توجد أداة أصلية للمقارنة معها؛ وتتحقق الاختبارات من السلوك المتوقع في مساحة العمل الاختبارية.
5. **نطاق greph المفهرس**: اختبارات تستخدم `bin/greph-index` للبناء والتحديث والبحث النصي بعد التهيئة.
6. **نطاق مكتبة AST المفهرسة**: اختبارات تستدعي PHP API ‏(`Greph::buildAstIndex()` و`Greph::searchAstIndexed()` و`Greph::buildAstCache()` و`Greph::searchAstCached()`) وتتحقق من البناء والبحث والتحديث.

## إعادة توليد المصفوفة

```bash
php bin/feature-matrix
```

شغّلها من نسخة مستنسخة من المستودع باستخدام `rg` و`sg` على `PATH`؛ فـ `bin/feature-matrix` ليست جزءًا من حزمة Composer. تبني مساحة العمل الاختبارية، وتجري اختبارات التوافق على الملف التنفيذي الأصلي (إن كان مثبتًا) وعلى غلاف Greph، وتسجل النتائج المنظّمة، وتكتب كلًا من `FEATURE_MATRIX.json` و`FEATURE_MATRIX.md`. مرّر `--stdout` لطباعة Markdown دون كتابة أي من الملفين.

تُعاد توليد الملفات المودعة يدويًا؛ ولا يعيد CI توليدها. تتضمن مجموعة PHPUnit التي يشغّلها CI اختبارًا ينشئ المصفوفة مع اعتبار الأدوات الأصلية غير متاحة، ويتحقق من بنية التقرير، لذا لا يؤدي إخفاق اختبار استقصائي واحد إلى إخفاق CI. أعد توليد المصفوفة وراجع الفروقات قبل الإصدار.

## محتوى المصفوفة والوثائق

يصف مرجع CLI وصفحتا [التوافق / rg](https://greph.inline0.dev/ar/docs/compatibility/rg) و[التوافق / sg](https://greph.inline0.dev/ar/docs/compatibility/sg) النطاق *المقصود*. أما مصفوفة الميزات فتسجل النطاق *الذي جرى التحقق منه*، مع وسيطات الاختبار الدقيقة بجانب كل صف.

إذا وُثّق شيء ولم يظهر في المصفوفة، فالوثائق قديمة. وإذا ظهر في المصفوفة ولم يُوثّق، فيجب استكمال الوثائق. ينبغي أن يتطابق الاثنان.

## أمثلة على الصفوف

### توافق rg (مقتطف)

| الميزة | rg | bin/rg | ملاحظات |
|---|---|---|---|
| بحث بسلاسل ثابتة | نجاح | نجاح | الاختبار: `-F needle single.txt` |
| بحث بسلاسل ثابتة غير حساس لحالة الأحرف | نجاح | نجاح | الاختبار: `-F -i needle single.txt` |
| بحث عن كلمات كاملة | نجاح | نجاح | الاختبار: `-F -w needle words.txt` |
| عامل تصفية Glob | نجاح | نجاح | الاختبار: `--glob *.php function .` |
| الملفات المخفية | نجاح | نجاح | الاختبار: `--hidden -F secret .` |
| مخرجات JSON منظّمة | نجاح | نجاح | الاختبار: `--json -F needle single.txt` باستخدام دلالات أحداث ripgrep JSON |

### توافق sg (مقتطف)

| الميزة | sg | bin/sg | ملاحظات |
|---|---|---|---|
| البحث عن نمط باستخدام `run --pattern` | نجاح | نجاح | الاختبار: `run --pattern array($$$ITEMS) src/App.php` |
| إعادة الكتابة عبر `run --rewrite` | نجاح | نجاح | الاختبار: `run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] src/App.php` |
| مخرجات تدفق JSON منظّمة | نجاح | نجاح | الاختبار: `run --json=stream --pattern dispatch($EVENT) src/App.php` |
| إعادة كتابة الكل وتحديثه | نجاح | نجاح | الاختبار: `run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] --update-all src/App.php` |

للاطلاع على الجدول الكامل، راجع [`FEATURE_MATRIX.md`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.md).

## لماذا نعتمد الاختبارات الاستقصائية

سرعان ما تصبح جداول التوافق التي تُصان يدويًا قديمة. تقوم فكرة الأغلفة على «استخدامها بدلًا من `rg` أو `sg` كما اعتدت، وستواصل العمل»، والسبيل الوحيد للوفاء بهذا الوعد هو تشغيل الأداة الأصلية والغلاف جنبًا إلى جنب ومقارنة النتائج. وهذا بالضبط ما يفعله مشغّل الاختبارات كلما أُعيد توليد المصفوفة.