#!/usr/bin/env bash # The docs checker (plan 0040 step 17): every fenced block tagged run=gate (the tag atlibs' docs use: ```bash run=gate) in the # docs listed below runs and must pass. A page's blocks run in ONE shell (bash -euo pipefail), in order, from the repository # root, with HOME a scratch dir (an example never touches the real install), so a later block sees what an earlier one exported. A run=gate block that is not bash or sh fails: nothing here runs it. # A block with any other tag, or none, is not run; the summary counts them and --list names every block (file:line: its fence). # The list: README.md, docs/quickstart*.md, docs/deploy.md, docs/bidder.md, and with ATLIBS_REPO set to an atlibs checkout # its docs/ (run from that checkout). Docs that act on prod and the debug docs (docs/ci-debug.md, AGENTS.md, the plans and # the runbooks) are not in the list. Arguments replace the list: files or directories (every *.md under one), run from --root. # scripts/check-docs.sh [--list] [--root ] [ ...] set -uo pipefail here="$(cd "$(dirname "$0")/.." && pwd)" list=0 root="" args=() while [ $# -gt 0 ]; do case "$1" in --list) list=1 ;; --root) root="$(cd "${2:?--root }" && pwd)" || exit 2; shift ;; -*) echo "usage: $0 [--list] [--root ] [ ...]" >&2; exit 2 ;; *) args+=("$1") ;; esac shift done mkdir -p "${TMPDIR:-$HOME/.tmp}" state="$(mktemp -d "${TMPDIR:-$HOME/.tmp}/check-docs.XXXXXX")" || exit 2 trap 'rm -rf "$state"' EXIT rc=0 ran=0 other=0 pages=0 # blocks : one line per fenced block, " ", its body in $state/body. blocks() { rm -f "$state"/body.* awk -v dir="$state" ' !open && match($0, /^[ \t]*```/) { open = 1; indent = RLENGTH - 3; at = FNR; info = substr($0, RLENGTH + 1) gsub(/^[ \t]+|[ \t]+$/, "", info); gsub(/[ \t]+/, "\037", info) body = dir "/body." at; printf "" > body print at, (info == "" ? "\037" : info) next } open && /^[ \t]*```[ \t]*$/ { open = 0; close(body); next } open { line = $0; if (indent > 0 && match(line, /^[ \t]+/)) line = substr(line, (RLENGTH < indent ? RLENGTH : indent) + 1); print line >> body } END { if (open) { print FILENAME ":" at ": a fence that never closes" > "/dev/stderr"; exit 1 } } ' "$1" } # check check() { local base="$1" page="$2" at info lang gate=0 rest=0 bad=0 script="$state/page.sh" index="$state/index" pages=$((pages + 1)) if ! blocks "$base/$page" > "$index"; then rc=1 return fi : > "$script" while read -r at info; do info="${info//$'\037'/ }" info="${info# }" if [ "$list" = 1 ]; then echo "$page:$at: \`\`\`$info" fi case " $info " in *" run=gate "*) lang="${info%% *}" gate=$((gate + 1)) if [ "$lang" != bash ] && [ "$lang" != sh ]; then echo "check-docs.sh: FAILED $page:$at: a run=gate block of \`$lang\`: only bash and sh blocks run" >&2 rc=1 bad=1 continue fi { printf 'echo %q > %q\n' "$page:$at" "$state/at" printf 'echo %q >&2\n' "check-docs.sh: run $page:$at" cat "$state/body.$at" echo } >> "$script" ;; *) rest=$((rest + 1)) ;; esac done < "$index" ran=$((ran + gate)) other=$((other + rest)) if [ "$list" = 1 ] || [ "$bad" = 1 ]; then return fi if [ -s "$script" ]; then rm -f "$state/at" if ! (mkdir -p "$state/home" && cd "$base" && HOME="$state/home" bash -euo pipefail "$script"); then echo "check-docs.sh: FAILED $(cat "$state/at" 2>/dev/null || echo "$page"): the block did not pass" >&2 rc=1 return fi fi echo "check-docs.sh: ok $page ($gate run=gate, $rest not run)" } # each ... each() { local base="$1" p f shift for p in "$@"; do [ "$p" != . ] || p="" if [ -d "$base/$p" ]; then while read -r f; do check "$base" "${f#"$base"/}"; done < <(find "$base/${p#./}" -name '*.md' -type f | LC_ALL=C sort) elif [ -f "$base/$p" ]; then check "$base" "$p" else echo "check-docs.sh: FAILED $p: not a file or directory of $base" >&2 rc=1 fi done } if [ "${#args[@]}" -gt 0 ]; then each "${root:-$PWD}" "${args[@]}" else each "$here" README.md $(cd "$here" && ls docs/quickstart*.md) docs/deploy.md docs/bidder.md if [ -n "${ATLIBS_REPO:-}" ]; then each "$(cd "$ATLIBS_REPO" && pwd)" docs fi fi [ "$pages" -gt 0 ] || { echo "check-docs.sh: FAILED no doc to check" >&2; exit 1; } if [ "$list" = 1 ]; then echo "check-docs.sh: $pages docs: $ran run=gate blocks, $other not run" elif [ "$rc" = 0 ]; then echo "check-docs.sh: ok $pages docs: $ran run=gate blocks ran and passed, $other blocks not run" fi exit $rc