ci-quality.yml

name: Quality Checks

on:
  push:
    branches: [ main, develop ]
    paths:
      - 'src/**'
      - 'tests/**'
      - 'pyproject.toml'
      - 'requirements*.txt'
      - 'uv.lock'
      - '.ruff.toml'
      - '.github/workflows/ci-quality.yml'
  pull_request:
    branches: [ main, develop ]
    paths:
      - 'src/**'
      - 'tests/**'
      - 'pyproject.toml'
      - 'requirements*.txt'
      - 'uv.lock'
      - '.ruff.toml'
      - '.github/workflows/ci-quality.yml'
  # pull_request_target is needed only for the auto-format-suggest job to call
  # the PR Reviews API on fork PRs. All other jobs gate on event_name to avoid
  # double execution.
  pull_request_target:
    branches: [ main, develop ]
    paths:
      - 'src/**'
      - 'tests/**'
      - 'pyproject.toml'
      - 'requirements*.txt'
      - 'uv.lock'
      - '.ruff.toml'
      - '.github/workflows/ci-quality.yml'

permissions:
  contents: read

jobs:
  config:
    name: Configuration
    uses: ./.github/workflows/shared-config.yml

  quality-check:
    name: Quality Standards
    # Skip on pull_request_target — only auto-format-suggest needs that event.
    if: github.event_name != 'pull_request_target'
    runs-on: ubuntu-latest
    needs: config
    permissions:
      contents: read
    
    env:
      AWS_DEFAULT_REGION: ${{ needs.config.outputs.aws-region }}
      AWS_ACCESS_KEY_ID: ${{ needs.config.outputs.aws-access-key }}
      AWS_SECRET_ACCESS_KEY: ${{ needs.config.outputs.aws-secret-key }}
      ENVIRONMENT: ${{ needs.config.outputs.environment }}
      TESTING: ${{ needs.config.outputs.testing-flag }}
    
    steps:
    - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
      with:
        fetch-depth: 0
    
    - name: Setup Python and UV
      uses: ./.github/actions/setup-uv-fresh
      with:
        python-version: ${{ needs.config.outputs.default-python-version }}
        cache-key-suffix: quality
    
    - name: Run quality checks
      run: |
        if [ "${{ github.event_name }}" = "schedule" ]; then
          make quality-check-all
        else
          make quality-check
        fi

  setup-cache:
    name: Setup Cache
    # Runs on both pull_request and pull_request_target — auto-format-suggest
    # depends on it and needs to run on pull_request_target for fork PRs.
    needs: config
    uses: ./.github/workflows/cache-management.yml
    with:
      cache-type: dependencies
      cache-key-base: quality-deps
      python-version: ${{ needs.config.outputs.default-python-version }}

  auto-format:
    name: Auto-Format Code
    # Same-repo PRs only: GITHUB_TOKEN can push directly to the branch.
    # Fork PRs are handled by the auto-format-suggest job below.
    if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    needs: [config, setup-cache]
    permissions:
      contents: write
    steps:
      - name: Checkout code
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          ref: ${{ github.head_ref }}

      - name: Setup UV with cache
        uses: ./.github/actions/setup-uv-cached
        with:
          cache-key: ${{ needs.setup-cache.outputs.cache-key }}
          fail-on-cache-miss: false

      - name: Auto-format code
        run: make format-fix

      - name: Commit formatting changes
        env:
          GIT_AUTHOR_NAME: github-actions[bot]
          GIT_AUTHOR_EMAIL: github-actions[bot]@users.noreply.github.com
          GIT_COMMITTER_NAME: github-actions[bot]
          GIT_COMMITTER_EMAIL: github-actions[bot]@users.noreply.github.com
        run: |
          git add .
          if ! git diff --staged --quiet; then
            git commit -m "style: auto-format code with ruff [skip ci]"
            git push
          fi

  auto-format-suggest:
    name: Auto-Format Suggestions
    # Fork PRs: post formatted changes as PR review suggestions for the
    # contributor to apply via the GitHub UI's "Commit suggestion" button.
    # Uses pull_request_target so the GITHUB_TOKEN can call the PR Reviews API
    # (POST /pulls/{id}/reviews) — pull_request fork-PR tokens cannot.
    # The workflow file is evaluated at the base ref (safe); only the PR head
    # code is checked out into a non-elevated working tree for formatting.
    if: github.event_name == 'pull_request_target' && github.event.pull_request.head.repo.full_name != github.repository
    runs-on: ubuntu-latest
    needs: [config, setup-cache]
    permissions:
      contents: read
      pull-requests: write
    steps:
      - name: Checkout PR head
        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          # No token here — formatter does not need write access; this prevents
          # untrusted PR code from authenticating with elevated permissions.
          persist-credentials: false

      - name: Setup UV with cache
        uses: ./.github/actions/setup-uv-cached
        with:
          cache-key: ${{ needs.setup-cache.outputs.cache-key }}
          fail-on-cache-miss: false

      - name: Run formatter
        run: make format-fix

      - name: Post review suggestions
        uses: reviewdog/action-suggester@aa38384ceb608d00f84b4690cacc83a5aba307ff  # v1.24.0
        with:
          tool_name: ruff
          level: warning
          fail_on_error: false

  lint-ruff:
    name: Ruff (Code Quality)
    if: github.event_name != 'pull_request_target'
    runs-on: ubuntu-latest
    needs: [config, setup-cache]
    permissions:
      contents: read
    steps:
      - name: Checkout code
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0

      - name: Setup UV with cache
        uses: ./.github/actions/setup-uv-cached
        with:
          cache-key: ${{ needs.setup-cache.outputs.cache-key }}
          fail-on-cache-miss: false

      - name: Check code quality
        run: make ci-quality-ruff

  lint-ruff-optional:
    name: Ruff (Extended Checks)
    if: github.event_name != 'pull_request_target'
    runs-on: ubuntu-latest
    needs: [config, setup-cache, lint-ruff]
    permissions:
      contents: read
    steps:
      - name: Checkout code
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0

      - name: Setup UV with cache
        uses: ./.github/actions/setup-uv-cached
        with:
          cache-key: ${{ needs.setup-cache.outputs.cache-key }}
          fail-on-cache-miss: false

      - name: Extended linting (warnings)
        run: make ci-quality-ruff-optional
        continue-on-error: true

  lint-pyright:
    name: Type Checking (pyright)
    if: github.event_name != 'pull_request_target'
    runs-on: ubuntu-latest
    needs: [config, setup-cache, lint-ruff]
    permissions:
      contents: read
    steps:
    - name: Checkout code
      uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0

    - name: Setup UV with cache
      uses: ./.github/actions/setup-uv-cached
      with:
        cache-key: ${{ needs.setup-cache.outputs.cache-key }}
        fail-on-cache-miss: false

    - name: Run pyright type check
      run: make ci-quality-pyright


  arch-validation:
    name: Architecture Validation
    if: github.event_name != 'pull_request_target'
    runs-on: ubuntu-latest
    needs: [config, setup-cache, lint-ruff]
    permissions:
      contents: read
    strategy:
      matrix:
        check: [cqrs, clean, imports, file-sizes]
        include:
          - check: cqrs
            description: "CQRS Pattern Validation"
          - check: clean
            description: "Clean Architecture Dependencies"
          - check: imports
            description: "Import Validation"
          - check: file-sizes
            description: "File Size Compliance"
    steps:
    - name: Checkout code
      uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0

    - name: Setup UV with cache
      uses: ./.github/actions/setup-uv-cached
      with:
        cache-key: ${{ needs.setup-cache.outputs.cache-key }}
        fail-on-cache-miss: false

    - name: Run architecture validation (${{ matrix.description }})
      run: make ci-arch-${{ matrix.check }}