SysML v2
Інструмент командного рядка holarch
Перевіряйте, форматуйте та експортуйте моделі SysML v2 у збірках і CI за допомогою інструмента командного рядка holarch і Holarch Language Engine; GitHub Actions та інші системи CI, звіти JSON і SARIF, коди виходу, вхід з токеном API або файлом ліцензії.
На цій сторінці
Огляд
holarch — це інструмент командного рядка, який перевіряє текстові файли SysML v2 за допомогою Holarch Language Engine — того самого рушія, що його використовує редактор Holarch. Запускайте його на власному комп’ютері або у збірці: він читає кожен файл .sysml у теці, повідомляє про проблеми з файлом, рядком і стовпцем і завершується з ненульовим кодом, коли модель має помилки, тож pull request зі зламаною моделлю не проходить перевірки.
Інструмент робить три речі:
- Перевірка: синтаксис, імена, типи, спеціалізації, кратності, одиниці та інші правила рушія в усіх файлах моделі. Звіти — у вигляді тексту, JSON, SARIF (для сканування коду) або анотацій GitHub.
- Форматування: переписує файли в одному канонічному розміщенні (відступ у чотири пробіли, один елемент на рядок, канонічні проміжки), зберігаючи кожен коментар.
- Експорт: записує модель як SysML v2 JSON — формат обміну 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."). Коментарі лишаються на місці: нотатки перед елементом лишаються над ним, нотатка в кінці рядка лишається в кінці цього рядка.
Експорт моделі як SysML v2 JSON
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. Проблеми з’являються як анотації на змінених рядках pull request, а завдання завершується помилкою, коли модель має помилки або файл не в канонічному розміщенні. Пропустіть крок
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, наведений вище. Кожен наступний pull request, що ламає модель, не пройде перевірку.
Поради та добрі практики
- Тримайте вміст кожного файлу в пакеті. Елементи поза будь-яким пакетом працюють, але пакет на файл зберігає унікальність імен між файлами.
- Використовуйте для 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] | Записує модель як SysML v2 JSON |
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)." (Інструменту командного рядка holarch потрібен токен API Holarch тарифу Individual або Team чи файл ліцензії Holarch Language Engine.) | Не задано ні токена, ні файлу ліцензії |
| "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." (Інструмент входить до тарифів Individual і Team; виберіть тариф у Налаштування облікового запису → Тариф і оплата або використайте файл ліцензії.) | Обліковий запис токена на тарифі Free |
| "The API and MCP come with the Individual and Team plans." (API і MCP входять до тарифів Individual і Team.) | Обліковий запис токена на тарифі Free і не має також доступу до API |
| "The API token is not valid: it is wrong, revoked or expired, or its account cannot sign in." (Токен API недійсний.) | Створіть новий токен |
| "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" (… недоступний для перевірки токена API) | Немає з’єднання й немає свіжої відповіді в кеші; спробуйте знову або використайте файл ліцензії |
| "<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." (Встановлений рушій не є справжньою збіркою Holarch.) | Перевстановіть інструмент |
Обмеження
- Не більше 8 MB тексту SysML на мову в одній моделі й рядки до 64 KB, як у редакторі.
- Не більше 10,000 файлів за один запуск.
- Кожен крок рушія зупиняється через
--timeoutсекунд (за замовчуванням 60). - Імена розв’язуються між файлами тієї самої мови: файл
.sysmlне бачить імен, оголошених у файлі.kerml.