Justfile

# Debtmap - Justfile
# Quick development commands for Rust projects

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

# Development commands
alias d := dev
alias r := run
alias t := test
alias c := check
alias f := fmt
alias l := lint

# === DEVELOPMENT ===

# Run the project in development mode and forward CLI arguments
dev *ARGS:
    cargo run -- {{ARGS}}

# Run the project with hot reloading
watch:
    cargo watch -x run

# Run the project with the debug build and forward CLI arguments
run *ARGS:
    cargo run -- {{ARGS}}

# Run the project with the release build and forward CLI arguments
run-release *ARGS:
    cargo run --release -- {{ARGS}}

# Run with all features enabled
run-all:
    cargo run --all-features

# === BUILDING ===

# Build the project
build:
    cargo build

# Build in release mode
build-release:
    cargo build --release

# Build with optimizations for native CPU
build-native:
    RUSTFLAGS="-C target-cpu=native" cargo build --release

# Clean build artifacts
clean:
    cargo clean

# === TESTING ===

# Run the bounded fast feedback suite
test: test-fast

# Run library tests and the smallest stable integration targets
test-fast:
    @echo "Running tests with cargo nextest..."
    cargo nextest run --profile fast --lib \
        --test analyzer_tests --test complexity_tests --test core_metrics_tests \
        --test debt_tests --test entropy_tests

# Verify installer platform, download, checksum, and release-publication contracts
test-install:
    bash -n install.sh tests/install_script_test.sh
    shellcheck install.sh tests/install_script_test.sh
    bash tests/install_script_test.sh

# Backwards-compatible fast plus bounded integration suite
test-safe: test-fast test-integration

# Run the bounded cross-module regression suite
test-integration:
    cargo nextest run --profile integration \
        --test analyzer_tests --test apply_entropy_dampening_tests --test batch_integration \
        --test bug_documentation_tests --test call_graph_closure_test \
        --test call_graph_extraction_test --test call_graph_improved_test \
        --test call_graph_resolution_test --test call_graph_cross_file_resolution_test \
        --test cognitive_complexity_tests --test complexity_comparison_test \
        --test compare_integration_test --test compare_safety_test \
        --test complexity_module_tests --test complexity_tests \
        --test context_aware_integration_test --test context_aware_test --test core_ast_tests \
        --test core_display_tests --test core_metrics_tests --test core_monadic_tests \
        --test core_untested_functions_tests --test cyclomatic_complexity_tests \
        --test debt_grouping_tests --test debt_tests --test dependency_and_coupling_tests \
        --test demo_library_api_test --test determinism_regression_test \
        --test entropy_integration_tests --test entropy_tests \
        --test error_swallowing_pipeline_test --test error_swallowing_test \
        --test external_api_detection_tests --test external_api_detector_integration_test \
        --test false_positive_reproduction_tests --test fast_unit_tests \
        --test field_access_chain_test --test io_walker_tests --test json_serialization_test \
        --test language_tests --test python_complexity_tests --test python_extraction_test \
        --test data_flow_identity_matrix --test rust_resolution_constraint_matrix \
        --test rust_resolution_namespace_matrix --test rust_resolution_matrix_oracles \
        --test rust_resolution_matrix_invariants --test rust_resolution_matrix_assertions \
        --test recursive_dependency_metrics \
        --test solidity_analyzer_tests --test suppression_tests --test token_classification_tests \
        --test validate_improvement_integration_test

# Run tests with output
test-verbose:
    cargo nextest run --nocapture

# Run tests with specific pattern
test-pattern PATTERN:
    cargo nextest run {{PATTERN}}

# Run tests and watch for changes
test-watch:
    cargo watch -x 'nextest run'

# Representative coverage: all ordinary library, binary and integration tests.
# Libtest creates one profile per binary; Cargo discovers new test targets.
coverage: coverage-collect
    just coverage-report-html

coverage-lcov: coverage-collect
    just coverage-report-lcov

coverage-check: coverage-collect
    just coverage-report-check

# Collect once; additional report formats can reuse this successful run.
coverage-collect:
    mkdir -p target/coverage
    rm -f target/coverage/.complete target/coverage/lcov.info target/coverage/coverage-summary.json
    rm -rf target/coverage/html
    cargo llvm-cov clean --profraw-only
    cargo llvm-cov --no-report --all-features --tests --no-fail-fast -- --quiet
    touch target/coverage/.complete

# Export only after successful representative collection.
coverage-report-html:
    test -f target/coverage/.complete
    cargo llvm-cov report --html --output-dir target/coverage

coverage-report-lcov:
    test -f target/coverage/.complete
    cargo llvm-cov report --lcov --output-path target/coverage/lcov.info

coverage-report-check:
    test -f target/coverage/.complete
    cargo llvm-cov report --json --summary-only --output-path target/coverage/coverage-summary.json --fail-under-lines 80

