nova CLI

Quickstart

# Внутри Nova-проекта (рядом есть nova.toml):
nova check                       # type-check всего workspace
nova check src/                  # рекурсивно по директории
nova check src/lib.nv            # одиночный файл

nova run hello.nv                # запустить через интерпретатор
nova build app.nv -o app         # скомпилировать в native binary
nova test                        # запустить все nova_tests/
nova test --filter basics        # подмножество по подстроке

nova doc src/lib.nv              # markdown в stdout
nova doc src/ --format json      # JSON-схема D107
nova doc src/ --check --strict   # CI-валидация документации

nova bench run bench.nv          # запустить бенчмарки
nova contracts verify foo.nv     # SMT-верификация контрактов

Установка и сборка

nova-cli живёт в nova-cli/ рядом с compiler-codegen/. Оба crate самостоятельные (workspace не используется).

# Debug-сборка (default, opt-level=0)
cargo build --manifest-path nova-cli/Cargo.toml

# Release (opt-level=2, LTO thin)
cargo build --release --manifest-path nova-cli/Cargo.toml

# С Z3-бэкендом для контрактов (Plan 33.1)
cargo build --release --manifest-path nova-cli/Cargo.toml --features z3-backend

Результаты сборки:

• nova-cli/target/{debug,release}/nova[.exe]
• nova-cli/target/{debug,release}/migrate_plan60[.exe]
• nova-cli/target/{debug,release}/migrate_plan65[.exe]

nova имеет path-зависимость на nova_codegen (../compiler-codegen) — rebuild compiler автоматически перекомпилирует CLI.

Глобальные флаги

Применяются ко всем субкомандам:

Авто-детект цвета (priority high → low):

1. CLI --color always|never — принудительно
2. CLICOLOR_FORCE=1 → always
3. NO_COLOR (любое значение) → never
4. CLICOLOR=0 → never
5. CI=true → never
6. TERM=dumb → never
7. По умолчанию — включено

Коды выхода

nova doc --diff дополнительно использует 3 = patch-level breaking change. См. nova doc.

Поиск корня проекта

Большинство команд ищут nova.toml снизу вверх от CWD (workspace-aware, D78 AD6):

1. Идём от CWD вверх до filesystem root.
2. На каждом уровне читаем nova.toml если есть.
3. Если в нём есть [workspace] — это корень, останавливаемся.
4. Иначе запоминаем последний найденный nova.toml и идём дальше.
5. Возвращаем workspace root если найден; иначе — самый верхний nova.toml.

Защищает от ситуации «вложенный nova_tests/nova.toml затмил основной». Если nova.toml не найден — exit 2:

error: nova.toml not found — are you inside a Nova project?

Пути, резолвящиеся под workspace root: nova_tests/, std/, compiler-codegen/, target/last-test-results.json.

nova check

Type-check одного или нескольких .nv файлов / директорий.

nova check [PATHS...] [--jobs N] [-q|-v] [--list] [--format human|short]
           [--include-runtime] [--skip PATTERN]...

Всегда пропускаются: target/, node_modules/, vendor/, .git/, .hg/, .svn/, директории начинающиеся с _ или ., std/runtime/.

Summary: pass=N fail=N warnings=N (X.YYs). Exit 1 при наличии FAIL.

nova run

Запустить .nv-файл через интерпретатор (без компиляции в C).

nova run FILE

FILE — путь к .nv-файлу с fn main.

nova build

Скомпилировать один .nv-файл в native binary (через C-backend).

nova build FILE [-o OUTPUT] [--mode dev|release] [--toolchain auto|clang|msvc|gcc]
           [--vcvars PATH] [--clang PATH] [--timeout SECS] [--keep-artifacts]
           [--mono-depth N]

Только один файл за раз. Для multi-file проектов используй import внутри entry-point.

Pipeline: parse + typecheck + infer_effects → C emit → toolchain detect → libuv detect/build → compile → copy → cleanup tmp.

nova test

Запуск тестов из директории или файла.

nova test [PATH] [--filter SUBSTR] [--jobs N] [--format text|json|tap|junit]
          [--mode dev|release] [--toolchain auto|clang|msvc|gcc]
          [--vcvars PATH] [--clang PATH] [--timeout SECS] [-v|-q]
          [--results-file PATH] [--rerun-failed] [--retries N]
          [--include-stdlib] [--keep-artifacts] [--gc boehm|malloc]
          [--list] [--filter-from PATH] [--shuffle [SEED]]
          [--skip PATTERN]... [--mono-depth N]

Форматы вывода: text (человекочитаемый, цветной), json (массив с name/status/duration_ms/stderr), tap (TAP v13), junit (JUnit XML для CI-агрегаторов).

EXPECT-маркеры в тестовых файлах:

