Holarch

SysML v2

Lo strumento a riga di comando holarch

Controllare, formattare ed esportare modelli SysML v2 in build e CI con lo strumento a riga di comando holarch e l'Holarch Language Engine; GitHub Actions e altri sistemi di CI, report JSON e SARIF, codici di uscita, accesso con un token API o un file di licenza.

Come usarlo →

In questa pagina
  1. Panoramica
  2. Concetti
  3. Come usarlo
    1. Quando e perché
    2. Installazione
    3. Accedere con un token API
    4. Controllare un modello
    5. Formattare i file
    6. Esportare il modello come SysML v2 JSON
    7. Eseguirlo in GitHub Actions
    8. Eseguirlo in altri sistemi CI
    9. Esempio guidato: la demo Hybrid Car
    10. Suggerimenti e buone pratiche
    11. Errori comuni
    12. Come si collega alle altre funzionalità
  4. Comandi
    1. Opzioni di check
    2. Opzioni di format
    3. Opzioni di export
    4. Opzioni di ogni comando che esegue l'accesso
  5. Accesso per lo strumento
    1. File di licenza in CI
  6. Report
    1. Output JSON
    2. SARIF
    3. Annotazioni GitHub
  7. Codici di uscita
  8. Messaggi
  9. Limiti
  10. Pagine correlate

Panoramica

holarch è uno strumento a riga di comando che controlla i file di testo SysML v2 con l'Holarch Language Engine, lo stesso motore usato dall'editor di Holarch. Si esegue sul proprio computer o in una build: legge ogni file .sysml in una cartella, segnala i problemi con file, riga e colonna, ed esce con un codice diverso da zero quando il modello ha errori, così una pull request con un modello difettoso non supera i controlli.

Lo strumento fa tre cose:

  • Controllo: sintassi, nomi, tipi, specializzazioni, molteplicità, unità e le altre regole del motore, su tutti i file del modello. Report come testo, JSON, SARIF (per il code scanning) o annotazioni GitHub.
  • Formattazione: riscrive i file in un unico layout canonico (rientro di quattro spazi, un elemento per riga, spaziatura canonica), conservando ogni commento.
  • Esportazione: scrive il modello come SysML v2 JSON, il formato di interscambio della Systems Modeling API.

Lo strumento è incluso nei piani Individual e Team (compresa la prova), in una licenza dell'Holarch Language Engine e in una licenza dell'edizione self-hosted. Non richiede un progetto Holarch: lavora sui file del proprio repository.

Concetti

  • Modello: tutti i file .sysml sotto le cartelle indicate (predefinita: la cartella corrente), letti come un unico modello. Un nome dichiarato in un file si risolve negli altri, come i package in un progetto Holarch. Le cartelle il cui nome inizia con un punto (come .git) vengono saltate.
  • File KerML: i file .kerml vengono controllati come KerML dalle versioni del motore che leggono KerML. Le versioni precedenti del motore li elencano come saltati, il che non è un errore.
  • Diagnostica: ogni problema ha un codice (per esempio name.unresolved), una gravità (errore, avviso o nota), una posizione e un messaggio con le stesse parole dell'editor di Holarch. Solo gli errori fanno fallire un controllo, a meno di aggiungere --warnings-as-errors.
  • Accesso: lo strumento verifica una volta al giorno che il token API appartenga a un piano Individual o Team, oppure legge un file di licenza senza alcun accesso alla rete. Vedere Accesso per lo strumento.
  • Il motore: lo strumento contiene l'Holarch Language Engine compilato e la libreria standard SysML v2. holarch version ne stampa le versioni e la nota di copyright del motore.

Come usarlo

Quando e perché

Usare lo strumento dove il testo SysML v2 risiede in un repository di sorgenti: i progettisti modificano i file .sysml nel loro editor preferito e ogni modifica viene controllata prima dell'unione. Risponde a “questo modello è ancora coerente?” a ogni commit, come fa un compilatore per il codice. Usare l'editor di Holarch per la modellazione, i diagrammi e le revisioni; usare lo strumento per proteggere i file tra una modifica e l'altra. Per spostare un modello tra il repository e un progetto Holarch, usare Importazione ed esportazione.

Installazione

  1. Installare Python 3.9 o successivo.
  2. Installare lo strumento per il proprio sistema (Linux x86-64, Linux arm64 o macOS su Apple silicon) con pip:
python3 -m pip install holarch-cli
  1. Verificare l'installazione: holarch version stampa le versioni dello strumento, del motore e della libreria.

