ci.yml

name: CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

# Cancel in-progress runs when a new workflow with the same group name is triggered
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

permissions:
  contents: read

jobs:
  # Detect if code changes warrant full CI run
  changes:
    runs-on: ubuntu-latest
    outputs:
      code: ${{ steps.filter.outputs.code }}
      spec: ${{ steps.filter.outputs.spec }}
    steps:
      - uses: actions/checkout@v6
      - uses: dorny/paths-filter@v4
        id: filter
        with:
          filters: |
            code:
              - '!docs/**'
              - '!mkdocs.yml'
              - '!*.md'
              - '!LICENSE'
              - '!.github/copilot-instructions.md'
              - '!.github/pull_request_template.md'
              - '!.github/agents/**'
              - '!.github/instructions/**'
              - '!.github/prompts/**'
            spec:
              - 'docs/katana-openapi.yaml'
              - 'docs/upstream-specs/**'

  test:
    needs: changes
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false  # Don't cancel other matrix jobs if one fails
      matrix:
        python-version: ["3.12", "3.13", "3.14"]

    steps:
      - name: Skip for docs-only changes
        if: needs.changes.outputs.code == 'false'
        run: echo "Skipping tests for documentation-only changes"

      - name: Checkout code
        if: needs.changes.outputs.code == 'true'
        uses: actions/checkout@v6

      - name: Install uv
        if: needs.changes.outputs.code == 'true'
        uses: astral-sh/setup-uv@v7
        with:
          enable-cache: true
          cache-dependency-glob: "uv.lock"
          python-version: ${{ matrix.python-version }}

      - name: Install dependencies
        if: needs.changes.outputs.code == 'true'
        run: uv sync --all-extras

      - name: Check code formatting
        if: needs.changes.outputs.code == 'true'
        run: uv run poe format-check

      - name: Run linting and type checking
        if: needs.changes.outputs.code == 'true'
        run: uv run poe lint

      - name: Run tests
        if: needs.changes.outputs.code == 'true'
        run: uv run poe test-coverage

      - name: Upload coverage to Codecov
        if: needs.changes.outputs.code == 'true'
        uses: codecov/codecov-action@v6
        with:
          files: coverage.xml
          fail_ci_if_error: false

  # Headless-browser render tests for Prefab UI cards. Runs `poe
  # test-browser`, which spins up `fastmcp dev apps` against a minimal
  # MCP server in `katana_mcp_server/tests/browser/render_test_server.py`
  # and drives the iframe via Playwright + Chromium. Catches the
  # blank-iframe / "valid wire envelope but unrenderable" bug class
  # that the Python-side unit tests can't see.
  #
  # Single Python version (3.14) — the JS renderer doesn't care which
  # Python launched it, and re-running across the matrix would burn
  # ~5 minutes for no signal.
  browser-test:
    needs: changes
    runs-on: ubuntu-latest
    steps:
      - name: Skip for docs-only changes
        if: needs.changes.outputs.code == 'false'
        run: echo "Skipping browser tests for documentation-only changes"

      - name: Checkout code
        if: needs.changes.outputs.code == 'true'
        uses: actions/checkout@v6

      - name: Install uv
        if: needs.changes.outputs.code == 'true'
        uses: astral-sh/setup-uv@v7
        with:
          enable-cache: true
          cache-dependency-glob: "uv.lock"
          python-version: "3.14"

      - name: Install dependencies
        if: needs.changes.outputs.code == 'true'
        run: uv sync --all-extras

      - name: Cache Playwright browsers
        if: needs.changes.outputs.code == 'true'
        uses: actions/cache@v5
        with:
          path: ~/.cache/ms-playwright
          # Bust the cache when the playwright pin changes — the
          # browser build is pinned to the SDK version.
          key: playwright-chromium-${{ runner.os }}-${{ hashFiles('uv.lock') }}

      - name: Install Chromium for Playwright
        if: needs.changes.outputs.code == 'true'
        run: uv run playwright install --with-deps chromium

      - name: Run browser-render tests
        if: needs.changes.outputs.code == 'true'
        run: uv run poe test-browser

  quality:
    needs: changes
    runs-on: ubuntu-latest
    steps:
      - name: Skip for docs-only changes
        if: needs.changes.outputs.code == 'false' && needs.changes.outputs.spec == 'false'
        run: echo "Skipping quality checks for documentation-only changes"

      - name: Checkout code
        if: needs.changes.outputs.code == 'true' || needs.changes.outputs.spec == 'true'
        uses: actions/checkout@v6

      - name: Install uv
        if: needs.changes.outputs.code == 'true' || needs.changes.outputs.spec == 'true'
        uses: astral-sh/setup-uv@v7
        with:
          enable-cache: true
          cache-dependency-glob: "uv.lock"
          python-version: "3.14"

      - name: Install dependencies
        if: needs.changes.outputs.code == 'true' || needs.changes.outputs.spec == 'true'
        run: uv sync --all-extras

      - name: Validate OpenAPI specification
        if: needs.changes.outputs.code == 'true' || needs.changes.outputs.spec == 'true'
        run: uv run poe validate-openapi

      - name: Validate inline spec examples
        if: needs.changes.outputs.code == 'true' || needs.changes.outputs.spec == 'true'
        run: uv run poe validate-examples

      - name: Build documentation
        if: needs.changes.outputs.code == 'true'
        run: uv run poe docs-build
        env:
          CI_DOCS_BUILD: "true"
          # Silences the "Warning from the Material for MkDocs team" prep-banner
          # ahead of the MkDocs 2.0 transition (handled separately).
          NO_MKDOCS_2_WARNING: "true"
          # Silences the promotional banner injected by `properdocs`, pulled in
          # transitively as a hard requirement of mkdocs-gen-files /
          # mkdocs-literate-nav. See follow-up issue.
          DISABLE_MKDOCS_2_WARNING: "true"

      - name: Test documentation
        if: needs.changes.outputs.code == 'true'
        run: uv run poe test-docs
        env:
          CI_DOCS_BUILD: "true"
          NO_MKDOCS_2_WARNING: "true"
          DISABLE_MKDOCS_2_WARNING: "true"