موجّه شامل لتدقيق المستودع ومعالجة المشكلات

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

## المرحلة 1: التقييم الأولي للمستودع

### 1.1 رسم خريطة البنية المعمارية
- ارسم خريطة هيكل المشروع بالكامل (src/, lib/, tests/, docs/, config/, scripts/, وغيرها)
- حدّد حزمة التقنيات والتبعيات (package.json, requirements.txt, go.mod, pom.xml, Gemfile, وغيرها)
- وثّق نقاط الدخول الرئيسية، والمسارات الحرجة، وحدود النظام
- حلّل إعدادات البناء ومسارات CI/CD
- راجع التوثيق الموجود (README، توثيق API، المخططات المعمارية)

### 1.2 تحليل بيئة التطوير
- حدّد أطر الاختبار المستخدمة (Jest, pytest, PHPUnit, Go test, JUnit, RSpec، وغيرها)
- راجع إعدادات الفحص linting والتنسيق formatting (ESLint, Prettier, Black, RuboCop، وغيرها)
- افحص وجود تتبّع للمشكلات (GitHub Issues، وتعليقات TODO/FIXME/HACK/XXX)
- حلّل سجل commits لتحديد المناطق التي ظهرت فيها مشكلات مؤخرًا
- راجع تقارير تغطية الاختبارات الحالية إن وجدت

## المرحلة 2: اكتشاف الأخطاء بشكل منهجي

### 2.1 فئات الأخطاء المطلوب اكتشافها
**أخطاء حرجة:**
- ثغرات أمنية (SQL injection، XSS، CSRF، تجاوز المصادقة، وغيرها)
- مخاطر تلف البيانات أو فقدانها
- انهيار النظام أو حالات deadlock
- تسرّب الذاكرة أو استنزاف الموارد

**أخطاء وظيفية:**
- أخطاء منطقية (شروط غير صحيحة، حسابات خاطئة، أخطاء off-by-one)
- مشكلات إدارة الحالة (race conditions، حالة غير متسقة، تعديلات غير سليمة)
- عقود API أو خرائط بيانات غير صحيحة
- تحققات ناقصة أو غير صحيحة
- قواعد أعمال أو مسارات عمل متعطلة

**أخطاء التكامل:**
- استخدام غير صحيح لواجهات API خارجية
- أخطاء أو عدم كفاءة في استعلامات قاعدة البيانات
- مشكلات في التعامل مع طوابير الرسائل message queues
- مشكلات في عمليات نظام الملفات
- أخطاء في اتصال الشبكة

**الحالات الحدّية ومعالجة الأخطاء:**
- التعامل مع null/undefined/nil
- المجموعات الفارغة أو حالات القيم الصفرية
- شروط الحدود وتجاوز الحدود المسموحة
- غياب تمرير الأخطاء أو كتم الاستثناءات
- مشكلات منطق timeout و retry

**مشكلات جودة الكود:**
- عدم تطابق الأنواع أو استخدام casts غير آمنة
- استخدام APIs مهملة أو deprecated
- كود ميت أو فروع غير قابلة للوصول
- تبعيات دائرية
- اختناقات أداء (استعلامات N+1، خوارزميات غير فعّالة)

### 2.2 طرق الاكتشاف
- تحليل ثابت للكود باستخدام أدوات مناسبة لكل لغة
- البحث عن الأنماط الشائعة المضادة للممارسات الجيدة
- فحص ثغرات التبعيات
- تحليل مسارات الكود غير القابلة للوصول أو غير المختبرة
- التحقق من صحة الإعدادات
- مطابقة التوثيق مع التنفيذ الفعلي

## المرحلة 3: توثيق الأخطاء وترتيب الأولويات

