# توافق sg

`vendor/bin/sg` غلاف توافق بأسلوب ast-grep. يقبل أعلام `ast-grep` الأكثر استخدامًا، ويعيد استخدام المحرك `Greph\Ast\AstSearcher` نفسه الذي يستخدمه `vendor/bin/greph -p`. أُعيد إنتاج نطاق التوافق المتحقق منه استنادًا إلى عمليات فحص للملف التنفيذي الأصلي `sg`، وهو متاح في [متقدم / مصفوفة الميزات](https://greph.inline0.dev/ar/docs/advanced/feature-matrix).

## متى تستخدمه

استخدم الغلاف عندما:

- لديك أداة أو وكيل أو نص برمجي موجود يستدعي `sg` بالفعل.
- تريد بديلًا جاهزًا للاستخدام في بيئات لا يمكنك فيها تثبيت `ast-grep` نفسه.
- تريد سهولة استخدام ast-grep مع تثبيت Composer فقط.

استخدم `vendor/bin/greph -p` الأصلي عندما:

- تكتب تعليمات برمجية جديدة ولا تحتاج إلى صيغة ast-grep CLI.
- تريد مجموعة الأعلام نفسها المستخدمة في وضع النص (فالملف التنفيذي الأصلي يوحّد الوضعين).

## الاستخدام

```bash
sg run --pattern PATTERN [options] [path...]
sg scan -p PATTERN [options] [path...]
sg rewrite -p PATTERN -r TEMPLATE [options] [path...]
```

`run` هو الأمر الأساسي المعتمد في ast-grep. أما `scan` و`rewrite` فهما اسمان مستعاران خاصان بالغلاف يعكسان الاستخدام الشائع. يعمل الاستدعاء المجرد كبحث لمرة واحدة:

```bash
./vendor/bin/sg --pattern 'array($$$ITEMS)' src
```

## الأنماط

قواعد الأنماط مطابقة لقواعد بحث AST الأصلي. راجع [الأوضاع / بحث AST](https://greph.inline0.dev/ar/docs/modes/ast) للاطلاع على المرجع الكامل.

```bash
./vendor/bin/sg run --pattern 'array($$$ITEMS)' src
./vendor/bin/sg run --pattern '$obj->$method($$$ARGS)' src
./vendor/bin/sg run --pattern 'new $CLASS()' src
```

## عمليات إعادة الكتابة

يدعم الغلاف سير العمل نفسه لإعادة الكتابة الجافة / التفاعلية / الفعلية الذي تدعمه إعادة الكتابة الأصلية، مع أسماء أعلام ast-grep:

```bash
# Preview only (default)
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' src

# Apply without confirmation
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' --update-all src

# Confirm each match
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' --interactive src

# Wrapper-only aliases
./vendor/bin/sg rewrite -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src
./vendor/bin/sg rewrite -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --interactive src
```

## مخرجات JSON

يُصدر `--json` مخرجات JSON بهيئة ast-grep. وتتوفر ثلاثة أنماط:

```bash
./vendor/bin/sg run --json --pattern 'dispatch($EVENT)' src
./vendor/bin/sg run --json=stream --pattern 'dispatch($EVENT)' src
./vendor/bin/sg run --json=compact --pattern 'dispatch($EVENT)' src
```

| النمط | البنية |
|---|---|
| `--json` (الافتراضي `pretty`) | مصفوفة JSON واحدة منسّقة للقراءة |
| `--json=stream` | مطابقة واحدة في كل سطر، بصيغة JSON مفصولة بأسطر جديدة |
| `--json=compact` | مصفوفة JSON واحدة موجزة |

## نطاق التوافق المتحقق منه

الرايات التالية مُتحقق منها باستخدام الملف التنفيذي الأصلي `sg` في [مصفوفة الميزات](https://greph.inline0.dev/ar/docs/advanced/feature-matrix). عندما يكون للراية اسمان (`-p` و`--pattern`، `--glob` و`--globs`)، يستخدم الاختبار أحدهما ويحلل الغلاف كليهما باعتبارهما الخيار نفسه.

### أعلام الأنماط

- `--pattern PATTERN` (على المستوى الأعلى وداخل `run`)
- `-p PATTERN` (اسم مستعار)
- `--rewrite TEMPLATE`
- `-r TEMPLATE`
- `--lang NAME`، `-l NAME`

### أعلام المطابقة

- `--files-with-matches`
- `--json` (`pretty`, `stream`, `compact`)
- `--update-all`, `-U`

### أعلام التنقل

- `--no-ignore hidden` (صيغة مدمجة)
- `--glob GLOB`، `--globs GLOB`

### أعلام العمال

- `-j N`, `--threads N`

### خيارات مقبولة دون اختبار

يقبل الغلاف أيضًا هذه الأعلام، لكن لم يختبرها أي اختبار لمصفوفة الميزات بعد:

- `--no-ignore` بمفرده، أو مع قيمة غير `hidden`
- `--type NAME`، `--type-not NAME`

### إضافات خاصة بالغلاف

يوفر الغلاف بعض الأدوات المساعدة غير المتاحة في ast-grep نفسه:

- الاسمان المستعاران `scan` و`rewrite` لـ`run`
- العَلَم `--hidden` (يضم ast-grep هذه الوظيفة ضمن `--no-ignore hidden`)
- اسم مستعار لمعاينة إعادة الكتابة: `--dry-run`
- سير عمل لتأكيد إعادة الكتابة عبر `--interactive`

## القيود

يغطي غلاف `sg` الخاص بـGreph نطاق البحث البنيوي وإعادة الكتابة الذي تستخدمه معظم الأدوات والوكلاء. ولا يوفّر حاليًا ميزات ast-grep التالية:

- ملفات القواعد YAML (`--rule`، `--config`)
- الفحص متعدد اللغات بما يتجاوز PHP
- المحوّلات غير القائمة على الأنماط (`--debug-query`، `--inspect`)
- تكامل LSP

إذا واجهت عَلَمًا غير مدعوم، فأرسل بلاغًا يتضمن الاختبار الذي أجريته على `sg` الأصلي والمخرجات المتوقعة.

## تكافؤ السلوك

يسعى الغلاف إلى تكافؤ السلوك لا إلى التطابق على مستوى البايتات. المخرجات متكافئة دلاليًا، لكن قد تختلف في تفاصيل شكلية. تتحقق الاختبارات المستخدمة في [مصفوفة الميزات](https://greph.inline0.dev/ar/docs/advanced/feature-matrix) من تكافؤ الحقول ذات الصلة بالتحليل (مسار الملف، ورقم السطر، والأكواد الملتقطة، والالتقاطات، وبنية JSON)، لا من تدفق البايتات.