مرجع الإعدادات

كل مفتاح في .clean-code-tracker.json، وملف التخصيص المحلي، وإعدادات VS Code، وخيارات سطر الأوامر، وأيها يغلب

6 دقائق قراءة7 أقسام

يمكن ضبط CleanLens في أربعة أماكن:

المكان	النطاق	من يستخدمه
`.clean-code-tracker.json`	المشروع؛ أضفه إلى المستودع لمشاركته مع الفريق	الإضافة + سطر الأوامر
`.clean-code-tracker.local.json`	شخصي؛ يتجاهله git	الإضافة + سطر الأوامر (ليس مع `--preset`)
إعدادات VS Code ‏(`cleanlens.*`)	المستخدم أو مساحة العمل	الإضافة فقط
خيارات سطر الأوامر	تشغيل واحد	سطر الأوامر فقط

هذا الملف يسرد كل خيار. لمعرفة أي القيم تختار، انظر 11 — دليل الضبط والتخصيص.

1. `.clean-code-tracker.json`

يوجد في جذر المستودع. أنشئه بالأمر CleanLens: Initialize Project أو يدوياً. إذا لم يكن موجوداً، يُستخدم الإعداد المسبق javascript ويظهر تحذير.

مثال كامل (كل المفاتيح)

json

{
  "version": 1,
  "rules": {
    "maxFunctionLines":  { "enabled": true, "severity": "medium", "limit": 40 },
    "maxFileLines":      { "enabled": true, "severity": "medium", "limit": 400 },
    "maxParameters":     { "enabled": true, "severity": "medium", "limit": 5 },
    "maxComplexity":     { "enabled": true, "severity": "high",   "limit": 10 },
    "maxNestingDepth":   { "enabled": true, "severity": "high",   "limit": 4 },
    "detectDuplicateCode": { "enabled": true, "severity": "medium", "options": { "minLines": 6 } },
    "detectUnusedCode":  { "enabled": true, "severity": "low" },
    "requireClearVariableNames": { "enabled": true, "severity": "low" },
    "requireErrorHandling":      { "enabled": true, "severity": "medium" },
    "forbidEmptyCatchBlocks":    { "enabled": true, "severity": "high" },
    "forbidHardcodedSecrets":    { "enabled": true, "severity": "critical" },
    "forbidDebugStatements":     { "enabled": true, "severity": "low" },
    "requireSingleResponsibility": { "enabled": true, "severity": "medium", "options": { "maxMethods": 10 } },
    "requireDocumentationForComplexCode": { "enabled": true, "severity": "low", "options": { "complexityThreshold": 15 } }
  },
  "exclude": ["node_modules/**", "dist/**", "*.min.js", "scripts/**"],
  "excludeGenerated": true,
  "excludeMigrations": true,
  "excludeLockFiles": true,
  "mergeSameNameAuthors": true,
  "developers": [
    { "displayName": "Musa Alahmed", "emails": ["musa@work.com", "musa.personal@gmail.com"] }
  ],
  "analysis": {
    "maxCommits": 500,
    "since": "2026-01-01"
  },
  "scoring": {
    "categoryScales": { "duplication": 15, "structure": 45, "hygiene": 38 },
    "weights": { "duplication": 0.3, "structure": 0.45, "hygiene": 0.25 },
    "minLinesForRanking": 1000
  }
}

المفاتيح

