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

[Discourse]

يستخدم Discourse أداة lefthook للخطافات (hooks) الخاصة بـ git، ويستخدم 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 عملية تثبيت (commits)، بالإضافة إلى الملفات غير المتتبَّعة (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 فقط تحت مجلد docs/developer-guides/. إذا قمت بتشغيل bin/lint path/to/doc.md على أي ملف Markdown آخر، فسيُبلّغك النظام بأنه لم يتم فحص أي شيء.

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

توجد التهيئة الدقيقة في 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 لمعلومات الأنواع في Discourse. يعمل في وضع TypeScript strict وينشئ أيضًا التصريحات المنشورة (published declarations).

لا يشغّل 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).

هذا يعني:

• قد تفشل عملية التثبيت لأن الملفات المُدرجة لا تجتاز الفحص
• 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.