ci.yml

# Workflow: Continuous Integration (CI)
#
# This workflow runs on every push and pull request to ensure code quality
# and compatibility across different platforms and Rust versions.
# It performs comprehensive testing, linting, formatting checks, and builds.

name: CI

# Trigger conditions: run on pushes to main branch and all pull requests
on:
  push:
    branches: [ "main", "master" ]
  pull_request:
    branches: [ "main", "master" ]

# Define environment variables used across all jobs
env:
  CARGO_TERM_COLOR: always
  RUST_BACKTRACE: 1

# Define the jobs that make up the CI pipeline
jobs:
  # Job 1: Run comprehensive tests across multiple platforms and Rust versions
  test:
    name: Test Suite
    runs-on: ${{ matrix.os }}
    
    # Strategy matrix: test on multiple operating systems and Rust versions
    # This ensures our code works across different environments
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        # Using rust-toolchain.toml to enforce consistent Rust 1.86.0 across all environments
        # This ensures Cargo.lock v4 compatibility everywhere
    
    steps:
    # Step 1: Check out the source code from the repository
    - name: Checkout source code
      uses: actions/checkout@v4
    
    # Step 2: Install Rust toolchain from rust-toolchain.toml
    # This ensures consistent Rust 1.86.0 that supports Cargo.lock v4
    - name: Install Rust toolchain
      uses: dtolnay/rust-toolchain@1.86.0
      with:
        components: rustfmt, clippy
    
    # Step 3: Configure Rust cargo caching to speed up builds
    # This caches dependencies and build artifacts between runs
    - name: Setup Rust cache
      uses: Swatinem/rust-cache@v2
      with:
        # Cache key includes OS for proper isolation
        key: ${{ matrix.os }}-rust-1.86.0
    
    # Step 4: Build all targets to ensure compilation succeeds
    # We build all binary examples defined in Cargo.toml
    - name: Build all examples
      run: cargo build --all-targets --verbose
    
    # Step 5: Run all unit and integration tests
    # The --all-targets flag ensures we test all our binary examples
    - name: Run tests
      run: cargo test --all-targets --verbose
    
    # Step 6: Build and run each example individually to verify they work
    # This is important since we have multiple binary targets
    - name: Test individual examples
      run: |
        # Get list of all binary examples from Cargo.toml
        for example in $(cargo read-manifest | jq -r '.targets[] | select(.kind[] == "bin") | .name'); do
          echo "Testing example: $example"
          cargo run --bin "$example" --help || true  # Run with --help to test basic functionality
        done
      shell: bash
    
    # Step 7: Run tests with all features enabled (if any)
    - name: Run tests with all features
      run: cargo test --all-features --verbose

  # Job 2: Code quality checks (formatting and linting)
  quality:
    name: Code Quality
    runs-on: ubuntu-latest
    
    steps:
    # Step 1: Check out the source code
    - name: Checkout source code
      uses: actions/checkout@v4
    
    # Step 2: Install Rust toolchain with Cargo.lock v4 support
    - name: Install Rust toolchain
      uses: dtolnay/rust-toolchain@1.86.0
      with:
        components: rustfmt, clippy
    
    # Step 3: Setup caching for faster subsequent runs
    - name: Setup Rust cache
      uses: Swatinem/rust-cache@v2
    
    # Step 4: Check code formatting with rustfmt
    # This ensures all code follows consistent formatting standards
    - name: Check formatting
      run: cargo fmt --all -- --check
    
    # Step 5: Run Clippy linter for code quality and style issues
    # Clippy catches common mistakes and suggests improvements
    - name: Run Clippy linting
      run: cargo clippy --all-targets --all-features -- -D warnings
    
    # Step 6: Check for unused dependencies (educational note)
    # Note: For educational examples with multiple binaries, dependency usage
    # analysis is more complex since deps are used across different examples
    - name: Dependency usage information
      run: |
        echo "ℹ️  Dependency Usage Note for Educational Examples:"
        echo "   This project contains multiple binary examples, each using different subsets of dependencies"
        echo "   Dependencies like 'anyhow', 'futures', 'rmcp', 'thiserror' are intentionally included"
        echo "   For production projects, consider using: cargo +nightly udeps --all-targets"
        echo ""
        echo "📦 Current Dependencies:"
        cargo tree --depth 1

  # Job 3: Security audit to check for known vulnerabilities
  security:
    name: Security Audit
    runs-on: ubuntu-latest
    
    steps:
    # Step 1: Check out the source code
    - name: Checkout source code
      uses: actions/checkout@v4
    
    # Step 2: Install Rust toolchain with Cargo.lock v4 support
    - name: Install Rust toolchain
      uses: dtolnay/rust-toolchain@1.86.0
    
    # Step 3: Setup Rust caching
    - name: Setup Rust cache
      uses: Swatinem/rust-cache@v2
    
    # Step 4: Install cargo-audit for security scanning
    - name: Install cargo-audit
      run: cargo install cargo-audit --locked
    
    # Step 5: Run security audit on dependencies
    # This checks for known security vulnerabilities in our dependencies
    # We ignore RUSTSEC-2023-0071 (RSA timing sidechannel) as it's a transitive
    # dependency through sqlx-mysql with no fix available, and poses minimal
    # risk for educational examples that don't handle sensitive RSA operations
    - name: Run security audit
      run: cargo audit --ignore RUSTSEC-2023-0071
    
    # Step 6: Check for vulnerabilities in our Cargo.lock file
    - name: Check advisories
      run: cargo audit --json | jq '.vulnerabilities'

  # Job 4: Documentation checks
  docs:
    name: Documentation
    runs-on: ubuntu-latest
    
    steps:
    # Step 1: Check out the source code
    - name: Checkout source code
      uses: actions/checkout@v4
    
    # Step 2: Install Rust toolchain with Cargo.lock v4 support
    - name: Install Rust toolchain
      uses: dtolnay/rust-toolchain@1.86.0
    
    # Step 3: Setup caching
    - name: Setup Rust cache
      uses: Swatinem/rust-cache@v2
    
    # Step 4: Build documentation to ensure it compiles without errors
    # This catches documentation issues early
    - name: Build documentation
      run: cargo doc --all --no-deps --document-private-items
      env:
        RUSTDOCFLAGS: "-D warnings"
    
    # Step 5: Check that documentation builds without errors
    # Note: We don't enforce missing-docs for examples since they are educational code
    - name: Check documentation builds
      run: cargo doc --all --no-deps

  # Job 5: Dependency review for supply chain security
  dependency-review:
    name: Dependency Review
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    
    steps:
    # Step 1: Check out the source code
    - name: Checkout source code
      uses: actions/checkout@v4
    
    # Step 2: Run GitHub's dependency review action
    # This checks for security issues in dependency changes
    - name: Dependency Review
      uses: actions/dependency-review-action@v4