### 3.1 قالب تقرير الخطأ
لكل خطأ يتم اكتشافه، وثّق الآتي:
```
BUG-ID: [Sequential identifier]
Severity: [CRITICAL | HIGH | MEDIUM | LOW]
Category: [Security | Functional | Performance | Integration | Code Quality]
File(s): [Complete file path(s) and line numbers]
Component: [Module/Service/Feature affected]

Description:
- السلوك الحالي (ما الخلل الحاصل)
- السلوك المتوقع (ما الذي يجب أن يحدث)
- تحليل السبب الجذري

Impact Assessment:
- أثره على المستخدم (تراجع تجربة الاستخدام، فقدان بيانات، تعرض أمني)
- أثره على النظام (الأداء، الاستقرار، قابلية التوسع)
- أثره على العمل (الامتثال، الإيرادات، السمعة)

Reproduction Steps:
1. [Step-by-step instructions]
2. [Include test data/conditions if needed]
3. [Expected vs actual results]

Verification Method:
- [Code snippet or test that demonstrates the bug]
- [Metrics or logs showing the issue]

Dependencies:
- Related bugs: [List of related BUG-IDs]
- Blocking issues: [What needs to be fixed first]
```

### 3.2 مصفوفة ترتيب الأولويات
رتّب الأخطاء بناءً على:
- **Severity**: Critical > High > Medium > Low
- **User Impact**: عدد المستخدمين أو الميزات المتأثرة
- **Fix Complexity**: Simple < Medium < Complex
- **Risk of Regression**: Low < Medium < High

## المرحلة 4: تنفيذ الإصلاحات

### 4.1 استراتيجية الإصلاح
**لكل خطأ:**
1. أنشئ فرع إصلاح مستقلًا (إذا كان المشروع يستخدم نظام تحكم بالإصدارات)
2. اكتب اختبارًا يفشل أولًا قبل الإصلاح (منهجية TDD)
3. نفّذ إصلاحًا محدودًا ومركّزًا
4. تحقق من نجاح الاختبار
5. شغّل اختبارات الانحدار
6. حدّث التوثيق عند الحاجة

### 4.2 إرشادات الإصلاح
- **مبدأ أقل تغيير ممكن**: استخدم أصغر تعديل يعالج المشكلة بشكل صحيح
- **بدون توسّع خارج النطاق**: تجنّب إعادة الهيكلة أو التحسينات غير المرتبطة
- **الحفاظ على التوافق السابق**: إلا إذا كان الخطأ نفسه يتطلب تغييرًا كاسرًا للتوافق في API
- **اتباع معايير المشروع**: التزم بأسلوب الكود والأنماط المعتمدة في المشروع
- **إضافة برمجة دفاعية**: امنع تكرار أخطاء مشابهة مستقبلًا

### 4.3 قائمة مراجعة الكود
- [ ] الإصلاح يعالج السبب الجذري وليس الأعراض فقط
- [ ] جميع الحالات الحدّية تمت معالجتها
- [ ] رسائل الخطأ واضحة وتساعد على اتخاذ إجراء
- [ ] أثر الأداء مقبول
- [ ] تمت مراعاة الاعتبارات الأمنية
- [ ] لم تتم إضافة تحذيرات أو أخطاء linting جديدة

## المرحلة 5: الاختبار والتحقق

### 5.1 متطلبات الاختبار
**لكل خطأ تم إصلاحه، وفّر:**
1. **Unit Test**: اختبارًا معزولًا للإصلاح المحدد
2. **Integration Test**: إذا كان الخطأ يشمل أكثر من مكوّن
3. **Regression Test**: للتأكد من أن الإصلاح لا يكسر الوظائف الحالية
4. **Edge Case Tests**: لتغطية الحالات الحدّية المرتبطة

### 5.2 هيكل الاختبار
```[language-specific]
describe('BUG-[ID]: [Bug description]', () => {
  test('should fail with original bug', () => {
    // هذا الاختبار كان سيفشل قبل الإصلاح
    // يوضح وجود الخطأ
  });
  
  test('should pass after fix', () => {
    // هذا الاختبار ينجح بعد الإصلاح
    // يتحقق من السلوك الصحيح
  });
  
  test('should handle edge cases', () => {
    // تغطية إضافية للحالات الحدّية
  });
});
```

### 5.3 خطوات التحقق
1. شغّل كامل حزمة الاختبارات: `[npm test | pytest | go test ./... | mvn test | etc.]`
2. افحص تغيّر تغطية الاختبارات
3. شغّل أدوات التحليل الثابت
4. تحقق من مؤشرات الأداء القياسية إذا كانت منطبقة
5. اختبر في بيئات مختلفة إن أمكن

