basic-workflow.yml

# Basic lintdiff workflow for Rust projects
# ===========================================
# This workflow runs lintdiff on pull requests to identify lint issues
# located on lines touched by the PR.
#
# Features demonstrated:
# - Complete PR lint checking with clippy
# - Feature flags usage for conditional lint rules
# - Report artifact upload for later analysis
# - Clear comments explaining each step
#
# To use: Copy this file to .github/workflows/lintdiff.yml in your repository

name: Lintdiff

on:
  pull_request:
    # Run on all PR events (opened, synchronize, reopened)
    types: [opened, synchronize, reopened]
  # Allow manual triggering for debugging
  workflow_dispatch:

# Cancel in-progress runs when a new commit is pushed
concurrency:
  group: lintdiff-${{ github.head_ref }}
  cancel-in-progress: true

jobs:
  lintdiff:
    name: Run lintdiff analysis
    runs-on: ubuntu-latest
    
    steps:
      # Step 1: Checkout the repository
      # fetch-depth: 0 is required to get full git history for diff calculation
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      # Step 2: Set up Rust toolchain with clippy component
      # Using dtolnay/rust-toolchain for reliable Rust installation
      - name: Set up Rust toolchain
        uses: dtolnay/rust-toolchain@stable
        with:
          components: clippy

      # Step 3: Cache cargo artifacts for faster builds
      # This significantly speeds up subsequent workflow runs
      - name: Cache cargo artifacts
        uses: Swatinem/rust-cache@v2
        with:
          # Cache key based on Cargo.lock hash
          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}

      # Step 4: Run clippy to generate diagnostics
      # The --message-format=json flag outputs machine-readable diagnostics
      # We redirect to a file for lintdiff to process
      - name: Run Clippy
        id: clippy
        continue-on-error: true
        run: |
          echo "Running clippy with JSON output..."
          set +e
          cargo clippy --all-features --message-format=json 2>/dev/null > clippy.jsonl
          EXIT_CODE=$?
          echo "exit_code=$EXIT_CODE" >> "$GITHUB_OUTPUT"
          if jq -e -s 'any(.[]; .reason == "build-finished")' clippy.jsonl >/dev/null 2>&1; then
            echo "build_finished=true" >> "$GITHUB_OUTPUT"
            BUILD_SUCCESS=$(jq -s -r '[.[] | select(.reason == "build-finished") | .success] | .[-1]' clippy.jsonl)
            echo "build_success=$BUILD_SUCCESS" >> "$GITHUB_OUTPUT"
          else
            echo "build_finished=false" >> "$GITHUB_OUTPUT"
            echo "build_success=" >> "$GITHUB_OUTPUT"
          fi
          echo "Clippy diagnostics saved to clippy.jsonl"

      # Step 5: Run lintdiff to filter diagnostics to changed lines
      # This uses the effortless-metrics/lintdiff GitHub Action
      # Feature flags example: Using --all-features to check all code paths
      - name: Run lintdiff
        id: lintdiff
        if: always()
        uses: effortless-metrics/lintdiff@v0.1.0
        with:
          # Path to clippy diagnostics output
          diagnostics: clippy.jsonl
          upstream_exit_code: ${{ steps.clippy.outputs.exit_code }}
          upstream_build_finished: ${{ steps.clippy.outputs.build_finished }}
          upstream_build_success: ${{ steps.clippy.outputs.build_success }}
          upstream_command: '["cargo","clippy","--all-features","--message-format=json"]'
          # Fail the workflow if errors are found in changed code
          fail_on: error
          # Optional: Specify a custom config file (uncomment if needed)
          # config: lintdiff.toml

      # Step 6: Upload the lintdiff report as an artifact
      # This allows you to download and analyze the report later
      # The report contains detailed information about all findings
      - name: Upload lintdiff report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: lintdiff-report
          path: artifacts/lintdiff/
          # Fail silently if no report was generated (e.g., if lintdiff was skipped)
          if-no-files-found: ignore
          # Retain for 30 days for later analysis
          retention-days: 30

      # Step 7: Output summary (optional but helpful for debugging)
      - name: Print summary
        if: always()
        run: |
          echo "## Lintdiff Results" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "- **Verdict**: ${{ steps.lintdiff.outputs.verdict }}" >> $GITHUB_STEP_SUMMARY
          echo "- **Exit Code**: ${{ steps.lintdiff.outputs.exit_code }}" >> $GITHUB_STEP_SUMMARY
          echo "- **Report Path**: ${{ steps.lintdiff.outputs.report_path }}" >> $GITHUB_STEP_SUMMARY