للتحقق مما ستقدمه حزمة مساحة عمل npm مشتركة فعليًا، شغّل اختباراتها من المستودع الأحادي (monorepo)، ثم احزم مساحة العمل، وثبّت ملف الأرشيف المضغوط (tarball) هذا في دليل مستهلك مؤقت منفصل على جهاز Mac الخاص بك. يكتشف هذا الإجراء المشاكل التي قد تحجبها الروابط الرمزية (symlinks) المحلية لمساحة عمل npm، مثل ملفات البناء المفقودة أو نقطة دخول غير صحيحة للحزمة. ولا يؤدي هذا إلى نشر أي شيء في سجل الحزم (registry).

1. تشغيل الاختبارات الخاصة بالحزمة من جذر مساحة العمل

افتح تطبيق Terminal وانتقل إلى جذر المستودع الأحادي (monorepo)—وهو الدليل الذي يحتوي على ملف package.json الرئيسي. تأكد من ظهور الحزمة في إعدادات workspaces بالجذر واحتوائها على ملف package.json خاص بها. يثبّت npm مساحات العمل المحددة كروابط داخل مجلد node_modules الرئيسي، وبذلك يمكن لعملية الاختبار هناك الوصول إلى الكود المصدري المباشر لمساحة العمل. يتيح لك خيار مساحة العمل استهداف حزمة معينة عبر اسمها المعلن أو مسار دليلها. npm Workspaces

شغّل سكريبت الاختبار الخاص بالحزمة عبر اسم مساحة العمل الخاصة بها، مع استبدال الاسم بالاسم الموجود في ملف package.json الخاص بها:

npm run test --workspace=@acme/math

إذا كانت الحزمة تستخدم اسم سكريبت مختلف، فاستخدم هذا الاسم. وإذا لم تكن تحتوي على سكريبت اختبار، فلن يتمكن هذا الأمر من اختبار سلوكها؛ وحينها قم بتشغيل عمليات الفحص المحددة بالفعل في المشروع، مثل سكريبتات البناء (build) أو التحقق من التنسيق (lint). تجنب الاعتماد فقط على أمر اختبار على مستوى الجذر: حيث تعمل أوامر npm مثل test على مستوى الجذر ما لم تحدد مساحة عمل. npm Workspaces

2. مراجعة وإنشاء ملف الأرشيف المضغوط (tarball) للحزمة

لا يثبت اختبار مساحة العمل محليًا أن الملفات التي يحتاجها المستهلكون مضمنة بالفعل في الحزمة. أولاً، عاين محتويات حزمة مساحة العمل المحددة من جذر المستودع الأحادي:

npm pack --workspace=@acme/math --dry-run

راجع قائمة الملفات للتأكد من وجود نقطة دخول الحزمة، ومخرجات البناء، وتصريحات الأنواع (type declarations)، وأي ملفات أخرى تعد بها الحزمة. تؤثر إعدادات files و.npmignore و.gitignore في npm على المحتويات؛ ويعد ملف package.json وملفات README وملفات الترخيص من بين الملفات التي يضمنها npm افتراضيًا. تأكد من أن main أو exports تشير إلى ملفات ستكون موجودة داخل الأرشيف. npm pack، ملفات package.json ونقاط الدخول

عندما تبدو القائمة صحيحة، أنشئ ملف tarball فعليًا في دليل مؤقت. تستخدم الأوامر التالية أسلوب الاقتباس المتوافق مع غلاف zsh الافتراضي في macOS، وتبقي الملف المُنتج خارج المستودع الخاص بك:

scratch="$(mktemp -d "${TMPDIR:-/tmp}/workspace-package-check.XXXXXX")"
npm pack --workspace=@acme/math --pack-destination="$scratch"

يعرض الخيار --dry-run فقط ما سيقوم npm بحزمه دون إنشاء الأرشيف بالفعل. أما الأمر الثاني فينشئ الأرشيف بالفعل، لكنه لا يرفعه. توضح وثائق npm أن الأمر npm pack ينشئ ملف tarball ويدعم محدد مساحة العمل. npm pack

3. تثبيت الأرشيف في مجلد مستهلك نظيف

اعثر على مسار ملف tarball، وأنشئ دليل مستهلك منفصل، ثم ثبّت الأرشيف هناك. يفترض هذا المثال أنه تم حزم ملف tarball واحد فقط في الدليل المؤقت:

tarball="$(find "$scratch" -maxdepth 1 -name '*.tgz' -print -quit)"
consumer="$scratch/consumer"
mkdir -p "$consumer"
cd "$consumer"
npm init -y
npm install "$tarball"

يؤدي تثبيت ملف .tgz إلى اختبار المنتج النهائي المحزوم. قد يختلف السلوك عند تثبيت مجلد مساحة العمل أو استخدام الاعتمادية المرتبطة الخاصة بالمستودع الأحادي. npm install

الآن، اختبر الحزمة عبر نقطة دخولها العامة. استخدم الاسم الفعلي للحزمة مع إجراء فحص استهلاك بسيط يناسب واجهة برمجة التطبيقات (API) الخاصة بها—على سبيل المثال، قم باستيرادها (require أو import)، ثم استدعِ دالة تصدير نموذجية. شغّل هذا الفحص من داخل دليل المستهلك، حيث يتم جلب الحزمة من مجلد node_modules المثبت حديثًا. وإذا كان المشروع ينشر مخرجات مترجمة/مبنية، فتأكد من تشغيل عملية البناء قبل الحزم؛ وإلا فقد يفقد الأرشيف بعض الملفات على الرغم من اجتياز الاختبارات أثناء مرحلة التطوير.

4. تشخيص الأخطاء قبل النشر

إذا فشل التثبيت، فتحقق من احتواء الأرشيف على ملف package.json يتضمن name وversion، ثم افحص قائمة ملفاته وتأكد من وجود نقاط الدخول المحددة داخل ملف tarball. وإذا فشل الاستيراد، فقارن صيغة وحدة المستهلك (module format) بإعدادات type وmain وexports الخاصة بالحزمة. قد تجتاز الحزمة اختبارات مساحة العمل وتفشل هنا، لأن تلك الاختبارات قد تُحمّل الملفات المصدرية مباشرة أو تجلب اعتماديات غير معلنة من المستودع الأحادي.

إذا كانت إحدى التبعيات عبارة عن مساحة عمل أخرى غير منشورة، فاختبر أيضًا ترتيبات الإصدار المخطط لها. فالمستهلك الذي يثبت ملف tarball واحدًا لن يتلقى تلقائيًا الكود المصدري لمساحة العمل الشقيقة عبر رابط المستودع الأحادي. تأكد من نشر الحزم الشقيقة أو توفرها بإصدارات متوافقة، أو استخدم بنية مدروسة مسبقًا مجمعة أو قابلة للتثبيت. يتحقق هذا الإجراء من الحزمة المحزومة محليًا في بيئة Mac/Node الحالية؛ ولا يمكنه إثبات صحة السلوك عبر كل إصدارات Node أو أنظمة التشغيل أو إعدادات السجلات المختلفة.

النقطة المناسبة للانتهاء هي اجتياز اختبار مساحة العمل، وظهور قائمة ملفات منطقية للحزمة، ونجاح فحص المستهلك الذي يثبت ملف tarball ويختبره من خارج المستودع الأحادي. احتفظ بالدليل المؤقت إذا كنت بحاجة إلى فحصه، أو احذفه باستخدام rm -rf "$scratch" بعد التأكد من أن المتغير لا يزال يشير إلى المسار المؤقت المُنشأ.

المصادر