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

Что даёт CLI

Бинарник zero — это весь тулчейн разработки. Никаких отдельных менеджеров пакетов, форматтеров, линтеров или test-раннеров — всё это подкоманды zero. Это держит поверхность маленькой и предсказуемой, что и есть смысл.

Короткое меню команд, к которым будете обращаться чаще всего:

Команда	Что делает
zero check	Проверка типов исходника без производства исполняемого.
zero run	Компиляция и запуск одним шагом.
zero build	Компиляция в нативный исполняемый файл.
zero test	Запуск тестовых целей пакета.
zero fix	Применение или предпросмотр структурированных планов починки.
zero explain	Поиск прозы-объяснения для кода диагностики.
zero new	Скаффолд нового пакета.
zero --version	Вывод версии тулчейна.

У каждой из них есть --json для машинно-читаемого вывода вместо человеческого текста.

zero check

Рабочая лошадка. zero check запускает статические проверки компилятора — парсинг, проверку типов, вывод capability и эффектов, поиск пропущенных импортов — и останавливается до генерации кода. Работает быстро, что важно, потому что агенты и редакторы дёргают её постоянно.

zero check hello.0

Чистый вывод (ничего не печатается, exit 0) означает, что файл корректен. Ошибки по умолчанию выходят человеческим текстом. Добавьте --json — и получите структурированную форму, которую потребляют агенты:

zero check hello.0 --json

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

Форма диагностики полностью описана в JSON-диагностике. Обратите внимание на стабильное поле code — NAM003 всегда означает «unknown identifier», независимо от версии компилятора.

check можно направить и на каталог пакета вместо одного файла:

zero check ./my-package

Он читает zero.json, обходит дерево исходников и сообщает о каждой проблеме во всех целях.

zero run

run компилирует и запускает одним шагом. Удобен, когда итерируете на маленькой программе и не хотите получить бинарник на диске.

zero run hello.0

Эквивалентно zero build плюс вызову собранного бинарника, разве что артефакт выбрасывается. Stdout вашей программы прокидывается в stdout терминала — вызовы world.out.write приземляются на ваш экран.

Если программе нужны аргументы, передавайте их после --:

zero run greet.0 -- Alice

Рантайм даёт программе доступ к этим аргументам через тот же capability World, который выставляет I/O.

zero build

Когда нужен артефакт, используйте build:

zero build hello.0

Компилятор производит нативный исполняемый файл рядом с исходником (или под каталогом сборки пакета, если работаете в пакете). Запускать его можно как любую другую программу — отдельный рантайм не нужен, потому что бинарники Zero самодостаточны.

Бинарники Zero маленькие. Дизайн-цель проекта — исполняемые файлы меньше 10 КБ для тривиальных программ; добиваются этого, пропуская тулчейн LLVM и эмитируя компактные пути кода напрямую.

zero test

Запуск тестовых целей пакета:

zero test

Тесты живут рядом с исходником в src/ и объявляются как тестовые цели в zero.json пакета. Раннер их обнаруживает, выполняет каждый и выдаёт pass/fail. С --json вывод структурирован по каждому тесту — имя, статус, длительность, захваченные диагностики — для агентов и тулинга CI.

Zero packages разбирает объявление тестовых целей в zero.json.

zero fix

fix потребляет метаданные починки, которые производит check --json. У неё два режима:

zero fix --plan --json   # показать структурированный план, не применять
zero fix                 # применить план на месте

План выглядит примерно так (форма иллюстративная):

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

Идея в том, что агент подтягивает план, решает, доверять ли ему, и либо применяет напрямую, либо передаёт его шагу более высокоуровневого рассуждения. Планы — это данные; агенты не разбирают прозу, чтобы действовать.

zero explain

explain — это проза-сторона системы диагностики:

zero explain NAM003

Печатает человеческое объяснение кода ошибки — что он означает, почему компилятор его выдаёт, как выглядят типичные починки. Полезно когда:

• Отлаживает человек и хочет более длинного ответа, чем встроенное сообщение.
• Агент столкнулся с кодом диагностики, которого не было в обучающих данных, и хочет больше контекста.

Сам код стабилен между версиями компилятора, поэтому закэшированные объяснения остаются валидны.

zero new

Скаффолдинг свежего пакета:

zero new cli hello

Создаёт каталог hello/ с манифестом zero.json и стартовым src/main.0. Первый аргумент (cli здесь) выбирает шаблон — в этом случае исполняемое CLI-приложение. Zero packages подробно объясняет layout.

Привычка к --json

Почти каждая команда поддерживает --json. Если вы строите тулинг, агентский harness или CI-пайплайн вокруг Zero, по умолчанию берите JSON-форму. Она:

• Стабильна. Схема версионирована, и команда трактует её как контракт.
• Полна. Получите поля, которых нет в человеческом выводе (точные диапазоны, ID планов починки, данные графа зависимостей).
• Парсится. Никаких регулярок над английской прозой ради номера строки.

Для людей оставляйте --json выключенным — отформатированный текст — это то, что нужно в терминале.

Другие полезные команды

Несколько менее часто используемых команд, которые стоит знать:

• zero graph --json — отдаёт граф зависимостей пакета как структурированные данные. Полезно, чтобы понять, что от чего зависит, и для агентов, которые хотят рассуждать о местах вызова.
• zero size --json — отчёт о размере собранных артефактов на диске, в разбивке по целям. Полезно, когда важен размер бинарника (а это дизайн-цель Zero).
• zero --version — печатает версию тулчейна. Запишите её где-то у себя в команде — Zero pre-1.0, и ломающие изменения случаются.

Дальше: Zero Packages

Одного файла .0 достаточно для hello-world. Реальные проекты используют пакеты с манифестом zero.json и каталогом src/. Zero Packages показывает, как скаффолдить такой и объясняет каждое поле.