SysML v2
Инструмент командной строки holarch
Проверка, форматирование и экспорт моделей SysML v2 в сборках и CI с помощью инструмента командной строки holarch и Holarch Language Engine; GitHub Actions и другие системы CI, отчёты JSON и SARIF, коды выхода, вход с токеном API или файлом лицензии.
На этой странице
Обзор
holarch — инструмент командной строки, который проверяет текстовые файлы SysML v2 с помощью Holarch Language Engine — того же движка, который использует редактор Holarch. Запускайте его на своём компьютере или в сборке: он читает каждый файл .sysml в папке, сообщает о проблемах с файлом, строкой и столбцом и завершается с ненулевым кодом, если в модели есть ошибки, так что запрос на слияние со сломанной моделью не проходит проверки.
Инструмент делает три вещи:
- Проверка: синтаксис, имена, типы, специализации, кратности, единицы и другие правила движка по всем файлам модели. Отчёты в виде текста, JSON, SARIF (для сканирования кода) или аннотаций GitHub.
- Форматирование: переписывает файлы в одном каноническом макете (отступ в четыре пробела, один элемент на строку, каноническая расстановка пробелов), сохраняя все комментарии.
- Экспорт: записывает модель как JSON SysML v2 — формат обмена Systems Modeling API.
Инструмент входит в тарифы Individual и Team (включая пробный период), лицензию Holarch Language Engine и лицензию самостоятельно размещаемой редакции. Ему не нужен проект Holarch: он работает с файлами в вашем репозитории.
Понятия
- Модель: все файлы
.sysmlв указанных вами папках (по умолчанию — в текущей папке), прочитанные как одна модель. Имя, объявленное в одном файле, разрешается в других, как пакеты в проекте Holarch. Папки, имена которых начинаются с точки (например,.git), пропускаются. - Файлы KerML: файлы
.kermlпроверяются как KerML версиями движка, которые читают KerML. Более старые версии движка указывают их как пропущенные, что не является ошибкой. - Диагностика: у каждой проблемы есть код (например,
name.unresolved), серьёзность (ошибка, предупреждение или примечание), позиция и сообщение теми же словами, что и в редакторе Holarch. Проверку проваливают только ошибки, если вы не добавите--warnings-as-errors. - Вход: раз в день инструмент проверяет, что ваш токен API относится к тарифу Individual или Team, либо читает файл лицензии вообще без доступа к сети. См. Вход для инструмента.
- Движок: инструмент содержит скомпилированный Holarch Language Engine и стандартную библиотеку SysML v2.
holarch versionвыводит их версии и уведомление об авторских правах движка.
Как использовать
Когда и зачем
Используйте инструмент там, где текст SysML v2 хранится в репозитории исходного кода: проектировщики редактируют файлы .sysml в выбранном ими редакторе, и каждое изменение проверяется до слияния. На каждом коммите он отвечает на вопрос “модель всё ещё согласована?”, как компилятор для кода. Используйте редактор Holarch для моделирования, диаграмм и рецензирования, а инструмент — для защиты файлов между правками. Чтобы переносить модель между репозиторием и проектом Holarch, используйте Импорт и экспорт.
Установка
- Установите Python 3.9 или новее.
- Установите инструмент для своей системы (Linux x86-64, Linux arm64 или macOS на Apple silicon) с помощью pip:
python3 -m pip install holarch-cli
- Проверьте установку:
holarch versionвыводит версии инструмента, движка и библиотеки.
Вход с токеном API
- В Holarch откройте Настройки учётной записи → Токены API и создайте токен. Доступа Только чтение достаточно.
- Поместите токен в переменную окружения
HOLARCH_API_KEY(в CI — как секрет). - Выполните
holarch whoami. Команда выводит ваш тариф и учётную запись, например"plan": "team".
Проверка модели
holarch check models/
Каждая проблема — одна строка, затем сводка:
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.
Код выхода — 1, если в модели есть ошибки, и 0 в остальных случаях. Добавьте --warnings-as-errors, чтобы проверка проваливалась и на предупреждениях.
Форматирование файлов
- Выполните
holarch format models/. Каждый изменённый файл выводится как “reformatted <file>”. - Чтобы проверить макет в CI, не меняя файлы, выполните
holarch format --check models/. Команда выводит “would reformat <file>” и завершается с кодом 1, если файл изменился бы. - Чтобы сначала увидеть изменения, выполните
holarch format --diff models/.
Файл с синтаксическими ошибками не форматируется (“not formatted: the file has syntax errors.”). Комментарии остаются на своих местах: заметки перед элементом остаются над ним, заметка в конце строки остаётся в конце этой строки.
Экспорт модели в JSON SysML v2
holarch export models/ -o model.json
Файл содержит стандартный массив элементов Systems Modeling API. Одни и те же файлы всегда дают одинаковый JSON, поэтому экспорт можно фиксировать в репозитории и сравнивать. Модель с ошибками не экспортируется (“The model has errors, so it was not exported.”); добавьте --force, чтобы всё равно её экспортировать. Добавьте --holarch-fields, чтобы сохранить то, что читает только Holarch (порядок элементов, написание), для точного импорта в проект Holarch.
Запуск в GitHub Actions
- Добавьте токен API как секрет репозитория с именем
HOLARCH_API_KEY(Settings → Secrets and variables → Actions). - Добавьте файл рабочего процесса, например
.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
- Отправьте изменения (push). Проблемы появляются как аннотации на изменённых строках запроса на слияние, а задание проваливается, если в модели есть ошибки или файл не в каноническом макете. Уберите шаг
holarch format --check, чтобы проверять только модель.
Последний шаг загружает отчёт SARIF в сканирование кода, где проблемы перечисляются в разделе Security → Code scanning. Уберите его, если ваш репозиторий не использует сканирование кода: аннотации работают и без него.
Запуск в других системах CI
Любая система CI с Python 3.9 или новее выполняет те же команды. Установите инструмент, задайте токен из секрета, выполните проверку:
python3 -m pip install holarch-cli
holarch check models/ --sarif holarch.sarif --json holarch.json
Например, GitLab CI (.gitlab-ci.yml, с HOLARCH_API_KEY в виде маскированной переменной CI/CD):
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 и другие работают так же: один шаг устанавливает инструмент, следующий выполняет holarch check; ненулевой код выхода проваливает сборку. Сохраняйте отчёт JSON (--json) как артефакт сборки, если хотите видеть цифры на панели мониторинга.
Разобранный пример: демо-проект Hybrid Car
- Создайте демо-проект: на странице Управление проектами нажмите Файлы проектов ▾ → Новый демо-проект → Hybrid Car (SysML v2).
- Откройте Модель → Импорт и экспорт. В разделе Экспорт выберите Вся модель и Текст SysML v2, нажмите Экспорт и распакуйте скачанный файл в папку
modelsвашего репозитория. - Выполните
holarch check models. Результат: “6 files checked: 0 errors, 0 warnings.” - В
requirements.sysmlзаменитеattribute maxCurbMass : MassValueнаMassValuи снова выполните проверку. Она сообщаетrequirements.sysml:14:27: error name.unresolved: “MassValu” is not defined here.и завершается с кодом 1. - Отмените изменение. Один раз выполните
holarch format modelsи зафиксируйте файлы в репозитории, чтобы последующие запускиformat --checkпроходили. - Добавьте рабочий процесс GitHub, приведённый выше. Каждый последующий запрос на слияние, ломающий модель, не пройдёт проверку.
Советы и рекомендации
- Держите содержимое каждого файла в пакете. Элементы вне пакетов работают, но пакет на файл сохраняет уникальность имён между файлами.
- Используйте для CI токен только для чтения, не привязанный ни к одному проекту: инструменту не нужен доступ к проектам.
- Один раз отформатируйте файлы и зафиксируйте результат, прежде чем включать
format-check, иначе первый запуск провалится на каждом файле. - Закрепите версию инструмента в CI (
holarch-cli==<version>), чтобы новый выпуск движка не изменил результаты посреди рецензирования. - Исполнители без доступа к интернету используют файл лицензии вместо токена.
Типичные ошибки
- “No .sysml or .kerml files found”: путь неверен или файлы находятся в папке, имя которой начинается с точки.
- Имена не разрешаются только в одном файле: файл объявляет имена, которые использует другой файл, а в том другом файле есть синтаксическая ошибка. Сначала исправьте синтаксическую ошибку; отчёт сообщает, какие файлы были пропущены.
- Задание завершается с кодом выхода 3: токен отсутствует, неверен или принадлежит учётной записи на тарифе Free. Сообщение указывает, что именно.
Связь с другими функциями
- Проверки те же, что у текста SysML v2 в редакторе Holarch и у Проверки модели для проектов SysML v2, с теми же сообщениями (Текстовый редактор SysML v2).
- Файлы, экспортированные из проекта (Импорт и экспорт), проходят проверку без замечаний; JSON, экспортированный инструментом, импортируется в проект.
- Для изменений, которые должны пройти рецензирование в Holarch, а не через файлы, используйте API или клиент Python, изменения которых поступают как предложения.
Команды
| Команда | Что он делает |
|---|---|
holarch check [paths] | Проверяет модель; сообщает о проблемах; при ошибках код выхода 1 |
holarch format [paths] | Переписывает файлы в каноническом макете |
holarch export [paths] | Записывает модель как JSON SysML v2 |
holarch whoami | Показывает, что разрешает токен или файл лицензии |
holarch version | Выводит версии инструмента, движка и библиотеки и уведомление об авторских правах движка (вход не нужен) |
Пути — это файлы или папки; по умолчанию — текущая папка. Поиск в папках идёт вместе с их подпапками.
Параметры check
| Параметр | Значение |
|---|---|
--format human|json|sarif|github | Отчёт в стандартный вывод (по умолчанию human) |
--output FILE | Записать этот отчёт в файл |
--sarif FILE | Дополнительно записать отчёт SARIF 2.1.0 |
--json FILE | Дополнительно записать отчёт JSON |
--warnings-as-errors | Код выхода 1 и при предупреждениях |
Параметры format
| Параметр | Значение |
|---|---|
--check | Ничего не менять; код выхода 1, если файл изменился бы |
--diff | Ничего не менять; вывести изменения в виде унифицированного diff |
--stdout | Вывести отформатированный текст одного файла вместо его записи |
Параметры export
| Параметр | Значение |
|---|---|
-o FILE, --output FILE | Записать в файл (по умолчанию: стандартный вывод) |
--holarch-fields | Добавить поля, которые читает только Holarch, для точного обмена туда и обратно |
--force | Экспортировать модель с ошибками (но никогда — с синтаксическими ошибками) |
Параметры всех команд, выполняющих вход
| Параметр | Переменная окружения | Значение |
|---|---|---|
--api-key KEY | HOLARCH_API_KEY | Токен API (hol_…); лучше использовать переменную, чтобы токен не попадал в журналы |
--license FILE | HOLARCH_LICENSE_FILE | Файл лицензии для работы офлайн |
--server URL | HOLARCH_SERVER | Сервер Holarch, который проверяет токен (https-адрес) |
--timeout SECONDS | Ограничение времени для каждого шага движка (по умолчанию 60) |
Вход для инструмента
Инструмент работает, если есть одно из следующего:
- Токен API тарифа Individual или Team, включая пробный период Individual. Инструмент один раз обращается к серверу и хранит ответ сутки в файле кэша (
~/.cache/holarch/entitlement.json;HOLARCH_CACHE_DIRперемещает его). Кэш содержит тариф и адрес электронной почты учётной записи, но никогда не токен. Если сервер недоступен, ответ давностью до 7 дней по-прежнему засчитывается, с примечанием. - Файл лицензии — для лицензиатов Holarch Language Engine, клиентов самостоятельно размещаемой редакции и исполнителей без доступа к интернету. Инструмент сам проверяет подпись файла и никогда не подключается к серверу. Каждая действующая лицензия включает инструмент без дополнительной платы:
- Лицензия Holarch Language Engine: сохраните лицензионный ключ из поставки движка (текст, начинающийся с
l1.) в файл, напримерholarch-engine.key, и укажите его в--licenseилиHOLARCH_LICENSE_FILE. Разрывы строк, добавленные почтовой программой, не имеют значения. Лицензированные веб-адреса и серверное использование ключа относятся к движку в вашем продукте, а не к инструменту. В течение 14 дней после даты окончания ключа инструмент продолжает работать и выводит напоминание. - Лицензия самостоятельно размещаемой редакции: используйте файл лицензии вашего сервера Holarch как есть. В последние 30 дней её действия инструмент выводит напоминание. В течение 30 дней после даты окончания (льготный период лицензии) инструмент продолжает работать и выводит число оставшихся дней; после этого он перестаёт работать до установки продлённой лицензии.
- Лицензия Holarch Language Engine: сохраните лицензионный ключ из поставки движка (текст, начинающийся с
Ключ движка, у которого истекли и эти 14 дней, также останавливает инструмент до установки продлённого ключа.
Токен учётной записи на тарифе Free отклоняется, даже если у учётной записи остаётся доступ к API благодаря академическому адресу электронной почты. Пробный период Individual включает инструмент.
Файлы лицензий в CI
Храните лицензию как секрет, никогда не в репозитории. В CI записывайте секрет в файл за пределами рабочей копии (в GitHub Actions — в $RUNNER_TEMP) и задайте в HOLARCH_LICENSE_FILE путь к нему.
Отчёты
Вывод JSON
--format json и --json FILE записывают:
| Поле | Значение |
|---|---|
tool, version, engine | holarch, версия инструмента, версия движка |
files | Проверенные файлы в виде путей относительно папки, в которой запускался инструмент |
summary | errors, warnings, notes, files |
diagnostics | file, line, column, endLine, endColumn (с отсчётом от 1), severity (error, warning, info), code, message, args |
skipped | Непроверенные файлы с причиной (файлы KerML при более старом движке) |
excluded | Файлы с синтаксическими ошибками, исключённые из проверок между файлами |
Столбцы отсчитываются в символах Unicode (кодовых точках).
SARIF
--format sarif и --sarif FILE записывают SARIF 2.1.0 с одним правилом на каждый код диагностики, серьёзностью error, warning или note и путями относительно папки, в которой запускался инструмент. Запускайте инструмент в корне репозитория, чтобы сканирование кода нашло файлы.
Аннотации GitHub
--format github выводит по одной команде рабочего процесса на каждую проблему (::error file=…,line=…,col=…::message), которые GitHub Actions показывает как аннотации, а затем строку сводки.
Коды выхода
| Код | Значение |
|---|---|
| 0 | Ошибок нет (format: менять больше нечего) |
| 1 | В модели есть ошибки; format --check или --diff: файл изменился бы или файл не удалось отформатировать; export: отказ из-за ошибок |
| 2 | Неверное использование: неизвестный параметр, несуществующий путь, нет файлов модели |
| 3 | Вход не выполнен или нет права: нет токена или файла лицензии, токен отклонён, тариф Free, файл лицензии недействителен, изменён или просрочен |
| 4 | Движок не может запуститься или отклонил модель как слишком большую или слишком медленную для проверки |
Сообщения
| Сообщение | Значение |
|---|---|
| “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).” | Не задан ни токен, ни файл лицензии |
| “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.” | Учётная запись токена на тарифе Free |
| “The API and MCP come with the Individual and Team plans.” | Учётная запись токена на тарифе Free и к тому же не имеет доступа к API |
| “The API token is not valid: it is wrong, revoked or expired, or its account cannot sign in.” | Создайте новый токен |
| “The license file's signature does not verify. Use the file exactly as it was delivered.” | Файл лицензии был изменён или повреждён |
| “License <id> expired on <date>. Install a renewed license file.” | Лицензия самостоятельно размещаемой редакции закончилась более 30 дней назад или лицензионный ключ движка — более 14 дней назад |
| “The engine license key's signature does not verify. Use the key exactly as it was delivered.” | Ключ в файле был изменён или относится к другому продукту |
| “The engine license key is not complete. Copy the whole key (l1.….…) into the file.” | Часть ключа отсутствует |
| “… cannot be reached to check the API token” | Нет подключения и нет свежего ответа в кэше; повторите попытку или используйте файл лицензии |
| “<file>: not formatted: the file has syntax errors.” | Выполните holarch check, чтобы их увидеть |
| “<file>: not formatted: a comment could not be kept in place.” | Файл остаётся без изменений; инструмент никогда не удаляет комментарии |
| “The model has errors, so it was not exported.” | Исправьте ошибки или добавьте --force |
| “The installed engine does not carry the Holarch Language Engine copyright notice, so it is not a genuine Holarch build.” | Переустановите инструмент |
Ограничения
- Не более 8 МБ текста SysML на язык в одной модели и строки до 64 КБ, как в редакторе.
- Не более 10 000 файлов за один запуск.
- Каждый шаг движка останавливается через
--timeoutсекунд (по умолчанию 60). - Имена разрешаются между файлами одного языка: файл
.sysmlне видит имён, объявленных в файле.kerml.