الاختبار: حزمة التحقق

شغّلها

just test
# or
python3 tests/validate.py

تعمل من أي مكان وتحتاج Python 3 فقط (بلا حزم خارجية ولا شبكة). تطبع سطرًا لكل فحص وتخرج بقيمة غير صفرية إذا فشل أي فحص، فتصلح للتكامل المستمر ولخطّاف ما قبل الإيداع.

ما تفحصه

العدد المتوقع للمواضيع (الثابت في أعلى السكربت).
الترقيم المتصل داخل كل جزء، بدءًا من N.0.
مطابقة H1 للرقم العشري في اسم الملف لكل موضوع.
مطابقة عناوين H1 لـ spec/structure.md حرفًا بحرف، لا الرقم العشري في البداية فقط.
الأقسام المطلوبة موجودة في كل موضوع محتوى (الأجزاء من 1 إلى 8، الموضوع N.1 فما فوق)، بترتيب القالب تمامًا.
حد أدنى لعدد الكلمات لكل موضوع محتوى (1500 كلمة)، مع قائمة سماح في السكربت للاستثناءات المقصودة.
لا شرطات طويلة في أي ملف Markdown.
الشرطات المتوسطة بين رقمين فقط، فيجتاز “2.1–2.8” ويفشل كل ما سواه.
لا عبارات محظورة (“not only” و”but also” و”load-bearing”).
كل روابط .md الداخلية تعمل.
الإحالات النثرية تشير إلى مواضيع حقيقية: فالإحالة إلى رقم موضوع لا ملف له على القرص تفشل، باستخدام نمط الإحالة نفسه الذي يستخدمه الربط التلقائي للمواضيع في الموقع المنشور.
روابط ويكيبيديا سليمة الشكل (https://en.wikipedia.org/wiki/...).
يطابق spec/structure.md الملفات على القرص، في الاتجاهين.
يربط README والصفحة الرئيسية وصفحة المحتويات كل موضوع.

عند فشل فحص

يسمّي السطر الفاشل الملف والمشكلة. الإصلاحات الشائعة:

العثور على شرطة طويلة: أعد صياغة الجملة لإزالة ”—“. لا تحذفها فحسب.
قسم مفقود: أضف قسم ## المفقود من قالب الموضوع.
عدم تطابق البنية: أضفت موضوعًا أو أعدت تسميته دون تحديث spec/structure.md، أو العكس. أعدهما إلى الاتساق.
رابط معطوب: أصلح المسار، أو حدّثه بعد إعادة التسمية.
فجوة في الترقيم: أعد الترقيم ليتصل الجزء من N.0.

ما وراء حزمة التحقق

يشغّل just spell الأداة codespell على المستودع. التهيئة، بما فيها قائمة تجاهل الإيجابيات الكاذبة، هي قسم [tool.codespell] في pyproject.toml.
يطبع just stats تقريرًا بصيغة Markdown (عدد كلمات كل موضوع، والمواضيع الضعيفة، وروابط ويكيبيديا، وبنود المراجع) من tools/stats.py.

التكامل المستمر

يعمل .github/workflows/test.yml على كل طلب دمج وعلى الدفعات إلى الفروع غير الرئيسية: حزمة التحقق وcodespell. لا يبني هذا المستودع موقعًا ولا ينشره؛ فالعرض يجري في مستودع software-engineering-metrics.github.io المنفصل.
يفحص .github/workflows/links.yml الروابط الخارجية أسبوعيًا باستخدام lychee (أنماط التجاهل في .lycheeignore) ويحتفظ بالنتائج في بلاغ واحد “Link checker report”. وتبقى الروابط الخارجية خارج مسار طلبات الدمج عن قصد.

ما لا تغطيه الاختبارات

تفحص الحزمة البنية والأسلوب لا الحقيقة. لا تستطيع أن تعرف هل المرجع حقيقي أو هل النثر دقيق. تحقق من الاستشهادات والوقائع يدويًا أو بجولة بحثية. كما أن وجود رابط ويكيبيديا (بخلاف شكله) يحتاج فحصًا على الشبكة، وتتركه الحزمة عمدًا لتعمل دون اتصال.