python-ci.yml

name: Python CI

# Reusable CI for MattFisher Python projects: uv install, basedpyright, pytest,
# and the shared pre-commit stack (ruff + zizmor + mdformat). Consumers call it
# from a thin workflow — see the scaffolded `.github/workflows/ci.yml`.
on:
  workflow_call:
    inputs:
      python-version:
        description: Python version to run against.
        type: string
        default: "3.12"
      runs-on:
        description: Runner to execute on (lets callers matrix over OSes).
        type: string
        default: ubuntu-latest
      typecheck-paths:
        description: Paths to type-check.
        type: string
        default: "src"
      mypy-paths:
        description: Deprecated alias of typecheck-paths; wins when set.
        type: string
        default: ""
      working-directory:
        description: >
          Directory holding pyproject.toml. Defaults to the repo root; set to a
          subdirectory for a repo where the Python project isn't at the top.
          Mirrors the same input on node-ci.yml.
        type: string
        default: "."
      lfs:
        description: >
          Fetch Git LFS objects during checkout. Off by default: LFS pulls cost
          bandwidth against the account quota on every run. Turn it on for a
          repo whose tests read LFS-tracked fixtures — without it they get the
          pointer files, and fail with whatever the reading library says about
          malformed input rather than anything about LFS.
        type: boolean
        default: false

permissions:
  contents: read

jobs:
  ci:
    name: Lint, type-check, and test
    runs-on: ${{ inputs.runs-on }}
    permissions:
      contents: read
    defaults:
      run:
        working-directory: ${{ inputs.working-directory }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
          lfs: ${{ inputs.lfs }}

      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        with:
          python-version: ${{ inputs.python-version }}

      - name: Install dependencies
        run: uv sync --locked

      # `v1` is a moving tag, so this step lands on consumers that still have
      # mypy in their dev dependencies (scaffolds from before the basedpyright
      # migration). Fall back to mypy for those until they run `copier update`.
      - name: Type check (basedpyright, or mypy where not yet migrated)
        env:
          TYPECHECK_PATHS: ${{ inputs.mypy-paths || inputs.typecheck-paths }} # via env to avoid run-step template injection
        run: |
          if uv run --no-sync basedpyright --version >/dev/null 2>&1; then
            uv run basedpyright $TYPECHECK_PATHS
          else
            echo "basedpyright not in the project's dependencies; falling back to mypy (deprecated — migrate via 'copier update')"
            uv run mypy $TYPECHECK_PATHS
          fi

      - name: Pytest
        run: uv run pytest

      # We cache pre-commit's hook environments ourselves rather than using
      # pre-commit/action: that action keys its cache on env.pythonLocation,
      # which only setup-python populates. With setup-uv the segment is empty,
      # collapsing the key to the config hash alone — shared across every
      # Python version AND OS in a caller's matrix. A macOS job then restores a
      # Linux-built cache (/home/runner paths) → InvalidManifestError. Keying on
      # runner.os + the Python version keeps each matrix leg isolated.
      - name: Cache pre-commit environments
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: ~/.cache/pre-commit
          key: pre-commit-3|${{ runner.os }}|${{ inputs.python-version }}|${{ hashFiles(format('{0}/.pre-commit-config.yaml', inputs.working-directory)) }}

      - name: Pre-commit (ruff, zizmor, mdformat)
        env:
          GH_TOKEN: ${{ github.token }} # lets zizmor's online checks query the GitHub API
        run: uv run pre-commit run --show-diff-on-failure --color=always --all-files --hook-stage manual