Zero JSON Diagnostics: Ajanlar İçin Yapılandırılmış Compiler Hataları

Manşet Özelliği

Zero'nun en ayırt edici özelliği bir söz dizimi parçası değil. Compiler'ın, çıktısını okuyan kişiyle — ya da neyle — konuşma biçimi.

Bozuk bir programı zero check --json'dan geçirin ve bir ajanın doğrudan okuyabileceği bir feed alırsınız:

{
    "ok": false,
    "diagnostics": [
        {
            "code": "NAM003",
            "message": "unknown identifier",
            "line": 3,
            "repair": { "id": "declare-missing-symbol" }
        }
    ]
}

Küçük ama yüklü bir blob. Her alanı ve arkasındaki tasarım tercihlerini açalım.

Bir Diagnostic'in Anatomisi

Bir diagnostic, kaynaktaki bir sorunu tarif eden yapılandırılmış bir nesnedir. Kanonik alanlar:

• code — kararlı bir tanımlayıcı (örn. NAM003). Compiler sürümünden bağımsız olarak her zaman aynı şeyi ifade eder.
• message — insan tarafından okunabilir bir açıklama. Sürümler arasında ifadesi değişebilir; anlam code ile sabitlenir, mesaj ile değil.
• line (ve diğer konum alanları) — sorunun nerede olduğu.
• repair — compiler'ın diagnostic'i çözeceğini düşündüğü bir düzeltmeyi tarif eden opsiyonel yapılandırılmış metadata. Bu alanın şekli kendisi belgelenmiş ve kararlıdır.

Üst seviye şekil, tüm çalıştırma için bir ok boolean'ı ve bir diagnostics dizisi içerir; çalıştırma başarılı olduğunda bile dizi uyarılar veya notlar içerebilir.

Kararlı Hata Kodları

code üzerindeki sözleşme, sizi en çok şaşırtması muhtemel olan kısım. NAM003 bugün "unknown identifier" demektir. NAM003 gelecek ay ve gelecek yıl da "unknown identifier" demek olacak. Ajanlar (ve insanlar) buna güvenebilir.

Bu önemlidir çünkü dil modelleri ve tooling, gördüklerini cache'leme veya ezberleme eğilimindedir. NAM003'ün anlamı her release ile kayarsa, her cache lookup'ı güvensiz olurdu. Kodu sabitlemek şunları korur:

• Sürümler arasında geçerli ajan training verisi.
• Koda göre indeksli dokümantasyon.
• Kararlı tooling pipeline'ları.

İnsan tarafından okunabilir message, ekip ifadeyi iyileştirdikçe değişebilir. code, yük taşıyan tanımlayıcıdır.

Repair Metadata

repair alanı, mevcut olduğunda, tüketiciye compiler'ın hangi tür düzeltmenin işe yarayacağını düşündüğünü söyler:

{
    "code": "NAM003",
    "message": "unknown identifier",
    "line": 3,
    "repair": { "id": "declare-missing-symbol" }
}

Buradaki declare-missing-symbol, repair'in türüdür — yüksek seviye niyet. Gerçek edit'leri almak için zero fix --plan --json çağırın. Bu, dosya yolu, değiştirilecek byte range'leri ve yeni metni içeren bir plan döndürür:

{
    "diagnostic": { "code": "NAM003", "line": 3 },
    "plan": {
        "id": "declare-missing-symbol",
        "edits": [
            { "kind": "insert", "line": 1, "text": "fun answer() -> i32 { return 42 }\n" }
        ]
    }
}

(Kesin alan adları ve şekil toolchain sürümünüzde farklı olabilir — prensip "düz metin değil, yapılandırılmış veri".)

Planı okuyan bir ajanın birkaç seçeneği vardır:

1. Edit'leri olduğu gibi uygulamak.
2. Edit'leri değişikliklerle uygulamak.
3. Planı reddedip farklı bir düzeltmeye başvurmak.

Her durumda ajan, bir İngilizce öneriyi yorumlamaya çalışmak yerine yapılandırılmış veri üzerinde çalışır. Bu, repair plan'ları ile tipik bir compiler'daki "bunu mu demek istediniz...?" ipuçları arasındaki farktır.

Bir Ajan Bunu Nasıl Kullanır

Bir ajanın çalıştırabileceği basitleştirilmiş uçtan uca bir döngü:

