SysML v2
holarch コマンドラインツール
holarch コマンドラインツールと Holarch Language Engine を使って、ビルドや CI で SysML v2 モデルをチェック、整形、エクスポートします。GitHub Actions やその他の CI システム、JSON と SARIF のレポート、終了コード、API トークンまたはライセンスファイルによるサインインについて説明します。
このページの内容
概要
holarch は、Holarch エディターと同じエンジンである Holarch Language Engine で SysML v2 テキストファイルをチェックするコマンドラインツールです。自分のコンピューターやビルドで実行します。フォルダー内のすべての .sysml ファイルを読み取り、ファイル、行、列とともに問題を報告し、モデルにエラーがある場合は 0 以外のコードで終了します。そのため、壊れたモデルを含むプルリクエストはチェックに失敗します。
このツールは 3 つのことを行います:
- チェック:モデルのすべてのファイルにわたって、構文、名前、型、特化、多重度、単位、その他のエンジンのルールをチェックします。テキスト、JSON、SARIF(コードスキャン用)、または GitHub のアノテーションとして報告します。
- 整形:すべてのコメントを残したまま、ファイルを 1 つの標準レイアウト(4 スペースのインデント、1 行に 1 要素、標準の空白)に書き直します。
- エクスポート:モデルを、Systems Modeling API の交換形式である SysML v2 JSON として書き出します。
このツールは、Individual プランと Team プラン(試用版を含む)、Holarch Language Engine のライセンス、セルフホスト版のライセンスに付属します。Holarch プロジェクトは必要ありません。リポジトリ内のファイルの上で動作します。
概念
- モデル:指定したフォルダー(既定:現在のフォルダー)の下にあるすべての
.sysmlファイルを、1 つのモデルとして読み取ります。Holarch プロジェクトでパッケージがそうであるように、あるファイルで宣言された名前は他のファイルで解決されます。名前がドットで始まるフォルダー(.gitなど)はスキップされます。 - KerML ファイル:
.kermlファイルは、KerML を読み取れるエンジンのバージョンでは KerML としてチェックされます。古いエンジンのバージョンでは、スキップされたものとして一覧表示されます。これはエラーではありません。 - 診断:各問題には、コード(例:
name.unresolved)、重大度(error、warning、note)、位置、Holarch エディターと同じ文言のメッセージがあります。--warnings-as-errorsを追加しない限り、チェックを失敗させるのはエラーだけです。 - サインイン:ツールは 1 日 1 回、API トークンが Individual プランまたは Team プランに属していることをチェックするか、ネットワークにアクセスせずにライセンスファイルを読み取ります。ツールのサインインを参照してください。
- エンジン:ツールには、コンパイル済みの Holarch Language Engine と SysML v2 標準ライブラリが含まれています。
holarch versionは、それらのバージョンとエンジンの著作権表示を出力します。
使い方
使う場面と理由
SysML v2 テキストがソースリポジトリにある場合にこのツールを使います。設計者は好きなエディターで .sysml ファイルを編集し、すべての変更はマージされる前にチェックされます。コンパイラーがコードに対して行うように、コミットのたびに「このモデルはまだ整合しているか」に答えます。モデリング、ダイアグラム、レビューには Holarch エディターを使い、編集の合間のファイルを守るにはこのツールを使います。リポジトリと Holarch プロジェクトの間でモデルを移すには、インポートとエクスポートを使います。
インストール
- Python 3.9 以降をインストールします。
- pip を使って、お使いのシステム(Linux x86-64、Linux arm64、または Apple シリコンの macOS)用のツールをインストールします:
python3 -m pip install holarch-cli
- インストールを確認します:
holarch versionは、ツール、エンジン、ライブラリのバージョンを出力します。
API トークンでサインインする
- Holarch でアカウント設定 → API トークンを開き、トークンを作成します。読み取り専用のアクセス権で十分です。
- トークンを
HOLARCH_API_KEY環境変数に設定します(CI ではシークレット)。 holarch whoamiを実行します。プランとアカウントが出力されます(例:"plan": "team")。
モデルをチェックする
holarch check models/
各問題は 1 行で、その後に概要が続きます:
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 プロジェクトに正確にインポートするために、Holarch だけが読み取るもの(要素の順序、表記)を残すには --holarch-fields を追加します。
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
- プッシュします。問題はプルリクエストの変更された行にアノテーションとして表示され、モデルにエラーがある場合やファイルが標準レイアウトでない場合はジョブが失敗します。モデルだけをチェックするには、
holarch format --checkのステップを省きます。
最後のステップは SARIF レポートをコードスキャンにアップロードし、問題はSecurity → Code scanningの下に一覧表示されます。リポジトリでコードスキャンを使っていない場合は省きます。アノテーションはそれなしでも動作します。
その他の CI システムで実行する
Python 3.9 以降がある CI システムなら、どれでも同じコマンドを実行できます。ツールをインストールし、シークレットからトークンを設定して、チェックします:
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 なども同じように動作します。1 つのステップでツールをインストールし、次のステップで holarch check を実行します。0 以外の終了コードでビルドが失敗します。数値をダッシュボードに表示したい場合は、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 ワークフローを追加します。以降、モデルを壊すプルリクエストはすべてチェックに失敗します。
ヒントとよい進め方
- 各ファイルの内容はパッケージに入れます。どのパッケージにも属さない要素も動作しますが、ファイルごとに 1 つのパッケージにすると、ファイル間で名前が一意に保たれます。
- CI には、どのプロジェクトにも限定されない読み取り専用トークンを使います。ツールにプロジェクトへのアクセスは必要ありません。
format-checkをオンにする前に一度整形して結果をコミットします。そうしないと、最初の実行ですべてのファイルが失敗します。- 新しいエンジンのリリースによってレビューの途中で結果が変わらないように、CI ではツールのバージョンを固定します(
holarch-cli==<version>)。 - インターネットにアクセスできないランナーでは、トークンの代わりにライセンスファイルを使います。
よくある間違い
- 「No .sysml or .kerml files found」:パスが間違っているか、ファイルが名前がドットで始まるフォルダーにあります。
- 1 つのファイルでだけ名前が解決されない:そのファイルが別のファイルで宣言された名前を使っていて、その別のファイルに構文エラーがあります。まず構文エラーを修正します。レポートには、除外されたファイルが示されます。
- ジョブが終了コード 3 で失敗する:トークンがない、間違っている、または Free プランのアカウントに属しています。メッセージにどれかが示されます。
他の機能との関係
- チェックは、Holarch エディターの SysML v2 テキストと、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 | 何も変更しません。変更内容を unified diff として出力します |
--stdout | 1 つのファイルを書き込む代わりに、整形したテキストを出力します |
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) |
ツールのサインイン
ツールは、次のいずれかがある場合に動作します:
- Individual プランまたは Team プランの API トークン(Individual の試用版を含む)。ツールはサーバーに一度問い合わせ、その応答をキャッシュファイル(
~/.cache/holarch/entitlement.json。HOLARCH_CACHE_DIRで場所を変更できます)に 1 日保持します。キャッシュにはプランとアカウントのメールアドレスが保持され、トークンは決して保持されません。サーバーに接続できない場合は、7 日以内の応答であれば注記付きで引き続き有効です。 - ライセンスファイル。Holarch Language Engine のライセンシー、セルフホスト版の顧客、インターネットにアクセスできないランナー向けです。ツールはファイルの署名を自分でチェックし、サーバーには一切接続しません。すべての有効なライセンスには、追加料金なしでツールが含まれます:
- Holarch Language Engine のライセンス:エンジンの納品物にあるライセンスキー(
l1.で始まるテキスト)をファイル(例:holarch-engine.key)に保存し、--licenseまたはHOLARCH_LICENSE_FILEでそれを指定します。メールで追加された改行は問題になりません。キーのライセンス対象の Web アドレスとサーバーでの使用は、製品内のエンジンに適用されるもので、ツールには適用されません。キーの終了日から 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 は、診断コードごとに 1 つのルール、error、warning、note としての重大度、ツールを実行したフォルダーからの相対パスを持つ SARIF 2.1.0 を書き出します。コードスキャンがファイルを見つけられるように、ツールはリポジトリのルートで実行します。
GitHub のアノテーション
--format github は、問題ごとに 1 つのワークフローコマンド(::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.」 | ツールを再インストールします |
制限事項
- エディターと同じく、1 つのモデルで言語ごとに最大 8 MB の SysML テキスト、1 行は最大 64 KB。
- 1 回の実行で最大 10,000 ファイル。
- エンジンの各ステップは
--timeout秒(既定 60)で停止します。 - 名前は同じ言語のファイル間で解決されます。
.sysmlファイルからは、.kermlファイルで宣言された名前は見えません。