ci.yml

name: CI

on:
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened, ready_for_review]
  workflow_dispatch:
  # Callable as a gate by release.yml, which passes the pinned release SHA as
  # `ref` so the whole matrix runs against the exact commit being released
  # (not the branch tip). When triggered by a PR, `ref` is empty and every
  # checkout falls back to the triggering ref.
  workflow_call:
    inputs:
      ref:
        description: "Commit SHA / ref to check out. Empty = triggering ref."
        required: false
        type: string
        default: ""

concurrency:
  # Distinct group per release ref so a release-triggered run never cancels (or
  # is cancelled by) a PR's CI. PR runs still coalesce per PR number.
  group: ${{ github.workflow }}-${{ inputs.ref || github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

jobs:
  rust:
    name: Rust (${{ matrix.os }})
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ inputs.ref }}

      - name: Install Rust toolchain
        uses: dtolnay/rust-toolchain@stable

      - name: Cache cargo
        uses: Swatinem/rust-cache@v2

      - name: cargo test
        run: cargo test --workspace --all-targets

      - name: cargo doc
        env:
          RUSTDOCFLAGS: -D warnings
        run: cargo doc --workspace --no-deps

      # cargo fmt and cargo clippy are intentionally not gated here yet —
      # see the cleanup follow-up. Add them back once the repo is clean.

  python:
    name: Python (${{ matrix.os }}, ${{ matrix.python }})
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python: ["3.10", "3.11", "3.12", "3.13", "3.14"]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ inputs.ref }}

      - name: Install Rust toolchain
        uses: dtolnay/rust-toolchain@stable

      - name: Cache cargo
        uses: Swatinem/rust-cache@v2
        with:
          key: py-${{ matrix.os }}-${{ matrix.python }}

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

      # Create the venv and put its bin/Scripts dir on PATH so the
      # subsequent steps work identically on Unix (.venv/bin) and
      # Windows (.venv/Scripts).
      - name: Create virtualenv
        shell: bash
        run: |
          python -m venv .venv
          # GITHUB_PATH entries must be native paths. In Git Bash on Windows
          # $PWD is an MSYS path (/d/a/shell/shell) that the runner's Windows
          # PATH cannot resolve, so the venv would be silently ignored and
          # later steps would fall back to the host interpreter. Convert to a
          # native Windows path with cygpath so .venv\Scripts is actually used.
          if [ "$RUNNER_OS" == "Windows" ]; then
            cygpath -w "$PWD/.venv/Scripts" >> "$GITHUB_PATH"
          else
            echo "$PWD/.venv/bin" >> "$GITHUB_PATH"
          fi

      - name: Install build deps
        run: pip install maturin pytest

      - name: Build and install wheel
        run: maturin develop --release

      - name: pytest
        run: pytest tests/python -v

  audit:
    name: Security audit
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ inputs.ref }}

      - name: Install Rust toolchain
        uses: dtolnay/rust-toolchain@stable

      - name: Cache cargo
        uses: Swatinem/rust-cache@v2
        with:
          key: audit

      - name: cargo install cargo-audit
        run: cargo install --locked cargo-audit

      - name: cargo audit
        # Surfaces RustSec advisories in CI output. Not a hard gate yet —
        # transitive deps via reqwest/rustls carry advisories we haven't
        # triaged. Flip continue-on-error off once the dep tree is clean.
        run: cargo audit
        continue-on-error: true

      - name: Set up Node.js
        uses: actions/setup-node@v6
        with:
          node-version: "20"

      - name: npm audit (production)
        # package-lock.json is gitignored, so generate an ephemeral lockfile
        # for the audit (npm audit requires one).
        run: |
          npm install --package-lock-only
          npm audit --omit=dev

  node:
    name: Node.js (${{ matrix.os }}, Node ${{ matrix.node }})
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        node: ["20", "22", "24"]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ inputs.ref }}

      - name: Install Rust toolchain
        uses: dtolnay/rust-toolchain@stable

      - name: Cache cargo
        uses: Swatinem/rust-cache@v2
        with:
          key: node-${{ matrix.os }}-${{ matrix.node }}

      - name: Set up Node.js
        uses: actions/setup-node@v6
        with:
          node-version: ${{ matrix.node }}

      # The package.json build scripts use `$(npm run --silent host-triple)`
      # command substitution. npm runs script bodies with its configured
      # script-shell, which defaults to cmd.exe on Windows (no `$(...)`
      # support). Point it at the Git Bash that ships on the windows-latest
      # runner so the substitution works identically across platforms.
      - name: Use bash as npm script-shell (Windows)
        if: runner.os == 'Windows'
        run: npm config set script-shell bash

      - name: npm install
        # package-lock.json is gitignored, so `npm ci` can't run; use install.
        run: npm install

      - name: napi build
        run: npm run build:debug

      - name: tsc typecheck (public .d.ts surface)
        run: npm run typecheck

      - name: npm test
        run: npm test

  # Single required status check. Branch protection can require just this one
  # context ("CI Gate") instead of every matrix leg (Rust/Python/Node/audit),
  # whose names change whenever the matrix changes. This job fails if any
  # needed job failed or was cancelled, so it is a faithful aggregate gate.
  gate:
    name: CI Gate
    if: always()
    needs: [rust, python, audit, node]
    runs-on: ubuntu-latest
    steps:
      - name: Verify all required jobs succeeded
        env:
          RESULTS: ${{ join(needs.*.result, ' ') }}
        run: |
          echo "Needed job results: $RESULTS"
          for result in $RESULTS; do
            if [ "$result" != "success" ]; then
              echo "::error::A required CI job did not succeed (result: $result)."
              exit 1
            fi
          done
          echo "All required CI jobs succeeded."