ci: run Lychee through pre-commit in development and CI

.github/workflows/build-docs.yml

@@ -284,21 +284,47 @@ jobs:
           fi
           mv ${COMPONENT}/docs/build/html/* artifacts/docs/${TARGET}
 
-      # Keep link checks in the existing PR docs build, using the same revision
-      # as its wheels. Nightly supplies shared caches for both kinds of inputs.
-      - name: Check authored documentation links
+      # Authored sources are checked by the ordinary Linux/Windows pre-commit
+      # jobs. Generated HTML and anchors need this completed documentation build.
+      - name: Install pre-commit for rendered link checks
         if: ${{ !inputs.is-release && startsWith(github.ref_name, 'pull-request/') }}
-        timeout-minutes: 60
-        uses: ./.github/actions/check-doc-links
+        run: |
+          echo "PRE_COMMIT_HOME=${RUNNER_TEMP}/pre-commit" >> "${GITHUB_ENV}"
+          echo "LYCHEE_CACHE_DIR=${RUNNER_TEMP}/lychee-rendered" >> "${GITHUB_ENV}"
+          python -m pip install pre-commit
+
+      - name: Describe the rendered link cache
+        if: ${{ !inputs.is-release && startsWith(github.ref_name, 'pull-request/') }}
+        id: lychee-cache
+        run: python ci/tools/lychee_cache.py rendered --github-output "${GITHUB_OUTPUT}"
+
+      - name: Restore successful rendered link checks
+        if: ${{ !inputs.is-release && startsWith(github.ref_name, 'pull-request/') }}
+        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # v6.1.0
         with:
-          kind: authored
+          path: ${{ steps.lychee-cache.outputs.path }}
+          key: ${{ steps.lychee-cache.outputs.key }}
+          restore-keys: ${{ steps.lychee-cache.outputs.prefix }}
+          enableCrossOsArchive: true
 
-      - name: Check rendered documentation links
+      - name: Check rendered documentation links through pre-commit
         if: ${{ !inputs.is-release && startsWith(github.ref_name, 'pull-request/') }}
         timeout-minutes: 60
-        uses: ./.github/actions/check-doc-links
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: >-
+          python ci/tools/run_lychee_precommit.py rendered
+          --policy check --max-attempts 3
+          --report "${RUNNER_TEMP}/lychee-reports/lychee-rendered.json"
+
+      - name: Upload rendered link-check reports
+        if: ${{ always() && !inputs.is-release && startsWith(github.ref_name, 'pull-request/') }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
         with:
-          kind: rendered
+          name: lychee-rendered-${{ github.run_id }}-${{ github.run_attempt }}
+          path: ${{ runner.temp }}/lychee-reports/
+          if-no-files-found: ignore
+          retention-days: 7
 
       - name: Upload docs GitHub Pages artifact
         if: ${{ inputs.deploy-docs }}

.github/workflows/lychee.yml

@@ -2,9 +2,9 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-# Build documentation nightly and warm the link cache, reporting unresolved links
-# as warnings. Full PR CI reuses successful checks in build-docs.yml.
-# Ordinary PR updates run pre-commit without Lychee and do not build docs here.
+# Warm authored and rendered link caches through the configured pre-commit
+# hooks. Ordinary PRs reuse authored results; full docs CI reuses rendered
+# results. Nightly starts afresh and reports unresolved links as warnings.
 
 name: "CI: Documentation links"
 
@@ -50,6 +50,8 @@ jobs:
       fail-fast: false
       matrix:
         kind: [authored, rendered]
+    env:
+      PYTHONUTF8: "1"
     steps:
       - name: Checkout checked revision
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -62,10 +64,26 @@ jobs:
           submodules: ${{ matrix.kind == 'rendered' }}
 
       - name: Set up Python
+        id: python
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.14"
 
+      - name: Set link-check cache locations
+        run: |
+          echo "PRE_COMMIT_HOME=${RUNNER_TEMP}/pre-commit" >> "${GITHUB_ENV}"
+          echo "LYCHEE_CACHE_DIR=${RUNNER_TEMP}/lychee-rendered" >> "${GITHUB_ENV}"
+
+      - name: Restore pre-commit environments
+        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # v6.1.0
+        with:
+          path: ${{ env.PRE_COMMIT_HOME }}
+          key: pre-commit-${{ runner.os }}-py${{ steps.python.outputs.python-version }}-${{ hashFiles('.pre-commit-config.yaml') }}
+          restore-keys: pre-commit-${{ runner.os }}-py3.14
+
+      - name: Install pre-commit
+        run: python -m pip install pre-commit
+
       - name: Setup pixi
         if: ${{ matrix.kind == 'rendered' }}
         uses: ./.github/actions/setup-pixi
@@ -74,9 +92,42 @@ jobs:
         if: ${{ matrix.kind == 'rendered' }}
         run: pixi run --manifest-path cuda_core/pixi.toml -e docs docs-build-all-latest
 
-      - name: Check documentation links
-        uses: ./.github/actions/check-doc-links
+      - name: Describe the link cache
+        id: lychee-cache
+        run: python ci/tools/lychee_cache.py "${{ matrix.kind }}" --github-output "${GITHUB_OUTPUT}"
+
+      - name: Restore successful link checks
+        # Refresh mode deliberately skips yesterday's URL results.
+        if: ${{ !inputs.refresh-cache }}
+        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # v6.1.0
+        with:
+          path: ${{ steps.lychee-cache.outputs.path }}
+          key: ${{ steps.lychee-cache.outputs.key }}
+          restore-keys: ${{ steps.lychee-cache.outputs.prefix }}
+          enableCrossOsArchive: true
+
+      - name: Check documentation links through pre-commit
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: >-
+          python ci/tools/run_lychee_precommit.py "${{ matrix.kind }}"
+          --policy "${{ inputs.refresh-cache && 'cache-warm' || 'check' }}"
+          --max-attempts 3
+          --report "${RUNNER_TEMP}/lychee-reports/lychee-${{ matrix.kind }}.json"
+
+      - name: Publish fresh successful link checks
+        if: ${{ !cancelled() && inputs.refresh-cache && steps.lychee-cache.outputs.key != '' }}
+        uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # v6.1.0
+        with:
+          path: ${{ steps.lychee-cache.outputs.path }}
+          key: ${{ steps.lychee-cache.outputs.key }}
+          enableCrossOsArchive: true
+
+      - name: Upload link-check reports
+        if: ${{ always() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
         with:
-          kind: ${{ matrix.kind }}
-          refresh-cache: ${{ inputs.refresh-cache || false }}
-          failure-policy: ${{ inputs.refresh-cache && 'cache-warm' || 'check' }}
+          name: lychee-${{ matrix.kind }}-${{ github.run_id }}-${{ github.run_attempt }}
+          path: ${{ runner.temp }}/lychee-reports/
+          if-no-files-found: ignore
+          retention-days: 7

.github/workflows/pre-commit.yml

@@ -41,10 +41,10 @@ jobs:
           - name: Windows
             os: windows-latest
     env:
-      # Full-CI docs builds and nightly check links. The installation reminder
-      # is for developer machines; CI does not install a Git commit hook.
-      # A separate bounded check below exercises Lychee with local fixtures.
-      SKIP: lychee,check-precommit-installed
+      # The installation reminder is for developer machines; CI does not
+      # install a Git commit hook. All other hooks, including Lychee, run.
+      SKIP: check-precommit-installed
+      PYTHONUTF8: "1"
       # Minor version used by setup-python and as the cache restore-key prefix.
       PYTHON_VERSION: "3.14"
     steps:
@@ -138,17 +138,52 @@ jobs:
           LYCHEE_SMOKE_DIR: ${{ steps.lychee-smoke.outputs.directory }}
         run: python ci/tools/smoke_test_lychee_precommit.py --cleanup "$LYCHEE_SMOKE_DIR"
 
+      - name: Describe the authored link cache
+        id: lychee-cache
+        run: python ci/tools/lychee_cache.py authored --github-output "${GITHUB_OUTPUT}"
+
+      - name: Restore successful link checks from the shared baseline
+        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # v6.1.0
+        with:
+          path: ${{ steps.lychee-cache.outputs.path }}
+          key: ${{ steps.lychee-cache.outputs.key }}
+          restore-keys: ${{ steps.lychee-cache.outputs.prefix }}
+          enableCrossOsArchive: true
+
+      # Warm only Lychee, retaining successful checks between attempts. The
+      # full suite below runs once: formatter changes must remain failures.
+      # A missing baseline is supported; the first pass then checks afresh.
+      - name: Warm the Lychee cache with up to three hook attempts
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: >-
+          python ci/tools/run_lychee_precommit.py authored
+          --policy cache-warm --max-attempts 3
+          --report "${RUNNER_TEMP}/lychee-reports/lychee-authored.json"
+
       - name: Run pre-commit
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
         run: pre-commit run --all-files --show-diff-on-failure
 
-      # Full link scans generate external network traffic and need cache and
-      # retry handling; documentation CI provides that. These local fixtures
-      # keep per-PR coverage focused on the installed hook on each platform.
-      - name: Exercise the configured Lychee hook with local fixtures
-        env:
-          SKIP: check-precommit-installed
-          PYTHONUTF8: "1"
-        run: python ci/tools/test_lychee_precommit.py
+      - name: Save successful authored link checks from main
+        # Nightly and main pushes supply the shared baseline. PR runs only
+        # restore it; saving preserves timestamps and never caches failures.
+        if: ${{ !cancelled() && runner.os == 'Linux' && github.ref_name == github.event.repository.default_branch && steps.lychee-cache.outputs.key != '' }}
+        uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # v6.1.0
+        with:
+          path: ${{ steps.lychee-cache.outputs.path }}
+          key: ${{ steps.lychee-cache.outputs.key }}
+          enableCrossOsArchive: true
+
+      - name: Upload Lychee warm-up reports
+        if: ${{ always() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: lychee-precommit-${{ runner.os }}-${{ github.run_id }}-${{ github.run_attempt }}
+          path: ${{ runner.temp }}/lychee-reports/
+          if-no-files-found: ignore
+          retention-days: 7
 
       - name: Save pre-commit cache
         # Only the default branch saves, so per-PR merge refs don't store their

.gitignore

@@ -11,6 +11,7 @@ __pycache__/
 .cython-stdlib
 .cython-bindings
 .lycheecache
+.lychee-rendered/
 .pytest_cache/
 .benchmarks/
 *.cpp