تخيل أن لديك مشروع Python كبير، وتشك في وجود دوال مكررة تؤدي نفس المهمة لكن بأسماء مختلفة أو ترتيب أسطر مختلف. الأدوات التقليدية مثل PMD تعجز عن اكتشاف هذا التكرار غير الحرفي. هنا يأتي دور Slopo، أداة CLI مفتوحة المصدر تستخدم نماذج التضمين (Embedding Models) لاكتشاف التشابه الدلالي بين أجزاء الكود. في هذا الدليل العملي، ستتعلم كيفية تثبيت Slopo وتشغيله على مشروعك، مع مثال كامل من البداية إلى النتيجة، وأخطاء شائعة وحلولها، وكيفية تخصيص العتبة والنموذج.

ما هو Slopo؟

Slopo هي أداة سطر أوامر (CLI) مكتوبة بلغة Python، تهدف إلى اكتشاف تكرار الكود غير الحرفي (non-exact code duplication) باستخدام نماذج التضمين. بدلاً من مقارنة النص حرفياً، تحول الأداة الكود إلى تمثيلات رقمية (embeddings) ثم تحسب التشابه بينها. هذا يسمح باكتشاف أجزاء الكود التي تؤدي نفس الوظيفة حتى لو اختلفت في التسميات أو الترتيب.

المتطلبات الأساسية

• Python 3.8 أو أحدث
• pip (مدير حزم Python)
• اتصال بالإنترنت لتحميل النماذج (مرة واحدة)
• نظام تشغيل: Linux, macOS, أو Windows (مع WSL)

طريقة التركيب (خطوة بخطوة)

ملاحظة: README غير واضح بالكامل، لذا الخطوات تقريبية بناءً على بنية المشروع. تأكد من تثبيت Python 3.8+.

1. تحقق من تثبيت Python: python --version
2. قم بتثبيت Slopo عبر pip: pip install git+https://github.com/rafal-qa/slopo.git (إذا لم يكن متاحاً على PyPI، استخدم هذا الأمر)
3. تحقق من التثبيت: slopo --help

ملف .env والإعدادات

قد تحتاج إلى إنشاء ملف .env في مجلد المشروع لتحديد متغيرات البيئة. المتغيرات المدعومة حالياً (بناءً على README):

• SLOPO_THRESHOLD: نسبة التشابه الدنيا (افتراضي 0.8). مثال: SLOPO_THRESHOLD=0.7
• SLOPO_MODEL: اسم نموذج التضمين (افتراضي all-MiniLM-L6-v2). مثال: SLOPO_MODEL=all-mpnet-base-v2
• SLOPO_LANGUAGE: لغة الكود (افتراضي python). مثال: SLOPO_LANGUAGE=python

ملاحظة: هذه المتغيرات قد تختلف حسب إصدار Slopo. راجع الوثائق الرسمية للتأكد.

مثال عملي: اكتشاف تكرار في مشروع إدارة مخزون

لنفترض أن لديك مشروع إدارة مخزون بسيط يحتوي على ملفين:

inventory.py

def calculate_tax(price, rate):
    return price * rate

def apply_discount(price, discount):
    return price - (price * discount)

utils.py

def compute_tax(price, rate):
    return price * rate

def apply_discount_v2(price, discount):
    return price - (price * discount)

لاحظ أن calculate_tax و compute_tax متطابقتان وظيفياً لكن بأسماء مختلفة. كذلك apply_discount و apply_discount_v2. شغّل Slopo على المجلد:

slopo scan --threshold 0.7 /path/to/project

النتائج المتوقعة:

File: inventory.py, Lines: 1-2, Similarity: 1.0 with utils.py Lines: 1-2
File: inventory.py, Lines: 4-5, Similarity: 1.0 with utils.py Lines: 4-5

هذا يعني أن Slopo اكتشف التكرار غير الحرفي بنجاح.

تخصيص Slopo لمشاريع Python: ضبط العتبة والنموذج

يمكنك ضبط عتبة التشابه لتقليل النتائج الإيجابية الخاطئة. على سبيل المثال، إذا كنت تريد فقط التكرار العالي جداً، استخدم --threshold 0.9. إذا كنت تريد اكتشاف تكرارات أقل وضوحاً، استخدم --threshold 0.5. يمكنك أيضاً تغيير نموذج التضمين عبر متغير البيئة SLOPO_MODEL. النماذج الأكبر مثل all-mpnet-base-v2 تعطي دقة أعلى لكنها أبطأ.

الأخطاء الشائعة وحلولها

الأسئلة الشائعة

كيف أفسر نتائج التشابه؟

النتائج تظهر أزواجاً من أجزاء الكود مع نسبة تشابه (0-1). كلما اقتربت من 1، زاد التشابه. راجع الأجزاء المتشابهة وقرر ما إذا كنت تريد دمجها.

ماذا أفعل إذا لم تظهر نتائج؟

تأكد من أن العتبة منخفضة بما يكفي (جرب 0.5)، وأن المشروع يحتوي على تكرار غير حرفي. يمكنك أيضاً تجربة نموذج مختلف.

هل Slopo مجاني؟

نعم، مفتوح المصدر ومجاني بالكامل.

هل أحتاج إلى GPU؟

لا، يعمل على CPU بشكل طبيعي.

الخلاصة

Slopo أداة واعدة لاكتشاف التكرار غير الحرفي في مشاريع Python. جربها على مشروعك، وشارك ملاحظاتك مع المجتمع. تذكر أن الأداة لا تزال جديدة، لذا توقع بعض التحديات. ابدأ الآن بتحسين جودة كودك.