مرجع القواعد

في CleanLens 14 قاعدة. كل واحدة تُضبط في .clean-code-tracker.json تحت rules.<ruleId>:

"maxFunctionLines": { "enabled": true, "severity": "medium", "limit": 40 }

#ملخص

≈ = تقريبي (قاعدة تقديرية، انظر أدناه).

القيم الافتراضية مأخوذة من BASE_RULES في src/configuration/presets.ts. إذا لم يكن للقاعدة limit/خيار في الإعدادات، يستخدم المحلل نفس القيمة الافتراضية.

#قواعد البنية

#maxFunctionLines — دالة طويلة

• تُبلّغ عن دالة يزيد امتدادها (من أول سطر إلى آخر سطر، شاملاً) على limit.
• JS/TS: كل عقدة شبيهة بالدالة، بما فيها الدوال السهمية والـ methods. الدوال المتداخلة تُقاس منفصلة؛ وامتداد الدالة الخارجية يشملها.
• Python: def / async def من الترويسة حتى آخر سطر بمسافة بادئة.
• الموقع: الدالة كلها (من سطر البداية إلى سطر النهاية). وتحمل اسم الدالة.

#maxFileLines — ملف كبير

• تُبلّغ عن ملف عدد أسطره أكبر من limit. مخالفة واحدة لكل ملف، على السطر 1.
• تحسب كل الأسطر، بما فيها الفارغة والتعليقات.

#maxParameters — معاملات كثيرة

• تُبلّغ عن دالة تعرّف أكثر من limit معاملاً.
• Python تتجاهل self وcls و*args و**kwargs.
• JS/TS تحسب كل معامل معرّف؛ والكائن المفكك (destructured) يُحسب معاملاً واحداً.

#maxComplexity — تعقيد عالٍ

• تُبلّغ عن دالة تعقيدها الدوري أكبر من limit.
• JS/TS: 1 + كل if و?: وحلقة وcatch وcase غير فارغ و&& و|| و??. الدوال المتداخلة غير مشمولة.
• Python (تقريبي): 1 + كل سطر في جسم الدالة يبدأ بـ if/elif/for/while/except/case + كل and/or. الدوال المتداخلة مشمولة.

#maxNestingDepth — تداخل عميق

• تُبلّغ عن جملة تحكم متداخلة أعمق من limit.
• JS/TS: يزيد العمق مع if وfor وfor…in وfor…of وwhile وdo وswitch. الـ else if لا تضيف مستوى. كل جملة تتجاوز الحد يُبلَّغ عنها.
• Python (تقريبي): العمق = المسافة البادئة ÷ 4 على أسطر if/elif/else/for/while/with/try/except. العدّ يشمل مستويات def/class المحيطة، فيصل كود Python إلى الحد أسرع من كود JS المكافئ. فكّر في حد أعلى لمشاريع Python.

#requireSingleResponsibility — مسؤوليات متعددة

محفّزان:

• class فيه أكثر من options.maxMethods من الـ methods ‏(JS/TS: الـ methods والـ getters والـ setters؛ Python: الـ def في المستوى الأول داخل الـ class).
• دالة هي في الوقت نفسه أطول من 1.5 × maxFunctionLines.limit وأعقد من 1.5 × maxComplexity.limit. هذا المحفّز يقرأ حدود القاعدتين الأخريين، فتغييرهما يغيّر هذه القاعدة أيضاً.

هذه قاعدة تقديرية. انظر ملاحظات الإنذارات الخاطئة أدناه.

#requireDocumentationForComplexCode — كود معقد بلا توثيق

• تُبلّغ عن دالة تعقيدها أكبر من أو يساوي options.complexityThreshold وليس لها توثيق.
• JS/TS: التوثيق = كتلة JSDoc ‏(/** … */) ملحقة بالدالة. تعليق // العادي لا يُحسب.
• Python: التوثيق = docstring في أول سطر من جسم الدالة.

#قاعدة التكرار

#detectDuplicateCode — كود مكرر

