CLI Zero: check, run, build, test, fix, dan explain

Apa yang Diberikan CLI

Binary zero adalah seluruh toolchain pengembangan. Tidak ada package manager, formatter, linter, atau test runner terpisah, karena semuanya adalah subcommand dari zero. Dengan begitu, permukaannya tetap kecil dan mudah ditebak, dan memang itulah tujuannya.

Daftar singkat perintah yang paling sering kamu pakai:

Setiap perintah itu menerima --json untuk menghasilkan output yang bisa dibaca mesin, bukan teks yang diformat untuk manusia.

zero check

Ini perintah andalan. zero check menjalankan pemeriksaan statis compiler, yaitu parsing, pemeriksaan tipe, inferensi capability dan efek, serta deteksi import yang hilang, lalu berhenti sebelum tahap pembuatan kode. Perintah ini cepat, dan itu penting karena agen dan editor memanggilnya terus-menerus.

zero check hello.0

Output yang bersih (tidak ada yang ditampilkan, exit 0) berarti file-nya sudah benar strukturnya. Secara default, error ditampilkan sebagai teks yang mudah dibaca manusia. Tambahkan --json, dan kamu akan mendapat bentuk terstruktur yang dibaca agen:

zero check hello.0 --json

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

Struktur diagnostiknya didokumentasikan lengkap di Diagnostik JSON. Perhatikan field code yang stabil: NAM003 selalu berarti "unknown identifier", apa pun versi compiler-nya.

Kamu juga bisa mengarahkan check ke folder package, bukan ke satu file:

zero check ./my-package

Perintah ini membaca zero.json, menelusuri seluruh kode sumber, dan melaporkan setiap masalah di semua target.

zero run

run meng-compile dan menjalankan program dalam satu langkah. Paling cocok saat kamu sedang mencoba-coba program kecil dan tidak perlu menyimpan binary di disk.

zero run hello.0

Hasilnya sama dengan menjalankan zero build lalu memanggil binary yang dihasilkan, hanya saja hasil build-nya langsung dibuang. Stdout dari programmu diteruskan ke stdout terminal kamu, jadi pemanggilan world.out.write di program akan muncul di layarmu.

Kalau programmu butuh argumen, tulis argumennya setelah --:

zero run greet.0 -- Alice

Runtime memberi program akses ke argumen-argumen itu lewat capability World yang sama dengan yang menyediakan I/O.

zero build

Saat kamu butuh hasil build, pakai build:

zero build hello.0

Compiler menghasilkan executable native di sebelah file sumbermu (atau di folder build package kalau kamu bekerja di dalam package). Kamu bisa menjalankannya seperti program lain. Tidak perlu runtime terpisah karena binary Zero sudah lengkap dengan sendirinya.

Binary Zero berukuran kecil. Target desain proyek ini adalah executable di bawah 10KB untuk program sederhana, yang dicapai dengan tidak memakai toolchain LLVM dan langsung menghasilkan kode yang ringkas.

zero test

Menjalankan target test sebuah package:

zero test

Test berada bersama kode sumber di dalam src/, dan dideklarasikan sebagai target test di zero.json milik package. Test runner menemukannya, menjalankan satu per satu, lalu melaporkan lulus atau gagal. Dengan --json, output-nya terstruktur per test (nama, status, durasi, diagnostik yang tertangkap) untuk agen dan tooling CI.

Package Zero membahas cara mendeklarasikan target test di zero.json.

zero fix

fix memakai metadata perbaikan yang dihasilkan oleh check --json. Ada dua mode:

zero fix --plan --json   # show the structured plan, don't apply
zero fix                 # apply the plan in place

Sebuah rencana kira-kira terlihat seperti ini (strukturnya hanya ilustrasi):

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

Idenya, agen mengambil rencana itu, memutuskan apakah rencana itu bisa dipercaya, lalu langsung menerapkannya atau menyerahkannya ke langkah penalaran yang lebih tinggi. Rencana berupa data, jadi agen tidak perlu menafsirkan kalimat untuk mengambil tindakan.

zero explain

explain adalah sisi kalimat dari sistem diagnostik:

zero explain NAM003

Perintah ini menampilkan penjelasan kode error yang mudah dibaca manusia: artinya, kenapa compiler menghasilkannya, dan seperti apa perbaikan yang biasa dilakukan. Berguna saat:

• Manusia sedang men-debug dan butuh jawaban yang lebih panjang daripada pesan singkatnya.
• Agen menemukan kode diagnostik yang tidak ada di data latihannya dan butuh konteks tambahan.

Kodenya sendiri stabil di semua versi compiler, jadi penjelasan yang sudah disimpan tetap berlaku.

zero new

Membuat kerangka package baru:

zero new cli hello

Perintah ini membuat folder hello/ berisi manifest zero.json dan file awal src/main.0. Argumen pertama (di sini cli) memilih template, dalam contoh ini aplikasi command line yang bisa dieksekusi. Package Zero menjelaskan struktur foldernya secara detail.

Biasakan Memakai --json

Hampir setiap perintah mendukung --json. Kalau kamu membangun tooling, harness untuk agen, atau pipeline CI di sekitar Zero, pakai bentuk JSON secara default. Bentuk ini:

• Stabil. Skemanya diberi versi, dan timnya memperlakukannya sebagai kontrak.
• Lengkap. Kamu mendapat field yang tidak ada di output untuk manusia (span yang presisi, ID rencana perbaikan, data dependency graph).
• Mudah di-parse. Tidak perlu regex atas kalimat bahasa Inggris untuk mengambil nomor baris.

Untuk manusia, jangan pakai --json: teks yang diformat itulah yang kamu butuhkan di terminal.

Perintah Berguna Lainnya

Beberapa perintah yang lebih jarang dipakai, tetapi tetap perlu kamu kenal:

• 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.
• zero size --json: melaporkan ukuran hasil kompilasi di disk, dirinci per target. Membantu kalau kamu peduli pada ukuran binary (yang merupakan salah satu target desain Zero).
• zero --version: menampilkan versi toolchain. Catat versinya di suatu tempat kalau kamu bekerja dalam tim, karena Zero masih di bawah 1.0 dan perubahan yang merusak kompatibilitas memang terjadi.

Berikutnya: Package Zero

Satu file .0 sudah cukup untuk hello world. Proyek sungguhan memakai package dengan manifest zero.json dan folder src/. Package Zero menunjukkan cara membuat kerangkanya dan menjelaskan setiap field.