fix(ci): enforce v1.0.0 release gates

.github/CONTRIBUTING.md

@@ -52,17 +52,19 @@ scope can be agreed upon.
 
    `just check` is the fast, non-mutating source and tooling gate, including the
    repository-owned Semgrep policy and its fixtures. `just ci` adds the
-   supported build and complete 128-entry CTest suite: 104 doctest unit
-   scenarios, 23 CLI integration tests, and one arithmetic-backend correctness
-   test. `just build-parallel` builds the distinct CGAL/oneTBB configuration and
-   runs its 128-entry suite: 103 ordinary doctest scenarios, one replayable
-   parallel stress launcher containing five scenarios, the same 23 CLI
-   integration tests, and the arithmetic correctness test. When changing C++
+   supported build and complete 131-entry CTest suite: 106 doctest scenarios,
+   23 CLI integration tests, one compiled C++ API example, and one
+   arithmetic-backend correctness test. `just build-parallel` builds the
+   distinct CGAL/oneTBB configuration and runs its 132-entry suite: 106 ordinary
+   doctest scenarios, one replayable parallel stress launcher containing five
+   scenarios, the same 23 CLI integration tests, the C++ API example, and the
+   arithmetic correctness test. When changing C++
    behavior, also run `just clang-tidy` with the pinned LLVM 22 toolchain and
    review its advisory diagnostics.
    GitHub Actions runs `just ci` in its Ubuntu GCC, Ubuntu Clang, macOS AppleClang, and Windows MSVC jobs. The two
-   Ubuntu jobs also run `just build-parallel` to exercise the opt-in CGAL/oneTBB contract. Sanitizer and coverage
-   builds keep Release assertion semantics while adding their own debug information and optimization settings. A
+   Ubuntu jobs also run `just build-parallel` to exercise the opt-in CGAL/oneTBB contract, and the macOS job runs
+   `just viewer-build`. Pull requests run the separate coverage and generated-documentation gates. Sanitizer and
+   coverage builds keep Release assertion semantics while adding their own debug information and optimization settings. A
    separate full-suite Debug job is intentionally omitted because several fixtures traverse invalid intermediate
    triangulations and abort on CDT++ invariant assertions. Use `just build-debug` to compile production targets with
    CDT++ assertions enabled and run the 21 compatible CLI integration CTests. That preset defines `CGAL_NDEBUG` for

.github/actions/setup-just/action.yml

@@ -36,6 +36,6 @@ runs:
         echo "version=$version" >> "$GITHUB_OUTPUT"
 
     - name: Install Just
-      uses: taiki-e/install-action@6a1bd70eaac3c8bdf093356838d7ee09fda951cf  # v2.85.5
+      uses: taiki-e/install-action@1beb33eee6d086258184383af9a538940be190ed  # v2.85.6
       with:
         tool: just@${{ steps.resolve.outputs.version }}

.github/workflows/_sanitizer.yml

@@ -72,13 +72,19 @@ jobs:
       - name: Set up Just
         uses: ./.github/actions/setup-just
 
+      - name: Resolve sanitizer tool versions
+        id: tool-versions
+        run: |
+          llvm="$(just --evaluate llvm_version)"
+          printf 'llvm=%s\n' "$llvm" >> "$GITHUB_OUTPUT"
+
       - name: Set up pkgx
         uses: pkgxdev/setup@4d4ae97af87ccb39ab8be4e073dea697fef2c6f7  # v5.0.0
 
       - name: Set up cached vcpkg
         uses: ./.github/actions/setup-vcpkg
         with:
-          cache-key: clang-22
+          cache-key: clang-${{ steps.tool-versions.outputs.llvm }}
 
       - name: Build and exercise sanitizer configuration
         env:

.github/workflows/ci.yml

@@ -30,40 +30,36 @@ jobs:
         include:
           - name: Ubuntu GCC
             os: ubuntu-latest
-            compiler_package: gnu.org/gcc@16
+            compiler_family: gcc
             cc: gcc
             cxx: g++
             compiler_cache: ccache
-            compiler_cache_key: gcc-16
             run_parallel_contract: true
