python-315-ready.yml

# ============================================================
# .github/workflows/python-315-ready.yml (Python 3.15 readiness)
# ============================================================
# Updated: 2026-05-26 REPO SPECIFIC

name: Python 3.15 Ready

on:
  push:
    branches: [main] # WHY: Validate every push to main.
  pull_request:
    branches: [main] # WHY: Validate PRs before merge.
  workflow_dispatch: # WHY: Allow manual trigger from Actions tab.

permissions:
  contents: read # WHY: Least privilege; only reads, never writes.

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:
  python-315-ready:
    name: Python 3.15 readiness
    runs-on: ubuntu-latest
    timeout-minutes: 30 # WHY: Fail fast if a step hangs unexpectedly.
    continue-on-error: true

    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) Set up Python  ${{ env.PYTHON_VERSION }}
        uses: actions/setup-python@v6
        with:
          python-version: ${{ env.PYTHON_VERSION }}
          allow-prereleases: true

      - name: A4) Install all dependencies
        run: uv sync --extra dev --extra docs --upgrade

      - 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

      - name: A6) Run pre-commit on all files
        run: uv tool run pre-commit run --all-files

      # ============================================================
      # B) BASELINE CHECKS: Tools not covered by pre-commit
      # ============================================================
      - name: B1) Run Pyright type checker
        run: uv run python -m pyright

      # ============================================================
      # C) COVERAGE & TESTING: Python tests (pytest)
      # ============================================================
      - name: C1) Run pytest
        run: uv run python -m pytest

      # ============================================================
      # D) Docs build (no deployment)
      # ============================================================
      - name: D1) Build documentation with Zensical
        run: |
          if [ -f "zensical.toml" ]; then
            uv run python -m zensical build
          else
            echo "No zensical.toml found; skipping docs build."
          fi

      # ============================================================
      # E) Execute local cli commands for additional checks
      # ===========================================================
      - name: E1) Validate repository manifest against schema
        run: uv run se-manifest validate-manifest --strict

      - name: E2) Run Accountable Record verifier pipeline
        run: uv run accountable-record run all

      - name: E3) Verify lock is current
        run: uv run accountable-record verify-lock

      - name: E4) Check complexity threshold
        run: uvx radon cc src/accountable_record -s -a -n C