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이 아닌 코드로 종료하므로 모델이 깨진 풀 리퀘스트는 검사에 실패합니다.
도구는 세 가지 일을 합니다.
- 검사: 모델의 모든 파일에 걸친 구문, 이름, 유형, 특수화, 다중성, 단위 및 엔진의 기타 규칙. 텍스트, JSON, SARIF(코드 스캐닝용) 또는 GitHub 주석으로 보고합니다.
- 서식 지정: 모든 주석을 유지하면서 파일을 하나의 표준 레이아웃(4칸 들여쓰기, 줄마다 요소 하나, 표준 간격)으로 다시 씁니다.
- 내보내기: 모델을 Systems Modeling API의 교환 형식인 SysML v2 JSON으로 기록합니다.
이 도구는 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 이상을 설치합니다.
- pip로 시스템(Linux x86-64, Linux arm64 또는 Apple silicon의 macOS)에 맞는 도구를 설치합니다.
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 프로젝트로 정확히 가져오기 위해 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 등도 같은 방식으로 작동합니다. 한 단계에서 도구를 설치하고, 다음 단계에서 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 워크플로를 추가합니다. 이후 모델을 깨뜨리는 모든 풀 리퀘스트는 검사에 실패합니다.
팁과 모범 사례
- 각 파일의 내용은 패키지 안에 둡니다. 패키지 밖의 요소도 작동하지만, 파일마다 패키지를 두면 파일 간에 이름이 고유하게 유지됩니다.
- CI에는 프로젝트가 없도록 제한된 읽기 전용 토큰을 사용합니다. 도구에는 프로젝트 액세스가 필요하지 않습니다.
format-check를 켜기 전에 한 번 서식을 지정하고 결과를 커밋합니다. 그렇지 않으면 첫 실행이 모든 파일에서 실패합니다.- 새 엔진 릴리스가 검토 도중 결과를 바꾸지 않도록 CI에서 도구 버전을 고정합니다(
holarch-cli==<version>). - 인터넷 액세스가 없는 러너는 토큰 대신 라이선스 파일을 사용합니다.
흔한 실수
- "No .sysml or .kerml files found": 경로가 잘못되었거나, 파일이 이름이 점으로 시작하는 폴더에 있습니다.
- 한 파일에서만 이름이 확인되지 않음: 그 파일이 다른 파일에 선언된 이름을 사용하는데, 그 다른 파일에 구문 오류가 있습니다. 먼저 구문 오류를 고칩니다. 보고서에 제외된 파일이 표시됩니다.
- 작업이 종료 코드 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 | 파일 하나의 서식 지정된 텍스트를 기록하지 않고 출력 |
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로 위치 변경)에 보관합니다. 캐시에는 요금제와 계정 이메일이 들어 있으며, 토큰은 절대 들어 있지 않습니다. 서버에 연결할 수 없으면 최대 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 | 구문 오류가 있어 파일 간 검사에서 제외된 파일 |
열은 유니코드 문자(코드 포인트) 단위로 셉니다.
SARIF
--format sarif와 --sarif FILE은 진단 코드마다 규칙 하나, error, warning 또는 note로 된 심각도, 도구를 실행한 폴더 기준 상대 경로가 있는 SARIF 2.1.0을 기록합니다. 코드 스캐닝이 파일을 찾을 수 있도록 저장소 루트에서 도구를 실행합니다.
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 명령줄 도구에는 Individual 또는 Team 요금제의 Holarch API 토큰 또는 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."(holarch 명령줄 도구는 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 Language Engine 저작권 고지가 없으므로 정품 Holarch 빌드가 아닙니다.) | 도구를 다시 설치합니다 |
제한 사항
- 편집기와 마찬가지로 모델 하나에서 언어마다 SysML 텍스트 최대 8 MB, 줄 길이 최대 64 KB.
- 한 번 실행에 최대 10,000개 파일.
- 각 엔진 단계는
--timeout초(기본값 60) 후에 중지됩니다. - 이름은 같은 언어의 파일 간에 확인됩니다.
.sysml파일은.kerml파일에 선언된 이름을 보지 못합니다.