إضافة VS Code

الإضافة هي الطبقة الخاصة بـ vscode حول المحرّك المشترك. الكود: src/extension.ts وsrc/views/.

#التفعيل

• حدث التفعيل: onStartupFinished. تُحمَّل الإضافة بعد بدء VS Code، دون إبطاء بدء التشغيل.
• الثقة في مساحة العمل: مساحات العمل غير الموثوقة غير مدعومة، لأن الإضافة تشغّل git في المشروع.
• مساحات العمل متعددة المجلدات: يُستخدم المجلد الأول فقط.

عند التفعيل تقوم بما يلي:

1. تنشئ ReportStore (يحفظ آخر تقرير في الذاكرة) وDiagnosticsManager؛
2. تسجّل العروض الثلاثة في الشريط الجانبي والأوامر الأربعة؛
3. تبدأ التنبيهات المباشرة: تحمّل الإعدادات، وتراقب تغييرات .clean-code-tracker.json / .clean-code-tracker.local.json، وتستمع لأحداث المحرر.

التقارير تُحفظ في الذاكرة فقط. إغلاق VS Code يحذفها؛ والذاكرة المؤقتة لكل commit على القرص تجعل التشغيل التالي سريعاً.

#الأوامر

يظهر Run Analysis وOpen Dashboard أيضاً كأيقونتي ▶ ولوحة معلومات في شريط عنوان عرض Dashboard في الشريط الجانبي.

#تفاصيل Run Analysis

1. يقرأ إعدادات VS Code ‏(readSettings())، انظر 10 — مرجع الإعدادات.
2. يستدعي analyzeRepository() بالإعدادات، ومجلد الذاكرة المؤقتة (globalStorageUri)، وAbortSignal مرتبط بزر Cancel.
3. يعرض المراحل في الإشعار: Reading rules ← Reading Git history ← Scanning files (n/N) ← Analyzing commits (n/N).
4. التحذيرات (مثل "No config found; using default rules") تظهر كرسائل تحذير.
5. الأخطاء المتوقعة (ليس مستودعاً، لا commits، إعدادات غير صالحة) تظهر كرسائل خطأ.
6. عند النجاح: يحفظ التقرير، ويستبدل كل التنبيهات، ويفتح لوحة المعلومات، ويعرض ملخصاً: N developers · M violations (U unattributed) · F files.

#عروض الشريط الجانبي

أيقونة CleanLens في شريط الأنشطة تفتح ثلاثة عروض (treeProviders.ts):

#Dashboard

قائمة ملخصة: المطورون، وإجمالي المخالفات، وغير المنسوبة، والملفات المحللة، والـ commits المحللة، ووقت آخر تحليل. قبل التشغيل الأول تعرض "No analysis yet".

#Developers

عقدة لكل مطوّر:

• العنوان: الاسم المعروض.
• الوصف: score/100 · N new · X% contrib، مع · not ranked عندما يكون تحت حد الترتيب.
• التلميح: الدرجات الفرعية، والأسطر المحللة، والثقة، وأعداد الجديدة/المُصلحة/الموجودة سابقاً/غير المنسوبة، والنقاط الموزونة، وصافي الأثر على الجودة، والمساهمة، وأول/آخر مساهمة، والعناوين.
• العناصر الفرعية: المخالفات المحسوبة على ذلك المطوّر، الأخطر أولاً (حتى 500). انقر واحدة لفتح الملف على ذلك السطر.
• تظهر عقدة إضافية Unattributed عندما تكون هناك مخالفات تعذّر نسبها.

#Violations

كل مخالفة في التقرير (حتى 1,000)، مرتبة حسب الخطورة، بالشكل [severity] Rule title — path:line. التلميح يعرض الرسالة؛ والنقر يفتح الموقع.

#لوحة المعلومات

webview ‏(dashboardPanel.ts وdashboardHtml.ts).

المحتوى:

