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

Co daje CLI

Plik binarny zero to cały toolchain deweloperski. Nie ma osobnego menedżera pakietów, formatera, lintera ani narzędzia do testów: wszystko to są podpolecenia zero. Dzięki temu powierzchnia jest mała i przewidywalna, i właśnie o to chodzi.

Krótka lista najczęściej używanych poleceń:

Każde z nich przyjmuje --json, aby zwrócić wyjście czytelne maszynowo zamiast tekstu sformatowanego dla ludzi.

zero check

Koń pociągowy. zero check uruchamia statyczne sprawdzenia kompilatora (parsowanie, sprawdzanie typów, wnioskowanie capabilities i efektów, wykrywanie brakujących importów) i zatrzymuje się przed generowaniem kodu. Jest szybkie, co ma znaczenie, bo agenci i edytory wywołują je bez przerwy.

zero check hello.0

Czyste wyjście (nic nie zostaje wypisane, kod wyjścia 0) oznacza, że plik jest poprawnie zbudowany. Błędy domyślnie pojawiają się jako tekst czytelny dla ludzi. Dodaj --json, a dostaniesz ustrukturyzowaną formę, z której korzystają agenci:

zero check hello.0 --json

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

Kształt komunikatów diagnostycznych jest w pełni opisany w artykule Diagnostyka w JSON. Zwróć uwagę na stabilne pole code: NAM003 zawsze oznacza "nieznany identyfikator", niezależnie od wersji kompilatora.

Możesz też wskazać check katalog pakietu zamiast pojedynczego pliku:

zero check ./moj-pakiet

Polecenie czyta zero.json, przechodzi przez drzewo źródeł i zgłasza każdy problem we wszystkich celach.

zero run

run kompiluje i uruchamia w jednym kroku. Najlepsze, gdy pracujesz nad małym programem i nie zależy ci na pliku binarnym na dysku.

zero run hello.0

Działa jak zero build i uruchomienie powstałego pliku binarnego, tyle że artefakt jest wyrzucany. Stdout twojego programu trafia na stdout terminala: wywołania world.out.write pojawiają się na ekranie.

Jeśli program potrzebuje argumentów, przekaż je po --:

zero run greet.0 -- Alice

Środowisko uruchomieniowe daje programowi dostęp do tych argumentów przez tę samą capability World, która udostępnia I/O.

zero build

Gdy potrzebujesz artefaktu, użyj build:

zero build hello.0

Kompilator tworzy natywny plik wykonywalny obok pliku źródłowego (albo w katalogu build pakietu, jeśli pracujesz w pakiecie). Uruchamiasz go jak każdy inny program: nie trzeba osobnego środowiska uruchomieniowego, bo pliki binarne Zero są samowystarczalne.

Pliki binarne Zero są małe. Celem projektu są pliki wykonywalne poniżej 10 KB dla prostych programów, co osiąga się przez pominięcie toolchaina LLVM i bezpośrednie generowanie zwartego kodu.

zero test

Uruchom cele testowe pakietu:

zero test

Testy leżą obok kodu źródłowego w src/ i są zadeklarowane jako cele testowe w zero.json pakietu. Narzędzie je wykrywa, uruchamia każdy i zgłasza, czy przeszedł. Z --json wyjście jest ustrukturyzowane dla każdego testu (nazwa, status, czas trwania, przechwycona diagnostyka) na potrzeby agentów i narzędzi CI.

Artykuł Pakiety Zero pokazuje, jak deklarować cele testowe w zero.json.

zero fix

fix korzysta z metadanych naprawy, które zwraca check --json. Działa w dwóch trybach:

zero fix --plan --json   # pokazuje ustrukturyzowany plan, nie stosuje go
zero fix                 # stosuje plan w miejscu

Plan wygląda mniej więcej tak (kształt jest poglądowy):

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

Chodzi o to, że agent pobiera plan, decyduje, czy mu zaufać, i albo stosuje go bezpośrednio, albo przekazuje do wyższego poziomu rozumowania. Plany to dane; agenci nie muszą interpretować prozy, aby działać.

zero explain

explain to prozatorska strona systemu diagnostyki:

zero explain NAM003

Wypisuje czytelne wyjaśnienie kodu błędu: co oznacza, dlaczego kompilator go zgłasza i jak wyglądają typowe poprawki. Przydaje się, gdy:

• Człowiek debuguje i chce dłuższej odpowiedzi niż komunikat w linii.
• Agent trafia na kod diagnostyczny, którego nie było w jego danych treningowych, i potrzebuje więcej kontekstu.

Sam kod jest stabilny między wersjami kompilatora, więc zapisane wyjaśnienia pozostają aktualne.

zero new

Utwórz szkielet nowego pakietu:

zero new cli hello

To polecenie tworzy katalog hello/ z manifestem zero.json i startowym plikiem src/main.0. Pierwszy argument (tutaj cli) wybiera szablon, w tym przypadku wykonywalną aplikację wiersza poleceń. Artykuł Pakiety Zero szczegółowo omawia ten układ.

Nawyk --json

Niemal każde polecenie obsługuje --json. Jeśli budujesz narzędzia, środowisko dla agenta albo potok CI wokół Zero, domyślnie używaj formy JSON. Jest ona:

• Stabilna. Schemat jest wersjonowany, a zespół traktuje go jak umowę.
• Kompletna. Dostajesz pola, których nie ma w wyjściu dla ludzi (dokładne zakresy, identyfikatory planów naprawy, dane grafu zależności).
• Łatwa do parsowania. Żadnych wyrażeń regularnych na angielskiej prozie, żeby wyciągnąć numer linii.

Ludzie mogą pominąć --json: w terminalu potrzebny jest właśnie sformatowany tekst.

Inne przydatne polecenia

Kilka rzadziej używanych poleceń, które warto znać:

• zero graph --json: zwraca graf zależności pakietu jako ustrukturyzowane dane. Przydaje się do zrozumienia, co od czego zależy, oraz agentom, które chcą analizować miejsca wywołań.
• zero size --json: raportuje rozmiar skompilowanych artefaktów na dysku z podziałem na cele. Pomocne, gdy zależy ci na rozmiarze pliku binarnego (co jest jednym z celów projektowych Zero).
• zero --version: wypisuje wersję toolchaina. Zapisz ją gdzieś, jeśli pracujesz w zespole: Zero jest przed wersją 1.0 i niezgodne zmiany naprawdę się zdarzają.

Dalej: pakiety Zero

Pojedynczy plik .0 wystarczy do hello world. Prawdziwe projekty używają pakietów z manifestem zero.json i katalogiem src/. Artykuł Pakiety Zero pokazuje, jak utworzyć pakiet, i objaśnia każde pole.