• تُبلّغ عن كتلة من options.minLines سطراً مهماً على الأقل (افتراضياً 6، وأقل قيمة 3) تطابق، بعد توحيد المسافات، كتلة ظهرت قبلها.
• الأسطر الأقصر من 12 حرفاً، وأسطر الأقواس فقط، والتعليقات، وأسطر import/export تُتجاهل، فلا يثير الكود الروتيني هذه القاعدة.
• مخالفة واحدة لكل كتلة مكررة؛ والرسالة تذكر مكان الأصل.
• فحص HEAD يكشف النسخ عبر الملفات؛ ومرور الـ commits يكشفها داخل الملف الواحد. انظر 05 — المحللات.

#قواعد النظافة

#detectUnusedCode — كود غير مستخدم

• JS/TS: تُبلّغ عن import، أو متغير غير مُصدَّر على مستوى الوحدة، أو تعريف دالة غير مُصدَّرة، يظهر اسمه مرة واحدة فقط في الملف. لا توجد معلومات أنواع ولا تحليل عبر الملفات، فتُكتشف الحالات الواضحة فقط. الأسماء التي تبدأ بـ _ تُتجاهل.
• Python: تُبلّغ عن الاستيرادات غير المستخدمة فقط (الاسم يظهر مرة واحدة في الملف). وfrom x import * يُتجاهل.

#requireClearVariableNames — اسم غير واضح

• المتغيرات (JS/TS): الأسماء من حرف أو حرفين غير الموجودة في قائمة المسموح، والكلمات المبهمة مع رقم (data1 وtmp2 وobj3)، والأحرف القليلة مع أرقام (abc1).
• المعاملات وأسماء الدوال والـ classes (في اللغتين): فقط الكلمات المبهمة مع رقم والأحرف مع أرقام. الأسماء القصيرة المتعارف عليها (e وx وcb وi) مسموحة.
• مسموح: الأسماء التي تبدأ بـ _ والأسماء التقنية (utf8 وsha256 وipv6 وoauth2 وi18n وh1، …).

#requireErrorHandling — غياب معالجة الأخطاء

• JS/TS: ‏await ليس داخل كتلة try (في نفس الدالة) وليس جزءاً من سلسلة .catch(…) / .then(…).
• Python: سطر يستدعي open( أو requests.*( أو urllib أو json.load(s)( أو socket. أو subprocess. أو os.remove( أو shutil. أو int( أو float( وليس داخل كتلة try: في نفس الدالة.
• كثيراً ما يعالج الكود الأخطاء في مستوى أعلى (إطار عمل أو دالة مستدعية)، لذلك هذه القاعدة هي الأكثر احتمالاً لإنتاج إنذارات زائدة.

#forbidEmptyCatchBlocks — كتلة catch فارغة

• JS/TS: جملة catch بلا تعليمات. الـ catch التي تحتوي تعليقاً فقط تُعدّ فارغة.
• Python: ‏except …: جسمها pass أو ... فقط.

#forbidHardcodedSecrets — سرّ مكتوب في الكود

• تفحص القيم النصية المسندة إلى المتغيرات وخصائص الكائنات وعمليات الإسناد (JS/TS)، وعمليات الإسناد أو أي نص في السطر (Python).
• تُبلّغ عن صيغ الرموز المعروفة (AWS وGitHub وSlack وJWT وsk-… والمفاتيح الخاصة)، أو عن قيمة تشبه بيانات دخول مسندة إلى اسم يوحي بسرّ. النصوص البديلة مثل changeme وyour_api_key و<token> و${VAR} وexample تُتجاهل.
• الخطورة الافتراضية critical: سرّ واحد يزن مثل ثماني نتائج low.

#forbidDebugStatements — أمر تصحيح

• JS/TS: ‏console.log/debug/info/trace/dir/table(…) وdebugger. أما console.error وconsole.warn فهما مسموحان.
• Python: سطر يبدأ بـ print(، وأي breakpoint().

#الإنذارات الخاطئة وكيف تتعامل معها

لا توجد تعليقات لإسكات القاعدة داخل الكود. عدّل القاعدة أو استثنِ المسار. الوصفات موجودة في 11 — دليل الضبط والتخصيص.

#تغيير القواعد والذاكرة المؤقتة

أي تغيير في rules يغيّر بصمة إعدادات التحليل، وهذا يُلغي الذاكرة المؤقتة لكل commit. التشغيل التالي يعيد تحليل كل شيء بالقواعد الجديدة. انظر 09 — التخزين المؤقت والأداء.