• // EXPECT: <stdout-line> — точное совпадение строки
• // EXPECT_STDERR: <line> — для stderr
• // EXPECT_COMPILE_ERROR: <substring> — должно упасть при компиляции
• // EXPECT_RUNTIME_ERROR: <substring> — panic с подстрокой
• // REQUIRES_SMT_BACKEND — пропуск если SMT недоступен

nova test-build

Build + run одного тестового файла. Используется IDE / CI для точечной отладки.

nova test-build FILE [--mode dev|release] [--toolchain auto|clang|msvc|gcc]
                [--vcvars PATH] [--clang PATH] [--timeout SECS]
                [--keep-artifacts] [--gc boehm|malloc] [--mono-depth N]

Эквивалентно nova test <FILE>, но без machinery для bulk-runner'а. Дефолты: --timeout 60, --gc boehm, --mono-depth 500.

nova regen-runtime

Регенерация std/runtime/*.nv стабов из compiler-runtime реестра. Заменяет regen_runtime.ps1.

nova regen-runtime [--check]

nova doc

Production-grade документация (Plan 45 / D107). Markdown / JSON / HTML + doc-tests + coverage + mutation testing + watch + workspace-mode.

nova doc [FILE] [--format markdown|json|html] [--json-schema]
         [--include-private] [--test] [--check] [--watch]
         [--coverage [--coverage-threshold PERCENT]] [--jobs N]
         [--diff OLD NEW] [--scrape-examples WORKSPACE]
         [--strict] [--mutate-contracts [--real-exec]]
         [--output-dir DIR]

Exit-коды для --diff OLD NEW:

Mutation testing (--mutate-contracts): генерирует мутанты для каждой функции с контрактами (>↔>=, ==↔!=, дроп requires/ensures). Default — text heuristic (~1 мс/мутант). С --real-exec — запускает мутированные doc-tests (~100 мс/мутант, true positive guarantee).

Doc-комментарии

Используются два вида:

• /// (outer) — относится к следующей декларации.
• //! (inner) — относится к module целиком.

//! Модульный doc — описание всего файла.

module my.module

/// Краткое summary в одно предложение.
///
/// Длинное описание ниже. Может занимать несколько строк.
///
/// # Examples
///
/// ```nova
/// let x = double(3)
/// assert(x == 6)
/// ```
export fn double(x int) -> int => x * 2

Секции

Распознаются стандартные секции (D107, fixed order):

Другие # Heading сохраняются в текущей секции как часть text'а.

Intra-doc ссылки

/// Возвращает [Point] для координаты.
/// См. также [translate] и [std.math.abs].

Резолвинг:

• [Name] — short-match по item-id.
• [Type.method] — короткая форма метода.
• [mod.path.Name] — fully-qualified.

Broken links → target_id: null в JSON и сообщение от nova doc --check.

Doc-тесты

```nova-блоки в doc'е — это doc-tests, исполняемые nova doc --test.

Модификаторы

```nova,no_run        — компилируется, не запускается
```nova,ignore        — не компилируется (только display)
```nova,compile_fail  — ожидается compile-error
```nova,should_panic  — ожидается runtime panic
```nova,must_verify   — ожидается successful SMT verify

Можно комбинировать: ```nova,no_run,ignore.

Скрытые строки

Строки # code скрыты в визуальном выводе, но включаются в компиляцию:

/// ```nova
/// # import std.io
/// let r = compute()
/// assert(r == 42)
/// ```

Стабильность и deprecation

Через секции (version-based):

/// API.
///
/// # Since
///
/// 1.0.0
export fn add(a int, b int) -> int => a + b

# Since >= 1.0 → stability.tier = "stable", иначе unstable.

Через doc-attrs (D96 синтаксис #name(...) — пишется отдельной строкой между doc-comment'ом и item'ом, не внутри ///):

/// Экспериментальное API.
#experimental(note = "may change in 0.5")
#since("0.3.0")
export fn experimental_api() -> int => 0

#deprecated приоритетнее, чем # Deprecated section.

JSON-вывод

D107 schema v1. Ключи в алфавитном порядке, byte-for-byte deterministic. Top-level fields:

• format_version: 1
• nova_version: "0.1.0"
• generated_at — опускается по умолчанию; управляется через NOVA_DOC_GENERATED_AT или SOURCE_DATE_EPOCH.
• doc_tests[] — извлечённые ```nova блоки.
• links[] — intra-doc-links (resolved + broken).
• modules[] — DocModule entries.
• items[] — DocItem entries (fn/type/const/effect/protocol).

Полная спецификация: nova doc --json-schema.

jq-рецепты

# Список всех public fn с summary
nova doc src/api.nv --format json \
  | jq '[.items[] | select(.kind=="fn" and .visibility=="export") | {id,summary}]'

# Все items без summary (не задокументированные)
nova doc src/api.nv --format json \
  | jq '[.items[] | select(.summary == null) | .id]'

# Все #unstable или #experimental items
nova doc src/api.nv --format json \
  | jq '[.items[] | select(.stability.tier != null and .stability.tier != "stable") | {id, tier: .stability.tier}]'

# Все #deprecated items с заменой
nova doc src/api.nv --format json \
  | jq '[.items[] | select(.deprecation != null) | {id, note: .deprecation.note}]'

# Функции с @realtime
nova doc src/api.nv --format json \
  | jq '[.items[] | select(.capabilities.realtime==true) | .id]'

# Функции с SMT-контрактами (Proven)
nova doc src/api.nv --format json \
  | jq '[.items[] | select(.signature?.verify_status=="proven") | .id]'

# Все re-exports (doc_inline=true)
nova doc src/api.nv --format json \
  | jq '[.items[] | select(.kind=="reexport" and .doc_inline==true) | {id, source: .reexport_from}]'

# Items с scraped examples
nova doc src/api.nv --format json --scrape-examples . \
  | jq '[.items[] | select(.scraped_examples | length > 0) | {id, count: (.scraped_examples | length)}]'

# Все broken intra-doc links (target_id == null)
nova doc src/api.nv --format json \
  | jq '[.links[] | select(.target_id == null) | .text]'

# Семver diff: список major changes
nova doc --diff old.json new.json 2>&1 | grep '\[major\]'

CI-интеграция

# Проверить, что doc валиден (broken links, missing summaries)
nova doc src/api.nv --check

# Прогнать doc-tests (exit 1 на failure)
nova doc src/api.nv --test

# Reproducible builds
SOURCE_DATE_EPOCH=1700000000 nova doc src/api.nv --format json > api.json

Стиль (§11.5)

1. Первое предложение — summary, терминатор ..
2. Imperative mood: "Returns X" а не "This function returns X".
3. Fixed section order (см. таблицу выше).
4. Markdown subset: CommonMark + ```nova fenced blocks.
5. Examples обязательны для public fn.
6. Deprecation note содержит замену + # Since.
7. Stability tiers: stable / unstable / experimental.

nova doc-query

DSL-запросы к JSON-выводу nova doc --format json (Plan 45). Фундамент для MCP-сервера.

nova doc-query JSON_FILE [QUERY]

Синтаксис query: key=value,key=value,...

nova doc src/ --format json > out.json
nova doc-query out.json "kind=fn,capability=pure"
nova doc-query out.json "name=add,has-contracts=true"
nova doc-query out.json "module-prefix=std,effect=Fs"

Пустой query → весь файл as-is.

nova doc-mcp

MCP-сервер (Model Context Protocol) — JSON-RPC over stdio или HTTP. Совместим с MCP-клиентами (Claude Code, MCP Inspector).

nova doc-mcp FILE [--port PORT]

Tools (через tools/list):

• query_items(query) — поиск через DSL (см. nova doc-query)
• list_modules() — список module-путей
• get_item(item_id) — полный JSON одного item

Protocol: MCP-клиент шлёт initialize → tools/list → tools/call.

nova contracts

Инспекция и верификация контрактов (Plan 33 / D24). Output — JSON (AI-friendly schema, см. docs/contracts-diag-schema.json).

nova contracts list

Список всех контрактов в файле.

nova contracts list FILE

nova contracts verify

SMT-верификация контрактов. Z3-бэкенд требует build с --features z3-backend.

nova contracts verify FILE [--backend BACKEND]

nova contracts suggest

AI-assisted предложения для контрактов (стабы).

nova contracts suggest FILE FN_NAME

nova contracts counterexample

Контрпример для падающего контракта.

nova contracts counterexample FILE FN_NAME [--contract-id N]

nova bench

Бенчмарк-инфраструктура (Plan 57). Субкоманды:

run · diff · gate · calibrate · cpu-instr-check · membw-check · hyperfine · callgrind · callgrind-check · runner-branch · history-anomalies / history-add / history-list / history-squash · remote · corpus · dashboard

nova bench run

Запустить bench "..." { measure { ... } } декларации в файле.

nova bench run FILE [--filter PATTERN] [--samples N] [--warmup-ms MS]
                    [--time-budget SECS] [--gc boehm|malloc]
                    [--mode release|dev] [--toolchain auto|clang|msvc|gcc]
                    [--compile-timeout SECS] [--run-timeout SECS]
                    [--keep-artifacts] [--mono-depth N]
                    [--out PATH] [--out-csv PATH] [--out-md PATH]
                    [--out-criterion DIR] [--profile MODE OUT]
                    [--histogram]

Output-форматы: --out (JSON v1 с git SHA, toolchain, CPU model); --out-criterion (<dir>/<name>/new/{estimates,sample,benchmark}.json); --out-md (markdown-таблица для PR); --histogram (40 buckets, Unicode blocks, медиана + Tukey fences).

Profile-режимы: cpu — заворачивает в samply (нужен cargo install samply); heap — NOVA_BENCH_HEAP_SAMPLE_MS=10; gc — NOVA_BENCH_GC_TRACE=1.

nova bench diff

Сравнение двух bench-результатов. Welch's t-test, geomean delta, reproducibility check.

nova bench diff BASELINE NEW [--format terminal|markdown|json]
                              [--explain [--ai-config PATH] [--ai-max-tokens N] [--ai-dry-run]]
                              [--baseline-sha SHA] [--new-sha SHA]

--explain использует system curl и требует NOVA_AI_API_KEY или конфиг.

nova bench gate

CI-gate: применяет пороги из bench.toml. Exit 0 = pass, 1 = regression.

nova bench gate BASELINE NEW [--config PATH] [--noise PATH]

nova bench calibrate

Авто-калибровка noise-floor из ≥2 повторных прогонов того же baseline.

nova bench calibrate RUNS... [--out PATH]

Файл machine-specific; в git добавлять не нужно.

nova bench cpu-instr-check

Диагностика доступности CPU-instruction-counter. Linux: проверяет perf_event_open. Other OS: stub.

nova bench cpu-instr-check

nova bench membw-check

Диагностика memory-bandwidth measurement. Linux: probes /sys/devices/uncore_imc_*. Other OS: stub.

nova bench membw-check

nova bench hyperfine

Hyperfine-style cross-binary timing. Output совместим с nova bench diff.

nova bench hyperfine SPECS... [--warmup N] [--samples N]
                              [--timeout SECS] [--workdir PATH] [--out PATH]

nova bench hyperfine \
  "old=./nova-old build large.nv" \
  "new=./nova-new build large.nv" \
  --samples 10 --warmup 2 --out result.json

nova bench callgrind

Запуск под Valgrind Callgrind — deterministic CPU-instructions count. Работает на macOS + Linux при наличии valgrind.

nova bench callgrind BINARY [ARGS...] [--cache-sim] [--workdir PATH] [--out PATH]

nova bench callgrind-check — проверить наличие и версию valgrind.

nova bench runner-branch — рекомендованное имя history-branch на основе NOVA_BENCH_RUNNER_ID (возвращает bench-history или bench-history-<id>).

nova bench remote

SSH-distributed bench coordination.

nova bench remote list [--config PATH]           # список remotes
nova bench remote ping NAME [--config PATH]      # SSH health-check
nova bench remote run BENCH [--remotes LIST] [--gather-into DIR] [--sha SHA] [--config PATH]

Remote config: ~/.nova-bench-remotes.toml (override через NOVA_BENCH_REMOTES).

nova bench corpus PATH — per-pass compile time. Флаги: --json, --html PATH, --echarts-url URL, --mode, --toolchain, --gc.

nova bench history

Управление orphan history-branch для CI regression tracking.

# Добавить результат в history-branch
nova bench history-add RESULT [--branch BRANCH] [--push] [--remote NAME] [--dry-run]

# Список entries (newest first)
nova bench history-list [--branch BRANCH]

# Squash старых entries по дате (рекомендуется ежегодно)
nova bench history-squash --before-date YYYY-MM-DD [--branch BRANCH] [--push] [--remote NAME] [--dry-run]

# Детекция changepoints в historical median time-series (PELT)
nova bench history-anomalies [--branch BRANCH] [--format text|json]

Default history branch: bench-history (или bench-history-<NOVA_BENCH_RUNNER_ID> для multi-runner CI).

nova bench dashboard

Статический HTML dashboard из history.

nova bench dashboard [--history-branch BRANCH] [--out DIR] [--max-entries N] [--echarts-url URL]

Генерирует index.html + bench-<safe>.html per bench + data.json.

Переменные окружения

Migration-бинарники

Одноразовые lexer-based инструменты в nova-cli/src/bin/. Хранятся в репозитории как reference для будущих атомарных API-rename планов.

migrate_plan60

Миграция field-style size-accessors в method-form (D117 / Plan 60):

migrate_plan60 [--apply] [--dry-run] [--md] [--paths DIR...]

Skip condition: предыдущий значимый token == = (method-value assignment). Комментарии / whitespace / formatting сохраняются 1:1.

migrate_plan65

Миграция Time.after(<lit>) → ChanReader.close_after(Duration.from_*(<lit>)) (Plan 65 AD11):

migrate_plan65 [--apply] [--dry-run] [--md] [--paths DIR...]

Специальные exit-коды: