Holarch

SysML v2

holarch komut satırı aracı

holarch komut satırı aracı ve Holarch Language Engine ile derlemelerde ve CI'da SysML v2 modellerini denetleyin, biçimlendirin ve dışa aktarın; GitHub Actions ve diğer CI sistemleri, JSON ve SARIF raporları, çıkış kodları, API belirteci veya lisans dosyasıyla oturum açma.

Nasıl kullanılır →

Bu sayfada
  1. Genel bakış
  2. Kavramlar
  3. Nasıl kullanılır
    1. Ne zaman ve neden
    2. Kurulum
    3. Bir API belirteciyle oturum açma
    4. Bir modeli denetleme
    5. Dosyaları biçimlendirme
    6. Modeli SysML v2 JSON olarak dışa aktarma
    7. GitHub Actions'ta çalıştırma
    8. Diğer CI sistemlerinde çalıştırma
    9. Çalışılmış örnek: Hybrid Car demosu
    10. İpuçları ve iyi uygulamalar
    11. Yaygın hatalar
    12. Diğer özelliklerle nasıl bağlantılıdır
  4. Komutlar
    1. check seçenekleri
    2. format seçenekleri
    3. export seçenekleri
    4. Oturum açan her komutun seçenekleri
  5. Araç için oturum açma
    1. CI'da lisans dosyaları
  6. Raporlar
    1. JSON çıktısı
    2. SARIF
    3. GitHub ek açıklamaları
  7. Çıkış kodları
  8. İletiler
  9. Sınırlar
  10. İlgili sayfalar

Genel bakış

holarch, SysML v2 metin dosyalarını Holarch düzenleyicisinin kullandığı motorla, yani Holarch Language Engine ile denetleyen bir komut satırı aracıdır. Onu kendi bilgisayarınızda veya bir derlemede çalıştırın: bir klasördeki her .sysml dosyasını okur, sorunları dosya, satır ve sütunla bildirir ve modelde hata olduğunda sıfırdan farklı bir kodla çıkar; böylece modeli bozuk bir pull request denetimlerden geçemez.

Araç üç şey yapar:

  • Denetleme: modelin tüm dosyalarında sözdizimi, adlar, türler, özelleştirmeler, çokluklar, birimler ve motorun diğer kuralları. Metin, JSON, SARIF (kod taraması için) veya GitHub ek açıklamaları olarak raporlar.
  • Biçimlendirme: dosyaları her yorumu koruyarak tek bir standart yerleşimde (dört boşluklu girinti, satır başına bir öğe, standart aralıklar) yeniden yazar.
  • Dışa aktarma: modeli Systems Modeling API'nin değişim biçimi olan SysML v2 JSON olarak yazar.

Araç Individual ve Team planlarıyla (deneme dahil), bir Holarch Language Engine lisansıyla ve bir self-hosted sürüm lisansıyla gelir. Bir Holarch projesi gerektirmez: deponuzdaki dosyalar üzerinde çalışır.

Kavramlar

  • Model: belirttiğiniz klasörlerin (varsayılan: geçerli klasör) altındaki tüm .sysml dosyaları, tek bir model olarak okunur. Bir dosyada bildirilen ad, bir Holarch projesindeki paketlerde olduğu gibi diğer dosyalarda çözümlenir. Adı nokta ile başlayan klasörler (örneğin .git) atlanır.
  • KerML dosyaları: .kerml dosyaları, KerML okuyan motor sürümleri tarafından KerML olarak denetlenir. Eski motor sürümleri bunları atlanmış olarak listeler; bu bir hata değildir.
  • Tanılamalar: her sorunun bir kodu (örneğin name.unresolved), bir önem düzeyi (hata, uyarı veya not), bir konumu ve Holarch düzenleyicisindekiyle aynı sözcüklerle bir iletisi vardır. --warnings-as-errors eklemediğiniz sürece yalnızca hatalar bir denetimi başarısız kılar.
  • Oturum açma: araç günde bir kez API belirtecinizin bir Individual veya Team planına ait olduğunu denetler ya da hiçbir ağ erişimi olmadan bir lisans dosyasını okur. Bkz. Araç için oturum açma.
  • Motor: araç, derlenmiş Holarch Language Engine'i ve SysML v2 standart kitaplığını içerir. holarch version bunların sürümlerini ve motorun telif hakkı bildirimini yazdırır.

Nasıl kullanılır

Ne zaman ve neden

