Sitemap script + alert

.github/workflows/publish.yml

@@ -106,6 +106,65 @@ jobs:
           path: unified-doc/build-site/
           retention-days: 7
 
+  notify-sitemap-drift:
+    name: Notify doc-alerts of removed paths
+    needs: publish-docs-from-container
+    if: always() && needs.publish-docs-from-container.result == 'success' && github.repository_owner == 'netfoundry'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Download build artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: docusaurus-build-site
+          path: build-site/
+      - name: Check for sitemap drift report
+        id: drift
+        run: |
+          REPORT="build-site/sitemap-drift.json"
+          if [ ! -f "$REPORT" ]; then
+            echo "has_drift=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          COUNT=$(jq '.count' "$REPORT")
+          PATHS=$(jq -r '.removed[]' "$REPORT" | head -20 | sed 's/^/- /')
+          echo "has_drift=true" >> "$GITHUB_OUTPUT"
+          echo "count=$COUNT"   >> "$GITHUB_OUTPUT"
+          {
+            echo "paths<<EOF"
+            echo "$PATHS"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+      - name: Build drift event context
+        id: ctx
+        if: steps.drift.outputs.has_drift == 'true'
+        run: |
+          RUN_URL="https://github.com/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
+          BODY="⚠️ **${{ steps.drift.outputs.count }} path(s) removed** from the new build — redirects may be needed.
+
+${{ steps.drift.outputs.paths }}
+
+[View build logs](${RUN_URL})"
+          EVENT_JSON=$(jq -cn \
+            --arg repo "$GITHUB_REPOSITORY" \
+            --arg repo_url "https://github.com/$GITHUB_REPOSITORY" \
+            --arg run_url "$RUN_URL" \
+            --arg action "$BODY" \
+            '{
+              repository: { full_name: $repo, html_url: $repo_url, stargazers_count: 0 },
+              sender: { login: "ziti-ci", url: "https://api.github.com/users/netfoundry", html_url: "https://github.com/netfoundry", avatar_url: "https://raw.githubusercontent.com/netfoundry/branding/refs/heads/main/images/png/icon/netfoundry-icon-color.png" },
+              action: $action,
+              run_url: $run_url
+            }')
+          echo "event-json=$EVENT_JSON" >> "$GITHUB_OUTPUT"
+      - name: Send Mattermost alert
+        if: steps.drift.outputs.has_drift == 'true'
+        uses: openziti/ziti-mattermost-action-py@v1
+        with:
+          zitiId: ${{ secrets.ZITI_MATTERMOST_IDENTITY }}
+          webhookUrl: ${{ secrets.ZHOOK_URL_DOC_NOTIFICATIONS }}
+          eventJson: ${{ steps.ctx.outputs.event-json }}
+          senderUsername: "GitHubZ"
+
   # Notify the doc-alerts Mattermost channel only when the nightly scheduled
   # run fails. Push/workflow_dispatch runs are watched live by whoever triggered
   # them; the cron is unattended, so we only need a heads-up on failure.

unified-doc/publish-unified-doc.sh

@@ -39,6 +39,9 @@ if [ -f "$SITEMAP" ]; then
     echo "Injected llms.txt entry into sitemap.xml"
 fi
 
+# Check for paths removed vs production — writes sitemap-drift.json if any found.
+node "${pub_script_root}/scripts/check-sitemap-drift.mjs" "$SITEMAP" || true
+
 publish_docs() {
   local HOST=$1 PORT=$2 USER=$3 TARGET_DIR=$4 KEY_FILE=$5
   local zip_target="unified-docs${qualifier}.zip"

unified-doc/scripts/check-sitemap-drift.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+/**
+ * Compares the newly built sitemap against the live production sitemap.
+ * Any path present in production but absent from the new build is a potential
+ * broken link — it should either get a redirect or the removal is intentional.
+ *
+ * Usage: node check-sitemap-drift.mjs <new-sitemap-path>
+ *
+ * Writes a JSON report to <new-sitemap-dir>/sitemap-drift.json if paths were removed.
+ * Always exits 0 — never blocks the build.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const PROD_SITEMAP_URL = 'https://netfoundry.io/docs/sitemap.xml';
+
+const newSitemapPath = process.argv[2];
+if (!newSitemapPath) {
+    console.error('Usage: check-sitemap-drift.mjs <new-sitemap-path>');
+    process.exit(0);
+}
+
+if (!existsSync(newSitemapPath)) {
+    console.warn(`[sitemap-drift] New sitemap not found at ${newSitemapPath}, skipping.`);
+    process.exit(0);
+}
+
+function extractPaths(xml) {
+    const paths = new Set();
+    for (const match of xml.matchAll(/<loc>([^<]+)<\/loc>/g)) {
+        try {
+            const url = new URL(match[1]);
+            // Normalize: strip trailing slash except for root
+            const p = url.pathname.replace(/\/$/, '') || '/';
+            paths.add(p);
+        } catch {
+            // ignore malformed URLs
+        }
+    }
+    return paths;
+}
+
+// Paths to ignore — removed intentionally or not real doc pages
+const IGNORE_PREFIXES = [
+    '/docs/openziti/blog',
+    '/docs/openziti/1.x',
+    '/docs/openziti/tags',
+    '/docs/openziti/category',
+];
+
+function shouldIgnore(p) {
+    return IGNORE_PREFIXES.some(prefix => p === prefix || p.startsWith(prefix + '/'));
+}
+
+async function main() {
+    // Fetch production sitemap
+    let prodXml;
+    try {
+        const res = await fetch(PROD_SITEMAP_URL);
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        prodXml = await res.text();
+    } catch (err) {
+        console.warn(`[sitemap-drift] Could not fetch production sitemap: ${err.message}. Skipping.`);
+        process.exit(0);
+    }
+
+    const newXml = readFileSync(newSitemapPath, 'utf8');
+
+    const prodPaths = extractPaths(prodXml);
+    const newPaths  = extractPaths(newXml);
+
+    const removed = [...prodPaths]
+        .filter(p => !newPaths.has(p) && !shouldIgnore(p))
+        .sort();
+
+    if (removed.length === 0) {
+        console.log('[sitemap-drift] No paths removed. All good.');
+        process.exit(0);
+    }
+
+    console.warn(`[sitemap-drift] ⚠️  ${removed.length} path(s) removed from the new build:`);
+    for (const p of removed) console.warn(`  - ${p}`);
+
+    const report = { removed, count: removed.length };
+    const reportPath = join(dirname(newSitemapPath), 'sitemap-drift.json');
+    writeFileSync(reportPath, JSON.stringify(report, null, 2));
+    console.warn(`[sitemap-drift] Report written to ${reportPath}`);
+
+    process.exit(0);
+}
+
+main();