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

[Discourse]

يستخدم Discourse lefthook للخطافات (hooks) الخاصة بـ Git، و bin/lint كنقطة الدخول الرئيسية لواجهة سطر الأوامر (CLI) لتشغيل نفس الفحوصات يدويًا.

إذا كنت تعمل في نسخة محلية (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 عملية commit، بالإضافة إلى الملفات غير المُتتابة.
• 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 والlocales

• **/*.{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 لملفات client.en.yml / server.en.yml
• فحص Glint/الأنواع

العلاقة مع خطافات 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.