CLI держится на одном invariant: run, test, emit, build проходят тот же parse/resolve/type gate, что и check. Static failure останавливает выполнение или artifact production и выдаётся как Topaz diagnostic.
Контракт и компоненты
parse/dump-ast исследуют syntax; check проверяет unit и может выдавать deterministic JSON diagnostics или exports; run интерпретирует; test использует TestHost; emit lowering в Rust; build создаёт native/web/web-worker/Python artifacts. fmt, lsp, doc, explain, refactor, migrate и package commands используют ту же source/version model.
Рабочий процесс
Для явного unit передайте entry и при необходимости --root; без entry работает package mode. --language-version выбирает compatibility lane, default — 5.6. Human diagnostics предназначены для чтения, --format json и explain --json дают стабильные machine fields/codes. Аргументы программы идут после --.
Текущая поддержка
Командный инструмент 5.6.0 предоставляет текстовую и JSON-диагностику, проверку всей программы, выбор версии языка, форматирование, LSP, рефакторинг, миграцию, пакеты и создание документации. Примеры руководства проверяются теми же командами.
Границы и ограничения
--unchecked пропускает static gate для исследования runtime/emitter; это не нормальный workflow и не checked conformance. --backend native работает только checked и может fallback к boxed для недоказанных shapes. Foreign tool error не заменяет primary Topaz diagnostic.
Справочник команд
topaz check --root . src/main.tpz
topaz check --format json src/main.tpz
topaz explain TPZ5021 --json
topaz test --root . src/main.tpz -- arg1