Vapora/justfile

# VAPORA Justfile - Namespaced CI/CD Recipe Collection
# Workspace: Rust + Nushell + Provisioning/Nickel
#
# Usage:
#   just           - List all recipes
#   just ci-help  - Show CI namespace recipes
#   just ci-full  - Run complete CI pipeline
#
# Namespace Structure:
#   ci::*          - CI/CD pipelines and checks
#   build::*       - Build recipes
#   test::*        - Test recipes
#   fmt::*         - Format and code quality
#   check::*       - Validation and analysis
#   dev::*         - Development utilities
#   vapora::*      - Vapora-specific operations

set shell := ["nu", "-c"]
set dotenv-load := true

# ============================================================================
# Module Imports
# ============================================================================
mod distro "justfiles/distro.just"

# ============================================================================
# Default & Help
# ============================================================================

[no-cd]
default:
    @just -l

# Show help - usage: just help [module]
help MODULE="":
    #!/usr/bin/env bash
    if [ "{{MODULE}}" = "" ]; then
        echo "📖 VAPORA Justfile Recipes"
        echo "=========================="
        echo ""
        echo "🚀 QUICK START"
        echo "   just ci-full           Complete CI: check + test + build"
        echo "   just ci-quick          Fast checks (format + lint only)"
        echo "   just pre-commit        Pre-commit validation"
        echo ""
        echo "📦 KEY MODULES"
        echo "   just help ci           CI/CD pipelines and checks"
        echo "   just help build        Build recipes"
        echo "   just help test         Test recipes"
        echo "   just help fmt          Format and code quality"
        echo "   just help check        Validation and analysis"
        echo "   just help vapora       Vapora-specific operations"
        echo "   just distro help       Distribution and target builds"
        echo ""
        echo "🔍 OTHER COMMANDS"
        echo "   just -l                List all recipes"
        echo "   just help-full         Comprehensive help"
        echo ""
    elif [ "{{MODULE}}" = "ci" ]; then
        echo "🔧 CI/CD PIPELINES"
        echo "=================="
        echo ""
        echo "Main CI Pipelines:"
        echo "  just ci-full           Complete CI pipeline (check + test + build)"
        echo "  just ci-check          Code quality checks (format + lint + verify)"
        echo "  just ci-lint           Lint all code (strict mode)"
        echo "  just ci-test-all       Run all tests"
        echo ""
        echo "Quick & Dev:"
        echo "  just ci-quick          Fast checks (format + lint only)"
        echo "  just ci-pre-commit     Pre-commit validation"
        echo "  just ci-fast           Fast iteration checks"
        echo ""
        echo "Build Validation:"
        echo "  just ci-build-debug    Debug build"
        echo "  just ci-build-release  Release build (optimized)"
        echo ""
        echo "Advanced:"
        echo "  just ci-main           Main branch comprehensive checks"
        echo ""
    elif [ "{{MODULE}}" = "build" ]; then
        echo "🔨 BUILD RECIPES"
        echo "================"
        echo ""
        echo "  just build-debug       Build workspace (debug mode)"
        echo "  just build-release     Build workspace (release, optimized)"
        echo "  just build-all         Build all crates with per-crate status"
        echo "  just build-crate NAME  Build specific crate"
        echo ""
    elif [ "{{MODULE}}" = "test" ]; then
        echo "🧪 TEST RECIPES"
        echo "==============="
        echo ""
        echo "  just test-all          Run all tests (lib + integration + doc)"
        echo "  just test-lib          Library tests only (fast)"
        echo "  just test-doc          Doc tests only"
        echo "  just test-crate NAME   Test specific crate"
        echo "  just test-coverage     Generate coverage report"
        echo ""
    elif [ "{{MODULE}}" = "fmt" ]; then
        echo "✨ FORMAT & QUALITY"
        echo "==================="
        echo ""
        echo "  just fmt-check         Check formatting without modifying"
        echo "  just fmt-fix           Auto-format all code"
        echo "  just fmt-clippy        Lint code (strict: -D warnings)"
        echo "  just fmt-clippy-vapora Lint only vapora crates"
        echo ""
    elif [ "{{MODULE}}" = "check" ]; then
        echo "🔍 VALIDATION & ANALYSIS"
        echo "========================"
        echo ""
        echo "  just check-code        Quick syntax/dependency check"
        echo "  just check-security    Security audit + cargo-deny"
        echo "  just check-coupling    Analyze coupling metrics (AI suggestions)"
        echo "  just check-unused      Find unused dependencies"
        echo ""
    elif [ "{{MODULE}}" = "vapora" ]; then
        echo "🌊 VAPORA-SPECIFIC"
        echo "==================="
        echo ""
        echo "  just vapora-test-backend     Test vapora-backend"
        echo "  just vapora-test-agents      Test vapora-agents"
        echo "  just vapora-test-llm-router  Test vapora-llm-router"
        echo "  just vapora-test-kg          Test vapora-knowledge-graph"
        echo "  just vapora-test-all         Test all vapora crates"
        echo "  just vapora-check-backend    Check backend (compile + lint)"
        echo "  just vapora-check-agents     Check agents (compile + lint)"
        echo ""
    else
        echo "❌ Unknown module: {{MODULE}}"
        echo ""
        echo "Available modules: ci, build, test, fmt, check, vapora"
    fi

