دليل التطوير

كيف تبني CleanLens وتختبرها وتنقّحها وتصدرها، وكيف توسّعها.

#الإعداد

git clone https://github.com/MUSAALAHMED4/CleanLens.git
cd CleanLens
npm install

يتطلب Node.js ‏20 أو أحدث، وGit.

#السكربتات

vscode:prepublish / prepublishOnly يبنيان حزماً مصغّرة تلقائياً قبل التحزيم أو النشر.

#هيكل المشروع

CleanLens/
├── src/                 source (see 03 — Architecture for the module map)
├── test/                node:test suites (run with tsx, no build needed)
├── dist/                build output (git-ignored)
├── docs/                this documentation + RULES.md + PRIVACY.md
├── media/               icons and screenshots
├── website/             marketing site (separate Next.js app; see 16)
├── .github/workflows/   CI
├── .vscode/             launch + build task for F5 debugging
├── package.json         manifest: extension contributions, bin, scripts
├── tsconfig.json        strict, ES2022, Node16 modules
├── .eslintrc.json       eslint:recommended + @typescript-eslint/recommended
├── README.md / README.ar.md   product page (EN / AR)
├── CHANGELOG.md         release notes
└── Clean_Code_Tracker_Plan.md  original design plan

• src/ الكود المصدري (انظر 03 — البنية المعمارية لخريطة الوحدات).
• test/ اختبارات node:test (تعمل بـ tsx، بلا بناء).
• dist/ مخرجات البناء (يتجاهلها git).
• docs/ هذا التوثيق مع RULES.md وPRIVACY.md، وترجماته في docs/ar/ وdocs/tr/.
• website/ موقع التعريف (تطبيق Next.js منفصل؛ انظر 16).

#التنقيح

• الإضافة: اضغط F5. إعداد Run Extension يشغّل مهمة npm: build ثم يفتح Extension Development Host والإضافة محمّلة فيه. افتح أي مستودع Git في تلك النافذة وشغّل الأوامر.
• سطر الأوامر: npm run build:cli && node dist/cli.js /path/to/repo، أو استخدم npx tsx src/cli/index.ts /path/to/repo بدون بناء.
• HTML لوحة المعلومات: ‏renderDashboardDocument(report, { nonce: "x", standalone: true }) تعيد صفحة يمكنك فتحها في المتصفح.

#الاختبارات

تستخدم الاختبارات مشغّل node:test المدمج في Node وtsx. لا حاجة لنسخة VS Code: الكود المختبَر لا يستورد vscode.

اختبارات التكامل تنشئ مستودعات بـ git init في مجلد مؤقت وتستخدم إعدادات git معزولة وفارغة، فلا تعتمد على إعدادات Git العامة عندك. لتشغيل ملف واحد:

node --import tsx --test test/scoring.test.ts

#التكامل المستمر (CI)

.github/workflows/ci.yml يعمل عند كل push إلى main وعلى الـ pull requests، على Ubuntu وWindows وmacOS × Node 22 و24:

npm ci ← typecheck ← lint ← test ← build ← vsce package.

مهمة Ubuntu / Node 24 ترفع ملف .vsix كملف ناتج. Windows موجود عن قصد: فواصل المسارات، ونهايات الأسطر CRLF، وتحويل git.exe سبّبت أخطاء حقيقية من قبل (انظر سجل التغييرات).

#الإصدار

1. ارفع version في package.json؛ وأضف إدخالاً في CHANGELOG.md.
2. تأكد أن الـ CI ناجح.
3. npm run build && npx vsce package --no-dependencies ← cleanlens-<version>.vsix.
4. انشر بـ npx vsce publish (يحتاج PAT للناشر cleanlens) أو ارفع ملف .vsix في بوابة الناشر في المتجر.
5. اختيارياً npm publish لأداة سطر الأوامر (بنفس الإصدار).
6. حدّث EXTENSION_VERSION في website/lib/constants.ts.

قائمة files في package.json تحدد ما يُشحن (في .vsix وفي حزمة npm): الحزمتان، والأيقونات، وREADME.md وCHANGELOG.md وdocs/PRIVACY.md وdocs/RULES.md وLICENSE.txt. بقية ملفات التوثيق في هذا المجلد لا تُشحن؛ أضفها إلى files إذا أردتها في الحزمة.

#أعراف كتابة الكود

