Diagnostik JSON Zero: Error Compiler Terstruktur untuk Agen

Fitur Utamanya

Fitur paling khas di Zero bukan bagian dari sintaks. Fitur itu adalah cara compiler berbicara kepada siapa pun, atau apa pun, yang membaca output-nya.

Jalankan program yang rusak lewat zero check --json, dan kamu akan mendapat output yang bisa langsung dibaca agen:

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

Itu potongan data yang kecil tetapi padat makna. Mari kita bedah setiap field dan pilihan desain di baliknya.

Anatomi Sebuah Diagnostik

Diagnostik adalah objek terstruktur yang menjelaskan satu masalah di kode sumber. Field standarnya:

• code: identifier yang stabil (misalnya NAM003). Artinya selalu sama, apa pun versi compiler-nya.
• message: deskripsi yang mudah dibaca manusia. Kata-katanya bisa berubah antarversi, karena artinya ditetapkan oleh code, bukan oleh pesannya.
• line (dan field lokasi lainnya): tempat masalahnya berada.
• repair: metadata terstruktur opsional yang menjelaskan perbaikan yang menurut compiler bisa menyelesaikan diagnostik itu. Bentuk field ini sendiri sudah didokumentasikan dan stabil.

Bentuk tingkat atasnya memuat boolean ok untuk keseluruhan proses dan array diagnostics. Bahkan saat prosesnya berhasil, array itu bisa berisi peringatan atau catatan.

Kode Error yang Stabil

Kontrak pada code adalah bagian yang paling mungkin mengejutkanmu. NAM003 hari ini berarti "unknown identifier". NAM003 bulan depan dan tahun depan juga akan berarti "unknown identifier". Agen (dan manusia) bisa mengandalkan hal itu.

Ini penting karena model bahasa dan tooling cenderung menyimpan atau menghafal apa yang pernah dilihatnya. Kalau arti NAM003 bergeser di setiap rilis, setiap pencarian yang tersimpan menjadi tidak aman. Dengan kode yang tetap:

• Data latihan agen tetap berlaku di berbagai versi.
• Dokumentasi bisa diindeks berdasarkan kode.
• Pipeline tooling tetap stabil.

message yang ditujukan untuk manusia bebas berubah saat tim memperbaiki kata-katanya. code adalah identifier yang menjadi tumpuan.

Metadata Perbaikan

Field repair, kalau ada, memberi tahu pembacanya jenis perbaikan yang menurut compiler akan berhasil:

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

declare-missing-symbol di sini adalah jenis perbaikannya, yaitu maksud tingkat tinggi. Untuk mendapat edit yang sebenarnya, panggil zero fix --plan --json. Perintah itu mengembalikan rencana yang memuat path file, rentang byte yang perlu diubah, dan teks barunya:

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

(Nama field dan bentuk persisnya bisa berbeda di versi toolchain kamu. Prinsipnya adalah "data terstruktur, bukan kalimat".)

Agen yang membaca rencana itu punya beberapa pilihan:

1. Menerapkan edit apa adanya.
2. Menerapkan edit dengan beberapa perubahan.
3. Menolak rencana itu dan mencari perbaikan lain.

Dalam setiap kasus, agen bekerja dengan data terstruktur, bukan mencoba menafsirkan saran dalam bahasa Inggris. Itulah perbedaan antara rencana perbaikan dan petunjuk "did you mean ...?" di compiler pada umumnya.

Cara Agen Benar-Benar Memakainya

Alur sederhana dari awal sampai akhir yang mungkin dijalankan sebuah agen:

1. Membuat atau mengubah sebuah file Zero.
2. Menjalankan zero check --json pada file itu.
3. Kalau hasilnya { "ok": true, ... }, lanjut ke tugas berikutnya.
4. Kalau tidak, untuk setiap diagnostik:
   • Cari arti code untuk memahami apa yang salah (dengan zero explain atau tabel lokal).
   • Kalau ada repair yang ditawarkan dan terlihat aman, panggil zero fix --plan --json untuk mendapat edit-nya.
   • Terapkan (atau simulasikan) edit tersebut.