-            vcpkg_cache_key: gcc-16
+            run_viewer_contract: false
           - name: Ubuntu Clang
             os: ubuntu-latest
-            compiler_package: llvm.org@22
+            compiler_family: clang
             cc: clang
             cxx: clang++
             compiler_cache: ccache
-            compiler_cache_key: clang-22
             run_parallel_contract: true
-            vcpkg_cache_key: clang-22
+            run_viewer_contract: false
           - name: macOS AppleClang
             os: macos-latest
-            compiler_package: ""
+            compiler_family: appleclang
             cc: clang
             cxx: clang++
             compiler_cache: ""
-            compiler_cache_key: none
             run_parallel_contract: false
-            vcpkg_cache_key: appleclang
+            run_viewer_contract: true
           - name: Windows MSVC
             os: windows-latest
-            compiler_package: ""
+            compiler_family: msvc
             cc: cl
             cxx: cl
             compiler_cache: ""
-            compiler_cache_key: none
             run_parallel_contract: false
-            vcpkg_cache_key: msvc
+            run_viewer_contract: false
 
     steps:
       - name: Disable Git autocrlf on Windows
@@ -96,13 +92,52 @@ jobs:
           {
             echo "cmake=$(just --evaluate cmake_version)"
             echo "ccache=$(just --evaluate ccache_version)"
+            echo "gcc=$(just --evaluate gcc_version)"
             echo "llvm=$(just --evaluate llvm_version)"
             echo "ninja=$(just --evaluate ninja_version)"
             echo "ninja-windows-wheel=$(just --evaluate ninja_windows_wheel_version)"
+            echo "python=$(just --evaluate python_version)"
             echo "typos=$(just --evaluate typos_version)"
             echo "uv=$(just --evaluate uv_version)"
           } >> "$GITHUB_OUTPUT"
 
+      - name: Resolve matrix compiler pin
+        id: compiler
+        shell: bash
+        env:
+          COMPILER_FAMILY: ${{ matrix.compiler_family }}
+          GCC_VERSION: ${{ steps.tool-versions.outputs.gcc }}
+          LLVM_VERSION: ${{ steps.tool-versions.outputs.llvm }}
+        run: |
+          case "$COMPILER_FAMILY" in
+            gcc)
+              version="$GCC_VERSION"
+              package="gnu.org/gcc@${version}"
+              cache_key="gcc-${version}"
+              ;;
+            clang)
+              version="$LLVM_VERSION"
+              package="llvm.org@${version}"
+              cache_key="clang-${version}"
+              ;;
+            appleclang)
+              package=""
+              cache_key="appleclang"
+              ;;
+            msvc)
+              package=""
+              cache_key="msvc"
+              ;;
+            *)
+              echo "Unsupported compiler family: ${COMPILER_FAMILY}" >&2
+              exit 1
+              ;;
+          esac
+          {
+            echo "package=${package}"
+            echo "cache_key=${cache_key}"
+          } >> "$GITHUB_OUTPUT"
+
       - name: Set up typos
         uses: taiki-e/install-action@1beb33eee6d086258184383af9a538940be190ed  # v2.85.6
         with:
@@ -112,8 +147,9 @@ jobs:
         if: runner.os != 'Windows'
         uses: pkgxdev/setup@4d4ae97af87ccb39ab8be4e073dea697fef2c6f7  # v5.0.0
         with:
+          # Compiler packages are scoped to scripts/pkgx-build.sh so LLVM's
+          # ranlib does not shadow Apple's ranlib in the macOS viewer build.
           +: >-
-            llvm.org@${{ steps.tool-versions.outputs.llvm }}
             cmake.org@${{ steps.tool-versions.outputs.cmake }}
             ninja-build.org@${{ steps.tool-versions.outputs.ninja }}
 
@@ -134,7 +170,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
         with:
-          python-version-file: .python-version
+          python-version: ${{ steps.tool-versions.outputs.python }}
 
       - name: Set up uv
         uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9  # v9.0.0
@@ -172,16 +208,16 @@ jobs:
       - name: Set up cached vcpkg
         uses: ./.github/actions/setup-vcpkg
         with:
