İçeriğe geç
Muhammet Şafak
en
Günlük 3 dk okuma

archlint: mimari sınırları CI'da deterministik olarak zorlamak

Mimari kararlar kodda çürür. archlint, tek architecture.json ile Go, TypeScript ve Python sınırlarını her commit'te CI'da modelsiz zorluyor.

Rafa takılı archlint etiketli bir sunucu; mor ekranında archlint check: FAILED ve pkg/adapters -> pkg/domain satırları

Mimari kararların neden çürüdüğünü ayrı yazdım: bir ADR “domain altyapıyı import etmesin” der, iki yıl sonra bir bakarsın yüzlerce yerde import etmiş — çünkü kuralı izleyen hiçbir şey yoktu. Bu yazı o sorunun araç tarafı: küçük, bağımsız bir Go CLI — archlint.

Gerçek bir sistem tek dil değil ama: Go API, TypeScript frontend, Python worker’ları. Üçünde de aynı mimari niyet var; archlint üçünü de tek bir architecture.json ile yönetiyor.

architecture.json: kuralı koda yaz

Katmanları ve aralarındaki izinli bağımlılıkları tek bir dosyada beyan ediyorsun:

{
  "module": "github.com/acme/app",
  "layers": {
    "domain": ["internal/domain"],
    "db":     ["internal/db"],
    "http":   ["internal/http"]
  },
  "rules": {
    "domain": [],
    "db":     ["domain"],
    "http":   ["domain", "db"]
  }
}

domain içeride hiçbir şey import edemez, db yalnızca domain’i, http ikisini de. Başka her iç kenar bir ihlal. Aynı-katman import’u her zaman serbest; [] “hiçbir katmanı import edemez” demek.

Sınır dile bağlı değil; sözdizimi bağlı

Katman düzeyinde kural her dilde aynıdır: domain → db yasak. Diller arasında değişen şey kuralın kendisi değil, import’un nasıl yazıldığı ve hangi dosyaya çözüldüğü:

  • Go: mutlak paket yolu — github.com/acme/app/internal/db. Çözüm: modül-prefix’ini sıyır → internal/db.
  • TypeScript: göreli (../db/repo) ya da alias (@/db/repo). Çözüm: göreliyi dosyanın konumuna, alias’ı architecture.json’daki aliases eşlemesine göre çöz.
  • Python: noktalı + göreli — from ..db.repo import find_order. Çözüm: göreli noktaları dosyanın paketine göre yukarı çık, sonra modülü yola çevir.

archlint hepsini tek bir şeye indirger: repo-göreli bir yol → bir katman. O noktadan sonra motor aynı: “bu dosya hangi katmanda, bu import hangi katmana gidiyor, kural izin veriyor mu?”

Tek config, karışık repo

Aynı dosya üç dilli bir monorepo’yu birden yönetebiliyor. Katman adları ortak, yollar dile özel:

{
  "module": "github.com/acme/app",
  "aliases": { "@/": "web/src/" },
  "layers": {
    "domain": ["internal/domain", "web/src/domain", "workers/app/domain"],
    "infra":  ["internal/infra", "web/src/infra", "workers/app/infra"]
  },
  "rules": { "domain": [], "infra": ["domain"] }
}

domain katmanı üç serviste de var (Go internal/, TS web/src/, Python workers/app/) ve hiçbirinde altyapıyı import edemez. Tek kural, üç dil, tek CI kapısı.

Nasıl çalışıyor

archlint check, her Go, TypeScript ve Python dosyasının import’larını çıkarıyor. İçeride bir Language arayüzü var: her dil yalnızca iki şeyi bilir — bir dosyanın import’larını çıkarmak ve bir import’u repo-göreli yola çözmek. Linter’ın geri kalanı dil-agnostik; yeni bir dil eklemek, yeni bir Language implementasyonu eklemek demek.

Go import’ları stdlib’in go/parser’ıyla okunuyor — regex tahmini değil, derlemeye gerek yok, kesin. Her dosyayı ve her import’u (modül yolunu sıyırıp) bir katmana çözüyor; kuralı çiğneyen kenarı dosya:satır ile raporluyor:

$ archlint check examples/sample
Scanned examples/sample against examples/sample/architecture.json — 2 layer(s).

1 boundary violation(s):
  internal/domain/bad.go:6  domain → db is not allowed  (import "github.com/acme/app/internal/db")

İhlal varsa exit 1 → CI kırmızı. Çiğneyen import main’e ulaşmadan yakalanıyor; iki yıl sonra bir arkeoloji seansında değil.

