validate.yml

# ============================================================
# .github/workflows/validate.yml (Validation Workflow)
# ============================================================
# Updated: 2026-04-26 (REPO-SPECIFIC)
# PURPOSE: Run all validation checks and build the coverage matrix.

name: Validate

on:
  push:
  pull_request:
  workflow_call: # WHY: Allow this workflow to be called by other workflows if needed
  workflow_dispatch: # WHY: Manual trigger - always available

permissions:
  contents: read

env:
  PYTHONUNBUFFERED: "1"    # WHY: Real-time log output in CI.
  PYTHONIOENCODING: "utf-8" # WHY: Consistent encoding across platforms.
  PYTHON_VERSION: "3.15"
  UV_PYTHON: "3.15"

jobs:
  validate:
    runs-on: ubuntu-latest

    steps:
      # ============================================================
      # A) ASSEMBLE: Checkout code and set up environment
      # ============================================================

      - name: A1) Checkout repository code
        uses: actions/checkout@v6
        # WHY: Required so all subsequent steps can access repo files.

      - name: A2) Install uv (with caching)
        uses: astral-sh/setup-uv@v7
        with:
          enable-cache: true
          # WHY: Cache the uv tool itself for faster subsequent runs.
          cache-dependency-glob: "uv.lock"
          # WHY: Invalidate cache only when locked dependencies change.

      - name: A3) Install Python ${{ env.PYTHON_VERSION }}
        run: uv python install ${{ env.PYTHON_VERSION }}
        # WHY: Ensures the pinned Python version is available in CI.
        # OBS: Does not modify the repo; uv manages the interpreter locally.

      - name: A4) Install all dependencies
        run: uv sync --extra dev --extra docs --upgrade
        # WHY: Install dev and docs extras so all check and build tools are available.
        # OBS: --upgrade ensures CI catches dependency drift early.

      - name: A5) Show tool versions
        run: |
          uv --version
          uv run python --version
          uv run python -m ruff --version
          uv run python -m pyright --version
          if [ -f "zensical.toml" ]; then
            uv run python -m zensical --version
          fi
        # WHY: Version output helps debug when tools change.

      # ============================================================
      # B) BASELINE CHECKS: Repo-specific validation and matrix build
      # ============================================================
      - name: B1) Run validation
        run: uv run python -m se_mapping_education_math_g8 validate

      - name: B2) Build coverage matrix
        run: uv run python -m se_mapping_education_math_g8 matrix