tlk-truss

Gerçek koda bağlı mimari diyagramlar.

Metinden diyagram üreten araçların hepsi resmi çiziyor. Hiçbiri resmin ne zaman yalan söylemeye başladığını söyleyemiyor. truss her düğümü depodaki bir yola bağlar ve o yol kaybolduğunda derlemeni kırar.

$ truss denetle docs/mimari.truss --ci --lang tr
✗ docs/mimari.truss:14  E400  "ledger" düğümü src/ledger/** yoluna bağlı, hiçbir şeyle eşleşmiyor
1 bağ artık çözülmüyor
$ echo $?
1

English: README.md

Durum

v0.1 sürüyor; özellikleri tamam ve test edildi: dört görünüm, ölçülü yerleşim motoru, tek dosyalık HTML çıktısı ve içindeki canlı düzenleme, sapma kapısı, dışa aktarıcılar ve Mermaid içe aktarma. Kalan iş paketleme — CI, yayınlanan demo ve npm sürümü.

Nasıl görünüyor

| Mimari | Sekans | |---|---| | | |

| Veri akışı | Durum | |---|---| | | |

Düzenleme modu, çizimin yanında canlı kaynak:

Kurulum

Node 20 ve üstü, çalışma zamanı bağımlılığı yok.

npm install -g @talkdedsec/tlk-truss

Ya da doğrudan depodan:

node bin/truss.mjs ciz examples/payments.truss

Kaynak

baslik  Ödeme Platformu
akis    asagi

grup edge "Uç"
grup core "Çekirdek servisler"

dugum web  "Vitrin"    icinde=edge tur=istemci kod=apps/web/**
dugum api  "API Geçidi" icinde=core tur=servis  kod=services/api/**
dugum pay  "Ödeme"      icinde=core tur=servis  kod=services/payment/**
dugum bus  "Olay yolu"  icinde=core tur=kuyruk
dugum bank "Banka"                  tur=dis     not="üçüncü taraf"

web -> api : REST
api -> pay : tahsilat
pay ~> bus : payment.captured
pay -> bank : provizyon

• gorunum şunlardan biri: mimari, sekans, veriakisi, durum
• -> çağrı, ~> eşzamansız mesaj
• Bağlantıdan sonra gelen : etiketi taşır
• tur= şunlardan biri: servis, depo, kuyruk, altyapi, istemci, dis, gorev
• kod= bağdır: bir yol ya da glob; virgülle birden fazla verilebilir
• not= bir düğüme, sekansta bir mesaja not iliştirir: api -> pay : "tahsilat" not="idempotent"
• sekansta blok dongu|secenek|istege|paralel "neden" … yoksa "aksi halde" … son arasındaki mesajları çerçeveler; bloklar iç içe geçer, dallar çizgiyle ayrılır
• # yorum satırı başlatır

Her anahtar kelimenin İngilizce yazımı da geçerli (title, group, node, in=, kind=, code=); ikisi aynı dosyada karışık kullanılabilir.

Dört görünüm

| gorunum | Ne çizer | Ne değişir | |---|---|---| | mimari | servisler, depolar, sınırlar | gruplu kutular, yukarıdan aşağı katmanlar | | sekans | tek bir akış, mesaj mesaj | yaşam çizgileri, etkinleşme çubukları, notlar, bloklar, kendine çağrı | | veriakisi | bir boru hattı | soldan sağa, kaynak ve havuz eğik çizilir | | durum | bir durum makinesi | hap kutular, başlangıç noktası, bitiş halkası, kendine geçiş döngüsü |

İlk üçü tek yerleşim motorunu paylaşır, sekansın kendi motoru vardır. Bir durum kendini gösterebilir, sekansta aynı ikili iki kez konuşabilir — kurallar görünüme göre işler.

Komutlar

truss ciz       <kaynak.truss> [-o cikti.html]   tek dosyalık HTML diyagram çizer
truss denetle   <kaynak.truss> [--kok .]         her kod bağının çözüldüğünü doğrular
truss disaaktar <kaynak.truss> --bicim svg|dot|mermaid|json
truss iceaktar  <diyagram.mmd>                   Mermaid'i .truss kaynağına çevirir
truss izle      <kaynak.truss> [--sun]           her kayıtta yeniden çizer

izle, kaynak her değiştiğinde sayfayı yeniden yazar ve yeni sayıları basar. --sun ile sayfayı 127.0.0.1:4173 üzerinde de sunar ve her kayıtta tarayıcıyı tazeler; tazeleme kodu yalnızca sunulan kopyada durur, diskteki dosyada asla.

iceaktar, Mermaid flowchart, sequenceDiagram ve stateDiagram kaynaklarını okur; alt grafları, şekilleri, ok biçimlerini ve kenar etiketlerini korur ve depoya girebilecek bir kaynak yazar.

İkisi de --lang en|tr, --json ve --ci alır. denetle, bir bağ çözülmediğinde 1 ile çıkar — bir CI işinin ihtiyacı olan tek şey bu:

- run: npx @talkdedsec/tlk-truss denetle docs/mimari.truss --ci

Hazır bir action da var:

- uses: Talkdedsec/[email protected]
  with:
    sources: docs/*.truss
    uncovered: true

Hiç bağı olmayan düğümleri işaretlemek için --kati, soruyu tersine çevirmek için --kapsanmayan ekle: hangi dizini hiçbir diyagram sahiplenmiyor? Birden fazla kaynak birlikte denetlenebilir, kapsam hepsinin birleşimidir.

$ truss denetle docs/*.truss --kok . --kapsanmayan
! /srv/shop  W401  "workers/" yolunu hiçbir düğüm sahiplenmiyor
✓ bütün kod bağları çözülüyor — 21/26 düğüm koda bağlı

Çizim

Tek HTML dosyası, ağ çağrısı yok, derleme adımı yok. Koyu ve açık tema, kaydırma ve yakınlaştırma, arama, her düğüm için bağını gösteren ayrıntı paneli, SVG/PNG dışa aktarma. "Güzel oldu" demez, ne yaptığını sayıyla söyler: düğüm, kenar, katman sayısı ve ölçülmüş kenar kesişmesi altta durur.

Hiçbir şey donuk değil. Düzenle'ye bas, sayfa editöre dönüşür: düğümü yeniden adlandır, türünü, grubunu ya da kod bağını değiştir, düğüm, bağlantı ve grup ekle ya da sil. Her değişiklikte motorun tamamı — sayfanın içinde duruyor — yeniden çalışır ve diyagram gözünün önünde yeniden yerleşir. Kaynak düğmesi .truss metnini canlı gösterir, yapıştırılanı geri alır ve dosyayı kaydeder. Ayrıştırılamayan bir değişiklik tanı koduyla reddedilir, çizime dokunulmaz.

Yerleşim otomatiktir ve öyle kalır: döngüler kırılır, katmanlar atanır, sıralama medyan sezgiseliyle seçilir, kesişmeler Fenwick ağacıyla sayılır, koordinatlar düz çizgiye doğru gevşetilir ve grup kutuları üyesi olmayan düğümlerin dışına itilir. Kaynak dilinde elle koordinat yoktur, çünkü elle yerleştirilen diyagramı kimse güncellemez.

Ne kadar büyük diyagram kaldırır

Bu motorda ölçüldü; çapraz bağları olan bir ağaç, yukarıdan aşağı katmanlı:

| düğüm | bağlantı | katman | kesişme | süre | |---|---|---|---|---| | 30 | 39 | 8 | 10 | 7 ms | | 60 | 84 | 13 | 48 | 9 ms | | 120 | 179 | 25 | 382 | 28 ms | | 250 | 369 | 47 | 1458 | 93 ms |

Sorun hız değil, okunabilirlik. Otuz düğümü geçince resim bir şey anlatmayı bırakıyor ve bunu hiçbir yerleşim motoru kurtarmıyor — hikâyeyi birkaç diyagrama böl, ya da tek bir fikri değil bütün depoyu haritalayan bir araca geç.

Kütüphane olarak

import { draw, check, fromMermaid } from '@talkdedsec/tlk-truss';

const { html, diagram, diagnostics } = draw(kaynak);
console.log(diagram.stats.crossings);

parse, build, layout, renderDiagram, renderPage, toSource ve tanı yardımcıları da dışa aktarılıyor; kendi hattını kurmak isteyen için.

Lisans

PolyForm Noncommercial 1.0.0 — kullanımı serbest, satışı değil. Bkz. LICENSE.