دليل الضبط والتخصيص

هذا الدليل يشرح كيف تضبط CleanLens بحسب احتياجات فريقك: ماذا تغيّر، وأين، وما أثر ذلك. للقائمة الدقيقة بالمفاتيح وأنواعها، انظر 10 — مرجع الإعدادات.

المحتويات

1. اختر نقطة البداية
2. القواعد: الصرامة والإنذارات الزائدة
3. ماذا تحلل: الاستثناءات
4. التقييم
5. هويات المطورين
6. نافذة السجل
7. تجربة المحرر
8. بوابات الجودة في الـ CI
9. التخصيصات الشخصية
10. إعدادات جاهزة لأنواع الفرق
11. المعايرة على مستودعك
12. التخصيص في الكود المصدري
13. اجعل VS Code وسطر الأوامر متطابقين

#1. اختر نقطة البداية

شغّل CleanLens: Initialize Project واختر الإعداد المسبق المناسب للمستودع:

بعد ذلك عدّل ملف .clean-code-tracker.json الذي أُنشئ. الإعداد المسبق يُستخدم فقط لإنشاء الملف؛ والتغييرات اللاحقة لك.

#2. القواعد: الصرامة والإنذارات الزائدة

#الأدوات الثلاث لكل قاعدة

قاعدة عامة: غيّر limit عندما تُبلّغ القاعدة عن كود تراه سليماً؛ وغيّر severity عندما تُبلّغ بشكل صحيح لكن الأمر يهمك أقل (أو أكثر)؛ وعطّلها عندما تكون غالباً خاطئة في مشروعك.

#مستويات الصرامة

تذكّر أن requireSingleResponsibility تُبلّغ أيضاً عن الدوال التي تتجاوز 1.5 × maxFunctionLines.limit و1.5 × maxComplexity.limit، فتغيير هذين الحدين يغيّرها أيضاً.

#تقليل الإنذارات الزائدة

معظم الإنذارات الزائدة تأتي من بضع قواعد تقديرية. جرّب هذه بالترتيب:

1. requireErrorHandling: إذا كانت الأخطاء تُعالج مركزياً (middleware للأخطاء في Express، أو views في Django، أو طبقة React Query)، اخفضها إلى low أو عطّلها.

   "requireErrorHandling": { "enabled": true, "severity": "low" }

2. forbidDebugStatements: لأدوات سطر الأوامر والسكربتات التي يكون print / console.log فيها هو المخرج الحقيقي، استثنِ تلك المجلدات (القسم 3) بدلاً من تعطيل القاعدة للمشروع كله.
3. requireDocumentationForComplexCode: ارفع complexityThreshold إلى 20 أو أكثر، أو عطّلها إذا كان فريقك يوثّق بتعليقات عادية.
4. requireSingleResponsibility: ارفع maxMethods لأطر العمل التي فيها classes كبيرة لكنها مترابطة (Django admin، وclass components، وservice objects).
5. maxNestingDepth في Python: عمق Python يحسب مستويات class وdef، فيبدأ جسم الـ method من العمق 2. للمستودعات التي يغلب عليها Python استخدم limit: 5 أو 6.

#التركيز على ما يهمك

• الأمان أولاً: أبقِ forbidHardcodedSecrets على critical وارفع forbidEmptyCatchBlocks إلى critical.
• قابلية الصيانة أولاً: ارفع maxComplexity وmaxNestingDepth إلى critical، واخفض قواعد التسمية والتصحيح إلى low.
• البدء مع مشروع قديم: أبقِ الحدود متساهلة والخطورة منخفضة لقواعد البنية في البداية؛ وشدّدها كل بضع دورات عمل (sprints).

#3. ماذا تحلل: الاستثناءات

استثنِ كل ما ليس كوداً يكتبه فريقك ويصونه. هذا يجعل التحليل أسرع وأعدل.

#أين تضيف الأنماط

#أنماط شائعة

