Holarch

SysML v2

Narzędzie wiersza poleceń holarch

Sprawdzaj, formatuj i eksportuj modele SysML v2 w kompilacjach i CI za pomocą narzędzia wiersza poleceń holarch i Holarch Language Engine; GitHub Actions i inne systemy CI, raporty JSON i SARIF, kody wyjścia, logowanie tokenem API lub plikiem licencji.

Jak z niego korzystać →

Na tej stronie
  1. Przegląd
  2. Pojęcia
  3. Jak z niego korzystać
    1. Kiedy i dlaczego
    2. Instalacja
    3. Logowanie tokenem API
    4. Sprawdzanie modelu
    5. Formatowanie plików
    6. Eksport modelu jako SysML v2 JSON
    7. Uruchamianie w GitHub Actions
    8. Uruchamianie w innych systemach CI
    9. Przykład: projekt demonstracyjny Hybrid Car
    10. Wskazówki i dobre praktyki
    11. Typowe błędy
    12. Powiązania z innymi funkcjami
  4. Polecenia
    1. Opcje polecenia check
    2. Opcje polecenia format
    3. Opcje polecenia export
    4. Opcje każdego polecenia, które się loguje
  5. Logowanie narzędzia
    1. Pliki licencji w CI
  6. Raporty
    1. Wyjście JSON
    2. SARIF
    3. Adnotacje GitHub
  7. Kody wyjścia
  8. Komunikaty
  9. Limity
  10. Powiązane strony

Przegląd

holarch to narzędzie wiersza poleceń, które sprawdza pliki tekstowe SysML v2 za pomocą Holarch Language Engine, tego samego silnika, którego używa edytor Holarch. Uruchom je na własnym komputerze lub w kompilacji: odczytuje każdy plik .sysml w folderze, zgłasza problemy z plikiem, wierszem i kolumną i kończy działanie z niezerowym kodem, gdy model ma błędy, więc pull request z uszkodzonym modelem nie przechodzi kontroli.

Narzędzie robi trzy rzeczy:

  • Sprawdzanie: składnia, nazwy, typy, specjalizacje, liczności, jednostki i pozostałe reguły silnika we wszystkich plikach modelu. Raporty jako tekst, JSON, SARIF (do skanowania kodu) lub adnotacje GitHub.
  • Formatowanie: przepisuje pliki w jednym kanonicznym układzie (wcięcie czterema spacjami, jeden element na wiersz, kanoniczne odstępy), zachowując każdy komentarz.
  • Eksport: zapisuje model jako SysML v2 JSON, format wymiany Systems Modeling API.

Narzędzie jest dostępne w planach Individual i Team (łącznie z wersją próbną), z licencją Holarch Language Engine oraz z licencją edycji samodzielnie hostowanej. Nie wymaga projektu Holarch: działa na plikach w Twoim repozytorium.

Pojęcia

  • Model: wszystkie pliki .sysml w podanych folderach (domyślnie: bieżący folder), odczytywane jako jeden model. Nazwa zadeklarowana w jednym pliku jest rozwiązywana w pozostałych, tak jak pakiety w projekcie Holarch. Foldery, których nazwy zaczynają się od kropki (np. .git), są pomijane.
  • Pliki KerML: pliki .kerml są sprawdzane jako KerML przez wersje silnika, które odczytują KerML. Starsze wersje silnika wymieniają je jako pominięte, co nie jest błędem.
  • Diagnostyki: każdy problem ma kod (np. name.unresolved), ważność (error, warning lub note), położenie i komunikat w tym samym brzmieniu co w edytorze Holarch. Kontrola kończy się niepowodzeniem tylko przy błędach, chyba że dodasz --warnings-as-errors.
  • Logowanie: narzędzie raz dziennie sprawdza, czy Twój token API należy do planu Individual lub Team, albo odczytuje plik licencji bez dostępu do sieci. Zobacz Logowanie narzędzia.
  • Silnik: narzędzie zawiera skompilowany Holarch Language Engine i bibliotekę standardową SysML v2. holarch version wypisuje ich wersje i informację o prawach autorskich silnika.

Jak z niego korzystać

Kiedy i dlaczego

