|
| 1 | +#!/usr/bin/env bash |
| 2 | +# |
| 3 | +# verify-report.sh — the shared verdict contract for acq-kit `scripts/verify`. |
| 4 | +# |
| 5 | +# A verdict is a function of a COVERAGE RECORD, not a failure counter: a run |
| 6 | +# that checked nothing, and a run where every check passed, must not produce |
| 7 | +# the same result. This library supplies that record and the five states a |
| 8 | +# verify script needs to express it. |
| 9 | +# |
| 10 | +# STATES |
| 11 | +# |
| 12 | +# ok "<what passed>" a check ran and passed |
| 13 | +# bad "<what failed>" a check ran and failed |
| 14 | +# unver "<what, and why not>" a check COULD NOT RUN — missing tool, absent |
| 15 | +# credential, no network. Not a pass. Counted, |
| 16 | +# and it degrades the verdict. |
| 17 | +# skip "<what, and why>" deliberately not applicable in this |
| 18 | +# configuration (e.g. a backend-specific check on |
| 19 | +# the other backend). Counted and reported, but |
| 20 | +# does NOT degrade the verdict. |
| 21 | +# warn "<note>" advisory only; a documented fallback was taken. |
| 22 | +# Counted and reported; does not degrade. |
| 23 | +# |
| 24 | +# `unver` degrades the verdict because a check could not run. `skip` records a |
| 25 | +# check that does not apply to the current configuration and does not degrade it. |
| 26 | +# |
| 27 | +# EXIT CODES (verify_verdict) |
| 28 | +# |
| 29 | +# 0 every check that ran passed, and at least one check ran |
| 30 | +# 1 at least one check FAILED |
| 31 | +# 3 nothing failed, but the run is not a clean pass: |
| 32 | +# - at least one check could not be performed (unverified > 0), or |
| 33 | +# - no check ran at all (pass == 0) |
| 34 | +# |
| 35 | +# 3 is separate from 1 so a caller can tell "we looked and found problems" from |
| 36 | +# "we could not look". A caller that only cares about red/green can test for |
| 37 | +# non-zero and will correctly refuse to treat a degraded run as success. |
| 38 | +# |
| 39 | +# USAGE |
| 40 | +# |
| 41 | +# KIT_DIR="$(cd "$(dirname "$0")/.." && pwd)" |
| 42 | +# . "$KIT_DIR/../verify-report.sh" |
| 43 | +# verify_reset # initialize the counters |
| 44 | +# info "1. Something" |
| 45 | +# ok "it worked" |
| 46 | +# unver "API probe — no network" |
| 47 | +# verify_verdict "Offline gate" # prints the summary, returns 0/1/3 |
| 48 | +# |
| 49 | +# `verify_verdict` takes an optional label so a script with more than one gate |
| 50 | +# (openchamber, paseo and pi-coding-agent each have three) can name each one. |
| 51 | +# |
| 52 | +# POSIX sh compatible on purpose: these scripts run on contributor machines with |
| 53 | +# whatever /bin/sh is, and the arithmetic and parameter expansion here stay |
| 54 | +# within that subset. |
| 55 | + |
| 56 | +# Counters. Deliberately not `local` — they are the script-wide coverage record. |
| 57 | +verify_reset() { |
| 58 | + pass=0 |
| 59 | + fail=0 |
| 60 | + unverified=0 |
| 61 | + skipped=0 |
| 62 | + warned=0 |
| 63 | +} |
| 64 | + |
| 65 | +ok() { |
| 66 | + printf ' \033[32mPASS\033[0m %s\n' "$1" |
| 67 | + pass=$((pass + 1)) |
| 68 | +} |
| 69 | + |
| 70 | +bad() { |
| 71 | + printf ' \033[31mFAIL\033[0m %s\n' "$1" |
| 72 | + fail=$((fail + 1)) |
| 73 | +} |
| 74 | + |
| 75 | +# Could not check. The message SHOULD say what was not checked AND why, because |
| 76 | +# the reader's next question is always "why not". |
| 77 | +unver() { |
| 78 | + printf ' \033[35mUNVERIFIED\033[0m %s\n' "$1" |
| 79 | + unverified=$((unverified + 1)) |
| 80 | +} |
| 81 | + |
| 82 | +# Not applicable in this configuration. Does not degrade the verdict. |
| 83 | +skip() { |
| 84 | + printf ' \033[33mSKIP\033[0m %s\n' "$1" |
| 85 | + skipped=$((skipped + 1)) |
| 86 | +} |
| 87 | + |
| 88 | +# Advisory note; a documented fallback was taken. Does not degrade the verdict. |
| 89 | +warn() { |
| 90 | + printf ' \033[33mWARN\033[0m %s\n' "$1" |
| 91 | + warned=$((warned + 1)) |
| 92 | +} |
| 93 | + |
| 94 | +info() { |
| 95 | + printf '\n\033[1m%s\033[0m\n' "$1" |
| 96 | +} |
| 97 | + |
| 98 | +# Print the coverage record and return the verdict. |
| 99 | +# |
| 100 | +# $1 — optional gate label (default "Summary"). |
| 101 | +verify_verdict() { |
| 102 | + _vr_label="${1:-Summary}" |
| 103 | + |
| 104 | + info "$_vr_label" |
| 105 | + printf ' %d passed, %d failed, %d unverified, %d skipped, %d warned\n' \ |
| 106 | + "$pass" "$fail" "$unverified" "$skipped" "$warned" |
| 107 | + |
| 108 | + if [ "$fail" -gt 0 ]; then |
| 109 | + printf ' \033[31m%s FAILED — see above.\033[0m\n' "$_vr_label" |
| 110 | + return 1 |
| 111 | + fi |
| 112 | + |
| 113 | + # Nothing ran. Arithmetic over zero must never produce a pass: pass=0 and |
| 114 | + # fail=0 is a report of nothing proven, not a report of success. |
| 115 | + if [ "$pass" -eq 0 ]; then |
| 116 | + printf ' \033[35m%s UNVERIFIED — no check ran, so nothing was proven.\033[0m\n' \ |
| 117 | + "$_vr_label" |
| 118 | + return 3 |
| 119 | + fi |
| 120 | + |
| 121 | + if [ "$unverified" -gt 0 ]; then |
| 122 | + printf ' \033[35m%s UNVERIFIED — %d check(s) could not be performed; this is not a pass.\033[0m\n' \ |
| 123 | + "$_vr_label" "$unverified" |
| 124 | + return 3 |
| 125 | + fi |
| 126 | + |
| 127 | + printf ' \033[32m%s passed.\033[0m\n' "$_vr_label" |
| 128 | + return 0 |
| 129 | +} |
0 commit comments