beads/.github/scripts/docs-render-check.sh
Chris Sells 3198395a32 docs(ci): add Mintlify preview, docsync guard, and broken-links workflow
- mint.sh + make docs-dev: local preview of the docs/ Mintlify site
  (Node 22 handling modeled on the Gas City wrapper).
- test/docsync: Go guard keeping docs/ and docs.json in exact
  correspondence — every nav entry has a file, every page is in the nav
  (tiny stub allowlist for paths released bd binaries print), published
  pages use root-relative extensionless links that resolve, and engdocs/
  plus curated root markdown keep exact GitHub-style paths. Wired into
  make check-docs.
- .github/workflows/docs-mintlify.yml: docsync + baseline-aware
  mint broken-links check on PRs touching docs/**.
- Retire scripts/sync-website-docs.sh and its mirror-drift gate: the six
  mirrored files now live once in the Mintlify site; the committed
  Docusaurus mirrors stay frozen so the parallel-run site keeps building.
- Repoint inbound links to moved docs across README, guides, examples,
  npm-package, plugin resources, and Go comments; add docs/SYNC_CONCEPTS.md
  pointer stub (bd's agent templates print that path). Runtime strings in
  cmd/bd (prime.go, store_factory_nocgo.go, init_git_hooks.go) still print
  old paths — covered by stubs, flagged in the PR.
2026-07-12 10:37:07 -07:00

136 lines
4.9 KiB
Bash
Executable file

#!/usr/bin/env bash
#
# docs-render-check.sh — baseline-aware Mintlify broken-link check for CI.
#
# Runs `mint broken-links` on the HEAD docs tree. When the HEAD has broken
# page links, materializes the BASE docs tree (via git archive) and reports
# only NET-NEW breakage — links that the PR introduced, not pre-existing ones.
# Static-asset refs (.png/.svg/.jpg/.gif) are excluded: mint over-reports
# in-tree images the published build serves fine.
#
# Usage:
# docs-render-check.sh [<base-ref>]
#
# <base-ref> The base branch/sha to compare against (default: origin/main).
# Enables baseline-aware net-new detection.
#
# Exit codes:
# 0 — no net-new page-link regressions
# 1 — net-new page-link regressions found; details on stdout
#
# Requires: git, npx (Node.js), jq
#
set -euo pipefail
DOCS_DIR="docs"
DOCS_CONFIG="$DOCS_DIR/docs.json"
BASE_REF="${1:-origin/main}"
MINT_CMD="${MINT_CMD:-npx --yes mint@latest}"
WORK_TMP="$(mktemp -d)"
trap 'rm -rf "$WORK_TMP"' EXIT
# Verify we have a Mintlify docs tree.
if [[ ! -f "$DOCS_CONFIG" ]]; then
echo "docs-render-check: no docs/docs.json found — skipping" >&2
exit 0
fi
# --- extract_page_links <mint-output-file> -----------------------------------
# Parse `mint broken-links` output lines. Each broken link looks like:
# [broken-links] tutorials/01-beads.md -> /tutorials/01-beads.md
# or
# ✗ /tutorials/01-beads.md
# We capture only page links (no static-asset extensions).
ASSET_EXTS='\.png$|\.svg$|\.jpg$|\.jpeg$|\.gif$|\.ico$|\.webp$|\.woff2?$|\.ttf$|\.eot$'
extract_page_links() {
local file="$1"
grep -oE '[^ ]+\.[a-z]+$|/[^ ]+' "$file" 2>/dev/null \
| grep -vE "$ASSET_EXTS" \
| sort -u || true
}
# Alternative simpler extraction: just lines with the broken-links marker.
parse_mint_broken_links() {
local file="$1"
# mint outputs lines like: " ✗ /path/to/page" or " ✗ page-slug"
# or with indentation. Grab any token that looks like a link (starts with /).
grep -E '✗|broken|BROKEN|error|ERROR' "$file" 2>/dev/null \
| grep -oE '[/][^ )]+' \
| grep -vE "$ASSET_EXTS" \
| sort -u || true
}
# --- run_mint <docs-root> <output-file> → exit code -------------------------
run_mint() {
local root="$1"
local out="$2"
cd "$root"
if $MINT_CMD broken-links >"$out" 2>&1; then
cd - >/dev/null
return 0
fi
cd - >/dev/null
return 1
}
HEAD_OUT="$WORK_TMP/head-mint.txt"
BASE_OUT="$WORK_TMP/base-mint.txt"
BASE_TREE="$WORK_TMP/base-docs"
# --- HEAD check --------------------------------------------------------------
HEAD_EXIT=0
run_mint "." "$HEAD_OUT" || HEAD_EXIT=$?
if [[ $HEAD_EXIT -eq 0 ]]; then
echo "docs-render-check: no broken links in HEAD — PASS" >&2
exit 0
fi
HEAD_LINKS="$WORK_TMP/head-links.txt"
parse_mint_broken_links "$HEAD_OUT" | sort -u >"$HEAD_LINKS"
if [[ ! -s "$HEAD_LINKS" ]]; then
# mint exited non-zero but no links we care about. Pass.
echo "docs-render-check: mint non-zero but no page-link regressions detected — PASS" >&2
exit 0
fi
# --- BASE check (baseline-aware) --------------------------------------------
mkdir -p "$BASE_TREE"
if git archive "$BASE_REF" -- "$DOCS_DIR" 2>/dev/null | tar -x -C "$BASE_TREE"; then
BASE_EXIT=0
run_mint "$BASE_TREE" "$BASE_OUT" || BASE_EXIT=$?
BASE_LINKS="$WORK_TMP/base-links.txt"
parse_mint_broken_links "$BASE_OUT" | sort -u >"$BASE_LINKS"
# Net-new = in HEAD but NOT in BASE.
NEW_LINKS="$WORK_TMP/new-links.txt"
comm -23 "$HEAD_LINKS" "$BASE_LINKS" >"$NEW_LINKS"
else
echo "docs-render-check: could not materialize base tree from $BASE_REF — checking HEAD only" >&2
cp "$HEAD_LINKS" "$WORK_TMP/new-links.txt"
NEW_LINKS="$WORK_TMP/new-links.txt"
fi
if [[ ! -s "$NEW_LINKS" ]]; then
echo "docs-render-check: broken links exist but none are net-new — PASS (pre-existing baseline)" >&2
exit 0
fi
# --- NET-NEW regressions found — fail with explanation --------------
echo ""
echo "::error::docs-render-check: net-new broken Mintlify page links detected"
echo ""
echo "The following page links are newly broken by this PR:"
while IFS= read -r link; do
echo " $link"
done <"$NEW_LINKS"
echo ""
echo "──────────────────────────────────────────────────────────────────────────"
echo "docs/ is authored for the Mintlify site (the beads Mintlify site),"
echo "not for direct GitHub viewing. These paths/links are intentional —"
echo "please don't reformat them for GitHub. If something is genuinely broken"
echo "on the live site, note it in the PR and we'll fix it Mintlify-side."
echo "──────────────────────────────────────────────────────────────────────────"
exit 1