# ============================================================================
# CI/CD Namespace - CI Pipelines & Orchestration
# ============================================================================

ci_help := '''
🔧 VAPORA CI Namespace

CI/CD Pipelines:
  just ci-full           Complete CI pipeline (all checks)
  just ci-check          Code check + format + lint
  just ci-lint           Lint all code (strict)
  just ci-test-all       Test all features
  just ci-build-debug    Debug build
  just ci-build-release  Release build

Pre-commit & Quick:
  just ci-quick          Fast checks (format + lint only)
  just ci-pre-commit     Pre-commit validation
  just ci-fast           Minimal CI for iteration

Main Branch:
  just ci-main           Main branch comprehensive checks

Development:
  just ci-watch          Watch for changes and lint
  just ci-debug          CI with environment info
'''

# Show CI namespace help
[no-cd]
ci-help:
    @echo "{{ci_help}}"

# Complete CI pipeline: check + test + build (strict)
[no-cd]
ci-full: fmt-fix fmt-check fmt-clippy test-all build-debug
    @echo ""
    @echo "✅ Full CI Pipeline Complete"
    @echo ""

# Code quality checks: format + lint + verify
[no-cd]
ci-check: fmt-check fmt-clippy check-code
    @echo ""
    @echo "✅ Code Quality Checks Complete"
    @echo ""

# Lint all code (strict: -D warnings)
[no-cd]
ci-lint: fmt-clippy
    @echo ""
    @echo "✅ Linting Complete"
    @echo ""

# Test all features (lib + integration + doc)
[no-cd]
ci-test-all: test-all
    @echo ""
    @echo "✅ All Tests Complete"
    @echo ""

# Debug build
[no-cd]
ci-build-debug: build-debug
    @echo ""
    @echo "✅ Debug Build Complete"
    @echo ""

# Release build (optimized)
[no-cd]
ci-build-release: build-release
    @echo ""
    @echo "✅ Release Build Complete"
    @echo ""

# Fast CI check: format + lint only (no build/test)
[no-cd]
ci-quick: fmt-check fmt-clippy
    @echo ""
    @echo "✅ Quick Check Complete"
    @echo ""

# Pre-commit hook: format + check + lint vapora crates
[no-cd]
ci-pre-commit: fmt-fix fmt-check fmt-clippy-vapora check-code
    @echo ""
    @echo "✅ Pre-commit Checks Passed"
    @echo ""

# Main branch CI: comprehensive validation
[no-cd]
ci-main: check-code fmt-check fmt-clippy test-all build-debug check-security check-coupling
    @echo ""
    @echo "✅ Main Branch CI Complete"
    @echo ""

# Fast iteration CI: minimal checks
[no-cd]
ci-fast: check-code fmt-clippy-vapora test-lib
    @echo ""
    @echo "✅ Fast CI Complete"
    @echo ""

# ============================================================================
# Build Namespace
# ============================================================================

# Build workspace in debug mode
[no-cd]
build-debug:
    #!/usr/bin/env nu
    print "🔨 Building workspace (debug mode)..."
    cargo build --workspace

# Build workspace in release mode (optimized)
[no-cd]
build-release:
    #!/usr/bin/env nu
    print "🔨 Building workspace (release mode, optimized)..."
    cargo build --release --workspace

# Build all crates with per-crate status
[no-cd]
build-all:
    #!/usr/bin/env nu
    print "🔨 Building all crates in release mode (detailed)..."
    nu ./scripts/build.nu --release

# Build specific crate (arg: NAME=crate_name)
[no-cd]
build-crate NAME='vapora-backend':
    #!/usr/bin/env nu
    print $"🔨 Building (${{ NAME }})..."
    cargo build -p {{ NAME }}

# Build specific crate in release mode
[no-cd]
build-crate-release NAME='vapora-backend':
    #!/usr/bin/env nu
    print $"🔨 Building (${{ NAME }}) in release mode..."
    cargo build --release -p {{ NAME }}

# ============================================================================
# Test Namespace
# ============================================================================

# Run all tests (lib + integration + doc)
[no-cd]
test-all:
    #!/usr/bin/env nu
    print "🧪 Running all tests (workspace)..."
    cargo test --workspace

