توافق sg

vendor/bin/sg غلاف توافق بأسلوب ast-grep. يقبل أعلام ast-grep الأكثر استخدامًا، ويعيد استخدام المحرك Greph\Ast\AstSearcher نفسه الذي يستخدمه vendor/bin/greph -p. أُعيد إنتاج نطاق التوافق المتحقق منه استنادًا إلى عمليات فحص للملف التنفيذي الأصلي sg، وهو متاح في متقدم / مصفوفة الميزات.

متى تستخدمه

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

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

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

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

الاستخدام

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 فهما اسمان مستعاران خاصان بالغلاف يعكسان الاستخدام الشائع. يعمل الاستدعاء المجرد كبحث لمرة واحدة:

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

الأنماط

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

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

# 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. وتتوفر ثلاثة أنماط:

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

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

الرايات التالية مُتحقق منها باستخدام الملف التنفيذي الأصلي sg في مصفوفة الميزات. عندما يكون للراية اسمان (-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 الأصلي والمخرجات المتوقعة.

تكافؤ السلوك

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