1. Bir Zero dosyası üret ya da değiştir.
2. Ona karşı zero check --json çalıştır.
3. Sonuç { "ok": true, ... } ise devam et.
4. Aksi takdirde, her diagnostic için:
   • Neyin yanlış olduğunu anlamak için code'a bak (zero explain ya da yerel bir tablo ile).
   • Bir repair sunuluyorsa ve güvenli görünüyorsa edit'ler için zero fix --plan --json çağır.
   • Edit'leri uygula (ya da simüle et).
5. 2. adıma geri dön.

Bunu düz metin bir mesajla çalışmakla karşılaştırın: ajanın İngilizce parse etmesi, olası bir satır numarası çıkarması, düzeltme türünü tahmin etmesi ve kesin ekleme ya da değiştirme metnini çıkarsaması gerekir. Her adım bulanıktır. JSON yolu, her adımı belgelenmiş bir şemaya karşı bir lookup ile değiştirir.

Hataların Ötesinde: Graph ve Size

--json yalnızca diagnostic'ler için değil. Diğer komutlar da aynı şekilde yapılandırılmış veri sergiler:

• zero graph --json — bir paketin dependency graph'ını yapılandırılmış veri olarak üretir. Neyin neye bağlı olduğunu anlamak ve dokunmadan önce çağrı yerleri hakkında muhakeme yapmak isteyen ajanlar için faydalı.
• zero size --json — derlenmiş artifact'lerin disk boyutunu target bazında raporlar. Veri, insanların zero size'da gördüğüyle aynıdır; sadece parse edilebilir.

Bu şekiller tasarımın parçasıdır: compiler'ın faydalı veriye sahip olduğu her zaman, araçların screen-scraping yapmadan tüketebilmesi için JSON olarak mevcuttur.

Şema Nasıl Görünür

Alan adları ve kesin şekiller Zero repository'sinde belgelenir ve proje pre-1.0 olduğu sürece gelişecek. Bekleyebileceğiniz kategoriler:

• Run metadata — ok, version, zamanlama.
• Diagnostics — code, message, konum (file/line/column/byte range'leri), severity (error/warning/note), opsiyonel repair.
• Repair plan'ları — getirildiğinde yapılandırılmış edit listesi.

Bu yüzeye karşı tooling kuruyorsanız, güvenli desen bildiğiniz alanları okumak, bilinmeyen alanları zarif bir şekilde yok saymak ve davranışsal kararlar için code'u anahtar yapmaktır.

Hızlı Uçtan Uca Bir Yürüyüş

Diyelim kaynak kodunuz tanımlanmamış bir identifier kullanıyor:

pub fun main(world: World) -> Void raises {
    check world.out.write(answer())   // 'answer' hiçbir yerde tanımlı değil
}

zero check --json çalıştırmak şuna benzer bir şey üretir:

{
    "ok": false,
    "diagnostics": [
        {
            "code": "NAM003",
            "message": "unknown identifier 'answer'",
            "line": 2,
            "column": 27,
            "repair": { "id": "declare-missing-symbol" }
        }
    ]
}

zero fix --plan --json edit'i döndürür:

{
    "diagnostic": { "code": "NAM003", "line": 2 },
    "plan": {
        "id": "declare-missing-symbol",
        "edits": [
            { "kind": "insert", "line": 1, "text": "fun answer() -> i32 { return 42 }\n" }
        ]
    }
}

zero fix (--plan olmadan) edit'i yerinde uygular; bundan sonra zero check, ok: true döndürür. Her adım ayrı, incelenebilir bir transaction.

Bu Neden Ajanların Ötesinde Önemlidir

Aynı özellikler — yapılandırılmış çıktı, kararlı kodlar, repair plan'ları — şunların hayatını da kolaylaştırır:

• Editör'ler ve IDE'ler. Parse edilmiş metin yerine repair ID'lerine göre hareket eden squiggle'lar ve ampuller.
• CI pipeline'ları. Kolay grep'leme ve dashboarding için code ile loglanan başarısızlıklar.
• Code-mod araçları. Mesajlar üzerinde regex değil, kod üzerinde hedeflenen toplu düzeltmeler.

Sistem ajanlar düşünülerek tasarlandı, ama insan odaklı tooling de aynı faydaları alır.

Sırada: Agent-First Tasarım

Diagnostic sistemi, Zero'nun ajan odaklı felsefesinin en somut örneğidir. Bir sonraki yazı, agent-first tasarım, altta yatan prensiplere geri yakınlaşıyor — küçük yüzey, deterministik tooling, explicit effect'ler — ve her birinin yerini nasıl kazandığı.