المفتاح	النوع	الافتراضي	الوصف
`version`	`1`	— (إلزامي)	نسخة البنية. يجب أن تكون `1` بالضبط.
`rules`	كائن	— (إلزامي)	إدخال لكل معرّف قاعدة. المعرّفات غير المعروفة خطأ. القاعدة غير الموجودة تكون معطلة. انظر 06.
`rules.<id>.enabled`	منطقي	— (إلزامي)	تشغيل القاعدة أو إيقافها.
`rules.<id>.severity`	`low`/`medium`/`high`/`critical`	— (إلزامي)	الوزن 1/3/5/8؛ وأيضاً مستوى التنبيه في المحرر.
`rules.<id>.limit`	رقم > 0	حسب القاعدة	الحد للقواعد الرقمية.
`rules.<id>.options`	`{ [k]: number \| boolean }`	حسب القاعدة	`minLines` و`maxMethods` و`complexityThreshold`.
`exclude`	مصفوفة نصوص	`[]`	أنماط glob إضافية. تُضاف إلى القائمة المدمجة، ولا تستبدلها أبداً. انظر 05 — صيغة glob.
`excludeGenerated`	منطقي	`true`	تخطي ملفات `linguist-generated` والملفات التي تقول أسطرها الخمسة الأولى "generated" / "do not edit".
`excludeMigrations`	منطقي	`true`	استثناء `/migrations/`.
`excludeLockFiles`	منطقي	`true`	استثناء `package-lock.json` و`yarn.lock` و`pnpm-lock.yaml`.
`mergeSameNameAuthors`	منطقي	`true`	دمج الهويات التي تبدو لنفس الشخص تلقائياً. انظر 04.
`developers`	`{ displayName, emails[] }[]`	`[]`	إجبار عناوين بريد على أن تكون مطوّراً واحداً باسم عرض ثابت.
`analysis.maxCommits`	رقم ≥ 0	`500`	إعادة تشغيل أحدث N من الـ commits غير الدمجية. `0` = السجل كاملاً.
`analysis.since`	نص	لا يوجد	إعادة تشغيل الـ commits بعد هذا التاريخ فقط. أي قيمة يقبلها `git log --since`.
`scoring.categoryScales`	`{ duplication?, structure?, hygiene? }`	15 / 45 / 38	الكثافة التي تنخفض عندها الدرجة الفرعية إلى حوالي 37. الأكبر = أكثر تساهلاً.
`scoring.weights`	`{ duplication?, structure?, hygiene? }`	0.30 / 0.45 / 0.25	حصة كل درجة فرعية في الدرجة النهائية. يجب أن يكون مجموعها 1.
`scoring.minLinesForRanking`	رقم	`1000`	الأسطر المحللة المطلوبة لدخول الترتيب.
`scoring.severityWeights`	`{ low?, medium?, high?, critical? }`	1 / 3 / 5 / 8	مقبول، لكنه لا يؤثر حالياً في الدرجات (انظر 08). استخدم `severity` للقاعدة بدلاً منه.

الكائنات الجزئية مقبولة في scoring.*: المفاتيح الناقصة تحتفظ بقيمها الافتراضية.

التحقق

يُتحقق من الملف عند تحميله (configValidator.ts). أي خطأ يوقف التحليل مع قائمة بكل المشاكل، مثلاً:

text

.clean-code-tracker.json is invalid:
- Rule "maxComplexity": "severity" must be one of critical | high | medium | low.
- Unknown rule: "maxLineLength". Supported rules: maxFunctionLines, …

ما يُفحص: version === 1؛ وrules كائن من معرّفات معروفة، لكل منها enabled منطقي، وseverity صالحة، وlimit موجب إن وُجد، وoptions أرقام/قيم منطقية؛ وexclude مصفوفة نصوص؛ والخيارات الأربعة منطقية؛ وdevelopers بالشكل الصحيح؛ وscoring وanalysis كائنات؛ وanalysis.maxCommits رقم غير سالب؛ وanalysis.since نص.

يجب أن يكون الملف JSON صارماً (بلا تعليقات ولا فواصل زائدة في النهاية).

2. `.clean-code-tracker.local.json`

تخصيص شخصي، يتجاهله .gitignore في هذا المستودع (أضفه إلى مستودعك أيضاً). يُقرأ منه مفتاحان فقط:

المفتاح	السلوك
`rules`	كل إدخال يُدمج دمجاً سطحياً مع قاعدة المشروع: `{ ...project, ...local }`
`exclude`	يُضاف إلى قائمة المشروع

مثال — إسكات قاعدتين لنفسك، وتخطي مجلد تجارب:

json

{
  "rules": {
    "forbidDebugStatements": { "enabled": false },
    "maxComplexity": { "limit": 15 }
  },
  "exclude": ["playground/**"]
}

ملاحظات:

