في مشروع تطبيق حكومي سعودي، وجدت دالة معالجة بيانات مكررة 5 مرات بتغيير أسماء المتغيرات فقط. أدوات الكشف التقليدية مثل jscpd لم تكتشفها لأنها تبحث عن تطابق حرفي. هنا يأتي دور Slopo، أداة CLI جديدة تستخدم نماذج التضمين (embeddings) لاكتشاف التكرار غير الحرفي. هذا الدليل يشرح كيفية تثبيت Slopo وتشغيله على مشروعك، مع أمثلة حقيقية من تجربة عملية.

ما هو Slopo؟

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

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

• Node.js v18 أو أحدث
• مفتاح API لنموذج تضمين (مثل OpenAI) أو نموذج محلي
• مشروع كود للاختبار

تركيب Slopo خطوة بخطوة

استناداً إلى README الرسمي (https://github.com/rafal-qa/slopo)، اتبع الخطوات التالية:

1. استنساخ المستودع: git clone https://github.com/rafal-qa/slopo.git
2. تثبيت الاعتماديات: npm install
3. إعداد ملف .env (انظر القسم التالي)
4. تشغيل الأداة: node index.js --path ./my-project

شرح ملف .env والإعدادات

يحتاج Slopo إلى متغيرات بيئية لتكوين نموذج التضمين. مثال حقيقي لملف .env:

EMBEDDING_MODEL=text-embedding-ada-002
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SIMILARITY_THRESHOLD=0.8

شرح المتغيرات:

• EMBEDDING_MODEL: اسم نموذج التضمين. القيمة الافتراضية هي text-embedding-ada-002 من OpenAI.
• OPENAI_API_KEY: مفتاح API الخاص بحساب OpenAI. يمكن الحصول عليه من https://platform.openai.com/api-keys.
• SIMILARITY_THRESHOLD: عتبة التشابه (بين 0 و1). القيم الأعلى تعني تشابهاً أكبر. يوصى بالبدء بـ 0.8.

إذا كنت تستخدم نموذجاً محلياً، قد تحتاج إلى متغيرات إضافية مثل LOCAL_MODEL_PATH (غير موثقة حالياً).

تشغيل Slopo على مشروعك

بعد التركيب، شغّل الأمر التالي على مجلد مشروعك:

node index.js --path ./src

مثال إخراج متوقع:

Found 3 similar code pairs:
Pair 1: ./src/utils.js (lines 10-25) and ./src/helpers.js (lines 5-20) - similarity: 0.92
Pair 2: ./src/auth.js (lines 30-45) and ./src/login.js (lines 15-30) - similarity: 0.85
Pair 3: ./src/db.js (lines 50-65) and ./src/cache.js (lines 40-55) - similarity: 0.78

كل زوج يظهر مسار الملفين ونطاق الأسطر ونسبة التشابه. ركز على الأزواج ذات النسبة العالية (مثلاً >0.8).

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

مثال عملي: تشغيل Slopo على مشروع عربي

لنفترض أن لديك مشروعاً عربياً باسم my-arabic-app. بعد تثبيت Slopo، شغّل الأمر:

node index.js --path ./my-arabic-app

إذا كان المشروع يحتوي على كود مكرر غير حرفي، سترى نتائج مشابهة للمثال أعلاه. لاحظ أن Slopo يعمل على مستوى النص، لذا فهو يدعم أي لغة برمجة.

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

النتائج تظهر أزواجاً من الملفات مع نسبة تشابه. النسبة العالية (مثلاً >0.8) تعني أن الكود متشابه دلالياً. راجع هذه الأزواج يدوياً لتقرر ما إذا كان التكرار حقيقياً ويحتاج إلى إعادة هيكلة.

هل يستحق Slopo التجربة؟ تقييم موضوعي

Slopo فكرة واعدة، لكنه في مرحلة مبكرة جداً (إصدار 0.x). README غير واضح في بعض النقاط، وقد تواجه صعوبات في التركيب. إذا كنت مستعداً للتجربة والمساهمة، فقد تجد فائدة. أما إذا كنت تبحث عن حل جاهز، فانتظر نضوج المشروع أو استخدم البدائل.

بدائل Slopo: أدوات مشابهة

• jscpd: كشف التكرار الحرفي، ناضج وسهل.
• PMD Copy/Paste Detector: أداة Java قوية.
• Duplo: أداة CLI لكشف التكرار الحرفي.