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.
Na tej stronie
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
.sysmlw 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
.kermlsą 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 versionwypisuje 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
- Zainstaluj Pythona 3.9 lub nowszego.
- 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
- Sprawdź instalację:
holarch versionwypisuje wersje narzędzia, silnika i biblioteki.
Logowanie tokenem API
- W Holarch otwórz Ustawienia konta → Tokeny API i utwórz token. Wystarczy dostęp Tylko do odczytu.
- Umieść token w zmiennej środowiskowej
HOLARCH_API_KEY(w CI: jako sekret). - 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
- Uruchom
holarch format models/. Każdy zmieniony plik jest wymieniany jako “reformatted <file>”. - 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ł. - 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
- Dodaj token API jako sekret repozytorium o nazwie
HOLARCH_API_KEY(Settings → Secrets and variables → Actions). - 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
- 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
- Utwórz demo: na stronie Zarządzaj projektami kliknij Pliki projektów ▾ → Nowy projekt demonstracyjny → Hybrid Car (SysML v2).
- 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
modelsw repozytorium. - Uruchom
holarch check models. Wynik to “6 files checked: 0 errors, 0 warnings.” - W
requirements.sysmlzmieńattribute maxCurbMass : MassValuenaMassValui uruchom sprawdzenie ponownie. Zgłasza onorequirements.sysml:14:27: error name.unresolved: “MassValu” is not defined here.i kończy działanie z kodem 1. - Cofnij zmianę. Uruchom raz
holarch format modelsi zatwierdź pliki, aby późniejsze uruchomieniaformat --checkprzechodziły. - 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
| Polecenie | Co 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 whoami | Pokazuje, na co pozwala token lub plik licencji |
holarch version | Wypisuje 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
| Opcja | Znaczenie |
|---|---|
--format human|json|sarif|github | Raport na standardowym wyjściu (domyślnie human) |
--output FILE | Zapisuje ten raport do pliku zamiast tego |
--sarif FILE | Dodatkowo zapisuje raport SARIF 2.1.0 |
--json FILE | Dodatkowo zapisuje raport JSON |
--warnings-as-errors | Kod wyjścia 1 także przy ostrzeżeniach |
Opcje polecenia format
| Opcja | Znaczenie |
|---|---|
--check | Niczego nie zmienia; kod wyjścia 1, gdy plik by się zmienił |
--diff | Niczego nie zmienia; wypisuje zmiany jako ujednolicony diff |
--stdout | Wypisuje sformatowany tekst jednego pliku zamiast go zapisywać |
Opcje polecenia export
| Opcja | Znaczenie |
|---|---|
-o FILE, --output FILE | Zapisuje do pliku (domyślnie: standardowe wyjście) |
--holarch-fields | Dodaje pola odczytywane tylko przez Holarch, na potrzeby dokładnej wymiany w obie strony |
--force | Eksportuje model z błędami (nigdy z błędami składni) |
Opcje każdego polecenia, które się loguje
| Opcja | Zmienna środowiskowa | Znaczenie |
|---|---|---|
--api-key KEY | HOLARCH_API_KEY | Token API (hol_…); preferuj zmienną, aby token nie trafiał do logów |
--license FILE | HOLARCH_LICENSE_FILE | Plik licencji do użytku offline |
--server URL | HOLARCH_SERVER | Serwer Holarch, który sprawdza token (adres https) |
--timeout SECONDS | Limit 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_DIRzmienia 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--licenselubHOLARCH_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.
- Licencja Holarch Language Engine: zapisz klucz licencyjny z dostawy silnika (tekst zaczynający się od
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ą:
| Pole | Znaczenie |
|---|---|
tool, version, engine | holarch, wersja narzędzia, wersja silnika |
files | Sprawdzone pliki jako ścieżki względem folderu, w którym uruchomiono narzędzie |
summary | errors, warnings, notes, files |
diagnostics | file, line, column, endLine, endColumn (liczone od 1), severity (error, warning, info), code, message, args |
skipped | Niesprawdzone pliki z przyczyną (pliki KerML przy starszym silniku) |
excluded | Pliki 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
| Kod | Znaczenie |
|---|---|
| 0 | Brak błędów (format: nic do zmiany) |
| 1 | Model 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 |
| 2 | Nieprawidłowe użycie: nieznana opcja, nieistniejąca ścieżka, brak plików modelu |
| 3 | Brak logowania lub uprawnień: brak tokenu lub pliku licencji, odrzucony token, plan Free, plik licencji nieprawidłowy, zmieniony lub wygasły |
| 4 | Silnik 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
--timeoutsekundach (domyślnie 60). - Nazwy są rozwiązywane między plikami tego samego języka: plik
.sysmlnie widzi nazw zadeklarowanych w pliku.kerml.