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/web-app/http-service/Python artifacts. dev запускает package-mode web-app или ограниченный HTTP-сервис на loopback. fmt, lsp, doc, explain, refactor и package commands используют ту же source model.
Рабочий процесс
Для явного unit передайте entry и при необходимости --root; без entry работает package mode. --language-version нужен только для сознательного выбора compatibility lane; default — текущий язык. Human diagnostics предназначены для чтения, --format json и explain --json дают стабильные machine fields/codes. Аргументы программы идут после --.
topaz fmt --check использует тот же parse-gated formatter и тот же выбор package-файлов, что и topaz fmt, но перечисляет все пути с отличиями и завершается с ненулевым кодом, не изменяя source или metadata. В package mode vendored dependencies и build outputs пропускаются.
Команда check --profile agent-pack проверяет допустимые формы исходного кода поверх канонического языка до запуска программы. Она отклоняет и те формы, которые допустимы в языке, но исключены из agent-pack. В режиме JSON stderr содержит поток JSONL topaz.profile-diagnostic/v1 с профилем, правилом, диапазоном исходного текста и автоматически применимым исправлением только для однозначной замены идентификатора; stdout содержит единственную сводку topaz.profile-check/v1. Профиль test-profile явно разрешает каноническую тестовую функцию assert(...). Метки блоков кода, самодостаточность примеров и ссылки на SPEC по-прежнему проверяются при рецензировании пакета или документации; правила public-docs для текста, перевода и метаданных страницы также остаются вне компилятора.
Проверенные команды emit и build --backend native принимают --native-report-json <путь>. Отчёт объясняет выбор для всего модуля или отдельных функций, не изменяя stdout, stderr и созданные артефакты. Неверный или конфликтующий путь отклоняется до изменения каталога вывода, а JSON публикуется атомарно только после успешного понижения.
Решения по функциям также охватывают точные быстрые пути Bytes и ByteBuffer и доказанные проверяющим прямые бинарные поля record. Более широкий или недоказанный aggregate остаётся boxed со стабильной причиной отказа.
Текущая поддержка
Текущий CLI предоставляет текстовую и 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 check --profile agent-pack --format json src/main.tpz
topaz emit src/main.tpz --backend native --native-report-json native-report.json
topaz fmt --check --root .
topaz explain TPZ5021 --json
topaz test --root . src/main.tpz -- arg1