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

1. تأكيد المسار الدقيق والتغيير

في التطبيق المتأثر، تحقق من المجلد المفتوح كمساحة عمل وتأكد من أن الملف المعدل يقع داخل ذلك المجلد. يمكن أن يظهر الملف في المحرر بينما يكون خارج جذر المراقبة؛ كما قد تتصرف الروابط الرمزية (symbolic links) بشكل مختلف عن المجلدات المتداخلة العادية. على سبيل المثال، يوضح توثيق VS Code أن أداة المراقبة الخاصة به على macOS تستخدم FSEvents، وأنه لا يتم تتبع الروابط الرمزية تلقائيًا، وأن إعداد استبعاد أداة المراقبة يمكنه حذف مسارات معينة. تنطبق هذه التفاصيل على VS Code وليس بالضرورة على كل تطبيق Mac، لذا تحقق من إعدادات مساحة العمل والاستبعاد المماثلة في أداتك الخاصة. VS Code: File Watcher Issues

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

2. التحقق مما إذا كان التطبيق قد استلم الأحداث

إشعارات نظام الملفات ليست وعداً بتقديم رد نداء (callback) دقيق لكل تعديل فردي. تذكر وثائق FSEvents من Apple أنه يمكن دمج الأحداث معاً؛ وعند تعيين علامة MustScanSubDirs، يجب على العميل إعادة فحص الدليل المحدد بشكل متكرر وتراجعي (recursively). تشير علامات الأحداث التي تم إسقاطها (dropped-event flags) إلى مشاكل في التخزين المؤقت وتتطلب فحصاً كاملاً للأدلة الخاضعة للمراقبة. هذا يعني أن أداة المراقبة التي تعمل بشكل جيد تحتاج إلى تسوية المحتويات الحالية للدليل ومطابقتها، بدلاً من الاعتماد فقط على تسلسل مثالي من الإشعارات. Apple: Using the File System Events API، Apple: FSEventStreamEventFlags

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

3. استخدام fs_usage لفحص نشاط نظام الملفات

يتضمن macOS أداة fs_usage، والتي تعرض نشاط استدعاءات النظام المتعلقة بنظام الملفات أثناء حدوثها. يمكن أن تساعد في تحديد ما إذا كان التطبيق المعني يصل إلى الملفات أثناء عملية إعادة الإنتاج، ولكنها ليست أداة لعرض أحداث FSEvents ولا يمكنها إثبات أن أداة المراقبة قد تلقت إشعاراً أو عالجته. تشير Apple إلى أن عناصر التحكم في الوصول تُطبق وأن الوصول بصلاحيات root قد يكون مطلوباً. Apple: Examining File-System Usage

في تطبيق Terminal، أعد إنتاج المشكلة أثناء مراقبة التطبيق المحدد. استبدل اسم العملية الفعلي بـ YourApp (على سبيل المثال، قد يختلف اسم عملية التطبيق عن اسم العرض الخاص به):

sudo fs_usage -w YourApp

أوقف العرض المباشر باستخدام Control-C بعد إعادة الإنتاج القصيرة. يمكن أن تكون المخرجات مزدحمة، لذا ركز على وقت التعديل والمسارات ذات الصلة. إذا كان اسم العملية غير مؤكد، فراجع وثائق التطبيق أو مراقب النشاط (Activity Monitor)؛ لا تفترض أن التصفية بناءً على اسم تم تخمينه ستُظهر العملية الصحيحة. يُعد fs_usage وسيلة مساعدة تشخيصية لنشاط الملفات، وليس أمراً لإعادة تعيين أداة المراقبة أو إصلاحها.

4. مقارنة الحجم وظروف الوصول

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

تحقق مما إذا كان التطبيق المتأثر يمكنه الوصول إلى موقع المشروع. يمكن لعناصر التحكم في الخصوصية وقواعد App Sandbox في macOS تقييد الوصول إلى المجلدات، وتوضح وثائق Apple أن الوصول إلى المواقع المحمية قد يتطلب تفويضاً من المستخدم في إعدادات النظام. راجع حالة إذن التطبيق ضمن System Settings > Privacy & Security، وامنح فقط الوصول المطلوب لهذه المهمة. قد تمنع مشكلة الأذونات الوصول المفيد إلى الملف حتى عندما يظهر المسار داخل التطبيق. Apple: Accessing Files from the macOS App Sandbox

5. اختيار الخطوة التالية بناءً على الأدلة

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

المصادر