في هذا الفيديو: الـ linters وأدوات التنسيق (formatters)، وهما أداتان يمكنكم تشغيلهما بينما يعدّل الوكيل الكود. سنرى ما تفعله كل أداة، ونستخدم diff صغيرًا لنرى كيف يسهّل التنسيق الموحّد المراجعة، ثم نشغّل الأداتين في Python وفي TypeScript. بعد ذلك سنصلح تقرير lint حقيقيًا واحدًا، ونحوّل أحد اصطلاحات المشروع إلى قاعدة lint.
لنبدأ بالتمييز بين أداتين كثيرًا ما تُذكران معًا. يبحث الـ linter في الكود عن أنماط صحيحة تمامًا في اللغة، لكنها مريبة. مثل استيراد غير مستخدَم، أو مقارنة نتيجتها صحيحة دائمًا، أو متغيّر يحجب متغيّرًا آخر دون أن يُلاحَظ. وبشكل أعمّ، يُبلغ الـ linter عن مشكلات الكود وعن مخالفات الاصطلاحات، بحسب القواعد المفعّلة في إعداداته. فهو يُبلغ عمّا يجده، وفي الوضع الافتراضي لا يغيّر شيئًا.
أما أداة التنسيق فعملها أضيق بكثير. فهي توحّد تنسيق الكود في صيغة قياسية واحدة، دون أن تغيّر ما يفعله البرنامج. وهي تحدّد مواضع فواصل الأسطر، ومقدار المسافة البادئة، ووجود مسافة بعد الفاصلة، ونوع علامات التنصيص في السلاسل النصية.
التنسيق الموحّد يفيد كثيرًا عند مراجعة التغييرات. إليكم مثالًا على diff من مشروع بلا تنسيق موحّد. التغيير المطلوب يرفع نسبة الضريبة، لكن الوكيل يغيّر أيضًا المسافات في الدالة. يُظهر الـ diff ثلاثة أسطر محذوفة وثلاثة أسطر مضافة.
تعديل نسبة الضريبة وحده، من 0.17 إلى 0.18، هو الذي يغيّر السلوك هنا. والباقي مسافات فقط. والـ diff الذي تغلب عليه تغييرات الشكل يُغري بالتصفّح بدل القراءة، فيسهل أن يفوتكم التغيير المهمّ.
قارنوا ذلك بالتعديل نفسه في ملف منسَّق مسبقًا. الملف بالصيغة القياسية قبل التعديل، وكذلك بعد إعادة تنسيقه. في هذا المثال، تختفي تعديلات المسافات، ولا يبقى إلا السطر القديم والسطر الجديد لنسبة الضريبة.
التنسيق الموحّد يزيل فروق الشكل التي يمكن تجنّبها، فيسهل العثور على التعديلات المهمّة. وهذا يفيد حين يُنتج الوكيل diff كبيرًا وتحتاجون إلى فهم ما الذي تغيّر.
لكل أداة أمر يمكنكم تشغيله في المشروع. في Python، شغّلوا ruff check . وفي TypeScript، شغّلوا npx eslint . مع وجود إعدادات ESLint الخاصة بالمشروع. يفحص كل linter الملفات التي تحدّدها إعداداته ويُبلغ عن مخالفات القواعد المفعّلة.
ولكلٍّ منهما خيار للإصلاح: ruff check --fix .، أو npx eslint --fix . فيطبّقان الإصلاحات التلقائية المتاحة، ويُبلغان عن المشكلات المتبقّية. راجعوا التغييرات، وعالجوا ما تبقّى.
لتنسيق الكود، شغّلوا ruff format . في Python، أو npx prettier --write . في TypeScript. كلٌّ منهما يعيد كتابة الملفات المدعومة في المشروع بصيغة قياسية واحدة، فتقلّ فروق التنسيق في المراجعة التالية.
عند الأخطاء، يُرجع الـ linter رمز خروج غير صفري، فيصبح الفشل مرئيًا للبرنامج كما هو مرئي للإنسان. وضع الكتابة في أداة التنسيق يصلح التنسيق. أما ruff format --check . وnpx prettier --check . فيفشلان بدلًا من ذلك إذا كان التنسيق يحتاج إلى تغيير. استخدموا وضع الكتابة عند التعديل. واستخدموا وضع الفحص حين تريدون أن يُبلغ الأمر عن الفشل دون أن يغيّر أي ملف. اطلبوا من الوكيل تشغيل الـ linter وأداة التنسيق قبل أن يُبلغ بانتهاء العمل.
هكذا يبدو تقرير lint واحد. الملف billing.py يستورد الوحدة os ولا يستخدمها. الأمر ruff check . يُبلغ عن مخالفة القاعدة F401: الوحدة os مستورَدة وغير مستخدَمة. ويذكر الملف والسطر والعمود، ويقترح إزالة الاستيراد. يُرجع الأمر رمز خروج غير صفري، فيعرف الوكيل أن الفحص فشل.
النجمة بين القوسين المربعين تميّز تقريرًا يستطيع Ruff إصلاحه تلقائيًا. الأمر ruff check --fix . يزيل الاستيراد غير المستخدَم، ويُبلغ أنه وجد خطأً واحدًا، وأصلح خطأً واحدًا، ولم يبقَ شيء.
تشغيل الفحص مرة أخرى يؤكّد الإصلاح. نجحت كل الفحوصات، ويُرجع الأمر رمز الخروج 0. هذه هي الحلقة التي تريدون أن يتبعها الوكيل. قراءة التقرير، ثم إصلاح السبب، ثم تشغيل الفحص مجددًا حتى يمرّ دون أخطاء.
يستطيع الـ linter أيضًا فحص اصطلاحات اخترتموها لمشروعكم. الاختبارات والأنواع تعبّر أيضًا عن متطلبات المشروع. وقواعد lint مفيدة حين يكون الاصطلاح نمطًا يمكن التعرّف عليه في الكود. لنفترض أن مشروعكم يحصر التعامل مع قاعدة البيانات في حزمة واحدة اسمها db. ولا يحقّ إلا لهذه الحزمة أن تستورد sqlite3. وجملة في ملف التعليمات تطلب من الوكيل اتباع هذا الاصطلاح.
اجعلوا الاصطلاح قابلًا للتنفيذ. الـ linter يرى كل عبارة import، لذا فهذه القاعدة نمط يستطيع فحصه. في Ruff، يفعّل سطر extend-select قاعدة الاستيراد المحظور، ويحدّد إعداد banned-api الوحدة المحظورة، وهي هنا sqlite3. ثم يُبلغ Ruff عن كل ملف يستوردها، باستثناء الملفات في الحزمة db، التي يستثنيها إعداد per-file-ignores. وفي ESLint، تؤدي القاعدة no-restricted-imports الشيء نفسه. وتقبل الـ linters قواعد أخرى أيضًا. في الأساس، أي فحص للكود يمكنكم برمجته يمكن أن يصبح قاعدة lint. الجملة تطلب من الوكيل الالتزام. أما قاعدة الـ lint فتُبلغ عن كل مخالفة، في كل مرة تُشغَّل فيها.
هناك مواضع قد تضرّ فيها الـ linters. تخيّلوا قاعدة تمنع الطباعة، مفعّلة في أداة سطر أوامر عملها كله هو الطباعة. يُبلَّغ عن الأسطر الثلاثة كلها، والثلاثة كلها صحيحة.
تعليقات إسكات التحذيرات (suppression comments) تُخفي هذه التقارير. فلا تعود هذه القاعدة تفحص تلك الأسطر.
إذا كانت الطباعة مناسبة في وحدة سطر الأوامر كلها، فاضبطوا النطاق بدلًا من ذلك، باستخدام per-file-ignores في Ruff أو override في إعدادات ESLint. هنا، يعطّل سطران في pyproject.toml قاعدة الطباعة في الملف cli.py وحده. أما بقية الملفات فما زالت تُفحص.
القاعدة التي تُبلغ باستمرار عن كود مقبول قد تُغرقكم بتعليقات الإسكات وتُضعف ثقتكم بتحذيراتها. ابدؤوا بالإعدادات القياسية بدلًا من تفعيل كل القواعد. واستعينوا بالتقارير أثناء العمل الحقيقي لتقرّروا أيّ القواعد تفيد، وأيّها يحتاج إلى نطاق أضيق.
إذن، دعوا أداة التنسيق تحصر الـ diffs في السلوك. ودعوا الـ linter يتولّى فرض قواعد مشروعكم. يكشف في ثوانٍ الأخطاء البرمجية المحتملة ومخالفات الاصطلاحات، فيصلحها الوكيل قبل أن تقرؤوا الكود أصلًا. ابدؤوا بالإعدادات القياسية لمشروعكم، وستفيدكم كثيرًا. شكرًا على المشاهدة، ونراكم في الفيديو التالي.