• TypeScript بوضع strict. لا any إلا عند الضرورة.
• فقط src/extension.ts وsrc/views/* يُسمح لها باستيراد vscode.
• المحللات دوال خالصة: (relPath, text, config) => RawFinding[].
• كل استدعاء لـ Git يستخدم execFile (بلا shell) ويعالج الفشل صراحة.
• الأرقام القابلة للضبط مكانها src/scoring/scoringConfig.ts (للتقييم) أو كثوابت مسمّاة في أعلى وحدتها.
• ارفع ENGINE_VERSION عندما يغيّر تعديلٌ نتائجَ تحليل كل commit.

#إضافة قاعدة

مثال: قاعدة جديدة maxLineLength.

1. سجّلها في src/configuration/types.ts:
   • أضف "maxLineLength" إلى RULE_IDS؛
   • أضف عنواناً في RULE_TITLES (مثل "Long line")؛
   • أضف فئتها في RULE_CATEGORY (مثل "structure"). بعدها سيشير TypeScript إلى كل مكان يحتاج المعرّف الجديد.
2. أعطها قيماً افتراضية في BASE_RULES في src/configuration/presets.ts: ‏maxLineLength: { enabled: true, severity: "low", limit: 120 }.
3. نفّذها في jsAnalyzer.ts و/أو pyAnalyzer.ts:

   if (on("maxLineLength")) {
     const max = lim("maxLineLength", 120);
     text.split("\n").forEach((line, i) => {
       if (line.length > max) add("maxLineLength", i + 1, `Line has ${line.length} characters (limit ${max}).`);
     });
   }

   مرّر symbolName عندما تنتمي النتيجة إلى دالة أو class؛ هذا يجعل النسب أدق.
4. ارفع ENGINE_VERSION في scoringConfig.ts.
5. اختبرها في test/jsAnalyzer.test.ts (حالات إيجابية وسلبية).
6. وثّقها في docs/RULES.md و06 — مرجع القواعد (بالثلاث لغات)، وجداول القواعد في README (بالإنجليزية والعربية).

ملفات الإعدادات الموجودة لا تذكر القاعدة الجديدة، فتكون معطلة فيها حتى يضيفها المستخدمون (القاعدة غير الموجودة معطلة). والمدقق يقبلها بمجرد إضافتها إلى RULE_IDS.

#إضافة لغة

1. أنشئ src/analyzers/<lang>Analyzer.ts يصدّر analyze<Lang>(filePath, text, config): RawFinding[] وقائمة امتداداته. استخدم ruleEnabled وruleLimit وruleOption من model.ts، وأعد استخدام secrets.ts / names.ts.
2. سجّله في runAnalyzers.ts: أضف الامتدادات إلى ALL_EXTENSIONS وفرعاً في analyzerFor(). فحص HEAD ومرور الـ commits والتنبيهات المباشرة كلها تستخدم analyzerFor()، فلا حاجة لربط أي شيء آخر.
3. تأكد أن fingerprint.ts يحذف صيغة تعليقات السطر في تلك اللغة (حالياً // و#).
4. فكّر في إضافة إعداد مسبق في presets.ts واكتشافه في detectPreset().
5. ارفع ENGINE_VERSION، وأضف اختبارات، وحدّث التوثيق.

#التوثيق والترجمات

التوثيق موجود بثلاث لغات بنفس أسماء الملفات:

docs/*.md      English — the source of truth
docs/ar/*.md   Arabic
docs/tr/*.md   Turkish

الإنجليزية هي المرجع. عندما تغيّر ملفاً إنجليزياً، حدّث الترجمتين في نفس التغيير. قواعد تحافظ على عمل صفحات التوثيق في الموقع (انظر 16):

• أبقِ بنية العناوين متطابقة (نفس عدد العناوين، ونفس المستويات، ونفس الترتيب). الموقع يعطي العناوين المترجمة معرّفات الروابط الإنجليزية حسب موقعها، فتبقى الروابط والعناوين URL متطابقة في كل اللغات.
• الروابط إلى الأقسام تستخدم المعرّفات الإنجليزية في كل اللغات (مثل 08-scoring.md#severity-weights).
• الروابط إلى ملفات خارج docs/ تصعد مستوى إضافياً في الترجمات (../../src/… بدلاً من ../src/…).
• كتل الكود، والمعرّفات، ومعرّفات القواعد، ومفاتيح الإعدادات، ومخرجات سطر الأوامر تبقى بالإنجليزية.
• إذا كان ملف ترجمة مفقوداً، يعرض الموقع الملف الإنجليزي.

#إضافة إعداد في VS Code

1. عرّفه تحت contributes.configuration.properties في package.json.
2. اقرأه في readSettings() في src/extension.ts.
3. إذا كان يقابل مفتاحاً في الإعدادات، أضفه إلى ExtensionSettings وapplySettings() في src/core/analyzeRepository.ts. فضّل القيمة undefined عندما لا يضبطه المستخدم، حتى لا يتجاوز الافتراضيُّ ملفَ الإعدادات.
4. وثّقه في 10 — مرجع الإعدادات.