Używaj narzędzia tam, gdzie tekst SysML v2 znajduje się w repozytorium kodu źródłowego: projektanci edytują pliki .sysml w wybranym edytorze, a każda zmiana jest sprawdzana przed scaleniem. Narzędzie odpowiada na pytanie “czy ten model nadal jest spójny?” przy każdym commicie, tak jak kompilator w przypadku kodu. Edytora Holarch używaj do modelowania, diagramów i przeglądów; narzędzia używaj do pilnowania plików między edycjami. Aby przenieść model między repozytorium a projektem Holarch, użyj Importu i eksportu.

Instalacja

  1. Zainstaluj Pythona 3.9 lub nowszego.
  2. Zainstaluj narzędzie dla swojego systemu (Linux x86-64, Linux arm64 lub macOS na Apple silicon) za pomocą pip:
python3 -m pip install holarch-cli
  1. Sprawdź instalację: holarch version wypisuje wersje narzędzia, silnika i biblioteki.

Logowanie tokenem API

  1. W Holarch otwórz Ustawienia konta → Tokeny API i utwórz token. Wystarczy dostęp Tylko do odczytu.
  2. Umieść token w zmiennej środowiskowej HOLARCH_API_KEY (w CI: jako sekret).
  3. Uruchom holarch whoami. Polecenie wypisuje Twój plan i konto, na przykład "plan": "team".

Sprawdzanie modelu

holarch check models/

Każdy problem to jeden wiersz, a na końcu podsumowanie:

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.

Kod wyjścia to 1, gdy model ma błędy, a w przeciwnym razie 0. Dodaj --warnings-as-errors, aby kończyć niepowodzeniem także przy ostrzeżeniach.

Formatowanie plików

  1. Uruchom holarch format models/. Każdy zmieniony plik jest wymieniany jako “reformatted <file>”.
  2. Aby sprawdzić układ w CI bez zmieniania plików, uruchom holarch format --check models/. Polecenie wymienia “would reformat <file>” i kończy działanie z kodem 1, gdy plik by się zmienił.
  3. Aby najpierw zobaczyć zmiany, uruchom holarch format --diff models/.

Plik z błędami składni nie jest formatowany (“not formatted: the file has syntax errors.”). Komentarze pozostają na swoich miejscach: uwagi przed elementem pozostają nad nim, a uwaga na końcu wiersza pozostaje na końcu tego wiersza.

Eksport modelu jako SysML v2 JSON

holarch export models/ -o model.json

Plik zawiera standardową tablicę elementów Systems Modeling API. Te same pliki zawsze dają ten sam JSON, więc eksport można zatwierdzić w repozytorium i porównywać. Model z błędami nie jest eksportowany (“The model has errors, so it was not exported.”); dodaj --force, aby mimo to go wyeksportować. Dodaj --holarch-fields, aby zachować to, co odczytuje tylko Holarch (kolejność elementów, pisownię), na potrzeby dokładnego importu do projektu Holarch.

Uruchamianie w GitHub Actions

  1. Dodaj token API jako sekret repozytorium o nazwie HOLARCH_API_KEY (Settings → Secrets and variables → Actions).
  2. Dodaj plik przepływu pracy, na przykład .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. Wypchnij zmiany. Problemy pojawiają się jako adnotacje przy zmienionych wierszach pull requestu, a zadanie kończy się niepowodzeniem, gdy model ma błędy lub plik nie ma kanonicznego układu. Pomiń krok holarch format --check, aby sprawdzać tylko model.

Ostatni krok przesyła raport SARIF do skanowania kodu, gdzie problemy są wymienione w Security → Code scanning. Pomiń go, jeśli repozytorium nie używa skanowania kodu: adnotacje działają bez niego.

Uruchamianie w innych systemach CI

Każdy system CI z Pythonem 3.9 lub nowszym uruchamia te same polecenia. Zainstaluj narzędzie, ustaw token z sekretu, sprawdź:

python3 -m pip install holarch-cli
holarch check models/ --sarif holarch.sarif --json holarch.json

