Address carbolymer review on PR #1180

- Changelog (.changes/.../fix_haddock_links.yml): collapse the
  description block scalar to a single line, removing the hard wraps
  Herald renders verbatim (r3159565460).

- derive_name_candidates (scripts/fix-haddock-links.sh): 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 silently accepts it and rewrites every cardano-* link to
  the wrong site. Add an early break after the suffix strip so the
  heuristic never emits a URL whose subdomain is a single bare token
  (r3159784338).

- curl retries (scripts/fix-haddock-links.sh): every probe was a
  single-shot attempt (5s connect, 10s max) with no retry. 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. Add
  --retry 3 --retry-delay 2 --retry-all-errors to all five curl sites
  (r3159784102).

- Workflow assignee 422 (.github/workflows/github-page.yml): the
  GitHub API rejects assignees that aren't repo collaborators with a
  422. If an external contributor merges a PR that breaks the haddock-
  links check on master, the rolling-issue workflow step would crash
  there, leaving the issue or comment half-created. Wrap both
  addAssignees calls in try/catch and remove assignees from the
  issues.create payload, doing assignment as a separate best-effort
  call so the issue always lands (r3159784547).

Author: Jimbo4350

.changes/20260428_cardano_api_fix_haddock_links.yml

@@ -4,14 +4,4 @@ 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.
+  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.

.github/workflows/github-page.yml

@@ -188,12 +188,19 @@ jobs:
                 issue_number: existing.number,
                 body: commentBody,
               });
-              await github.rest.issues.addAssignees({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                issue_number: existing.number,
-                assignees: [author],
-              });
+              try {
+                await github.rest.issues.addAssignees({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: existing.number,
+                  assignees: [author],
+                });
+              } catch (e) {
+                // External contributors aren't repo collaborators, so the API
+                // returns 422 here. Log and continue rather than crashing the
+                // step — the comment was posted, which is the important part.
+                console.log(`Could not assign @${author} to #${existing.number} (likely not a repo collaborator): ${e.message}`);
+              }
               console.log(`Appended to existing issue #${existing.number}: ${existing.html_url}`);
             } else {
               // No open issue → create one. The body documents the fix
@@ -215,13 +222,25 @@ jobs:
                 ``,
                 commentBody,
               ].join('\n');
+              // Create the issue without assignees first — passing assignees
+              // to issues.create makes the whole call 422 for non-collaborator
+              // authors. We assign separately so the issue always lands.
               const created = await github.rest.issues.create({
                 owner: context.repo.owner,
                 repo: context.repo.repo,
                 title: titleText,
                 body: issueBody,
                 labels: [labelName],
-                assignees: [author],
               });
+              try {
+                await github.rest.issues.addAssignees({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: created.data.number,
+                  assignees: [author],
+                });
+              } catch (e) {
+                console.log(`Could not assign @${author} to #${created.data.number} (likely not a repo collaborator): ${e.message}`);
+              }
               console.log(`Opened tracking issue #${created.data.number}: ${created.data.html_url}`);
             }

scripts/fix-haddock-links.sh

@@ -165,12 +165,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" || "$code" == "307" || "$code" == "308" ]]
 }
@@ -238,7 +241,8 @@ done
 # outage doesn't silently produce an empty index that masquerades as
 # "everything is non-CHaP".
 CHAP_PKGS_FILE=$(mktemp_tracked)
-if ! curl -sL --fail https://chap.intersectmbo.org/01-index.tar.gz \
+if ! curl -sL --fail --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"; then
   echo "Error: failed to fetch CHaP package index from https://chap.intersectmbo.org/01-index.tar.gz" >&2
   exit 1
@@ -433,7 +437,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" ] || [ "$code" = "307" ] || [ "$code" = "308" ]; 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" ] || [ "$code" = "307" ] || [ "$code" = "308" ]; then echo "{}"; fi' \
         > "$REEXPORT_VALID_FILE" 2>/dev/null
   fi
 
@@ -502,7 +506,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" ] && [ "$code" != "307" ] && [ "$code" != "308" ]; 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" ] && [ "$code" != "307" ] && [ "$code" != "308" ]; then echo "{}"; fi' \
     < "$URLS_FILE" > "$DEAD_URLS_FILE" 2>/dev/null
 fi
 dead_count=$(wc -l < "$DEAD_URLS_FILE" | tr -d ' ')
@@ -550,7 +554,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" ] || [ "$code" = "307" ] || [ "$code" = "308" ]; 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" ] || [ "$code" = "307" ] || [ "$code" = "308" ]; then echo "{}"; fi' \
         > "$RESCUE_VALID_FILE" 2>/dev/null
   fi