SysML v2
A ferramenta de linha de comando holarch
Cheque, formate e exporte modelos SysML v2 em builds e CI com a ferramenta de linha de comando holarch e o Holarch Language Engine; GitHub Actions e outros sistemas de CI, relatórios JSON e SARIF, códigos de saída, login com um token de API ou um arquivo de licença.
Nesta página
Visão geral
holarch é uma ferramenta de linha de comando que checa arquivos de texto SysML v2 com o Holarch Language Engine, o mesmo motor que o editor do Holarch usa. Execute-a no seu próprio computador ou em um build: ela lê todo arquivo .sysml de uma pasta, relata os problemas com arquivo, linha e coluna, e sai com um código diferente de zero quando o modelo tem erros, de modo que um pull request com um modelo quebrado falha nas checagens.
A ferramenta faz três coisas:
- Checar: sintaxe, nomes, tipos, especializações, multiplicidades, unidades e as outras regras do motor, em todos os arquivos do modelo. Relata como texto, JSON, SARIF (para code scanning) ou anotações do GitHub.
- Formatar: reescreve os arquivos em um layout canônico (indentação de quatro espaços, um elemento por linha, espaçamento canônico), mantendo todos os comentários.
- Exportar: grava o modelo como JSON do SysML v2, o formato de intercâmbio da Systems Modeling API.
A ferramenta vem com os planos Individual e Team (incluindo o período de teste), com uma licença do Holarch Language Engine e com uma licença da edição auto-hospedada. Ela não precisa de um projeto Holarch: funciona sobre os arquivos do seu repositório.
Conceitos
- Modelo: todos os arquivos
.sysmlnas pastas que você indicar (padrão: a pasta atual), lidos como um único modelo. Um nome declarado em um arquivo é resolvido nos outros, como os pacotes em um projeto Holarch. As pastas cujo nome começa com ponto (como.git) são ignoradas. - Arquivos KerML: os arquivos
.kermlsão checados como KerML pelas versões do motor que leem KerML. As versões mais antigas do motor os listam como ignorados, o que não é um erro. - Diagnósticos: cada problema tem um código (por exemplo
name.unresolved), uma severidade (error, warning ou note), uma posição e uma mensagem com as mesmas palavras do editor do Holarch. Só os erros fazem uma checagem falhar, a menos que você adicione--warnings-as-errors. - Login: a ferramenta checa uma vez por dia se seu token de API pertence a um plano Individual ou Team, ou lê um arquivo de licença sem nenhum acesso à rede. Consulte Login da ferramenta.
- O motor: a ferramenta contém o Holarch Language Engine compilado e a biblioteca padrão do SysML v2.
holarch versionimprime suas versões e o aviso de copyright do motor.
Como usá-lo
Quando e por quê
Use a ferramenta onde o texto SysML v2 fica em um repositório de código-fonte: os projetistas editam os arquivos .sysml no editor de sua preferência, e cada mudança é checada antes de ser mesclada. Ela responde "este modelo ainda se sustenta?" a cada commit, como um compilador faz para o código. Use o editor do Holarch para modelagem, diagramas e revisões; use a ferramenta para proteger os arquivos entre as edições. Para mover um modelo entre o repositório e um projeto Holarch, use Importar e exportar.
Instalar
- Instale o Python 3.9 ou posterior.
- Instale a ferramenta para o seu sistema (Linux x86-64, Linux arm64 ou macOS em Apple silicon) com o pip:
python3 -m pip install holarch-cli
- Cheque a instalação:
holarch versionimprime as versões da ferramenta, do motor e da biblioteca.
Entrar com um token de API
- No Holarch, abra Ajustes da conta → Tokens de API e crie um token. O acesso Somente leitura basta.
- Coloque o token na variável de ambiente
HOLARCH_API_KEY(em CI: um secret). - Execute
holarch whoami. Ele imprime seu plano e sua conta, por exemplo"plan": "team".
Checar um modelo
holarch check models/
Cada problema ocupa uma linha, seguida de um resumo:
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.
O código de saída é 1 quando o modelo tem erros e 0 caso contrário. Adicione --warnings-as-errors para falhar também com avisos.
Formatar arquivos
- Execute
holarch format models/. Cada arquivo alterado é listado como "reformatted <file>". - Para checar o layout em CI sem alterar arquivos, execute
holarch format --check models/. Ele lista "would reformat <file>" e sai com 1 quando um arquivo mudaria. - Para ver as mudanças antes, execute
holarch format --diff models/.
Um arquivo com erros de sintaxe não é formatado ("not formatted: the file has syntax errors."). Os comentários ficam onde estavam: notas antes de um elemento ficam acima dele, uma nota no fim de uma linha fica no fim dessa linha.
Exportar o modelo como JSON do SysML v2
holarch export models/ -o model.json
O arquivo contém o array de elementos padrão da Systems Modeling API. Os mesmos arquivos sempre dão o mesmo JSON, então a exportação pode ser versionada e comparada. Um modelo com erros não é exportado ("The model has errors, so it was not exported."); adicione --force para exportá-lo mesmo assim. Adicione --holarch-fields para manter o que só o Holarch lê (ordem dos elementos, grafia), para uma importação exata em um projeto Holarch.
Executar no GitHub Actions
- Adicione o token de API como um secret do repositório chamado
HOLARCH_API_KEY(Settings → Secrets and variables → Actions). - Adicione um arquivo de workflow, por exemplo
.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
- Faça push. Os problemas aparecem como anotações nas linhas alteradas do pull request, e o job falha quando o modelo tem erros ou quando um arquivo não está no layout canônico. Omita a etapa
holarch format --checkpara checar apenas o modelo.
A última etapa envia o relatório SARIF ao code scanning, onde os problemas são listados em Security → Code scanning. Omita-a se o seu repositório não usa code scanning: as anotações funcionam sem ela.
Executar em outros sistemas de CI
Qualquer sistema de CI com Python 3.9 ou posterior executa os mesmos comandos. Instale a ferramenta, defina o token a partir de um secret e cheque:
python3 -m pip install holarch-cli
holarch check models/ --sarif holarch.sarif --json holarch.json
Por exemplo, GitLab CI (.gitlab-ci.yml, com HOLARCH_API_KEY como variável de CI/CD mascarada):
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 outros funcionam da mesma forma: uma etapa instala a ferramenta, a seguinte executa holarch check; um código de saída diferente de zero faz o build falhar. Guarde o relatório JSON (--json) como artefato do build quando quiser os números em um painel.
Exemplo prático: a demonstração Hybrid Car
- Crie a demonstração: em Gerenciar projetos, clique em Arquivos do projeto ▾ → Novo projeto de demonstração → Hybrid Car (SysML v2).
- Abra Modelo → Importar e exportar. Em Exportar, escolha Todo o modelo e texto SysML v2, clique em Exportar e descompacte o download em uma pasta
modelsdo seu repositório. - Execute
holarch check models. O resultado é "6 files checked: 0 errors, 0 warnings." - Em
requirements.sysml, altereattribute maxCurbMass : MassValueparaMassValue execute a checagem de novo. Ela relatarequirements.sysml:14:27: error name.unresolved: “MassValu” is not defined here.e sai com 1. - Desfaça a alteração. Execute
holarch format modelsuma vez e faça commit dos arquivos, para que as execuções posteriores deformat --checkpassem. - Adicione o workflow do GitHub acima. Todo pull request posterior que quebrar o modelo falha na checagem.
Dicas e boas práticas
- Mantenha o conteúdo de cada arquivo em um pacote. Elementos fora de qualquer pacote funcionam, mas um pacote por arquivo mantém os nomes únicos entre os arquivos.
- Use um token somente leitura para CI, limitado a nenhum projeto: a ferramenta não precisa de acesso a projetos.
- Formate uma vez e faça commit do resultado antes de ativar
format-check, ou a primeira execução falha em todos os arquivos. - Fixe a versão da ferramenta em CI (
holarch-cli==<version>) para que uma nova versão do motor não mude os resultados no meio de uma revisão. - Runners sem acesso à internet usam um arquivo de licença em vez de um token.
Erros comuns
- "No .sysml or .kerml files found": o caminho está errado, ou os arquivos estão em uma pasta cujo nome começa com ponto.
- Nomes não resolvidos em um só arquivo: o arquivo declara nomes que outro arquivo usa, e esse outro arquivo tem um erro de sintaxe. Corrija o erro de sintaxe primeiro; o relatório diz quais arquivos ficaram de fora.
- O job falha com o código de saída 3: o token está ausente, errado ou pertence a uma conta no plano Free. A mensagem diz qual é o caso.
Como se conecta a outros recursos
- As checagens são as do texto SysML v2 do editor do Holarch e das Checagens do modelo para projetos SysML v2, com as mesmas mensagens (O editor de texto SysML v2).
- Os arquivos exportados de um projeto (Importar e exportar) passam nas checagens sem problemas; o JSON que a ferramenta exporta pode ser importado em um projeto.
- Para mudanças que devem passar por revisão no Holarch em vez de por arquivos, use a API ou o cliente Python, cujas mudanças chegam como propostas.
Comandos
| Comando | O que ele faz |
|---|---|
holarch check [paths] | Checa o modelo; relata problemas; sai com 1 em caso de erros |
holarch format [paths] | Reescreve os arquivos no layout canônico |
holarch export [paths] | Grava o modelo como JSON do SysML v2 |
holarch whoami | Mostra o que o token ou o arquivo de licença permite |
holarch version | Imprime as versões da ferramenta, do motor e da biblioteca e o aviso de copyright do motor (sem login) |
Os caminhos são arquivos ou pastas; o padrão é a pasta atual. As pastas são pesquisadas com suas subpastas.
Opções de check
| Opção | Significado |
|---|---|
--format human|json|sarif|github | O relatório na saída padrão (padrão human) |
--output FILE | Grava esse relatório em um arquivo |
--sarif FILE | Grava também um relatório SARIF 2.1.0 |
--json FILE | Grava também um relatório JSON |
--warnings-as-errors | Sai com 1 também em caso de avisos |
Opções de format
| Opção | Significado |
|---|---|
--check | Não altera nada; sai com 1 quando um arquivo mudaria |
--diff | Não altera nada; imprime as mudanças como diff unificado |
--stdout | Imprime o texto formatado de um arquivo em vez de gravá-lo |
Opções de export
| Opção | Significado |
|---|---|
-o FILE, --output FILE | Grava em um arquivo (padrão: saída padrão) |
--holarch-fields | Acrescenta os campos que só o Holarch lê, para uma ida e volta exata |
--force | Exporta um modelo com erros (nunca um com erros de sintaxe) |
Opções de todo comando que faz login
| Opção | Variável de ambiente | Significado |
|---|---|---|
--api-key KEY | HOLARCH_API_KEY | Um token de API (hol_…); prefira a variável, para que o token fique fora dos logs |
--license FILE | HOLARCH_LICENSE_FILE | Um arquivo de licença para uso offline |
--server URL | HOLARCH_SERVER | O servidor Holarch que checa o token (um endereço https) |
--timeout SECONDS | Limite de tempo de cada etapa do motor (padrão 60) |
Login da ferramenta
A ferramenta é executada quando um destes está presente:
- Um token de API de um plano Individual ou Team, incluindo o período de teste do Individual. A ferramenta consulta o servidor uma vez e guarda a resposta por um dia em um arquivo de cache (
~/.cache/holarch/entitlement.json;HOLARCH_CACHE_DIRo muda de lugar). O cache contém o plano e o e-mail da conta, nunca o token. Quando o servidor não pode ser alcançado, uma resposta de até 7 dias ainda vale, com uma nota. - Um arquivo de licença, para licenciados do Holarch Language Engine, clientes da edição auto-hospedada e runners sem acesso à internet. A própria ferramenta checa a assinatura do arquivo e nunca se conecta a um servidor. Toda licença válida inclui a ferramenta sem custo adicional:
- Licença do Holarch Language Engine: salve a chave de licença da entrega do motor (o texto que começa com
l1.) em um arquivo, por exemploholarch-engine.key, e aponte--licenseouHOLARCH_LICENSE_FILEpara ele. Quebras de linha acrescentadas por um e-mail não importam. Os endereços web licenciados e o uso em servidor da chave se aplicam ao motor no seu produto, não à ferramenta. Nos 14 dias após a data final da chave, a ferramenta continua funcionando e imprime um lembrete. - Licença da edição auto-hospedada: use o arquivo de licença do seu servidor Holarch como está. Nos seus últimos 30 dias, a ferramenta imprime um lembrete. Nos 30 dias após a data final (o período de carência da licença), a ferramenta continua funcionando e imprime os dias restantes; depois disso, ela para até que uma licença renovada seja instalada.
- Licença do Holarch Language Engine: salve a chave de licença da entrega do motor (o texto que começa com
Uma chave do motor após seus 14 dias também faz a ferramenta parar até que uma chave renovada seja instalada.
Um token de uma conta no plano Free é recusado, também quando a conta mantém a API por meio de um endereço de e-mail acadêmico. O período de teste do Individual inclui a ferramenta.
Arquivos de licença em CI
Guarde a licença como secret, nunca no repositório. Em CI, grave o secret em um arquivo fora do checkout (no GitHub Actions, em $RUNNER_TEMP) e defina HOLARCH_LICENSE_FILE com o caminho dele.
Relatórios
Saída JSON
--format json e --json FILE gravam:
| Campo | Significado |
|---|---|
tool, version, engine | holarch, a versão da ferramenta, a versão do motor |
files | Os arquivos checados, como caminhos relativos à pasta em que a ferramenta foi executada |
summary | errors, warnings, notes, files |
diagnostics | file, line, column, endLine, endColumn (a partir de 1), severity (error, warning, info), code, message, args |
skipped | Arquivos não checados, com o motivo (arquivos KerML com um motor mais antigo) |
excluded | Arquivos com erros de sintaxe, deixados de fora das checagens entre arquivos |
As colunas contam caracteres Unicode (code points).
SARIF
--format sarif e --sarif FILE gravam SARIF 2.1.0 com uma regra por código de diagnóstico, a severidade como error, warning ou note, e caminhos relativos à pasta em que a ferramenta foi executada. Execute a ferramenta na raiz do repositório para que o code scanning encontre os arquivos.
Anotações do GitHub
--format github imprime um comando de workflow por problema (::error file=…,line=…,col=…::message), que o GitHub Actions mostra como anotações, e depois a linha de resumo.
Códigos de saída
| Código | Significado |
|---|---|
| 0 | Nenhum erro (format: nada mais a alterar) |
| 1 | O modelo tem erros; format --check ou --diff: um arquivo mudaria, ou um arquivo não pôde ser formatado; export: recusado por causa de erros |
| 2 | Uso incorreto: uma opção desconhecida, um caminho que não existe, nenhum arquivo de modelo |
| 3 | Sem login ou sem direito: nenhum token nem arquivo de licença, um token recusado, um plano Free, um arquivo de licença inválido, alterado ou expirado |
| 4 | O motor não consegue ser executado, ou recusou o modelo por ser grande demais ou lento demais para checar |
Mensagens
| Mensagem | 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)." | Nem um token nem um arquivo de licença está definido |
| "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." | A conta do token está no plano Free |
| "The API and MCP come with the Individual and Team plans." | A conta do token está no plano Free e também não tem acesso à API |
| "The API token is not valid: it is wrong, revoked or expired, or its account cannot sign in." | Crie um token novo |
| "The license file's signature does not verify. Use the file exactly as it was delivered." | O arquivo de licença foi alterado ou danificado |
| "License <id> expired on <date>. Install a renewed license file." | Uma licença auto-hospedada terminou há mais de 30 dias, ou uma chave de licença do motor há mais de 14 dias |
| "The engine license key's signature does not verify. Use the key exactly as it was delivered." | A chave no arquivo foi alterada ou é de outro produto |
| "The engine license key is not complete. Copy the whole key (l1.….…) into the file." | Falta parte da chave |
| "… cannot be reached to check the API token" | Sem conexão e sem resposta recente no cache; tente de novo ou use um arquivo de licença |
| "<file>: not formatted: the file has syntax errors." | Execute holarch check para vê-los |
| "<file>: not formatted: a comment could not be kept in place." | O arquivo fica inalterado; a ferramenta nunca descarta um comentário |
| "The model has errors, so it was not exported." | Corrija os erros ou adicione --force |
| "The installed engine does not carry the Holarch Language Engine copyright notice, so it is not a genuine Holarch build." | Reinstale a ferramenta |
Limites
- No máximo 8 MB de texto SysML por linguagem em um modelo, e linhas de até 64 KB, como no editor.
- No máximo 10.000 arquivos em uma execução.
- Cada etapa do motor para após
--timeoutsegundos (padrão 60). - Os nomes são resolvidos entre arquivos da mesma linguagem: um arquivo
.sysmlnão vê nomes declarados em um arquivo.kerml.