• مربعات الإحصاءات: المطورون، والمخالفات، وغير المنسوبة، والملفات، والـ commits، وآخر تحليل.
• بطاقات المطورين، مرتبة حسب الدرجة الأدنى أولاً، وغير القابلين للترتيب في الآخر. كل بطاقة فيها شريط درجة (أخضر ≥ 80، وكهرماني 50–79، وأحمر < 50)، والدرجات الفرعية الثلاث، وملاحظة "Not ranked" عند الحاجة، والأسطر المحللة، والثقة، والمساهمة، والجديدة/المُصلحة، والموجودة سابقاً/غير المنسوبة، والمخالفات الموزونة، وصافي الأثر على الجودة، وأيام النشاط.
• "How the Clean Code Score is measured": شرح مختصر للمعادلة.
• جدول المخالفات: الخطورة، والقاعدة، والحالة/الثقة، و"من أدخلها"، والموقع.
  • مربع بحث يصفّي حسب الملف والقاعدة واسم المطوّر.
  • مربعات اختيار الخطورة تصفّي حسب الخطورة.
  • ترقيم الصفحات: 10 صفوف لكل صفحة.
  • النقر على الموقع يفتح الملف على ذلك السطر.
• زر Re-run analysis.

ملاحظات تقنية:

• لوحة واحدة في كل مرة؛ فتحها مرة أخرى يُظهر اللوحة الموجودة.
• retainContextWhenHidden يحفظ الفلاتر والصفحة عند التنقل بين التبويبات.
• سياسة أمان محتوى (CSP) صارمة: لا موارد خارجية، وأنماط مضمّنة، والسكربت المضمّن الوحيد المسموح هو الموسوم بـ nonce.
• تستخدم متغيرات سمة VS Code، فتتلاءم مع السمات الفاتحة والداكنة وعالية التباين.
• مولّد الـ HTML دالة خالصة (renderDashboardDocument(report, { nonce, standalone })). مع standalone: true يضيف ألواناً احتياطية حتى يمكن عرض الصفحة خارج VS Code (تُستخدم لالتقاط الصور).
• الرسائل من الـ webview: ‏{ type: "run" } و{ type: "open", file, line }.

#التنبيهات داخل المحرر

diagnostics.ts يملك مجموعة التنبيهات cleanlens. تظهر التنبيهات في المحرر (خطوط تحت الكود) وفي لوحة Problems بالمصدر CleanLens ومعرّف القاعدة كرمز.

تحويل الخطورة:

الخط يغطي مدى أسطر النتيجة كاملاً (مثلاً الدالة الطويلة كلها).

#تغذيتان

كيف تتفاعلان:

• عندما تكون التنبيهات المباشرة مفعّلة والإعدادات محمّلة، يعرض الملف المفتوح نتائجه المباشرة. وهي تحل محل نتائج التقرير الكامل لذلك الملف ما دام مفتوحاً.
• عند إغلاق الملف، أو إيقاف التنبيهات المباشرة، أو تعذّر تحميل الإعدادات، يعود الملف إلى نتائج آخر تقرير كامل (أو لا شيء).
• إذا تعذّر تحليل المحتوى أثناء الكتابة، تبقى التنبيهات السابقة.
• تُفحص فقط الملفات داخل مجلد مساحة العمل، بامتداد مدعوم وعنوان file:.
• التغذية المباشرة لا تطبّق قائمة الاستثناءات ولا تقوم بالنسب. إنها حلقة تغذية راجعة سريعة، وليست تقريراً.
• تعديل ملف الإعدادات أو ملف التخصيص المحلي يعيد تحميل القواعد ويعيد فحص كل الملفات المفتوحة فوراً.

الإعداد: cleanlens.liveDiagnostics (افتراضياً true). الاسم القديم cleanCodeTracker.liveDiagnostics ما زال يُقرأ إذا ضُبط صراحة.

#أين تحفظ الإضافة البيانات

#تنقيح الإضافة

اضغط F5 في هذا المستودع. إعداد التشغيل Run Extension يبني أولاً (npm: build) ثم يفتح Extension Development Host. انظر 15 — دليل التطوير.