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.
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’dakialiaseseş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/parserile, 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/parserGo 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/parserile 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.
checkkatmanlar 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.
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.
Yorumlar
Yorum yapmak için GitHub hesabınızla giriş yapmanız yeterli. Yorumlar GitHub Discussions üzerinde saklanır.