القيود وحل المشاكل والأسئلة الشائعة

#القيود المعروفة

#التحليل

• اللغات: فقط JavaScript/TypeScript ‏(.js .jsx .mjs .cjs .ts .tsx) وPython ‏(.py). الملفات الأخرى تُتجاهل، وأسطرها لا تُحسب ضمن الأسطر المحللة.
• تحليل Python تقديري. يعتمد على المسافة البادئة والأنماط، وليس على parser كامل. التعقيد والتداخل تقريبيان؛ وعمق التداخل يشمل مستويات class/def. النصوص متعددة الأسطر التي تشبه الكود قد تربكه.
• لا معلومات أنواع. detectUnusedCode ‏(JS/TS) يجد فقط الأسماء المستخدمة مرة واحدة في نفس الملف؛ لا يتتبع التصدير ولا الملفات الأخرى.
• قواعد تقديرية: requireErrorHandling وrequireSingleResponsibility وrequireDocumentationForComplexCode قد تنتج إنذارات خاطئة بطبيعتها.
• لا توجد تعليقات إسكات داخل الكود (مثل // eslint-disable). عدّل القاعدة أو استثنِ المسار.
• نفس القواعد لكل اللغات في المستودع الواحد.
• الملفات الأكبر من 1 ميغابايت تُتخطى في فحص HEAD.
• أنماط glob لا تدعم ! ولا {a,b} ولا [abc]. ودعم .gitignore بأفضل جهد (ملف الجذر فقط، وتُتجاهل حالات النفي).

#النسب

• النافذة: المخالفات التي أُدخلت قبل الـ commits المحللة تكون existing ولا تُحسب على أحد. استخدم نافذة أوسع لتغطية كاملة.
• التكرار عبر الملفات يُكتشف في الكود الحالي، لكن مرور الـ commits يرى فقط التكرار داخل الملف، فتظهر النسخ المكررة عبر الملفات existing ولا تُحسب على أحد.
• إعادة التسمية تقطع الارتباط بالكاتب الأصلي: تظهر المخالفات كأنها أُدخلت (بثقة منخفضة، ولا تُحسب) بواسطة commit إعادة التسمية، الذي يحصل أيضاً على رصيد "fixed" في إجمالياته المعروضة.
• النسخ يُعامل ككود جديد كتبه الناسخ.
• commits الدمج تُتخطى؛ تعديلات حل التعارض داخل commit الدمج لا تُنسب.
• Squash merge وrebase تنسب كل شيء إلى كاتب الـ commit المضغوط.
• البرمجة الثنائية / الكتّاب المشاركون: يُستخدم كاتب الـ commit فقط؛ وأسطر Co-authored-by تُتجاهل.

#التقييم

• الدرجة نسبية لمجموعة القواعد وللمشروع. الدرجات من مجموعات قواعد أو مستودعات مختلفة غير قابلة للمقارنة.
• العينات الصغيرة تُسحب نحو متوسط المشروع؛ هذا مقصود، لكنه يعني أن درجة المطوّر الجديد تقول عن المشروع أكثر مما تقول عنه.
• scoring.severityWeights لا يغيّر الدرجات حالياً (استخدم severity للقاعدة).

#الإعدادات

• في إضافة VS Code، عدة إعدادات في VS Code تتجاوز ملف الإعدادات حتى بقيمها الافتراضية؛ انظر 10 — الأولوية.
• ملف التخصيص المحلي لا يُتحقق منه.
• مساحات العمل متعددة المجلدات: يُحلَّل المجلد الأول فقط.

#الاستخدام المسؤول

CleanLens تقيس الكود، وليس الأشخاص. قبل مشاركة الدرجات مع فريق:

• اعرض الدرجة مع الدرجات الفرعية، والثقة، والمساهمة، ومجموعة القواعد؛
• لا تقارن الدرجات insufficient / provisional؛
• تذكّر أن بعض العمل (المراجعات، والتصميم، والتوجيه، والبنية التحتية، واللغات الأخرى) غير مرئي لها؛
• استخدمها لمعرفة أين يمكن التحسين، وليس كتقييم أداء بمفردها.

---

#حل المشاكل

#"This project is not a Git repository."

افتح جذر المستودع (المجلد الذي فيه .git)، أو مرّره لأداة سطر الأوامر: cleanlens /path/to/repo. في VS Code يُستخدم أول مجلد في مساحة العمل فقط.

#"The repository has no commits."

أنشئ commit واحداً على الأقل. النسب مبني على الـ commits.

#".clean-code-tracker.json is invalid: …"

اقرأ الأخطاء المذكورة. الأسباب الشائعة: "version" ليست 1؛ أو خطأ إملائي في معرّف قاعدة؛ أو خطورة مثل "error" بدلاً من low|medium|high|critical؛ أو تعليقات أو فواصل زائدة في النهاية (يجب أن يكون الملف JSON صارماً).

#"No .clean-code-tracker.json found; using default rules."

مجرد تحذير. شغّل CleanLens: Initialize Project، أو تجاهله لاستخدام إعداد JavaScript المسبق.

#الكل يظهر "existing" ولا أحد أدخل مخالفات

• نافذة الـ commits صغيرة جداً أو حديثة جداً: جرّب --full-history (سطر الأوامر) أو cleanlens.analysis.maxCommits: 0 ‏(VS Code).
• نسخة سطحية (شائعة في الـ CI): استخدم fetch-depth: 0.
• معظم المخالفات تكرار عبر الملفات (لا يمكن نسبه، انظر أعلاه).

#شخص واحد يظهر مرتين

أضف إدخالاً في developers أو سطراً في .mailmap. انظر 11 — دليل الضبط والتخصيص §5.

#شخصان مختلفان دُمجا في واحد

يشتركان في الاسم، أو في الاسم المضغوط، أو في مُعرّف البريد. اضبط mergeSameNameAuthors: false (وفي VS Code الإعداد أيضاً) وأدرج عمليات الدمج الحقيقية صراحة.

#مطوّر لديه "— (no analysed code)"

ليس لديه أسطر مضافة في ملفات قابلة للتحليل داخل النافذة (مثلاً عدّل فقط التوثيق أو الإعدادات أو ملفات القفل، أو كل commits قديمة). هذا ليس مثل الدرجة الكاملة.

#درجات الجميع منخفضة جداً (أو عالية جداً)

قم بالمعايرة: ابحث أولاً عن أكثر القواعد إزعاجاً، ثم عدّل مقياس الفئة المنخفضة عند الجميع. انظر 11 — دليل الضبط والتخصيص §11.

#غيّرت إعداداً في ملف الإعدادات لكن الإضافة تتجاهله

بعض إعدادات VS Code تتجاوز الملف (analysis.maxCommits وscoring.minLinesForRanking وخيارات الاستثناء وmergeSameNameAuthors). اضبطها في إعدادات VS Code أيضاً.

#التحليل بطيء

أبقِ الذاكرة المؤقتة مفعّلة؛ واستثنِ كود المكتبات الخارجية والكود المولَّد؛ واستخدم نافذة أصغر للاستخدام اليومي. انظر 09 — التخزين المؤقت والأداء.

#النتائج تبدو قديمة بعد تغيير القواعد

لا ينبغي ذلك: أي تغيير في القواعد أو الاستثناءات أو التقييم يلغي الذاكرة المؤقتة. إذا غيّرت كود المحللات نفسه، ارفع ENGINE_VERSION أو شغّل مع --no-cache / cleanlens.cache.enabled: false، أو احذف ملفات الذاكرة المؤقتة commits-*.json.

#خطوط تحت الكود في ملف استثنيته

التنبيهات المباشرة لا تطبّق قائمة الاستثناءات. عطّل cleanlens.liveDiagnostics، أو تجاهلها؛ فهي لا تؤثر في التقرير.

#الإضافة لا تفعل شيئاً في نافذة جديدة

تحقق من أن مساحة العمل موثوقة (الوضع المقيّد يعطّل الإضافة).

---

#الأسئلة الشائعة

هل ترسل CleanLens الكود الخاص بي إلى أي مكان؟ لا. تشغّل git وتقرأ الملفات محلياً. لا اتصال بالشبكة، ولا قياس استخدام. انظر PRIVACY.md.

هل تعدّل الكود الخاص بي؟ لا. الملف الوحيد الذي تكتبه في مستودعك هو .clean-code-tracker.json، وفقط بعد أن تؤكد Initialize Project.

لماذا تختلف درجتي عن تشغيل زميلي؟ إعدادات مختلفة (تخصيص محلي، أو إعدادات VS Code، أو إعداد مسبق)، أو نافذة commits مختلفة، أو عمق نسخ مختلف. قارن analysisConfigHash وanalyzedCommits في التقريرين.

لماذا "المخالفات الجديدة" أكثر من عدد مخالفاتي الموجودة في الكود الآن؟ "الجديدة" رقم تاريخي: يحسب كل ما أدخلته في النافذة، بما فيه ما أُصلح لاحقاً (بواسطتك أو بواسطة غيرك).

لماذا المساهمة ليست جزءاً من الدرجة؟ خلط الحجم بالجودة سيكافئ كتابة كود أكثر بدلاً من كود أنظف. يُعرضان جنباً إلى جنب عن قصد.

هل يمكنني استخدام نتائج ESLint / Ruff بدلاً منها؟ ليس حالياً. الحقل source يحجز القيم eslint وruff وpylint لتكامل مستقبلي.

هل يمكنني تحليل مجلد واحد فقط من مستودع موحّد؟ استثنِ الباقي بأنماط exclude. مرور الـ commits يعمل على سجل المستودع كله لكنه يتخطى المسارات المستثناة.

هل توجد نسخة عربية أو تركية من التوثيق؟ نعم. هذا التوثيق متوفر بالعربية (ar/) وبالتركية (tr/)، والموقع يعرض النسخة المطابقة للغته. وصفحة المنتج متوفرة أيضاً بالعربية (README.ar.md).