# المعايير

يحتوي المستودع على أداة لقياس الأداء ضمن `bin/` و`benchmarks/`. تقيس كل أنماط البحث على مجموعات بيانات واقعية (WordPress وLaravel) ومجموعات اصطناعية مولّدة، وتلتقط تقارير منظّمة، وتتيح مقارنة سلسلتين من التقارير.

الأداة جزء من المستودع وليست من حزمة Composer: منذ الإصدار 0.2.3، لا تُضمّن `benchmarks/` ونصوص `bin/bench*` البرمجية في الحزمة، لذا شغّلها من نسخة مستنسخة (`git clone https://github.com/inline0/greph && cd greph && composer install`).

تستند الأرقام المنشورة في [README](https://github.com/inline0/greph#performance) إلى عمليات تشغيل GitHub Actions، ولا تُستمد مطلقًا من الأجهزة المحلية. تفيد عمليات التشغيل المحلية في التكرار والتحسين؛ أما عمليات CI فهي المرجع المعتمد.

## مجموعات البيانات

تُنشأ مجموعات البيانات الاصطناعية (`synthetic-1k` و`synthetic-10k` و`synthetic-100k-single`) ضمن `benchmarks/corpora/synthetic/` عند التشغيل الأول. أما مجموعات البيانات الواقعية فغير مضمّنة: ضع نسخة مستنسخة في `benchmarks/corpora/wordpress` أو `benchmarks/corpora/laravel` (تستنسخ عملية CI سير العمل `WordPress/WordPress` باستخدام `--depth=1`). تُتخطى أي مجموعة بيانات يفتقد مجلدها.

## تشغيل معايير الأداء

```bash
# Full benchmark suite, every corpus that is present
./bin/bench

# Specific category (the category names used in benchmarks/suites/)
./bin/bench --category text
./bin/bench --category ast

# Compare against external tools when available
./bin/bench --compare rg,grep
./bin/bench --compare sg

# Choose a corpus
./bin/bench --corpus wordpress
./bin/bench --corpus laravel
./bin/bench --corpus synthetic-1k

# Write the run as JSON
./bin/bench --corpus wordpress --output build/run-1.json

# Measured series: 5 runs after 1 warmup run
./bin/bench-series --repeat 5 --warmup 1 --corpus wordpress --output build/head-series.json

# Aggregate separate runs into one series
./bin/bench-aggregate --output build/head-series.json build/run-*.json
```

تقارن `bin/bench-compare base-series.json head-series.json` بين سلسلتي ملفات (الناتج من `bench-series` أو `bench-aggregate`) وتطبع ملخصًا بصيغة Markdown، وهو مفيد عند تحسين مسار سريع الاستدعاء. يشغّل `bin/bench-ci` سير عمل Benchmark على GitHub Actions عبر `gh` CLI.

## الفئات

ينشر README ثماني مجموعات من النتائج، تقيس كل منها طبقة محددة من المحرك. تضم كل مجموعة فئة واحدة أو أكثر من فئات أداة القياس المعرّفة في `benchmarks/suites/`.

### وضع الفحص: النص

بحث نصي أصلي باستخدام أنماط حرفية وتعبيرات نمطية ومجموعة تجمع بينهما. يُجرى القياس الأساسي المنشور على مجموعة البيانات WordPress ويشمل:

- `function` حرفي
- حرفي غير حساس لحالة الأحرف
- حرفي للكلمة كاملة
- إنشاء تعبير نمطي جديد
- استدعاء مصفوفة التعبيرات النمطية
- بادئة حرفية للتعبير النمطي
- لاحقة حرفية للتعبير النمطي
- سطر كامل حرفي للتعبير النمطي
- دمج التعبيرات النمطية الحرفية

### وضع الفحص: التصفح

اجتياز الملفات فقط، بلا بحث. يقيس تكلفة أداة اجتياز تراعي gitignore وحدها.

### وضع الفحص: النص المتوازي

بحث بسلاسل ثابتة عن `function` باستخدام `1` و`2` و`4` مهام. لا يبدأ تجمع العمال لهذا النمط إلا عند تجاوز `jobs * 4_000` ملفًا (راجع [العمال المتوازيون](https://greph.inline0.dev/ar/docs/advanced/parallel))، وهو عدد يفوق ملفات مجموعة البيانات WordPress؛ لذا تعمل الصفوف الثلاثة المنشورة في عملية واحدة ولا تُظهر زيادة الأداء مع حجم التجمع ([#8](https://github.com/inline0/greph/issues/8)).

### وضع الفحص: AST

بحث AST أصلي باستخدام أنماط تمثيلية:

- `new $CLASS()`
- `array($$$ITEMS)`

### وضع النص المفهرس

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

### استعلامات الملخص المفهرس

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

### AST المفهرس / المخزّن مؤقتًا

بحث عن حقائق AST بعد التهيئة وبحث AST مخزّن مؤقتًا باستخدام الأنماط نفسها في وضع فحص AST.

### تكاليف البناء

تكاليف البناء البارد لفهرس trigram وفهرس حقائق AST وذاكرة AST المؤقتة. تفيد في تحديد النمط الذي ينبغي الإبقاء عليه لأعباء العمل المختلفة.

## قراءة الأرقام المنشورة

ينشر README لقطة من أحدث عملية تشغيل CI لكل قياس أساسي. يستند كل قسم إلى عملية تشغيل محددة على GitHub Actions، ويُذكر فيه مجموعة البيانات والمشغّل وإصدار PHP وعدد مرات القياس والتهيئة. لإعادة إنتاج رقم ما، استخدم المجموعة نفسها محليًا.

تُجمع أعمدة المقارنة (`rg` و`grep` و`sg`) في المهمة نفسها وعلى المشغّل نفسه وباستخدام مجموعة البيانات نفسها. ولا تُستقرأ من معايير خارجية.

## كيفية إضافة معيار أداء

1. أضف تعريفًا لمعيار أداء ضمن `benchmarks/`.
2. أضف سيناريو مطابقًا إلى مجموعة اختبارات الانحدار إن لم يوجد سيناريو مكافئ بعد، للتحقق من السلوك الذي يجري قياسه أيضًا.
3. شغّل `./bin/bench --category <yours>` للتحقق من معيار الأداء الجديد.
4. قارنه بـ `main` باستخدام سير عمل Benchmark، الذي يعمل على طلبات السحب التي تمس `src/` أو `benchmarks/` أو `bin/` وينشر مقارنة بين الإصدار الحالي والأساسي في ملخص التشغيل.
5. حدّث جدول README بعد دمج عملية CI التي تتضمن معيار الأداء الجديد في `main`.

## فلسفة الأداء

لا يحاول Greph التفوق على ripgrep أو grep في عمليات الفحص الباردة. نُفذ Ripgrep باستخدام Rust مع فحص حرفي محسّن يدويًا بتعليمات SIMD، وتُظهر الأرقام المنشورة أن كلًا من `rg` وGNU `grep` أسرع من Greph في كل عمليات فحص النصوص الباردة. تختلف الأهداف:

- أن يكون سريعًا بما يكفي لتبدو التفاعلات ودورات عمل الوكلاء طبيعية.
- الإجابة عن الاستعلامات المتكررة من فهارس مهيأة: البحث بالتعبير النمطي والعدد وقوائم الملفات المفهرسة أسرع من الفحص نفسه للشجرة باستخدام كل من `rg` و`grep`.
- التفوق على `ast-grep` في أعباء عمل AST المفهرسة والمخزّنة مؤقتًا، حيث تتجنب الذاكرة المؤقتة الدافئة في Greph إعادة تحليل الشجرة. أما البحث البارد في AST فتختلف نتائجه: `new $CLASS()` أسرع من `sg`، و`array($$$ITEMS)` أبطأ.
- جعل كل تحسين في الأداء قابلًا للقياس وإعادة الإنتاج.

لا يُعتمد أي ادعاء بشأن الأداء ما لم يدعمه تقرير قياس أداء.