الملف المحلي لا يُتحقق منه. خطأ إملائي في معرّف قاعدة يضيف قاعدة مجهولة لا يقرؤها شيء. تحقق من الكتابة جيداً.
المفاتيح الأخرى (scoring وanalysis وdevelopers، …) تُتجاهل.
التخصيص المحلي يغيّر بصمة الإعدادات، فيلغي ذاكرتك المؤقتة أيضاً.
التخصيصات المحلية تجعل أرقامك مختلفة عن أرقام زملائك. استخدمها للتجارب، وليس للتقارير الرسمية.

3. إعدادات VS Code

اضبطها من Settings ← Extensions ← CleanLens، أو في settings.json (للمستخدم، أو .vscode/settings.json لمساحة العمل).

الإعداد	النوع	الافتراضي	يقابل
`cleanlens.liveDiagnostics`	منطقي	`true`	إعادة فحص الملفات المفتوحة أثناء الكتابة
`cleanlens.exclude`	مصفوفة نصوص	`[]`	يُضاف إلى `exclude`
`cleanlens.excludeGenerated`	منطقي	`true`	`excludeGenerated`
`cleanlens.excludeMigrations`	منطقي	`true`	`excludeMigrations`
`cleanlens.excludeLockFiles`	منطقي	`true`	`excludeLockFiles`
`cleanlens.mergeSameNameAuthors`	منطقي	`true`	`mergeSameNameAuthors`
`cleanlens.analysis.maxCommits`	رقم	`500`	`analysis.maxCommits`
`cleanlens.analysis.since`	نص	`""`	`analysis.since` (الفارغ = غير محدد)
`cleanlens.scoring.minLinesForRanking`	رقم	`1000`	`scoring.minLinesForRanking`
`cleanlens.cache.enabled`	منطقي	`true`	استخدام الذاكرة المؤقتة لكل commit
`cleanCodeTracker.liveDiagnostics`	منطقي	`true`	اسم قديم لـ `cleanlens.liveDiagnostics`؛ يُقرأ فقط إذا ضُبط صراحة

مثال على settings.json لمساحة العمل:

json

{
  "cleanlens.analysis.maxCommits": 0,
  "cleanlens.exclude": ["scripts/**", "**/fixtures/**"],
  "cleanlens.scoring.minLinesForRanking": 500
}

4. خيارات سطر الأوامر

الخيار	الأثر
`[path]`	المستودع المراد تحليله (افتراضياً: المجلد الحالي)
`--preset <name>`	استخدام إعداد مسبق (`javascript`/`react`/`python`/`django`) بدلاً من ملفي الإعدادات
`--max-commits <n>`	يتجاوز `analysis.maxCommits`
`--full-history`	مثل `--max-commits 0`
`--since <date>`	يتجاوز `analysis.since`
`--no-cache`	تعطيل الذاكرة المؤقتة
`--json` و`--markdown` و`--violations` و`--fail-on <sev>`	المخرجات ورمز الخروج؛ انظر 13 — أداة سطر الأوامر

5. الأولوية — أي قيمة تغلب

في سطر الأوامر

text

built-in defaults
  ◀ .clean-code-tracker.json         (or --preset, which replaces both files)
  ◀ .clean-code-tracker.local.json   (rules + exclude only; skipped with --preset)
  ◀ --max-commits / --full-history / --since

أي: الافتراضيات المدمجة، ثم ملف المشروع (أو --preset الذي يحل محل الملفين)، ثم الملف المحلي (القواعد والاستثناءات فقط، ويُتخطى مع --preset)، ثم خيارات سطر الأوامر، والأخير يغلب.

في إضافة VS Code

text

built-in defaults
  ◀ .clean-code-tracker.json
  ◀ .clean-code-tracker.local.json   (rules + exclude only)
  ◀ VS Code settings

مهم: في الإضافة، إعدادات VS Code التالية تغلب ملف الإعدادات دائماً، حتى لو لم تغيّرها، لأن القيمة الافتراضية للإعداد تُستخدم كقيمة:

excludeGenerated وexcludeMigrations وexcludeLockFiles وmergeSameNameAuthors وanalysis.maxCommits وscoring.minLinesForRanking.

