هذا المستودع هو نقطة البداية لبناء محرر لغة مكتبي شبيه بـ VS Code ومترجم مستقل للغة البرمجة العربية المحددة في ملفات المقرر. المشروع يتجه إلى Flutter Desktop، مع فصل Clean Architecture بين الواجهة، منطق المحرر، البنية التحتية، ونواة المترجم.
قواعد اللغة ومتطلبات التكليف محفوظة داخل:
.project/skills/arabic-compiler-project/
├── SKILL.md
└── references/
├── language-rules.txt
└── assignment-requirements.txt
يجب قراءة الـ Skill قبل تعديل أي قاعدة أو مرحلة ترجمة. لا تُستبدل اللغة العربية بصياغة C-like ولا تُقبل نتائج ثابتة بدل نتائج ناتجة عن المصدر.
| الوثيقة | الغرض |
|---|---|
docs/architecture/architecture.md |
الطبقات وعقد التكامل |
docs/architecture/product-boundary.md |
ما يدخل في النطاق وما يبقى خارج الادعاء |
docs/architecture/editor-shortcuts.md |
مصفوفة أوامر المحرر واختبارها |
docs/assignment/12-code-component-guide.md |
سبب وجود كل مكون ومسار بياناته وحدوده |
docs/roadmap/roadmap.md |
مراحل البناء ومعايير الانتقال |
docs/testing/test-strategy.md |
اختبارات كل مرحلة ومعايير الجودة |
.github/workflows/ci.yml |
بوابة CI وبناء Desktop |
CHANGELOG.md |
سجل الإصدارات وملاحظات البناء |
يقدم المحرر مستكشف ملفات، مجلد workspace، تعدد الملفات والتبويبات، تحرير RTL، اختصارات، command palette، بحث واستبدال، تنسيق، themes، Undo/Redo transaction-based، تشخيصات، تشغيل وإيقاف، ولوحات Tokens وAST وSymbol Table وSemantic Diagnostics وTAC وAssembly وRuntime Output.
يُبنى كل تغيير في فرع مستقل ويُدمج عبر Pull Request بعد نجاح format وanalyze والاختبارات وبناء Desktop واختبار عقد JSON بين المحرر والمترجم. لا تُغلق أي Issue إلا بعد تنفيذ معايير القبول وخطة الاختبار المكتوبة فيها.
المستودع يحتوي على محرر Flutter Desktop ومترجم compiler_core مستقل يتواصل مع المحرر عبر JSON protocol الإصدار 0.5.0. تدعم النواة Lexer وParser/AST والتحليل الدلالي وSymbol Table وTAC وTyped IR وAssembly النصية وInterpreter، إضافة إلى backend dart-native محدود ومثبت باختبارات parity وartifact metadata.
يحتوي المحرر على workspace حقيقي وشجرة ملفات وتبويبات وتحرير وحفظ وتنسيق وتشخيصات وquick fixes محدودة وcompletion وhelp وghost text وsyntax/semantic highlighting وMinimap واختصارات التحرير وthemes ونتائج مراحل المترجم. توجد عشرة أمثلة نجاح مختلفة في examples/، وfixtures سلبية مستقلة في examples/errors/ لاختبار syntax وsemantic diagnostics.
الإصدار الحالي هو v0.0.3، ويشمل تحسينات محرر RTL، وإلزام الفاصلة المنقوطة العربية، وإصلاح بناء Windows، إضافة إلى قواعد المترجم العربي الأساسية وتحسين AST ومخرجات بروتوكول compiler. لا تُسمى Assembly binary، ولا يُعلن dart-native مترجمًا عامًا لكل قواعد اللغة؛ كلا الحدين موثق ومغطى فقط ضمن subset المثبت.
يتطلب بناء arabicc وجود CMake وFlex وBison ومترجم C متوافق. على Linux وmacOS:
cd packages/compiler_c
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallelوعلى Windows باستخدام Visual Studio:
cd packages/compiler_c
cmake -S . -B build
cmake --build build --parallel --config Releaseيتم توليد scanner الخاص بـ Flex في Windows بوضع wincompat لتجنب الاعتماد على unistd.h، كما أن الكود يستخدم نسخًا نصية محمولة ومتوافقة مع C17 وMSVC. بعد البناء يمكن اختبار عقد البروتوكول عبر:
dart run tool/verify_compiler_bundle.dart --executable packages/compiler_c/build/arabiccيتم نشر صورة بيئة التطوير تلقائيًا إلى ghcr.io/emran025/acsys360/dev:latest عند الدفع إلى الفرع الرئيسي.
يمكن بناء نسخة Windows كاملة من جذر المشروع باستخدام PowerShell. يتطلب السكربت Flutter وDart وCMake وVisual Studio مع أدوات C، إضافة إلى Flex وBison؛ ويمكن تثبيت الأخيرين عبر Chocolatey:
choco install winflexbison3 --yesبعدها شغّل:
powershell -ExecutionPolicy Bypass -File .\tool\build_windows_release.ps1ينفذ السكربت flutter pub get وdart format وflutter analyze وflutter test، ثم يبني arabicc.exe عبر CMake، ويبني المحرر بـ flutter build windows --release، ويضمّن المترجم داخل compiler\arabicc.exe. بعد ذلك يشغّل smoke test للبروتوكول ويكتب الحزمة القابلة للتوزيع هنا:
dist\acsys360-windows-local.zip
لإعادة البناء من الصفر:
powershell -ExecutionPolicy Bypass -File .\tool\build_windows_release.ps1 -Cleanيمكن تجاوز فحوص Dart/Flutter فقط عند الحاجة إلى تصحيح سريع للبناء، وليس كفحص إصدار نهائي:
powershell -ExecutionPolicy Bypass -File .\tool\build_windows_release.ps1 -SkipChecksلتوليد arabicc.exe من الكود الحالي ونسخه إلى المسار الذي يستخدمه التطبيق المحلي، شغّل من جذر المشروع في PowerShell:
powershell -ExecutionPolicy Bypass -File .\tool\build_windows_debug.ps1 -Runينتج السكربت الملف التالي:
build\windows\x64\runner\Debug\compiler\arabicc.exe
يتطلب ذلك وجود CMake وVisual Studio C++ وFlex/Bison وFlutter في PATH.