# Compatibility names: representative coverage is now the default.
coverage-full: coverage
coverage-full-lcov: coverage-lcov
coverage-full-check: coverage-check

# Partial, library-only feedback. Profiles and artifacts are isolated from full coverage.
coverage-fast: _coverage-fast-collect
    CARGO_LLVM_COV_TARGET_DIR=target/llvm-cov-fast-target cargo llvm-cov report --html --output-dir target/coverage-fast

coverage-fast-lcov: _coverage-fast-collect
    CARGO_LLVM_COV_TARGET_DIR=target/llvm-cov-fast-target cargo llvm-cov report --lcov --output-path target/coverage-fast/lcov.info

_coverage-fast-collect:
    mkdir -p target/coverage-fast
    rm -f target/coverage-fast/lcov.info
    rm -rf target/coverage-fast/html
    CARGO_LLVM_COV_TARGET_DIR=target/llvm-cov-fast-target cargo llvm-cov clean --profraw-only
    CARGO_LLVM_COV_TARGET_DIR=target/llvm-cov-fast-target cargo llvm-cov --no-report --lib -- --quiet

# Open representative coverage in the browser.
coverage-open: coverage
    open target/coverage/html/index.html

# Analyze this repository using freshly collected representative coverage.
analyze-self: coverage-lcov
    cargo build --bin debtmap
    ./target/debug/debtmap analyze . --lcov target/coverage/lcov.info -vv

# Run property-based tests only (if using proptest)
test-prop:
    cargo nextest run prop

# Run bounded CLI/output tests serially against Cargo's prebuilt debug binary
test-cli:
    cargo nextest run --profile cli \
        --test clean_dispatcher_output_test --test cli_output_format_integration_test \
        --test config_contract_integration_test --test json_output_contract_test \
        --test parallel_sequential_equivalence_test \
        --test progress_display_integration_test --test validate_parallel_test

# Run benchmarks
bench:
    cargo bench

# Run bounded slow repository/context regressions
test-slow:
    cargo nextest run --profile slow --run-ignored only --lib \
        --test god_object_detection_test --test integration_false_positive_test \
        test_git_history_on_real_repo test_git_history_with_analysis_style_paths \
        test_git_history_via_context_aggregator test_large_call_graph_no_stack_overflow \
        test_context_aggregator_large_codebase test_real_project_health_score \
        test_detects_rust_call_graph_scenario test_spec_130_god_class_vs_god_file_detection \
        test_context_aware_on_entire_codebase
    cargo nextest run --profile slow --run-ignored only --test ui_tests

# Run bounded scale and timing tests
test-stress:
    cargo nextest run --profile stress --run-ignored only --lib \
        test_analyze_many_functions_with_context_no_stack_overflow
    cargo nextest run --profile stress --run-ignored only \
        --test call_graph_debug_output_test --test call_graph_stress_test \
        --test demo_library_api_test --test functional_composition_validation_test \
        --test parallel_unified_analysis_test --test stress_test_large_projects
    cargo nextest run --profile stress --run-ignored all \
        --test boilerplate_performance_test --test coverage_performance_regression_test

# Run opt-in tests that depend on terminal state, binaries, or local artifacts
test-environment:
    cargo nextest run --profile environment --run-ignored only --lib \
        --test trait_method_coverage_test \
        test_editor_command_construction test_execute_detail_action_open_in_editor \
        test_coverage_matching_integration test_explain_coverage_finds_trait_method

# Run only ignored tests that document unfinished behavior
test-known-broken:
    cargo nextest run --profile known-broken --run-ignored only --lib \
        --test clustering_integration --test god_object_config_rs_test \
        --test inter_procedural_purity_test --test tier_aware_filtering_integration_test \
        test_simple_import_resolution test_select_macro test_clustering_determinism \
        test_god_object_detection_on_config_rs test_impure_caller_propagates_impurity \
        test_all_error_swallowing_patterns_visible_with_defaults test_t1_bypasses_high_threshold

# Run every supported bounded group expected to pass in a configured environment
test-supported: test-fast test-integration test-cli test-slow test-stress

# Compatibility name for all ignored dispositions; diagnostics may fail by design
test-ignored: test-slow test-stress test-environment test-known-broken
test-perf: test-stress

# Exhaustive bounded run; environment and known-broken diagnostics may fail by design
test-all: test-supported test-environment test-known-broken

# === CODE QUALITY ===

# Format code
fmt:
    cargo fmt

# Check formatting without making changes
fmt-check:
    cargo fmt --check

# Run clippy linter
lint:
    cargo clippy -- -D warnings

# Run clippy with all targets
lint-all:
    cargo clippy --all-targets --all-features -- -D warnings

# Quick check without building
check:
    cargo check

# Check all targets and features
check-all:
    cargo check --all-targets --all-features

# Fix automatically fixable lints
fix:
    cargo fix --allow-dirty

# === DOCUMENTATION ===

# Generate and open documentation
doc:
    cargo doc --open

