bambuddy/.github/workflows/ci.yml

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:
    # Run on PRs targeting main, but skip for repo owner (runs local tests)

# Skip CI for PRs authored by repo owner (they run tests locally)
# Uses PR author instead of triggering actor so rebasing by owner doesn't skip CI

env:
  PYTHON_VERSION: '3.11'
  NODE_VERSION: '22'

# Cancel in-progress runs for the same branch
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

# Minimum permissions for all jobs
permissions:
  contents: read

jobs:
  # ============================================================================
  # Backend Checks
  # ============================================================================

  backend-lint:
    name: Backend Lint
    runs-on: ubuntu-latest
    if: github.event_name == 'push' || github.event.pull_request.user.login != github.repository_owner
    steps:
      - uses: actions/checkout@v6

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: ${{ env.PYTHON_VERSION }}

      - name: Install ruff
        # Install the exact pin from requirements-dev.txt rather than the latest
        # release, so CI and contributors run the same linter. `pip install ruff`
        # silently drifted ahead of every local venv.
        run: pip install "$(grep -E '^ruff==' requirements-dev.txt)"

      - name: Run ruff check
        run: ruff check backend/

      - name: Run ruff format check
        run: ruff format --check backend/

  backend-typecheck:
    name: Backend Type Check
    runs-on: ubuntu-latest
    if: github.event_name == 'push' || github.event.pull_request.user.login != github.repository_owner
    steps:
      - uses: actions/checkout@v6

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: ${{ env.PYTHON_VERSION }}

      - name: Install the pinned type-check environment
        # requirements-typecheck.lock, not requirements.txt: the baseline only
        # holds for these exact library versions (see requirements-typecheck.txt).
        run: pip install -r requirements-typecheck.lock

      - name: Check the lock covers requirements.txt
        # A dependency added to requirements.txt but not to the lock would show
        # up below as an unresolved import instead of saying what is wrong.
        run: |
          if ! out=$(pip install --dry-run -r requirements.txt 2>&1); then
            echo "$out"
            echo "::error::pip could not resolve requirements.txt against the type-check environment."
            exit 1
          fi
          if echo "$out" | grep '^Would install'; then
            echo "::error::requirements-typecheck.lock is missing packages from requirements.txt. Regenerate it as described in requirements-typecheck.txt."
            exit 1
          fi

      - name: Run basedpyright
        # Errors recorded in .basedpyright/baseline.json pass; any new one fails.
        # Lock mode also fails when a baselined error was fixed but the smaller
        # baseline was not committed.
        run: basedpyright --pythonpath "$(which python)" --baselinemode=lock

  backend-security:
    name: Backend Security
    runs-on: ubuntu-latest
    if: github.event_name == 'push' || github.event.pull_request.user.login != github.repository_owner
    continue-on-error: true
    steps:
      - uses: actions/checkout@v6

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: ${{ env.PYTHON_VERSION }}

      - name: Install dependencies
        run: |
          # Upgrade setuptools too: the runner's Python toolcache ships an old
          # setuptools that trips pip-audit (PYSEC-2026-3447, fixed in 83.0.0).
          # A fix exists, so we upgrade rather than --ignore-vuln.
          python -m pip install --upgrade pip setuptools
          pip install -r requirements.lock
          pip install pip-audit

      - name: Run pip-audit
        run: |
          # CVE-2026-4539: low-severity ReDoS in Pygments AdlLexer (indirect dep via mkdocs-material/pytest/rich).
          # No fix available yet. Remove --ignore-vuln once Pygments releases a patched version.
          #
          # CVE-2025-45768 (PYSEC-2025-183 / GHSA-65pc-fj4g-8rjx): disputed by PyJWT maintainers.
          # Advisory says "key length is chosen by the application that uses the library" — no
          # PyJWT fix exists or will exist. Bambuddy is safe: backend/app/core/auth.py:184 uses
          # secrets.token_urlsafe(64) (~86 chars of entropy) for auto-generated secrets and
          # rejects file-loaded secrets shorter than 32 chars at :177. Keep ignored permanently.
          pip-audit --desc on \
            --ignore-vuln CVE-2026-4539 \
            --ignore-vuln CVE-2025-45768

  backend-tests:
    name: Backend Tests (shard ${{ matrix.shard }}/4)
    runs-on: ubuntu-latest
    if: github.event_name == 'push' || github.event.pull_request.user.login != github.repository_owner
    needs: backend-lint
    strategy:
      # Don't cancel sibling shards if one fails — we want every shard's
      # failure list, not just the first one, so a single PR push shows
      # all broken tests in one go.
      fail-fast: false
      matrix:
        shard: [1, 2, 3, 4]
    steps:
      - uses: actions/checkout@v6

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: ${{ env.PYTHON_VERSION }}

      - name: Cache pip
        uses: actions/cache@v5
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-${{ hashFiles('requirements.lock', 'requirements-dev.txt') }}
          restore-keys: |
            ${{ runner.os }}-pip-

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          # The pinned versions that ship (Docker, installers), not whatever is newest.
          pip install -r requirements.lock
          pip install -r requirements-dev.txt

      - name: Run tests (shard ${{ matrix.shard }}/4)
        timeout-minutes: 15
        run: |
          cd backend
          # -v dropped: 5300+ "PASSED foo::bar" lines per worker eat 30-60s
          # of stdout I/O time on 2-vCPU runners. --tb=short is enough.
          #
          # --splits 4 --group N slices the suite across the 4 matrix shards.
          # Without a durations file pytest-split balances by test COUNT, which
          # is not the same thing as time: measured 2026-08-31, that put 658s of
          # the suite's 1046s into shard 1 and 101s into shard 4 -- a 6.5x spread
          # that walked shard 1 into the old 10-minute timeout on a docs-only
          # commit. tests/.test_durations is committed so the split is balanced
          # by measured time instead (1.01x spread). Shard test counts are
          # lopsided by design once it is used: shard 4 takes thousands of fast
          # unit tests, shard 1 keeps the slow integration ones.
          #
          # --durations-path must be explicit: pytest-split defaults it to
          # $CWD/.test_durations, and this job runs from backend/ while the
          # Docker job below runs from the image root. Left implicit, one of
          # them silently finds no file and falls back to the count split.
          # Regenerate after adding slow tests:
          #   cd backend && python -m pytest tests/ --store-durations \
          #     --durations-path tests/.test_durations
          python -m pytest tests/ \
            --tb=short \
            --timeout=60 --timeout-method=thread \
            -n auto \
            --splits 4 --group ${{ matrix.shard }} \
            --durations-path tests/.test_durations

  backend-postgres-upgrade:
    # The test suite runs on SQLite only. This builds PostgreSQL databases with
    # older releases' code, upgrades them and compares each with a fresh
    # install (see scripts/check_postgres_upgrade.py).
    name: PostgreSQL Upgrade Check
    runs-on: ubuntu-latest
    if: github.event_name == 'push' || github.event.pull_request.user.login != github.repository_owner
    needs: backend-lint
    services:
      postgres:
        # The version the docker-compose example and the wiki use.
        image: postgres:16-alpine
        env:
          POSTGRES_PASSWORD: ci
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 5s
          --health-timeout 5s
          --health-retries 20
    steps:
      - uses: actions/checkout@v6
        with:
          # The release tags: older releases' code builds the databases to upgrade.
          fetch-depth: 0

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: ${{ env.PYTHON_VERSION }}

      - name: Cache pip
        uses: actions/cache@v5
        with:
          path: ~/.cache/pip
          # Its own key: this job installs the lock only, and finishes long
          # before the test shards, so sharing theirs would save a cache
          # without the dev packages under their key.
          key: ${{ runner.os }}-pip-lock-${{ hashFiles('requirements.lock') }}
          restore-keys: |
            ${{ runner.os }}-pip-lock-

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.lock

      - name: Upgrade from older releases and compare with a fresh install
        timeout-minutes: 10
        run: python scripts/check_postgres_upgrade.py --url postgresql://postgres:ci@localhost:5432/postgres

  # ============================================================================
  # Frontend Checks
  # ============================================================================

  frontend-lint:
    name: Frontend Lint
    runs-on: ubuntu-latest
    if: github.event_name == 'push' || github.event.pull_request.user.login != github.repository_owner
    steps:
      - uses: actions/checkout@v6

      - name: Set up Node.js
        uses: actions/setup-node@v6
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
          cache-dependency-path: frontend/package-lock.json

      - name: Install dependencies
        working-directory: frontend
        run: npm ci

      - name: Run ESLint
        working-directory: frontend
        run: npm run lint

      - name: Unused files and dependencies (knip)
        working-directory: frontend
        run: npm run check:knip

  frontend-security:
    name: Frontend Security
    runs-on: ubuntu-latest
    if: github.event_name == 'push' || github.event.pull_request.user.login != github.repository_owner
    continue-on-error: true
    steps:
      - uses: actions/checkout@v6

      - name: Set up Node.js
        uses: actions/setup-node@v6
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
          cache-dependency-path: frontend/package-lock.json

      - name: Install dependencies
        working-directory: frontend
        run: npm ci

      - name: Run npm audit
        working-directory: frontend
        run: |
          # Only audit production dependencies and filter out npm-internal packages.
          # npm 10.x audit/ls reports vulns in its own bundled deps (npm, tar, minimatch)
          # so we parse package-lock.json directly to get the real prod dep list.
          npm audit --omit=dev --json > /tmp/audit.json 2>/dev/null || true
          python3 -c "
          import json, sys
          data = json.load(open('/tmp/audit.json'))
          lock = json.load(open('package-lock.json'))
          prod = set()
          for path, info in lock.get('packages', {}).items():
              if path and not info.get('dev') and not info.get('devOptional'):
                  prod.add(path.split('node_modules/')[-1])
          vulns = data.get('vulnerabilities', {})
          # Documented advisory exceptions: high/critical findings whose only offered
          # 'fix' is a semver-major change and which do not apply to how Bambuddy ships.
          # Keyed by GHSA id. An entry only holds while the fix stays major-only (see
          # fix_is_major below) - once upstream backports, the gate fails until we take
          # the patch. That is what retired the one entry this list used to carry:
          # GHSA-qwww-vcr4-c8h2 (React Router RSC-mode CSRF) shipped in 7.18.2, so the
          # pin moved rather than the exception staying.
          ALLOWLIST = set()
          def advisory_ids(name, seen=None):
              seen = seen if seen is not None else set()
              if name in seen:
                  return set()
              seen.add(name)
              ids = set()
              for item in vulns.get(name, {}).get('via', []):
                  if isinstance(item, dict):
                      url = item.get('url', '')
                      if '/advisories/' in url:
                          ids.add(url.rsplit('/', 1)[-1])
                  elif isinstance(item, str):
                      ids |= advisory_ids(item, seen)
              return ids
          def fix_is_major(v):
              fa = v.get('fixAvailable')
              return isinstance(fa, dict) and fa.get('isSemVerMajor')
          def exempt(name, v):
              ids = advisory_ids(name)
              return bool(ids) and ids <= ALLOWLIST and fix_is_major(v)
          fixable = {n: v for n, v in vulns.items()
                     if n in prod and v.get('severity') in ('high', 'critical')
                     and v.get('fixAvailable') and not exempt(n, v)}
          skipped = len(vulns) - len({n: v for n, v in vulns.items() if n in prod})
          if fixable:
              for name, v in fixable.items():
                  print(f'FIXABLE {v[\"severity\"].upper()}: {name}')
              sys.exit(1)
          total = sum(1 for n, v in vulns.items() if n in prod and v.get('severity') in ('high', 'critical'))
          exempted = sorted(n for n, v in vulns.items() if n in prod and exempt(n, v))
          print(f'npm audit: {total} high/critical (0 fixable), {len(vulns)} total ({skipped} npm-internal filtered)')
          if exempted:
              print('exempted (documented, unreachable): ' + ', '.join(exempted))
          "

  frontend-typecheck:
    name: Frontend Type Check
    runs-on: ubuntu-latest
    if: github.event_name == 'push' || github.event.pull_request.user.login != github.repository_owner
    steps:
      - uses: actions/checkout@v6

      - name: Set up Node.js
        uses: actions/setup-node@v6
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
          cache-dependency-path: frontend/package-lock.json

      - name: Install dependencies
        working-directory: frontend
        run: npm ci

      # `tsc -b`, not `tsc --noEmit`: the root tsconfig only holds project
      # references, so plain `tsc` checks zero files. Kept out of `npm run
      # build` because every installer runs that on the user's machine, and
      # the type check alone needs ~1 GB of Node heap (#3181).
      - name: Run TypeScript check
        working-directory: frontend
        run: npm run typecheck

  frontend-tests:
    name: Frontend Tests
    runs-on: ubuntu-latest
    if: github.event_name == 'push' || github.event.pull_request.user.login != github.repository_owner
    needs: [frontend-lint, frontend-typecheck]
    steps:
      - uses: actions/checkout@v6

      - name: Set up Node.js
        uses: actions/setup-node@v6
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
          cache-dependency-path: frontend/package-lock.json

      - name: Install dependencies
        working-directory: frontend
        run: npm ci

      - name: Run tests
        timeout-minutes: 10
        working-directory: frontend
        run: npm run test:run

  frontend-build:
    name: Frontend Build
    runs-on: ubuntu-latest
    if: github.event_name == 'push' || github.event.pull_request.user.login != github.repository_owner
    needs: [frontend-tests]
    steps:
      - uses: actions/checkout@v6

      - name: Set up Node.js
        uses: actions/setup-node@v6
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
          cache-dependency-path: frontend/package-lock.json

      - name: Install dependencies
        working-directory: frontend
        run: npm ci

      - name: Build
        working-directory: frontend
        run: npm run build

  # ============================================================================
  # Docker Tests (matches test_docker.sh)
  # ============================================================================

  # Run the FULL backend test suite inside the test image, sharded 4-way
  # so wall-clock matches the host-side backend-tests job. Catches the
  # rare-but-real cases where a test passes on the GHA host but fails in
  # the python:3.13-slim test image (system-binary version differences,
  # locale/timezone, container vs host user, cwd assumptions). Without
  # sharding this was a 5-10 min single-runner job; with sharding it's
  # ~120-150s per shard running in parallel, gated by max(shard).
  docker-backend-tests:
    name: Docker Backend Tests (shard ${{ matrix.shard }}/4)
    runs-on: ubuntu-latest
    if: github.event_name == 'push' || github.event.pull_request.user.login != github.repository_owner
    timeout-minutes: 15
    strategy:
      fail-fast: false
      matrix:
        shard: [1, 2, 3, 4]
    steps:
      - uses: actions/checkout@v6

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      # Build the backend-test image with GHA BuildKit cache backend so
      # the pip-install layer is shared across the 4 matrix shards AND
      # across CI runs. First run on a given requirements.txt is cold
      # (~60-90s); subsequent runs are ~5-10s.
      - name: Build backend test image (cached)
        uses: docker/build-push-action@v7
        with:
          context: .
          file: Dockerfile.test
          target: backend-test
          load: true
          tags: bambuddy-backend-test:latest
          cache-from: type=gha,scope=backend-test
          cache-to: type=gha,scope=backend-test,mode=max

      - name: Run backend tests in Docker (shard ${{ matrix.shard }}/4)
        run: |
          docker run --rm \
            -e TESTING=1 \
            -e PYTHONUNBUFFERED=1 \
            bambuddy-backend-test:latest \
            pytest backend/tests/ \
              --tb=short \
              --timeout=60 --timeout-method=thread \
              -p no:cacheprovider \
              -n auto \
              --splits 4 --group ${{ matrix.shard }} \
              --durations-path backend/tests/.test_durations

  docker-test:
    name: Docker Build
    runs-on: ubuntu-latest
    if: github.event_name == 'push' || github.event.pull_request.user.login != github.repository_owner
    timeout-minutes: 20
    needs: [backend-tests, frontend-build]
    steps:
      - uses: actions/checkout@v6

      # Test 1: Docker Build
      - name: Build production image
        run: docker build -t bambuddy:test .

      - name: Verify backend imports
        run: docker run --rm bambuddy:test python -c "import backend.app.main; print('Backend imports OK')"

      - name: Verify static files exist
        run: docker run --rm bambuddy:test test -d /app/static

      # Test 4: Integration Tests
      - name: Build integration container
        run: docker compose -f docker-compose.test.yml build integration

      - name: Start integration container
        run: |
          docker compose -f docker-compose.test.yml up -d integration
          echo "Waiting for container to be healthy..."
          for i in {1..30}; do
            if docker compose -f docker-compose.test.yml ps integration | grep -q "healthy"; then
              echo "Container is healthy"
              break
            fi
            sleep 2
          done

      - name: Test health endpoint
        run: |
          HEALTH=$(docker compose -f docker-compose.test.yml exec -T integration curl -s http://localhost:8000/health)
          echo "$HEALTH"
          echo "$HEALTH" | grep -q "healthy"

      - name: Test API endpoint
        run: |
          docker compose -f docker-compose.test.yml exec -T integration curl -s http://localhost:8000/api/v1/settings

      - name: Test static files served
        run: |
          STATUS=$(docker compose -f docker-compose.test.yml exec -T integration curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/)
          echo "Static files HTTP status: $STATUS"
          [ "$STATUS" = "200" ]

      # Test 5: Integration Test Suite (pytest)
      - name: Build integration test runner
        run: docker compose -f docker-compose.test.yml build integration-test-runner

      - name: Run integration test suite
        run: docker compose -f docker-compose.test.yml run --rm integration-test-runner

      - name: Show logs on failure
        if: failure()
        run: docker compose -f docker-compose.test.yml logs

      - name: Cleanup
        if: always()
        run: docker compose -f docker-compose.test.yml down -v --remove-orphans