02

البدء

تثبيت الإضافة وأداة سطر الأوامر وتشغيلهما لأول مرة

2 دقائق قراءة5 أقسام

المتطلبات

المتطلبالسبب
Git موجود في PATHكل تحليل يشغّل git log وgit diff وgit cat-file.
مجلد هو مستودع Git فيه commit واحد على الأقلالنسب مبني على الـ commits. بدونها يتوقف التحليل برسالة خطأ.
VS Code ‏1.90 أو أحدث (للإضافة)محدد في engines.vscode.
Node.js ‏20 أو أحدث (لأداة سطر الأوامر)محدد في engines.node.
مساحة عمل موثوقة (للإضافة)الإضافة تشغّل أوامر Git، لذلك تتعطل في الوضع المقيّد (Restricted Mode).

الخيار أ — إضافة VS Code

التثبيت

  • من المتجر: ابحث عن CleanLens (المعرّف cleanlens.cleanlens)، أو
  • من نسخة مبنية محلياً: شغّل npm run package ثم Extensions ← … ← Install from VSIX.

التشغيل الأول

  1. افتح مجلد المشروع (جذر المستودع) في VS Code.
  2. شغّل CleanLens: Initialize Project من لوحة الأوامر (Cmd/Ctrl+Shift+P).
    • تقترح CleanLens إعداداً مسبقاً بحسب الملفات في الجذر: manage.py ← Django؛ وpyproject.toml / requirements.txt / setup.py ← Python؛ وغير ذلك ← JavaScript.
    • اختر الإعداد، وراجع المعاينة، واضغط Create.
    • هذا يكتب الملف .clean-code-tracker.json في الجذر ويفتحه. لا يستبدل أبداً ملفاً موجوداً.
  3. راجع القواعد (انظر 06 — مرجع القواعد).
  4. شغّل CleanLens: Run Analysis (أو زر ▶ في الشريط الجانبي لـ CleanLens). يظهر إشعار تقدّم يعرض كل مرحلة، ويمكنك إلغاؤه.
  5. تُفتح لوحة المعلومات تلقائياً. وتمتلئ عروض Dashboard وDevelopers وViolations في الشريط الجانبي، وتظهر خطوط تحت كل مخالفة في المحرر.

أثناء كتابة الكود

التنبيهات المباشرة مفعّلة افتراضياً: كل ملف JS/TS/Python مفتوح يُعاد فحصه بعد 400 ملّي ثانية من توقفك عن الكتابة، باستخدام القواعد التي تعمل على مستوى الملف. انظر 12 — إضافة VS Code.

الخيار ب — أداة سطر الأوامر

البناء والتشغيل من هذا المستودع

bash
npm install
npm run build
node dist/cli.js /path/to/repo

بعد تثبيتها كحزمة

bash
cleanlens                       # تحليل المجلد الحالي
cleanlens ./my-project --violations
cleanlens --markdown > report.md
cleanlens --json > report.json
cleanlens --preset django --fail-on high

أداة سطر الأوامر تقرأ نفس الملف .clean-code-tracker.json الذي تقرؤه الإضافة. الخيار --preset يتجاهل هذا الملف ويستخدم إعداداً مسبقاً مدمجاً بدلاً منه. انظر 13 — أداة سطر الأوامر لكل الخيارات.

قراءة تقريرك الأول

التقرير النصي يبدو هكذا (القيم للتوضيح فقط):

text
Developers: 3
Analyzed files: 84
Analyzed commits: 500
Total violations: 212
Unattributed: 0

Alice
  Clean Code Score: 78/100
    duplication 88 · structure 70 · hygiene 82
  Analyzed Lines: 12,400
  Confidence: Highly reliable
  Contribution: 61%
  New Violations: 64
  Fixed Violations: 21
  ...

كيف تقرؤه:

  • Score تقيس الجودة: كلما ارتفعت كان الكود أنظف. Contribution تقيس الحجم. اقرأهما منفصلتين.
  • الدرجات الفرعية الثلاث تبيّن أين توجد المشاكل.
  • Confidence تخبرك بحجم الكود الذي بُنيت عليه الدرجة. تعامل بحذر مع الدرجات Insufficient وProvisional.
  • أعداد Existing وUnattributed للمعلومة فقط. لا تخفض الدرجة أبداً.
  • المطورون تحت حد الترتيب يظهرون تحت "Not ranked".

الخطوات التالية