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

[Discourse]

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

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

pnpm install
pnpm lefthook install

بعد ذلك، سيتم فحص الملفات المعدة تلقائيًا عند git commit.

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

استخدم bin/lint عندما تريد تشغيل أدوات التحليل المتوافقة مع المستودع بنفسك بدلاً من انتظار خطاف ما قبل الالتزام (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 التزامًا، بالإضافة إلى الملفات غير المتعقبة
• bin/lint --staged: تحليل الملفات المعدة فقط
• bin/lint --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}
• مطابقة أصول المكونات الإضافية والسمات (theme assets)

عمليات التحقق:

• prettier/pprettier

تحليل JavaScript و GJS

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

عمليات التحقق:

• eslint

تحليل قوالب GJS

• frontend/**/*.gjs
• مطابقة ملفات .gjs للمكونات الإضافية والسمات

عمليات التحقق:

• ember-template-lint

تحليل 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 وخطاف ما قبل الالتزام لا يقومان بتشغيل فحص النوع الكامل. استخدم bin/lint العادي عندما تريد المرور الكامل لتحليل المستودع بأكمله.

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

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

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

• prettier --write
• eslint --fix
• ember-template-lint --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

يستخدم خطاف ما قبل الالتزام نفس تكوين lefthook مثل bin/lint، ولكنه يعمل فقط على الملفات المعدة.

هذا يعني:

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