SysML v2
La herramienta de línea de comandos holarch
Compruebe, formatee y exporte modelos SysML v2 en compilaciones y CI con la herramienta de línea de comandos holarch y el Holarch Language Engine; GitHub Actions y otros sistemas de CI, informes JSON y SARIF, códigos de salida, inicio de sesión con un token de API o un archivo de licencia.
En esta página
- Resumen
- Conceptos
- Cómo usarlo
- Cuándo y por qué
- Instalación
- Iniciar sesión con un token de API
- Comprobar un modelo
- Formatear archivos
- Exportar el modelo como JSON de SysML v2
- Ejecutarla en GitHub Actions
- Ejecutarla en otros sistemas de CI
- Ejemplo práctico: la demostración Hybrid Car
- Consejos y buenas prácticas
- Errores habituales
- Cómo se relaciona con otras funciones
- Comandos
- Inicio de sesión de la herramienta
- Informes
- Códigos de salida
- Mensajes
- Límites
- Páginas relacionadas
Resumen
holarch es una herramienta de línea de comandos que comprueba archivos de texto SysML v2 con el Holarch Language Engine, el mismo motor que usa el editor de Holarch. Ejecútela en su propio equipo o en una compilación: lee todos los archivos .sysml de una carpeta, informa de los problemas con archivo, línea y columna, y termina con un código distinto de cero cuando el modelo tiene errores, de modo que una pull request con un modelo roto no supera sus comprobaciones.
La herramienta hace tres cosas:
- Comprobar: sintaxis, nombres, tipos, especializaciones, multiplicidades, unidades y las demás reglas del motor, en todos los archivos del modelo. Informa como texto, JSON, SARIF (para el análisis de código) o anotaciones de GitHub.
- Formatear: reescribe los archivos con un diseño canónico (sangría de cuatro espacios, un elemento por línea, espaciado canónico), conservando todos los comentarios.
- Exportar: escribe el modelo como JSON de SysML v2, el formato de intercambio de la Systems Modeling API.
La herramienta se incluye con los planes Individual y Team (incluida la prueba), con una licencia del Holarch Language Engine y con una licencia de la edición autoalojada. No necesita un proyecto de Holarch: trabaja sobre los archivos de su repositorio.
Conceptos
- Modelo: todos los archivos
.sysmlde las carpetas que indique (de forma predeterminada, la carpeta actual), leídos como un solo modelo. Un nombre declarado en un archivo se resuelve en los demás, como ocurre con los paquetes en un proyecto de Holarch. Las carpetas cuyo nombre empieza por un punto (como.git) se omiten. - Archivos KerML: los archivos
.kermlse comprueban como KerML con las versiones del motor que leen KerML. Las versiones anteriores del motor los muestran como omitidos, lo que no es un error. - Diagnósticos: cada problema tiene un código (por ejemplo
name.unresolved), una gravedad (error, advertencia o nota), una posición y un mensaje con las mismas palabras que el editor de Holarch. Solo los errores hacen fallar una comprobación, salvo que añada--warnings-as-errors. - Inicio de sesión: la herramienta comprueba una vez al día que su token de API pertenece a un plan Individual o Team, o lee un archivo de licencia sin ningún acceso a la red. Consulte Inicio de sesión de la herramienta.
- El motor: la herramienta contiene el Holarch Language Engine compilado y la biblioteca estándar de SysML v2.
holarch versionmuestra sus versiones y el aviso de copyright del motor.
Cómo usarlo
Cuándo y por qué
Use la herramienta donde el texto SysML v2 reside en un repositorio de código fuente: los diseñadores editan los archivos .sysml en el editor que prefieran, y cada cambio se comprueba antes de fusionarse. Responde a «¿este modelo sigue siendo coherente?» en cada commit, como hace un compilador con el código. Use el editor de Holarch para modelar, para los diagramas y para las revisiones; use la herramienta para proteger los archivos entre ediciones. Para mover un modelo entre el repositorio y un proyecto de Holarch, use Importación y exportación.
Instalación
- Instale Python 3.9 o posterior.
- Instale la herramienta para su sistema (Linux x86-64, Linux arm64 o macOS en Apple silicon) con pip:
python3 -m pip install holarch-cli
- Compruebe la instalación:
holarch versionmuestra las versiones de la herramienta, del motor y de la biblioteca.
Iniciar sesión con un token de API
- En Holarch, abra Ajustes de la cuenta → Tokens de API y cree un token. Basta con el acceso Solo lectura.
- Ponga el token en la variable de entorno
HOLARCH_API_KEY(en CI: un secreto). - Ejecute
holarch whoami. Muestra su plan y su cuenta, por ejemplo"plan": "team".
Comprobar un modelo
holarch check models/
Cada problema ocupa una línea, seguida de un resumen:
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.
El código de salida es 1 cuando el modelo tiene errores y 0 en caso contrario. Añada --warnings-as-errors para fallar también con advertencias.
Formatear archivos
- Ejecute
holarch format models/. Cada archivo cambiado aparece como «reformatted <file>». - Para comprobar el diseño en CI sin cambiar archivos, ejecute
holarch format --check models/. Muestra «would reformat <file>» y termina con 1 cuando un archivo cambiaría. - Para ver primero los cambios, ejecute
holarch format --diff models/.
Un archivo con errores de sintaxis no se formatea («not formatted: the file has syntax errors.»). Los comentarios se quedan donde estaban: las notas delante de un elemento siguen encima de él, una nota al final de una línea sigue al final de esa línea.
Exportar el modelo como JSON de SysML v2
holarch export models/ -o model.json
El archivo contiene el array de elementos estándar de la Systems Modeling API. Los mismos archivos siempre dan el mismo JSON, de modo que la exportación se puede confirmar en el repositorio y comparar. Un modelo con errores no se exporta («The model has errors, so it was not exported.»); añada --force para exportarlo de todos modos. Añada --holarch-fields para conservar lo que solo lee Holarch (orden de los elementos, escritura), para una importación exacta en un proyecto de Holarch.
Ejecutarla en GitHub Actions
- Añada el token de API como secreto del repositorio con el nombre
HOLARCH_API_KEY(Settings → Secrets and variables → Actions). - Añada un archivo de flujo de trabajo, por ejemplo
.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
- Haga push. Los problemas aparecen como anotaciones en las líneas cambiadas de la pull request, y el trabajo falla cuando el modelo tiene errores o un archivo no tiene el diseño canónico. Omita el paso
holarch format --checkpara comprobar solo el modelo.
El último paso sube el informe SARIF al análisis de código, donde los problemas se enumeran en Security → Code scanning. Omítalo si su repositorio no usa el análisis de código: las anotaciones funcionan sin él.
Ejecutarla en otros sistemas de CI
Cualquier sistema de CI con Python 3.9 o posterior ejecuta los mismos comandos. Instale la herramienta, establezca el token a partir de un secreto y compruebe:
python3 -m pip install holarch-cli
holarch check models/ --sarif holarch.sarif --json holarch.json
Por ejemplo, GitLab CI (.gitlab-ci.yml, con HOLARCH_API_KEY como variable de CI/CD enmascarada):
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 y otros funcionan de la misma forma: un paso instala la herramienta y el siguiente ejecuta holarch check; un código de salida distinto de cero hace fallar la compilación. Conserve el informe JSON (--json) como artefacto de compilación cuando quiera las cifras en un panel.
Ejemplo práctico: la demostración Hybrid Car
- Cree la demostración: en Gestionar proyectos, haga clic en Archivos de proyecto ▾ → Nuevo proyecto de demostración → Hybrid Car (SysML v2).
- Abra Modelo → Importación y exportación. En Exportar, elija Todo el modelo y texto SysML v2, haga clic en Exportar y descomprima la descarga en una carpeta
modelsde su repositorio. - Ejecute
holarch check models. El resultado es «6 files checked: 0 errors, 0 warnings.» - En
requirements.sysml, cambieattribute maxCurbMass : MassValueporMassValuy ejecute de nuevo la comprobación. Informarequirements.sysml:14:27: error name.unresolved: “MassValu” is not defined here.y termina con 1. - Deshaga el cambio. Ejecute
holarch format modelsuna vez y confirme los archivos, para que las ejecuciones posteriores deformat --checkpasen. - Añada el flujo de trabajo de GitHub anterior. Cada pull request posterior que rompa el modelo no supera su comprobación.
Consejos y buenas prácticas
- Mantenga el contenido de cada archivo en un paquete. Los elementos fuera de paquetes funcionan, pero un paquete por archivo mantiene los nombres únicos entre archivos.
- Use para CI un token de solo lectura, limitado a ningún proyecto: la herramienta no necesita acceso a proyectos.
- Formatee una vez y confirme el resultado antes de activar
format-check, o la primera ejecución fallará en todos los archivos. - Fije la versión de la herramienta en CI (
holarch-cli==<version>) para que una nueva versión del motor no cambie los resultados en mitad de una revisión. - Los ejecutores sin acceso a internet usan un archivo de licencia en lugar de un token.
Errores habituales
- «No .sysml or .kerml files found»: la ruta es incorrecta, o los archivos están en una carpeta cuyo nombre empieza por un punto.
- Nombres sin resolver en un solo archivo: el archivo declara nombres que usa otro archivo, y ese otro archivo tiene un error de sintaxis. Corrija primero el error de sintaxis; el informe indica qué archivos se omitieron.
- El trabajo falla con el código de salida 3: el token falta, es incorrecto o pertenece a una cuenta del plan Free. El mensaje indica cuál de ellos.
Cómo se relaciona con otras funciones
- Las comprobaciones son las del texto SysML v2 del editor de Holarch y las de Comprobaciones del modelo para proyectos SysML v2, con los mismos mensajes (El editor de texto SysML v2).
- Los archivos exportados desde un proyecto (Importación y exportación) se comprueban sin problemas; el JSON que exporta la herramienta se importa en un proyecto.
- Para los cambios que deben pasar por revisión en Holarch en lugar de por archivos, use la API o el cliente de Python, cuyos cambios llegan como propuestas.
Comandos
| Comando | Qué hace |
|---|---|
holarch check [paths] | Comprueba el modelo; informa de los problemas; sale con 1 si hay errores |
holarch format [paths] | Reescribe los archivos con el diseño canónico |
holarch export [paths] | Escribe el modelo como JSON de SysML v2 |
holarch whoami | Muestra lo que permite el token o el archivo de licencia |
holarch version | Muestra las versiones de la herramienta, del motor y de la biblioteca y el aviso de copyright del motor (no requiere inicio de sesión) |
Las rutas son archivos o carpetas; la predeterminada es la carpeta actual. Las carpetas se recorren con sus subcarpetas.
Opciones de check
| Opción | Significado |
|---|---|
--format human|json|sarif|github | El informe en la salida estándar (human de forma predeterminada) |
--output FILE | Escribir ese informe en un archivo en su lugar |
--sarif FILE | Escribir también un informe SARIF 2.1.0 |
--json FILE | Escribir también un informe JSON |
--warnings-as-errors | Salir con 1 también si hay advertencias |
Opciones de format
| Opción | Significado |
|---|---|
--check | No cambiar nada; salir con 1 cuando un archivo cambiaría |
--diff | No cambiar nada; mostrar los cambios como un diff unificado |
--stdout | Mostrar el texto formateado de un archivo en lugar de escribirlo |
Opciones de export
| Opción | Significado |
|---|---|
-o FILE, --output FILE | Escribir en un archivo (de forma predeterminada: salida estándar) |
--holarch-fields | Añadir los campos que solo lee Holarch, para un viaje de ida y vuelta exacto |
--force | Exportar un modelo con errores (nunca uno con errores de sintaxis) |
Opciones de todos los comandos que inician sesión
| Opción | Variable de entorno | Significado |
|---|---|---|
--api-key KEY | HOLARCH_API_KEY | Un token de API (hol_…); es preferible la variable, para que el token no aparezca en los registros |
--license FILE | HOLARCH_LICENSE_FILE | Un archivo de licencia para uso sin conexión |
--server URL | HOLARCH_SERVER | El servidor de Holarch que comprueba el token (una dirección https) |
--timeout SECONDS | Límite de tiempo para cada paso del motor (60 de forma predeterminada) |
Inicio de sesión de la herramienta
La herramienta se ejecuta cuando hay uno de estos:
- Un token de API de un plan Individual o Team, incluida la prueba de Individual. La herramienta pregunta al servidor una vez y guarda la respuesta durante un día en un archivo de caché (
~/.cache/holarch/entitlement.json;HOLARCH_CACHE_DIRlo traslada). La caché contiene el plan y el correo de la cuenta, nunca el token. Cuando no se puede contactar con el servidor, sigue valiendo una respuesta de hasta 7 días de antigüedad, con una nota. - Un archivo de licencia, para licenciatarios del Holarch Language Engine, clientes de la edición autoalojada y ejecutores sin acceso a internet. La herramienta comprueba ella misma la firma del archivo y nunca se conecta a un servidor. Toda licencia válida incluye la herramienta sin coste adicional:
- Licencia del Holarch Language Engine: guarde la clave de licencia de la entrega de su motor (el texto que empieza por
l1.) en un archivo, por ejemploholarch-engine.key, y apunte--licenseoHOLARCH_LICENSE_FILEa él. Los saltos de línea que haya añadido un correo no importan. Las direcciones web con licencia y el uso en servidor de la clave se aplican al motor en su producto, no a la herramienta. En los 14 días posteriores a la fecha de fin de la clave, la herramienta sigue funcionando y muestra un recordatorio. - Licencia de la edición autoalojada: use tal cual el archivo de licencia de su servidor de Holarch. En sus últimos 30 días, la herramienta muestra un recordatorio. En los 30 días posteriores a la fecha de fin (el periodo de gracia de la licencia), la herramienta sigue funcionando y muestra los días restantes; después se detiene hasta que se instala una licencia renovada.
- Licencia del Holarch Language Engine: guarde la clave de licencia de la entrega de su motor (el texto que empieza por
Una clave del motor pasados sus 14 días también detiene la herramienta hasta que se instala una clave renovada.
Se rechaza el token de una cuenta del plan Free, también cuando la cuenta conserva la API gracias a una dirección de correo académica. La prueba de Individual incluye la herramienta.
Archivos de licencia en CI
Guarde la licencia como secreto, nunca en el repositorio. En CI, escriba el secreto en un archivo fuera de la copia de trabajo (en GitHub Actions, en $RUNNER_TEMP) y establezca HOLARCH_LICENSE_FILE en su ruta.
Informes
Salida JSON
--format json y --json FILE escriben:
| Campo | Significado |
|---|---|
tool, version, engine | holarch, la versión de la herramienta, la versión del motor |
files | Los archivos comprobados, como rutas relativas a la carpeta en la que se ejecutó la herramienta |
summary | errors, warnings, notes, files |
diagnostics | file, line, column, endLine, endColumn (empezando en 1), severity (error, warning, info), code, message, args |
skipped | Archivos no comprobados, con el motivo (archivos KerML con un motor anterior) |
excluded | Archivos con errores de sintaxis, excluidos de las comprobaciones entre archivos |
Las columnas cuentan caracteres Unicode (puntos de código).
SARIF
--format sarif y --sarif FILE escriben SARIF 2.1.0 con una regla por código de diagnóstico, la gravedad como error, warning o note, y rutas relativas a la carpeta en la que se ejecutó la herramienta. Ejecute la herramienta en la raíz del repositorio para que el análisis de código encuentre los archivos.
Anotaciones de GitHub
--format github muestra un comando de flujo de trabajo por problema (::error file=…,line=…,col=…::message), que GitHub Actions muestra como anotaciones, y después la línea de resumen.
Códigos de salida
| Código | Significado |
|---|---|
| 0 | Sin errores (format: no queda nada por cambiar) |
| 1 | El modelo tiene errores; format --check o --diff: un archivo cambiaría o no se pudo formatear; export: rechazado por errores |
| 2 | Uso incorrecto: una opción desconocida, una ruta que no existe, ningún archivo de modelo |
| 3 | Sin sesión iniciada o sin derecho de uso: ningún token ni archivo de licencia, un token rechazado, un plan Free, un archivo de licencia no válido, modificado o caducado |
| 4 | El motor no puede ejecutarse, o rechazó el modelo por ser demasiado grande o demasiado lento de comprobar |
Mensajes
| Mensaje | Significado |
|---|---|
| «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).» (La herramienta necesita un token de API de un plan Individual o Team, o un archivo de licencia del Holarch Language Engine.) | No se ha establecido ni un token ni un archivo de licencia |
| «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.» (Elija un plan en Ajustes de la cuenta → Plan y facturación, o use un archivo de licencia del Holarch Language Engine.) | La cuenta del token está en el plan Free |
| «The API and MCP come with the Individual and Team plans.» (La API y MCP se incluyen con los planes Individual y Team.) | La cuenta del token está en el plan Free y tampoco tiene acceso a la API |
| «The API token is not valid: it is wrong, revoked or expired, or its account cannot sign in.» (El token de API no es válido.) | Cree un token nuevo |
| «The license file's signature does not verify. Use the file exactly as it was delivered.» (La firma del archivo de licencia no se verifica.) | El archivo de licencia se modificó o está dañado |
| «License <id> expired on <date>. Install a renewed license file.» (La licencia caducó; instale un archivo de licencia renovado.) | Una licencia autoalojada terminó hace más de 30 días, o una clave de licencia del motor hace más de 14 días |
| «The engine license key's signature does not verify. Use the key exactly as it was delivered.» (La firma de la clave de licencia del motor no se verifica.) | La clave del archivo se modificó o es de otro producto |
| «The engine license key is not complete. Copy the whole key (l1.….…) into the file.» (La clave está incompleta; copie la clave entera en el archivo.) | Falta parte de la clave |
| «… cannot be reached to check the API token» (no se puede contactar para comprobar el token de API) | Sin conexión y sin una respuesta reciente en la caché; inténtelo de nuevo o use un archivo de licencia |
| «<file>: not formatted: the file has syntax errors.» (no formateado: el archivo tiene errores de sintaxis) | Ejecute holarch check para verlos |
| «<file>: not formatted: a comment could not be kept in place.» (no formateado: no se pudo mantener un comentario en su sitio) | El archivo no cambia; la herramienta nunca descarta un comentario |
| «The model has errors, so it was not exported.» (El modelo tiene errores, por lo que no se exportó.) | Corrija los errores o añada --force |
| «The installed engine does not carry the Holarch Language Engine copyright notice, so it is not a genuine Holarch build.» (El motor instalado no es una compilación auténtica de Holarch.) | Reinstale la herramienta |
Límites
- Como máximo 8 MB de texto SysML por lenguaje en un modelo, y líneas de hasta 64 KB, como en el editor.
- Como máximo 10,000 archivos en una ejecución.
- Cada paso del motor se detiene después de
--timeoutsegundos (60 de forma predeterminada). - Los nombres se resuelven entre archivos del mismo lenguaje: un archivo
.sysmlno ve los nombres declarados en un archivo.kerml.