Holarch

SysML v2

כלי שורת הפקודה holarch

בדיקה, עיצוב וייצוא של מודלים של SysML v2 בבנייה וב-CI עם כלי שורת הפקודה holarch ו-Holarch Language Engine; GitHub Actions ומערכות CI אחרות, דוחות JSON ו-SARIF, קודי יציאה, כניסה עם אסימון API או קובץ רישיון.

אופן השימוש ←

בדף זה
  1. סקירה כללית
  2. מושגים
  3. איך להשתמש בה
    1. מתי ולמה
    2. התקנה
    3. כניסה עם אסימון API
    4. בדיקת מודל
    5. עיצוב קבצים
    6. ייצוא המודל כ-SysML v2 JSON
    7. הרצה ב-GitHub Actions
    8. הרצה במערכות CI אחרות
    9. דוגמה מעשית: הדגמת Hybrid Car
    10. עצות ושיטות עבודה טובות
    11. טעויות נפוצות
    12. כיצד זה מתחבר לתכונות אחרות
  4. פקודות
    1. אפשרויות של check
    2. אפשרויות של format
    3. אפשרויות של export
    4. אפשרויות של כל פקודה שמבצעת כניסה
  5. כניסה עבור הכלי
    1. קובצי רישיון ב-CI
  6. דוחות
    1. פלט JSON
    2. SARIF
    3. הערות GitHub (annotations)
  7. קודי יציאה
  8. הודעות
  9. מגבלות
  10. דפים קשורים

סקירה כללית

holarch הוא כלי שורת פקודה שבודק קובצי טקסט של SysML v2 עם Holarch Language Engine, אותו מנוע שבו משתמש העורך של Holarch. אפשר להריץ אותו במחשב שלך או בבנייה: הוא קורא כל קובץ .sysml בתיקייה, מדווח על בעיות עם קובץ, שורה ועמודה, ויוצא עם קוד שאינו אפס כשבמודל יש שגיאות, כך ש-pull request עם מודל שבור נכשל בבדיקות שלו.

הכלי עושה שלושה דברים:

  • בדיקה: תחביר, שמות, טיפוסים, התמחויות, ריבויים, יחידות ושאר הכללים של המנוע, על פני כל הקבצים של המודל. דוחות כטקסט, 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 בעורך שהם בוחרים, וכל שינוי נבדק לפני שהוא ממוזג. הוא עונה על השאלה "האם המודל הזה עדיין מחזיק?" בכל commit, כמו שמהדר עושה לקוד. את העורך של Holarch משמשים למידול, לדיאגרמות ולסקירות; את הכלי משמשים לשמירה על הקבצים בין עריכות. כדי להעביר מודל בין המאגר לפרויקט Holarch, יש להשתמש בייבוא וייצוא.

התקנה

  1. יש להתקין Python 3.9 ומעלה.
  2. יש להתקין את הכלי עבור המערכת שלך (Linux x86-64, Linux arm64 או macOS על Apple silicon) עם pip:
python3 -m pip install holarch-cli
  1. בדיקת ההתקנה: holarch version מדפיס את הגרסאות של הכלי, המנוע והספרייה.

כניסה עם אסימון API

  1. ב-Holarch, יש לפתוח את הגדרות החשבון → אסימוני API וליצור אסימון. גישת קריאה בלבד מספיקה.
  2. יש לשים את האסימון במשתנה הסביבה HOLARCH_API_KEY (ב-CI: סוד).
  3. יש להריץ את 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.

עיצוב קבצים

  1. יש להריץ את holarch format models/. כל קובץ שהשתנה מופיע כ-"reformatted <file>".
  2. כדי לבדוק את הפריסה ב-CI בלי לשנות קבצים, יש להריץ את holarch format --check models/. הוא מציג "would reformat <file>" ויוצא עם 1 כשקובץ היה משתנה.
  3. כדי לראות את השינויים קודם, יש להריץ את holarch format --diff models/.

קובץ עם שגיאות תחביר אינו מעוצב ("not formatted: the file has syntax errors."). הערות נשארות במקומן: הערות לפני אלמנט נשארות מעליו, הערה בסוף שורה נשארת בסוף אותה שורה.

ייצוא המודל כ-SysML v2 JSON

holarch export models/ -o model.json

הקובץ מכיל את מערך האלמנטים הסטנדרטי של Systems Modeling API. אותם קבצים נותנים תמיד את אותו JSON, כך שאפשר לבצע commit לייצוא ולהשוות אותו. מודל עם שגיאות אינו מיוצא ("The model has errors, so it was not exported."); כדי לייצא אותו בכל זאת, יש להוסיף --force. כדי לשמור את מה שרק Holarch קורא (סדר אלמנטים, כתיב), לייבוא מדויק לפרויקט Holarch, יש להוסיף --holarch-fields.