## المرحلة 6: التوثيق والتقارير

### 6.1 توثيق الإصلاح
لكل خطأ تم إصلاحه:
- حدّث التعليقات داخل الكود لشرح الإصلاح
- أضف أو حدّث توثيق API إذا تغيّر السلوك
- أنشئ أو حدّث أدلة استكشاف الأخطاء وحلها
- وثّق أي حلول مؤقتة للمشكلات غير المعالجة

### 6.2 تقرير الملخص التنفيذي
```markdown
# تقرير إصلاح الأخطاء - [Repository Name]
التاريخ: [YYYY-MM-DD]
المحلّل: [Tool/Person Name]

## نظرة عامة
- إجمالي الأخطاء المكتشفة: [X]
- إجمالي الأخطاء التي تم إصلاحها: [Y]
- غير مُصلح/مؤجل: [Z]
- تغيّر تغطية الاختبارات: [Before]% → [After]%

## أبرز النتائج الحرجة
[List top 3-5 most critical bugs found and fixed]

## ملخص الإصلاح حسب الفئة
- الأمن: [X bugs fixed]
- الوظائف: [Y bugs fixed]
- الأداء: [Z bugs fixed]
- التكامل: [W bugs fixed]
- جودة الكود: [V bugs fixed]

## قائمة الإصلاحات التفصيلية
[Organized table with columns: BUG-ID | File | Description | Status | Test Added]

## تقييم المخاطر
- المشكلات عالية الأولوية المتبقية: [List]
- الخطوات التالية الموصى بها: [Actions]
- الدين التقني الذي تم رصده: [Summary]

## نتائج الاختبار
- أمر الاختبار: [exact command used]
- الاختبارات الناجحة: [X/Y]
- الاختبارات الجديدة المضافة: [Count]
- أثر التغطية: [Details]
```

### 6.3 قائمة تسليم المخرجات
- [ ] تم توثيق جميع الأخطاء بالصيغة القياسية
- [ ] تم تنفيذ الإصلاحات واختبارها
- [ ] تم تحديث حزمة الاختبارات وهي ناجحة
- [ ] تم تحديث التوثيق
- [ ] تم إكمال مراجعة الكود
- [ ] تم تقييم أثر الأداء
- [ ] تم إجراء مراجعة أمنية للإصلاحات المتعلقة بالأمن
- [ ] تم تجهيز ملاحظات النشر

## المرحلة 7: التحسين المستمر

### 7.1 تحليل الأنماط
- حدّد أنماط الأخطاء المتكررة
- اقترح إجراءات وقائية
- أوصِ بتحسينات على الأدوات
- اقترح تعديلات معمارية تمنع تكرار مشكلات مشابهة

### 7.2 توصيات المراقبة
- اقترح مؤشرات يتم تتبعها
- أوصِ بقواعد تنبيه مناسبة
- اقترح تحسينات على التسجيل logging
- حدّد المناطق التي تحتاج إلى تغطية اختبارات أفضل

## القيود وأفضل الممارسات

1. **لا تساوم أبدًا على الأمن** مقابل التبسيط
2. **حافظ على سجل تدقيق** لكل التغييرات
3. **اتبع الإصدار الدلالي semantic versioning** إذا كانت الإصلاحات تغيّر API
4. **احترم حدود المعدل rate limits** عند اختبار الخدمات الخارجية
5. **استخدم feature flags** للإصلاحات عالية المخاطر إذا كان ذلك مناسبًا
6. **ضع استراتيجية rollback** لكل إصلاح
7. **وثّق الافتراضات** التي اعتمدت عليها أثناء التحليل

## صيغة المخرجات
قدّم النتائج بالصيغ التالية:
- Markdown لتسهيل القراءة البشرية
- JSON/YAML للمعالجة الآلية
- CSV للاستيراد في أنظمة تتبع الأخطاء

## اعتبارات خاصة
- في monorepos: حلّل كل package بشكل مستقل
- في microservices: راعِ التبعيات بين الخدمات
- في الكود القديم legacy: وازن بين مخاطر الإصلاح وفائدته
- في تبعيات الطرف الثالث: بلّغ المشروع الأصلي upstream عند الحاجة