عن المشروع

# plantuml.rs إعادة تنفيذ كاملة بلغة Rust لمكتبة [PlantUML](https://plantuml.com/) — مكتبة توليد المخططات بلغة Java — بهدف تحقيق التطابق السلوكي، مع ارتباطات لغوية لـ Java وTypeScript وPython عبر FFI. ## الحالة **قيد التطوير.** تحليل مخططات التسلسل وعرض SVG ومخرجات PREPROC (النص المعالج مسبقاً) تعمل ومختبرة مقابل المرجع بلغة Java. تُنقل أنواع المخططات الأخرى (الفئات، الأنشطة، حالات الاستخدام، إلخ) وخلفيات العرض (PNG، PDF، LaTeX) تدريجياً. راجع [`.agents/architecture.md`](.agents/architecture.md) للاطلاع على خارطة الطريق الكاملة. ## الميزات **تعمل حالياً:** - تحليل مخططات التسلسل (`plantuml-sequence`) - خلفية عرض SVG (`plantuml-svg`) - مخرجات PREPROC (النص المعالج مسبقاً عبر محرك TIM، `plantuml-preproc`) - واجهة عرض موحدة: `render_svg` و`render_preproc` و`render(source, format)` (`plantuml-engine`) - ارتباط Java عبر JNI — `PlantUml.renderSvg` / `PlantUml.renderPreproc` - ارتباط TypeScript عبر WASM — `renderSvg` / `renderPreproc` (المتصفح + Node.js) - حلّال قيود أحادي البعد لتحديد مواضع التخطيط (`plantuml-real`) - محرك تعبيرات نمطية مخصص (`plantuml-regex`) - المعالج المسبق: `!include` و`!define` والمتغيرات والشرطيات (`plantuml-preproc`) - إطار تحليل الأوامر (`plantuml-command`) - أوليات الرسومات ثنائية الأبعاد (`plantuml-klimt`) - نظام السمات والأنماط والقوالب (`plantuml-skin`) **مخطط لها:** - مخططات الفئات والأنشطة وحالات الاستخدام وأنواع أخرى - خلفيات عرض PNG وPDF وLaTeX/TikZ - محركات التخطيط (Graphviz / ELK) - برنامج سطر أوامر (`plantuml-cli`) - ارتباط Python (PyO3 + maturin) - مكتبة C FFI مشتركة لارتباطات لغوية إضافية ## البنية المعمارية ### خط المعالجة ``` نص المصدر │ ▼ BlockUmlBuilder يقسّم المدخل إلى كتل @start/@end │ ▼ BlockUml واحدة لكل كتلة @start/@end. كسولة: TimLoader يعالج مسبقاً (!include، !define، المتغيرات) ▼ PSystemBuilder createPSystem() توزّع إلى مصنع نوع المخطط (Sequence، Class، Activity، UseCase، إلخ) ▼ كائن Diagram نموذج المخطط في الذاكرة │ ▼ Diagram.exportDiagram() يعرض عبر StringBinder الخاص بـ FileFormat إلى SVG / PNG / PDF / LaTeX / EPS / إلخ ▼ بايتات المخرجات ``` ### حزمة Java ← صندوق Rust | حزم Java | صندوق Rust | المسؤولية | |------------------|------------|---------------| | `klimt` | `plantuml-klimt` | رسومات ثنائية الأبعاد: الأشكال، الهندسة، الخطوط، `StringBounder`، `UGraphic`، `TextBlock` | | `com.plantuml.ubrex` | `plantuml-regex` | محرك تعبيرات نمطية مخصص | | `preproc` / `tim` | `plantuml-preproc` | المعالج المسبق: `!include`، `!define`، المتغيرات، الشرطيات | | `command` | `plantuml-command` | إطار تحليل `Command` / `CommandFactory` | | `abel` / `cucadiagram` | `plantuml-model` | نموذج الكيانات/العلاقات: `Entity`، `Link`، `LeafType` | | `sequencediagram` | `plantuml-sequence` | مخطط التسلسل | | `skin` / `style` / `theme` | `plantuml-skin` | نظام السمات والأنماط والقوالب | | `real` | `plantuml-real` | حلّال قيود أحادي البعد لتحديد مواضع التخطيط | | `svg` | `plantuml-svg` | خلفية عرض SVG | | الجذر (جزئي) | `plantuml-engine` | `BlockUml`، `BlockUmlBuilder`، `PSystemBuilder`، `SourceStringReader`، واجهة عرض موحدة | | الجذر (جزئي) | `plantuml-core` | `Diagram`، `TextBlock`، `StringBounder`، `FileFormat`، `FileFormatOption` | | — | `plantuml-ffi` | مكتبة C FFI مشتركة للارتباطات اللغوية | | — | `plantuml-wasm` | وحدة WASM (wasm-bindgen) لارتباط TypeScript | ### أنماط التصميم يحافظ نقل Rust على أنماط التصميم الرئيسية من الأصل بلغة Java: 1. **المصنع + السجل** — يوزّع `PSystemBuilder` إلى تطبيقات `*DiagramFactory` لكل نوع عبر سجل قائم على السمات. 2. **نمط الأمر** — كل محلّل سطر مصدر هو `Command` مسجّل في `CommandFactory`؛ يُربط بسمة `Command` مع تطبيقات. 3. **الاستراتيجية** — يختار `FileFormat` خلفية العرض؛ اختيار خلفية التخطيط (Graphviz مقابل ELK) هو أيضاً استراتيجية، باستخدام كائنات السمات أو التعدادات. 4. **التهيئة الكسولة** — يبني `BlockUml.getDiagram()` النموذج عند الطلب عبر `OnceCell<T>` أو استدعاءات `build()` الصريحة. 5. **طريقة القالب** — يعرّف `TitledDiagram` / `Diagram` السلوك الأساسي الذي توسّعه الفئات الفرعية؛ يُربط بسمات ذات طرق افتراضية وتركيب. ## بنية مساحة العمل ``` plantuml.rs/ ├── crates/ │ ├── plantuml-core/ # Diagram، TextBlock، StringBounder، FileFormat │ ├── plantuml-klimt/ # رسومات ثنائية الأبعاد: الأشكال، الهندسة، الخطوط │ ├── plantuml-regex/ # محرك تعبيرات نمطية مخصص │ ├── plantuml-preproc/ # المعالج المسبق: !include، !define، المتغيرات │ ├── plantuml-command/ # إطار تحليل Command / CommandFactory │ ├── plantuml-model/ # نموذج الكيانات/العلاقات │ ├── plantuml-engine/ # خط المعالجة العلوي وواجهة العرض الموحدة │ ├── plantuml-svg/ # خلفية عرض SVG │ ├── plantuml-skin/ # نظام السمات والأنماط والقوالب │ ├── plantuml-real/ # حلّال قيود أحادي البعد للتخطيط │ ├── plantuml-sequence/ # مخطط التسلسل │ ├── plantuml-ffi/ # مكتبة C FFI مشتركة │ └── plantuml-wasm/ # وحدة WASM (wasm-bindgen) ├── bindings/ │ ├── plantuml-java/ # ارتباط Java (JNI) — com.vgerbot.plantuml:plantuml-java │ └── plantuml-ts/ # ارتباط TypeScript (WASM) — @vgerbot/plantuml ├── .agents/ # إرشادات الوكلاء ووثائق البنية المعمارية └── Cargo.toml # بيان مساحة العمل ``` ## البدء ### المتطلبات الأساسية - **سلسلة أدوات Rust** (إصدار 2021، `resolver = "2"`) - **Java 17+** — مطلوبة فقط لارتباط Java - **Node.js** — مطلوب فقط لارتباط TypeScript (`npm install` في `bindings/plantuml-ts`) ### البناء ```sh cargo build ``` ### الاختبار ```sh cargo test ``` ### الفحص ```sh cargo clippy --workspace -- -D warnings ``` ## الاستخدام ### Rust ```rust use plantuml_engine::render_svg; let svg = render_svg("@startuml\nAlice -> Bob: hello\n@enduml")?; ``` توزّع دالة `render` حسب `FileFormat`: ```rust use plantuml_engine::render; use plantuml_core::FileFormat; let svg = render("@startuml\nAlice -> Bob: hello\n@enduml", FileFormat::Svg)?; ``` ### Java إحداثيات Maven: ```xml <dependency> <groupId>com.vgerbot.plantuml</groupId> <artifactId>plantuml-java</artifactId> <version>0.1.0</version> </dependency> ``` الاستخدام: ```java import com.vgerbot.plantuml.PlantUml; String svg = PlantUml.renderSvg("@startuml\nAlice -> Bob: hello\n@enduml"); System.out.println(svg); ``` ### TypeScript التثبيت: ```sh npm install @vgerbot/plantuml ``` الاستخدام (المتصفح أو Node.js): ```typescript import { renderSvg } from '@vgerbot/plantuml'; const svg = await renderSvg('@startuml\nAlice -> Bob: hello\n@enduml'); ``` ### Python مخطط له (PyO3 + maturin). لم يُنفّذ بعد. ## بناء الارتباطات | الارتباط | أمر البناء | |---------|-------------| | Java | `cd bindings/plantuml-java && ./gradlew build` | | TypeScript | `cd bindings/plantuml-ts && npm run build` | ## الاختبار ```sh cargo test --workspace ``` نُقلت الاختبارات مباشرة من مرجع PlantUML بلغة Java: - **اختبارات Vega المدفوعة بالبيانات** — ملفات `.puml` مع مخرجات `.svg` / `.preproc` متوقعة، تُقارن مقابل بيانات المرجع بلغة Java. تغطي 38 اختبار SVG للتسلسل واختبارات PREPROC عبر مجموعات `asciiverse/` و`svg/` و`mvp/`. - **اختبارات Nonreg** — اختبارات انحدار منقولة من مجموعة nonreg بلغة Java. - **اختبارات الوحدة/المتنوعة** — اختبارات وحدة لكل صندوق في `#[cfg(test)] mod tests`. بيانات الاختبار مُودعة تحت `crates/plantuml-engine/tests/resources/vega/`. ## إرشادات النقل يتبع النقل تعييناً صارماً 1:1 للملفات من Java → Rust: - **التسمية**: PascalCase → snake_case للملفات والدوال؛ حزمة Java → مسار صندوق Rust. - **تعيين الملفات**: ملف Java واحد → ملف Rust واحد؛ حوكمة حجم الملف (≤500 / 501–800 / >800 سطر). - **OOP → Rust**: الواجهات → السمات، الفئات → البنى، التحميلات الزائدة → البانيات. - **معالجة الأخطاء**: `Result` + `thiserror` للمكتبات، `anyhow` لسطر الأوامر. لا أخطاء فادحة في كود المكتبة. - **تعليقات التوثيق**: جميع العناصر العامة تستشهد بمصدر Java، مثل `/// Ported from: net/sourceforge/plantuml/SourceStringReader.java`. راجع [`.agents/rules/java-to-rust-porting.md`](.agents/rules/java-to-rust-porting.md) للتفاصيل الكاملة. ## المساهمة راجع [`.agents/AGENTS.md`](.agents/AGENTS.md) لأعراف المشروع و[`.agents/architecture.md`](.agents/architecture.md) لنظرة عامة على البنية المعمارية وتعيين الطبقات وأنماط التصميم. ## الترخيص ترخيص MIT (وفقاً لملف [`LICENSE`](LICENSE) في مساحة العمل). > **ملاحظة:** يعلن `Cargo.toml` عن `license = "GPL-3.0-only"` في بيانات حزمة مساحة العمل، لكن ملف `LICENSE` المرجعي هو MIT. يعكس هذا الملف `LICENSE`. إذا كان المشروع يهدف إلى GPL-3.0، فيجب التوفيق بين ملف `LICENSE` وبيانات `Cargo.toml`.