announcement/justfile

# justfile for announcement crate
# High-level development and CI workflows

# =============================================================================
# Configuration
# =============================================================================

# Treat all warnings as errors
rustflags := "-D warnings"

# Code coverage target percentage (fail if below this threshold)
# Note: Target is 98% (actual: 98.52%) due to:
# - 3 extremely narrow TOCTOU race windows that are challenging to hit reliably in testing
coverage_target := "98"

# Timeout for coverage analysis in seconds
coverage_timeout := "600"

# Mutation testing timeout in seconds (default: none, runs until complete)
# Uncomment to limit mutation testing duration
# mutation_timeout := "600"

# Fuzz testing duration per target in seconds
fuzz_time := "900"

# =============================================================================

# Default recipe - show available recipes
default:
    @just --list

# =============================================================================
# Primary Development Workflows
# =============================================================================

# Quick development loop: format + lint + fast tests
dev:
    #!/usr/bin/env bash
    set -e
    echo "🔄 Running development checks..."
    cargo fmt
    RUSTFLAGS="{{rustflags}}" cargo clippy --all-targets --all-features &
    RUSTFLAGS="{{rustflags}}" cargo nextest run --all-features &
    wait
    echo "✅ Development checks passed"

# Pre-commit checks: format-check + lint + typecheck across all feature combinations
check:
    @echo "Running format check..."
    cargo fmt -- --check
    @echo ""
    @echo "Running clippy on all feature combinations..."
    RUSTFLAGS="{{rustflags}}" cargo clippy --all-targets --all-features
    RUSTFLAGS="{{rustflags}}" cargo clippy --all-targets --no-default-features
    RUSTFLAGS="{{rustflags}}" cargo clippy --all-targets --no-default-features --features std
    RUSTFLAGS="{{rustflags}}" cargo clippy --all-targets --features std,tracing
    @echo ""
    @echo "Verifying compilation on all feature combinations..."
    RUSTFLAGS="{{rustflags}}" cargo test --all-features --no-run
    RUSTFLAGS="{{rustflags}}" cargo test --no-default-features --no-run
    RUSTFLAGS="{{rustflags}}" cargo test --no-default-features --features std --no-run
    RUSTFLAGS="{{rustflags}}" cargo test --features std,tracing --no-run
    @echo ""
    @echo "✅ All checks passed"

# Run all tests with comprehensive feature coverage
test:
    @echo "Running tests with all feature combinations..."
    RUSTFLAGS="{{rustflags}}" cargo nextest run --all-features
    RUSTFLAGS="{{rustflags}}" cargo nextest run --no-default-features
    RUSTFLAGS="{{rustflags}}" cargo nextest run --no-default-features --features std
    RUSTFLAGS="{{rustflags}}" cargo nextest run --features std,tracing
    @echo "✅ All feature combinations tested"

# Before pushing: check + test + coverage
pre-push: check test coverage
    @echo ""
    @echo "✅ Pre-push checks passed - safe to push!"

# Comprehensive pre-release validation
pre-release: check test coverage audit mutants
    #!/usr/bin/env bash
    set -e

    # Verify documentation version matches crate version
    echo ""
    echo "📋 Verifying documentation version..."
    VERSION=$(grep '^version = ' Cargo.toml | head -1 | sed 's/.*"\(.*\)".*/\1/')
    MAJOR_MINOR=$(echo $VERSION | cut -d. -f1-2)

    if ! grep -q "announcement = \"$MAJOR_MINOR\"" README.md; then
        echo "❌ ERROR: README.md should reference version $MAJOR_MINOR (crate is $VERSION)"
        echo "   Update installation examples in README.md"
        exit 1
    fi
    echo "✅ Documentation version correct: $MAJOR_MINOR"

    # Package verification
    echo ""
    echo "📦 Verifying package..."
    cargo publish --dry-run
    cargo package --list > /tmp/announcement-files.txt
    echo "✅ Package verified"

    echo ""
    echo "✅ All pre-release checks passed!"
    echo "  - Code formatted and linted"
    echo "  - All tests passing (507+ tests)"
    echo "  - Code coverage ≥ {{coverage_target}}%"
    echo "  - No security vulnerabilities"
    echo "  - Dependencies verified"
    echo "  - Mutation testing complete"
    echo "  - Documentation version verified"
    echo "  - Package ready for publication"
    echo ""
    echo "📦 Ready to publish! Run: cargo publish"

# =============================================================================
# Quality & Security
# =============================================================================

# Run code coverage analysis
coverage:
    @echo "Running code coverage analysis (target: {{coverage_target}}%)..."
    cargo llvm-cov nextest --html --output-dir coverage --fail-under-lines {{coverage_target}}
    @echo "Coverage report: coverage/html/index.html"

# Mutation testing (NUCLEAR) - maximum aggression with parallelism
mutants:
    @echo "Running mutation testing..."
    @echo "⚠️  This will use significant CPU and memory resources!"
    cargo mutants \
        --no-shuffle \
        --test-tool nextest \
        --jobs 3 \
        --all-features \
        -vV

# Security audit + dependency checks
audit:
    @echo "🔒 Running security checks..."
    cargo audit
    cargo deny check
    @echo "✅ Security checks passed"

# Run Miri for undefined behavior detection (using default std feature)
miri:
    @echo "Running Miri tests for UB detection..."
    cargo +nightly miri test

# Run comprehensive fuzz tests
fuzz:
    @echo "Running comprehensive fuzz tests ({{fuzz_time}}s per target..."
    cargo +nightly fuzz build
    cargo +nightly fuzz run fuzz_announce -- -max_total_time={{fuzz_time}}
    cargo +nightly fuzz run fuzz_close -- -max_total_time={{fuzz_time}}
    cargo +nightly fuzz run fuzz_listen -- -max_total_time={{fuzz_time}}
    cargo +nightly fuzz run fuzz_concurrent -- -max_total_time={{fuzz_time}}

# =============================================================================
# Benchmarks
# =============================================================================

# Run all benchmarks
bench:
    cargo bench

# Run benchmarks and save as baseline
bench-baseline:
    cargo bench -- --save-baseline baseline

# Compare benchmarks against baseline
bench-compare:
    cargo bench -- --baseline baseline


# =============================================================================
# Documentation & Utilities
# =============================================================================

# Build documentation and open in browser
doc:
    cargo doc --no-deps --all-features --open

# Format code
fmt:
    cargo fmt

# Show project information
info:
    @echo "announcement crate - Runtime-agnostic oneshot broadcast channel"
    @echo ""
    @echo "Rust: $(rustc --version)"
    @echo "Cargo: $(cargo --version)"
    @echo ""
    @echo "Dependencies:"
    @cargo tree --depth 1

# Run all examples (user guide verification)
examples:
    @echo "Running all examples..."
    cargo run --example 01_basic_usage
    cargo run --example 02_async_listening
    cargo run --example 03_multiple_listeners
    cargo run --example 04_efficient_broadcasting
    cargo run --example 05_blocking_operations
    cargo run --example shutdown
    cargo run --example config_broadcast
    cargo run --example lazy_init
    @echo "✅ All examples completed successfully"

# Clean build artifacts
clean:
    cargo clean
    rm -rf mutants.out/ mutants.out.old/ mutation_history.json
    rm -f bench-output.txt