home-network-k3s-impl/ci/lib.sh

#!/usr/bin/env bash
# ci/lib.sh — shared helpers for the merge-gate scripts.
# Sourced by every ci/*.sh; never executed directly.
#
# Conventions:
#   - All scripts: `set -euo pipefail`.
#   - Log to stderr; machine-readable output (e.g. requirement lists) to stdout.
#   - Exit codes: 0 = pass, 1 = fail (gate blocks), 3 = SKIPPED/not-run
#     (cluster-gated stage with no cluster — NOT a pass, NOT a fail).
set -euo pipefail

# --- Paths -------------------------------------------------------------------
# CI_DIR = this ci/ directory (always the real script location). REPO_ROOT = its
# parent (impl repo root) by default, but OVERRIDABLE via the environment so the
# scripts can be pointed at a throwaway git repo under test (see ci/tests/) without
# copying them out of the tree. CI and normal runs leave it unset -> unchanged.
CI_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
: "${REPO_ROOT:=$(cd "${CI_DIR}/.." && pwd)}"
# shellcheck disable=SC1091
source "${CI_DIR}/versions.env"

# --- Integration points (other agents' entrypoints) --------------------------
# These are the seams this gate depends on. Each has an env override so the PM /
# owning agent can reconcile the real entrypoint at integration WITHOUT editing
# these scripts. Defaults are this workstream's *assumptions* — see README.
: "${CATALOG_DIR:=${REPO_ROOT}/catalog}"                       # ServiceDefinition sources
: "${SCHEMAS_DIR:=${REPO_ROOT}/schemas}"                       # owned by T-0.3 (schema + renderer contract)
: "${KYVERNO_POLICY_DIR:=${REPO_ROOT}/platform/kyverno}"       # owned by T-0.5 (L0 Kyverno policies + tests)
: "${CONFORMANCE_DIR:=${REPO_ROOT}/conformance}"               # owned by T-0.4 (Chainsaw harness + coverage)
# Commands (overridable). Defaults documented in ci/README.md.
: "${SCHEMA_VALIDATE_CMD:=${SCHEMAS_DIR}/validate.sh}"          # ASSUMED: validates catalog/*.yaml against the ServiceDefinition schema
: "${CONFORMANCE_CMD:=${CONFORMANCE_DIR}/run.sh}"              # ASSUMED: single-command conformance runner (R-TEST-02)

# --- Artifact locations (git-ignored: see .gitignore) ------------------------
: "${RESULTS_DIR:=${REPO_ROOT}/results}"    # JUnit XML lands here
: "${REPORTS_DIR:=${REPO_ROOT}/reports}"    # requirement-coverage report lands here
: "${JUNIT_DIR:=${RESULTS_DIR}/junit}"
: "${COVERAGE_DIR:=${REPORTS_DIR}/coverage}"

# --- Logging -----------------------------------------------------------------
_is_tty() { [ -t 2 ]; }
if _is_tty; then C_RED=$'\033[31m'; C_GRN=$'\033[32m'; C_YEL=$'\033[33m'; C_BLU=$'\033[34m'; C_DIM=$'\033[2m'; C_RST=$'\033[0m'
else C_RED=""; C_GRN=""; C_YEL=""; C_BLU=""; C_DIM=""; C_RST=""; fi

log()  { printf '%s[gate]%s %s\n' "$C_BLU" "$C_RST" "$*" >&2; }
ok()   { printf '%s[ ok ]%s %s\n' "$C_GRN" "$C_RST" "$*" >&2; }
warn() { printf '%s[warn]%s %s\n' "$C_YEL" "$C_RST" "$*" >&2; }
err()  { printf '%s[fail]%s %s\n' "$C_RED" "$C_RST" "$*" >&2; }
skip() { printf '%s[skip]%s %s\n' "$C_YEL" "$C_RST" "$*" >&2; }
die()  { err "$*"; exit 1; }