Aracı, SysML v2 metninin bir kaynak deposunda bulunduğu yerlerde kullanın: tasarımcılar .sysml dosyalarını seçtikleri düzenleyicide düzenler ve her değişiklik birleştirilmeden önce denetlenir. Bir derleyicinin kod için yaptığı gibi her commit'te “bu model hâlâ tutarlı mı?” sorusunu yanıtlar. Modelleme, diyagramlar ve incelemeler için Holarch düzenleyicisini; düzenlemeler arasında dosyaları korumak için aracı kullanın. Bir modeli depo ile bir Holarch projesi arasında taşımak için İçe ve dışa aktarma kullanın.

Kurulum

  1. Python 3.9 veya sonrasını kurun.
  2. Aracı sisteminiz için (Linux x86-64, Linux arm64 veya Apple silikonlu macOS) pip ile kurun:
python3 -m pip install holarch-cli
  1. Kurulumu denetleyin: holarch version araç, motor ve kitaplık sürümlerini yazdırır.

Bir API belirteciyle oturum açma

  1. Holarch'ta Hesap ayarları → API belirteçleri sayfasını açın ve bir belirteç oluşturun. Salt okunur erişim yeterlidir.
  2. Belirteci HOLARCH_API_KEY ortam değişkenine koyun (CI'da: bir gizli değer).
  3. holarch whoami çalıştırın. Planınızı ve hesabınızı yazdırır, örneğin "plan": "team".

Bir modeli denetleme

holarch check models/

Her sorun bir satırdır, ardından bir özet gelir:

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.

Modelde hata olduğunda çıkış kodu 1, aksi takdirde 0'dır. Uyarılarda da başarısız olmak için --warnings-as-errors ekleyin.

Dosyaları biçimlendirme

  1. holarch format models/ çalıştırın. Değişen her dosya “reformatted <file>” olarak listelenir.
  2. CI'da dosyaları değiştirmeden yerleşimi denetlemek için holarch format --check models/ çalıştırın. “would reformat <file>” listeler ve bir dosya değişecekse 1 ile çıkar.
  3. Değişiklikleri önce görmek için holarch format --diff models/ çalıştırın.

Sözdizimi hataları olan bir dosya biçimlendirilmez (“not formatted: the file has syntax errors.”). Yorumlar oldukları yerde kalır: bir öğeden önceki notlar onun üstünde, satır sonundaki bir not o satırın sonunda kalır.

Modeli SysML v2 JSON olarak dışa aktarma

holarch export models/ -o model.json

Dosya, Systems Modeling API'nin standart öğe dizisini tutar. Aynı dosyalar her zaman aynı JSON'u verir; bu nedenle dışa aktarma commit edilip karşılaştırılabilir. Hataları olan bir model dışa aktarılmaz (“The model has errors, so it was not exported.”); yine de dışa aktarmak için --force ekleyin. Bir Holarch projesine birebir içe aktarma için yalnızca Holarch'ın okuduklarını (öğe sırası, yazım) korumak üzere --holarch-fields ekleyin.

GitHub Actions'ta çalıştırma

  1. API belirtecini HOLARCH_API_KEY adlı bir depo gizli değeri olarak ekleyin (Settings → Secrets and variables → Actions).
  2. Bir iş akışı dosyası ekleyin, örneğin .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. Gönderin (push). Sorunlar pull request'in değişen satırlarında ek açıklama olarak görünür ve modelde hata olduğunda veya bir dosya standart yerleşimde olmadığında iş başarısız olur. Yalnızca modeli denetlemek için holarch format --check adımını çıkarın.

Son adım SARIF raporunu kod taramasına yükler; sorunlar orada Security → Code scanning altında listelenir. Deponuz kod taraması kullanmıyorsa bu adımı çıkarın: ek açıklamalar onsuz da çalışır.

Diğer CI sistemlerinde çalıştırma

Python 3.9 veya sonrasına sahip her CI sistemi aynı komutları çalıştırır. Aracı kurun, belirteci bir gizli değerden ayarlayın, denetleyin:

python3 -m pip install holarch-cli
holarch check models/ --sarif holarch.sarif --json holarch.json

Örneğin GitLab CI (.gitlab-ci.yml, maskelenmiş bir CI/CD değişkeni olarak HOLARCH_API_KEY ile):

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 ve diğerleri aynı şekilde çalışır: bir adım aracı kurar, sonraki holarch check çalıştırır; sıfırdan farklı bir çıkış kodu derlemeyi başarısız kılar. Sayıları bir panoda görmek istediğinizde JSON raporunu (--json) bir derleme yapıtı olarak saklayın.

Çalışılmış örnek: Hybrid Car demosu

  1. Demoyu oluşturun: Projeleri yönet sayfasında Proje dosyaları ▾ → Yeni demo proje → Hybrid Car (SysML v2) seçeneğine tıklayın.
  2. Model → İçe ve dışa aktarma sayfasını açın. Dışa aktar altında Tüm model ve SysML v2 metni seçeneklerini seçin, Dışa aktar düğmesine tıklayın ve indirilen dosyayı deponuzdaki models klasörüne açın.
  3. holarch check models çalıştırın. Sonuç “6 files checked: 0 errors, 0 warnings.” olur.
  4. requirements.sysml içinde attribute maxCurbMass : MassValue ifadesini MassValu olarak değiştirin ve denetimi yeniden çalıştırın. requirements.sysml:14:27: error name.unresolved: “MassValu” is not defined here. bildirir ve 1 ile çıkar.
  5. Değişikliği geri alın. holarch format models komutunu bir kez çalıştırın ve dosyaları commit edin; böylece sonraki format --check çalıştırmaları geçer.
  6. Yukarıdaki GitHub iş akışını ekleyin. Modeli bozan sonraki her pull request denetiminden geçemez.

İpuçları ve iyi uygulamalar

  • Her dosyanın içeriğini bir pakette tutun. Herhangi bir paketin dışındaki öğeler çalışır, ancak dosya başına bir paket adları dosyalar arasında benzersiz tutar.
  • CI için hiçbir projeyle sınırlı olmayan salt okunur bir belirteç kullanın: aracın proje erişimine ihtiyacı yoktur.
  • format-check özelliğini açmadan önce bir kez biçimlendirip sonucu commit edin; aksi takdirde ilk çalıştırma her dosyada başarısız olur.
  • Yeni bir motor sürümünün bir incelemenin ortasında sonuçları değiştirmemesi için CI'da aracın sürümünü sabitleyin (holarch-cli==<version>).
  • İnternet erişimi olmayan çalıştırıcılar belirteç yerine bir lisans dosyası kullanır.

Yaygın hatalar

  • “No .sysml or .kerml files found”: yol yanlış veya dosyalar adı nokta ile başlayan bir klasörde.
  • Adlar yalnızca bir dosyada çözümlenmiyor: dosya, başka bir dosyanın kullandığı adları bildiriyor ve o diğer dosyada bir sözdizimi hatası var. Önce sözdizimi hatasını düzeltin; rapor hangi dosyaların dışarıda bırakıldığını belirtir.
  • İş 3 çıkış koduyla başarısız oluyor: belirteç eksik, yanlış veya Free planındaki bir hesaba ait. İleti hangisi olduğunu belirtir.

Diğer özelliklerle nasıl bağlantılıdır

  • Denetimler, Holarch düzenleyicisinin SysML v2 metni ve SysML v2 projeleri için Model denetimleri denetimleriyle aynıdır, aynı iletilerle (SysML v2 metin düzenleyicisi).
  • Bir projeden dışa aktarılan dosyalar (İçe ve dışa aktarma) sorunsuz denetlenir; aracın dışa aktardığı JSON bir projeye içe aktarılır.
  • Dosyalar yerine Holarch'ta incelemeden geçmesi gereken değişiklikler için değişiklikleri öneri olarak gelen API'yi veya Python istemcisi'ni kullanın.

Komutlar

KomutNe yapar
holarch check [paths]Modeli denetler; sorunları bildirir; hatalarda 1 ile çıkar
holarch format [paths]Dosyaları standart yerleşimde yeniden yazar
holarch export [paths]Modeli SysML v2 JSON olarak yazar
holarch whoamiBelirtecin veya lisans dosyasının neye izin verdiğini gösterir
holarch versionAraç, motor ve kitaplık sürümlerini ve motorun telif hakkı bildirimini yazdırır (oturum açma gerekmez)

Yollar dosya veya klasördür; varsayılan geçerli klasördür. Klasörler alt klasörleriyle birlikte aranır.

check seçenekleri

SeçenekAnlamı
--format human|json|sarif|githubStandart çıktıdaki rapor (varsayılan human)
--output FILEBunun yerine o raporu bir dosyaya yazar
--sarif FILEAyrıca bir SARIF 2.1.0 raporu yazar
--json FILEAyrıca bir JSON raporu yazar
--warnings-as-errorsUyarılarda da 1 ile çıkar

format seçenekleri

SeçenekAnlamı
--checkHiçbir şeyi değiştirmez; bir dosya değişecekse 1 ile çıkar
--diffHiçbir şeyi değiştirmez; değişiklikleri birleşik fark olarak yazdırır
--stdoutBir dosyanın biçimlendirilmiş metnini yazmak yerine yazdırır

export seçenekleri

SeçenekAnlamı
-o FILE, --output FILEBir dosyaya yazar (varsayılan: standart çıktı)
--holarch-fieldsBirebir gidiş dönüş için yalnızca Holarch'ın okuduğu alanları ekler
--forceHataları olan bir modeli dışa aktarır (sözdizimi hataları olanı asla)

Oturum açan her komutun seçenekleri

SeçenekOrtam değişkeniAnlamı
--api-key KEYHOLARCH_API_KEYBir API belirteci (hol_…); belirteç günlüklerin dışında kalsın diye değişkeni tercih edin
--license FILEHOLARCH_LICENSE_FILEÇevrimdışı kullanım için bir lisans dosyası
--server URLHOLARCH_SERVERBelirteci denetleyen Holarch sunucusu (bir https adresi)
--timeout SECONDSHer motor adımı için süre sınırı (varsayılan 60)

Araç için oturum açma

Araç, bunlardan biri mevcut olduğunda çalışır:

  • Individual veya Team planına ait bir API belirteci; Individual denemesi dahil. Araç sunucuya bir kez sorar ve yanıtı bir gün boyunca bir önbellek dosyasında tutar (~/.cache/holarch/entitlement.json; HOLARCH_CACHE_DIR konumunu değiştirir). Önbellek planı ve hesap e-postasını tutar, belirteci asla tutmaz. Sunucuya ulaşılamadığında en fazla 7 günlük bir yanıt, bir notla birlikte yine geçerli sayılır.
  • Bir lisans dosyası; Holarch Language Engine lisans sahipleri, self-hosted sürüm müşterileri ve internet erişimi olmayan çalıştırıcılar için. Araç dosyanın imzasını kendisi denetler ve hiçbir zaman bir sunucuya bağlanmaz. Her geçerli lisans aracı ek ücret olmadan içerir:
    • Holarch Language Engine lisansı: motor tesliminizdeki lisans anahtarını (l1. ile başlayan metin) bir dosyaya kaydedin, örneğin holarch-engine.key, ve --license veya HOLARCH_LICENSE_FILE ile onu gösterin. Bir e-postanın eklediği satır sonları önemli değildir. Anahtarın lisanslı web adresleri ve sunucu kullanımı aracı değil, ürününüzdeki motoru kapsar. Anahtarın bitiş tarihinden sonraki 14 gün içinde araç çalışmaya devam eder ve bir hatırlatma yazdırır.
    • Self-hosted sürüm lisansı: Holarch sunucunuzun lisans dosyasını olduğu gibi kullanın. Son 30 gününde araç bir hatırlatma yazdırır. Bitiş tarihinden sonraki 30 gün içinde (lisansın ek süresi) araç çalışmaya devam eder ve kalan günleri yazdırır; bundan sonra yenilenmiş bir lisans kurulana kadar durur.

14 gününü aşmış bir motor anahtarı da yenilenmiş bir anahtar kurulana kadar aracı durdurur.

Free planındaki bir hesabın belirteci reddedilir; hesap API'yi akademik bir e-posta adresi aracılığıyla korusa da. Individual denemesi aracı içerir.

CI'da lisans dosyaları

Lisansı depoda değil, bir gizli değer olarak saklayın. CI'da gizli değeri checkout dışındaki bir dosyaya yazın (GitHub Actions'ta $RUNNER_TEMP altına) ve HOLARCH_LICENSE_FILE değişkenini onun yoluna ayarlayın.

