SysML v2
L'outil en ligne de commande holarch
Contrôlez, formatez et exportez des modèles SysML v2 dans les builds et la CI avec l'outil en ligne de commande holarch et le Holarch Language Engine ; GitHub Actions et autres systèmes de CI, rapports JSON et SARIF, codes de sortie, connexion avec un jeton d'API ou un fichier de licence.
Sur cette page
- Vue d'ensemble
- Concepts
- Mode d'emploi
- Quand et pourquoi
- Installer
- Se connecter avec un jeton API
- Contrôler un modèle
- Formater des fichiers
- Exporter le modèle en JSON SysML v2
- L'exécuter dans GitHub Actions
- L'exécuter dans d'autres systèmes de CI
- Exemple commenté : la démo Hybrid Car
- Conseils et bonnes pratiques
- Erreurs courantes
- Liens avec les autres fonctions
- Commandes
- Connexion de l'outil
- Rapports
- Codes de sortie
- Messages
- Limites
- Pages associées
Vue d'ensemble
holarch est un outil en ligne de commande qui contrôle des fichiers texte SysML v2 avec le Holarch Language Engine, le même moteur que celui de l'éditeur Holarch. Exécutez-le sur votre ordinateur ou dans un build : il lit chaque fichier .sysml d'un dossier, signale les problèmes avec fichier, ligne et colonne, et se termine avec un code non nul lorsque le modèle a des erreurs, de sorte qu'une pull request contenant un modèle cassé échoue à ses contrôles.
L'outil fait trois choses :
- Contrôler : syntaxe, noms, types, spécialisations, multiplicités, unités et les autres règles du moteur, sur tous les fichiers du modèle. Rapports en texte, JSON, SARIF (pour l'analyse de code) ou annotations GitHub.
- Formater : réécrit les fichiers selon une disposition canonique (indentation de quatre espaces, un élément par ligne, espacement canonique), en gardant chaque commentaire.
- Exporter : écrit le modèle en JSON SysML v2, le format d'échange de l'API Systems Modeling.
L'outil est inclus dans les offres Individual et Team (essai compris), une licence Holarch Language Engine et une licence de l'édition auto-hébergée. Il n'a pas besoin d'un projet Holarch : il travaille sur les fichiers de votre dépôt.
Concepts
- Modèle : tous les fichiers
.sysmlsous les dossiers que vous nommez (par défaut : le dossier courant), lus comme un seul modèle. Un nom déclaré dans un fichier se résout dans les autres, comme le font les packages dans un projet Holarch. Les dossiers dont le nom commence par un point (comme.git) sont ignorés. - Fichiers KerML : les fichiers
.kermlsont contrôlés en KerML par les versions du moteur qui lisent KerML. Les versions plus anciennes du moteur les listent comme ignorés, ce qui n'est pas une erreur. - Diagnostics : chaque problème a un code (par exemple
name.unresolved), une gravité (error, warning ou note), une position et un message dans les mêmes termes que l'éditeur Holarch. Seules les erreurs font échouer un contrôle, sauf si vous ajoutez--warnings-as-errors. - Connexion : l'outil vérifie une fois par jour que votre jeton API appartient à une offre Individual ou Team, ou lit un fichier de licence sans aucun accès réseau. Voir Connexion de l'outil.
- Le moteur : l'outil contient le Holarch Language Engine compilé et la bibliothèque standard SysML v2.
holarch versionaffiche leurs versions et la mention de copyright du moteur.
Mode d'emploi
Quand et pourquoi
Utilisez l'outil là où le texte SysML v2 vit dans un dépôt de sources : les concepteurs modifient les fichiers .sysml dans l'éditeur de leur choix, et chaque modification est contrôlée avant d'être fusionnée. Il répond à « ce modèle tient-il toujours debout ? » à chaque commit, comme un compilateur le fait pour du code. Utilisez l'éditeur Holarch pour la modélisation, les diagrammes et les revues ; utilisez l'outil pour protéger les fichiers entre les modifications. Pour transférer un modèle entre le dépôt et un projet Holarch, utilisez Importer et exporter.
Installer
- Installez Python 3.9 ou ultérieur.
- Installez l'outil pour votre système (Linux x86-64, Linux arm64 ou macOS sur Apple silicon) avec pip :
python3 -m pip install holarch-cli
- Vérifiez l'installation :
holarch versionaffiche les versions de l'outil, du moteur et de la bibliothèque.
Se connecter avec un jeton API
- Dans Holarch, ouvrez Paramètres du compte → Jetons API et créez un jeton. Un accès en Lecture seule suffit.
- Mettez le jeton dans la variable d'environnement
HOLARCH_API_KEY(en CI : un secret). - Exécutez
holarch whoami. Il affiche votre offre et votre compte, par exemple"plan": "team".
Contrôler un modèle
holarch check models/
Chaque problème occupe une ligne, puis vient un résumé :
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.
Le code de sortie est 1 lorsque le modèle a des erreurs et 0 sinon. Ajoutez --warnings-as-errors pour échouer aussi sur les avertissements.
Formater des fichiers
- Exécutez
holarch format models/. Chaque fichier modifié est listé sous la forme « reformatted <file> ». - Pour contrôler la disposition en CI sans modifier les fichiers, exécutez
holarch format --check models/. Il liste « would reformat <file> » et se termine avec 1 lorsqu'un fichier changerait. - Pour voir d'abord les modifications, exécutez
holarch format --diff models/.
Un fichier comportant des erreurs de syntaxe n'est pas formaté (« not formatted: the file has syntax errors. »). Les commentaires restent où ils étaient : les notes placées avant un élément restent au-dessus de lui, une note en fin de ligne reste à la fin de cette ligne.
Exporter le modèle en JSON SysML v2
holarch export models/ -o model.json
Le fichier contient le tableau d'éléments standard de l'API Systems Modeling. Les mêmes fichiers donnent toujours le même JSON, de sorte que l'export peut être versionné et comparé. Un modèle comportant des erreurs n'est pas exporté (« The model has errors, so it was not exported. ») ; ajoutez --force pour l'exporter quand même. Ajoutez --holarch-fields pour garder ce que seul Holarch lit (ordre des éléments, graphie), pour une importation exacte dans un projet Holarch.
L'exécuter dans GitHub Actions
- Ajoutez le jeton API comme secret du dépôt nommé
HOLARCH_API_KEY(Settings → Secrets and variables → Actions). - Ajoutez un fichier de workflow, par exemple
.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
- Faites un push. Les problèmes apparaissent comme annotations sur les lignes modifiées de la pull request, et le job échoue lorsque le modèle a des erreurs ou qu'un fichier n'est pas dans la disposition canonique. Omettez l'étape
holarch format --checkpour ne contrôler que le modèle.
La dernière étape téléverse le rapport SARIF vers l'analyse de code, où les problèmes sont listés sous Security → Code scanning. Omettez-la si votre dépôt n'utilise pas l'analyse de code : les annotations fonctionnent sans elle.
L'exécuter dans d'autres systèmes de CI
Tout système de CI disposant de Python 3.9 ou ultérieur exécute les mêmes commandes. Installez l'outil, définissez le jeton à partir d'un secret, lancez le contrôle :
python3 -m pip install holarch-cli
holarch check models/ --sarif holarch.sarif --json holarch.json
Par exemple, GitLab CI (.gitlab-ci.yml, avec HOLARCH_API_KEY comme variable CI/CD masquée) :
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 et d'autres fonctionnent de la même façon : une étape installe l'outil, la suivante exécute holarch check ; un code de sortie non nul fait échouer le build. Conservez le rapport JSON (--json) comme artefact de build si vous voulez les chiffres dans un tableau de bord.
Exemple commenté : la démo Hybrid Car
- Créez la démo : dans Gérer les projets, cliquez sur Fichiers de projet ▾ → Nouveau projet de démonstration → Hybrid Car (SysML v2).
- Ouvrez Modèle → Importer et exporter. Sous Exporter, choisissez Le modèle entier et Texte SysML v2, cliquez sur Exporter, et décompressez le téléchargement dans un dossier
modelsde votre dépôt. - Exécutez
holarch check models. Le résultat est « 6 files checked: 0 errors, 0 warnings. » - Dans
requirements.sysml, remplacezattribute maxCurbMass : MassValueparMassValuet relancez le contrôle. Il signalerequirements.sysml:14:27: error name.unresolved: “MassValu” is not defined here.et se termine avec 1. - Annulez la modification. Exécutez une fois
holarch format modelset validez les fichiers, afin que les exécutions ultérieures deformat --checkréussissent. - Ajoutez le workflow GitHub ci-dessus. Chaque pull request ultérieure qui casse le modèle échoue à son contrôle.
Conseils et bonnes pratiques
- Gardez le contenu de chaque fichier dans un package. Les éléments hors de tout package fonctionnent, mais un package par fichier garde les noms uniques d'un fichier à l'autre.
- Utilisez pour la CI un jeton en lecture seule, limité à aucun projet : l'outil n'a besoin d'aucun accès aux projets.
- Formatez une fois et validez le résultat avant d'activer
format-check, sinon la première exécution échoue sur chaque fichier. - Épinglez la version de l'outil en CI (
holarch-cli==<version>) pour qu'une nouvelle version du moteur ne change pas les résultats au milieu d'une revue. - Les runners sans accès à Internet utilisent un fichier de licence au lieu d'un jeton.
Erreurs courantes
- « No .sysml or .kerml files found » : le chemin est faux, ou les fichiers sont dans un dossier dont le nom commence par un point.
- Noms non résolus dans un seul fichier : le fichier déclare des noms qu'un autre fichier utilise, et cet autre fichier a une erreur de syntaxe. Corrigez d'abord l'erreur de syntaxe ; le rapport indique quels fichiers ont été omis.
- Le job échoue avec le code de sortie 3 : le jeton est absent, erroné, ou appartient à un compte de l'offre Free. Le message indique lequel.
Liens avec les autres fonctions
- Les contrôles sont ceux du texte SysML v2 de l'éditeur Holarch et des Contrôles du modèle pour les projets SysML v2, avec les mêmes messages (L'éditeur de texte SysML v2).
- Les fichiers exportés d'un projet (Importer et exporter) passent le contrôle sans problème ; le JSON qu'exporte l'outil s'importe dans un projet.
- Pour les modifications qui doivent passer par une revue dans Holarch plutôt que par des fichiers, utilisez l'API ou le client Python, dont les modifications arrivent sous forme de propositions.
Commandes
| Commande | Ce qu'il fait |
|---|---|
holarch check [paths] | Contrôle le modèle ; signale les problèmes ; sortie 1 en cas d'erreurs |
holarch format [paths] | Réécrit les fichiers dans la disposition canonique |
holarch export [paths] | Écrit le modèle en JSON SysML v2 |
holarch whoami | Affiche ce que permet le jeton ou le fichier de licence |
holarch version | Affiche les versions de l'outil, du moteur et de la bibliothèque, et la mention de copyright du moteur (aucune connexion nécessaire) |
Les chemins sont des fichiers ou des dossiers ; par défaut, le dossier courant. Les dossiers sont parcourus avec leurs sous-dossiers.
Options de check
| Option | Signification |
|---|---|
--format human|json|sarif|github | Le rapport sur la sortie standard (human par défaut) |
--output FILE | Écrire ce rapport dans un fichier à la place |
--sarif FILE | Écrire aussi un rapport SARIF 2.1.0 |
--json FILE | Écrire aussi un rapport JSON |
--warnings-as-errors | Sortie 1 aussi en cas d'avertissements |
Options de format
| Option | Signification |
|---|---|
--check | Ne rien modifier ; sortie 1 lorsqu'un fichier changerait |
--diff | Ne rien modifier ; afficher les modifications sous forme de diff unifié |
--stdout | Afficher le texte formaté d'un fichier au lieu de l'écrire |
Options d'export
| Option | Signification |
|---|---|
-o FILE, --output FILE | Écrire dans un fichier (par défaut : sortie standard) |
--holarch-fields | Ajouter les champs que seul Holarch lit, pour un aller-retour exact |
--force | Exporter un modèle comportant des erreurs (jamais un modèle avec des erreurs de syntaxe) |
Options de chaque commande qui se connecte
| Option | Variable d'environnement | Signification |
|---|---|---|
--api-key KEY | HOLARCH_API_KEY | Un jeton API (hol_…) ; préférez la variable, pour que le jeton reste hors des journaux |
--license FILE | HOLARCH_LICENSE_FILE | Un fichier de licence pour une utilisation hors ligne |
--server URL | HOLARCH_SERVER | Le serveur Holarch qui vérifie le jeton (une adresse https) |
--timeout SECONDS | Délai maximal pour chaque étape du moteur (60 par défaut) |
Connexion de l'outil
L'outil s'exécute lorsque l'un de ces éléments est présent :
- Un jeton API d'une offre Individual ou Team, essai Individual compris. L'outil interroge le serveur une fois et garde la réponse pendant une journée dans un fichier cache (
~/.cache/holarch/entitlement.json;HOLARCH_CACHE_DIRle déplace). Le cache contient l'offre et l'e-mail du compte, jamais le jeton. Lorsque le serveur est injoignable, une réponse datant de 7 jours au plus compte encore, avec une note. - Un fichier de licence, pour les titulaires d'une licence Holarch Language Engine, les clients de l'édition auto-hébergée et les runners sans accès à Internet. L'outil vérifie lui-même la signature du fichier et ne se connecte jamais à un serveur. Chaque licence valide inclut l'outil sans frais supplémentaires :
- Licence Holarch Language Engine : enregistrez la clé de licence de votre livraison du moteur (le texte qui commence par
l1.) dans un fichier, par exempleholarch-engine.key, et faites pointer--licenseouHOLARCH_LICENSE_FILEvers lui. Les sauts de ligne ajoutés par un e-mail n'ont pas d'importance. Les adresses web et l'usage serveur couverts par la clé s'appliquent au moteur dans votre produit, et non à l'outil. Dans les 14 jours suivant la date de fin de la clé, l'outil continue de fonctionner et affiche un rappel. - Licence de l'édition auto-hébergée : utilisez tel quel le fichier de licence de votre serveur Holarch. Pendant ses 30 derniers jours, l'outil affiche un rappel. Dans les 30 jours suivant la date de fin (la période de grâce de la licence), l'outil continue de fonctionner et affiche les jours restants ; ensuite, il s'arrête jusqu'à l'installation d'une licence renouvelée.
- Licence Holarch Language Engine : enregistrez la clé de licence de votre livraison du moteur (le texte qui commence par
Une clé de moteur au-delà de ses 14 jours arrête elle aussi l'outil jusqu'à l'installation d'une clé renouvelée.
Un jeton d'un compte de l'offre Free est refusé, même lorsque le compte garde l'API grâce à une adresse e-mail académique. L'essai Individual inclut l'outil.
Fichiers de licence en CI
Stockez la licence comme secret, jamais dans le dépôt. En CI, écrivez le secret dans un fichier hors de l'extraction (dans GitHub Actions, sous $RUNNER_TEMP) et définissez HOLARCH_LICENSE_FILE sur son chemin.
Rapports
Sortie JSON
--format json et --json FILE écrivent :
| Champ | Signification |
|---|---|
tool, version, engine | holarch, la version de l'outil, la version du moteur |
files | Les fichiers contrôlés, sous forme de chemins relatifs au dossier où l'outil a été exécuté |
summary | errors, warnings, notes, files |
diagnostics | file, line, column, endLine, endColumn (à partir de 1), severity (error, warning, info), code, message, args |
skipped | Fichiers non contrôlés, avec la raison (fichiers KerML avec un moteur plus ancien) |
excluded | Fichiers comportant des erreurs de syntaxe, omis des contrôles entre fichiers |
Les colonnes comptent des caractères Unicode (points de code).
SARIF
--format sarif et --sarif FILE écrivent du SARIF 2.1.0 avec une règle par code de diagnostic, la gravité sous la forme error, warning ou note, et des chemins relatifs au dossier où l'outil a été exécuté. Exécutez l'outil à la racine du dépôt pour que l'analyse de code trouve les fichiers.
Annotations GitHub
--format github affiche une commande de workflow par problème (::error file=…,line=…,col=…::message), que GitHub Actions affiche sous forme d'annotations, puis la ligne de résumé.
Codes de sortie
| Code | Signification |
|---|---|
| 0 | Aucune erreur (format : plus rien à modifier) |
| 1 | Le modèle a des erreurs ; format --check ou --diff : un fichier changerait, ou un fichier n'a pas pu être formaté ; export : refusé en raison d'erreurs |
| 2 | Mauvaise utilisation : une option inconnue, un chemin qui n'existe pas, aucun fichier de modèle |
| 3 | Non connecté ou non autorisé : aucun jeton ni fichier de licence, un jeton refusé, une offre Free, un fichier de licence invalide, modifié ou expiré |
| 4 | Le moteur ne peut pas s'exécuter, ou a refusé le modèle comme trop volumineux ou trop lent à contrôler |
Messages
| Message | Signification |
|---|---|
| « 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). » | Ni jeton ni fichier de licence n'est défini |
| « 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. » | Le compte du jeton est sur l'offre Free |
| « The API and MCP come with the Individual and Team plans. » | Le compte du jeton est sur l'offre Free et n'a pas non plus d'accès à l'API |
| « The API token is not valid: it is wrong, revoked or expired, or its account cannot sign in. » | Créez un nouveau jeton |
| « The license file's signature does not verify. Use the file exactly as it was delivered. » | Le fichier de licence a été modifié ou endommagé |
| « License <id> expired on <date>. Install a renewed license file. » | Une licence auto-hébergée a pris fin il y a plus de 30 jours, ou une clé de licence du moteur il y a plus de 14 jours |
| « The engine license key's signature does not verify. Use the key exactly as it was delivered. » | La clé du fichier a été modifiée ou provient d'un autre produit |
| « The engine license key is not complete. Copy the whole key (l1.….…) into the file. » | Une partie de la clé manque |
| « … cannot be reached to check the API token » | Aucune connexion et aucune réponse récente dans le cache ; réessayez, ou utilisez un fichier de licence |
| « <file>: not formatted: the file has syntax errors. » | Exécutez holarch check pour les voir |
| « <file>: not formatted: a comment could not be kept in place. » | Le fichier reste inchangé ; l'outil ne supprime jamais un commentaire |
| « The model has errors, so it was not exported. » | Corrigez les erreurs, ou ajoutez --force |
| « The installed engine does not carry the Holarch Language Engine copyright notice, so it is not a genuine Holarch build. » | Réinstallez l'outil |
Limites
- Au plus 8 Mo de texte SysML par langage dans un modèle, et des lignes jusqu'à 64 Ko, comme dans l'éditeur.
- Au plus 10 000 fichiers par exécution.
- Chaque étape du moteur s'arrête après
--timeoutsecondes (60 par défaut). - Les noms se résolvent entre fichiers du même langage : un fichier
.sysmlne voit pas les noms déclarés dans un fichier.kerml.