Reference OS v8 5 دقائق قراءة ٣ يوليو ٢٠٢٦ informational - فهم أداة تقنية جديدة وتقييم فائدتها وطريقة تجربتها Slopo: أداة CLI لاكتشاف تكرار الكود غير الحرفي باستخدام التضمين - تجربة عملية بعد قراءة…
Show HN: CLI tool for detecting non-exact code duplication with embedding models
اختر القسم الذي تحتاجه الآن
الفكرة التي تمنع التسرع
في مشروع تطبيق حكومي سعودي، وجدت دالة معالجة بيانات مكررة 5 مرات بتغيير أسماء المتغيرات فقط. أدوات الكشف التقليدية لم تكتشفها. هنا يأتي دور Slopo.
قبل أن تطبق، اعرف أين تقف بالضبط
لا تعتمد على الانطباع؛ اختر مؤشراً تراجعه
في مشروع تطبيق حكومي سعودي، وجدت دالة معالجة بيانات مكررة 5 مرات بتغيير أسماء المتغيرات فقط. أدوات الكشف التقليدية مثل jscpd لم تكتشفها لأنها تبحث عن تطابق حرفي. هنا يأتي دور Slopo، أداة CLI جديدة تستخدم نماذج التضمين (embeddings) لاكتشاف التكرار غير الحرفي. هذا الدليل يشرح كيفية تثبيت Slopo وتشغيله على مشروعك، مع أمثلة حقيقية من تجربة عملية.
Slopo هي أداة سطر أوامر (CLI) مفتوحة المصدر تكتشف تكرار الكود غير الحرفي (non-exact duplication). بدلاً من البحث عن تطابق تام، تستخدم نماذج التضمين (مثل OpenAI embeddings) لتحويل الكود إلى متجهات رقمية، ثم تقارن هذه المتجهات لإيجاد التشابه الدلالي. هذا يعني أنها تستطيع اكتشاف كود مكرر حتى بعد إعادة تسمية المتغيرات أو إعادة ترتيب الأسطر.
استناداً إلى README الرسمي (https://github.com/rafal-qa/slopo)، اتبع الخطوات التالية:
git clone https://github.com/rafal-qa/slopo.gitnpm install.env (انظر القسم التالي)node index.js --path ./my-projectيحتاج 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 (غير موثقة حالياً).
بعد التركيب، شغّل الأمر التالي على مجلد مشروعك:
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).
لنفترض أن لديك مشروعاً عربياً باسم my-arabic-app. بعد تثبيت Slopo، شغّل الأمر:
node index.js --path ./my-arabic-appإذا كان المشروع يحتوي على كود مكرر غير حرفي، سترى نتائج مشابهة للمثال أعلاه. لاحظ أن Slopo يعمل على مستوى النص، لذا فهو يدعم أي لغة برمجة.
النتائج تظهر أزواجاً من الملفات مع نسبة تشابه. النسبة العالية (مثلاً >0.8) تعني أن الكود متشابه دلالياً. راجع هذه الأزواج يدوياً لتقرر ما إذا كان التكرار حقيقياً ويحتاج إلى إعادة هيكلة.
Slopo فكرة واعدة، لكنه في مرحلة مبكرة جداً (إصدار 0.x). README غير واضح في بعض النقاط، وقد تواجه صعوبات في التركيب. إذا كنت مستعداً للتجربة والمساهمة، فقد تجد فائدة. أما إذا كنت تبحث عن حل جاهز، فانتظر نضوج المشروع أو استخدم البدائل.
خطوات عملية مرتبة من التشخيص إلى النتيجة
لماذا؟ Slopo يعتمد على Node.js ومفتاح API لتضمين الكود.
كيف؟ تأكد من تثبيت Node.js v18+، واحصل على مفتاح API من OpenAI (https://platform.openai.com/api-keys).
الناتج: بيئة جاهزة مع Node.js ومفتاح API صالح.
لماذا؟ تحتاج إلى كود الأداة محليًا لتشغيلها.
كيف؟ git clone https://github.com/rafal-qa/slopo.git ثم cd slopo ثم npm install
الناتج: مجلد slopo مع تثبيت جميع الحزم.
لماذا؟ Slopo يحتاج إلى متغيرات بيئية لتحديد نموذج التضمين والمفتاح.
كيف؟ أنشئ ملف .env في مجلد slopo وأضف: EMBEDDING_MODEL=text-embedding-ada-002, OPENAI_API_KEY=sk-..., SIMILARITY_THRESHOLD=0.8
الناتج: ملف .env صحيح.
لماذا؟ لاكتشاف التكرار غير الحرفي في قاعدة الكود.
كيف؟ node index.js --path ./path-to-your-project (مثال: node index.js --path ./my-arabic-app)
الناتج: قائمة بأزواج الملفات المتشابهة مع نسب التشابه.
لماذا؟ تحديد الأزواج التي تحتاج إلى إعادة هيكلة.
كيف؟ ركز على الأزواج ذات التشابه >0.8، وراجع الكود يدويًا لتأكيد التكرار.
الناتج: قائمة بالتكرارات المؤكدة التي يمكن إعادة هيكلتها.
حوّل القراءة إلى تنفيذ سريع
EMBEDDING_MODEL=text-embedding-ada-002 OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx SIMILARITY_THRESHOLD=0.8
node index.js --path ./src
اعرف أين يتعثر الناس وكيف تتجنب ذلك
ماذا تفعل حسب حالتك؟
إذا: إذا كان لديك مفتاح API صالح وNode.js v18+
إذن: اتبع خطوات التثبيت والتشغيل.
إذا: إذا لم يكن لديك مفتاح API
إذن: احصل على مفتاح من OpenAI أو استخدم نموذجًا محليًا (غير موثق).
إذا: إذا كنت تبحث عن حل ناضج وفوري
إذن: استخدم jscpd أو PMD Copy/Paste Detector بدلاً من Slopo.
إذا: إذا واجهت أخطاء في التثبيت
إذن: راجع جدول الأخطاء الشائعة وحلولها.
جدول صغير يمنع التسويف
نقاط مختصرة ترجع لها لاحقاً
1. Slopo يستخدم نماذج تضمين لاكتشاف التشابه الدلالي وليس الحرفي.
2. يتطلب Node.js v18 أو أحدث.
3. يدعم أي لغة برمجة نصية.
4. المشروع في مرحلة مبكرة (إصدار 0.x).
5. README الأصلي غير واضح في بعض النقاط.
6. يمكن استخدامه مع نماذج OpenAI أو نماذج محلية (غير موثقة).
7. عتبة التشابه الافتراضية 0.8.
إجابات مباشرة على ما يبحث عنه الزائر
تعريفات مختصرة تمنع الالتباس
تمثيل رقمي للنص (مثل الكود) في شكل متجه، يستخدم لمقارنة التشابه الدلالي.
تكرار الكود مع اختلافات مثل إعادة تسمية المتغيرات أو إعادة ترتيب الأسطر.
قيمة بين 0 و1 تحدد مدى التشابه المطلوب لاعتبار الكود مكررًا.
استخدمها كمسارات متابعة داخل نفس الموضوع
تحول القارئ: من مطور يجهل وجود أدوات تكشف التكرار غير الحرفي إلى مطور قادر على تجربة Slopo وتقييمها.
القيمة الحقيقية تظهر عند العودة والتطبيق
لا تتعامل معه كمقال يُقرأ مرة واحدة. استخدمه كلوحة تشغيل: ارجع للتشخيص عند ظهور المشكلة، وللقوالب عند التطبيق، ولمؤشرات القياس عند المراجعة.
Slopo أداة طموحة تستخدم AI لكشف التكرار غير الحرفي. رغم أن README غير واضح والمشروع في بدايته، إلا أنه يستحق المتابعة. إذا كنت مطوراً عربياً تحب التجربة، جربه وساهم في تحسينه. أما إذا كنت بحاجة لحل فوري، فاستخدم البدائل الناضجة مثل jscpd. تابع المشروع على GitHub لترى التحديثات.
حتى يبقى المرجع صالحاً مع الوقت
FAQ
