From 9ddd48e336a92c28799c4b38d868722d8d10936e Mon Sep 17 00:00:00 2001
From: Speculator55005 <50082482+fas89@users.noreply.github.com>
Date: Tue, 15 Sep 2026 20:27:51 +0200
Subject: [PATCH] ci: gate the artifact that actually ships, not only the ones
 in pull requests

`scripts/check-dist-links.mjs` was wired into docs-pr-check.yml alone, and that
workflow is `pull_request`-only. So the job that uploads to GitHub Pages ran
`npm ci`, `npm run docs:build`, `touch .nojekyll`, `upload-pages-artifact`, with
nothing between the build and the upload.

Two ways a broken site shipped past a green history:

- a direct push to main was ungated entirely;
- two pull requests, each green against its own base, can combine into a broken
  artifact that neither run examined.

The step goes BEFORE `.nojekyll` and the upload, so a bad artifact is never
published rather than published and then reported.

No `continue-on-error`, no `|| true`, and deliberately not `if: always()`. A
failed build leaves no artifact, and measuring an absent or stale dist is the
exact failure this exists to prevent; the script refuses to run when dist is
missing, so a green result here always means it read the bytes this job is about
to upload.

Verified on this branch, not assumed:

  npm run docs:build                exit 0
  node scripts/check-dist-links.mjs exit 0 - 219 pages, 107,738 absolute
                                    references, 474 distinct targets, canaries
                                    passing

...and the gate proved load-bearing here the same way it was in the pull-request
workflow. With `link: '/why'` changed to `'/whyy'` in the config.ts navbar:

  npm run docs:build                exit 0    <- the hole
  node scripts/check-dist-links.mjs exit 1    <- 424 dead references, 212 pages

Restored, rebuilt, both green again.

This does not make docs-pr-check.yml redundant; the coverage map in that file says
why. It reports a REPOSITORY path a contributor can act on, and it runs on a
source-only change. This one is the last thing between a build and the live site.
---
 .github/workflows/deploy-docs.yml | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
index 47b7baf..8fd3dde 100644
--- a/.github/workflows/deploy-docs.yml
+++ b/.github/workflows/deploy-docs.yml
@@ -40,6 +40,24 @@ jobs:
       - name: Build docs
         run: npm run docs:build
 
+      # The same artifact gate docs-pr-check.yml runs, here as well, because that
+      # workflow is `pull_request`-only and this one is what actually ships.
+      # Without this step a direct push to main uploads to Pages with nothing
+      # checking it, and two individually-green pull requests can combine into a
+      # broken artifact: each was checked against its own base, neither against
+      # the merge result. Measured on 92925e5: a one-character typo in the
+      # config.ts navbar leaves `npm run docs:build` exiting 0 while shipping 424
+      # dead references across 212 of 213 rendered pages.
+      #
+      # No `continue-on-error`, no `|| true`, and deliberately NOT `if: always()`.
+      # A failed build leaves no artifact, and measuring an absent or stale dist
+      # is the exact failure this exists to prevent - the script refuses to run
+      # when dist is missing, so a green result here always means it read the
+      # bytes this job is about to upload. It runs BEFORE `.nojekyll` and
+      # `upload-pages-artifact` so a bad artifact is never published at all.
+      - name: Check the built artifact for dead internal links
+        run: node scripts/check-dist-links.mjs
+
       - name: Add .nojekyll
         run: touch docs/.vuepress/dist/.nojekyll