5. Kembali ke langkah 2.

Bandingkan dengan bekerja dari pesan berbentuk kalimat: agen harus mengurai bahasa Inggris, mengambil nomor baris yang mungkin, menebak jenis perbaikannya, dan menyimpulkan teks persis yang harus disisipkan atau diganti. Setiap langkah serba tidak pasti. Jalur JSON mengganti setiap langkah itu dengan pencarian terhadap skema yang terdokumentasi.

Bukan Hanya Error: Graph dan Size

--json bukan hanya untuk diagnostik. Perintah lain menyediakan data terstruktur dengan cara yang sama:

• zero graph --json: menghasilkan dependency graph sebuah package sebagai data terstruktur. Berguna untuk memahami apa bergantung pada apa, dan untuk agen yang ingin menalar tempat-tempat pemanggilan sebelum menyentuhnya.
• zero size --json: melaporkan ukuran hasil kompilasi di disk, dirinci per target. Datanya sama dengan yang dilihat manusia di zero size, hanya saja bisa di-parse.

Bentuk-bentuk ini adalah bagian dari desainnya: setiap kali compiler punya data yang berguna, data itu tersedia sebagai JSON untuk dipakai tool tanpa harus mengambil teks dari layar.

Seperti Apa Skemanya

Nama field dan bentuk persisnya didokumentasikan di repository Zero dan akan terus berkembang selama proyek ini masih di bawah 1.0. Kategori yang bisa kamu harapkan:

• Metadata proses: ok, version, waktu eksekusi.
• Diagnostik: code, message, lokasi (file/baris/kolom/rentang byte), tingkat keparahan (error/peringatan/catatan), dan repair yang opsional.
• Rencana perbaikan: saat diambil, berupa daftar edit yang terstruktur.

Kalau kamu membangun tooling di atas bagian ini, pola yang aman adalah membaca field yang kamu kenal, mengabaikan field yang tidak dikenal dengan baik, dan mendasarkan keputusan perilaku pada code.

Contoh Singkat dari Awal sampai Akhir

Misalkan kode sumbermu memakai identifier yang belum dideklarasikan:

pub fun main(world: World) -> Void raises {
    check world.out.write(answer())   // 'answer' is not defined anywhere
}

Menjalankan zero check --json menghasilkan kira-kira seperti ini:

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

zero fix --plan --json mengembalikan edit-nya:

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

zero fix (tanpa --plan) menerapkan edit itu langsung di file, setelah itu zero check mengembalikan ok: true. Setiap langkah adalah transaksi terpisah yang bisa diperiksa.

Kenapa Ini Penting, Bukan Hanya untuk Agen

Sifat-sifat yang sama, yaitu output terstruktur, kode yang stabil, dan rencana perbaikan, juga memudahkan:

• Editor dan IDE. Garis bergelombang dan ikon bola lampu yang bekerja berdasarkan ID repair, bukan teks yang di-parse.
• Pipeline CI. Kegagalan dicatat dengan code sehingga mudah dicari dengan grep dan ditampilkan di dashboard.
• Tool code-mod. Perbaikan massal yang menargetkan sebuah kode, bukan regex atas pesan.

Sistem ini dirancang dengan agen sebagai sasaran utama, tetapi tooling untuk manusia mendapat manfaat yang sama.

Berikutnya: Desain yang Mengutamakan Agen

Sistem diagnostik adalah contoh paling konkret dari filosofi Zero yang mengutamakan agen. Dokumen berikutnya, desain yang mengutamakan agen, kembali melihat gambaran besarnya, yaitu prinsip-prinsip dasarnya (permukaan yang kecil, tooling yang deterministik, efek yang eksplisit) dan alasan masing-masing prinsip layak dipertahankan.