Tasarım kararları

  • Deterministik, modelsiz. Bütün amaç CI’da kapı kurabileceğin bir guardrail: aynı diff, aynı verdict, döngüde model yok. Bir LLM’e “mimariyi gözden geçir” demekten farkı bu.
  • Sıfır bağımlılık (Go stdlib). Ağır bir CGo bağımlılığı olan tree-sitter yerine Go’yu go/parser ile, TypeScript ve Python’ı regex tarayıcılarla okuyorum. Config şimdilik JSON — YAML bir bağımlılık ekliyor, o yüzden follow-up.
  • Go kesin, TypeScript ve Python en iyi çaba. go/parser Go import’larını kesin veriyor. TypeScript/JavaScript ve Python import’ları, standart biçimleri kapsayan regex tarayıcılarıyla çıkarılıyor; yani tam birer parser değiller.

CI’da

Buradan sonrası, GitHub Actions ile kurduğum akışların alışılmış iki satırı; archlint’in tek beklentisi, ihlalde sıfırdan farklı bir kod dönerek job’ı düşürebilmek.

- run: go install github.com/muhammetsafak/archlint/cmd/archlint@latest
- run: archlint check

Ya da paketlenmiş GitHub Action ile:

- uses: muhammetsafak/archlint@v0.3.0

Sınırlar — dürüst liste

  • TS/JS ve Python için regex tarayıcıları. Go import’ları go/parser ile okunuyor (kesin). TS/JS ve Python import’ları regex tarayıcılarından geliyor; bu yüzden yorum ya da string literal içindeki import benzeri bir metin yanlış pozitife yol açabilir. README’de açıkça yazıyor.
  • Statik import grafiği. check katmanlar arası bağımlılık grafiğini yönetir; archlint metrics (v0.3.0’da eklendi) aynı grafik üzerinde bağımlılık (coupling), bounded context ve Conway sinyalleri ekler. “Senkron olması gereken yerde async çağrı” ya da domain sınırını aşan doğrudan bir DB sorgusu, runtime trace’leri ilişkilendirmeyi gerektirir — sonraki faz.
  • JSON config (YAML follow-up). Deterministik tasarım kasıtlı: gate’lenebilir olsun diye.

Denemek için

Her örnek kasıtlı bir ihlal içeriyor:

archlint check examples/sample      # Go     → internal/domain/bad.go
archlint check examples/ts-sample   # TS     → src/domain/bad.ts   ("@/" alias çözülür)
archlint check examples/py-sample   # Python → app/domain/bad.py   ("..db.repo" çözülür)

Üçü de aynı çıktıyı verir: domain → db is not allowed, exit 1, CI kırmızı.

architecture.json’unuzu yazın ve archlint check çalıştırın. Sıradaki dil ya da sınır hangisi olsun isterseniz yazın, sıraya koyayım.

Bu konudaki deneyler

Zarsız bir 4X çekirdeği: 480 altıgen, en çok 60 tur, tarayıcıda çevrimdışı. Kapsamı tek oturum kısıtı belirledi; oyun Regnarium olarak yayına çıktı.

Şu an ne yapıyor

480 altıgenlik haritada azami 60 turda biten bir 4X eli yürütüyor; kurallar, harita üretimi ve rakip yapay zekâ tek bir saf TypeScript çekirdeğinde, savaş zarsız. Elinde yarım saati olan ve strateji oynamak isteyen herkes tarayıcıdan açabilir.

Web TypeScript Next.js React +2 daha
Eylül 2026 — Eylül 2026

Dile özgü serileştirme yerine dondurulmuş bir JSON zarfı seçildi; deneme, PHP, Python, Go ve Node.js'in okuduğu bir kuyruk standardına dönüştü.

Şu an ne yapıyor

Dondurulmuş JSON zarfı dört dilde — PHP, Python, Go, Node.js — aynı baytları okutuyor; sidecar ya da broker eklentisi gerekmiyor. Polyglot kuyruk kuran ekipler spesifikasyonu ve SDK'ları bugün kullanabilir.

Open-Source JSON Redis RabbitMQ +4 daha
Mart 2026 — Haziran 2026

Yorumlar

Yorum yapmak için GitHub hesabınızla giriş yapmanız yeterli. Yorumlar GitHub Discussions üzerinde saklanır.

İlgili Yazılar

Sitede Ara

Yazı, proje ve sayfalarda arama yapmak için yazmaya başlayın.

Esc ile kapat Pagefind ile güçlendirildi