Accedere con un token API

  1. In Holarch, aprire Impostazioni account → Token API e creare un token. È sufficiente l'accesso Sola lettura.
  2. Inserire il token nella variabile d'ambiente HOLARCH_API_KEY (in CI: un secret).
  3. Eseguire holarch whoami. Stampa il proprio piano e account, per esempio "plan": "team".

Controllare un modello

holarch check models/

Ogni problema occupa una riga, seguita da un riepilogo:

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.

Il codice di uscita è 1 quando il modello ha errori e 0 altrimenti. Aggiungere --warnings-as-errors per fallire anche sugli avvisi.

Formattare i file

  1. Eseguire holarch format models/. Ogni file modificato viene elencato come “reformatted <file>”.
  2. Per controllare il layout in CI senza modificare i file, eseguire holarch format --check models/. Elenca “would reformat <file>” ed esce con 1 quando un file verrebbe modificato.
  3. Per vedere prima le modifiche, eseguire holarch format --diff models/.

Un file con errori di sintassi non viene formattato (“not formatted: the file has syntax errors.”). I commenti restano dov'erano: le note prima di un elemento restano sopra di esso, una nota a fine riga resta alla fine di quella riga.

Esportare il modello come SysML v2 JSON

holarch export models/ -o model.json

Il file contiene l'array di elementi standard della Systems Modeling API. Gli stessi file producono sempre lo stesso JSON, quindi l'esportazione si può inserire in un commit e confrontare. Un modello con errori non viene esportato (“The model has errors, so it was not exported.”); aggiungere --force per esportarlo comunque. Aggiungere --holarch-fields per conservare ciò che legge solo Holarch (ordine degli elementi, grafia), per un'importazione esatta in un progetto Holarch.

Eseguirlo in GitHub Actions

  1. Aggiungere il token API come secret del repository denominato HOLARCH_API_KEY (Settings → Secrets and variables → Actions).
  2. Aggiungere un file di workflow, per esempio .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. Eseguire il push. I problemi compaiono come annotazioni sulle righe modificate della pull request, e il job fallisce quando il modello ha errori o un file non è nel layout canonico. Omettere il passo holarch format --check per controllare solo il modello.

L'ultimo passo carica il report SARIF nel code scanning, dove i problemi sono elencati in Security → Code scanning. Ometterlo se il repository non usa il code scanning: le annotazioni funzionano anche senza.

Eseguirlo in altri sistemi CI

Qualsiasi sistema CI con Python 3.9 o successivo esegue gli stessi comandi. Installare lo strumento, impostare il token da un secret, controllare:

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

Per esempio, GitLab CI (.gitlab-ci.yml, con HOLARCH_API_KEY come variabile CI/CD mascherata):

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 e altri funzionano allo stesso modo: un passo installa lo strumento, il successivo esegue holarch check; un codice di uscita diverso da zero fa fallire la build. Conservare il report JSON (--json) come artefatto della build quando si vogliono i numeri in una dashboard.

Esempio guidato: la demo Hybrid Car

  1. Creare la demo: in Gestisci progetti, fare clic su File di progetto ▾ → Nuovo progetto demo → Hybrid Car (SysML v2).
  2. Aprire Modello → Importazione ed esportazione. In Esporta, scegliere L'intero modello e Testo SysML v2, fare clic su Esporta ed estrarre il file scaricato in una cartella models del repository.
  3. Eseguire holarch check models. Il risultato è “6 files checked: 0 errors, 0 warnings.”
  4. In requirements.sysml, cambiare attribute maxCurbMass : MassValue in MassValu ed eseguire di nuovo il controllo. Riporta requirements.sysml:14:27: error name.unresolved: “MassValu” is not defined here. ed esce con 1.
  5. Annullare la modifica. Eseguire holarch format models una volta e inserire i file in un commit, così le successive esecuzioni di format --check vanno a buon fine.
  6. Aggiungere il workflow GitHub indicato sopra. Ogni pull request successiva che rompe il modello non supera il controllo.

Suggerimenti e buone pratiche

  • Mantenere il contenuto di ogni file in un package. Gli elementi fuori da qualsiasi package funzionano, ma un package per file mantiene i nomi univoci tra i file.
  • Per la CI usare un token di sola lettura, limitato a nessun progetto: lo strumento non richiede l'accesso ai progetti.
  • Formattare una volta e inserire il risultato in un commit prima di attivare format-check, altrimenti la prima esecuzione fallisce su ogni file.
  • Fissare la versione dello strumento in CI (holarch-cli==<version>), così un nuovo rilascio del motore non cambia i risultati nel mezzo di una revisione.
  • I runner senza accesso a Internet usano un file di licenza invece di un token.

