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'

# Cancel in-progress runs when a new push arrives on the same branch/ref.
# The auto-format job is exempted via its own job-level concurrency block
# (cancel-in-progress: false) because it pushes a commit back to the branch —
# cancelling it mid-push could leave the branch in a partially formatted state.
concurrency:
  group: ci-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

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. Fork PRs handled by auto-format-suggest below.
    # Bot-actor guard prevents the job re-triggering on its own push.
    if: |
      github.event_name == 'pull_request'
      && github.event.pull_request.head.repo.full_name == github.repository
      && github.actor != 'open-resource-broker-cicd[bot]'
    runs-on: ubuntu-latest
    needs: [config, setup-cache]
    # Override the workflow-level concurrency so this job is never cancelled
    # mid-run.  If it were interrupted after `ruff` rewrites files but before
    # `git push`, the PR branch would be left in a half-formatted state.
    concurrency:
      group: ci-auto-format-${{ github.ref }}
      cancel-in-progress: false
    permissions:
      contents: write
    steps:
      - name: Checkout code
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
        with:
          ref: ${{ github.head_ref }}
          # See semantic-release.yml for the rationale - the App-token URL
          # set by the composite below must be the only credential source
          # so the auto-format push lands as the ORB CICD App rather than
          # falling back to github-actions[bot] via the persisted extraheader.
          persist-credentials: false

      - name: ORB CICD App token
        id: cicd
        uses: ./.github/actions/orb-cicd-app-token
        with:
          app-id: ${{ secrets.GH_APP_ID }}
          private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}

      - 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: ${{ steps.cicd.outputs.committer-name }}
          GIT_AUTHOR_EMAIL: ${{ steps.cicd.outputs.committer-email }}
          GIT_COMMITTER_NAME: ${{ steps.cicd.outputs.committer-name }}
          GIT_COMMITTER_EMAIL: ${{ steps.cicd.outputs.committer-email }}
        run: |
          git add .
          if ! git diff --staged --quiet; then
            git commit -m "style: auto-format code with ruff"
            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@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
        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@2558ba17e65a9039e73764a73009fc05fef28a46  # v1.24.3
        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 }}