Raporlar

JSON çıktısı

--format json ve --json FILE şunları yazar:

AlanAnlamı
tool, version, engineholarch, aracın sürümü, motorun sürümü
filesAracın çalıştığı klasöre göre göreli yollar olarak denetlenen dosyalar
summaryerrors, warnings, notes, files
diagnosticsfile, line, column, endLine, endColumn (1 tabanlı), severity (error, warning, info), code, message, args
skippedDenetlenmeyen dosyalar, nedeniyle birlikte (eski bir motorla KerML dosyaları)
excludedDosyalar arası denetimlerin dışında bırakılan, sözdizimi hataları olan dosyalar

Sütunlar Unicode karakterlerini (kod noktalarını) sayar.

SARIF

--format sarif ve --sarif FILE, her tanılama kodu için bir kural, error, warning veya note olarak önem düzeyi ve aracın çalıştığı klasöre göre göreli yollarla SARIF 2.1.0 yazar. Kod taramasının dosyaları bulması için aracı deponun kökünde çalıştırın.

GitHub ek açıklamaları

--format github, her sorun için GitHub Actions'ın ek açıklama olarak gösterdiği bir iş akışı komutu (::error file=…,line=…,col=…::message), ardından özet satırını yazdırır.

Çıkış kodları

KodAnlamı
0Hata yok (format: değiştirilecek bir şey kalmadı)
1Modelde hatalar var; format --check veya --diff: bir dosya değişecek veya bir dosya biçimlendirilemedi; export: hatalar nedeniyle reddedildi
2Yanlış kullanım: bilinmeyen bir seçenek, var olmayan bir yol, model dosyası yok
3Oturum açılmamış veya yetki yok: belirteç veya lisans dosyası yok, reddedilmiş bir belirteç, bir Free planı, geçersiz, değiştirilmiş veya süresi dolmuş bir lisans dosyası
4Motor çalışamıyor veya modeli denetlenemeyecek kadar büyük ya da yavaş olduğu için reddetti

