تنسيق وفحص الكود تلقائيًا قبل الالتزامات

[Discourse]

يتعامل Discourse مع خطافات git باستخدام lefthook، ويعتمد على bin/lint كنقطة دخول رئيسية لسطر الأوامر لتشغيل نفس الفحوصات يدوياً.

إذا كنت تعمل في نسخة محلية (clone)، قم بتثبيت الخطافات مرة واحدة:

pnpm install
pnpm lefthook install

بعد ذلك، سيتم فحص الملفات المُجهَّزة (staged) تلقائياً عند تنفيذ git commit.

الأمر الرئيسي: bin/lint

استخدم bin/lint عندما تريد تشغيل أدوات الفحص (linters) المُهيأة في المستودع بنفسك بدلاً من الانتظار حتى خطاف ما قبل التثبيت (pre-commit hook).

أمثلة شائعة:

bin/lint
bin/lint path/to/file.rb path/to/file.gjs
bin/lint --recent
bin/lint --staged
bin/lint --unstaged
bin/lint --wip
bin/lint --fix path/to/file.rb
bin/lint --fix --recent
bin/lint --fix

ما يفعله كل وضع

• bin/lint: يفحص جميع الملفات المدعومة في المستودع
• bin/lint path/to/file ...: يفحص الملفات المحددة فقط
• bin/lint --recent: يفحص الملفات التي تم تغييرها في آخر 50 عملية تثبيت، بالإضافة إلى الملفات غير المتتبَّعة (untracked)
• bin/lint --staged: يفحص الملفات المُجهَّزة (staged) فقط
• bin/lint --unstaged: يفحص الملفات غير المُجهَّزة (unstaged) فقط
• bin/lint --wip: يفحص الملفات المُجهَّزة، والملفات غير المُجهَّزة، والملفات التي تم تغييرها منذ فرع main
• bin/lint --fix ...: يشغّل أدوات الإصلاح التلقائي للملفات المحددة
• bin/lint --fix: يشغّل جميع أدوات الإصلاح التلقائي المتاحة عبر المستودع بأكمله
• bin/lint --verbose: يطبع أوامر lefthook الأساسية

عند تمرير ملفات صريحة، يقوم bin/lint بتصفيتها إلى أنواع الملفات القابلة للفحص المدعومة قبل استدعاء lefthook.

ملفات توثيق Markdown ليست حالياً جزءاً من bin/lint، لذا فإن تشغيل bin/lint path/to/doc.md سيُبلغك بأنه لا توجد ملفات مطابقة للفحص.

ما الذي يتم فحصه

توجد الإعدادات الدقيقة في lefthook.yml. عند كتابة هذا الدليل، يغطي bin/lint ما يلي:

Ruby

• **/*.{rb,rake,thor}
• سكربتات Ruby تحت bin/**/*
• Gemfile

الفحوصات:

• rubocop
• syntax_tree (stree check)

تنسيق JavaScript، GJS، CSS، و SCSS

• app/assets/stylesheets/**/*.{css,scss}
• frontend/**/*.{js,gjs,scss,css,cjs,mjs}
• ملفات الأصول المطابقة للإضافات (plugins) والسمات (themes)

الفحوصات:

• prettier/pprettier

فحص JavaScript و GJS

• frontend/**/*.{js,gjs}
• ملفات JS المطابقة للإضافات والسمات

الفحوصات:

• eslint (مع قواعد template-* من eslint-plugin-ember التي تغطي الجزء الخاص بالقوالب في ملفات .gjs)

فحص SCSS

• app/assets/stylesheets/**/*.scss
• ملفات SCSS المطابقة للإضافات والسمات

الفحوصات:

• stylelint

فحوصات YAML والترجمة (locale)

• **/*.{yaml,yml} باستثناء config/database.yml
• **/{client,server}.en.yml

الفحوصات:

• yaml-lint
• script/i18n_lint.rb

فحص الأنواع (Type checking)

عند تشغيل bin/lint دون تمرير أي حجة ملف، يشغّل فحص المستودع الكامل أيضاً:

• pnpm lint:types

هذا هو فحص بأسلوب Glint/TypeScript لمعلومات أنواع JavaScript في Discourse.

أوامر bin/lint path/to/file وخطاف ما قبل التثبيت (pre-commit hook) لا تشغّل فحص الأنواع الكامل. استخدم bin/lint العادي عندما تريد إجراء فحص شامل للمستودع بأكمله.

ما الذي يمكن إصلاحه تلقائياً

يمكن لـ bin/lint --fix إصلاح الكثير من المشكلات تلقائياً، لكن ليس جميعها.

تم تكوين الإصلاح التلقائي لـ:

• prettier --write
• eslint --fix
• stylelint --fix
• rubocop -A
• syntax_tree (stree write)

عملياً، هذا يعني أن --fix يمكنه إعادة تنسيق وكتابة:

• Ruby
• JavaScript / GJS
• CSS / SCSS

هذه الفحوصات لا يتم إصلاحها تلقائياً بواسطة bin/lint --fix:

• التحقق من صحة صياغة YAML
• فحص الترجمة (i18n linting) لـ client.en.yml / server.en.yml
• فحص الأنواع (Glint/type checking)

العلاقة مع خطافات git

يستخدم خطاف ما قبل التثبيت (pre-commit hook) نفس إعداد lefthook المستخدم في bin/lint، لكنه يعمل فقط على الملفات المُجهَّزة (staged).

هذا يعني:

• قد يفشل التثبيت (commit) لأن الملفات المُجهَّزة لا تجتاز الفحص
• bin/lint --staged هو المقابل اليدوي الأقرب لخطاف ما قبل التثبيت
• bin/lint --fix --staged طريقة جيدة لإصلاح بالضبط ما أنت على وشك تثبيته

سير عمل عملي

للتنمية اليومية، هذه هي الأوامر الأكثر فائدة:

# قبل تثبيت بضعة ملفات معدلة
bin/lint --fix path/to/file1.rb path/to/file2.gjs

# للتحقق من بالضبط ما سيفحصه خطاف ما قبل التثبيت
bin/lint --staged

# لتنظيف جميع الأعمال الجارية حالياً
bin/lint --fix --wip

# لتشغيل مجموعة فحص المستودع الكاملة، بما في ذلك فحوصات الأنواع
bin/lint

---

هذا المستند مُتحكم به عبر الإصدارات - اقترح تعديلات على github.