Address carbolymer review on PR #1180

- Add changelog fragment with single-line description (no hard wraps in
  the YAML block scalar).
- derive_name_candidates: cap at two-token names. The previous loop
  emitted a single-token URL like cardano.cardano.intersectmbo.org as
  its last candidate. If that subdomain ever resolves (wildcard DNS,
  future deploy, catch-all), probe_site would silently accept it and
  rewrite every cardano-* link to the wrong site. An early break after
  the suffix strip prevents the heuristic from ever emitting a URL
  whose subdomain is a single bare token.
- Add --retry 3 --retry-delay 2 --retry-all-errors to all five curl
  sites. Every probe was previously a single-shot attempt (5s connect,
  10s max). Worst case: Phase 3 validation downgrades a perfectly
  valid rewritten URL into an unclickable <span>, silently shipping a
  regression. Other failure modes: probe_site falling through to a
  wrong candidate, or the CHaP index fetch killing the whole build on
  a CDN hiccup.

Author: Jimbo4350

.changes/20260428_cardano_api_fix_haddock_links.yml

@@ -0,0 +1,7 @@
+project: cardano-api
+pr: 1180
+kind:
+  - bugfix
+  - documentation
+description: |
+  Fix broken cross-package Haddock links on the hosted documentation site. Links to dependency packages (cardano-ledger-*, plutus-*, cardano-base, etc.) were relative paths pointing to directories that don't exist on the site, resulting in 404s. A post-processing script now resolves each cross-package href via a name-suffix heuristic under *.cardano.intersectmbo.org plus a small fallback list of known IOG doc-site roots, and rewrites them to absolute URLs. Hrefs that don't resolve become annotated unclickable spans with tooltips. A follow-up GitHub Actions step opens or comments on a rolling tracking issue when the script reports actionable dead links on master, tagging the PR opener so the breakage lands on someone's board instead of going unnoticed.

scripts/fix-haddock-links.sh

@@ -89,12 +89,15 @@ derive_name_candidates() {
     printf '%s\n' "https://${name}.cardano.intersectmbo.org"
     [[ "$name" == *-* ]] || break
     name="${name%-*}"
+    [[ "$name" == *-* ]] || break
   done
 }
 
 probe_site() {
   local code
-  code=$(curl -sI -o /dev/null -w "%{http_code}" --connect-timeout 5 --max-time 10 \
+  code=$(curl -sI -o /dev/null -w "%{http_code}" \
+    --connect-timeout 5 --max-time 10 \
+    --retry 3 --retry-delay 2 --retry-all-errors \
     "${1}/${2}/doc-index.html" 2>/dev/null || echo "000")
   [[ "$code" == "200" || "$code" == "301" || "$code" == "302" ]]
 }
@@ -157,7 +160,8 @@ done
 
 # Fetch CHaP index
 CHAP_PKGS_FILE=$(mktemp_tracked)
-curl -sL https://chap.intersectmbo.org/01-index.tar.gz \
+curl -sL --retry 3 --retry-delay 2 --retry-all-errors \
+  https://chap.intersectmbo.org/01-index.tar.gz \
   | tar -tz | grep -oP '^[^/]+' | sort -u > "$CHAP_PKGS_FILE"
 declare -A CHAP_SET
 while IFS= read -r pkg; do CHAP_SET["$pkg"]=1; done < "$CHAP_PKGS_FILE"
@@ -345,7 +349,7 @@ if [[ $reexport_total -gt 0 ]]; then
     # shellcheck disable=SC2016
     awk -F'\t' '{print $4}' "$REEXPORT_CANDIDATES" | sort -u | \
       xargs -P 16 -I{} sh -c \
-        'code=$(curl -sI -o /dev/null -w "%{http_code}" --connect-timeout 5 --max-time 10 "{}"); if [ "$code" = "200" ] || [ "$code" = "301" ] || [ "$code" = "302" ]; then echo "{}"; fi' \
+        'code=$(curl -sI -o /dev/null -w "%{http_code}" --connect-timeout 5 --max-time 10 --retry 3 --retry-delay 2 --retry-all-errors "{}"); if [ "$code" = "200" ] || [ "$code" = "301" ] || [ "$code" = "302" ]; then echo "{}"; fi' \
         > "$REEXPORT_VALID_FILE" 2>/dev/null
   fi
 
@@ -408,7 +412,7 @@ url_count=$(wc -l < "$URLS_FILE")
 if [[ $url_count -gt 0 ]]; then
   # shellcheck disable=SC2016 # single quotes intentional: expansions evaluated by inner sh -c
   xargs -P 16 -I{} sh -c \
-    'code=$(curl -sI -o /dev/null -w "%{http_code}" --connect-timeout 5 --max-time 10 "{}"); if [ "$code" != "200" ] && [ "$code" != "301" ] && [ "$code" != "302" ]; then echo "{}"; fi' \
+    'code=$(curl -sI -o /dev/null -w "%{http_code}" --connect-timeout 5 --max-time 10 --retry 3 --retry-delay 2 --retry-all-errors "{}"); if [ "$code" != "200" ] && [ "$code" != "301" ] && [ "$code" != "302" ]; then echo "{}"; fi' \
     < "$URLS_FILE" > "$DEAD_URLS_FILE" 2>/dev/null
 fi
 dead_count=$(wc -l < "$DEAD_URLS_FILE" | tr -d ' ')
@@ -456,7 +460,7 @@ if [[ $dead_count -gt 0 ]]; then
     # shellcheck disable=SC2016
     awk -F'\t' '{print $2}' "$RESCUE_CANDIDATES" | sort -u | \
       xargs -P 16 -I{} sh -c \
-        'code=$(curl -sI -o /dev/null -w "%{http_code}" --connect-timeout 5 --max-time 10 "{}"); if [ "$code" = "200" ] || [ "$code" = "301" ] || [ "$code" = "302" ]; then echo "{}"; fi' \
+        'code=$(curl -sI -o /dev/null -w "%{http_code}" --connect-timeout 5 --max-time 10 --retry 3 --retry-delay 2 --retry-all-errors "{}"); if [ "$code" = "200" ] || [ "$code" = "301" ] || [ "$code" = "302" ]; then echo "{}"; fi' \
         > "$RESCUE_VALID_FILE" 2>/dev/null
   fi