Justfile

# bitnet-rs development commands

set dotenv-load := false

# Show available commands
help:
    @just --list

# Run all pre-tag MVP validation checks
mvp-pretag:
    cargo clippy --workspace --all-targets --no-default-features --features cpu -D warnings
    cargo test --workspace --no-default-features --features cpu
    BITNET_STRICT_MODE=1 BITNET_DETERMINISTIC=1 RAYON_NUM_THREADS=1 \
    cargo run -p xtask --no-default-features --features inference -- \
      verify-receipt --path docs/baselines/20251015-cpu.json

# Build release binaries and generate checksums
mvp-build:
    cargo build --release -p bitnet-cli --no-default-features --features cpu,full-cli
    cargo build --release -p bitnet-st2gguf
    cd target/release && shasum -a 256 bitnet st2gguf > SHA256SUMS && cat SHA256SUMS

# Smoke test gate validation (expect failures on bad receipts)
gate-smoke:
    @echo "Testing mocked compute path (should fail)..."
    jq '.compute_path = "mock"' docs/baselines/20251015-cpu.json > /tmp/bad-compute.json
    cargo run -p xtask --no-default-features --features inference -- \
      verify-receipt --path /tmp/bad-compute.json && echo "❌ UNEXPECTED PASS" || echo "✓ EXPECTED FAIL"
    @echo ""
    @echo "Testing empty kernels (should fail)..."
    jq '.kernels = []' docs/baselines/20251015-cpu.json > /tmp/bad-kernels.json
    cargo run -p xtask --no-default-features --features inference -- \
      verify-receipt --path /tmp/bad-kernels.json && echo "❌ UNEXPECTED PASS" || echo "✓ EXPECTED FAIL"
    @echo ""
    @echo "Testing invalid schema version (should fail)..."
    jq '.schema_version = "0.9.0"' docs/baselines/20251015-cpu.json > /tmp/bad-schema.json
    cargo run -p xtask --no-default-features --features inference -- \
      verify-receipt --path /tmp/bad-schema.json && echo "❌ UNEXPECTED PASS" || echo "✓ EXPECTED FAIL"

# Run CPU test suite with coverage
test-cpu:
    cargo test --workspace --no-default-features --features cpu

# Run TL correctness and stress tests
test-tl-stress:
    cargo test -p bitnet-kernels --no-default-features --features cpu \
      --test tl_packed_correctness -- --test-threads=1
    cargo test -p bitnet-kernels --no-default-features --features cpu \
      --test fuzz_tl_lut_stress -- --test-threads=1

# Build and verify documentation
docs:
    cargo doc --workspace --no-default-features --features cpu --no-deps
    cargo test --doc --workspace --no-default-features --features cpu

# Run docs automation checks (markdownlint, link check, rustdoc)
docs-automation:
    scripts/docs_automation.sh

# Format and lint code
fmt:
    cargo fmt --all
    cargo clippy --workspace --all-targets --all-features -- -D warnings

# Generate a new CPU receipt baseline
receipt-baseline MODEL_PATH='models/microsoft-bitnet-b1.58-2B-4T-gguf/ggml-model-i2_s.gguf':
    BITNET_STRICT_MODE=1 BITNET_DETERMINISTIC=1 RAYON_NUM_THREADS=1 \
    cargo run -p xtask --no-default-features --features inference -- \
      benchmark --model {{MODEL_PATH}} --tokens 128 --deterministic
    cp ci/inference.json docs/baselines/$(date +%Y%m%d)-cpu.json
    @echo "Baseline saved to docs/baselines/$(date +%Y%m%d)-cpu.json"

# Clean build artifacts
clean:
    cargo clean
    rm -rf target/

# Generate TDD receipts and update documentation
tdd-receipts:
    python3 scripts/tdd_receipts.py

# ── GPU Backend Commands ──────────────────────────────────────

# Build with OpenCL/Intel GPU support
build-opencl:
    cargo build --no-default-features --features oneapi

# Build with all GPU backends
build-gpu-all:
    cargo build --no-default-features --features cpu,gpu

# Test OpenCL microcrate
test-opencl:
    cargo test -p bitnet-opencl --no-default-features --features cpu

# Test all GPU microcrates
test-gpu:
    cargo test -p bitnet-opencl -p bitnet-vulkan -p bitnet-webgpu --no-default-features --features cpu

# Run GPU stress tests
test-gpu-stress:
    cargo test -p bitnet-opencl --no-default-features --features cpu -- --ignored stress

# Lint GPU code
lint-gpu:
    cargo clippy -p bitnet-opencl -p bitnet-vulkan -p bitnet-webgpu -p bitnet-gpu-hal --no-default-features --features cpu -- -D warnings

# Run GPU benchmarks
bench-gpu:
    cargo bench --no-default-features --features cpu,bench -- gpu

# Check all GPU feature combinations compile
check-gpu-features:
    cargo check --no-default-features --features cpu
    cargo check --no-default-features --features oneapi
    cargo check --no-default-features --features cpu,oneapi

# GPU device info (if hardware available)
gpu-info:
    @echo "Checking GPU hardware..."
    -clinfo --list 2>/dev/null || echo "clinfo not found"
    -vulkaninfo --summary 2>/dev/null || echo "vulkaninfo not found"

# Full GPU CI check (runs locally)
ci-gpu: lint-gpu test-opencl check-gpu-features
    @echo "GPU CI checks passed!"