İletiler

İletiAnlamı
“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 komut satırı aracı, bir Individual veya Team planına ait bir Holarch API belirteci ya da bir Holarch Language Engine lisans dosyası gerektirir.)Ne belirteç ne de lisans dosyası ayarlanmış
“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.” (Araç Individual ve Team planlarıyla gelir; Hesap ayarları → Plan ve faturalandırma içinde bir plan seçin veya bir lisans dosyası kullanın.)Belirtecin hesabı Free planında
“The API and MCP come with the Individual and Team plans.” (API ve MCP, Individual ve Team planlarıyla gelir.)Belirtecin hesabı Free planında ve API erişimi de yok
“The API token is not valid: it is wrong, revoked or expired, or its account cannot sign in.” (API belirteci geçersiz: yanlış, iptal edilmiş veya süresi dolmuş ya da hesabı oturum açamıyor.)Yeni bir belirteç oluşturun
“The license file's signature does not verify. Use the file exactly as it was delivered.” (Lisans dosyasının imzası doğrulanmıyor; dosyayı teslim edildiği gibi kullanın.)Lisans dosyası değiştirilmiş veya hasarlı
“License <id> expired on <date>. Install a renewed license file.” (Lisansın süresi doldu; yenilenmiş bir lisans dosyası kurun.)Bir self-hosted lisansı 30 günden uzun süre önce veya bir motor lisans anahtarı 14 günden uzun süre önce sona erdi
“The engine license key's signature does not verify. Use the key exactly as it was delivered.” (Motor lisans anahtarının imzası doğrulanmıyor; anahtarı teslim edildiği gibi kullanın.)Dosyadaki anahtar değiştirilmiş veya başka bir ürüne ait
“The engine license key is not complete. Copy the whole key (l1.….…) into the file.” (Motor lisans anahtarı eksik; anahtarın tamamını dosyaya kopyalayın.)Anahtarın bir kısmı eksik
“… cannot be reached to check the API token” (API belirtecini denetlemek için … adresine ulaşılamıyor)Bağlantı yok ve önbellekte yakın tarihli bir yanıt yok; yeniden deneyin veya bir lisans dosyası kullanın
“<file>: not formatted: the file has syntax errors.” (dosya biçimlendirilmedi: sözdizimi hataları var.)Bunları görmek için holarch check çalıştırın
“<file>: not formatted: a comment could not be kept in place.” (dosya biçimlendirilmedi: bir yorum yerinde tutulamadı.)Dosya değişmeden kalır; araç hiçbir zaman bir yorumu atmaz
“The model has errors, so it was not exported.” (Modelde hatalar olduğu için dışa aktarılmadı.)Hataları düzeltin veya --force ekleyin
“The installed engine does not carry the Holarch Language Engine copyright notice, so it is not a genuine Holarch build.” (Kurulu motor Holarch Language Engine telif hakkı bildirimini taşımıyor; bu nedenle gerçek bir Holarch derlemesi değil.)Aracı yeniden kurun

Sınırlar

  • Düzenleyicide olduğu gibi bir modelde dil başına en fazla 8 MB SysML metni ve en fazla 64 KB'lık satırlar.
  • Tek bir çalıştırmada en fazla 10,000 dosya.
  • Her motor adımı --timeout saniye sonra durur (varsayılan 60).
  • Adlar aynı dildeki dosyalar arasında çözümlenir: bir .sysml dosyası bir .kerml dosyasında bildirilen adları görmez.