ci.yml

name: CI

# Path-filters skip CI on truly content-only changes (top-level README/LICENSE/
# CHANGELOG, plus docs/ which is human-written prose). Anything that COULD
# affect runtime — src/, tests/, scripts/, eval/, site/, package*.json,
# tsconfig*.json, .github/workflows/ — still triggers CI.
on:
  push:
    branches:
      - master
    paths-ignore:
      - 'README.md'
      - 'CONTRIBUTING.md'
      - 'CHANGELOG.md'
      - 'LICENSE'
      - 'RELEASE_NOTES.md'
      - 'docs/**'
      - 'doc/**'
      - 'archive/**'
  pull_request:
    branches:
      - master
      - develop
    paths-ignore:
      - 'README.md'
      - 'CONTRIBUTING.md'
      - 'CHANGELOG.md'
      - 'LICENSE'
      - 'RELEASE_NOTES.md'
      - 'docs/**'
      - 'doc/**'
      - 'archive/**'
  workflow_dispatch:
  # Required so the branch-protection merge queue gets its checks: the queue
  # tests a speculative merge on a temporary `merge_group` ref and waits for the
  # same required checks (lint / build-and-checks / test) to report there.
  merge_group:

permissions:
  contents: read

concurrency:
  # Keyed per-PR (a new push cancels the prior run) but per-run for merge_group
  # so queued entries never cancel one another.
  group: ci-${{ github.event_name }}-${{ github.event.pull_request.number || github.run_id }}
  cancel-in-progress: true

# Three independent QC jobs run in parallel; e2e (master-only) gates on all
# three being green. See ci-acceleration-design (in kernelCAD-private).
jobs:
  lint:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v4
      - uses: ./.github/actions/setup-cad
      - name: QC — lint
        run: npm run qc:lint

  build-and-checks:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4
      - uses: ./.github/actions/setup-cad
      - name: QC — typecheck + build:cli + cookbook + drift check
        run: npm run qc:build

  # Slow modeled-thread geometry proofs (full M3–M12 helical sweep, modeled
  # tapped holes, bolt-in-nut clearance and interference on the M6 example).
  # Each modeled thread costs seconds of OCCT booleans, so these stay out of
  # the required sharded `test` gate and run here instead. Deliberately NOT a
  # required check and NOT in branch protection. The tests skip unless
  # KERNELCAD_SLOW_GEOMETRY_TESTS=1, which only this job sets.
  geometry-proofs:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v4
      - uses: ./.github/actions/setup-cad
      - name: Modeled thread proofs
        env:
          KERNELCAD_SLOW_GEOMETRY_TESTS: '1'
          NODE_OPTIONS: '--max-old-space-size=3072'
        run: npx vitest run tests/integration/modeling/modeledThreadProofs.test.ts

  # The vitest suite is sharded across parallel runners so the merge gate stays
  # responsive. Eight shards keep coverage unchanged while cutting duplicated
  # checkout/setup/build work compared with the previous 12-runner fanout.
  test-shard:
    runs-on: ubuntu-latest
    # 20 gives headroom for the shard that draws the heavy physics
    # example-sweep tests (a single example can run ~6 min) so a legitimately
    # slow run is never cancelled mid-test. Setup itself is now near-instant
    # (ffmpeg preinstalled; apt fallback bounded) so this is pure test headroom.
    timeout-minutes: 20
    strategy:
      fail-fast: false
      matrix:
        shard: [1, 2, 3, 4, 5, 6, 7, 8]
    steps:
      - uses: actions/checkout@v4
      - uses: ./.github/actions/setup-cad
      # cli-bundle and eval/* integration tests require the bundled CLI at
      # dist/cli/index.js; we rebuild it in each shard's runner because jobs
      # run on separate runners with isolated FS. The shared build cache
      # keeps this fast (~10-15s on hit).
      - name: Build CLI bundle (required by integration tests)
        run: npm run build:cli
      - name: QC — vitest (shard ${{ matrix.shard }}/8)
        run: npm test -- --shard=${{ matrix.shard }}/8

  # Gate job: carries the required-check name `test` so branch protection is
  # unchanged. if: always() ensures it reports failure (rather than being
  # skipped) when a shard fails or is cancelled.
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 2
    needs: test-shard
    if: always()
    steps:
      - name: All test shards green
        run: |
          [ "${{ needs.test-shard.result }}" = "success" ] || { echo "shard result: ${{ needs.test-shard.result }}"; exit 1; }

  # Exercises the FEA solve and USD-Isaac export against the REAL external
  # toolchain (CalculiX, gmsh, usd-core) instead of letting the integration
  # tests skip when the tools are absent. Deliberately NOT part of the
  # required `test` gate and NOT added to branch protection: apt/pip installs
  # here are slower and less reliable than the sandboxed unit suite, and a
  # flaky external-tool fetch must never block a merge. KERNELCAD_REQUIRE_
  # FEA_TOOLCHAIN=1 turns every "toolchain absent, skip" path in these tests
  # into a hard failure, so a broken install shows up as a failing job rather
  # than a quietly-green skip.
  external-tools:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v4
      - uses: ./.github/actions/setup-cad

      - name: Install CalculiX (ccx) and gmsh wheel runtime libs
        run: |
          sudo apt-get update
          sudo apt-get install -y calculix-ccx libglu1-mesa libgl1 libxcursor1 \
            libxinerama1 libxft2 libxrender1 libgomp1

      - name: Cache pip
        uses: actions/cache@v4
        with:
          path: ~/.cache/pip
          key: ${{ runner.os }}-pip-gmsh4.15.2-usdcore

      - name: Install gmsh + usd-core into .tools-venv
        run: |
          python3 -m venv .tools-venv
          .tools-venv/bin/pip install --disable-pip-version-check gmsh==4.15.2 usd-core
          .tools-venv/bin/python -c "import gmsh, pxr; print('gmsh', gmsh.GMSH_API_VERSION); print('pxr ok')"

      - name: FEA integration tests (real toolchain, skip-is-failure)
        env:
          KERNELCAD_FEA_PYTHON: ${{ github.workspace }}/.tools-venv/bin/python
          KERNELCAD_REQUIRE_FEA_TOOLCHAIN: '1'
        run: |
          NODE_OPTIONS=--max-old-space-size=3072 npx vitest run \
            tests/unit/fea/feaGate.integration.test.ts \
            tests/unit/fea/cantilever.integration.test.ts

      - name: USD-Isaac export validation (real pxr schemas, skip-is-failure)
        env:
          KERNELCAD_FEA_PYTHON: ${{ github.workspace }}/.tools-venv/bin/python
          KERNELCAD_REQUIRE_FEA_TOOLCHAIN: '1'
        run: |
          NODE_OPTIONS=--max-old-space-size=3072 npx vitest run \
            tests/integration/export/usdIsaacPxr.test.ts

  e2e:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    needs: [lint, build-and-checks, test]
    if: >
      (github.event_name == 'push' && github.ref == 'refs/heads/master') ||
      (github.event_name == 'pull_request' && github.base_ref == 'master') ||
      (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/master')
    steps:
      - uses: actions/checkout@v4
      - uses: ./.github/actions/setup-cad
      - name: Install Playwright Chromium
        run: npx playwright install --with-deps chromium
      - name: E2E tests (Playwright)
        run: npm run test:e2e
      - name: Upload Playwright report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: playwright-report
          path: playwright-report
          retention-days: 7
      - name: Upload Playwright traces (on failure)
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: playwright-test-results
          path: test-results
          retention-days: 7