أداة TypeScript: بناء رسم بياني هندسي من سجلات GitHub

مقدمة تحليلية

في 24 أغسطس 2026، كشف تقرير على Dev.to عن منهجية لبناء رسم بياني هندسي مصغر باستخدام TypeScript وGitHub. تهدف هذه الأداة إلى معالجة تحدٍ أساسي يواجهه المهندسون عند وراثة قواعد أكواد معقدة، مثل ملف checkout.ts الذي يسبب مشكلات متكررة. فبدلاً من البحث اليدوي في طلبات السحب والمراجعات وسجلات الملفات وذاكرة الفريق، التي تظل معلوماتها مبعثرة ضمن GitHub، تقدم هذه المنهجية حلاً منظماً.

تركز الفكرة المحورية على أن المعرفة الهندسية تزداد قيمتها عند الحفاظ على العلاقات بين العناصر التي ينشئها الفريق بالفعل. الأداة، وهي عبارة عن واجهة سطر أوامر (CLI) صغيرة مبنية بـTypeScript، تحول طلبات سحب GitHub الحقيقية إلى رسم بياني هندسي فعال. هذا النهج يتجنب الحاجة إلى قواعد بيانات رسوم بيانية معقدة أو قواعد بيانات متجهات أو نماذج ذكاء اصطناعي، ويعتمد بدلاً من ذلك على TypeScript وGitHub API وحدهما. الأوامر المتاحة تشمل الاستعلام عن مستودعات مثل vercel/ai، وتفاصيل طلب السحب pr 123، وتحديد الخبراء experts "src/example.ts"، والملفات ذات الصلة related "src/example.ts".

التحليل التقني

تعتمد البنية التقنية للأداة على أربعة أنواع رئيسية من العقد وأربعة أنواع من العلاقات لتمثيل المعرفة الهندسية. تشمل العقد: المستودع (مثل vercel/ai)، طلب السحب (مثلاً #482: Improve streaming response handling)، الملف (مثلاً packages/ai/src/generate-text.ts)، والشخص (مثلاً bobbyhalljr). أما العلاقات فهي: BELONGS_TO (طلب السحب ينتمي إلى مستودع)، AUTHORED (شخص أنشأ طلب سحب)، MODIFIED (طلب سحب عدّل ملفاً)، وREVIEWED (شخص راجع طلب سحب).

كل علاقة ضمن هذا الرسم البياني تتضمن دليلاً مباشراً، يتكون من المصدر (github)، رابط URL، ملخص، ووقت المراقبة (observedAt). هذا يضمن أن أي ادعاء، مثل تأليف أو مراجعة تغيير، يمكن تتبعه مباشرة إلى المصدر الأصلي في GitHub.

الكود الأساسي يتجسد في فئة EngineeringGraph التي تحتفظ بالعقد والحواف في خرائط الذاكرة. الطريقة الأهم هي neighbors التي تسمح بالاستعلام عن العقد المتصلة بعقدة معينة عبر علاقة محددة وفي اتجاه معين (صادر أو وارد). على سبيل المثال، الاستعلام عن pr:acme/storefront#41 والعلاقة MODIFIED يُرجع الملفات التي تم تغييرها بواسطة طلب السحب، بينما عكس الاتجاه لـ file:acme/storefront:src/checkout.ts يُرجع طلبات السحب التي عدّلت الملف ذاته. هذا التمايز في الاتجاه يحول العلاقة الواحدة إلى إجابتين مختلفتين.

تُبنى هذه الرسوم البيانية من بيانات GitHub الفعلية عبر دالة buildEngineeringGraph، التي تتصل بـ GitHub API. تتطلب هذه العملية:

• Node.js 18 أو أحدث.
• حد أقصى للطلبات غير الموثقة في GitHub API يبلغ 60 طلباً في الساعة.
• تحليل 10 طلبات سحب مغلقة حديثاً افتراضياً، ما يستهلك 21 طلب API (طلب واحد لسرد طلبات السحب، وطلب واحد لكل طلب سحب مدمج لسرد الملفات المتغيرة، وطلب واحد لكل طلب سحب مدمج لسرد المراجعات).
• إمكانية رفع حد طلبات السحب إلى 25 باستخدام متغير البيئة PR_LIMIT.

وتصنيف "الخبراء" يعتمد على نقاط مخصصة: 3 نقاط للمؤلف و1 نقطة للمراجع، وهي مقياس إرشادي بسيط، كما يتضح من الاختبار ranks pull request authors above reviewers.

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

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

الحلول الموجودة في السوق، مثل أدوات تحليل الكود المستندة إلى البحث النصي أو حتى بعض الأدوات التي توظف نماذج الذكاء الاصطناعي (AI) لتخمين الخبرة، غالباً ما تفتقر إلى الشفافية أو الدقة المدعومة بالأدلة. أداة TypeScript هذه تتفوق بتقديم "دليل" صريح لكل علاقة مكتشفة، مما يميزها عن الحلول التي قد "تخمن من يبدو مؤهلاً". فمثلاً، بدلًا من طلب نموذج لغة كبير (LLM) لاقتراح خبراء، فإن الأداة تشير إلى أن bobby وmaya هما الخبراء المحتملون بناءً على 4 نقاط لكل منهما (1 تأليف، 1 مراجعة أو العكس) مع روابط مباشرة لـ https://github.com/acme/storefront/pull/41 وhttps://github.com/acme/storefront/pull/40#review-2. هذا الدليل القاطع يعزز الثقة في النتائج.

ما يميز هذه الأداة أيضاً هو أنها لا تتطلب "قاعدة بيانات رسوم بيانية" أو "قاعدة بيانات متجهات" أو "نموذج ذكاء اصطناعي"، مما يقلل من التعقيد التشغيلي والتكاليف. إنها تقف كمنافس مباشر للجهود اليدوية والتخمينات غير المستندة إلى بيانات، وتوفر حلاً عملياً لتحديات فهم الكود التي تتجاوز مجرد البحث عن الكلمات المفتاحية، وتحدد بدقة الملفات ذات الصلة التي قد تتغير مع src/payments.ts بـ 2 تغييرات مشتركة.

رؤية Glitch4Techs

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

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