بيان حزمة الأداة

معرّف المخطط: artifact-package@1 المخطط القابل للقراءة آليًا: artifact-package.schema.json اسم الملف داخل الأرشيف: parsware.json، في جذره

هو ما يحوّل مجلد مخرجات المُجمِّع إلى شيء تستطيع المنصة قبوله. يكتبه npm run pack إلى جانب مخرجات البناء ويحزمه معها؛ وتقرؤه المنصة عند الرفع، ويُرفض الأرشيف المجمَّع يدويًا بالقاعدة نفسها التي يُرفض بها المولَّد (قاعدة مسار التحقق الواحد، القسم 6.7).

لماذا يوجد

كان التسجيل يطلب من المصمم ستة حقول، اثنان منها يُنسخان من إعدادات المُجمِّع: نطاق Module Federation والوحدة المكشوفة. وكان الخطأ في أيٍّ منهما يُنتج عرضًا واحدًا — لا يُحمَّل عنصر التحكم — دون ما يدل على أيهما كان خاطئًا. البناء يعرف الاثنين أصلًا، فصار يكتبهما.

الشكل

الحقل	النوع	مطلوب	ملاحظات
formatVersion	integer	نعم	يجب أن يساوي 1 تمامًا. وهو const لا حد أدنى، حتى يُرفض أرشيف من صيغة مستقبلية برسالة واضحة بدل أن يُقرأ بقواعد اليوم فيفشل في موضع أقل وضوحًا.
kind	string	نعم	CustomControl. وتنضم التطبيقات المخصصة إلى هذه القائمة حين تعتمد الحزمة — ستستخدم المخزن والذاكرة المؤقتة ونقطة التقديم نفسها، ولن تختلف إلا في حقول هذا البيان الخاصة بكل نوع.
logicalName	string	نعم	مسبوق ببادئة الناشر، بصيغة snake_case صغيرة (مثل par_signature_pad). يُفحص عند الرفع مقابل بادئة ناشر الحل المالك، فلا يستطيع أرشيف من مكان آخر أن يدّعي بادئة.
displayName	string	نعم	اسم مقروء يظهر في لوحة الحقول لدى مصمم النماذج.
description	string | null	لا	وصف قصير، 512 حرفًا كحد أقصى.
version	string	نعم	إصدار من ثلاثة أجزاء (1.2.3)، وهو إصدار npm الخاص بعنصر التحكم. يُسجَّل للتشخيص ويُعرض على مصمم يتحقق من أن المثبَّت هو ما بناه؛ ولا يحكم شيئًا.
scope	string	نعم	نطاق حاوية Module Federation، مقروءًا من إعدادات federation في البناء.
module	string	نعم	مسار الوحدة المكشوفة (مثل ./Control)، مقروءًا من خريطة exposes في إعدادات federation.
entry	string	نعم	ملف مدخل الحاوية داخل الأرشيف (مثل remoteEntry.js). اسم ملف مجرد لا مسار: يسمّي ملفًا في جذر الأرشيف، وهو أيضًا المسار الأساس الذي تقدّم منه المنصة أجزاء الأداة غير المتزامنة.
substitutesFor	string[]	نعم لـ CustomControl	عائلات أنواع بيانات الحقول التي يمكن ربط عنصر التحكم بها. يجب أن تطابق قائمة custom-control-manifest@1 تمامًا.
requestedScopes	string[]	نعم لـ CustomApp	نطاقات OAuth التي يعلن تطبيق مخصّص حاجته إليها، وتُطلب حين يُسكّ رمز سياق التطبيق (§6.3). وهي غائبة لعنصر تحكّم مخصّص، فهو لا يعلن شيئًا — إذ يعمل بصلاحيات من يستخدمه (§28).

من أين تأتي القيم

مصدران، ولا يخمّن أيٌّ منهما نصف الآخر:

• scope وmodule وentry تُقرأ من mf-manifest.json الخاص بالبناء، لأن المُجمِّع هو من يقررها. ولا يُنتج @module-federation/vite ذلك الملف إلا إذا ضُبط على manifest: true، وهو معطّل افتراضيًا — لذا يفعّله كل عنصر تحكم في بارسوير، ويرفض المُحزِّم التخمين إن غاب.
• logicalName وdisplayName وdescription وsubstitutesFor تأتي من كتلة parsware في package.json لعنصر التحكم، لأن المُجمِّع لم يسمع بأيٍّ منها قط. أما version فهو حقل version في الملف نفسه.

ما هو غائب عن قصد

لا نطاقات معلنة ولا جداول معلنة. تعمل الأداة بصلاحيات الشخص الذي يستخدمها (§24)، فقائمة النطاقات على الأداة ما كانت لتفعل إلا أن تضيّق على مستخدمها، لا أن توسّع له.

ولا عنوان remote-entry. تُقدَّم الحزمة من عنوان المنصة نفسها على مسار يُحسب من البيئة ومن الاسم المنطقي، وهذا ما يتيح لعنصر تحكم أن ينتقل داخل حلّه بدل أن يُجلب من مضيف خارجي.

ما الذي تفحصه المنصة

عند الرفع، وقبل تخزين أي شيء:

1. الأرشيف ضمن حد الحجم المضغوط وهو ملف zip قابل للقراءة؛
2. لا يحمل أكثر من عدد الملفات المضبوط، ولا يتمدد إلى أكثر من الإجمالي المضبوط (يُفحص أثناء القراءة، ومرة أخرى أثناء الاستخراج — فالطول المعلن في ترويسة الـ zip ادّعاء يقوله الأرشيف عن نفسه)؛
3. مسار كل مدخل نسبي وآمن — .. والمسار المجذَّر وبادئة قرص ويندوز أو UNC كلها تُرفض لا تُنقَّح، لأن أرشيفًا يسمّي مسارًا خارج مجلده ليس أرشيفًا نُصلحه بصمت؛
4. لكل ملف امتداد ضمن قائمة السماح التي تقدّمها المنصة؛
5. parsware.json موجود في الجذر ويطابق هذا المخطط؛
6. kind يطابق نقطة النهاية، والملف الذي يسمّيه entry موجود فعلًا.

ذات صلة

• بناء عنصر تحكم مخصص — كتابته وتحزيمه.
• تسجيل عنصر تحكم مخصص — رفع الحزمة.
• بيان عنصر التحكم المخصص — الشكل المخزَّن الذي يُؤلَّف إليه هذا البيان.