Find guards wired onto a helper that can never return non-zero
This commit is contained in:
Gmer4Lfe
Executable
+171
@@ -0,0 +1,171 @@
|
|||||||
|
#!/bin/bash
|
||||||
|
# ══════════════════════════════════════════════════════════════════════════════════════════════
|
||||||
|
# PURPOSE
|
||||||
|
# Find guards that cannot fire. A script that writes
|
||||||
|
#
|
||||||
|
# do_the_work || STEP_OK=false
|
||||||
|
#
|
||||||
|
# is only telling the truth if do_the_work can actually return non-zero. When it cannot, the
|
||||||
|
# flag stays true no matter what happened, and the run reports a step it never completed.
|
||||||
|
#
|
||||||
|
# This is the most expensive bug shape in this repo — a summary that says ✅ is the thing the
|
||||||
|
# operator trusts instead of reading the log. adapter.sh already carries the scar: "every
|
||||||
|
# caller that wrote `platform_push_setup_state || X=false` was testing a constant."
|
||||||
|
#
|
||||||
|
# Written 2026-08-24. Its first run found partnership_offboard.sh Step 3 reporting a stack
|
||||||
|
# cleanup that could not fail and, on a second path, one that had not run at all.
|
||||||
|
#
|
||||||
|
# OPERATIONAL MODEL
|
||||||
|
# For every `cmd || VAR=false` in the tree, the command left of the || is resolved and
|
||||||
|
# classified:
|
||||||
|
#
|
||||||
|
# CANFAIL a shell function with an explicit non-zero exit path — the guard is real
|
||||||
|
# EXTERNAL chown, docker, ssh, rsync and friends — can fail, nothing to check
|
||||||
|
# IDIOM [[ … ]] && X=true || X=false — a conditional, not a guard
|
||||||
|
# NEVERFAILS a function with no non-zero path — the guard is decorative
|
||||||
|
# UNKNOWN could not be resolved; reported rather than assumed either way
|
||||||
|
#
|
||||||
|
# A function "can fail" if it contains `return` or `exit` with a non-zero literal or any
|
||||||
|
# variable. The variable case matters: cleanup_partner_containers ends `return "$_rc"`, and a
|
||||||
|
# pattern that only looked for digits reported a working guard as broken.
|
||||||
|
#
|
||||||
|
# UNKNOWN is a first-class verdict, not a failure. Deciding what a bare `done` returns means
|
||||||
|
# evaluating the last command of the last loop, and a checker that guesses at that would
|
||||||
|
# produce confident wrong answers in both directions.
|
||||||
|
#
|
||||||
|
# DESIGN PRINCIPLES
|
||||||
|
# Resolve the command, never word-split it.
|
||||||
|
# An early build stripped a leading "do" to handle `for x in …; do cmd || F=false; done`
|
||||||
|
# and turned do_final_sync into a phantom _final_sync that resolved to nothing. The
|
||||||
|
# inline-loop case is matched on "; do " with required trailing space; nothing else is
|
||||||
|
# trimmed from a command name.
|
||||||
|
#
|
||||||
|
# Comments are excluded before anything else.
|
||||||
|
# Two of the matches in this repo are prose describing the bug, in adapter.sh and
|
||||||
|
# rsync_stop.sh. A checker that reports the documentation of a fixed bug as the bug
|
||||||
|
# teaches the operator to skim its output.
|
||||||
|
#
|
||||||
|
# Every verdict names where it looked.
|
||||||
|
# A NEVERFAILS line carries the file and line of the function it judged, because the
|
||||||
|
# first question is always "which definition did it find" — a name can exist twice.
|
||||||
|
#
|
||||||
|
# OPERATIONAL SAFEGUARDS
|
||||||
|
# Read-only. Greps and reads; writes nothing, executes nothing it finds.
|
||||||
|
# Exits 1 when any NEVERFAILS is reported, 0 otherwise — safe to gate a commit on.
|
||||||
|
# UNKNOWN never fails the run. It is a prompt to look, not a defect claim.
|
||||||
|
#
|
||||||
|
# RUNTIME MODES
|
||||||
|
# ══════════════════════════════════════════════════════════════════════════════════════════════
|
||||||
|
#
|
||||||
|
# audit_guards.sh
|
||||||
|
# Classify every guard in the repo. Exits 1 if any guard cannot fire.
|
||||||
|
#
|
||||||
|
# audit_guards.sh --all
|
||||||
|
# Show every verdict, including the guards that are sound.
|
||||||
|
#
|
||||||
|
# audit_guards.sh --unknown
|
||||||
|
# Show only the guards that could not be resolved.
|
||||||
|
#
|
||||||
|
# ══════════════════════════════════════════════════════════════════════════════════════════════
|
||||||
|
|
||||||
|
REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||||
|
|
||||||
|
SHOW_ALL=false
|
||||||
|
ONLY_UNKNOWN=false
|
||||||
|
for a in "$@"; do
|
||||||
|
case "$a" in
|
||||||
|
--all) SHOW_ALL=true ;;
|
||||||
|
--unknown) ONLY_UNKNOWN=true ;;
|
||||||
|
*) echo "unknown argument: $a" >&2; exit 2 ;;
|
||||||
|
esac
|
||||||
|
done
|
||||||
|
|
||||||
|
cd "$REPO_ROOT" || { echo "cannot reach repo root: $REPO_ROOT" >&2; exit 2; }
|
||||||
|
|
||||||
|
# Locate a function definition and print "file:line" followed by its body.
|
||||||
|
_fn_body() {
|
||||||
|
local fn="$1" loc f ln
|
||||||
|
loc=$(grep -rnE "^[[:space:]]*(function[[:space:]]+)?${fn}[[:space:]]*\(\)" \
|
||||||
|
--include='*.sh' . 2>/dev/null | grep -v '^./.git' | head -1)
|
||||||
|
[[ -z "$loc" ]] && return 1
|
||||||
|
f=${loc%%:*}
|
||||||
|
ln=$(echo "$loc" | cut -d: -f2)
|
||||||
|
echo "${f#./}:$ln"
|
||||||
|
awk -v s="$ln" 'NR>=s { print; if (NR > s && /^\}/) exit }' "$f"
|
||||||
|
}
|
||||||
|
|
||||||
|
dead=0 sound=0 unknown=0 other=0
|
||||||
|
|
||||||
|
while IFS= read -r hit; do
|
||||||
|
file=${hit%%:*}
|
||||||
|
lno=$(echo "$hit" | cut -d: -f2)
|
||||||
|
code=$(echo "$hit" | cut -d: -f3-)
|
||||||
|
|
||||||
|
# Everything left of the ||, with an inline loop header removed. The trailing space after
|
||||||
|
# "do" is required — without it this eats the prefix of do_final_sync.
|
||||||
|
cmd=$(echo "$code" | sed 's/[[:space:]]*||.*//' \
|
||||||
|
| sed 's/^[[:space:]]*//' \
|
||||||
|
| sed 's/^.*;[[:space:]]*do[[:space:]]\{1,\}//')
|
||||||
|
head=$(echo "$cmd" | awk '{print $1}')
|
||||||
|
|
||||||
|
verdict=""; detail=""
|
||||||
|
case "$head" in
|
||||||
|
'[['|'[' | test )
|
||||||
|
verdict=IDIOM; detail="conditional, not a guard" ;;
|
||||||
|
chown|chmod|find|rm|mv|cp|docker|ssh|rsync|systemctl|timeout|curl|git|mkdir|ln|tar )
|
||||||
|
verdict=EXTERNAL; detail="external command, can fail" ;;
|
||||||
|
-*|2\>*|1\>*|\>* )
|
||||||
|
# A guard written across several lines: the match landed on a continuation of an
|
||||||
|
# external command (find … -exec …, a redirect) rather than on its head. Reading
|
||||||
|
# back to the head would mean parsing line continuations; the classification is
|
||||||
|
# the same either way, so it is recorded as what it is.
|
||||||
|
verdict=EXTERNAL; detail="continuation of a multi-line external command" ;;
|
||||||
|
esac
|
||||||
|
|
||||||
|
if [[ -z "$verdict" ]]; then
|
||||||
|
if body=$(_fn_body "$head"); then
|
||||||
|
where=$(echo "$body" | head -1)
|
||||||
|
body=$(echo "$body" | tail -n +2)
|
||||||
|
# Non-zero literal, or any variable — quoted or bare.
|
||||||
|
if echo "$body" | grep -qE '^[[:space:]]*(return|exit)[[:space:]]+("?\$|[1-9])'; then
|
||||||
|
verdict=CANFAIL; detail="$where"
|
||||||
|
else
|
||||||
|
verdict=NEVERFAILS
|
||||||
|
detail="$where — no non-zero exit path"
|
||||||
|
fi
|
||||||
|
else
|
||||||
|
verdict=UNKNOWN; detail="could not resolve '$head'"
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
|
||||||
|
case "$verdict" in
|
||||||
|
NEVERFAILS) dead=$((dead+1)) ;;
|
||||||
|
CANFAIL) sound=$((sound+1)) ;;
|
||||||
|
UNKNOWN) unknown=$((unknown+1)) ;;
|
||||||
|
*) other=$((other+1)) ;;
|
||||||
|
esac
|
||||||
|
|
||||||
|
if $ONLY_UNKNOWN; then
|
||||||
|
show=false
|
||||||
|
[[ "$verdict" == UNKNOWN ]] && show=true
|
||||||
|
elif $SHOW_ALL || [[ "$verdict" == NEVERFAILS ]]; then
|
||||||
|
show=true
|
||||||
|
else
|
||||||
|
show=false
|
||||||
|
fi
|
||||||
|
if $show; then
|
||||||
|
printf '%-11s %s:%s\n %s\n %s\n' \
|
||||||
|
"$verdict" "$file" "$lno" "$(echo "$cmd" | cut -c1-76)" "$detail"
|
||||||
|
fi
|
||||||
|
|
||||||
|
done < <(grep -rnE '\|\|[[:space:]]*[A-Za-z_][A-Za-z0-9_]*=false' --include='*.sh' . 2>/dev/null \
|
||||||
|
| grep -v '^./.git' \
|
||||||
|
| grep -vE ':[0-9]+:[[:space:]]*#' \
|
||||||
|
| sed 's|^\./||')
|
||||||
|
|
||||||
|
echo
|
||||||
|
echo "──────────────────────────────────────────────────────────────"
|
||||||
|
printf 'sound %s external/idiom %s unresolved %s CANNOT FIRE %s\n' \
|
||||||
|
"$sound" "$other" "$unknown" "$dead"
|
||||||
|
[[ $dead -gt 0 ]] && exit 1
|
||||||
|
exit 0
|
||||||
Reference in New Issue
Block a user