-          cache-key: ${{ matrix.vcpkg_cache_key }}
+          cache-key: ${{ steps.compiler.outputs.cache_key }}
 
       - name: Restore compiler cache
         if: matrix.compiler_cache != ''
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # v6.1.0
         with:
           path: .cache/ccache
-          key: ccache-v1-${{ runner.os }}-${{ matrix.compiler_cache_key }}-${{ github.sha }}
+          key: ccache-v1-${{ runner.os }}-${{ steps.compiler.outputs.cache_key }}-${{ github.sha }}
           restore-keys: |
-            ccache-v1-${{ runner.os }}-${{ matrix.compiler_cache_key }}-
+            ccache-v1-${{ runner.os }}-${{ steps.compiler.outputs.cache_key }}-
 
       - name: Run the canonical local CI contract
         env:
@@ -191,7 +227,7 @@ jobs:
           CCACHE_MAXSIZE: 1G
           CC: ${{ matrix.cc }}
           CDT_COMPILER_CACHE: ${{ matrix.compiler_cache }}
-          CDT_PKGX_COMPILER_PACKAGE: ${{ matrix.compiler_package }}
+          CDT_PKGX_COMPILER_PACKAGE: ${{ steps.compiler.outputs.package }}
           CXX: ${{ matrix.cxx }}
         run: just ci
 
@@ -204,10 +240,14 @@ jobs:
           CCACHE_MAXSIZE: 1G
           CC: ${{ matrix.cc }}
           CDT_COMPILER_CACHE: ${{ matrix.compiler_cache }}
-          CDT_PKGX_COMPILER_PACKAGE: ${{ matrix.compiler_package }}
+          CDT_PKGX_COMPILER_PACKAGE: ${{ steps.compiler.outputs.package }}
           CXX: ${{ matrix.cxx }}
         run: just build-parallel
 
+      - name: Run the opt-in macOS viewer contract
+        if: matrix.run_viewer_contract
+        run: just viewer-build
+
       - name: Report compiler cache statistics
         if: ${{ always() && matrix.compiler_cache != '' }}
         env:

.github/workflows/codecov-upload.yml

@@ -5,6 +5,9 @@ name: CodeCov
   push:
     branches:
       - main
+  pull_request:
+    branches:
+      - main
   workflow_dispatch:
 
 permissions:
@@ -30,6 +33,24 @@ jobs:
           fetch-depth: 0
           persist-credentials: false
 
+      - name: Set up Just
+        uses: ./.github/actions/setup-just
+
+      - name: Resolve coverage tool versions
+        id: tool-versions
+        run: |
+          cmake="$(just --evaluate cmake_version)"
+          gcc="$(just --evaluate gcc_version)"
+          lcov="$(just --evaluate lcov_version)"
+          lcov_sha256="$(just --evaluate lcov_sha256)"
+          ninja="$(just --evaluate ninja_version)"
+          printf '%s\n' \
+            "cmake=${cmake}" \
+            "gcc=${gcc}" \
+            "lcov=${lcov}" \
+            "lcov_sha256=${lcov_sha256}" \
+            "ninja=${ninja}" >> "$GITHUB_OUTPUT"
+
       - name: Setup
         run: |
           sudo apt update
@@ -38,10 +59,10 @@ jobs:
             curl lcov libtool-bin ninja-build python3-sphinx \
             python3-sphinx-rtd-theme texinfo yasm
 
-      - name: Install LCOV 2.5
+      - name: Install pinned LCOV
         env:
-          LCOV_SHA256: 7e5e5a154bd5f3557659c328cab376764e7abd238bb403c424472c296b175126
-          LCOV_VERSION: "2.5"
+          LCOV_SHA256: ${{ steps.tool-versions.outputs.lcov_sha256 }}
+          LCOV_VERSION: ${{ steps.tool-versions.outputs.lcov }}
         run: |
           archive="${RUNNER_TEMP}/lcov-${LCOV_VERSION}.tar.gz"
           source_dir="${RUNNER_TEMP}/lcov-${LCOV_VERSION}"