הרצה ב-GitHub Actions

  1. יש להוסיף את אסימון ה-API כסוד של המאגר בשם HOLARCH_API_KEY (Settings → Secrets and variables → Actions).
  2. יש להוסיף קובץ workflow, למשל .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
  1. יש לבצע push. בעיות מופיעות כהערות על השורות שהשתנו ב-pull request, וה-job נכשל כשבמודל יש שגיאות או כשקובץ אינו בפריסה הקנונית. כדי לבדוק רק את המודל, יש להשמיט את השלב 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

  1. יצירת ההדגמה: בניהול פרויקטים, יש ללחוץ על קובצי פרויקט ▾ → פרויקט הדגמה חדש → Hybrid Car (SysML v2).
  2. יש לפתוח את מודל → ייבוא וייצוא. תחת ייצוא, יש לבחור כל המודל ו-טקסט SysML v2, ללחוץ על ייצוא, ולחלץ את ההורדה לתיקייה models במאגר שלך.
  3. יש להריץ את holarch check models. התוצאה היא "6 files checked: 0 errors, 0 warnings."
  4. ב-requirements.sysml, יש לשנות את attribute maxCurbMass : MassValue ל-MassValu ולהריץ שוב את הבדיקה. היא מדווחת requirements.sysml:14:27: error name.unresolved: “MassValu” is not defined here. ויוצאת עם 1.
  5. יש לבטל את השינוי. יש להריץ את holarch format models פעם אחת ולבצע commit לקבצים, כך שהרצות format --check מאוחרות יותר יעברו.
  6. יש להוסיף את ה-workflow של GitHub שלמעלה. כל pull request מאוחר יותר ששובר את המודל נכשל בבדיקה שלו.

עצות ושיטות עבודה טובות

  • כדאי לשמור את התוכן של כל קובץ בחבילה. אלמנטים מחוץ לכל חבילה עובדים, אבל חבילה לכל קובץ שומרת על ייחודיות השמות בין הקבצים.
  • כדאי להשתמש ב-CI באסימון לקריאה בלבד, שמוגבל לאף פרויקט: הכלי אינו זקוק לגישה לפרויקטים.
  • כדאי לעצב פעם אחת ולבצע commit לתוצאה לפני הפעלת format-check, אחרת ההרצה הראשונה נכשלת על כל קובץ.
  • כדאי לקבע את גרסת הכלי ב-CI (holarch-cli==<version>) כך שגרסת מנוע חדשה לא תשנה תוצאות באמצע סקירה.
  • מריצים (runners) ללא גישה לאינטרנט משתמשים בקובץ רישיון במקום באסימון.

טעויות נפוצות

  • "No .sysml or .kerml files found": הנתיב שגוי, או שהקבצים נמצאים בתיקייה ששמה מתחיל בנקודה.
  • שמות שאינם נפתרים בקובץ אחד בלבד: הקובץ מצהיר על שמות שקובץ אחר משתמש בהם, ובקובץ האחר יש שגיאת תחביר. יש לתקן קודם את שגיאת התחביר; הדוח מציין אילו קבצים הושמטו.
  • ה-job נכשל עם קוד יציאה 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ללא שינוי; הדפסת השינויים כ-diff מאוחד
--stdoutהדפסת הטקסט המעוצב של קובץ אחד במקום לכתוב אותו

אפשרויות של export

אפשרותמשמעות
-o FILE, --output FILEכתיבה לקובץ (ברירת מחדל: פלט סטנדרטי)
--holarch-fieldsהוספת השדות שרק Holarch קורא, להלוך ושוב מדויק
--forceייצוא מודל עם שגיאות (לעולם לא מודל עם שגיאות תחביר)

אפשרויות של כל פקודה שמבצעת כניסה

אפשרותמשתנה סביבהמשמעות
--api-key KEYHOLARCH_API_KEYאסימון API (hol_…); עדיף להשתמש במשתנה, כך שהאסימון לא יופיע ביומנים
--license FILEHOLARCH_LICENSE_FILEקובץ רישיון לשימוש לא מקוון
--server URLHOLARCH_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 הימים שאחרי תאריך הסיום (תקופת החסד של הרישיון) הכלי ממשיך לפעול ומדפיס את הימים שנותרו; אחר כך הוא נעצר עד שמותקן רישיון מחודש.

גם מפתח מנוע שעברו 14 הימים שלו עוצר את הכלי עד שמותקן מפתח מחודש.

אסימון של חשבון בתוכנית Free נדחה, גם כשהחשבון שומר על ה-API דרך כתובת דוא״ל אקדמית. תקופת הניסיון של Individual כוללת את הכלי.

קובצי רישיון ב-CI

יש לשמור את הרישיון כסוד, לעולם לא במאגר. ב-CI, יש לכתוב את הסוד לקובץ מחוץ לעותק המאגר (ב-GitHub Actions, תחת $RUNNER_TEMP) ולהגדיר את HOLARCH_LICENSE_FILE לנתיב שלו.

דוחות

פלט JSON

--format json ו---json FILE כותבים:

שדהמשמעות
tool, version, engineholarch, גרסת הכלי, גרסת המנוע
filesהקבצים שנבדקו, כנתיבים יחסיים לתיקייה שבה הכלי רץ
summaryerrors, warnings, notes, files
diagnosticsfile, 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 (annotations)

--format github מדפיס פקודת workflow אחת לכל בעיה (::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 דורש אסימון API של Holarch בתוכנית 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." (הכלי מגיע עם תוכניות Individual ו-Team; יש לבחור תוכנית או להשתמש בקובץ רישיון.)החשבון של האסימון בתוכנית 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." (תוקף הרישיון פג; יש להתקין קובץ רישיון מחודש.)רישיון לאירוח עצמי הסתיים לפני יותר מ-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." (מפתח רישיון המנוע אינו שלם.)חלק מהמפתח חסר
"… 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.