Holarch

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.

Como usá-lo →

Nesta página
  1. Visão geral
  2. Conceitos
  3. Como usá-lo
    1. Quando e por quê
    2. Instalar
    3. Entrar com um token de API
    4. Checar um modelo
    5. Formatar arquivos
    6. Exportar o modelo como JSON do SysML v2
    7. Executar no GitHub Actions
    8. Executar em outros sistemas de CI
    9. Exemplo prático: a demonstração Hybrid Car
    10. Dicas e boas práticas
    11. Erros comuns
    12. Como se conecta a outros recursos
  4. Comandos
    1. Opções de check
    2. Opções de format
    3. Opções de export
    4. Opções de todo comando que faz login
  5. Login da ferramenta
    1. Arquivos de licença em CI
  6. Relatórios
    1. Saída JSON
    2. SARIF
    3. Anotações do GitHub
  7. Códigos de saída
  8. Mensagens
  9. Limites
  10. Páginas relacionadas

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 .sysml nas 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 .kerml sã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 version imprime 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

  1. Instale o Python 3.9 ou posterior.
  2. 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
  1. Cheque a instalação: holarch version imprime as versões da ferramenta, do motor e da biblioteca.

Entrar com um token de API

  1. No Holarch, abra Ajustes da conta → Tokens de API e crie um token. O acesso Somente leitura basta.
  2. Coloque o token na variável de ambiente HOLARCH_API_KEY (em CI: um secret).
  3. 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

  1. Execute holarch format models/. Cada arquivo alterado é listado como "reformatted <file>".
  2. 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.
  3. 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

  1. Adicione o token de API como um secret do repositório chamado HOLARCH_API_KEY (Settings → Secrets and variables → Actions).
  2. 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
  1. 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 --check para 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

  1. Crie a demonstração: em Gerenciar projetos, clique em Arquivos do projeto ▾ → Novo projeto de demonstração → Hybrid Car (SysML v2).
  2. 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 models do seu repositório.
  3. Execute holarch check models. O resultado é "6 files checked: 0 errors, 0 warnings."
  4. Em requirements.sysml, altere attribute maxCurbMass : MassValue para MassValu e execute a checagem de novo. Ela relata requirements.sysml:14:27: error name.unresolved: “MassValu” is not defined here. e sai com 1.
  5. Desfaça a alteração. Execute holarch format models uma vez e faça commit dos arquivos, para que as execuções posteriores de format --check passem.
  6. 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

ComandoO 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 whoamiMostra o que o token ou o arquivo de licença permite
holarch versionImprime 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çãoSignificado
--format human|json|sarif|githubO relatório na saída padrão (padrão human)
--output FILEGrava esse relatório em um arquivo
--sarif FILEGrava também um relatório SARIF 2.1.0
--json FILEGrava também um relatório JSON
--warnings-as-errorsSai com 1 também em caso de avisos

Opções de format

OpçãoSignificado
--checkNão altera nada; sai com 1 quando um arquivo mudaria
--diffNão altera nada; imprime as mudanças como diff unificado
--stdoutImprime o texto formatado de um arquivo em vez de gravá-lo

Opções de export

OpçãoSignificado
-o FILE, --output FILEGrava em um arquivo (padrão: saída padrão)
--holarch-fieldsAcrescenta os campos que só o Holarch lê, para uma ida e volta exata
--forceExporta um modelo com erros (nunca um com erros de sintaxe)

Opções de todo comando que faz login

OpçãoVariável de ambienteSignificado
--api-key KEYHOLARCH_API_KEYUm token de API (hol_…); prefira a variável, para que o token fique fora dos logs
--license FILEHOLARCH_LICENSE_FILEUm arquivo de licença para uso offline
--server URLHOLARCH_SERVERO servidor Holarch que checa o token (um endereço https)
--timeout SECONDSLimite 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_DIR o 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 exemplo holarch-engine.key, e aponte --license ou HOLARCH_LICENSE_FILE para 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.

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:

CampoSignificado
tool, version, engineholarch, a versão da ferramenta, a versão do motor
filesOs arquivos checados, como caminhos relativos à pasta em que a ferramenta foi executada
summaryerrors, warnings, notes, files
diagnosticsfile, line, column, endLine, endColumn (a partir de 1), severity (error, warning, info), code, message, args
skippedArquivos não checados, com o motivo (arquivos KerML com um motor mais antigo)
excludedArquivos 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ódigoSignificado
0Nenhum erro (format: nada mais a alterar)
1O 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
2Uso incorreto: uma opção desconhecida, um caminho que não existe, nenhum arquivo de modelo
3Sem 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
4O motor não consegue ser executado, ou recusou o modelo por ser grande demais ou lento demais para checar

Mensagens

MensagemSignificado
"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 --timeout segundos (padrão 60).
  • Os nomes são resolvidos entre arquivos da mesma linguagem: um arquivo .sysml não vê nomes declarados em um arquivo .kerml.