chore: Fix the html checker (#488)

<!-- markdownlint-disable MD041 -->
#### What this PR does / why we need it
The current htmlcheck is not able to successfully scan links on the real
website, so it produces quite a bunch of false positives. This PR adds
the link check using
[`linkinator`](https://github.com/JustinBeckwith/linkinator). Both
together should now really guarantee that there are no broken links as
we always scan the real website generated as deploy preview by Netlify.

---------

Signed-off-by: Gerald Morrison (SAP) <[email protected]>
Co-authored-by: Gerald Morrison (SAP) <[email protected]>

Author: morri-son

.github/config/htmltest.yml

@@ -4,6 +4,7 @@
 DirectoryPath: ./public
 
 # Checks to ignore
+CheckExternal: false
 CheckInternalHash: false
 CheckDoctype: false
 IgnoreInternalEmptyHash: true
@@ -21,11 +22,6 @@ ExternalTimeout: 10
 
 # URLs to ignore
 IgnoreURLs:
-  # Skip all SAP legal pages (appears in footer, so on every page)
-  - "^https://www\\.sap\\.com/.*/legal/.*"
   - "^mailto:"
-  # Skip local pages from secure delivery demo
-  - "^https?://(www\\.)?gitea\\.ocm\\.dev(/|$)"
-  - "^https://.*\\.ocm\\.dev(/|$)"
-  # Skip Google calendar entries
-  - "^https://calendar\\.google\\.com(/|$)"
+  # Skip OCM software pages because they are not yet live in a PR
+  - "^https://ocm\\.software(/|$)"

.github/config/linkinator.json

@@ -0,0 +1,8 @@
+{
+  "concurrency": 20,
+  "recurse": true,
+  "verbosity": "warning",
+  "timeout": 20000,
+  "retry": true,
+  "skip": ["https://www\\.sap\\.com/.*/legal/.*","^https?://(www\\.)?gitea\\.ocm\\.dev(/|$)","^https://.*\\.ocm\\.dev(/|$)","^https://calendar\\.google\\.com(/|$)","^https://github\\.com/open-component-model(/|$)"]
+}

.github/workflows/verify-html.yml

@@ -1,6 +1,3 @@
-# This workflow verifies that all links in the HTML files are valid.
-# GitHub repo: https://github.com/wjdp/htmltest
-
 name: Verify HTML Links
 
 on:
@@ -10,14 +7,74 @@ on:
 
 permissions:
   contents: read
+  checks: read
 
 jobs:
   check-links:
-    name: Check external and internal links
+    name: Check external and internal links (Netlify Deploy Preview)
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
 
+      - name: Wait for Netlify Deploy Preview
+        id: wait_for_preview
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          echo "Waiting up to 10 minutes for Netlify deploy preview..."
+          export REPO="${{ github.repository }}"
+          export SHA="${{ github.event.pull_request.head.sha }}"
+
+          timeout 600 bash -c '
+            while true; do
+              # Get check suite for Netlify app
+              SUITE_JSON=$(
+                gh api repos/"$REPO"/commits/"$SHA"/check-suites \
+                  --jq "[ .check_suites[] | select(.app.slug == \"netlify\") ]" 2>/dev/null
+              )
+
+              # no suite available? sleep and retry
+              if [ "$(echo "$SUITE_JSON" | jq length)" -eq 0 ]; then
+                sleep 5
+                continue
+              fi
+
+              # Read suite ID, status and conclusion
+              SUITE_ID=$(echo "$SUITE_JSON" | jq -r ".[0].id")
+              STATUS=$(echo    "$SUITE_JSON" | jq -r ".[0].status")
+              CONCLUSION=$(echo "$SUITE_JSON" | jq -r ".[0].conclusion")
+
+              echo "Netlify suite status: $STATUS, conclusion: $CONCLUSION"
+
+              if [ "$STATUS" = "completed" ]; then
+                if [[ "$CONCLUSION" = "success" || "$CONCLUSION" = "neutral" ]]; then
+                  # Get deploy preview URL from status
+                  STATUS_JSON=$(gh api repos/"$REPO"/commits/"$SHA"/status \
+                    --jq ".statuses[] | select(.context==\"netlify/open-component-model/deploy-preview\")" 2>/dev/null
+                  )
+
+                  PREVIEW_URL=$(echo "$STATUS_JSON" | jq -r '.target_url')
+
+                  echo "✅ Deploy Preview ready: $PREVIEW_URL"
+                  echo "preview_url=$PREVIEW_URL" >> $GITHUB_OUTPUT
+                  exit 0
+                else
+                  echo "❌ Deploy failed: $CONCLUSION"
+                  exit 1
+                fi
+              fi
+
+              # still pending? 
+              sleep 15
+            done
+          '
+
+          #  timeout returns 124 if command times out
+          if [ $? -eq 124 ]; then
+            echo "❌ Timeout after 10 minutes"
+            exit 1
+          fi
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
@@ -26,12 +83,20 @@ jobs:
       - name: Install Dependencies
         run: npm install
 
-      - name: Build Site
-        run: npm run build
+      - name: Build Site using Netlify Preview URL
+        id: build_site
+        run: |
+          npm run build -- --baseURL="$PREVIEW_URL"
 
       - name: Verify HTML links
-        # Download binary to ./bin. Execute it with log level 1 (INFO) and config file
         run: |
           curl https://htmltest.wjdp.uk | bash
           chmod +x ./bin/htmltest
-          ./bin/htmltest -l 1 -c .github/config/htmltest.yml
+          ./bin/htmltest -l 1 -c .github/config/htmltest.yml
+
+      - name: Verify links with linkinator
+        run: |
+          npm install linkinator
+          echo "Verifying links at ${{ steps.wait_for_preview.outputs.preview_url }}"
+          npx linkinator "${{ steps.wait_for_preview.outputs.preview_url }}" --config .github/config/linkinator.json \
+            && echo "✅ Linkinator: No broken links found."