improvise/scripts/checkers.sh

#!/usr/bin/env bash
# The one entry point for every check_the_checker in scripts/. CI calls THIS,
# and so does the local gate, so a suite cannot be green under one shell and
# red under the other. Reasoning: context/code/tooling.md section 3.
#
# It does two things a bare `./scripts/X-test.sh` does not. It runs every
# suite under the bash running it (the dev shell's), and it:
#
#   1. scrubs the environment down to an allowlist, because `nix develop`
#      exports `name`, `out`, `system`, `shell`, `builder` and two dozen more
#      generically-named variables that CI does not have -- a `set -u` fault
#      reading one of them is SILENT inside the dev shell and fatal in CI;
#   2. refuses a shell script in scripts/ whose shebang is not
#      `#!/usr/bin/env bash`, so the sh/bash split cannot come back.
set -euo pipefail

HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

usage() {
  cat >&2 <<'EOF'
usage: checkers.sh [--list] [--self-test] [name ...]

  name        a suite to run, spelled without the -test.sh suffix
              (e.g. `pr-reviews` for scripts/pr-reviews-test.sh).
              With no name, every suite in scripts/ runs.
  --list      print the suite names and exit
  --self-test run scripts/checkers-test.sh, which injects the faults this
              runner exists to catch

exit 0  every suite passed
exit 1  a suite failed, or a shebang is not `#!/usr/bin/env bash`
exit 4  usage error

THIS SCRIPT'S `$?` MUST BE THE ONE YOU READ. Nothing may follow it in the same
pipeline or `;` list -- a trailing `echo "exit=$?"` takes the status.
EOF
}

# The allowlist. A variable not named here does not reach a suite, which is the
# whole point: the dev shell's `name` masked improvise-f9qf's fault for a day.
# CHECKERS_KEEP adds names, space-separated, for a caller that needs one.
ALLOW="HOME TMPDIR TMP TEMP TERM LANG LC_ALL USER LOGNAME
       CI GITHUB_ACTIONS GITHUB_TOKEN GH_TOKEN
       NIX_PATH NIX_REMOTE NIX_SSL_CERT_FILE SSL_CERT_FILE
       XDG_CACHE_HOME XDG_CONFIG_HOME XDG_DATA_HOME"

# Every shell script in scripts/ says `#!/usr/bin/env bash` and nothing else.
# `#!/bin/sh` is dash in CI and bash 3.2 in sh-mode on macOS: a second platform
# split, undetected for the same reason the first one was.
check_shebangs() {
  local bad=0 f first
  for f in "$HERE"/*; do
    [ -f "$f" ] || continue
    first="$(head -1 "$f")"
    case "$first" in
      '#!'*sh|'#!'*sh\ *)
        case "$first" in
          '#!/usr/bin/env bash') ;;
          *) printf 'checkers: %s has shebang %s, wanted #!/usr/bin/env bash\n' \
               "${f##*/}" "$first" >&2; bad=1 ;;
        esac ;;
    esac
  done
  return $bad
}

# A check_the_checker is named after the thing it checks, so `X-test.sh` is a
# suite only when `X` or `X.sh` is here too. That excludes `node-test.sh`,
# which is a test RUNNER whose own checker is `node-test-test.sh`.
suites() {
  local f n
  for f in "$HERE"/*-test.sh; do
    [ -f "$f" ] || continue
    n="${f##*/}"; n="${n%-test.sh}"
    if [ -f "$HERE/$n" ] || [ -f "$HERE/$n.sh" ]; then printf '%s\n' "$n"; fi
  done
}

# $1 the suite file, run by the bash running this script, with PATH unchanged.
run_suite() {
  local file="$1"
  local -a env_args=(-i)
  local v
  for v in $ALLOW ${CHECKERS_KEEP:-}; do
    if [ -n "${!v+set}" ]; then env_args+=("$v=${!v}"); fi
  done
  env_args+=("PATH=$PATH")
  env "${env_args[@]}" "$BASH" "$file"
}

main() {
  local self_test=0
  local -a names=()
  while [ $# -gt 0 ]; do
    case "$1" in
      --list) suites; return 0 ;;
      --self-test) self_test=1 ;;
      -h|--help) usage; return 4 ;;
      -*) printf 'checkers: unknown option %s\n' "$1" >&2; usage; return 4 ;;
      *) names+=("$1") ;;
    esac
    shift
  done

  printf 'checkers: bash %s at %s\n' "$BASH_VERSION" "$BASH"
  local rc=0
  check_shebangs || rc=1

  if [ "$self_test" = 1 ]; then
    names=(checkers)
  elif [ ${#names[@]} -eq 0 ]; then
    while IFS= read -r line; do names+=("$line"); done < <(suites)
  fi

  local n file
  for n in ${names[@]+"${names[@]}"}; do
    file="$HERE/$n-test.sh"
    if [ ! -f "$file" ]; then
      printf 'checkers: no such suite: %s\n' "$n" >&2
      rc=4; continue
    fi
    printf '\n=== %s ===\n' "$n"
    run_suite "$file" || rc=1
  done
  return $rc
}

main "$@"