التخزين المؤقت والأداء

#أين يذهب الوقت

#الذاكرة المؤقتة لكل commit

منفّذة في src/cache/analysisCache.ts.

• المفتاح: معرّف الـ commit. القيمة: ‏CommitContribution الخاص بذلك الـ commit (الكاتب، والتاريخ، والأسطر المحللة، وسجلات ما أُدخل، وبصمات ما أُصلح، والأعداد).
• محتوى الـ commit لا يتغير أبداً، فالنتيجة المخزنة صالحة ما دامت القواعد والإعدادات هي نفسها. عمليات التشغيل اللاحقة تحلل الـ commits الجديدة فقط.
• التخزين: ملف JSON واحد لكل مستودع، commits-<hash of repo path>.json:

• يُكتب الملف مرة واحدة في نهاية التشغيل، وفقط إذا تغيّر شيء.
• فشل قراءة الذاكرة المؤقتة أو كتابتها يُتجاهل. الذاكرة المفقودة أو التالفة تعني فقط إعادة تحليل كاملة.

#الإلغاء

تُلغى الذاكرة المؤقتة كاملة للمستودع عندما تتغير أي من القيمتين:

1. ENGINE_VERSION (في scoringConfig.ts) — يُرفع كلما تغيّر منطق المحرّك.
2. بصمة إعدادات التحليل = قيمة FNV-1a لـ { engine, rules, sorted exclude list, scoring }. تغيير أي قاعدة، أو خطورة، أو حد، أو خيار، أو نمط استثناء (بما فيها المأخوذة من .gitignore / .gitattributes)، أو تخصيص للتقييم، يلغيها.

أشياء لا تلغي الذاكرة المؤقتة (ولا داعي لذلك): maxCommits وsince وdevelopers وmergeSameNameAuthors. هذه تحدد فقط أي الإدخالات المخزنة تُستخدم وكيف تُجمَّع.

#إيقافها

• في الإضافة: "cleanlens.cache.enabled": false.
• في سطر الأوامر: --no-cache.
• لمسحها يدوياً، احذف ملف أو ملفات commits-*.json في المجلدات أعلاه.

#التحسينات المدمجة

• git diff واحد لكل commit لكل ملفاته، مع --unified=0 (مخرجات صغيرة).
• git cat-file --batch واحد لكل commit لكل الـ blobs الخاصة به، بدلاً من git show لكل ملف.
• حفظ نتائج الـ blobs: تحليل الـ blob يُعاد استخدامه داخل التشغيل، فنسخة "ما بعد" في الـ commit رقم N ونسخة "ما قبل" في الـ commit رقم N+1 تُحلَّلان مرة واحدة.
• 12 commit بالتوازي (COMMIT_CONCURRENCY).
• التخطي المبكر: الملفات الثنائية وغير المدعومة والمستثناة وتعديلات المسافات فقط والمولَّدة لا تُحلَّل أبداً.
• الملفات الأكبر من 1 ميغابايت تُتخطى في فحص HEAD.
• المجلدات المستثناة لا تُدخَل أثناء استعراض الملفات.

#نصائح للمستودعات الكبيرة

1. أبقِ النافذة الافتراضية (500 commit) للاستخدام اليومي. تغطي معظم العمل النشط وهي سريعة.
2. استخدم analysis.since (مثلاً "12 months ago") لمراجعة محددة بفترة زمنية.
3. شغّل --full-history من وقت لآخر (مثلاً مهمة CI ليلية). الذاكرة المؤقتة تجعل التشغيلات اللاحقة تزايدية.
4. استثنِ الكود المضمَّن من مكتبات خارجية والمولَّد وبيانات الاختبار. هذا يوفر الوقت ويجعل النتائج أعدل.
5. أبقِ الذاكرة المؤقتة مفعّلة. بعد التشغيل الأول، فقط الـ commits الجديدة تستهلك وقتاً.
6. تجنّب تغيير القواعد كثيراً أثناء فترة تقييم: كل تغيير يفرض إعادة تحليل كاملة.

#مفاتيح الضبط على مستوى الكود

هذه ثوابت، وليست إعدادات. غيّرها في الكود وأعد البناء إذا احتجت:

ارفع ENGINE_VERSION إذا كان التغيير يؤثر في نتائج كل commit، حتى تُلغى الذاكرة المؤقتة القديمة.