عن المشروع

gdstyle هي أداة فحص وتنسيق للغة GDScript، وهي لغة البرمجة النصية المستخدمة في محرك الألعاب Godot 4.x. وهي مكتوبة بلغة Rust وموزّعة كملف تنفيذي ثابت واحد، لذا لا يتطلب تشغيلها وجود Python أو سلسلة أدوات Rust أو تثبيت Godot. ما الذي تقوم به تفحص الأداة ملفات GDScript بحثًا عن مخالفات الأسلوب وعدم اتساق التسمية ومشكلات جودة الشيفرة الشائعة، ويمكنها إعادة تنسيق الملفات لتتبع دليل أسلوب Godot الرسمي. وقد استُمدت العديد من الاصطلاحات من دليل أسلوب GDScript الخاص بـ GDQuest. وتوفر 56 قاعدة موزّعة على خمس فئات: - الصياغة (قاعدة واحدة): تُبلّغ عن أخطاء المحلّل المعجمي مثل السلاسل غير المنتهية أو الأرقام غير الصالحة. - التسمية (11 قاعدة): تفرض نمط PascalCase للأصناف والتعدادات، ونمط snake_case للدوال والمتغيرات والإشارات وأسماء الملفات، ونمط SCREAMING_SNAKE_CASE للثوابت وأعضاء التعدادات، وأسماء الإشارات بصيغة الماضي، ومسارات العُقد بنمط PascalCase. - التنسيق (20 قاعدة): يغطي طول السطر، والمسافات والأسطر الجديدة الزائدة، والجدولة مقابل المسافات، والمعاملات المنطقية، ونمط علامات الاقتباس، وتباعد التعليقات، والأقواس، والقيم الرقمية، وعبارة واحدة لكل سطر، والأسطر الفارغة، والفواصل اللاحقة، وتباعد المعاملات والنقطتين والفواصل والأقواس، وأقواس الاستدعاء، وأصفار الأعداد العشرية، والشرطات السفلية في الأعداد الكبيرة، وتخطيط التعدادات. - الترتيب (قاعدة واحدة): تفرض الترتيب المعياري لأعضاء الصنف في Godot، من التعليقات التوضيحية وclass_name مرورًا بالإشارات والتعدادات والثوابت والمتغيرات والدوال الافتراضية والدوال والأصناف الداخلية. - الجودة (23 قاعدة): حدود على عدد الدوال والملفات والمعاملات ومستويات التداخل وعبارات الإرجاع والفروع والمتغيرات المحلية ومتغيرات الصنف والدوال العامة والأصناف الداخلية، إضافة إلى فحوصات لـ pass غير الضرورية والمقارنة الذاتية والإسناد الذاتي ومفاتيح القواميس المكررة واستدعاءات load المكررة والشيفرة غير القابلة للوصول وawait داخل الحلقات والتخصيص داخل الحلقات والبحث عن العُقد في _process وغير ذلك. معظم القواعد مفعّلة افتراضيًا بدرجة تحذير. وهناك بعض القواعد الإرشادية (تلميحات الأنواع والدوال الفارغة وطباعات التصحيح) معطّلة افتراضيًا ويجب تفعيلها صراحةً. المنسّق والإصلاح التلقائي تعيد الأوامر الفرعية fmt تنسيق الملفات في مكانها وهي ثابتة النتائج. وتوحّد المسافات البادئة والمسافات البيضاء والأسطر الفارغة والمعاملات المنطقية وعلامات الاقتباس وتباعد التعليقات وتباعد علامات الترقيم والقيم الرقمية والأسطر الجديدة اللاحقة، وتوسّع التعدادات أحادية السطر، وتعيد ترتيب أعضاء الصنف، وتلفّ الأسطر الطويلة عند الفواصل داخل المحددات، وعند and/or في الشروط، وعند حدود الكلمات في التعليقات. وتُترك الأسطر التي لا تحتوي على نمط قابل للكسر دون تغيير. يدعم الأمر الفرعي check الخيار --fix للإصلاحات الآمنة و--unsafe-fix لإعادة التسمية وإعادة الترتيب. وتنتشر إعادة التسمية غير الآمنة عبر ملفات .gd الأخرى وإلى ربط المشاهد .tscn/.tres؛ ويُبلّغ عن أي شيء لا يمكن إعادة كتابته بأمان كتحذير. وتُكتب الإصلاحات على القرص دون نسخ احتياطي أو تأكيد، لذا ينصح ملف README بالالتزام أو التخزين المؤقت أولًا. الإعداد والتعطيل يوجد الإعداد في gdstyle.toml أو .gdstyle.toml، ويُكتشف عبر الصعود في شجرة الدلائل، أو يُمرّر باستخدام --config. وتشمل الإعدادات طول السطر واستخدام الجدولة وحدود أحجام متنوعة وأنماط الاستبعاد/التضمين وتجاوزات درجة الخطورة لكل قاعدة (off، warn، error). وتُبلّغ أسماء القواعد غير المعروفة في الإعداد على stderr. ويمكن إسكات التشخيصات لكل سطر أو لكل ملف باستخدام تعليقات # gdstyle:ignore و# gdstyle:ignore-file، مع إمكانية تضييقها إلى معرّفات قواعد محددة. كما أن تجاهل قاعدة ترتيب الأعضاء يثبّت العضو بحيث لا ينقله المنسّق. التكامل يمكن أن يكون الإخراج نصيًا أو JSON، وتميّز رموز الخروج بين التشغيلات النظيفة وأخطاء الفحص أو تجاوز حدود التحذيرات وأخطاء الإعداد. ويوثّق ملف README استخدام GitHub Actions وخطافات pre-commit (gdstyle وgdstyle-fmt) وخطاف git خام بسيط. وتوفر إضافة محرر Godot اختيارية لوحة سفلية بتشخيصات قابلة للنقر وإصلاحات بنقرة واحدة وفحص/تنسيق عند الحفظ، باستخدام GDExtension عند توفره مع الرجوع إلى الملف التنفيذي CLI. كما يمكن استخدام الحزمة كمكتبة Rust.