توثيق NPQ

يحتوي هذا الدليل على توثيق شامل لأداة التدقيق الأمني NPQ (جودة حزم Node).

التوثيق الأساسي

optional-features.md

إعداد واستخدام الميزات الأمنية الاختيارية، بما في ذلك التحسينات الأخيرة وإصلاحات الأخطاء.

age.marshall.md

توثيق تفصيلي لمكوّن Age Marshall الأمني الذي يتحقق من عمر الحزمة ونضجها.

توثيق الميزات

يحتوي دليل feature/ على توثيق تفصيلي لميزات وتنفيذات محددة:

التطورات الأخيرة

• test-coverage-improvements.md - تحسينات شاملة لتغطية الاختبارات رفعت التغطية الإجمالية من 84.4% إلى 93.39%
• signature-verification-fix.md - إصلاح خطأ حرج في التحقق من التوقيعات مع نطاقات الإصدارات (مثل @angular/common@^20.2.4)

الميزات الحالية

• auto-continue.md - توثيق ميزة المتابعة التلقائية التي تبسّط سير عمل تثبيت الحزم
• exit-codes.md - مرجع لسلوك أكواد الخروج لعمليات npq و npq-hero
• json-output.md - مخرجات تدقيق قابلة للقراءة آليًا ومُرقّمة الإصدارات للـ CI والأتمتة
• malicious-package.md - توثيق اكتشاف الحزم المعروفة بأنها خبيثة عبر بيانات Snyk/OSV
• pacote-dependency-reduction.md - ملخص تنفيذ تقليل الاعتماديات الاختياري لـ pacote

معايير التوثيق

البنية

• كل ميزة لها ملف Markdown خاص بها في feature/
• الوظائف الأساسية موثقة في مستوى جذر الدليل
• تفاصيل التنفيذ الفني مرفقة بأمثلة برمجية
• الإعدادات الموجهة للمستخدم موثقة مع أمثلة استخدام

إرشادات المحتوى

• نظرة عامة: وصف موجز للميزة/المكوّن
• التصميم الفني: تفاصيل البنية والتنفيذ
• أمثلة الاستخدام: أمثلة عملية مع مقاطع برمجية
• الاختبار: معلومات التغطية والتحقق
• اعتبارات مستقبلية: ملاحظات الصيانة والتطوير

توثيق Marshall

مكوّنات Marshall هي وحدات التحقق الأمني الأساسية في NPQ. يركز كل Marshall على جانب أمني محدد:

• Age Marshall (age.marshall.md) - التحقق من عمر الحزمة ونضجها
• Signature Marshall - التحقق من توقيعات سجل NPM (انظر signature-verification-fix.md)
• Provenance Marshall - التحقق من إثبات بناء الحزمة
• Snyk Marshall - التكامل مع قاعدة بيانات الثغرات
• Typosquatting Marshall - اكتشاف تشابه أسماء الحزم

المساهمة في التوثيق

عند إضافة ميزات جديدة أو إجراء تغييرات جوهرية:

1. توثيق الميزة: أنشئ ملفًا جديدًا في دليل feature/
2. تحديث الفهرس: أضف إدخالًا إلى هذا README
3. المراجع المتبادلة: حدّث ملفات التوثيق ذات الصلة
4. الأمثلة: أدرج أمثلة استخدام عملية
5. الاختبار: وثّق تغطية الاختبارات والتحقق

مرجع سريع

سياق المشروع

• التطوير - الإعداد المحلي، سير العمل، والأوامر المفيدة.
• الاختبار - أوامر الاختبار، تنظيم الاختبارات، وتوقعات التحقق.
• البنية - هيكل المستودع، حدود الحزم، والتدفقات المهمة.
• الاتفاقيات - اتفاقيات البرمجة والتوثيق والصيانة.

مواصفات التصميم

• أمان التثبيت غير التفاعلي - تصميم معتمد للتثبيتات غير التفاعلية (non-TTY) مع إغلاق آمن عند الفشل واشتراكات صريحة للأتمتة وعوامل الترميز.

• أمان التثبيت غير التفاعلي - خطة تعتمد على الاختبار أولًا لتوجيه التثبيت غير التفاعلي (non-TTY) وتمرير عوامل الترميز.

• تشغيل مدير الحزم بدون شل - تصميم معتمد لتمرير وسائط مدير الحزم دون إعادة بناء أوامر الشل.

• دعم السجلات المخصصة - تصميم معتمد لدعم Artifactory المتوافق مع npm والسجلات الخاصة.

• اكتشاف JSON لعوامل الترميز - تصميم معتمد للاختيار التلقائي لوضع تدقيق JSON في بيئات عوامل الترميز.

• مخرجات تدقيق JSON - تصميم معتمد لنتائج تدقيق مُرقّمة الإصدارات وقابلة للقراءة آليًا وغير تفاعلية.

• تحذيرات هوية المشرفين ذوي النطاقات منتهية الصلاحية - تصميم معتمد لتحذيرات النطاقات منتهية الصلاحية القابلة للإسناد.

• الإصدار المُحلّى للنطاق منتهي الصلاحية - تصميم لحل إصدار الاعتمادية الدقيق لفحوصات النطاقات منتهية الصلاحية.

خطط التنفيذ

• أمان التثبيت غير التفاعلي - خطة تعتمد على الاختبار أولًا لتوجيه التثبيت غير التفاعلي (non-TTY) وتمرير عوامل الترميز.
• تشغيل مدير الحزم بدون شل - خطة تعتمد على الاختبار أولًا لتشغيل مديري الحزم دون إعادة بناء أوامر الشل.
• دعم السجلات المخصصة - خطة تنفيذ مهمة بمهمة للقضية #429.
• اكتشاف JSON لعوامل الترميز - خطة تنفيذ تعتمد على الاختبار أولًا للقضية #426 عبر npq و npq-hero.
• مخرجات تدقيق JSON - خطة مهمة بمهمة لمخرجات CLI بتنسيق JSON للتدقيق فقط ومُرقّمة الإصدارات.
• الإصدار المُحلّى للنطاق منتهي الصلاحية - خطة تنفيذ لحل إصدار الاعتمادية الدقيق في فحوصات النطاقات منتهية الصلاحية.
• تحذيرات هوية المشرفين ذوي النطاقات منتهية الصلاحية - خطة تنفيذ تعتمد على الاختبار أولًا لتحذيرات النطاقات منتهية الصلاحية القابلة للإسناد.