diff --git "a/tools/mihrab/0000-\331\205\330\255\330\261\330\247\330\250-\331\205\330\255\330\261\330\261-\331\204\330\272\330\251-\330\265-\330\247\331\204\331\205\330\263\330\252\331\202\331\204.md" "b/tools/mihrab/0000-\331\205\330\255\330\261\330\247\330\250-\331\205\330\255\330\261\330\261-\331\204\330\272\330\251-\330\265-\330\247\331\204\331\205\330\263\330\252\331\202\331\204.md" new file mode 100644 index 0000000..8cf148e --- /dev/null +++ "b/tools/mihrab/0000-\331\205\330\255\330\261\330\247\330\250-\331\205\330\255\330\261\330\261-\331\204\330\272\330\251-\330\265-\330\247\331\204\331\205\330\263\330\252\331\202\331\204.md" @@ -0,0 +1,157 @@ +- **عنوان المقترح:** محراب — محرّر لغة ص المستقلّ (VSCodium-مرقَّع) +- **النطاق:** أداة `tools/mihrab` +- **تاريخ البدء:** 2026-06-30 +- **رقم الـ RFC:** (يُترك فارغًا حتى الدمج — يصبح رقم الـ PR في مستودع `sadlang-rfcs` نفسه) +- **الحالة:** مقترَح (PR مفتوح) +- **Issue التتبُّع:** (يُترك فارغًا حتى القبول) + +# ملخّص + +**محراب** محرّرٌ وبيئة تطوير **مستقلّة** للغة ص، مبنيّ على **VSCodium-مرقَّع** — +لا تفرّع عميق (نمط Cursor) ولا تجميد (hard fork). يحزم سلسلة أدوات ص (إضافة المحرّر + +خادم LSP + `sad-build`/`sad-run`) بتهيئة صفريّة، ويقدّم **دعم RTL من الدرجة الأولى** +الذي يستحيل تحقيقه كاملًا بطبقة إضافة وحدها. النتيجة المرئيّة: يثبّت المستخدم تطبيقًا +واحدًا باسم «محراب» بهويّة مملوكة بالكامل، يفتح ملفّ `.ص`، فيعمل كلّ شيء (إبراز، إكمال، +تشخيص، بناء، تشغيل) دون أيّ إعداد — في محرّر عربيّ الاتّجاه أصالةً. + +هذا المقترح **وحدة حَجْز عمل (claim)** لتثبيت محراب كمسار رسميّ قبل بدء التنفيذ (م0)، +وليس تغييرًا في نواة اللغة. التخطيط التفصيليّ يعيش في +[`sadlang-planning/projects/mihrab-editor/`](https://github.com/sadlang/sadlang-planning/tree/main/projects/mihrab-editor) +(خطّة التأسيس م0–م5 + مرجعيّة الاختبارات + ميزات التمايز)، ويُسجَّل المعلم في +الفيدراليّة بمعرّف `M-mihrab-1.0` (المرحلة الثالثة). + +# الدافع (Motivation) + +لغة ص **عربيّة أوّلًا**، لكنّ بيئات التطوير الحاليّة مبنيّة على افتراض الاتّجاه من +اليسار إلى اليمين (LTR). تقدّم المنظومة اليوم ثلاث إضافات VS Code متمايزة +(`vs_code_rtl`، `arabic_vscode`، `vscode-extension`) — وهي تعالج معظم المنطق على طبقة +الإضافة بدَيْن دمج شبه معدوم. لكن تبقى فجوات **بنيويّة لا تُسدّ من طبقة إضافة**: + +1. **RTL على مستوى القشرة (workbench) والمحرّر (Monaco):** اتّجاه ألواح الأدوات، + وثنائيّة الاتّجاه (bidi) ومحارف التحكّم (Trojan-Source)، والتفاف الأسطر — كلّها في + نواة VS Code، لا في واجهة الإضافة. +2. **تجربة تهيئة صفريّة:** اليوم يحتاج المستخدم تثبيت VS Code + الإضافات + سلسلة أدوات + يدويًّا. محراب يحزمها معًا فيختفي حاجز الإعداد. +3. **ملكيّة الهويّة:** الاسم والعلامة وسوق الإضافات (Open VSX) مملوكة بالكامل دون + الارتهان لإصدارات مايكروسوفت — مع **بقاء القاعدة متزامنة مع المنبع** (ملكيّة + الهويّة ≠ تباعد قاعدة الشيفرة). +4. **النجمة القطبيّة (dogfooding):** حين تنضج خلفيّة JS/WASM في المترجم، نعيد كتابة + LSP بلغة ص، ثم — لاحقًا — نستبدل القشرة بمضيف خاصّ (Monaco أو SadUI). محراب هو + الحامل الذي يجعل هذا المسار ممكنًا تدريجيًّا. + +حالة استخدام واقعيّة: مطوّر يكتب `اطبع("مرحبًا")` في ملفّ `.ص`؛ في محراب يرى النصّ +بمحاذاة يمينيّة صحيحة، مع إكمال عربيّ، وزرّ «تشغيل» يستدعي `sad-run` مباشرة — بلا أيّ +ضبط مسبق. + +# الشرح التوجيهي (Guide-level explanation) + +من منظور المستخدم، محراب **محرّر مستقلّ** لا إضافة: + +- يُنزّل تطبيق «محراب» لمنصّته (ويندوز أو ماك أو لينكس)، يثبّته، يفتحه. +- يفتح مجلّد مشروع `.ص`؛ كلّ مزايا اللغة حاضرة فورًا (إبراز، إكمال، تشخيص، تنسيق، + تعريف ومرجع) لأنّ خادم LSP وسلسلة الأدوات **محزومة**. +- الواجهة عربيّة الاتّجاه أصالةً: الشريط الجانبيّ يمينًا، والمحرّر يتعامل مع bidi دون + كسر، والتفاف الأسطر صحيح. +- يضغط «بناء» ← يستدعي `sad-build`؛ و«تشغيل» ← يستدعي `sad-run`. لا إعداد مسارات. + +```sad +# يفتحه المستخدم في محراب فيعمل فورًا — بلا تهيئة +دالة رئيسية() { + اطبع("مرحبًا بالعالم") +} +``` + +العلاقة بالمنتجات القائمة: محراب **يحزم القلب المفتوح** لإضافة المحرّر (يبني على +نمط Strategy في `vs_code_rtl`) — لا يكرّرها ولا يستبدلها. الإضافات تبقى صالحة لمن +يفضّل VS Code نفسه؛ ومحراب لمن يريد بيئة عربيّة-أوّلًا متكاملة بهويّة مستقلّة. محراب +**فئة مختلفة** عن الإضافات الثلاث (محرّر مستقلّ، لا إضافة رابعة). + +# الشرح المرجعي (Reference-level explanation) + +محراب **ليس تغييرًا في نواة اللغة**؛ لا كلمة مفتاحيّة أو توجيه أو نوع أو خطأ جديد. +الأثر على الأنظمة المتشابكة: + +- **مصدر الحقيقة (`language-truth/`):** لا تغيير. (محراب مستهلِك للأدوات، لا يوسّع + مصدر الحقيقة.) +- **المحلل المعجمي/النحوي · AST · المفسّر · المترجم (`sad-build`):** لا تغيير في + داخليّاتها؛ محراب يستدعيها كصناديق سوداء عبر LSP وثنائيّات `sad-build`/`sad-run`. +- **نظام الأخطاء:** يعرضها كما يصدرها الكتالوج عبر LSP؛ لا رموز جديدة. +- **الأدوات:** محراب **يحزم** خادم LSP والمنسّق وسلسلة الأدوات؛ ونقطة التكامل هي + بروتوكول LSP واستدعاء الثنائيّات. لا تعديل في داخليّات الأدوات. +- **التوافق الخلفي:** لا أثر على برامج `.ص` القائمة (محراب طبقة تطبيق). + +## نموذج التغيير: قاعدة الطبقات الثلاث + +الرافعة الحاكمة لدَيْن الدمج هي **موضع** التغيير لا حقيقة التفرّع: + +| الطبقة | المثال | دَيْن الدمج | +|--------|--------|------------| +| 1 — إضافة محزومة | معظم منطق ص (إبراز/إكمال/تشخيص عبر LSP) | شبه معدوم | +| 2 — مساهَمة بناء | `product.json`، والإعدادات الافتراضيّة، وسوق Open VSX | منخفض | +| 3 — رُقعة وقت-البناء | العلامة، وRTL النواة (workbench/Monaco)، وإزالة التتبّع | مرتفع — يُحتوى | + +**مؤشّر الصحّة هو عدد رُقَع الطبقة الثالثة.** كلّما قلّ، قلّ دَيْن الصيانة. + +## المراحل (DoD المعلم `M-mihrab-1.0`) + +- **م0** بناء VSCodium نظيف قابل للتكرار من المنبع. +- **م1** الهويّة (`product.json`: محراب، `.mihrab`، سوق Open VSX + الأصول). +- **م2** حزم سلسلة أدوات ص (الإضافة + LSP + `sad-build`/`sad-run`) بتهيئة صفريّة. +- **م3** RTL من الدرجة الأولى — الرُقعة النواة المبرَّرة الوحيدة، وتُقسَّم إلى: + م3-أ (bidi وTrojan-Source، صغيرة عالية القيمة) · م3-ب (اتّجاه Monaco) · + م3-ج (workbench RTL، الأكبر — تُقيَّم أو تؤجَّل). **م3 عنق الزجاجة.** +- **م4** التوزيع (Open VSX + توقيع لكلّ منصّة + تحديث تلقائيّ كناقل لرُقَع أمان Chromium). +- **م5** أتمتة دَيْن الدمج (مزامنة دوريّة + مؤشّرات صحّة: عدد الرُقَع، والفاشل منها، + والتأخّر، وعمر Chromium). **تحدّد بقاء المشروع.** + +> سياج تنفيذيّ: لا يبدأ كود م0 قبل قبول هذا الـRFC وفتح Issue تتبُّع في مستودع كود +> محراب (يُنشأ عند البدء؛ ويُسجَّل في الفيدراليّة وفريق المحرّر). + +# السلبيات (Drawbacks) + +- **دَيْن أمنيّ Chromium:** امتلاك القشرة يعني تحمّل مسؤوليّة ترقيع Chromium/Electron + أمنيًّا (ما تتحمّله مايكروسوفت اليوم) — أثقل ما في القرار، ويُدار بـم4 وم5. +- **دَيْن دمج المنبع:** يتراكم إن أُهمل؛ ويُحتوى بقاعدة الطبقات الثلاث ومؤشّر الصحّة. +- **مشروع متعدّد السنوات** بكلفة هندسيّة كبيرة (امتلاك قشرة ضخمة فعليًّا للتشغيل لا + للتعديل). +- **م3-ج (workbench RTL)** الأعلى كلفةً وخطرًا؛ وقد يلزم تأجيله. + +# المبرّرات والبدائل (Rationale and alternatives) + +- **لماذا VSCodium-مرقَّع؟** يحقّق ملكيّة الهويّة الكاملة مع أدنى دَيْن دمج وبقاء + التزامن مع المنبع — التوازن الأمثل بين الاستقلال والصيانة. +- **بديل: تفرّع عميق (نمط Cursor).** مرفوض: يعظّم دَيْن الدمج ويبعدنا عن المنبع بلا + حاجة فعليّة لتعديلات عميقة في القشرة. +- **بديل: تجميد (hard fork).** مرفوض: لا يلغي دَيْن الصيانة بل **يبدّله** — دمجُ + المنبع (تتحمّله مايكروسوفت أمنيًّا اليوم) يصير دَيْنًا أمنيًّا وشيخوخيًّا يتحمّله + الفريق وحده، وهو أثقل. +- **بديل: الاكتفاء بالإضافات الثلاث.** مرفوض جزئيًّا: ممتاز لطبقة الإضافة، لكنه يترك + فجوات RTL البنيويّة (workbench وMonaco وbidi) وتجربة التهيئة الصفريّة دون حلّ. +- **أثر عدم الفعل:** تبقى تجربة عربيّة-أوّلًا منقوصة في القشرة، ويتعذّر مسار dogfooding. + +# أعمال سابقة (Prior art) + +- **VSCodium:** يثبت أنّ ملكيّة الهويّة (علامة + Open VSX) ممكنة مع تزامن آليّ كامل + مع المنبع — الأساس المباشر لمحراب. +- **Cursor:** تفرّع عميق لإضافة الذكاء؛ يوضّح كلفة دَيْن الدمج حين تثقل التعديلات. +- **Theia وEclipse:** قشرة قابلة لإعادة التركيب؛ درس في فصل الطبقات. +- **Zed:** محرّر أصليّ من الصفر؛ يوضّح الكلفة الهائلة للبديل «من الصفر» الذي نتجنّبه الآن. + +خصوصيّة ص: لا أحد من هؤلاء يعالج **العربيّة-أوّلًا وRTL** على مستوى القشرة — وهنا +مبرّر وجود محراب الحقيقيّ. + +# أسئلة غير محسومة (Unresolved questions) + +- **نطاق هذا الـRFC:** هل يقفل المراحل م0–م5 كاملةً، أم م0–م2 (الأساس) فقط ويُفتح + RFC لاحق لـم3 وم4 وم5؟ (مقترَح: يقفل المبدأ والمسار كاملًا، والتنفيذ يتدرّج عبر Issues.) +- **اسم مستودع كود محراب** ومتى يُنشأ (عند بدء م0). +- **توقيت dogfooding:** مشروط بنضوج خلفيّة JS/WASM في المترجم — خارج نطاق التنفيذ الآن. +- **حدّ م3-ج:** يُحسَم بالقياس أثناء التنفيذ (تقييم أو تأجيل). +- **خارج النطاق:** أيّ تغيير في نواة اللغة أو مصدر الحقيقة؛ والمنتجات المغلقة. + +# إمكانات مستقبلية (Future possibilities) + +- إعادة كتابة LSP بلغة ص فوق خلفيّة JS/WASM (dogfooding المرحلة الأولى). +- استبدال القشرة تدريجيًّا بمضيف خاصّ (Tauri أو أصليّ أو WASM) مع Monaco أو **SadUI**. +- لوحات تطوير أصيلة بـSadUI داخل محراب (مستكشف AST، ومنقّح، ومقياس أداء). +- تكامل المنقّح (debugger) المخطّط للمرحلة الثالثة مباشرةً في محراب.