Language Reference

Datro DSL (.dtro dosyaları için tam sözdizimi referansı. Her blok türü, her alan, her teşhis kodu — hepsi tek bir yerde.

Her .dtro dosyası 1. satırdaki sihirli başlıkla başlamalıdır. Ayrıştırıcı, eksik veya hatalı biçimlendirilmişse E100 değerini döndürür.

#!DATRO 1.0

İsteğe bağlı belge düzeyinde meta veriler. Atlanırsa I003 bilgi ipucu üretir. kind hariç tüm alanlar isteğe bağlı dizeler/dizilerdir.

#!DATRO 1.0

meta {
  title:       "Payment Service"
  version:     "2.1.0"
  description: "Handles card and crypto charges"
  author:      "jane@example.com"
  owner:       "payments-team"
  tags:        ["payments", "critical"]
  sla:         "99.95%"
  criticality: "P0"
  kind:        architecture
}

Diyagramdaki bir varlığı bildirir. Her düğümün benzersiz bir kimliği, oluşturulan şeklini ve varsayılan rengini kontrol eden bir anlamsal type ve meta veriler için isteğe bağlı bir attrs bloğu vardır.

# Minimal
node api_gw { type: gateway label: "API Gateway" }

# With attrs block
node payment_svc {
  type:  service
  label: "Payment Service"
  attrs {
    tech:       "nestjs"
    owner:      "payments-team"
    deprecated: false
    sla:        "99.95%"
  }
}

# Inline attrs (alternative syntax)
node db { type: database label: "Payments DB"  attrs { tech: "postgres" } }

İki düğüm arasındaki ilişkiyi bildirir. Kenar yönü bildirimde doğrudan yazılır: -> (yönlendirilmiş), <-> (çift yönlü) veya -- (yönsüz).

# Minimal
edge api_gw -> payment_svc { kind: http }

# Full metadata
edge payment_svc -> stripe {
  kind:   http
  label:  "charge API"
  weight: 2.0
  async:  false
  attrs { sla: "200ms" }
}

# Bidirectional edge
edge cache <-> service { kind: read }

# Undirected edge
edge svc_a -- svc_b { kind: depends }

İlgili düğümleri etiketli bir alt grafik kutusunda kümeler. Bir düğüm en fazla bir gruba ait olabilir — E403 çatışmalarda tetiklenir. Gruplar iç içe yerleştirilebilir: Bir üye kimliği başka bir grup kimliğine referans verebilir.

group data_tier {
  label:   "Data Layer"
  members: [payments_db, fraud_cache, audit_log]
  attrs { compliance: "PCI-DSS" }
}

# Alternative: assign group on the node
node payments_db {
  type:  database
  label: "Payments DB"
  group: data_tier
}

Doğrulayıcının IR'ye göre değerlendirdiği bir mimari kural bildirir. İhlaller E501 (veya severity: warn olduğunda W501 üretir. rule alanı kısa ve üç belirteçli bir dilbilgisi kullanır.

# Prohibition: databases may not call external services
constraint {
  id:       "no-db-external"
  rule:     "database !-> external"
  message:  "Databases must not connect directly to external APIs"
  severity: error
}

# Requirement: every gateway must connect to a service
constraint {
  rule:     "gateway -> service"
  message:  "Each gateway must route to at least one service"
  severity: warn
}

# Membership: all databases must be in the data_tier group
constraint {
  rule:     "database in data_tier"
  message:  "All database nodes must belong to the data_tier group"
  severity: error
}

Kısıtlama fiilleri

• `!->` — hiçbir SUBJECT düğümü, herhangi bir OBJECT düğümüne yönlendirilmiş bir kenara sahip olamaz.
• `->` — her SUBJECT düğümü, bir OBJECT düğümüne en az bir yönlendirilmiş kenara sahip olmalıdır.
• `!<->` — SUBJECT ve OBJECT düğümleri arasında çift yönlü kenar mevcut olamaz.
• `<->` — her SUBJECT düğümünün, bazı OBJECT düğümlerine çift yönlü bir kenarı olmalıdır.
• `in` — her SUBJECT düğümü, OBJECT grubunun üyesi olmalıdır.
• `!in` — hiçbir SUBJECT düğümü, OBJECT grubunun üyesi olamaz.

Büyük diyagramları birden fazla .dtro dosyaya böler. Çözümleyici, içe aktarılan IR'yi doğrulamadan önce üst öğeyle birleştirir. Ad alanı için as'i ve belirli kimlikleri beyaz listeye almak için expose'yi kullanın.

# Import everything from another .dtro file
import "auth.dtro"

# Import with a namespace alias — IDs become auth.user_service, etc.
import "auth.dtro" as auth

# Import only specific IDs (whitelist)
import "infra.dtro" as infra expose [load_balancer, cdn]

Oluşturucuya grafiğin nasıl düzenleneceğine dair ipuçları. Tüm alanlar isteğe bağlıdır; oluşturucu, blok atlandığında mantıklı varsayılanları kullanır.

layout {
  direction:       LR          # LR | RL | TB | BT
  algo:            dagre        # dagre | dot | elk | force | none
  node_sep:        60           # px between nodes in the same rank
  rank_sep:        120          # px between ranks
  margin:          20           # graph margin in px
  cluster_padding: 16           # padding inside group boxes
}

İşlenen diyagramın görsel görünümünü kontrol eder. palette, düğüm türlerini onaltılık renklerle eşler. accessibility alt bloğu otomatik WCAG 2.1 kontrast kontrolünü etkinleştirir.

theme {
  name: "Corporate"

  palette {
    service:    "#D0E8FF"
    database:   "#FFE8C0"
    gateway:    "#FFD0D0"
    queue:      "#E8D0FF"
    cache:      "#C0FFE8"
    external:   "#F0F0F0"
    background: "#FFFFFF"
  }

  typography {
    font_family:      "Inter, sans-serif"
    node_font_size:   11
    edge_font_size:   9
    label_font_weight: "600"
  }

  accessibility {
    min_contrast:    AA          # AA | AAA | none
    max_label_length: 60
  }
}

Temadan sonra uygulanan öğe başına ince taneli geçersiz kılmalar. Kurallar basamaklanır: by_id, by_type'i geçersiz kılar. Her alt blok bir anahtarı bir mülk haritasına eşler.

style {
  # Override by node type
  by_type {
    database { fill: "#FFF3CD"  stroke: "#E6A817"  shape: cylinder }
    external { fill: "#F8F9FA"  stroke: "#6C757D"  dash: true }
  }

  # Override individual node by id
  by_id {
    stripe { fill: "#635BFF"  stroke: "#4B44CC" }
  }

  # Style edge kinds
  by_edge_kind {
    query   { color: "#E6A817"  width: 2 }
    publish { color: "#198754"  dash: true }
  }

  # Style edges that carry a boolean attr set to true
  by_edge_attr {
    async { dash: true  color: "#ADB5BD" }
  }
}

Tüm teşhisler bir code, severity, message ve isteğe bağlı bir line:col konumu içerir. Aşağıdaki tablo, takım zincirinin yayabileceği her kodu listelemektedir.

Hatalar (E×××)

• `E100` — Sihirli başlık #!DATRO 1.0 eksik veya hatalı biçimlendirilmiş
• `E201` — Yinelenen düğüm kimliği
• `E202` — Düğüm bilinmeyen bir grup kimliğine başvuruyor
• `E301` — Kenar from düğümü bulunamadı
• `E302` — Kenar to düğümü bulunamadı
• `E303` — Kenar weight negatiftir
• `E401` — Yinelenen grup kimliği
• `E402` — members grubu bilinmeyen bir kimliğe başvuruyor
• `E403` — Düğüm birden fazla gruba atandı
• `E404` — Dairesel grup içi içe yerleştirme algılandı
• `E500` — Kısıtlama kuralında sözdizimi hatası var
• `E501` — Kısıtlama kuralı ihlal edildi (şiddet, kısıtlamanın kendi severity ciddiyetini yansıtıyor)

Uyarılar (G×××)

• `W301` — Yinelenen kenar (ilk/tür/etiketle aynı)
• `W501` — Kısıtlama kuralında bilinmeyen bir fiil kullanılıyor
• `W601` — Düğüm etiketi max_label_length değerini aşıyor (varsayılan 80 karakter)
• `W602` — Tema paleti rengi WCAG AA kontrastının (4,5:1) altına düşüyor
• `W603` — Tema paleti rengi WCAG AAA kontrastının (7,0:1) altına düşüyor

Bilgi ipuçları (I×××)

• `I001` — Yalıtılmış düğüm — ona hiçbir kenar bağlanmıyor
• `I002` — Boş grup — üye belirtilmedi
• `I003` — meta bloğu yok — dokümantasyon için önerilir
• `I601` — Tema paleti tanımlanmadı — kontrast kontrolleri atlandı

• Komut satırından doğrulamak, biçimlendirmek ve dışa aktarmak için CLI Reference'ı kullanın.
• Diyagramları Markdown'a Markdown plugin ile gömün.
• Adım adım açıklama için Quick Start'a geri dönün.