# Run library tests only (fast, no integration tests)
[no-cd]
test-lib:
    #!/usr/bin/env nu
    print "🧪 Running library tests only..."
    cargo test --lib --no-fail-fast

# Run doc tests only
[no-cd]
test-doc:
    #!/usr/bin/env nu
    print "🧪 Running doc tests..."
    cargo test --doc

# Test specific crate (arg: NAME=vapora-backend)
[no-cd]
test-crate NAME='vapora-backend':
    #!/usr/bin/env nu
    print $"🧪 Testing (${{ NAME }})..."
    cargo test -p {{ NAME }}

# Run tests with output visible
[no-cd]
test-verbose:
    #!/usr/bin/env nu
    print "🧪 Running tests with output..."
    cargo test --workspace -- --nocapture

# Generate coverage report
[no-cd]
test-coverage:
    #!/usr/bin/env nu
    print "🧪 Running tests with coverage..."
    if (which cargo-tarpaulin | is-empty) {
        print "⚠️  cargo-tarpaulin not installed. Install with: cargo install cargo-tarpaulin"
        return 1
    }
    cargo tarpaulin --workspace --out Html --output-dir coverage

# ============================================================================
# Format & Code Quality Namespace
# ============================================================================

# Check formatting without modifying files
[no-cd]
fmt-check:
    #!/usr/bin/env nu
    print "📋 Checking code format..."
    cargo fmt --all -- --check

# Format code using rustfmt
[no-cd]
fmt-fix:
    #!/usr/bin/env nu
    print "✨ Formatting code..."
    cargo fmt --all

# Lint code (strict: -D warnings)
[no-cd]
fmt-clippy:
    #!/usr/bin/env nu
    print "🔗 Linting code (strict mode)..."
    cargo clippy --all-targets -- -D warnings

# Lint only vapora crates (ignore external dependencies)
[no-cd]
fmt-clippy-vapora:
    #!/usr/bin/env nu
    print "🔗 Linting vapora crates only..."
    cargo clippy -p vapora-backend -p vapora-agents -p vapora-knowledge-graph -p vapora-llm-router -p vapora-swarm -p vapora-shared -p vapora-analytics -p vapora-telemetry -p vapora-tracking -p vapora-worktree --all-targets -- -D warnings

# Lint in release mode (catches more optimizations)
[no-cd]
fmt-clippy-release:
    #!/usr/bin/env nu
    print "🔗 Linting code (release mode)..."
    cargo clippy --release --all-targets -- -D warnings

# ============================================================================
# Check Namespace - Validation & Analysis
# ============================================================================

# Quick syntax/dependency check (fastest)
[no-cd]
check-code:
    #!/usr/bin/env nu
    print "🔍 Checking code (syntax/deps only)..."
    cargo check --all-targets

# Security audit + dependency checks
[no-cd]
check-security:
    #!/usr/bin/env nu
    print "🔒 Running security audit..."
    if (which cargo-audit | is-empty) {
        print "⚠️  cargo-audit not installed. Install with: cargo install cargo-audit"
        return 1
    }
    cargo audit --deny warnings

# Analyze coupling metrics with AI
[no-cd]
check-coupling:
    #!/usr/bin/env nu
    print "📊 Analyzing coupling metrics..."
    if (which cargo-coupling | is-empty) {
        print "⚠️  cargo-coupling not installed. Install with: cargo install cargo-coupling"
        return 1
    }
    cargo coupling --ai

# Check licenses and advisories
[no-cd]
check-deny:
    #!/usr/bin/env nu
    print "📜 Checking licenses and advisories..."
    if (which cargo-deny | is-empty) {
        print "⚠️  cargo-deny not installed. Install with: cargo install cargo-deny"
        return 1
    }
    cargo deny check licenses advisories

# Find unused dependencies
[no-cd]
check-unused:
    #!/usr/bin/env nu
    print "🔍 Checking for unused dependencies..."
    if (which cargo-udeps | is-empty) {
        print "⚠️  cargo-udeps not installed. Install with: cargo install cargo-udeps"
        return 1
    }
    cargo +nightly udeps --workspace

# ============================================================================
# Development Namespace
# ============================================================================

# Clean build artifacts
[no-cd]
dev-clean:
    #!/usr/bin/env nu
    print "🧹 Cleaning build artifacts..."
    nu ./scripts/clean.nu

# Update dependencies
[no-cd]
dev-update-deps:
    #!/usr/bin/env nu
    print "📦 Updating dependencies..."
    cargo update
    print "✓ Dependencies updated. Review changes and test thoroughly."