Errori comuni

  • “No .sysml or .kerml files found”: il percorso è errato, oppure i file si trovano in una cartella il cui nome inizia con un punto.
  • Nomi non risolti in un solo file: il file dichiara nomi usati da un altro file, e quell'altro file ha un errore di sintassi. Correggere prima l'errore di sintassi; il report indica quali file sono stati omessi.
  • Il job fallisce con codice di uscita 3: il token manca, è errato o appartiene a un account del piano Free. Il messaggio indica quale caso.

Come si collega alle altre funzionalità

  • I controlli sono quelli del testo SysML v2 dell'editor di Holarch e dei Controlli del modello per i progetti SysML v2, con gli stessi messaggi (L'editor di testo SysML v2).
  • I file esportati da un progetto (Importazione ed esportazione) superano i controlli senza problemi; il JSON esportato dallo strumento si importa in un progetto.
  • Per modifiche che devono passare per una revisione in Holarch anziché attraverso i file, usare l'API o il client Python, le cui modifiche arrivano come proposte.

Comandi

ComandoChe cosa fa
holarch check [paths]Controlla il modello; segnala i problemi; esce con 1 in caso di errori
holarch format [paths]Riscrive i file nel layout canonico
holarch export [paths]Scrive il modello come SysML v2 JSON
holarch whoamiMostra cosa consente il token o il file di licenza
holarch versionStampa le versioni dello strumento, del motore e della libreria e la nota di copyright del motore (non serve l'accesso)

I percorsi sono file o cartelle; il valore predefinito è la cartella corrente. Le cartelle vengono esaminate con le loro sottocartelle.

Opzioni di check

OpzioneSignificato
--format human|json|sarif|githubIl report sullo standard output (predefinito human)
--output FILEScrive invece quel report in un file
--sarif FILEScrive anche un report SARIF 2.1.0
--json FILEScrive anche un report JSON
--warnings-as-errorsEsce con 1 anche in caso di avvisi

Opzioni di format

OpzioneSignificato
--checkNon modifica nulla; esce con 1 quando un file verrebbe modificato
--diffNon modifica nulla; stampa le modifiche come diff unificato
--stdoutStampa il testo formattato di un file invece di scriverlo

Opzioni di export

OpzioneSignificato
-o FILE, --output FILEScrive in un file (predefinito: standard output)
--holarch-fieldsAggiunge i campi che legge solo Holarch, per un andata e ritorno esatto
--forceEsporta un modello con errori (mai uno con errori di sintassi)

Opzioni di ogni comando che esegue l'accesso

OpzioneVariabile d'ambienteSignificato
--api-key KEYHOLARCH_API_KEYUn token API (hol_…); preferire la variabile, così il token resta fuori dai log
--license FILEHOLARCH_LICENSE_FILEUn file di licenza per l'uso offline
--server URLHOLARCH_SERVERIl server Holarch che verifica il token (un indirizzo https)
--timeout SECONDSLimite di tempo per ogni passo del motore (predefinito 60)

Accesso per lo strumento

Lo strumento funziona quando è presente uno dei seguenti:

  • Un token API di un piano Individual o Team, compresa la prova Individual. Lo strumento interroga il server una volta e conserva la risposta per un giorno in un file di cache (~/.cache/holarch/entitlement.json; HOLARCH_CACHE_DIR lo sposta). La cache contiene il piano e l'email dell'account, mai il token. Quando il server non è raggiungibile, vale ancora una risposta vecchia fino a 7 giorni, con una nota.
  • Un file di licenza, per i licenziatari dell'Holarch Language Engine, i clienti dell'edizione self-hosted e i runner senza accesso a Internet. Lo strumento verifica da sé la firma del file e non si connette mai a un server. Ogni licenza valida include lo strumento senza costi aggiuntivi:
    • Licenza dell'Holarch Language Engine: salvare la chiave di licenza ricevuta con il motore (il testo che inizia con l1.) in un file, per esempio holarch-engine.key, e indicarlo con --license o HOLARCH_LICENSE_FILE. Le interruzioni di riga aggiunte da un'email non contano. Gli indirizzi web e l'uso su server previsti dalla licenza della chiave si applicano al motore nel proprio prodotto, non allo strumento. Nei 14 giorni successivi alla data di fine della chiave lo strumento continua a funzionare e stampa un promemoria.
    • Licenza dell'edizione self-hosted: usare il file di licenza del proprio server Holarch così com'è. Negli ultimi 30 giorni lo strumento stampa un promemoria. Nei 30 giorni successivi alla data di fine (il periodo di tolleranza della licenza) lo strumento continua a funzionare e stampa i giorni rimanenti; poi si ferma finché non viene installata una licenza rinnovata.

Anche una chiave del motore oltre i suoi 14 giorni ferma lo strumento finché non viene installata una chiave rinnovata.

Il token di un account del piano Free viene rifiutato, anche quando l'account mantiene l'API tramite un indirizzo email accademico. La prova Individual include lo strumento.

File di licenza in CI

Conservare la licenza come secret, mai nel repository. In CI, scrivere il secret in un file fuori dal checkout (in GitHub Actions, sotto $RUNNER_TEMP) e impostare HOLARCH_LICENSE_FILE sul suo percorso.

Report

Output JSON

--format json e --json FILE scrivono:

CampoSignificato
tool, version, engineholarch, la versione dello strumento, la versione del motore
filesI file controllati, come percorsi relativi alla cartella in cui è stato eseguito lo strumento
summaryerrors, warnings, notes, files
diagnosticsfile, line, column, endLine, endColumn (a partire da 1), severity (error, warning, info), code, message, args
skippedFile non controllati, con il motivo (file KerML con un motore più vecchio)
excludedFile con errori di sintassi, omessi dai controlli tra file

Le colonne contano i caratteri Unicode (code point).

SARIF

--format sarif e --sarif FILE scrivono SARIF 2.1.0 con una regola per codice di diagnostica, la gravità come error, warning o note, e percorsi relativi alla cartella in cui è stato eseguito lo strumento. Eseguire lo strumento nella radice del repository affinché il code scanning trovi i file.

Annotazioni GitHub

--format github stampa un comando di workflow per problema (::error file=…,line=…,col=…::message), che GitHub Actions mostra come annotazioni, poi la riga di riepilogo.

Codici di uscita

CodiceSignificato
0Nessun errore (format: nulla da modificare)
1Il modello ha errori; format --check o --diff: un file verrebbe modificato, o un file non si è potuto formattare; export: rifiutato a causa di errori
2Uso errato: un'opzione sconosciuta, un percorso inesistente, nessun file di modello
3Accesso non eseguito o non autorizzato: nessun token o file di licenza, un token rifiutato, un piano Free, un file di licenza non valido, modificato o scaduto
4Il motore non può essere eseguito, o ha rifiutato il modello perché troppo grande o troppo lento da controllare

Messaggi

MessaggioSignificato
"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)." (Lo strumento richiede un token API Holarch di un piano Individual o Team oppure un file di licenza dell'Holarch Language Engine.)Non è impostato né un token né un file di licenza
"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." (Lo strumento è incluso nei piani Individual e Team; scegliere un piano o usare un file di licenza.)L'account del token è nel piano Free
"The API and MCP come with the Individual and Team plans." (API e MCP sono inclusi nei piani Individual e Team.)L'account del token è nel piano Free e non ha nemmeno l'accesso all'API
"The API token is not valid: it is wrong, revoked or expired, or its account cannot sign in." (Il token API non è valido.)Creare un nuovo token
"The license file's signature does not verify. Use the file exactly as it was delivered." (La firma del file di licenza non è valida.)Il file di licenza è stato modificato o è danneggiato
"License <id> expired on <date>. Install a renewed license file." (La licenza è scaduta; installare un file di licenza rinnovato.)Una licenza self-hosted è terminata da più di 30 giorni, o una chiave di licenza del motore da più di 14 giorni
"The engine license key's signature does not verify. Use the key exactly as it was delivered." (La firma della chiave di licenza del motore non è valida.)La chiave nel file è stata modificata o proviene da un altro prodotto
"The engine license key is not complete. Copy the whole key (l1.….…) into the file." (La chiave di licenza del motore è incompleta.)Manca una parte della chiave
"… cannot be reached to check the API token" (server non raggiungibile per verificare il token API)Nessuna connessione e nessuna risposta recente nella cache; riprovare o usare un file di licenza
"<file>: not formatted: the file has syntax errors." (non formattato: il file ha errori di sintassi.)Eseguire holarch check per vederli
"<file>: not formatted: a comment could not be kept in place." (non formattato: non è stato possibile mantenere un commento al suo posto.)Il file resta invariato; lo strumento non elimina mai un commento
"The model has errors, so it was not exported." (Il modello ha errori, quindi non è stato esportato.)Correggere gli errori o aggiungere --force
"The installed engine does not carry the Holarch Language Engine copyright notice, so it is not a genuine Holarch build." (Il motore installato non è una build originale di Holarch.)Reinstallare lo strumento

Limiti

  • Al massimo 8 MB di testo SysML per linguaggio in un modello, e righe fino a 64 KB, come nell'editor.
  • Al massimo 10.000 file in un'esecuzione.
  • Ogni passo del motore si interrompe dopo --timeout secondi (predefinito 60).
  • I nomi si risolvono tra file dello stesso linguaggio: un file .sysml non vede i nomi dichiarati in un file .kerml.