Holarch

SysML v2

holarch コマンドラインツール

holarch コマンドラインツールと Holarch Language Engine を使って、ビルドや CI で SysML v2 モデルをチェック、整形、エクスポートします。GitHub Actions やその他の CI システム、JSON と SARIF のレポート、終了コード、API トークンまたはライセンスファイルによるサインインについて説明します。

使い方 →

このページの内容
  1. 概要
  2. 概念
  3. 使い方
    1. 使う場面と理由
    2. インストール
    3. API トークンでサインインする
    4. モデルをチェックする
    5. ファイルを整形する
    6. モデルを SysML v2 JSON としてエクスポートする
    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 は、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 プロジェクトの間でモデルを移すには、インポートとエクスポートを使います。

インストール

  1. Python 3.9 以降をインストールします。
  2. pip を使って、お使いのシステム(Linux x86-64、Linux arm64、または Apple シリコンの macOS)用のツールをインストールします:
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/

各問題は 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 を追加します。

ファイルを整形する

  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.」)。コメントは元の位置に残ります。要素の前のメモはその上に、行末のメモはその行の末尾に残ります。

モデルを 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 で実行する

  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. プッシュします。問題はプルリクエストの変更された行にアノテーションとして表示され、モデルにエラーがある場合やファイルが標準レイアウトでない場合はジョブが失敗します。モデルだけをチェックするには、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 デモ

  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 ワークフローを追加します。以降、モデルを壊すプルリクエストはすべてチェックに失敗します。

ヒントとよい進め方

  • 各ファイルの内容はパッケージに入れます。どのパッケージにも属さない要素も動作しますが、ファイルごとに 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 FILESARIF 2.1.0 のレポートも書き出します
--json FILEJSON のレポートも書き出します
--warnings-as-errors警告でも 1 で終了します

format のオプション

オプション意味
--check何も変更しません。ファイルが変更される場合は 1 で終了します
--diff何も変更しません。変更内容を unified diff として出力します
--stdout1 つのファイルを書き込む代わりに、整形したテキストを出力します

export のオプション

オプション意味
-o FILE, --output FILEファイルに書き出します(既定:標準出力)
--holarch-fields正確な往復変換のために、Holarch だけが読み取るフィールドを追加します
--forceエラーのあるモデルをエクスポートします(構文エラーのあるものは決してエクスポートしません)

サインインするすべてのコマンドのオプション

オプション環境変数意味
--api-key KEYHOLARCH_API_KEYAPI トークン(hol_…)。トークンがログに残らないように、変数を使うことをお勧めします
--license FILEHOLARCH_LICENSE_FILEオフラインで使うためのライセンスファイル
--server URLHOLARCH_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 日間(ライセンスの猶予期間)は、ツールは動作を続け、残りの日数を出力します。その後は、更新されたライセンスがインストールされるまで停止します。

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 は、診断コードごとに 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 ファイルで宣言された名前は見えません。