Na przykład GitLab CI (.gitlab-ci.yml, z HOLARCH_API_KEY jako zamaskowaną zmienną 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 i inne działają tak samo: jeden krok instaluje narzędzie, następny uruchamia holarch check; niezerowy kod wyjścia powoduje niepowodzenie kompilacji. Zachowaj raport JSON (--json) jako artefakt kompilacji, jeśli chcesz mieć liczby na pulpicie.

Przykład: projekt demonstracyjny Hybrid Car

  1. Utwórz demo: na stronie Zarządzaj projektami kliknij Pliki projektów ▾ → Nowy projekt demonstracyjny → Hybrid Car (SysML v2).
  2. Otwórz Model → Import i eksport. W sekcji Eksportuj wybierz Cały model i Tekst SysML v2, kliknij Eksportuj i rozpakuj pobrany plik do folderu models w repozytorium.
  3. Uruchom holarch check models. Wynik to “6 files checked: 0 errors, 0 warnings.”
  4. W requirements.sysml zmień attribute maxCurbMass : MassValue na MassValu i uruchom sprawdzenie ponownie. Zgłasza ono requirements.sysml:14:27: error name.unresolved: “MassValu” is not defined here. i kończy działanie z kodem 1.
  5. Cofnij zmianę. Uruchom raz holarch format models i zatwierdź pliki, aby późniejsze uruchomienia format --check przechodziły.
  6. Dodaj powyższy przepływ pracy GitHub. Każdy późniejszy pull request, który psuje model, nie przejdzie kontroli.

Wskazówki i dobre praktyki

  • Zawartość każdego pliku umieszczaj w pakiecie. Elementy spoza pakietów działają, ale pakiet na plik zapewnia unikatowość nazw między plikami.
  • Do CI używaj tokenu tylko do odczytu, bez dostępu do żadnych projektów: narzędzie nie potrzebuje dostępu do projektów.
  • Sformatuj pliki raz i zatwierdź wynik, zanim włączysz format-check, w przeciwnym razie pierwsze uruchomienie zakończy się niepowodzeniem dla każdego pliku.
  • Przypnij wersję narzędzia w CI (holarch-cli==<version>), aby nowe wydanie silnika nie zmieniło wyników w trakcie przeglądu.
  • Maszyny wykonawcze bez dostępu do internetu używają pliku licencji zamiast tokenu.

Typowe błędy

  • “No .sysml or .kerml files found”: ścieżka jest błędna lub pliki znajdują się w folderze, którego nazwa zaczyna się od kropki.
  • Nazwy nierozwiązane tylko w jednym pliku: plik deklaruje nazwy, których używa inny plik, a ten inny plik ma błąd składni. Najpierw popraw błąd składni; raport podaje, które pliki zostały pominięte.
  • Zadanie kończy się kodem wyjścia 3: brakuje tokenu, jest błędny lub należy do konta w planie Free. Komunikat podaje, który przypadek zachodzi.

Powiązania z innymi funkcjami

  • Kontrole są takie same jak w tekście SysML v2 edytora Holarch i w Kontrole modelu dla projektów SysML v2, z tymi samymi komunikatami (Edytor tekstu SysML v2).
  • Pliki wyeksportowane z projektu (Import i eksport) przechodzą sprawdzenie bez problemów; JSON wyeksportowany przez narzędzie importuje się do projektu.
  • Dla zmian, które powinny przechodzić przegląd w Holarch, a nie przez pliki, użyj API lub klienta Python, których zmiany docierają jako propozycje.

Polecenia

PolecenieCo robi
holarch check [paths]Sprawdza model; zgłasza problemy; kod wyjścia 1 przy błędach
holarch format [paths]Przepisuje pliki w kanonicznym układzie
holarch export [paths]Zapisuje model jako SysML v2 JSON
holarch whoamiPokazuje, na co pozwala token lub plik licencji
holarch versionWypisuje wersje narzędzia, silnika i biblioteki oraz informację o prawach autorskich silnika (bez logowania)

Ścieżki to pliki lub foldery; domyślnie bieżący folder. Foldery są przeszukiwane wraz z podfolderami.

Opcje polecenia check

OpcjaZnaczenie
--format human|json|sarif|githubRaport na standardowym wyjściu (domyślnie human)
--output FILEZapisuje ten raport do pliku zamiast tego
--sarif FILEDodatkowo zapisuje raport SARIF 2.1.0
--json FILEDodatkowo zapisuje raport JSON
--warnings-as-errorsKod wyjścia 1 także przy ostrzeżeniach

Opcje polecenia format

OpcjaZnaczenie
--checkNiczego nie zmienia; kod wyjścia 1, gdy plik by się zmienił
--diffNiczego nie zmienia; wypisuje zmiany jako ujednolicony diff
--stdoutWypisuje sformatowany tekst jednego pliku zamiast go zapisywać

Opcje polecenia export

OpcjaZnaczenie
-o FILE, --output FILEZapisuje do pliku (domyślnie: standardowe wyjście)
--holarch-fieldsDodaje pola odczytywane tylko przez Holarch, na potrzeby dokładnej wymiany w obie strony
--forceEksportuje model z błędami (nigdy z błędami składni)

Opcje każdego polecenia, które się loguje

OpcjaZmienna środowiskowaZnaczenie
--api-key KEYHOLARCH_API_KEYToken API (hol_…); preferuj zmienną, aby token nie trafiał do logów
--license FILEHOLARCH_LICENSE_FILEPlik licencji do użytku offline
--server URLHOLARCH_SERVERSerwer Holarch, który sprawdza token (adres https)
--timeout SECONDSLimit czasu każdego kroku silnika (domyślnie 60)

Logowanie narzędzia

Narzędzie działa, gdy dostępne jest jedno z poniższych:

  • Token API planu Individual lub Team, w tym wersji próbnej Individual. Narzędzie pyta serwer raz i przechowuje odpowiedź przez dobę w pliku pamięci podręcznej (~/.cache/holarch/entitlement.json; HOLARCH_CACHE_DIR zmienia jego położenie). Pamięć podręczna zawiera plan i adres e-mail konta, nigdy token. Gdy serwer jest nieosiągalny, nadal liczy się odpowiedź sprzed najwyżej 7 dni, z uwagą.
  • Plik licencji dla licencjobiorców Holarch Language Engine, klientów edycji samodzielnie hostowanej i maszyn wykonawczych bez dostępu do internetu. Narzędzie samo sprawdza podpis pliku i nigdy nie łączy się z serwerem. Każda ważna licencja obejmuje narzędzie bez dodatkowych opłat:
    • Licencja Holarch Language Engine: zapisz klucz licencyjny z dostawy silnika (tekst zaczynający się od l1.) w pliku, np. holarch-engine.key, i wskaż go w --license lub HOLARCH_LICENSE_FILE. Podziały wierszy dodane przez pocztę e-mail nie mają znaczenia. Licencjonowane adresy internetowe klucza i użycie na serwerze dotyczą silnika w Twoim produkcie, a nie narzędzia. Przez 14 dni po dacie końcowej klucza narzędzie nadal działa i wyświetla przypomnienie.
    • Licencja edycji samodzielnie hostowanej: użyj pliku licencji swojego serwera Holarch bez zmian. W ostatnich 30 dniach narzędzie wyświetla przypomnienie. Przez 30 dni po dacie końcowej (okres karencji licencji) narzędzie nadal działa i wyświetla liczbę pozostałych dni; potem przestaje działać do czasu zainstalowania odnowionej licencji.

Klucz silnika po upływie 14 dni również zatrzymuje narzędzie do czasu zainstalowania odnowionego klucza.

Token konta w planie Free jest odrzucany, także wtedy, gdy konto zachowuje dostęp do API dzięki akademickiemu adresowi e-mail. Wersja próbna Individual obejmuje narzędzie.

Pliki licencji w CI

Przechowuj licencję jako sekret, nigdy w repozytorium. W CI zapisz sekret do pliku poza katalogiem roboczym (w GitHub Actions w $RUNNER_TEMP) i ustaw HOLARCH_LICENSE_FILE na jego ścieżkę.

Raporty

Wyjście JSON

--format json i --json FILE zapisują:

PoleZnaczenie
tool, version, engineholarch, wersja narzędzia, wersja silnika
filesSprawdzone pliki jako ścieżki względem folderu, w którym uruchomiono narzędzie
summaryerrors, warnings, notes, files
diagnosticsfile, line, column, endLine, endColumn (liczone od 1), severity (error, warning, info), code, message, args
skippedNiesprawdzone pliki z przyczyną (pliki KerML przy starszym silniku)
excludedPliki z błędami składni, pominięte w kontrolach obejmujących wiele plików

Kolumny liczą znaki Unicode (punkty kodowe).

SARIF

--format sarif i --sarif FILE zapisują SARIF 2.1.0 z jedną regułą na kod diagnostyki, ważnością jako error, warning lub note i ścieżkami względem folderu, w którym uruchomiono narzędzie. Uruchamiaj narzędzie w katalogu głównym repozytorium, aby skanowanie kodu znalazło pliki.

Adnotacje GitHub

--format github wypisuje jedno polecenie przepływu pracy na problem (::error file=…,line=…,col=…::message), które GitHub Actions pokazuje jako adnotacje, a następnie wiersz podsumowania.

Kody wyjścia

KodZnaczenie
0Brak błędów (format: nic do zmiany)
1Model ma błędy; format --check lub --diff: plik by się zmienił lub nie dało się go sformatować; export: odmowa z powodu błędów
2Nieprawidłowe użycie: nieznana opcja, nieistniejąca ścieżka, brak plików modelu
3Brak logowania lub uprawnień: brak tokenu lub pliku licencji, odrzucony token, plan Free, plik licencji nieprawidłowy, zmieniony lub wygasły
4Silnik nie może się uruchomić lub odrzucił model jako zbyt duży lub zbyt wolny do sprawdzenia

Komunikaty

WiadomośćZnaczenie
“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).” (Narzędzie wymaga tokenu API planu Individual lub Team albo pliku licencji Holarch Language Engine.)Nie ustawiono ani tokenu, ani pliku licencji
“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.” (Narzędzie jest dostępne w planach Individual i Team; wybierz plan w Ustawienia konta → Plan i rozliczenia lub użyj pliku licencji.)Konto tokenu jest w planie Free
“The API and MCP come with the Individual and Team plans.” (API i MCP są dostępne w planach Individual i Team.)Konto tokenu jest w planie Free i nie ma też dostępu do API
“The API token is not valid: it is wrong, revoked or expired, or its account cannot sign in.” (Token API jest nieprawidłowy, odwołany lub wygasły albo jego konto nie może się zalogować.)Utwórz nowy token
“The license file's signature does not verify. Use the file exactly as it was delivered.” (Podpis pliku licencji nie przechodzi weryfikacji; użyj pliku dokładnie w dostarczonej postaci.)Plik licencji został zmieniony lub uszkodzony
“License <id> expired on <date>. Install a renewed license file.” (Licencja wygasła; zainstaluj odnowiony plik licencji.)Licencja edycji samodzielnie hostowanej wygasła ponad 30 dni temu lub klucz licencyjny silnika ponad 14 dni temu
“The engine license key's signature does not verify. Use the key exactly as it was delivered.” (Podpis klucza licencyjnego silnika nie przechodzi weryfikacji; użyj klucza dokładnie w dostarczonej postaci.)Klucz w pliku został zmieniony lub pochodzi z innego produktu
“The engine license key is not complete. Copy the whole key (l1.….…) into the file.” (Klucz licencyjny silnika jest niekompletny; skopiuj do pliku cały klucz.)Brakuje części klucza
“… cannot be reached to check the API token” (serwer jest nieosiągalny, więc nie można sprawdzić tokenu API)Brak połączenia i brak niedawnej odpowiedzi w pamięci podręcznej; spróbuj ponownie lub użyj pliku licencji
“<file>: not formatted: the file has syntax errors.” (plik nie został sformatowany, bo ma błędy składni)Uruchom holarch check, aby je zobaczyć
“<file>: not formatted: a comment could not be kept in place.” (plik nie został sformatowany, bo nie dało się zachować komentarza na miejscu)Plik pozostaje bez zmian; narzędzie nigdy nie usuwa komentarzy
“The model has errors, so it was not exported.” (Model ma błędy, więc nie został wyeksportowany.)Popraw błędy lub dodaj --force
“The installed engine does not carry the Holarch Language Engine copyright notice, so it is not a genuine Holarch build.” (Zainstalowany silnik nie zawiera informacji o prawach autorskich Holarch Language Engine, więc nie jest oryginalną kompilacją Holarch.)Zainstaluj narzędzie ponownie

Limity

  • Najwyżej 8 MB tekstu SysML na język w jednym modelu i wiersze do 64 KB, tak jak w edytorze.
  • Najwyżej 10 000 plików w jednym uruchomieniu.
  • Każdy krok silnika zatrzymuje się po --timeout sekundach (domyślnie 60).
  • Nazwy są rozwiązywane między plikami tego samego języka: plik .sysml nie widzi nazw zadeklarowanych w pliku .kerml.