Davranışları Test Et. ArchMind Mimarisi Doğrular.

Bir PR 14 satırdı.

Olay iki güne mal oldu.

Testler geçti. Kod incelemesi onaylandı. Yine de üretim, müşteri siparişlerini bozdu.

Biri OrderService‘ı yeniden düzenledi. Bir yöntem çağrısı DB::transaction() dışında taşındı.

Email bildirimi istek sırasında başarısız oldu.

Siparişin yarısı yazıldı. Diğer yarısı yazılmadı.

Fark göze zarif göründü.

Türler doğruydu.

Logik değişmemiş gibi görünüyordu.

Ancak mimari değişmişti.

Karşılaştığım problem

Modern Laravel uygulamaları nadiren tek bir dosya içinde çalışır.

Bir istek genellikle şu şekilde akar:

Route
 → Middleware
 → FormRequest
 → Policy
 → Controller
 → Service
 → Transaction
 → Event
 → Listener

Uygulama büyüdükçe, bu akışı anlamak daha zor hale gelir.

Çoğu araç pek yardımcı olmaz.

PHPStan türleri doğrular.

Testler davranışı doğrular.

Kod inceleme farklara odaklanır.

Ancak hiçbiri basit bir soruyu yanıtlamaz:

Bu rotanın yürütme mimarisi değişti mi?

Örneğin:

POST /orders

Önce:
  auth
  tenant middleware
  DB::transaction
  Order::create
  OrderCreated event

Sonra:
  auth
  tenant middleware
  Order::create
  OrderCreated event

Transaction ortadan kalktı.

Kod hala derleniyor.

Testler hala geçiyor olabilir.

Ancak mimari değişti.

Mimari test edilebilir hale getirmek istedim

Frontend ekiplerinin görüntü testi vardır.

Eğer bir UI beklenmedik bir şekilde değişirse, CI bunu yakalar.

Ben de düşündüm:

Peki ya yürütme mimarisi için aynı şeyi yapabilirsek?

Bu fikir ArchMind oldu.

Bir Laravel projesini dosyalar topluluğu olarak değil, bir yürütme grafiği olarak yapılandırır.

Route
 → Middleware
 → Controller
 → Service
 → Transaction
 → Event

Grafik temel bir çizgi haline gelir.

Gelecekteki commitler buna karşılaştırılır.

Önemli bir mimari bileşen kaybolursa, ArchMind bir topoloji gerilemesi bildirir.

Örnek:

✘ TOPOLOJİ GERİLEMESİ: POST /orders

kayıp:
  transaction_boundary

CI, değişiklik üretime ulaşmadan önce başarısız olur.

ArchMind ne yapar?

1. Yürütme akışını izleme

archmind trace --project . "POST /orders"

Çıktı:

POST /orders
└─ auth:sanctum
   └─ ResolveTenant
      └─ OrderController::store
         └─ OrderService::createOrder
            └─ DB::transaction
               ├─ Order::create
               └─ OrderCreated

Bu, yürütme yolunun rota düzeyinde bir görünümünü sağlar.

Denetleyiciler, hizmetler, olaylar ve dinleyiciler arasında manuel olarak kazmamıza gerek yok.

2. Topoloji gerilemelerini algılama

archmind verify --project .

Örnek:

✘ TOPOLOJİ GERİLEMESİ

Route:
  POST /orders

Kayıp:
  transaction_boundary

Amacımız iş mantığını doğrulamak değil.

Amacımız mimariyi doğrulamaktır.

3. Mimari bulguları yüzeye çıkarma

archmind findings --project .

Örnekler:

missing_authorization

Route, kimlik doğrulaması gerektiriyor ama tokalı bir yetkilendirme katmanı algılanmadı.

Ya da:

transaction_escape

Olay bir transaction sınırından içeriden tetiklendi.

Bu bulgular kasıtlı olarak muhafazakardır.

Amacı mimari riskleri gözden geçirmeye sunmaktır, garanti edilen zayıflıkları iddia etmek değil.

Beklenmedik bir yan etki: daha iyi AI bağlamı

Başlangıçta ArchMind bir AI aracı olarak inşa edilmedi.

Statik analiz ve mimari doğrulama aracı olarak başladı.

Ancak bir yürütme grafiği var olduğunda, geri alma için de yararlı hale geldi.

Çoğu AI kodlama aracı yaklaşık olarak şöyle çalışır:

Soru
 ↓
Benzer dosyaları bul
 ↓
Dosyaları LLM'ye gönder

ArchMind bunun yerine yürütme bağlamını geri alır:

Soru:
Bu ödeme uç noktası neden bazen müşterileri iki kez ücretlendiriyor?

İlgili bağlam:
- transaction boundary
- ödeme olayı dağıtımı
- after-commit dinleyici

Gerçek Laravel uygulamalarında yapılan benchmark testlerinde:

İlginç sonuç sadece daha yüksek doğruluk değil.

Ayrıca, yürütme grafiği mimari bilgiyi çok daha küçük bir bağlam penceresine sıkıştırdı.

Nasıl çalışır

Yüksek düzeyde:

PHP Source
    ↓
Tree-sitter parsing
    ↓
Laravel-aware analysis
    ↓
Execution Graph
    ↓
Topology Verification

PHP çalışma zamanı gerekmez.

Mevcut destek şunları içerir:

• Laravel 10
• Laravel 11
• Laravel 12
• Middleware zincirleri
• FormRequests
• Policies
• Transactions
• Events
• Route grupları
• apiResource rotaları

ArchMind ne yapmaz

Sınırlamaları netleştirmek önemlidir.

ArchMind şunları yakalamaz:

• Yanlış iş mantığı
• Sıfıra bir fazlalık hatası
• Yanlış karşılaştırma operatörleri
• Harici hizmetlerden kaynaklanan çalışma zamanı hataları

Mimari ve yapısal değişikliklere odaklanır.

Bunu şöyle düşünün:

Yürütme mimarisi için anlık görüntü testi.

Bir testlerin yerini almaz.

Statik analizin yerini almaz.

Mimari niyeti doğrulayan ek bir katmandır.

Örnek CI kurulumu

Bir temel kaydedin:

archmind verify --project . --update

Commit edin:

git add .archmind/baselines
git commit -m "chore: add topology baseline"

Sonra CI’de çalıştırın:

- run: npm install -g @kidkender/archmind
- run: archmind verify --project .

Eğer bir transaction sınırı kaybolursa, bir yetkilendirme middleware’i kaldırılırsa ya da korumalı bir rota mimarisinin bir kısmını kaybederse, derleme başarısız olur.

Son düşünceler

Bu projeden elde edilen en ilginç sonuç Laravel ile ilgili değildi.

Bu düşünceydi:

Testler davranışı doğrular.

Mimari genellikle insanların kafasında yaşar.

Mimari bir grafik haline geldiğinde, sürümleyebileceğimiz, karşılaştırabileceğimiz ve doğrulayabileceğimiz bir şey olur.

ArchMind’in arkasındaki düşünce budur.

Laravel geliştiricilerinden geri bildirim almak isterim:

• Mimari gerilemeler projelerinizde olaylara neden oldu mu?
• Yürütme akışındaki değişiklikleri şu anda nasıl gözden geçirirsiniz?
• Mimari düzeyde doğrulama CI hattınızda faydalı olur mu?

GitHub: https://github.com/Kidkender/archMind