@@ -53,22 +74,11 @@ jobs:
           sudo make --directory "${source_dir}" install
           lcov --version
 
-      - name: Set up Just
-        uses: ./.github/actions/setup-just
-
-      - name: Resolve coverage tool versions
-        id: tool-versions
-        run: |
-          {
-            echo "cmake=$(just --evaluate cmake_version)"
-            echo "ninja=$(just --evaluate ninja_version)"
-          } >> "$GITHUB_OUTPUT"
-
       - name: Set up coverage toolchain
         uses: pkgxdev/setup@4d4ae97af87ccb39ab8be4e073dea697fef2c6f7  # v5.0.0
         with:
           +: >-
-            gnu.org/gcc@16
+            gnu.org/gcc@${{ steps.tool-versions.outputs.gcc }}
             cmake.org@${{ steps.tool-versions.outputs.cmake }}
             ninja-build.org@${{ steps.tool-versions.outputs.ninja }}
 
@@ -94,7 +104,7 @@ jobs:
       - name: Set up cached vcpkg
         uses: ./.github/actions/setup-vcpkg
         with:
-          cache-key: gcc-16
+          cache-key: gcc-${{ steps.tool-versions.outputs.gcc }}
 
       - name: Generate coverage reports
         env:
@@ -103,11 +113,23 @@ jobs:
           GCOV: gcov
         run: just coverage
 
+      - name: Validate coverage reports
+        run: |
+          if [[ ! -s build/coverage.info ]]; then
+            echo "build/coverage.info is missing or empty." >&2
+            exit 1
+          fi
+          if [[ ! -d build/coverage-html ]] ||
+             [[ -z "$(find build/coverage-html -type f -size +0c -print -quit)" ]]; then
+            echo "build/coverage-html is missing or empty." >&2
+            exit 1
+          fi
+
       - name: Preserve coverage reports
         if: ${{ always() }}
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
         with:
-          if-no-files-found: warn
+          if-no-files-found: error
           name: coverage-report-${{ github.sha }}
           path: |
             build/coverage.info
@@ -134,5 +156,6 @@ jobs:
           fail_ci_if_error: true
           files: build/coverage.info
           plugins: noop
-          use_oidc: true
+          token: ${{ secrets.CODECOV_TOKEN }}
+          use_oidc: ${{ github.actor != 'dependabot[bot]' }}
           verbose: true

.github/workflows/codeql.yml

@@ -70,6 +70,13 @@ jobs:
         if: matrix.language == 'c-cpp'
         uses: ./.github/actions/setup-just
 
+      - name: Resolve C++ tool versions
+        if: matrix.language == 'c-cpp'
+        id: tool-versions
+        run: |
+          gcc="$(just --evaluate gcc_version)"
+          printf 'gcc=%s\n' "$gcc" >> "$GITHUB_OUTPUT"
+
       - name: Set up C++ environment with pkgx
         if: matrix.language == 'c-cpp'
         uses: pkgxdev/setup@4d4ae97af87ccb39ab8be4e073dea697fef2c6f7  # v5.0.0
@@ -78,13 +85,13 @@ jobs:
         if: matrix.language == 'c-cpp'
         uses: ./.github/actions/setup-vcpkg
         with:
-          cache-key: gcc-16
+          cache-key: gcc-${{ steps.tool-versions.outputs.gcc }}
 
       - name: Prepare C++ dependencies outside CodeQL tracing
         if: matrix.language == 'c-cpp'
         env:
           CC: gcc
-          CDT_PKGX_COMPILER_PACKAGE: gnu.org/gcc@16
+          CDT_PKGX_COMPILER_PACKAGE: gnu.org/gcc@${{ steps.tool-versions.outputs.gcc }}
           CXX: g++
         run: just codeql-prepare
 
@@ -98,7 +105,7 @@ jobs:
         if: matrix.language == 'c-cpp'
         env:
           CC: gcc
-          CDT_PKGX_COMPILER_PACKAGE: gnu.org/gcc@16
+          CDT_PKGX_COMPILER_PACKAGE: gnu.org/gcc@${{ steps.tool-versions.outputs.gcc }}
           CXX: g++
         run: just codeql-build