أداة سطر الأوامر

الأمر cleanlens يشغّل نفس محرّك الإضافة ويطبع التقرير. الكود: src/cli/index.ts وsrc/cli/format.ts.

#الصيغة

cleanlens [path] [options]

path هو المستودع المراد تحليله (افتراضياً: المجلد الحالي). مسموح بمسار واحد فقط.

#الخيارات

إذا أُعطي --json و--markdown معاً، يغلب --json. الخيارات غير المعروفة والقيم غير الصالحة تطبع رسالة خطأ مع نص المساعدة وتخرج بالرمز 2.

#صيغ الإخراج

#نص (الافتراضي)

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
  Existing Violations: 30 (informational)
  Unattributed Violations: 0 (informational)
  Weighted Violations: 190
  Net Quality Impact: +120
  Violation Density: 15.32 / KLOC
  Active days: 88

Not ranked (insufficient analysed code)

  Bob
    Clean Code Score: 71/100
    ...

• المطورون القابلون للترتيب أولاً، مرتبين حسب الدرجة الأدنى أولاً (من يحتاج مساعدة أكثر في الأعلى)، ثم قسم "Not ranked".
• مع --violations تتبعها قائمة: [high] Deep nesting — src/app.ts:120 (introduced/high; Alice).

#Markdown ‏(--markdown)

تقرير مكتفٍ بذاته، مناسب كملف ناتج من الـ CI أو كتعليق على PR:

1. جدول ملخص (وقت الإنشاء، والمحرّك، والملفات، والـ commits، والمخالفات، وغير المنسوبة، والمطورون).
2. معادلة الدرجة وأوزان الخطورة.
3. Severity breakdown (العدد والوزن والنقاط الموزونة لكل خطورة).
4. أعداد Attribution status.
5. Developers: قسم لكل مطوّر فيه جدول مقاييس (الدرجات الفرعية مع الكثافة، والمساهمة، والجديدة/المُصلحة/الموجودة سابقاً/غير المنسوبة، والموزونة، وصافي الأثر، والكثافة، والعناوين، وأيام النشاط، وأول/آخر مساهمة).
6. Files with violations: لكل ملف العدد والخطورة وأرقام الأسطر (أول 40، ثم "+N more").
7. All violations: الخطورة، والقاعدة، والملف:السطر، والحالة، والثقة، ومن أدخلها، والرسالة.

#JSON ‏(--json)

كائن ProjectReport كاملاً ومنسّقاً. استخدمه للوحات المعلومات، أو لمقارنة التشغيلات، أو لأدواتك الخاصة.

#قنوات الإخراج

#رموز الخروج

--fail-on ينظر إلى كل مخالفة في الكود الحالي، أياً كانت حالة نسبها. ترتيب الخطورة: critical > high > medium > low؛ لذلك --fail-on medium يفشل عند medium أو high أو critical.

#الذاكرة المؤقتة

أداة سطر الأوامر تخزّن نتائج كل commit في <os.tmpdir()>/cleanlens-cache/. استخدم --no-cache لتشغيل نظيف قابل للتكرار. انظر 09 — التخزين المؤقت والأداء.

#أمثلة

# تقرير مقروء للمستودع الحالي
cleanlens

# مستودع آخر، مع قائمة المخالفات
cleanlens ../api --violations

# إعداد Django المسبق بدلاً من ملف الإعدادات، والفشل عند high وما فوق
cleanlens --preset django --fail-on high

# السجل كاملاً، بصيغة JSON
cleanlens --full-history --json > report.json

# آخر ربع سنة فقط، بصيغة Markdown
cleanlens --since "3 months ago" --markdown > q3.md

# فحص سريع للعمل الحديث
cleanlens --max-commits 50

#التكامل مع الـ CI

#GitHub Actions

name: Clean Code
on: [pull_request]

jobs:
  cleanlens:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0          # full history: attribution needs commits
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npx cleanlens --markdown > cleanlens-report.md
      - uses: actions/upload-artifact@v4
        with:
          name: cleanlens-report
          path: cleanlens-report.md
      - run: npx cleanlens --fail-on critical

ملاحظات:

• fetch-depth: 0 مهم. النسخة السطحية الافتراضية فيها commit واحد، فلن يكون هناك تقريباً ما يُنسب.
• خطوة البوابة تُفشل المهمة بالرمز 1؛ وخطوة التقرير التي قبلها تنتج الملف رغم ذلك.
• إذا لم تكن أداة سطر الأوامر منشورة على npm في بيئتك، ابنها من هذا المستودع وشغّل node dist/cli.js.

#خطاف pre-commit

#!/bin/sh
# .git/hooks/pre-commit  (chmod +x)
cleanlens --max-commits 20 --fail-on critical || {
  echo "CleanLens: critical violations found (e.g. a hard-coded secret)."
  exit 1
}

هذا يفحص مجلد العمل، وليس التغييرات المجهزة للـ commit فقط. أبقِ الحد على critical حتى لا يمنع الخطاف إلا المشاكل الخطيرة مثل الأسرار.

#متابعة الجودة عبر الزمن

احفظ تقارير --json لكل إصدار أو كل أسبوع وقارن cleanCodeScore وtotalViolations وbreakdown.netQualityImpact لكل مطوّر. أبقِ الإعدادات دون تغيير بين التشغيلات التي تقارنها.