جرّاح الكود الميت — تدقيق مرحلي وخارطة تنظيف لقاعدة الكود

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

────────────────────────────────────────
المرحلة 1 — الاستكشاف  (افحص كل شيء)
────────────────────────────────────────
تعقّب فئات الهدر التالية عبر قاعدة الكود بالكامل:

A) تعريفات غير قابلة للوصول
   • دوال / طرائق (methods) لا تُستدعى إطلاقًا (بما في ذلك الاستدعاءات غير المباشرة، callbacks، event handlers)
   • متغيرات وثوابت تُسنَد لها قيم ثم لا تُقرأ بعدها
   • Types أو classes أو structs أو enums أو interfaces مُعرّفة لكن لا تُنشأ ولا تُورّث ولا تُستخدم
   • ملفات مصدر كاملة مستبعدة من عملية البناء/التجميع أو لا تُستورد إطلاقًا

B) مسارات تحكم ميتة
   • فروع يستحيل الوصول إليها (مثل شروط نتيجتها دائمًا true/false،
     أو كود يأتي بعد return / throw / exit غير مشروط)
   • Feature flags ثُبّتت برمجيًا على حالة واحدة

C) اعتماديات وهمية
   • عبارات import / require / use التي لا يُستخدم أي symbol مُصدّر منها داخل الملف
   • اعتماديات على مستوى الحزمة (package.json, go.mod, Cargo.toml, وغيرها) بلا أي استخدام في الكود المصدري

────────────────────────────────────────
المرحلة 2 — التحقق  (لا تعتبر الكود الحي ميتًا)
────────────────────────────────────────
قبل وسم أي عنصر بأنه كود ميت، استبعد مصادر الإنذارات الكاذبة التالية:

- Dynamic dispatch, reflection, runtime type resolution
- حاويات Dependency Injection (ربط عبر أسماء نصية أو decorators)
- أهداف serialization / deserialization (نماذج ORM، JSON mappers، protobuf)
- Metaprogramming: macros, annotations, code generators, template engines
- Test fixtures وأدوات مخصصة للاختبارات فقط
- مساحة Public API العامة في المكتبات — الرموز المصدّرة قد يستهلكها عملاء خارجيون
- Framework lifecycle hooks (مثل beforeEach, onMount, middleware chains)
- سلوك تقوده الإعدادات (أسماء symbols داخل ملفات config، متغيرات البيئة، feature registries)

إذا انطبق أي من هذه الاستثناءات، خفّض درجة الثقة واذكر السبب بوضوح.

────────────────────────────────────────
المرحلة 3 — الفرز  (رتّب أولوية التنظيف)
────────────────────────────────────────
عيّن لكل نتيجة مستوى مخاطرة:

  🔴 HIGH    — آمن للحذف فورًا؛ لا يوجد مستدعون خارجيون ولا اعتماد على سلوك framework خفي
  🟡 MEDIUM  — غالبًا ميت، لكن قد يكون له استخدام غير مباشر؛ تحقّق قبل الحذف
  🟢 LOW     — غالبًا مستخدم عبر reflection / config / public API؛ ارفعه لمراجعة بشرية

────────────────────────────────────────
صيغة المخرجات
────────────────────────────────────────
أخرِج ثلاثة أقسام:

### 1. جدول النتائج

| # | File | Line(s) | Symbol | Category | Risk | Confidence | Action |
|---|------|---------|--------|----------|------|------------|--------|

Categories: UNREACHABLE_DECL / DEAD_FLOW / PHANTOM_DEP
Actions   : DELETE / RENAME_TO_UNDERSCORE / MOVE_TO_ARCHIVE / MANUAL_VERIFY / SUPPRESS_WITH_COMMENT

### 2. خارطة طريق التنظيف

اجمع النتائج في ثلاث دفعات متتابعة حسب مستوى المخاطرة.
لكل دفعة، اذكر:
  - تقدير عدد أسطر الكود المحذوفة (LOC)
  - الأثر المحتمل على حجم bundle / binary
  - ترتيب إعادة الهيكلة المقترح (أي الملفات تبدأ بها أولًا لتجنب الأخطاء المتسلسلة)

### 3. الملخص التنفيذي

| Metric | Count |
|--------|-------|
| Total findings | |
| High-confidence deletes | |
| Estimated LOC removed | |
| Estimated dead imports | |
| Files safe to delete entirely | |
| Estimated build time improvement | |

اختم بفقرة واحدة تقيّم الصحة العامة لقاعدة الكود،
ثم اذكر أعلى 3 إجراءات ذات أثر يجب على الفريق البدء بها أولًا.