مثلاً، "analysis": { "maxCommits": 0 } في ملف الإعدادات تحترمه أداة سطر الأوامر لكن الإضافة تتجاهله، وتستخدم cleanlens.analysis.maxCommits (‏500 افتراضياً). للحصول على نفس النتيجة في الاثنين، اضبط القيمة في المكانين، أو استخدم .vscode/settings.json لمساحة العمل وأضفه إلى المستودع بجانب ملف الإعدادات.

exclude يُجمع في كل مكان. وanalysis.since من VS Code يُطبق فقط إذا لم يكن فارغاً. وscoring.categoryScales وscoring.weights تأتيان من ملف الإعدادات فقط.

جدول سريع

الخيار	ملف الإعدادات	الملف المحلي	إعداد VS Code	خيار سطر الأوامر
rules	✅	✅ (يُدمج)	—	`--preset` يستبدلها
exclude	✅	✅ (يُضاف)	✅ (يُضاف)	—
excludeGenerated / Migrations / LockFiles	✅ (سطر الأوامر)	—	✅ (يغلب)	—
mergeSameNameAuthors	✅ (سطر الأوامر)	—	✅ (يغلب)	—
developers	✅	—	—	—
analysis.maxCommits	✅ (سطر الأوامر)	—	✅ (يغلب)	✅ (يغلب)
analysis.since	✅	—	✅ إذا لم يكن فارغاً	✅ (يغلب)
scoring.categoryScales / weights	✅	—	—	—
scoring.minLinesForRanking	✅ (سطر الأوامر)	—	✅ (يغلب)	—
الذاكرة المؤقتة	—	—	✅	`--no-cache`
التنبيهات المباشرة	—	—	✅	—

6. ملفات أخرى تقرؤها CleanLens

الملف	يُستخدم لـ
`.gitignore` (في الجذر فقط)	يُضاف إلى قائمة الاستثناءات (بأفضل جهد، بلا نفي)
`.gitattributes` (في الجذر فقط)	مسارات `linguist-generated` تُستثنى
`.mailmap`	يطبّقه Git نفسه على أسماء الكتّاب وعناوينهم
`manage.py` و`pyproject.toml` و`requirements.txt` و`setup.py` و`package.json`	اقتراح الإعداد المسبق في Initialize Project

7. الإعدادات المسبقة

الإعداد المسبق	القواعد	استثناءات إضافية (فوق القائمة الأساسية)
`javascript`	القواعد الأساسية	—
`react`	القواعد الأساسية	`.stories.` و`storybook-static/` و`/__tests__/*` و`.test.` و`.spec.*`
`python`	القواعد الأساسية	`__pycache__/*` و`.pyc` و`.mypy_cache/` و`.pytest_cache/` و`/tests/` و`test_*.py` و`conftest.py`
`django`	القواعد الأساسية، و`maxFileLines.limit` = 500	قائمة Python + `/migrations/` و`manage.py`

قائمة الاستثناءات الأساسية في كل إعداد مسبق: node_modules/** و.venv/** وvenv/** وmigrations/** وdist/** وbuild/** وcoverage/** وstaticfiles/** و*.min.js و*.generated.*.

#1. .clean-code-tracker.json

#مثال كامل (كل المفاتيح)

#المفاتيح

#التحقق

#2. .clean-code-tracker.local.json

#3. إعدادات VS Code

#4. خيارات سطر الأوامر

#5. الأولوية — أي قيمة تغلب

#في سطر الأوامر

#في إضافة VS Code

#جدول سريع

#6. ملفات أخرى تقرؤها CleanLens

#7. الإعدادات المسبقة

1. `.clean-code-tracker.json`

مثال كامل (كل المفاتيح)

المفاتيح

التحقق

2. `.clean-code-tracker.local.json`

3. إعدادات VS Code

4. خيارات سطر الأوامر

5. الأولوية — أي قيمة تغلب

في سطر الأوامر

في إضافة VS Code

جدول سريع

6. ملفات أخرى تقرؤها CleanLens

7. الإعدادات المسبقة