beads/scripts/check-doc-freshness.sh
Chris Sells 5c2fe0d496 docs: loss-check merge legacy docs/ originals into the site pages
Sixteen same-ground pairs reconciled: the ported website page won and every
fact living only in the older docs/ original was merged in before deleting
it (INSTALLING, SETUP, ARCHITECTURE, CONFIG, GIT_INTEGRATION, ADVANCED,
TROUBLESHOOTING, FAQ, MOLECULES, ROUTING, MULTI_REPO_AGENTS, and the five
agent-integration guides). The two divergent FAQs are now one canonical
FAQ with the comparison-first framing leading and pre-1.0 version gating
removed.

The routing pair inverted: the ported page described a routing system that
does not exist (bd routes, bd hydrate, .beads/routes.jsonl); the page was
rebuilt from the accurate sources (ROUTING.md + MULTI_REPO_AGENTS.md)
against the real surface (routing.mode config, role detection,
repos.primary/additional hydration, --repo override).

Every claim was verified against the Go source or the generated CLI
reference. Phantom surfaces removed across the corpus: bd pin/hook/pour/
wisp/routes/hydrate/reserve/lock/merge/stats, bd hooks status, bd vc
conflicts/log, bd dolt set shared-server, fictional beads_* MCP tool names
(real names taken from beads-mcp server.py), import.orphan_handling and
export.error_policy config keys, database.wal_mode/cache_size, stale
.beads/dolt/sql-server.log paths, and SQLite-era file paths. Notable
corrections: min_hash_length default is 3, .beads/metadata.json is
git-tracked, tombstone status is removed, wisps live in the main database
under an ephemeral flag.

Freshness markers moved with their content (configuration, ide-setup) and
the freshness gate + DOC_INVENTORY ledger now point at the new locations.
Load-bearing anchors preserved: #branchless-workflows-jujutsu--jj,
#circuit-breaker-server-appears-down-failing-fast, #extensible-database,
#multi-repo-hydration. Pointer stubs remain at docs/{SETUP,INSTALLING,
GIT_INTEGRATION}.md because released binaries print those paths
(allowlisted in the docsync guard).

Gates: go test ./test/docsync PASS; generate-cli-docs.sh --check PASS;
check-doc-freshness.sh PASS; mint broken-links: no broken links; mint dev
serves all sections (11 routes spot-checked at 200).
2026-07-12 10:37:07 -07:00

139 lines
4.6 KiB
Bash
Executable file

