verify.yml

# Pull request verification workflow.
# Purpose: cross-version test matrix and artifact install verify as required PR gates.
# This is the primary merge gate for all PRs to main.
name: Verify

on:
  # Run on PRs targeting main so merge decisions are based on full verification.
  pull_request:
    branches: [main]

concurrency:
  # Cancel superseded verification runs for the same PR.
  group: verify-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

permissions:
  # Verify jobs only read repository contents.
  contents: read

env:
  # Shared interpreter version for reproducible CI behavior.
  PYTHON_VERSION: "3.11"
  # Pin Poetry CLI version for deterministic CI behavior.
  POETRY_VERSION: "2.4.1"
  # Keep Poetry virtual environments inside the workspace for deterministic paths.
  POETRY_VIRTUALENVS_IN_PROJECT: "true"
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"

jobs:
  test-matrix:
    # Cross-version test coverage for all supported Python runtimes.
    # Runs on all PRs to main as a required merge gate.
    name: Tests (py${{ matrix.python-version }})
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        python-version: ["3.11", "3.12", "3.13", "3.14"]

    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1

      - name: Install Poetry
        run: pipx install "poetry==${POETRY_VERSION}"

      - name: Setup Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
        with:
          python-version: ${{ matrix.python-version }}
          cache: poetry
          cache-dependency-path: poetry.lock

      - name: Install dependencies
        run: poetry install --no-interaction --no-ansi

      - name: Test
        run: make test-local

  fixture-tests-fast:
    # Fast deterministic feedback for fixture drift and defect harness checks.
    name: Fixture Tests (fast)
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1

      - name: Install Poetry
        run: pipx install "poetry==${POETRY_VERSION}"

      - name: Setup Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
        with:
          python-version: ${{ env.PYTHON_VERSION }}
          cache: poetry
          cache-dependency-path: poetry.lock

      - name: Install dependencies
        run: poetry install --no-interaction --no-ansi

      - name: Run fixture-only golden and defect tests
        run: make test-fixtures

  vstack-verify:
    # Ensures generated artifacts can be installed and validated in an isolated target.
    name: Artifact Install Verify
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1

      - name: Install Poetry
        run: pipx install "poetry==${POETRY_VERSION}"

      - name: Setup Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
        with:
          python-version: ${{ env.PYTHON_VERSION }}
          cache: poetry
          cache-dependency-path: poetry.lock

      - name: Install dependencies
        run: poetry install --no-interaction --no-ansi

      - name: Set unique temp target directory
        # Avoid cross-run collisions on shared/self-hosted runners.
        run: echo "TARGET_DIR=${RUNNER_TEMP}/vstack-pr-target-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}" >> "$GITHUB_ENV"

      - name: Create temp target directory
        run: mkdir -p "${TARGET_DIR}"

      - name: Install artifacts into temp target
        run: poetry run vstack install --target "${TARGET_DIR}"

      - name: Verify source and installed output
        run: poetry run vstack verify --target "${TARGET_DIR}"

      - name: Drift guard for generated artifacts
        run: |
          poetry run vstack install
          # Ignore drift caused only by VSTACK-META vstack_version differences
          # between local tagged checkouts and CI shallow clones.
          if ! git --no-pager diff --quiet -I '"vstack_version":' -- .github; then
            echo "Generated artifact drift detected under .github/."
            echo "Run 'python3 -m vstack install' locally and commit the resulting changes."
            echo "Changed files:"
            git --no-pager diff --name-only -I '"vstack_version":' -- .github
            echo "Diff:"
            git --no-pager diff -I '"vstack_version":' -- .github || true
            exit 1
          fi