# Emit a GitHub/Gitea-Actions step-summary line if running in Actions.
summary() { [ -n "${GITHUB_STEP_SUMMARY:-}" ] && printf '%s\n' "$*" >> "$GITHUB_STEP_SUMMARY" || true; }

# --- Tooling -----------------------------------------------------------------
have() { command -v "$1" >/dev/null 2>&1; }

# require_tool <bin> <hint> — fail with an actionable message if missing.
require_tool() {
  have "$1" && return 0
  die "required tool '$1' not found. $2"
}

# entrypoint_ready <path-or-cmd> — returns 0 only if it exists AND is runnable.
# Used to distinguish 'other agent hasn't delivered yet / non-executable stub'
# (-> SKIP) from a wired entrypoint that genuinely fails (-> FAIL). A file that
# exists but isn't executable counts as NOT ready (unwired), not a failure.
entrypoint_ready() {
  local ep="$1"
  have "$ep" && return 0        # a bare command on PATH
  [ -f "$ep" ] && [ -x "$ep" ] && return 0   # an executable file
  return 1
}

# --- Cluster detection (drives SKIP vs run for L2/L3) -------------------------
# A cluster is 'available' only if explicitly declared. We NEVER auto-assume a
# cluster in Phase 0 — silence means SKIP, not pass (HARD RULE 4).
#   CLUSTER_AVAILABLE=true   -> L2/L3 run and are REQUIRED green
#   CLUSTER_AVAILABLE=false/unset -> L2/L3 SKIP (reported, never faked green)
cluster_available() {
  case "${CLUSTER_AVAILABLE:-false}" in
    true|1|yes) return 0 ;;
    *) return 1 ;;
  esac
}

mkartifacts() { mkdir -p "$JUNIT_DIR" "$COVERAGE_DIR"; }

# --- Touched-requirement subset (R-TEST-03 input) ----------------------------
# Sets: TOUCHED_RC (0 ok / 3 not determinable), TOUCHED_REQS[] and REQ_ARGS[]
# (ready to splice into a conformance/run.sh invocation).
#
# ci/touched-requirements.sh exits 3 — LOUDLY — when it cannot establish a reliable
# diff base, instead of the old silent degradation to an empty set. An empty set
# means run.sh gets no `--requirements`, which means its coverage `--require` gate
# never runs; treating "could not determine" as "nothing touched" is precisely the
# false green this helper exists to prevent. A stage still runs its FULL layer in
# that case (a superset, so nothing goes untested), but says plainly that the
# SCOPED check did not happen; ci/gate.sh turns that into an UNDECIDED decision.
load_touched_requirements() {
  local out rc=0
  out="$("${CI_DIR}/touched-requirements.sh")" || rc=$?
  TOUCHED_RC=$rc
  TOUCHED_REQS=()
  # `if`, not `[ ... ] && ...`: under `set -e` a false AND-list is the caller's last
  # command status and would abort the stage script on an EMPTY touched set.
  if [ -n "$out" ]; then mapfile -t TOUCHED_REQS <<< "$out"; fi
  REQ_ARGS=()
  if [ "$rc" -eq 3 ]; then
    warn "touched-requirement subset UNDETERMINED (reason logged above)."
    warn "  Running the FULL layer as a superset sanity net; the SCOPED R-TEST-03"
    warn "  coverage check is NOT performed here — ci/gate.sh reports that as UNDECIDED."
  elif [ "$rc" -ne 0 ]; then
    warn "touched-requirements.sh exited ${rc}; proceeding with the full layer."
  elif [ "${#TOUCHED_REQS[@]}" -gt 0 ]; then
    log "touched requirements: ${TOUCHED_REQS[*]}"
    REQ_ARGS=(--requirements "$(IFS=,; echo "${TOUCHED_REQS[*]}")")
  else
    log "empty touched-requirement set (base WAS established) — running the full layer."
  fi
  return 0
}