#!/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