Holarch

SysML v2

Инструмент командной строки holarch

Проверка, форматирование и экспорт моделей SysML v2 в сборках и CI с помощью инструмента командной строки holarch и Holarch Language Engine; GitHub Actions и другие системы CI, отчёты JSON и SARIF, коды выхода, вход с токеном API или файлом лицензии.

Как использовать →

На этой странице
  1. Обзор
  2. Понятия
  3. Как использовать
    1. Когда и зачем
    2. Установка
    3. Вход с токеном API
    4. Проверка модели
    5. Форматирование файлов
    6. Экспорт модели в JSON SysML v2
    7. Запуск в GitHub Actions
    8. Запуск в других системах CI
    9. Разобранный пример: демо-проект Hybrid Car
    10. Советы и рекомендации
    11. Типичные ошибки
    12. Связь с другими функциями
  4. Команды
    1. Параметры check
    2. Параметры format
    3. Параметры export
    4. Параметры всех команд, выполняющих вход
  5. Вход для инструмента
    1. Файлы лицензий в CI
  6. Отчёты
    1. Вывод JSON
    2. SARIF
    3. Аннотации GitHub
  7. Коды выхода
  8. Сообщения
  9. Ограничения
  10. Связанные страницы

Обзор

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, используйте Импорт и экспорт.

Установка

  1. Установите Python 3.9 или новее.
  2. Установите инструмент для своей системы (Linux x86-64, Linux arm64 или macOS на Apple silicon) с помощью pip:
python3 -m pip install holarch-cli
  1. Проверьте установку: holarch version выводит версии инструмента, движка и библиотеки.

Вход с токеном API

  1. В Holarch откройте Настройки учётной записи → Токены API и создайте токен. Доступа Только чтение достаточно.
  2. Поместите токен в переменную окружения HOLARCH_API_KEY (в CI — как секрет).
  3. Выполните 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, чтобы проверка проваливалась и на предупреждениях.

Форматирование файлов

  1. Выполните holarch format models/. Каждый изменённый файл выводится как “reformatted <file>”.
  2. Чтобы проверить макет в CI, не меняя файлы, выполните holarch format --check models/. Команда выводит “would reformat <file>” и завершается с кодом 1, если файл изменился бы.
  3. Чтобы сначала увидеть изменения, выполните 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

  1. Добавьте токен API как секрет репозитория с именем HOLARCH_API_KEY (Settings → Secrets and variables → Actions).
  2. Добавьте файл рабочего процесса, например .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. Отправьте изменения (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

  1. Создайте демо-проект: на странице Управление проектами нажмите Файлы проектов ▾ → Новый демо-проект → Hybrid Car (SysML v2).
  2. Откройте Модель → Импорт и экспорт. В разделе Экспорт выберите Вся модель и Текст SysML v2, нажмите Экспорт и распакуйте скачанный файл в папку models вашего репозитория.
  3. Выполните holarch check models. Результат: “6 files checked: 0 errors, 0 warnings.”
  4. В requirements.sysml замените attribute maxCurbMass : MassValue на MassValu и снова выполните проверку. Она сообщает requirements.sysml:14:27: error name.unresolved: “MassValu” is not defined here. и завершается с кодом 1.
  5. Отмените изменение. Один раз выполните holarch format models и зафиксируйте файлы в репозитории, чтобы последующие запуски format --check проходили.
  6. Добавьте рабочий процесс 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 KEYHOLARCH_API_KEYТокен API (hol_…); лучше использовать переменную, чтобы токен не попадал в журналы
--license FILEHOLARCH_LICENSE_FILEФайл лицензии для работы офлайн
--server URLHOLARCH_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 дней после даты окончания (льготный период лицензии) инструмент продолжает работать и выводит число оставшихся дней; после этого он перестаёт работать до установки продлённой лицензии.

Ключ движка, у которого истекли и эти 14 дней, также останавливает инструмент до установки продлённого ключа.

Токен учётной записи на тарифе Free отклоняется, даже если у учётной записи остаётся доступ к API благодаря академическому адресу электронной почты. Пробный период Individual включает инструмент.

Файлы лицензий в CI

Храните лицензию как секрет, никогда не в репозитории. В CI записывайте секрет в файл за пределами рабочей копии (в GitHub Actions — в $RUNNER_TEMP) и задайте в HOLARCH_LICENSE_FILE путь к нему.

Отчёты

Вывод JSON

--format json и --json FILE записывают:

ПолеЗначение
tool, version, engineholarch, версия инструмента, версия движка
filesПроверенные файлы в виде путей относительно папки, в которой запускался инструмент
summaryerrors, warnings, notes, files
diagnosticsfile, 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.