Makes the repo's agent and contributor surface describe developing beads, not using bd, and requires every PR to link a documented issue. - Contributor-only root AGENTS.md with a routing table; cmd/bd/AGENTS.md and engdocs/AGENTS.md seam files; CLAUDE.md symlinks so Claude Code loads nested files. - Bug and feature issue forms, a PR template that requires Closes #, CONTRIBUTING sections for the triage and pipeline labels, and the opt-in fork-cache during dev setup. - ROADMAP.md for 1.4: versioned beads (#6132), Graph Preview 2 (#7170), contributor onboarding (#7228). - docsync guards: root AGENTS.md at or under 20 KB; every AGENTS.md symlinked, routed, and with resolving links, paths, and guard-test names. Agent-Signature: claude-code-claude-opus-5-5-high on behalf of Julian Knutsen Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
257 lines
9.1 KiB
Bash
Executable file
257 lines
9.1 KiB
Bash
Executable file
#!/bin/bash
|
|
# check-doc-flags.sh — Validate documentation references against actual CLI flags.
|
|
#
|
|
# This script catches stale doc references by:
|
|
# 1. Extracting all flags from `bd help --all`
|
|
# 2. Scanning docs for `bd <command> --<flag>` patterns
|
|
# 3. Flagging any that don't exist in the CLI
|
|
#
|
|
# Also checks for references to known-removed commands.
|
|
#
|
|
# Usage: ./scripts/check-doc-flags.sh [bd-binary]
|
|
#
|
|
# Exit codes:
|
|
# 0 - All docs are consistent with CLI
|
|
# 1 - Stale references found
|
|
|
|
set -euo pipefail
|
|
|
|
BD="${1:-bd}"
|
|
ERRORS=0
|
|
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
|
PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
|
|
|
|
# Release pin (docs/cli-docs.pin): the docs describe the pinned release, so
|
|
# every check below validates against a bd built from that tag, not the
|
|
# supplied binary. Set BD_DOCS_IGNORE_PIN=1 to bypass.
|
|
if [ "${BD_DOCS_IGNORE_PIN:-0}" != "1" ]; then
|
|
PINNED_BD="$("$SCRIPT_DIR/resolve-docs-bd.sh")"
|
|
if [ -n "$PINNED_BD" ]; then
|
|
if [ "$BD" != "$PINNED_BD" ]; then
|
|
echo "Note: docs are pinned via docs/cli-docs.pin; validating against the pinned bd."
|
|
fi
|
|
BD="$PINNED_BD"
|
|
fi
|
|
fi
|
|
|
|
# Verify bd binary exists and runs
|
|
if ! command -v "$BD" &>/dev/null && [ ! -x "$BD" ]; then
|
|
echo "Error: bd binary not found at '$BD'"
|
|
echo "Usage: $0 [path-to-bd]"
|
|
exit 1
|
|
fi
|
|
|
|
# macOS has no coreutils timeout(1) by default; degrade to an unbounded run.
|
|
run_bounded() {
|
|
if command -v timeout >/dev/null 2>&1; then
|
|
timeout 30 "$@"
|
|
else
|
|
"$@"
|
|
fi
|
|
}
|
|
|
|
echo "Checking documentation against CLI flags..."
|
|
echo "Using: $($BD version 2>/dev/null | head -1 || echo "$BD")"
|
|
echo ""
|
|
|
|
# --- Check 1: Known-removed commands ---
|
|
echo "=== Check 1: Removed commands ==="
|
|
|
|
# bd sync: the JSONL-era command was removed in v0.51, and a top-level `bd sync`
|
|
# was reintroduced (wy-jpd3.4) as the federation loop — pull, positive conflict
|
|
# check, recompute-blocked, push. So the stale reference to hunt is no longer
|
|
# any mention of the command; it is docs still describing it as removed,
|
|
# deprecated, or a no-op, which is exactly what its own command doc said until
|
|
# the verb came back. CHANGELOG and the staged-for-removal audits are history
|
|
# and legitimately say so.
|
|
SYNC_REFS=$(grep -rn 'bd sync\b' \
|
|
"$PROJECT_ROOT"/docs/*.md \
|
|
"$PROJECT_ROOT"/docs/*/*.md \
|
|
"$PROJECT_ROOT"/cmd/bd/AGENTS.md \
|
|
"$PROJECT_ROOT"/AGENTS.md \
|
|
"$PROJECT_ROOT"/README.md \
|
|
"$PROJECT_ROOT"/npm-package/*.md \
|
|
"$PROJECT_ROOT"/integrations/*/README.md \
|
|
"$PROJECT_ROOT"/plugins/beads/skills/beads/commands/*.md \
|
|
"$PROJECT_ROOT"/plugins/beads/skills/beads/resources/*.md \
|
|
2>/dev/null \
|
|
| grep -v 'CHANGELOG\|audit-sync-mode' \
|
|
| grep -i 'deprecated\|no-op\|removed\|unknown-command' \
|
|
| grep -vi 'JSONL-era' \
|
|
|| true)
|
|
|
|
if [ -n "$SYNC_REFS" ]; then
|
|
echo "FAIL: Found docs describing 'bd sync' as removed/deprecated — it is a live command:"
|
|
echo "$SYNC_REFS" | head -20
|
|
ERRORS=$((ERRORS + 1))
|
|
else
|
|
echo "PASS: No stale 'bd sync is removed' references"
|
|
fi
|
|
|
|
echo ""
|
|
|
|
# --- Check 2: bd init flags ---
|
|
echo "=== Check 2: bd init flags ==="
|
|
|
|
# Get actual init flags. Match both long-only rows and rows with a short alias.
|
|
INIT_FLAGS_OK=1
|
|
if ! INIT_FLAGS=$("$BD" init --help 2>&1 \
|
|
| grep -E '^[[:space:]]+(-[[:alnum:]], )?--[a-z]' \
|
|
| grep -oE -- '--[a-z][a-z0-9-]*' \
|
|
| sort -u); then
|
|
echo "FAIL: Could not extract flags from 'bd init --help'"
|
|
ERRORS=$((ERRORS + 1))
|
|
INIT_FLAGS_OK=0
|
|
fi
|
|
|
|
# Check for --branch on init (removed)
|
|
BRANCH_REFS=$(grep -rn 'bd init.*--branch' \
|
|
"$PROJECT_ROOT"/docs/*.md \
|
|
"$PROJECT_ROOT"/docs/*/*.md \
|
|
"$PROJECT_ROOT"/cmd/bd/AGENTS.md \
|
|
"$PROJECT_ROOT"/AGENTS.md \
|
|
"$PROJECT_ROOT"/README.md \
|
|
2>/dev/null \
|
|
| grep -v 'CHANGELOG\|removed\|was removed\|no longer\|deprecated' \
|
|
|| true)
|
|
|
|
if [ "$INIT_FLAGS_OK" -ne 1 ]; then
|
|
echo "SKIP: Cannot validate 'bd init --branch' without the live init flag list"
|
|
elif printf '%s\n' "$INIT_FLAGS" | grep -qx -- '--branch'; then
|
|
echo "PASS: 'bd init --branch' is a live flag"
|
|
elif [ -n "$BRANCH_REFS" ]; then
|
|
echo "FAIL: Found references to removed 'bd init --branch' flag:"
|
|
echo "$BRANCH_REFS" | head -20
|
|
ERRORS=$((ERRORS + 1))
|
|
else
|
|
echo "PASS: No stale 'bd init --branch' references"
|
|
fi
|
|
|
|
echo ""
|
|
|
|
# --- Check 3: SQLite/legacy database paths ---
|
|
echo "=== Check 3: Legacy storage references ==="
|
|
|
|
SQLITE_REFS=$(grep -rn 'beads\.db\|default\.db\|sqlite3.*\.beads\|\.beads/.*\.db' \
|
|
"$PROJECT_ROOT"/docs/*.md \
|
|
"$PROJECT_ROOT"/docs/*/*.md \
|
|
"$PROJECT_ROOT"/cmd/bd/AGENTS.md \
|
|
"$PROJECT_ROOT"/AGENTS.md \
|
|
"$PROJECT_ROOT"/README.md \
|
|
2>/dev/null \
|
|
| grep -v 'CHANGELOG\|removed\|legacy\|migration\|migrate\|was removed\|pre-\|old\|deprecated' \
|
|
|| true)
|
|
|
|
if [ -n "$SQLITE_REFS" ]; then
|
|
echo "WARN: Found possible legacy SQLite/database references:"
|
|
echo "$SQLITE_REFS" | head -20
|
|
# Don't increment ERRORS — these may be intentional migration docs
|
|
else
|
|
echo "PASS: No stale SQLite references"
|
|
fi
|
|
|
|
echo ""
|
|
|
|
# --- Check 4: CLI command docs coverage and freshness ---
|
|
echo "=== Check 4: CLI command docs coverage and freshness ==="
|
|
|
|
CLI_REF="$PROJECT_ROOT/docs/CLI_REFERENCE.md"
|
|
if [ -f "$CLI_REF" ]; then
|
|
TMPDIR_CHECK=$(mktemp -d)
|
|
trap "rm -rf $TMPDIR_CHECK" EXIT
|
|
if run_bounded "$BD" help --list > "$TMPDIR_CHECK/help-cmds.txt" 2>/dev/null; then
|
|
sort -u "$TMPDIR_CHECK/help-cmds.txt" -o "$TMPDIR_CHECK/help-cmds.txt"
|
|
|
|
grep -oE '\bbd [a-z][a-z0-9-]*\b' "$CLI_REF" \
|
|
| sed 's/^bd //' | sort -u > "$TMPDIR_CHECK/cli-reference-cmds.txt" || true
|
|
|
|
MISSING_CLI_REF=$(comm -23 "$TMPDIR_CHECK/help-cmds.txt" "$TMPDIR_CHECK/cli-reference-cmds.txt" || true)
|
|
if [ -n "$MISSING_CLI_REF" ]; then
|
|
echo "FAIL: Live CLI commands missing from docs/CLI_REFERENCE.md:"
|
|
echo "$MISSING_CLI_REF" | sed 's/^/ bd /' | head -50
|
|
ERRORS=$((ERRORS + 1))
|
|
else
|
|
echo "PASS: docs/CLI_REFERENCE.md covers all live top-level CLI commands"
|
|
fi
|
|
|
|
WEBSITE_DIRS=("$PROJECT_ROOT/docs/cli-reference")
|
|
for dir in "${WEBSITE_DIRS[@]}"; do
|
|
if [ ! -d "$dir" ]; then
|
|
continue
|
|
fi
|
|
grep -rhoE '\bbd [a-z][a-z0-9-]*\b' "$dir"/*.md \
|
|
| sed 's/^bd //' | sort -u > "$TMPDIR_CHECK/website-cmds.txt" || true
|
|
|
|
MISSING_WEBSITE=$(comm -23 "$TMPDIR_CHECK/help-cmds.txt" "$TMPDIR_CHECK/website-cmds.txt" || true)
|
|
if [ -n "$MISSING_WEBSITE" ]; then
|
|
echo "FAIL: Live CLI commands missing from ${dir#$PROJECT_ROOT/}:"
|
|
echo "$MISSING_WEBSITE" | sed 's/^/ bd /' | head -50
|
|
ERRORS=$((ERRORS + 1))
|
|
else
|
|
echo "PASS: ${dir#$PROJECT_ROOT/} covers all live top-level CLI commands"
|
|
fi
|
|
done
|
|
|
|
if [ -x "$PROJECT_ROOT/scripts/generate-cli-docs.sh" ]; then
|
|
BD_FOR_GEN="$BD"
|
|
if ! [ -x "$BD_FOR_GEN" ]; then
|
|
BD_FOR_GEN="$(command -v "$BD" 2>/dev/null || true)"
|
|
fi
|
|
if [ -z "$BD_FOR_GEN" ]; then
|
|
echo "FAIL: Could not resolve bd binary path for CLI docs freshness check"
|
|
ERRORS=$((ERRORS + 1))
|
|
elif "$PROJECT_ROOT/scripts/check-cli-docs-drift.sh" "$BD_FOR_GEN"; then
|
|
echo "PASS: CLI docs freshness gate (see drift check output above)"
|
|
else
|
|
ERRORS=$((ERRORS + 1))
|
|
fi
|
|
else
|
|
echo "FAIL: scripts/generate-cli-docs.sh is missing"
|
|
ERRORS=$((ERRORS + 1))
|
|
fi
|
|
else
|
|
echo "FAIL: bd help --list timed out or unavailable"
|
|
ERRORS=$((ERRORS + 1))
|
|
fi
|
|
else
|
|
echo "FAIL: docs/CLI_REFERENCE.md not found"
|
|
ERRORS=$((ERRORS + 1))
|
|
fi
|
|
|
|
echo ""
|
|
|
|
# --- Check 5: Plugin CLI reference must stay a pointer ---
|
|
echo "=== Check 5: Plugin CLI reference pointer policy ==="
|
|
|
|
PLUGIN_CLI_REF="$PROJECT_ROOT/plugins/beads/skills/beads/resources/CLI_REFERENCE.md"
|
|
if [ -f "$PLUGIN_CLI_REF" ]; then
|
|
if grep -q 'This skill does not bundle a copied CLI command reference' "$PLUGIN_CLI_REF" \
|
|
&& grep -q 'docs/CLI_REFERENCE.md' "$PLUGIN_CLI_REF"; then
|
|
echo "PASS: plugin CLI resource is a pointer to live/canonical references"
|
|
else
|
|
echo "FAIL: plugin CLI resource drifted from pointer policy"
|
|
echo " Expected pointer language and canonical docs/CLI_REFERENCE.md reference in:"
|
|
echo " plugins/beads/skills/beads/resources/CLI_REFERENCE.md"
|
|
ERRORS=$((ERRORS + 1))
|
|
fi
|
|
else
|
|
echo "FAIL: plugin CLI resource missing: plugins/beads/skills/beads/resources/CLI_REFERENCE.md"
|
|
ERRORS=$((ERRORS + 1))
|
|
fi
|
|
|
|
echo ""
|
|
|
|
# --- Summary ---
|
|
echo "=== Summary ==="
|
|
if [ $ERRORS -gt 0 ]; then
|
|
echo "FAILED: $ERRORS stale reference category(ies) found"
|
|
echo ""
|
|
echo "To fix:"
|
|
echo " 1. Update stale prose references to use current CLI commands."
|
|
echo " 2. Regenerate CLI docs with: ./scripts/generate-cli-docs.sh $BD"
|
|
echo " 3. Re-run: ./scripts/check-doc-flags.sh $BD"
|
|
exit 1
|
|
else
|
|
echo "PASSED: All documentation references are consistent with CLI"
|
|
exit 0
|
|
fi
|