SysML v2
أداة سطر الأوامر holarch
افحص نماذج SysML v2 ونسّقها وصدّرها في عمليات البناء وCI باستخدام أداة سطر الأوامر holarch وHolarch Language Engine؛ GitHub Actions وأنظمة CI الأخرى، وتقارير JSON وSARIF، ورموز الخروج، وتسجيل الدخول برمز API أو ملف ترخيص.
في هذه الصفحة
نظرة عامة
holarch أداة سطر أوامر تفحص ملفات نص SysML v2 بـ Holarch Language Engine، وهو المحرك نفسه الذي يستخدمه محرر Holarch. شغّلها على حاسوبك أو في عملية بناء: فهي تقرأ كل ملف .sysml في مجلد، وتبلغ عن المشكلات مع الملف والسطر والعمود، وتخرج برمز غير صفري حين يكون في النموذج أخطاء، فيفشل طلب السحب ذو النموذج المعطوب في فحوصه.
تؤدي الأداة ثلاثة أشياء:
- الفحص: الصياغة والأسماء والأنواع والتخصيصات والتعدديات والوحدات وقواعد المحرك الأخرى، عبر كل ملفات النموذج. وتبلغ بصيغة نص أو JSON أو SARIF (لفحص الشيفرة) أو تعليقات GitHub التوضيحية.
- التنسيق: تعيد كتابة الملفات بتخطيط قياسي واحد (إزاحة بأربع مسافات، وعنصر واحد في كل سطر، وتباعد قياسي)، مع الإبقاء على كل تعليق.
- التصدير: تكتب النموذج بصيغة SysML v2 JSON، وهي صيغة التبادل في Systems Modeling API.
تأتي الأداة مع خطتي Individual وTeam (بما في ذلك الفترة التجريبية)، ومع ترخيص Holarch Language Engine وترخيص الإصدار المستضاف ذاتيًا. ولا تحتاج إلى مشروع Holarch: فهي تعمل على الملفات في مستودعك.
المفاهيم
- النموذج: كل ملفات
.sysmlتحت المجلدات التي تسمّيها (الافتراضي: المجلد الحالي)، مقروءة كنموذج واحد. والاسم المعلن في ملف يُحَل في الملفات الأخرى، كما تفعل الحزم في مشروع Holarch. وتُتخطى المجلدات التي تبدأ أسماؤها بنقطة (مثل.git). - ملفات KerML: تُفحص ملفات
.kermlكـ KerML في إصدارات المحرك التي تقرأ KerML. وتدرجها إصدارات المحرك الأقدم كمتخطاة، وهذا ليس خطأ. - التشخيصات: لكل مشكلة رمز (مثل
name.unresolved)، وخطورة (خطأ أو تحذير أو ملاحظة)، وموضع، ورسالة بالكلمات نفسها التي في محرر Holarch. ولا تُفشل الفحصَ إلا الأخطاء، ما لم تضف--warnings-as-errors. - تسجيل الدخول: تتحقق الأداة مرة يوميًا من أن رمز API الخاص بك يتبع خطة Individual أو Team، أو تقرأ ملف ترخيص دون أي وصول إلى الشبكة. انظر تسجيل الدخول للأداة.
- المحرك: تحوي الأداة Holarch Language Engine المترجَم ومكتبة SysML v2 القياسية. ويطبع
holarch versionإصداراتهما وإشعار حقوق النشر للمحرك.
طريقة استخدامها
متى ولماذا
استخدم الأداة حيث يعيش نص SysML v2 في مستودع مصدر: يحرر المصممون ملفات .sysml في المحرر الذي يختارونه، ويُفحص كل تغيير قبل دمجه. فهي تجيب عن “هل ما زال هذا النموذج متماسكًا؟” في كل إيداع، كما يفعل المترجم للشيفرة. استخدم محرر Holarch للنمذجة والمخططات والمراجعات؛ واستخدم الأداة لحراسة الملفات بين التعديلات. ولنقل نموذج بين المستودع ومشروع Holarch، استخدم الاستيراد والتصدير.
التثبيت
- ثبّت Python 3.9 أو أحدث.
- ثبّت الأداة لنظامك (Linux x86-64 أو Linux arm64 أو macOS على Apple silicon) باستخدام pip:
python3 -m pip install holarch-cli
- افحص التثبيت: يطبع
holarch versionإصدارات الأداة والمحرك والمكتبة.
تسجيل الدخول برمز API
- في Holarch، افتح إعدادات الحساب ← رموز API وأنشئ رمزًا. والوصول للقراءة فقط كافٍ.
- ضع الرمز في متغير البيئة
HOLARCH_API_KEY(في CI: سر). - شغّل
holarch whoami. فهو يطبع خطتك وحسابك، مثل"plan": "team".
فحص نموذج
holarch check models/
كل مشكلة سطر واحد، ثم ملخص:
models/requirements.sysml:14:27: error name.unresolved: “MassValu” is not defined here. Check the spelling, or import its package.
6 files checked: 1 error, 0 warnings.
رمز الخروج 1 حين يكون في النموذج أخطاء و0 في غير ذلك. أضف --warnings-as-errors للفشل عند التحذيرات أيضًا.
تنسيق الملفات
- شغّل
holarch format models/. ويُدرج كل ملف متغير بالشكل “reformatted <file>”. - لفحص التخطيط في CI دون تغيير الملفات، شغّل
holarch format --check models/. فهو يدرج “would reformat <file>” ويخرج بـ 1 حين سيتغير ملف. - لرؤية التغييرات أولًا، شغّل
holarch format --diff models/.
لا يُنسَّق الملف الذي فيه أخطاء صياغة (“not formatted: the file has syntax errors.”، أي: لم يُنسَّق: في الملف أخطاء صياغة). وتبقى التعليقات حيث كانت: الملاحظات التي قبل عنصر تبقى فوقه، والملاحظة في نهاية سطر تبقى في نهاية ذلك السطر.
تصدير النموذج بصيغة SysML v2 JSON
holarch export models/ -o model.json
يحوي الملف مصفوفة العناصر القياسية في Systems Modeling API. والملفات نفسها تعطي دائمًا JSON نفسه، فيمكن إيداع التصدير ومقارنته. ولا يُصدَّر النموذج الذي فيه أخطاء (“The model has errors, so it was not exported.”، أي: في النموذج أخطاء، فلم يُصدَّر)؛ أضف --force لتصديره على أي حال. وأضف --holarch-fields للإبقاء على ما لا يقرؤه إلا Holarch (ترتيب العناصر والتهجئة)، لاستيراد مطابق إلى مشروع Holarch.
التشغيل في GitHub Actions
- أضف رمز API كسر للمستودع باسم
HOLARCH_API_KEY(Settings → Secrets and variables → Actions). - أضف ملف سير عمل، مثل
.github/workflows/sysml.yml:
name: SysML model
on: [push, pull_request]
jobs:
check:
runs-on: ubuntu-latest
permissions:
contents: read
security-events: write
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- run: python -m pip install holarch-cli
- run: holarch check models --format github --sarif holarch.sarif
env:
HOLARCH_API_KEY: ${{ secrets.HOLARCH_API_KEY }}
- run: holarch format --check models
- uses: github/codeql-action/upload-sarif@v3
if: always()
with:
sarif_file: holarch.sarif
- ادفع. تظهر المشكلات كتعليقات توضيحية على الأسطر المتغيرة في طلب السحب، وتفشل المهمة حين يكون في النموذج أخطاء أو يكون ملف بغير التخطيط القياسي. واستبعد خطوة
holarch format --checkلفحص النموذج فقط.
ترفع الخطوة الأخيرة تقرير SARIF إلى فحص الشيفرة، حيث تُدرج المشكلات تحت Security → Code scanning. واستبعدها إن كان مستودعك لا يستخدم فحص الشيفرة: فالتعليقات التوضيحية تعمل دونها.
التشغيل في أنظمة CI أخرى
أي نظام CI فيه Python 3.9 أو أحدث يشغّل الأوامر نفسها. ثبّت الأداة، واضبط الرمز من سر، وافحص:
python3 -m pip install holarch-cli
holarch check models/ --sarif holarch.sarif --json holarch.json
مثلًا، GitLab CI (.gitlab-ci.yml، مع HOLARCH_API_KEY كمتغير CI/CD مقنَّع):
sysml:
image: python:3.12
script:
- pip install holarch-cli
- holarch check models/ --sarif gl-holarch.sarif
- holarch format --check models/
artifacts:
when: always
paths: [gl-holarch.sarif]
تعمل Jenkins وAzure Pipelines وCircleCI وغيرها بالطريقة نفسها: خطوة تثبّت الأداة، والتالية تشغّل holarch check؛ ورمز الخروج غير الصفري يُفشل البناء. واحتفظ بتقرير JSON (--json) كمصنوع بناء حين تريد الأرقام في لوحة معلومات.
مثال تطبيقي: المشروع التوضيحي Hybrid Car
- أنشئ المشروع التوضيحي: في إدارة المشاريع، انقر ملفات المشروع ▾ ← مشروع توضيحي جديد ← Hybrid Car (SysML v2).
- افتح النموذج ← الاستيراد والتصدير. تحت تصدير، اختر النموذج كله ونص SysML v2، وانقر تصدير، وفك ضغط الملف المنزَّل في مجلد
modelsفي مستودعك. - شغّل
holarch check models. والنتيجة “6 files checked: 0 errors, 0 warnings.” (فُحصت 6 ملفات: 0 أخطاء، 0 تحذيرات). - في
requirements.sysml، غيّرattribute maxCurbMass : MassValueإلىMassValuوشغّل الفحص مجددًا. فيبلغ عنrequirements.sysml:14:27: error name.unresolved: “MassValu” is not defined here.ويخرج بـ 1. - تراجع عن التغيير. شغّل
holarch format modelsمرة واحدة وأودع الملفات، لتنجح عملياتformat --checkاللاحقة. - أضف سير عمل GitHub أعلاه. وكل طلب سحب لاحق يعطب النموذج يفشل في فحصه.
نصائح وممارسات جيدة
- ضع محتوى كل ملف في حزمة. تعمل العناصر الواقعة خارج أي حزمة، لكن حزمة لكل ملف تُبقي الأسماء فريدة عبر الملفات.
- استخدم رمزًا للقراءة فقط في CI، غير مقيّد بأي مشروع: فالأداة لا تحتاج إلى وصول إلى المشاريع.
- نسّق مرة واحدة وأودع النتيجة قبل تفعيل
format-check، وإلا فشل التشغيل الأول على كل ملف. - ثبّت إصدار الأداة في CI (
holarch-cli==<version>) لكي لا يغيّر إصدار جديد للمحرك النتائج في منتصف مراجعة. - تستخدم المشغّلات التي لا وصول لها إلى الإنترنت ملف ترخيص بدل رمز.
أخطاء شائعة
- “No .sysml or .kerml files found” (لم يُعثر على ملفات .sysml أو .kerml): المسار خاطئ، أو الملفات في مجلد يبدأ اسمه بنقطة.
- أسماء غير محلولة في ملف واحد فقط: يعلن الملف أسماء يستخدمها ملف آخر، وذلك الملف الآخر فيه خطأ صياغة. أصلح خطأ الصياغة أولًا؛ ويذكر التقرير الملفات التي استُبعدت.
- تفشل المهمة برمز الخروج 3: الرمز مفقود أو خاطئ أو يتبع حسابًا على خطة Free. وتذكر الرسالة أيها.
كيف يرتبط بالميزات الأخرى
- الفحوص هي فحوص نص SysML v2 في محرر Holarch وفحوص فحوص النموذج لمشاريع SysML v2، بالرسائل نفسها (محرر نص SysML v2).
- تجتاز الملفات المصدّرة من مشروع (الاستيراد والتصدير) الفحص دون مشكلات؛ ويُستورد JSON الذي تصدّره الأداة إلى مشروع.
- للتغييرات التي يجب أن تمر بالمراجعة في Holarch بدل الملفات، استخدم واجهة API أو عميل Python، اللذين تصل تغييراتهما كمقترحات.
الأوامر
| الأمر | ما الذي يفعله |
|---|---|
holarch check [paths] | يفحص النموذج؛ ويبلغ عن المشكلات؛ ويخرج بـ 1 عند الأخطاء |
holarch format [paths] | يعيد كتابة الملفات بالتخطيط القياسي |
holarch export [paths] | يكتب النموذج بصيغة SysML v2 JSON |
holarch whoami | يُظهر ما يسمح به الرمز أو ملف الترخيص |
holarch version | يطبع إصدارات الأداة والمحرك والمكتبة وإشعار حقوق النشر للمحرك (لا حاجة إلى تسجيل الدخول) |
المسارات ملفات أو مجلدات؛ والافتراضي المجلد الحالي. ويُبحث في المجلدات مع مجلداتها الفرعية.
خيارات check
| الخيار | المعنى |
|---|---|
--format human|json|sarif|github | التقرير على المخرج القياسي (الافتراضي human) |
--output FILE | كتابة ذلك التقرير إلى ملف بدلًا من ذلك |
--sarif FILE | كتابة تقرير SARIF 2.1.0 أيضًا |
--json FILE | كتابة تقرير JSON أيضًا |
--warnings-as-errors | الخروج بـ 1 عند التحذيرات أيضًا |
خيارات format
| الخيار | المعنى |
|---|---|
--check | عدم تغيير أي شيء؛ والخروج بـ 1 حين سيتغير ملف |
--diff | عدم تغيير أي شيء؛ وطباعة التغييرات كفرق موحَّد |
--stdout | طباعة النص المنسَّق لملف واحد بدل كتابته |
خيارات export
| الخيار | المعنى |
|---|---|
-o FILE, --output FILE | الكتابة إلى ملف (الافتراضي: المخرج القياسي) |
--holarch-fields | إضافة الحقول التي لا يقرؤها إلا Holarch، لرحلة ذهاب وإياب مطابقة |
--force | تصدير نموذج فيه أخطاء (لا يكون أبدًا نموذجًا فيه أخطاء صياغة) |
خيارات كل أمر يسجّل الدخول
| الخيار | متغير البيئة | المعنى |
|---|---|---|
--api-key KEY | HOLARCH_API_KEY | رمز API (hol_…)؛ فضّل المتغير، ليبقى الرمز خارج السجلات |
--license FILE | HOLARCH_LICENSE_FILE | ملف ترخيص للاستخدام دون اتصال |
--server URL | HOLARCH_SERVER | خادم Holarch الذي يتحقق من الرمز (عنوان https) |
--timeout SECONDS | المهلة الزمنية لكل خطوة من خطوات المحرك (الافتراضي 60) |
تسجيل الدخول للأداة
تعمل الأداة حين يوجد أحد هذين:
- رمز API لخطة Individual أو Team، بما في ذلك الفترة التجريبية لـ Individual. تسأل الأداة الخادم مرة واحدة وتحتفظ بالإجابة يومًا في ملف ذاكرة تخزين مؤقت (
~/.cache/holarch/entitlement.json؛ وينقلهHOLARCH_CACHE_DIR). وتحوي الذاكرة المؤقتة الخطة والبريد الإلكتروني للحساب، لا الرمز أبدًا. وحين يتعذر الوصول إلى الخادم، تبقى الإجابة التي لا يتجاوز عمرها 7 أيام صالحة، مع ملاحظة. - ملف ترخيص، لمرخَّصي Holarch Language Engine وعملاء الإصدار المستضاف ذاتيًا والمشغّلات التي لا وصول لها إلى الإنترنت. تتحقق الأداة من توقيع الملف بنفسها ولا تتصل بأي خادم أبدًا. وكل ترخيص صالح يشمل الأداة دون رسوم إضافية:
- ترخيص Holarch Language Engine: احفظ مفتاح الترخيص من تسليم المحرك (النص الذي يبدأ بـ
l1.) في ملف، مثلholarch-engine.key، ووجّه--licenseأوHOLARCH_LICENSE_FILEإليه. ولا تهم فواصل الأسطر التي أضافها بريد إلكتروني. وتنطبق عناوين الويب المرخَّصة للمفتاح واستخدام الخادم على المحرك في منتجك، لا على الأداة. وفي الأيام الـ 14 التالية لتاريخ انتهاء المفتاح تواصل الأداة العمل وتطبع تذكيرًا. - ترخيص الإصدار المستضاف ذاتيًا: استخدم ملف الترخيص الخاص بخادم Holarch كما هو. وفي آخر 30 يومًا منه تطبع الأداة تذكيرًا. وفي الأيام الـ 30 التالية لتاريخ الانتهاء (فترة السماح للترخيص) تواصل الأداة العمل وتطبع الأيام المتبقية؛ وبعد ذلك تتوقف حتى يُثبَّت ترخيص مجدَّد.
- ترخيص Holarch Language Engine: احفظ مفتاح الترخيص من تسليم المحرك (النص الذي يبدأ بـ
ومفتاح المحرك الذي تجاوز أيامه الـ 14 يوقف الأداة أيضًا حتى يُثبَّت مفتاح مجدَّد.
يُرفض رمز الحساب على خطة Free، حتى حين يحتفظ الحساب بواجهة API عبر عنوان بريد إلكتروني أكاديمي. وتشمل الفترة التجريبية لـ Individual الأداة.
ملفات الترخيص في CI
خزّن الترخيص كسر، لا في المستودع أبدًا. وفي CI، اكتب السر إلى ملف خارج نسخة السحب (في GitHub Actions، تحت $RUNNER_TEMP) واضبط HOLARCH_LICENSE_FILE على مساره.
التقارير
مخرجات JSON
يكتب --format json و--json FILE:
| الحقل | المعنى |
|---|---|
tool, version, engine | holarch، وإصدار الأداة، وإصدار المحرك |
files | الملفات المفحوصة، كمسارات نسبية إلى المجلد الذي شُغّلت فيه الأداة |
summary | errors, warnings, notes, files |
diagnostics | file وline وcolumn وendLine وendColumn (بدءًا من 1)، وseverity (error، warning، info)، وcode، وmessage، وargs |
skipped | الملفات غير المفحوصة، مع السبب (ملفات KerML مع محرك أقدم) |
excluded | الملفات التي فيها أخطاء صياغة، المستبعدة من الفحوص عبر الملفات |
تعدّ الأعمدة محارف Unicode (نقاط الترميز).
SARIF
يكتب --format sarif و--sarif FILE بصيغة SARIF 2.1.0 مع قاعدة لكل رمز تشخيص، والخطورة بصيغة error أو warning أو note، ومسارات نسبية إلى المجلد الذي شُغّلت فيه الأداة. شغّل الأداة في جذر المستودع ليجد فحص الشيفرة الملفات.
تعليقات GitHub التوضيحية
يطبع --format github أمر سير عمل واحدًا لكل مشكلة (::error file=…,line=…,col=…::message)، تعرضه GitHub Actions كتعليقات توضيحية، ثم سطر الملخص.
رموز الخروج
| الرمز | المعنى |
|---|---|
| 0 | لا أخطاء (format: لا شيء متبقٍ للتغيير) |
| 1 | في النموذج أخطاء؛ format --check أو --diff: سيتغير ملف، أو تعذّر تنسيق ملف؛ export: رُفض بسبب الأخطاء |
| 2 | استخدام خاطئ: خيار غير معروف، أو مسار غير موجود، أو لا ملفات نموذج |
| 3 | غير مسجّل الدخول أو غير مستحق: لا رمز ولا ملف ترخيص، أو رمز مرفوض، أو خطة Free، أو ملف ترخيص غير صالح أو متغير أو منتهٍ |
| 4 | لا يستطيع المحرك العمل، أو رفض النموذج لأنه أكبر أو أبطأ من أن يُفحص |
الرسائل
| الرسالة | المعنى |
|---|---|
| “The holarch command line tool needs a Holarch API token of an Individual or Team plan (HOLARCH_API_KEY, or --api-key) or a Holarch Language Engine license file (HOLARCH_LICENSE_FILE, or --license).” (تحتاج أداة سطر الأوامر holarch إلى رمز Holarch API لخطة Individual أو Team، أو إلى ملف ترخيص Holarch Language Engine.) | لم يُضبط رمز ولا ملف ترخيص |
| “The holarch command line tool comes with the Individual and Team plans. Choose a plan in Account Settings → Plan & Billing, or use a Holarch Language Engine license file.” (تأتي أداة سطر الأوامر holarch مع خطتي Individual وTeam. اختر خطة في إعدادات الحساب ← الخطة والفوترة، أو استخدم ملف ترخيص Holarch Language Engine.) | حساب الرمز على خطة Free |
| “The API and MCP come with the Individual and Team plans.” (تأتي واجهة API وMCP مع خطتي Individual وTeam.) | حساب الرمز على خطة Free وليس له وصول إلى واجهة API أيضًا |
| “The API token is not valid: it is wrong, revoked or expired, or its account cannot sign in.” (رمز API غير صالح: فهو خاطئ أو ملغى أو منتهي الصلاحية، أو لا يستطيع حسابه تسجيل الدخول.) | أنشئ رمزًا جديدًا |
| “The license file's signature does not verify. Use the file exactly as it was delivered.” (لا يُتحقق من توقيع ملف الترخيص. استخدم الملف تمامًا كما سُلّم.) | تغيّر ملف الترخيص أو تلف |
| “License <id> expired on <date>. Install a renewed license file.” (انتهى الترخيص <id> في <date>. ثبّت ملف ترخيص مجدَّدًا.) | انتهى ترخيص مستضاف ذاتيًا منذ أكثر من 30 يومًا، أو مفتاح ترخيص محرك منذ أكثر من 14 يومًا |
| “The engine license key's signature does not verify. Use the key exactly as it was delivered.” (لا يُتحقق من توقيع مفتاح ترخيص المحرك. استخدم المفتاح تمامًا كما سُلّم.) | تغيّر المفتاح في الملف أو هو من منتج آخر |
| “The engine license key is not complete. Copy the whole key (l1.….…) into the file.” (مفتاح ترخيص المحرك غير كامل. انسخ المفتاح كله (l1.….…) إلى الملف.) | جزء من المفتاح مفقود |
| “… cannot be reached to check the API token” (يتعذر الوصول إلى … للتحقق من رمز API) | لا اتصال ولا إجابة حديثة في الذاكرة المؤقتة؛ حاول مجددًا، أو استخدم ملف ترخيص |
| “<file>: not formatted: the file has syntax errors.” (لم يُنسَّق: في الملف أخطاء صياغة.) | شغّل holarch check لرؤيتها |
| “<file>: not formatted: a comment could not be kept in place.” (لم يُنسَّق: تعذّر إبقاء تعليق في مكانه.) | يبقى الملف دون تغيير؛ فالأداة لا تُسقط تعليقًا أبدًا |
| “The model has errors, so it was not exported.” (في النموذج أخطاء، فلم يُصدَّر.) | أصلح الأخطاء، أو أضف --force |
| “The installed engine does not carry the Holarch Language Engine copyright notice, so it is not a genuine Holarch build.” (لا يحمل المحرك المثبّت إشعار حقوق النشر لـ Holarch Language Engine، فهو ليس إصدارًا أصليًا من Holarch.) | أعد تثبيت الأداة |
الحدود
- 8 MB على الأكثر من نص SysML لكل لغة في نموذج واحد، وأسطر حتى 64 KB، كما في المحرر.
- 10,000 ملف على الأكثر في تشغيل واحد.
- تتوقف كل خطوة من خطوات المحرك بعد
--timeoutثانية (الافتراضي 60). - تُحَل الأسماء عبر ملفات اللغة نفسها: لا يرى ملف
.sysmlالأسماء المعلنة في ملف.kerml.