مصفوفة توثق تراخيص مكتبات المشروع: مشاريع تخرج هندسة البرمجيات

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

ابدأ من ملف القفل

حدد بيئة واحدة أولاً، مثل مشروع JavaScript يعتمد npm، وخذ manifest وlockfile من نسخة مستودع مؤرخة. يشرح توثيق GitHub لرسم الاعتماديات أن الرسم يستند إلى ملفات البيان والقفل وإلى بيانات اعتماديات قد ترسلها الواجهة؛ لذلك لا يعني غياب حزمة من رسم معين أنها غير موجودة في كل مخرجات البناء. استورد الملف كما هو، وسجل commit الذي قرأته ووقت الفحص وإصدار الأداة، ولا تحذف الحزم المتعدية لأنها لا تظهر في ملف manifest الأعلى.

اجعل حدود النموذج معلنة: هل يقرأ حزم الإنتاج فقط أم أدوات الاختبار أيضاً؟ هل يتعامل مع تبعيات النظام أو ملفات vendored؟ ابدأ بإيكوسيستم واحد كي يمكن تفسير المحلل، ثم أضف واحداً آخر بعد بناء اختبارات له. لا تخلط نسخة lockfile التي تغيرت بعد الإصدار مع نسخة التقرير؛ اربط كل صف ببصمة الملف أو commit. هكذا يستطيع عضو الفريق إعادة إنتاج القائمة عند مراجعة تقرير مشروع التخرج.

سجل الدليل لا النتيجة وحدها

لكل حزمة احتفظ بالاسم كما في سجل الحزم، الإصدار المقفل، نوع التبعية، عنوان ملف الترخيص إن وجد، النص الذي تعرف عليه المحلل، ورابط الصفحة الأصلية. تسمح مواصفة SPDX 2.3.1 بتمثيل معرفات التراخيص والتعبيرات المركبة ومعلومات المصدر في صيغة معيارية؛ لا تفترض أن كل حزمة تستخدم معرفاً معروفاً. قد يكون الملف مفقوداً، أو يحمل نصاً مخصصاً، أو يتضمن إشعاراً إضافياً. خزن الحالة «غير محسوم» صراحة بدلاً من ملئها بتخمين من اسم الحزمة.

يمكن أن يحتوي الصف على حقول: packageUrl، version، manifestPath، licenseExpression، evidencePath، evidenceHash، reviewedBy، decision، وnotes. لا تجمع كل هذه الحقول في عمود نصي؛ الحقول المنفصلة تسهل المقارنة بين إصدارين. إذا تغير ملف الترخيص وحده، أظهر الفرق. لا تضع بيانات أشخاص أو سجلات اتصال في التقرير العام. وقبل إضافة قاعدة آلية تربط SPDX identifier بقرار، تحقق أن التعبير لا يحتوي مشغلات أو استثناءات تحتاج إلى تفسير.

مثال من ثلاث حزم

افترض مشروعاً مقفلاً على ثلاث حزم مباشرة: مكتبة واجهة ببيان ترخيص معروف، ومحلل CSV يحمل ملف LICENSE في المستودع، ومكتبة صغيرة لا يظهر لها ملف واضح في النسخة المنشورة. يعرض النظام أول حالتين مع رابط الدليل ونوع المصدر، ويضع الثالثة في قائمة مراجعة. لو قالت صفحة السجل شيئاً وملف النسخة شيئاً آخر، يسجل التعارض بدلاً من اختيار أحدهما بصمت. هذه بيانات تعليمية مصطنعة وليست نتيجة مسح لحزمة حقيقية.

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

قارن الإصدارات عبر الوقت

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

اجعل المراجعة البشرية جزءاً من دورة المشروع. يختار الفريق من كل فئة حالة واحدة ويفحص رابطها ونسختها، ويضيف قراراً مؤرخاً مع اسم المراجع داخل بيئة الجامعة. إذا كان المصدر غير متاح أو تغير، تظل الحالة معلقة. يمكن تقديم المصفوفة ضمن مشاريع التخرج وبناء قارئها كجزء من المشاريع البرمجية، مع توضيح أن فريقاً آخر يجب أن يتخذ قراراته وفق احتياجاته.

اختبارات قبول قابلة للتكرار

جهز عينات صغيرة: قفل بحزمة واحدة، تبعية متعدية، حزمة بلا بيانات ترخيص، ملف LICENSE مخصص، وتعبير SPDX مركب. اختبر أن العدد في التقرير يساوي عدد العناصر المقروءة، وأن كل صف يشير إلى نسخة المصدر الصحيحة، وأن غياب الملف يظهر كحالة معلقة لا كترخيص افتراضي. عدّل ملفاً واحداً ثم أعد التحليل وتأكد أن المقارنة تسجل هذا التغيير وحده. خط الأساس ملف CSV يدوي كتبه الفريق؛ قارن اكتمال الروابط والقدرة على إعادة الفحص، لا ادعاء الدقة المطلقة.

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

حدود ما يمكن استنتاجه

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

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