#!/usr/bin/env bash
# verify-docs.sh — assert that every subcommand documented in docs/cli.md
# exists in `orca --help` output (and vice versa). Catches doc drift.
#
# Usage: scripts/verify-docs.sh [binary] [docs/cli.md]
# Exit 0 = consistent, 1 = drift detected, 2 = error.
set -euo pipefail

BIN="${1:-./bin/orca}"
DOCS="${2:-docs/cli.md}"

if [ ! -x "$BIN" ]; then
  echo "verify-docs: binary not found at $BIN (run 'make build' first)" >&2
  exit 2
fi
if [ ! -f "$DOCS" ]; then
  echo "verify-docs: $DOCS not found" >&2
  exit 2
fi

# Extract top-level commands from `orca --help` (lines indented under
# "Available Commands:" with two leading spaces, command name is the
# first token).
HELP_OUTPUT="$("$BIN" --help 2>/dev/null)"
HELP_CMDS="$(echo "$HELP_OUTPUT" | \
  awk '/^Available Commands:/{flag=1; next} /^$/{flag=0} flag && /^  /{print $1}' | \
  grep -v '^completion$' | grep -v '^help$' | sort -u)"

# Extract documented commands from docs/cli.md. These appear as
# `## \`orca <command>\`` or `## \`orca <command>\` *(deprecated)*` headers.
DOC_CMDS="$(grep -oE '^## `orca [a-z_-]+`' "$DOCS" | \
  sed 's/^## `orca //; s/`$//' | sort -u)"

# Compare.
diff_out="$(diff <(echo "$HELP_CMDS") <(echo "$DOC_CMDS") || true)"

if [ -n "$diff_out" ]; then
  echo "verify-docs: drift detected between docs/cli.md and \`orca --help\`:" >&2
  echo "$diff_out" >&2
  echo "" >&2
  echo "Commands in --help but not in docs/cli.md (add them):" >&2
  comm -23 <(echo "$HELP_CMDS") <(echo "$DOC_CMDS") >&2
  echo "" >&2
  echo "Commands in docs/cli.md but not in --help (remove them or fix typo):" >&2
  comm -13 <(echo "$HELP_CMDS") <(echo "$DOC_CMDS") >&2
  exit 1
fi

echo "verify-docs: OK — docs/cli.md consistent with orca --help"
exit 0