نظرة عامة والمفاهيم الأساسية

#ما هي CleanLens

CleanLens أداة محلية لتحليل Clean Code تفهم سجل Git. تعمل بشكلين يشتركان في محرّك واحد:

• إضافة VS Code (شريط جانبي، ولوحة معلومات webview، وتنبيهات داخل المحرر)، و
• أداة سطر الأوامر cleanlens (تقرير نصي أو Markdown أو JSON، وبوابة جودة في الـ CI).

تحلل ملفات JavaScript / TypeScript (.js .jsx .mjs .cjs .ts .tsx) وPython (.py) وفق 14 قاعدة قابلة للضبط، ثم تحدد أي مطوّر أدخل كل مشكلة، وتعطي كل مطوّر Clean Code Score من 0 إلى 100.

كل شيء يعمل على جهازك. لا ترسل أي طلبات عبر الشبكة، ولا تجمع أي بيانات استخدام، ولا تحتاج تسجيل دخول (انظر PRIVACY.md).

#المشكلة التي تحلها

معظم أدوات "من كتب الكود السيئ" تستخدم git blame على الملفات الحالية. وهذا غير عادل: إذا عدّلت سارة سطراً واحداً في ملف قديم من 2,000 سطر، يجعلها blame آخر من كتب في هذا الملف، وأداة تعمل على مستوى الملف تحمّلها مشاكل الملف القديمة كلها.

أما CleanLens فتعيد تشغيل سجل الـ commits. لكل commit تحلل كل ملف تغيّر قبل الـ commit وبعده، وتقارن مجموعتي المخالفات:

• مخالفة تظهر بعد الـ commit فقط، على أسطر غيّرها الـ commit ← أدخلها كاتب هذا الـ commit؛
• مخالفة موجودة قبله وبعده ← موجودة سابقاً، ولا تُحسب على أحد؛
• مخالفة موجودة قبله واختفت بعده ← أُصلحت، وتُحسب لصالح الكاتب.

بعد ذلك تُبنى الدرجات على عدد المشاكل التي أدخلها المطوّر لكل 1,000 سطر كتبها، وليس على الأعداد الخام. وهناك تصحيح إحصائي (التقليص البايزي) يمنع العيّنة الصغيرة من إنتاج درجة متطرفة.

#مبادئ التصميم

1. العدالة قبل السهولة. لا يُحمَّل المطوّر مخالفة إلا بدليل (ثقة عالية أو متوسطة). أي شيء غير مؤكد يُعرض ولا يدخل في الدرجة.
2. الجودة منفصلة عن الحجم. "نسبة المساهمة" (كم كتبت من الكود) تظهر دائماً بجانب الدرجة، ولا تُخلط بها أبداً.
3. محلية وخاصة. فقط عمليات git وقراءة الملفات. لا خوادم.
4. قابلة للضبط. القواعد، ودرجات الخطورة، والحدود، والاستثناءات، وثوابت التقييم، والهويات، وعمق السجل، كلها قابلة للضبط (انظر 10 — مرجع الإعدادات و11 — دليل الضبط والتخصيص).
5. محرّك واحد وواجهتان. الإضافة وأداة سطر الأوامر تستدعيان نفس الدالة analyzeRepository()، لذلك أرقامهما متطابقة دائماً.

#المصطلحات

هذه المصطلحات مستخدمة في كل الملفات وفي واجهة الأداة.

#ماذا تحصل عليه من كل تشغيل

• إجماليات المشروع: عدد المطورين، والمخالفات، والمخالفات غير المنسوبة، والملفات المحللة، والـ commits المحللة، ووقت التحليل.
• لكل مطوّر: Clean Code Score ودرجاتها الفرعية الثلاث، والأسطر المحللة، وثقة الدرجة، ونسبة المساهمة، وأعداد المخالفات الجديدة / المُصلحة / الموجودة سابقاً / غير المنسوبة، والنقاط الموزونة، وصافي الأثر على الجودة، والكثافة لكل KLOC، وأيام النشاط، وأول وآخر مساهمة، والبريد الإلكتروني.
• لكل مخالفة: الخطورة، والقاعدة، والرسالة، والملف ومدى الأسطر، والحالة، والثقة، والمطوّر الذي أدخلها، والـ commit والتاريخ.

#إلى أين بعد ذلك

• لتشغيلها الآن: 02 — البدء.
• لفهم ما يجري من الداخل: 03 — البنية المعمارية.
• لضبطها: 11 — دليل الضبط والتخصيص.