#!/bin/bash
# check-doc-freshness.sh - Validate marker-based freshness for reference docs.
#
# Usage: ./scripts/check-doc-freshness.sh
#
# Environment:
# DOC_FRESHNESS_MAX_AGE_DAYS Maximum accepted age for Last reviewed markers.
# Defaults to 90 days.
# DOC_FRESHNESS_TODAY Override today's date for deterministic tests.
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
MAX_AGE_DAYS="${DOC_FRESHNESS_MAX_AGE_DAYS:-90}"
TODAY="${DOC_FRESHNESS_TODAY:-$(date +%F)}"
ERRORS=0
DOCS=(
"docs/reference/configuration.md|cmd/bd/main.go;cmd/bd/config.go;internal/configfile/"
"docs/getting-started/ide-setup.md|cmd/bd/setup*.go;internal/recipes/"
"docs/integrations/azure-devops.md|cmd/bd/ado*.go;internal/ado/"
"docs/reference/json-schema.md|cmd/bd/output.go;cmd/bd/errors.go;cmd/bd/protocol/json_contract_test.go"
"docs/recovery/init-safety.md|cmd/bd/init.go;cmd/bd/init_safety.go;cmd/bd/init_safety_test.go"
"engdocs/ERROR_HANDLING.md|cmd/bd/*.go;cmd/bd/errors.go"
"engdocs/LINTING.md|.golangci.yml"
"engdocs/design/otel/otel-data-model.md|internal/telemetry/;internal/storage/dolt/store.go;internal/compact/haiku.go;cmd/bd/find_duplicates.go;internal/hooks/"
)
echo "Checking reference doc freshness markers..."
echo "Max age: ${MAX_AGE_DAYS} days"
echo "Today: ${TODAY}"
echo ""
date_age_days() {
local reviewed="$1"
python3 - "$reviewed" "$TODAY" <<'PY'
import datetime
import sys
reviewed = datetime.date.fromisoformat(sys.argv[1])
today = datetime.date.fromisoformat(sys.argv[2])
print((today - reviewed).days)
PY
}
inventory_ref_for_doc() {
local doc="$1"
doc="${doc#docs/}"
doc="${doc#engdocs/}"
printf '%s\n' "$doc"
}
path_exists_or_glob_matches() {
local pattern="$1"
if [[ "$pattern" == *"*"* || "$pattern" == *"?"* || "$pattern" == *"["* ]]; then
compgen -G "$PROJECT_ROOT/$pattern" >/dev/null
else
[[ -e "$PROJECT_ROOT/$pattern" ]]
fi
}
for entry in "${DOCS[@]}"; do
IFS='|' read -r doc sources <<<"$entry"
doc_path="$PROJECT_ROOT/$doc"
inventory_ref="$(inventory_ref_for_doc "$doc")"
echo "=== $doc ==="
if [[ ! -f "$doc_path" ]]; then
echo "FAIL: missing document"
ERRORS=$((ERRORS + 1))
echo ""
continue
fi
if ! grep -Fq "\`$inventory_ref\`" "$PROJECT_ROOT/engdocs/DOC_INVENTORY.md"; then
echo "FAIL: engdocs/DOC_INVENTORY.md does not list \`$inventory_ref\`"
ERRORS=$((ERRORS + 1))
else
echo "PASS: listed in engdocs/DOC_INVENTORY.md"
fi
reviewed_line="$(grep -E -m1 '^Last reviewed: [0-9]{4}-[0-9]{2}-[0-9]{2}$' "$doc_path" || true)"
if [[ -z "$reviewed_line" ]]; then
echo "FAIL: missing Last reviewed marker in YYYY-MM-DD format"
ERRORS=$((ERRORS + 1))
else
reviewed="${reviewed_line#Last reviewed: }"
if ! age_days="$(date_age_days "$reviewed" 2>/dev/null)"; then
echo "FAIL: invalid Last reviewed date: $reviewed"
ERRORS=$((ERRORS + 1))
elif (( age_days < 0 )); then
echo "FAIL: Last reviewed date is in the future: $reviewed"
ERRORS=$((ERRORS + 1))
elif (( age_days > MAX_AGE_DAYS )); then
echo "FAIL: Last reviewed date is stale: $reviewed (${age_days} days old)"
ERRORS=$((ERRORS + 1))
else
echo "PASS: Last reviewed marker is current: $reviewed (${age_days} days old)"
fi
fi
if ! grep -Eq '^Freshness source:' "$doc_path"; then
echo "FAIL: missing Freshness source marker"
ERRORS=$((ERRORS + 1))
else
echo "PASS: Freshness source marker present"
fi
IFS=';' read -ra source_list <<<"$sources"
for source in "${source_list[@]}"; do
if ! grep -Fq "$source" "$doc_path"; then
echo "FAIL: Freshness source does not name $source"
ERRORS=$((ERRORS + 1))
elif ! path_exists_or_glob_matches "$source"; then
echo "FAIL: Freshness source path does not exist: $source"
ERRORS=$((ERRORS + 1))
else
echo "PASS: Freshness source path exists: $source"
fi
done
echo ""
done
echo "=== Summary ==="
if (( ERRORS > 0 )); then
echo "FAILED: $ERRORS reference doc freshness issue(s) found"
echo ""
echo "To fix:"
echo " 1. Re-review the failing doc against its Freshness source paths."
echo " 2. Update the doc's Last reviewed marker and Freshness source list."
echo " 3. Re-run: ./scripts/check-doc-freshness.sh"
exit 1
fi
echo "PASSED: Reference doc freshness markers are current and checkable"