[#36] [#37] CI: check link anchors, head meta tags and the robots.txt Sitemap line

.github/build-baseline/antora-errors.txt

@@ -0,0 +1,4 @@
+# Known Antora errors of the site build, one per line: file <TAB> message.
+# Written by .github/build-baseline/check.sh --update; the build fails on any other.
+openidm/modules/integrators-guide/pages/appendix-scripting.adoc	dropping cells from incomplete row detected end of table
+openig/modules/ROOT/partials/sec-release-levels.adoc	level 0 sections can only be used when doctype is book

.github/build-baseline/broken-links.jq

@@ -0,0 +1,28 @@
+#
+# The contents of this file are subject to the terms of the Common Development and
+# Distribution License (the License). You may not use this file except in compliance with the
+# License.
+#
+# You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
+# specific language governing permission and limitations under the License.
+#
+# When distributing Covered Software, include this CDDL Header Notice in each file and include
+# the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
+# Header, with the fields enclosed by brackets [] replaced by your own identifying
+# information: "Portions copyright [year] [name of copyright owner]".
+#
+# Copyright 2026 3A Systems, LLC.
+
+# The broken links of a lychee JSON report, one per line: page <TAB> link, both relative to the
+# site root. Used by check.sh and by the job summary of build.yml.
+
+# A link to the id of its target page itself, e.g. chap-resource-conf#chap-resource-conf: Antora
+# renders the page title without an id, so the browser opens the top of the page, which is where
+# the link points anyway. lychee's --exclude takes no back references, so these are dropped here.
+def top_of_page:
+  .status.text == "Cannot find fragment"
+  and (.url | split("#") | (.[0] | split("/") | last | rtrimstr(".html")) == (.[1:] | join("#")));
+
+.error_map // {} | to_entries[] | .key as $page | .value[]
+| select(top_of_page | not)
+| "\($page | ltrimstr("/site/"))\t\(.url | ltrimstr("file:///site/"))"

.github/build-baseline/broken-links.txt

@@ -0,0 +1,47 @@
+# Known broken links of the site build, one per line: page <TAB> link.
+# Written by .github/build-baseline/check.sh --update; the build fails on any other.
+openam/admin-guide/chap-monitoring.html	openam/admin-guide/chap-monitoring.html#interface-stability
+openam/admin-guide/chap-session-state.html	openam/admin-guide/chap-session-state.html#chap-cdsso
+openam/admin-guide/chap-session-state.html	openam/admin-guide/chap-session-state.html#chap-saml-1
+openam/admin-guide/chap-session-state.html	openam/admin-guide/chap-session-state.html#configure-policies-with-console
+openam/admin-guide/chap-session-state.html	openam/admin-guide/chap-session-state.html#configure-session-quotas
+openam/admin-guide/chap-session-state.html	openam/admin-guide/chap-session-state.html#saml2-and-session-state
+openam/admin-guide/chap-session-state.html	openam/admin-guide/chap-session-state.html#session-mgmt
+openam/admin-guide/chap-session-state.html	openam/admin-guide/chap-session-state.html#session-upgrade
+openam/admin-guide/chap-session-state.html	openam/admin-guide/chap-session-state.html#snmp-sessions
+openam/dev-guide/chap-client-dev.html	openam/admin-guide/index.html#configure-openid-connect-discovery
+openam/dev-guide/chap-client-dev.html	openam/admin-guide/index.html#configure-uma-discovery
+openam/dev-guide/chap-client-dev.html	openam/dev-guide/chap-client-dev.html#chap-sts
+openam/dev-guide/chap-client-dev.html	openam/dev-guide/index.html#appendix-deprecated-apis
+openam/dev-guide/chap-client-dev.html	openam/dev-guide/index.html#rest-api-auth
+openam/install-guide/chap-prepare-install.html	openam/admin-guide/index.html#tuning-jvm-for-openam
+openam/jee-users-guide/chap-jee-agent-config.html	openam/jee-users-guide/chap-jee-agent-config.html#filter-modes
+openam/jee-users-guide/chap-jee-agents-features.html	openam/jee-users-guide/index.html#j2ee-agent-cookie-reset-properties
+openam/jee-users-guide/chap-jee-agents-features.html	openam/jee-users-guide/index.html#j2ee-agent-fqdn-properties
+openam/jee-users-guide/chap-jee-agents-features.html	openam/jee-users-guide/index.html#j2ee-agent-general-properties
+openam/jee-users-guide/chap-jee-agents-features.html	openam/jee-users-guide/index.html#j2ee-agent-not-enforced-uri-properties
+openam/jee-users-guide/chap-troubleshooting.html	openam/jee-users-guide/index.html#install-with-ibm-jvm
+openam/reference/chap-endpoints.html	openam/dev-guide/index.html#rest-api-uma-well-known
+openam/reference/chap-log-messages.html	openam/admin-guide/index.html#debug-logging
+openam/reference/openam-cli-tools.html	openam/install-guide/index.html#install-openam-admin-tools
+openam/reference/openam-cli-tools.html	openam/reference/openam-cli-tools.html#ssoadm-create-policies
+openam/reference/openam-cli-tools.html	openam/reference/openam-cli-tools.html#ssoadm-delete-policies
+openam/reference/openam-cli-tools.html	openam/reference/openam-cli-tools.html#ssoadm-list-policies
+openam/reference/openam-cli-tools.html	openam/reference/openam-cli-tools.html#ssoadm-update-policies
+openam/web-users-guide/chap-msiis-7.html	openam/web-users-guide/index.html#chap-web-agents
+opendj/admin-guide/chap-admin-tools.html	opendj/reference/admin-tools-ref#ldif-diff-1
+opendj/admin-guide/chap-import-export.html	opendj/reference/admin-tools-ref#ldif-diff-1
+opendj/admin-guide/chap-import-export.html	opendj/reference/admin-tools-ref#make-ldif-template-5
+opendj/server-dev-guide/chap-ldap-operations.html	opendj/reference/admin-tools-ref#ldif-diff-1
+openidm/connectors-guide/chap-ldap.html	file:///opendj/3.5/server-dev-guide#referential-integrity
+openidm/getting-started/chap-where-to-go.html	file:///opendj/install-guide
+openidm/integrators-guide/chap-auth.html	file:///openam/13.5/admin-guide#session-state-cookies
+openidm/integrators-guide/chap-auth.html	openidm/integrators-guide/index.html#openam-session-module
+openidm/integrators-guide/chap-auth.html	openidm/integrators-guide/index.html#supported-session-modules
+openidm/integrators-guide/chap-passwords.html	file:///opendj/3.5/admin-guide/configure-ssl
+openidm/integrators-guide/chap-synchronization.html	file:///opendj/3.5/admin-guide#read-ecl-as-regular-user
+openidm/samples-guide/chap-fullstack-sample.html	file:///openam/13/admin-guide#chap-realms
+openidm/samples-guide/chap-fullstack-sample.html	file:///openam/13/admin-guide#realm-data-store
+openidm/samples-guide/chap-fullstack-sample.html	file:///openam/install-guide#configure-openam-custom
+openidm/samples-guide/chap-ldap-samples.html	file:///opendj/install-guide
+openidm/samples-guide/chap-workflow-samples.html	file:///opendj/install-guide#gui-install

.github/build-baseline/check.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+#
+# The contents of this file are subject to the terms of the Common Development and
+# Distribution License (the License). You may not use this file except in compliance with the
+# License.
+#
+# You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
+# specific language governing permission and limitations under the License.
+#
+# When distributing Covered Software, include this CDDL Header Notice in each file and include
+# the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
+# Header, with the fields enclosed by brackets [] replaced by your own identifying
+# information: "Portions copyright [year] [name of copyright owner]".
+#
+# Copyright 2026 3A Systems, LLC.
+
+# Compares the Antora errors and the broken links of a site build with the known ones listed in
+# this directory, and fails on any new one. The known ones come from the product repositories and
+# are fixed there; a known one that is gone is reported so that it is removed from the list.
+#
+# Usage, from the repository root after a build that wrote build/antora.log (Antora JSON log) and
+# build/lychee.json (lychee JSON report):
+#   .github/build-baseline/check.sh            check against the known lists
+#   .github/build-baseline/check.sh --update   rewrite the known lists from this build
+
+set -euo pipefail
+
+dir=$(cd "$(dirname "$0")" && pwd)
+root=$(cd "$dir/../.." && pwd)
+update=false
+[ "${1:-}" = --update ] && update=true
+
+# file <TAB> message, the file relative to the repository root
+antora_errors() {
+  jq -r --arg root "$root/" 'select(.level == "error" or .level == "fatal")
+    | "\(.file.path // "" | ltrimstr($root))\t\(.msg)"' "$root/build/antora.log" | LC_ALL=C sort
+}
+
+# page <TAB> link, both relative to the site root
+broken_links() {
+  jq -r -f "$dir/broken-links.jq" "$root/build/lychee.json" | LC_ALL=C sort -u
+}
+
+failed=false
+
+compare() {
+  local title=$1 file=$dir/$2 current=$3 new fixed
+  if $update; then
+    {
+      echo "# Known $title of the site build, one per line: $4."
+      echo "# Written by .github/build-baseline/check.sh --update; the build fails on any other."
+      printf '%s\n' "$current" | sed '/^$/d'
+    } > "$file"
+    echo "$file: $(printf '%s\n' "$current" | sed '/^$/d' | wc -l | tr -d ' ') entries"
+    return
+  fi
+  local known
+  known=$({ grep -v '^#' "$file" || true; } | LC_ALL=C sort)
+  new=$(LC_ALL=C comm -23 <(printf '%s\n' "$current" | sed '/^$/d') <(printf '%s\n' "$known" | sed '/^$/d'))
+  fixed=$(LC_ALL=C comm -13 <(printf '%s\n' "$current" | sed '/^$/d') <(printf '%s\n' "$known" | sed '/^$/d'))
+  {
+    echo "### $title"
+    echo
+    echo "$(printf '%s' "$new" | grep -c . || true) new, $(printf '%s' "$fixed" | grep -c . || true) no longer found."
+    echo
+  } >> "${GITHUB_STEP_SUMMARY:-/dev/null}"
+  while IFS= read -r line; do
+    [ -n "$line" ] || continue
+    msg=${line//%/%25}
+    msg=${msg//$'\r'/%0D}
+    echo "::error title=New $title::${msg//$'\t'/ — }"
+    echo "- new: \`${line//$'\t'/\` — \`}\`" >> "${GITHUB_STEP_SUMMARY:-/dev/null}"
+    failed=true
+  done <<< "$new"
+  while IFS= read -r line; do
+    [ -n "$line" ] || continue
+    msg=${line//%/%25}
+    msg=${msg//$'\r'/%0D}
+    echo "::notice title=No longer found; remove from .github/build-baseline/$2::${msg//$'\t'/ — }"
+    echo "- no longer found (remove from \`$2\`): \`${line//$'\t'/\` — \`}\`" >> "${GITHUB_STEP_SUMMARY:-/dev/null}"
+  done <<< "$fixed"
+  echo >> "${GITHUB_STEP_SUMMARY:-/dev/null}"
+}
+
+# assigned first, so that a missing or malformed input stops the script (set -e) instead of
+# reading as an empty build
+errors=$(antora_errors)
+links=$(broken_links)
+$update || echo "## Compared with the known problems" >> "${GITHUB_STEP_SUMMARY:-/dev/null}"
+compare "Antora errors" antora-errors.txt "$errors" "file <TAB> message"
+compare "broken links" broken-links.txt "$links" "page <TAB> link"
+
+if $failed; then
+  echo "The build has new Antora errors or broken links, see above. Fix them; if they come from a" \
+    "product repository, report them there and add them to .github/build-baseline." >&2
+  exit 1
+fi

.github/build-baseline/head-meta.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+#
+# The contents of this file are subject to the terms of the Common Development and
+# Distribution License (the License). You may not use this file except in compliance with the
+# License.
+#
+# You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
+# specific language governing permission and limitations under the License.
+#
+# When distributing Covered Software, include this CDDL Header Notice in each file and include
+# the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
+# Header, with the fields enclosed by brackets [] replaced by your own identifying
+# information: "Portions copyright [year] [name of copyright owner]".
+#
+# Copyright 2026 3A Systems, LLC.
+
+# Checks the generated site for the robots.txt Sitemap line and the head meta tags of every
+# page, and fails on any problem.
+#
+# Usage, from the repository root after a site build:
+#   .github/build-baseline/head-meta.sh [site directory, build/site by default]
+
+set -euo pipefail
+
+dir=$(cd "$(dirname "$0")" && pwd)
+root=$(cd "$dir/../.." && pwd)
+site=${1:-build/site}
+problems=()
+
+# Antora writes site.robots verbatim, so nothing else ties the Sitemap host to site.url
+url=$(cd "$root" && node -p "require('js-yaml').load(require('fs').readFileSync('antora-playbook.yml', 'utf8')).site.url")
+if ! grep -qxF "Sitemap: $url/sitemap.xml" "$site/robots.txt"; then
+  problems+=("robots.txt: no line \`Sitemap: $url/sitemap.xml\`")
+fi
+[ -f "$site/sitemap.xml" ] || problems+=("sitemap.xml: missing")
+
+# every page, other than a redirect page, carries exactly one of each tag; the API docs are not ours
+tags=('<meta name="description"' '<meta property="og:title"' '<meta property="og:description"'
+  '<meta property="og:image"' '<meta name="twitter:card"' '<meta property="og:url"')
+pages=0
+while IFS= read -r f; do
+  # the redirect page of Antora; page text cannot carry this, Asciidoctor escapes the <
+  grep -qF '<meta http-equiv="refresh"' "$f" && continue
+  pages=$((pages + 1))
+  for tag in "${tags[@]}"; do
+    # 404.html has no canonical URL
+    [ "$f" = "$site/404.html" ] && [ "$tag" = '<meta property="og:url"' ] && continue
+    n=$({ grep -oF "$tag" "$f" || true; } | wc -l | tr -d ' ')
+    [ "$n" -eq 1 ] || problems+=("${f#"$site/"}: $n x \`$tag\`")
+  done
+done < <(find "$site" \( -path "$site/openam/apidocs" -o -path "$site/opendj/apidocs" \
+  -o -path "$site/openidm/apidocs" -o -path "$site/openig/apidocs" \
+  -o -path "$site/openicf" -o -path "$site/commons" \) -prune -o -name '*.html' -print | LC_ALL=C sort)
+[ "$pages" -gt 0 ] || problems+=("no pages found in $site")
+
+{
+  echo "## Head meta tags and robots.txt"
+  echo
+  echo "$pages pages checked, ${#problems[@]} problems."
+  echo
+} >> "${GITHUB_STEP_SUMMARY:-/dev/null}"
+# "${problems[@]}" of an empty array is unbound in bash 3.2 (macOS)
+[ "${#problems[@]}" -eq 0 ] && exit 0
+for p in "${problems[@]}"; do
+  echo "- $p" >> "${GITHUB_STEP_SUMMARY:-/dev/null}"
+  msg=${p//%/%25}
+  echo "::error title=Head meta tags and robots.txt::${msg//$'\r'/%0D}"
+done
+exit 1