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/Python artifacts. dev обслуживает и пересобирает только package-mode web-app на loopback. fmt, lsp, doc, explain, refactor, migrate и package commands используют ту же source/version model. Публичный CLI Topaz 5.7.0 включает цель web-app и команду dev.
Рабочий процесс
Для явного unit передайте entry и при необходимости --root; без entry работает package mode. --language-version выбирает compatibility lane, default — 5.6. 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 пропускаются.
В Topaz 5.6.4 команда check --profile agent-pack проверяет допустимые формы исходного кода поверх канонического режима topaz-5.7 до запуска программы. Она отклоняет и те формы, которые допустимы в языке, но исключены из agent-pack. В режиме JSON stderr содержит поток JSONL topaz.profile-diagnostic/v1 с профилем, правилом, диапазоном исходного текста и автоматически применимым исправлением только для однозначной замены идентификатора; stdout содержит единственную сводку topaz.profile-check/v1. Профиль test-profile явно разрешает каноническую тестовую функцию assert(...). Метки блоков кода, самодостаточность примеров и ссылки на SPEC по-прежнему проверяются при рецензировании пакета или документации; правила public-docs для текста, перевода и метаданных страницы также остаются вне компилятора.
Текущая поддержка
Текущий публичный командный инструмент 5.7.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 check --profile agent-pack --format json src/main.tpz
topaz fmt --check --root .
topaz explain TPZ5021 --json
topaz test --root . src/main.tpz -- arg1