ci.yml

name: CI

on:
  push:
    branches: [main]
    # README-only changes don't affect code, tests, or the mkdocs site
    # (which is built from docs/, not README.md), so skip the full CI for them.
    paths-ignore: ['README.md']
  pull_request:
    branches: [main]
    paths-ignore: ['README.md']
  workflow_dispatch:

# Least-privilege default for all jobs — none need write access. (The release
# workflow grants id-token: write per-job for OIDC publishing; CI needs read.)
permissions:
  contents: read

jobs:
  test:
    name: Python ${{ matrix.python-version }} on ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python-version: ["3.13", "3.14"]

    steps:
      - uses: actions/checkout@v7

      - name: Install uv
        uses: astral-sh/setup-uv@v8.2.0

      - name: Set up Python ${{ matrix.python-version }}
        run: uv python install ${{ matrix.python-version }}

      - name: Install dependencies
        run: uv sync --all-extras

      - name: Run tests
        run: uv run pytest

  lint:
    name: Lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - name: Install uv
        uses: astral-sh/setup-uv@v8.2.0

      - name: Install dependencies
        run: uv sync --all-extras

      - name: Check formatting
        run: uv run ruff format --check .

      - name: Check linting
        run: uv run ruff check .

      # Docstring consistency (pydoclint) runs inside the pytest suite via
      # tests/test_docstrings.py, so it's not a separate CI lint step.

      - name: Type check (mypy)
        run: uv run mypy vgi/

      # ty is pre-1.0 and its inference drifts release-to-release; keep it
      # visible as a signal but don't gate CI on it (mypy is the blocking
      # type gate).
      - name: Type check (ty, non-blocking)
        run: uv run ty check vgi/
        continue-on-error: true

  docs:
    name: Docs (build + examples + prose)
    runs-on: ubuntu-latest
    env:
      DISABLE_MKDOCS_2_WARNING: "true"
    steps:
      - uses: actions/checkout@v7

      - name: Install uv
        uses: astral-sh/setup-uv@v8.2.0

      - name: Set up Python 3.13
        run: uv python install 3.13

      - name: Install dependencies
        run: uv sync --all-extras --group docs

      - name: Install d2
        run: curl -fsSL https://d2lang.com/install.sh | sh -s --

      - name: Build docs (strict)
        run: uv run mkdocs build --strict

      - name: Test documentation examples
        run: uv run pytest tests/test_documentation_examples.py tests/test_examples_workers.py -q

      # Prose lint. Runs on every PR as a signal. Kept non-blocking for now:
      # the Google package + spelling check needs a vocabulary-tuning pass
      # against a real run before it can gate without false positives. Flip
      # fail_on_error to true (and drop continue-on-error) once the vocab in
      # .github/styles/config/vocabularies/VGI/accept.txt is settled.
      - name: Prose lint (Vale)
        uses: errata-ai/vale-action@v2
        continue-on-error: true
        with:
          files: docs
          fail_on_error: true

      - name: Link check (lychee)
        uses: lycheeverse/lychee-action@v2
        with:
          # --root-dir resolves root-relative links (e.g. <img src="/assets/...">,
          # which mkdocs serves from the site root = docs/) for offline checking.
          args: "--no-progress --offline --root-dir ${{ github.workspace }}/docs docs/**/*.md *.md"
          fail: true

  s3-offload-localstack:
    name: S3 Offload Tests (LocalStack)
    runs-on: ubuntu-latest
    services:
      localstack:
        image: localstack/localstack:3.0
        ports:
          - 4566:4566
        env:
          SERVICES: s3
          AWS_DEFAULT_REGION: us-east-1
    steps:
      - uses: actions/checkout@v7

      - name: Checkout vgi-rpc
        uses: actions/checkout@v7
        with:
          repository: Query-farm/vgi-rpc-python
          path: vgi-rpc

      - name: Install uv
        uses: astral-sh/setup-uv@v8.2.0

      - name: Set up Python 3.13
        run: uv python install 3.13

      - name: Install test dependencies
        run: |
          # Project env first (vgi + fixtures + dev tools), then overlay the
          # local vgi-rpc checkout with the s3/external extras plus boto3.
          # Subsequent uv run calls must pass --no-sync or uv re-syncs the
          # env to the lockfile and drops the overlay.
          uv sync --all-extras --python 3.13
          uv pip install './vgi-rpc[http,s3,external]' boto3

      - name: Create test bucket in LocalStack
        env:
          AWS_ACCESS_KEY_ID: test
          AWS_SECRET_ACCESS_KEY: test
          AWS_DEFAULT_REGION: us-east-1
        run: |
          uv run --no-sync python - <<'PY'
          import time
          import boto3
          from botocore.exceptions import EndpointConnectionError

          endpoint = "http://127.0.0.1:4566"
          s3 = boto3.client(
              "s3",
              endpoint_url=endpoint,
              aws_access_key_id="test",
              aws_secret_access_key="test",
              region_name="us-east-1",
          )

          for _ in range(30):
              try:
                  s3.list_buckets()
                  break
              except EndpointConnectionError:
                  time.sleep(1)
          else:
              raise RuntimeError("LocalStack S3 did not become ready in time")

          s3.create_bucket(Bucket="vgi-offload-test")
          PY

      - name: Run HTTP S3 offload tests
        env:
          AWS_ACCESS_KEY_ID: test
          AWS_SECRET_ACCESS_KEY: test
          AWS_DEFAULT_REGION: us-east-1
          VGI_RUN_S3_HTTP_TESTS: "1"
          VGI_HTTP_S3_BUCKET: vgi-offload-test
          VGI_HTTP_S3_ENDPOINT_URL: http://127.0.0.1:4566
          PYTHONPATH: ${{ github.workspace }}
        run: uv run --no-sync pytest tests/test_http_s3_offload_output.py tests/test_http_s3_offload_input.py -q