عن المشروع

RecurSpec هي حزمة Node.js في مراحلها الأولى مرخصة بموجب MIT، تقوم باختبار مسارات الاسترداد في أدوات سطر الأوامر. وبينما قد يكتفي الاختبار التقليدي بالتأكد من طباعة رسالة خطأ، فإن RecurSpec تتحقق من أن الأمر الذي تقترحه الرسالة يعالج المشكلة بالفعل، لضمان عدم تعثر المستخدمين. آلية العمل يتم وصف حالة الاختبار بشكل تصريحي في ملف recurspec.yml. تحدد كل حالة الأمر المراد تشغيله، والفشل المتوقع (على سبيل المثال رمز خروج غير صفري وسلسلة نصية في stderr)، ومصدر تعليمات الاسترداد، وخطوة التحقق. يمكن أن تتضمن عملية التحقق إعادة تشغيل الأمر الأصلي واشتراط رمز خروج صفري، وبذلك تؤكد الأداة إغلاق حلقة الاسترداد بدلاً من مجرد وجود النصيحة. البدء يتطلب المشروع Node.js 22 أو إصداراً أحدث و pnpm. يتم تثبيته كاعتمادية تطوير، ثم يُستخدم من خلال ثلاثة أوامر أساسية: خطوة init التي تكتب تكويناً أولياً يحتوي على مثال Node.js قابل للتشغيل، وخطوة validate، وخطوة test. يمزج العرض التوضيحي المرفق عمداً بين مسارات استرداد ناجحة وأخرى معطلة. واجهة سطر الأوامر توفر واجهة CLI أوامر test و validate و init و explain و discover. يدعم أمر test خيارات لتحديد حالة أو علامة (tag)، واختيار تنسيق التقرير (human أو json أو junit أو markdown)، والمخرجات التفصيلية، وسلوك الفشل السريع (fail-fast)، وبذرة (seed)، وتشغيل تجريبي (dry run). تم تحديد رموز الخروج لتكون 0 للنجاح الكامل، و 1 لعقد فشل، و 2 لأخطاء التكوين أو الاستخدام. تهدف تقارير JSON و JUnit و Markdown إلى التكامل مع خطوط أنابيب CI وتعليقات طلبات السحب (pull-request). كما تتوفر واجهة برمجة تطبيقات (API) من خلال runRecurSpec. ما الذي تكتشفه الأداة تستهدف الأداة عدم التطابق بين رسالة الخطأ وتعليماتها: الأوامر المقترحة التي لم تعد موجودة، خطوات الاسترداد غير المكتملة، الأوامر التي تنجح دون حل المشكلة الأصلية، النصائح التي تؤدي إلى خطأ إضافي، حلقات التعليمات المفرغة، والتعليمات الغامضة أو غير الآمنة. إعادة المحاولة واسترداد الهدف يتم دعم شكلين من الاسترداد. في استرداد نمط إعادة المحاولة (retry-style)، يؤدي إزالة العائق إلى نجاح الأمر الأصلي في المحاولة الثانية. أما في استرداد الهدف (goal recovery)، فإن الأمر المقترح يحل محل العملية الفاشلة تماماً، بحيث يتم تحقيق هدف المستخدم حتى لو ظل تشغيل الأمر الأصلي فاشلاً. يشير ملف README إلى أن العمل على حالات Cargo أظهر هذا التمييز وأدى إلى تطوير التحقق القائم على الهدف. التوافق مع العالم الحقيقي تتضمن مجموعة التوافق حالات مستمدة من Git و Cargo و npm، تغطي مواقف مثل فقدان هوية Git، وحذف الفرع، ونصائح سحب متباعدة، ووجود دليل مشروع Cargo، وسكريبت npm مفقود. تشمل النتائج النصائح الغامضة (أوامر متعددة حصرية أو مطلوبة)، واسترداد الهدف، والرسائل المعلوماتية فقط التي يتم تجاهلها بشكل صحيح. يتم تخطي الأدوات المفقودة عند تشغيل المجموعة. نموذج السلامة يتم تحليل أوامر الاسترداد والتحقق منها قبل التنفيذ. يتم حظر تسلسل الأوامر (shell chaining)، وإعادة التوجيه، واستبدال الأوامر، والأوامر التدميرية المعروفة افتراضياً، وتعمل كل حالة في مساحة عمل مؤقتة ومعزولة. يوضح ملف README أن الخلفية المحلية لا تفرض عزل الشبكة على مستوى نظام التشغيل، لذا يظل إعداد deny-network استشارياً حتى يتوفر نظام خلفي يعتمد على الحاويات (container backend). القيود والحالة تدرج الوثائق ثلاثة قيود: عدم وجود عزل للشبكة على مستوى نظام التشغيل في الخلفية المحلية، والحاجة إلى إدخال قياسي مبرمج عند اختبار برامج TTY التفاعلية (دعم PTY الكامل هو عمل مستقبلي)، والاعتماد على الأدوات التي تطبع نصائح قابلة للبحث (greppable)، مع الإبلاغ عن النصائح الغامضة أو المفقودة بدلاً من تخمينها. توصف RecurSpec بأنها في مراحلها الأولى، وقد يتغير كل من التكوين وواجهة برمجة التطبيقات العامة قبل إصدار النسخة 1.0. تغطي وثائق منفصلة التكوين، والاستخراج، والسلامة، والتقارير، والاكتشاف.