# Generate documentation for all dependencies
doc-all:
    cargo doc --all --open

# Check documentation for errors
doc-check:
    cargo doc --no-deps

# === DEPENDENCIES ===

# Update dependencies
update:
    cargo update

# Audit dependencies for security vulnerabilities
audit:
    cargo audit

# Check for outdated dependencies
outdated:
    cargo outdated

# Add a new dependency
add CRATE:
    cargo add {{CRATE}}

# Add a development dependency
add-dev CRATE:
    cargo add --dev {{CRATE}}

# Remove a dependency
remove CRATE:
    cargo remove {{CRATE}}

# === UTILITY ===

# Show project tree structure
tree:
    tree -I 'target|node_modules'

# Show git status
status:
    git status

# Create a new module
new-module NAME:
    mkdir -p src/{{NAME}}
    echo "//! {{NAME}} module" > src/{{NAME}}/mod.rs
    echo "pub mod {{NAME}};" >> src/lib.rs

# Create a new integration test
new-test NAME:
    echo "//! Integration test for {{NAME}}" > tests/{{NAME}}.rs

# Create a new example
new-example NAME:
    echo "//! Example: {{NAME}}" > examples/{{NAME}}.rs

# === CI/CD SIMULATION ===

# Run all CI checks locally (matches GitHub Actions)
ci: test-fast test-integration test-cli
    @echo "Running CI checks (matching GitHub Actions)..."
    @echo "Setting environment variables..."
    @export CARGO_TERM_COLOR=always && \
     export CARGO_INCREMENTAL=0 && \
     export RUSTFLAGS="-Dwarnings" && \
     export RUST_BACKTRACE=1 && \
     echo "Running doc tests..." && \
     cargo test --doc && \
     echo "Running clippy..." && \
     cargo clippy --all-targets --all-features -- -D warnings && \
     echo "Checking formatting..." && \
     cargo fmt --all -- --check && \
     echo "Checking documentation..." && \
     cargo doc --no-deps --document-private-items && \
     echo "All CI checks passed!"

# Full CI build pipeline (equivalent to scripts/ci-build.sh)
ci-build: test-fast test-integration test-cli
    @echo "Building debtmap..."
    @echo "Checking code formatting..."
    cargo fmt --all -- --check
    @echo "Running clippy..."
    cargo clippy --all-targets --all-features -- -D warnings
    @echo "Building project..."
    cargo build
    @echo "Checking benchmarks..."
    cargo check --benches
    @echo "Build successful!"

# Pre-commit hook simulation
pre-commit: fmt lint test
    @echo "Pre-commit checks passed!"

# Full development cycle check
full-check: clean build test lint doc audit
    @echo "Full development cycle completed successfully!"

# === INSTALLATION ===

# Install development tools
install-tools:
    rustup component add rustfmt clippy llvm-tools-preview
    cargo install cargo-watch cargo-llvm-cov cargo-audit cargo-outdated cargo-nextest

# Install additional development tools
install-extras:
    cargo install cargo-expand cargo-machete cargo-deny cargo-udeps

# Install git hooks
install-hooks:
    #!/usr/bin/env bash
    echo "Installing git hooks..."
    for hook in git-hooks/*; do
        if [ -f "$hook" ]; then
            hook_name=$(basename "$hook")
            cp "$hook" ".git/hooks/$hook_name"
            chmod +x ".git/hooks/$hook_name"
            echo "  ✓ Installed $hook_name"
        fi
    done
    echo "Git hooks installed successfully!"

# === RELEASE ===

# Prepare for release (dry run)
release-check:
    cargo publish --dry-run

# Create a new release (requires manual version bump)
release:
    cargo publish

# === ADVANCED ===

# Record reproducible built-in phase timings using the debug binary.
profile path=".":
    #!/usr/bin/env bash
    set -euo pipefail
    output="target/profiling/debtmap-profile.json"
    mkdir -p "$(dirname "$output")"
    cargo build
    ./target/debug/debtmap analyze "{{path}}" \
        --profile --profile-output "$output" \
        --quiet --no-tui --no-context-aware
    echo "Debug profiling report: $output"

# Expand macros for debugging
expand:
    cargo expand

# Find unused dependencies
unused-deps:
    cargo machete

# Security-focused dependency check
security-check:
    cargo deny check

# Find duplicate dependencies
duplicate-deps:
    cargo tree --duplicates

# === HELP ===

# Show detailed help for cargo commands
help:
    @echo "Cargo commands reference:"
    @echo "  cargo run      - Run the project"
    @echo "  cargo test     - Run tests"
    @echo "  cargo build    - Build the project"
    @echo "  cargo fmt      - Format code"
    @echo "  cargo clippy   - Run linter"
    @echo "  cargo check    - Quick syntax check"
    @echo "  cargo doc      - Generate documentation"
    @echo ""
    @echo "Use 'just <command>' for convenience aliases!"