"exclude": [
  "**/__tests__/**", "*.test.*", "*.spec.*",   // الاختبارات
  "**/fixtures/**", "**/__mocks__/**",          // بيانات الاختبار
  "scripts/**", "tools/**",                     // سكربتات لمرة واحدة
  "**/third_party/**", "public/vendor/**",      // كود مكتبات خارجية
  "**/*.d.ts",                                  // تعريفات الأنواع
  "docs/**/*.js"                                // أمثلة في التوثيق
]

(التعليقات للشرح فقط؛ الملف الحقيقي يجب أن يكون JSON عادياً.)

نصائح للأنماط:

• folder/** يطابق ذلك المجلد في أي عمق. استخدم /folder/** للمطابقة في الجذر فقط.
• *.ext بدون / يطابق اسم الملف في أي مكان.
• لا نفي (!)، ولا {a,b}، ولا [abc]. اكتب أنماطاً منفصلة بدلاً منها.

#الملفات المولَّدة

أبقِ excludeGenerated: true (الافتراضي). لتعليم الملفات المولَّدة صراحة:

# .gitattributes
src/api/client.ts linguist-generated
proto/*.ts        linguist-generated

أو ضع // @generated / # DO NOT EDIT في أول خمسة أسطر من الملف.

#هل تُحلَّل الاختبارات؟

• استثنِها (كما يفعل الإعدادان المسبقان react وpython) إذا أردت أن تعكس الدرجات كود الإنتاج فقط.
• ضمّنها إذا كانت جودة الاختبارات تهمك. فكّر في خفض detectDuplicateCode إلى low: الاختبارات متكررة بطبيعتها غالباً.

#ملفات الترحيل

excludeMigrations: true (الافتراضي) يتخطى **/migrations/**. اجعله false فقط إذا كانت ملفات الترحيل مكتوبة يدوياً وتُراجع مثل كود التطبيق.

#4. التقييم

الدرجات تأتي من النقاط الموزونة لكل 1,000 سطر، مُحوَّلة عبر 100 × e^(−density / scale). انظر 08 — التقييم للمعادلة الكاملة.

#الأداة 1 — خطورة القاعدة (التحكم الرئيسي في الوزن)

وزن المخالفة يأتي من severity قاعدتها: low ‏1، medium ‏3، high ‏5، critical ‏8. هذه هي الطريقة لجعل قاعدة تؤثر أكثر أو أقل.

#الأداة 2 — مقاييس الفئات (مستوى التساهل العام)

scoring.categoryScales يحدد مقدار الكثافة التي تتحملها الفئة. المقياس الأكبر = تساهل أكثر.

"scoring": { "categoryScales": { "structure": 60 } }

اختر المقياس من هدف تحدده: "المطوّر الذي كثافته d يجب أن يحصل على درجة فرعية s":

scale = d / −ln(s / 100)

مثال: أفضل مطوريك كثافة البنية لديهم حوالي 12. تريدهم أن يحصلوا على 80 في البنية ← scale = 4.5 × 12 = 54.

#الأداة 3 — أوزان الفئات (ما الأهم)

scoring.weights يحدد حصة كل درجة فرعية في الدرجة النهائية. أبقِ المجموع 1.

إذا لم يكن مجموع الأوزان 1، تُضخَّم الدرجات أو تُصغَّر (وتُحصر بين 0 و100)، فيصعب مقارنتها. تجنّب ذلك.

#الأداة 4 — حد الترتيب

scoring.minLinesForRanking (افتراضياً 1000):

• فريق صغير / نافذة قصيرة: اخفضه إلى 300–500 حتى يدخل الناس الترتيب أصلاً.
• فريق كبير / مراجعة رسمية: ارفعه إلى 2,000–5,000 حتى لا تُقارن إلا الدرجات المبنية على بيانات كافية.

في VS Code، اضبط cleanlens.scoring.minLinesForRanking: هذا الإعداد يتجاوز ملف الإعدادات (انظر القسم 13).

#غير قابل للضبط (من الكود فقط)

قوة التقليص (PRIOR_KLOC = 1)، وحدود مستويات الثقة (300 / 1,000 / 5,000 سطر)، وأي درجات ثقة النسب تدخل في الدرجة (high + medium). انظر القسم 12.

#5. هويات المطورين

كثيراً ما يرسل الناس commits بعدة عناوين بريد أو بأكثر من طريقة لكتابة الاسم. تدمجها CleanLens بثلاث طرق، من الأكثر صراحة إلى الأقل:

#أ) قائمة صريحة في الإعدادات (يُنصح بها للفرق)

"developers": [
  { "displayName": "Musa Alahmed", "emails": ["musa@company.com", "12345+musa@users.noreply.github.com"] },
  { "displayName": "Ayman Khalil", "emails": ["ayman@company.com", "ayman.k@gmail.com"] }
]

• كل العناوين المدرجة تصبح مطوّراً واحداً، يُعرض بـ displayName.
• مطابقة البريد لا تعتمد على حالة الأحرف.

#ب) .mailmap (على مستوى Git، ويصلح أيضاً git log / git shortlog)

Musa Alahmed <musa@company.com> <musa.personal@gmail.com>
Musa Alahmed <musa@company.com> MUSAALAHMED4 <12345+MUSAALAHMED4@users.noreply.github.com>

#ج) الدمج التلقائي (mergeSameNameAuthors، مفعّل افتراضياً)

يدمج الهويات التي لها نفس الاسم، أو نفس الاسم بعد تجاهل المسافات وعلامات الترقيم والأرقام في آخره، أو نفس مُعرّف البريد المميز. التفاصيل: 04 — طبقة Git.

عطّله إذا كان شخصان مختلفان يحملان نفس الاسم، ثم أدرج عمليات الدمج الحقيقية صراحة:

"mergeSameNameAuthors": false

(في VS Code اضبط cleanlens.mergeSameNameAuthors على false أيضاً؛ الإعداد هو الذي يغلب.)

#البوتات

البوتات (Dependabot وRenovate والـ CI) تظهر كمطورين. عادة تلمس ملفات القفل والإعدادات فقط، فيكون لديها 0 أسطر محللة ودرجة "no analysed code" غير داخلة في الترتيب. لا يوجد خيار لإخفائها. يمكنك تجاهلها في التقرير، أو جمعها تحت اسم واحد بقائمة developers.

#6. نافذة السجل

فقط المخالفات التي أُدخلت داخل النافذة تُنسب. الأقدم منها تظهر existing ولا تُحسب على أحد.

عند ضبط الاثنين، يطبّقهما Git معاً: الـ commits بعد since، ثم أحدث maxCommits منها.

كلما اتسعت النافذة، زاد الكود لكل مطوّر، وارتفعت ثقة الدرجة، وقلّت المخالفات existing. ومع تفعيل الذاكرة المؤقتة، أول تشغيل واسع فقط يكون بطيئاً.

#7. تجربة المحرر

• التنبيهات المباشرة (cleanlens.liveDiagnostics، مفعّلة افتراضياً): تضع خطاً تحت المشاكل أثناء الكتابة، بالقواعد التي تعمل على مستوى الملف. عطّلها إذا كانت مزعجة أو بطيئة على الملفات الضخمة؛ تنبيهات التحليل الكامل تبقى.
• مستوى التنبيه يتبع الخطورة: critical/high ← Error (أحمر)، وmedium ← Warning (أصفر)، وlow ← Information (أزرق). لجعل قاعدة أهدأ في المحرر، اخفض خطورتها (وهذا يخفض وزنها في الدرجة أيضاً).
• التنبيهات المباشرة لا تطبّق قائمة الاستثناءات: الملف المستثنى الذي تفتحه يظهر فيه خطوط تحت المشاكل. نتائج التحليل الكامل لا تتأثر.

#8. بوابات الجودة في الـ CI

استخدم رموز الخروج في سطر الأوامر (0 = نجاح، 1 = فشل البوابة، 2 = خطأ):

# الفشل عند أي مخالفة high أو critical في الكود الحالي
cleanlens --fail-on high

# بوابة قابلة للتكرار تتجاهل التخصيصات الشخصية وتستخدم قواعد معروفة
cleanlens --preset django --fail-on critical --no-cache

# نشر تقرير كملف ناتج من الـ CI
cleanlens --markdown > cleanlens-report.md
cleanlens --json > cleanlens-report.json

أشياء يجب معرفتها:

• --fail-on يفحص كل المخالفات في الكود الحالي، بما فيها existing. في مشروع قديم، ابدأ بـ --fail-on critical (مثلاً للأسرار فقط) وشدّد مع الوقت.
• في الـ CI لا يوجد ملف التخصيص المحلي (git يتجاهله)، فيستخدم الـ CI إعدادات الفريق. وهذا ما تريده.
• استخدم --max-commits لإبقاء الـ CI سريعاً؛ النسب لا يؤثر في --fail-on.

أمثلة كاملة (GitHub Actions وخطاف pre-commit): 13 — أداة سطر الأوامر.

#9. التخصيصات الشخصية

للتجربة دون التأثير على فريقك، أنشئ .clean-code-tracker.local.json:

{
  "rules": { "maxFunctionLines": { "limit": 60 } },
  "exclude": ["sandbox/**"]
}

يُقرأ فقط rules (تُدمج لكل قاعدة) وexclude (يُضاف). الملف لا يُتحقق منه، فتأكد من معرّفات القواعد. وتأكد أنه موجود في .gitignore.

#10. إعدادات جاهزة لأنواع الفرق

انسخ واحداً ثم عدّله. تظهر فقط الفروقات عن الإعداد المسبق الافتراضي؛ ادمجها في rules / scoring في ملفك.

#شركة ناشئة / منتج سريع التطور

حدود بنية أكثر تساهلاً، وتركيز على الأخطاء الحقيقية والأسرار.

{
  "rules": {
    "maxFunctionLines": { "enabled": true, "severity": "low", "limit": 60 },
    "maxFileLines": { "enabled": true, "severity": "low", "limit": 600 },
    "maxComplexity": { "enabled": true, "severity": "medium", "limit": 12 },
    "requireDocumentationForComplexCode": { "enabled": false, "severity": "low" },
    "requireErrorHandling": { "enabled": true, "severity": "low" }
  },
  "scoring": { "categoryScales": { "structure": 60 } }
}

#مؤسسة / قطاع خاضع للأنظمة

حدود صارمة، والتوثيق مطلوب، وبيانات أكثر قبل الترتيب.

{
  "rules": {
    "maxFunctionLines": { "enabled": true, "severity": "medium", "limit": 30 },
    "maxComplexity": { "enabled": true, "severity": "high", "limit": 8 },
    "maxNestingDepth": { "enabled": true, "severity": "high", "limit": 3 },
    "forbidEmptyCatchBlocks": { "enabled": true, "severity": "critical" },
    "requireDocumentationForComplexCode": { "enabled": true, "severity": "medium", "options": { "complexityThreshold": 10 } }
  },
  "analysis": { "maxCommits": 0 },
  "scoring": { "minLinesForRanking": 3000 }
}

#الأمان أولاً

{
  "rules": {
    "forbidHardcodedSecrets": { "enabled": true, "severity": "critical" },
    "forbidEmptyCatchBlocks": { "enabled": true, "severity": "critical" },
    "requireErrorHandling": { "enabled": true, "severity": "high" },
    "forbidDebugStatements": { "enabled": true, "severity": "medium" }
  },
  "scoring": { "weights": { "duplication": 0.2, "structure": 0.35, "hygiene": 0.45 } }
}

#مشروع قديم (الأشهر الأولى)

حاسِب على العمل الجديد فقط، وأبقِ الدَّين القديم ظاهراً لكن خارج الدرجة، وشدّد مع الوقت.

{
  "rules": {
    "maxFileLines": { "enabled": true, "severity": "low", "limit": 1000 },
    "maxFunctionLines": { "enabled": true, "severity": "low", "limit": 80 },
    "detectDuplicateCode": { "enabled": true, "severity": "low", "options": { "minLines": 10 } }
  },
  "analysis": { "since": "2026-09-01" }
}

since = التاريخ الذي بدأ فيه الفريق التنظيف: كل ما هو أقدم يكون existing.

#خادم Python / Django

{
  "rules": {
    "maxNestingDepth": { "enabled": true, "severity": "high", "limit": 5 },
    "requireSingleResponsibility": { "enabled": true, "severity": "medium", "options": { "maxMethods": 15 } },
    "maxFileLines": { "enabled": true, "severity": "medium", "limit": 500 }
  }
}

#11. المعايرة على مستودعك

طريقة قابلة للتكرار لضبط CleanLens على فريق:

1. شغّلها على نطاق واسع على المستودع الحقيقي:

   cleanlens --full-history --markdown > baseline.md

2. اقرأ قسمي "Severity breakdown" و"Files with violations". ابحث عن القواعد التي لها أكثر النتائج.
3. عالج الإنذارات الزائدة أولاً. افتح 10 نتائج من أكثر قاعدة إزعاجاً. إذا كان معظمها ليس مشاكل حقيقية لفريقك، غيّر limit أو severity لتلك القاعدة، أو عطّلها (القسم 2). واستثنِ الكود الذي لا يملكه فريقك (القسم 3).
4. تحقق من الهويات. هل انقسم أحد إلى شخصين؟ أضف developers أو .mailmap (القسم 5).
5. بعد ذلك فقط انظر إلى الدرجات. إذا كانت فئة منخفضة عند الجميع، فالقواعد أو المقياس أشد مما يناسب سياقك. استخدم المعادلة في القسم 4 لتعديل مقياس تلك الفئة.
6. ثبّت الإعدادات وأضفها إلى المستودع. تغيير القواعد كل أسبوع يجعل الدرجات غير قابلة للمقارنة عبر الزمن (ويمسح الذاكرة المؤقتة).
7. وضّحها للفريق. شارك القواعد والقيود (17) مع الفريق. الدرجات لتحسين الكود، وليست لترتيب الأشخاص.

#12. التخصيص في الكود المصدري

بعض السلوك ثابت في الكود. غيّره، وأعد البناء (npm run build)، وارفع ENGINE_VERSION في src/scoring/scoringConfig.ts إذا كان التغيير يؤثر في نتائج التحليل، حتى تُلغى الذاكرة المؤقتة القديمة.

إضافة قاعدة جديدة أو لغة جديدة مشروحة في 15 — دليل التطوير.

#13. اجعل VS Code وسطر الأوامر متطابقين

في الإضافة، إعدادات VS Code التالية تتجاوز ملف الإعدادات حتى بقيمها الافتراضية: excludeGenerated وexcludeMigrations وexcludeLockFiles وmergeSameNameAuthors وanalysis.maxCommits وscoring.minLinesForRanking. (التفاصيل: 10 — الأولوية.)

للحصول على أرقام متطابقة من الإضافة وسطر الأوامر والـ CI:

1. ضع إعدادات الفريق في .clean-code-tracker.json.
2. أضف إلى المستودع ملف .vscode/settings.json بنفس القيم للإعدادات أعلاه، مثلاً:

   {
     "cleanlens.analysis.maxCommits": 0,
     "cleanlens.scoring.minLinesForRanking": 3000,
     "cleanlens.mergeSameNameAuthors": true
   }

3. لا تستخدم --preset في الـ CI إلا إذا كنت تستخدمه في كل مكان.
4. أبقِ التخصيصات الشخصية بعيدة عن التقارير المشتركة.