# Generate documentation
[no-cd]
dev-doc:
    #!/usr/bin/env nu
    print "📚 Generating documentation..."
    cargo doc --workspace --no-deps --document-private-items

# Generate and serve documentation locally
[no-cd]
dev-doc-serve:
    #!/usr/bin/env nu
    print "📚 Generating documentation and serving at http://localhost:8000..."
    cargo doc --workspace --no-deps --document-private-items --open

# Run benchmarks
[no-cd]
dev-bench:
    #!/usr/bin/env nu
    print "⚡ Running benchmarks..."
    cargo bench --workspace

# Run benchmarks and save baseline
[no-cd]
dev-bench-baseline:
    #!/usr/bin/env nu
    print "⚡ Running benchmarks and saving baseline..."
    cargo bench --workspace -- --save-baseline main

# ============================================================================
# Vapora-Specific Namespace
# ============================================================================

# Test vapora-backend service
[no-cd]
vapora-test-backend:
    #!/usr/bin/env nu
    print "🧪 Testing vapora-backend..."
    cargo test -p vapora-backend --lib --no-fail-fast

# Test vapora-agents service
[no-cd]
vapora-test-agents:
    #!/usr/bin/env nu
    print "🧪 Testing vapora-agents..."
    cargo test -p vapora-agents --lib --no-fail-fast

# Test vapora-llm-router service
[no-cd]
vapora-test-llm-router:
    #!/usr/bin/env nu
    print "🧪 Testing vapora-llm-router..."
    cargo test -p vapora-llm-router --lib --no-fail-fast

# Test vapora-knowledge-graph service
[no-cd]
vapora-test-kg:
    #!/usr/bin/env nu
    print "🧪 Testing vapora-knowledge-graph..."
    cargo test -p vapora-knowledge-graph --lib --no-fail-fast

# Test all vapora crates
[no-cd]
vapora-test-all:
    #!/usr/bin/env nu
    print "🧪 Testing all vapora crates..."
    cargo test -p vapora-backend \
               -p vapora-agents \
               -p vapora-knowledge-graph \
               -p vapora-llm-router \
               -p vapora-swarm \
               -p vapora-shared \
               --lib

# Check backend compilation and linting
[no-cd]
vapora-check-backend:
    #!/usr/bin/env nu
    print "🔍 Checking vapora-backend..."
    cargo check -p vapora-backend --all-targets
    cargo clippy -p vapora-backend --all-targets -- -D warnings

# Check agents compilation and linting
[no-cd]
vapora-check-agents:
    #!/usr/bin/env nu
    print "🔍 Checking vapora-agents..."
    cargo check -p vapora-agents --all-targets
    cargo clippy -p vapora-agents --all-targets -- -D warnings

# ============================================================================
# Helpers & Advanced
# ============================================================================

# Run recipe with timing information
[no-cd]
timed RECIPE:
    #!/usr/bin/env nu
    print $"⏱️  Running: just {{ RECIPE }} (with timing)"
    time just {{ RECIPE }}

# Run CI and display environment info
[no-cd]
ci-debug: check-code
    #!/usr/bin/env nu
    print ""
    print "🔍 Environment Information:"
    print $"Rust version: (rustc --version)"
    print $"Cargo version: (cargo --version)"
    print $"Nu version: (nu --version)"
    print ""
    print "Running full CI..."
    just ci-full

# ============================================================================
# Examples & Quick Reference
# ============================================================================

[no-cd]
examples:
    @echo ""
    @echo "📖 Quick Command Reference"
    @echo ""
    @echo "View help:"
    @echo "  just              - List all recipes"
    @echo "  just ci-help     - Show CI namespace help"
    @echo "  just help         - Show full help"
    @echo ""
    @echo "Development workflow:"
    @echo "  just fmt-fix              - Auto-format code"
    @echo "  just check-code           - Quick syntax check"
    @echo "  just fmt-clippy-vapora    - Lint vapora crates"
    @echo "  just vapora-test-backend  - Test backend"
    @echo ""
    @echo "Pre-commit:"
    @echo "  just ci-pre-commit        - Run pre-commit checks"
    @echo ""
    @echo "Full validation:"
    @echo "  just ci-full              - Complete CI pipeline"
    @echo "  just ci-main              - Main branch validation"
    @echo "  just check-security       - Security checks"
    @echo ""
    @echo "Build & test:"
    @echo "  just build-debug          - Debug build"
    @echo "  just build-release        - Release build"
    @echo "  just test-all             - Run all tests"
    @echo "  just test-coverage        - Generate coverage"
    @echo ""
    @echo "Analysis:"
    @echo "  just check-coupling       - Coupling metrics"
    @echo "  just check-unused         - Find unused deps"
    @echo "  just dev-bench            - Run benchmarks"
    @echo ""