forgedock 1.18.0 → 1.20.0

package/scripts/check-edge-cases.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# check-edge-cases.sh — Enforce that every FORGE:ARCHITECT edge case maps to a test in the diff or an untestable reason.
+#
+# Usage: check-edge-cases.sh --architect <file> --builder <file> --base <ref> [--repo <path>]
+#
+# <architect> is a FORGE:ARCHITECT comment body (or the extracted block); only the text between
+# <!-- FORGE:EDGE_CASES:BEGIN --> and <!-- FORGE:EDGE_CASES:END --> is parsed. One record per line:
+#   EDGE: id=e1 kind=error|edge|concurrency description=<free text>
+# Only id= and kind= are parsed; the description is free text and is never interpreted. ids match ^e[0-9]+$.
+# <builder> is a FORGE:BUILDER comment body (may be empty or absent content). Lines parsed:
+#   EDGE_TEST: id=e1 test=<path>::<name>
+#   EDGE_TEST: id=e1 untestable=<non-empty reason, spaces allowed>
+#
+# An id is covered when it has a non-empty untestable= reason, or a test=<path>::<name> where <name> (fixed-string)
+# appears in a line ADDED to <path> by the change (merge-base(base,HEAD) to the working tree, plus untracked files).
+# Pre-existing tests never satisfy a new edge case.
+#
+# Exit codes:
+#   0  covered, or no edge-case block / empty block (prints "SKIP: ..."); on success prints "MAPPED_TESTS: <n>"
+#   1  UNMAPPED: <id> | TEST_NOT_IN_DIFF: <id> <path>::<name> | EMPTY_REASON: <id> | DUPLICATE_ID: <id>
+#   2  malformed block or EDGE_TEST line, bad arguments, unreadable input, unresolvable base, git failure —
+#      NEVER a pass; callers report DEGRADED
+#
+# Offline, values are data (never eval'd). Portable to bash 3.2: no mapfile, no associative arrays.
+
+set -uo pipefail
+
+ARCH=""; BUILDER=""; BASE=""; REPO="."
+USAGE="usage: check-edge-cases.sh --architect <file> --builder <file> --base <ref> [--repo <path>]"
+die2() { echo "check-edge-cases: $*" >&2; exit 2; }
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --architect) [ "$#" -ge 2 ] || die2 "--architect needs a value"; ARCH="$2"; shift 2 ;;
+    --builder)   [ "$#" -ge 2 ] || die2 "--builder needs a value"; BUILDER="$2"; shift 2 ;;
+    --base)      [ "$#" -ge 2 ] || die2 "--base needs a value"; BASE="$2"; shift 2 ;;
+    --repo)      [ "$#" -ge 2 ] || die2 "--repo needs a value"; REPO="$2"; shift 2 ;;
+    *) die2 "$USAGE" ;;
+  esac
+done
+[ -n "$ARCH" ] && [ -n "$BUILDER" ] && [ -n "$BASE" ] || die2 "$USAGE"
+[ -f "$ARCH" ] || die2 "architect file not found: $ARCH"
+[ -f "$BUILDER" ] || die2 "builder file not found: $BUILDER"
+
+TMP=$(mktemp -d "${TMPDIR:-/tmp}/check-edge-cases.XXXXXX") || die2 "mktemp failed"
+trap 'rm -rf "$TMP"' EXIT
+
+# ---- extract BEGIN..END regions of the architect body --------------------------------------------------
+awk -v out="$TMP/region" '
+  index($0, "<!-- FORGE:EDGE_CASES:BEGIN -->") { if (inb) { bad = 1 } inb = 1; seen = 1; next }
+  index($0, "<!-- FORGE:EDGE_CASES:END -->")   { if (!inb) { bad = 1 } inb = 0; next }
+  inb { print > out }
+  END { if (inb || bad) exit 3; if (!seen) exit 4 }
+' "$ARCH"
+case $? in
+  0) ;;
+  4) echo "SKIP: no edge-case block"; exit 0 ;;
+  *) die2 "unbalanced FORGE:EDGE_CASES:BEGIN/END markers" ;;
+esac
+
+# ---- parse EDGE records ---------------------------------------------------------------------------------
+: > "$TMP/ids"; : > "$TMP/dups"
+EDGE_RE='^EDGE: id=(e[0-9]+) kind=(error|edge|concurrency)([[:space:]]|$)'
+LN=0
+if [ -f "$TMP/region" ]; then
+  while IFS= read -r line || [ -n "$line" ]; do
+    LN=$((LN+1)); line="${line%$'\r'}"
+    trimmed="${line#"${line%%[![:space:]]*}"}"
+    case "$trimmed" in ""|'```'*) continue ;; esac
+    [[ "$trimmed" =~ $EDGE_RE ]] || die2 "line $LN: malformed EDGE record: $trimmed"
+    id="${BASH_REMATCH[1]}"
+    if grep -Fxq -- "$id" "$TMP/ids"; then echo "$id" >> "$TMP/dups"; else echo "$id" >> "$TMP/ids"; fi
+  done < "$TMP/region"
+fi
+if [ ! -s "$TMP/ids" ]; then echo "SKIP: empty edge-case block"; exit 0; fi
+
+# ---- parse EDGE_TEST lines of the builder body ----------------------------------------------------------
+: > "$TMP/maps"   # id<TAB>test|untestable<TAB>value
+: > "$TMP/mapdups"
+PRE='^(-[[:space:]]+)?EDGE_TEST:[[:space:]]+id=(e[0-9]+)[[:space:]]+(test|untestable)=(.*)$'
+while IFS= read -r line || [ -n "$line" ]; do
+  line="${line%$'\r'}"
+  trimmed="${line#"${line%%[![:space:]]*}"}"
+  case "$trimmed" in *EDGE_TEST:*) ;; *) continue ;; esac
+  case "$trimmed" in EDGE_TEST:*|"- EDGE_TEST:"*) ;; *) continue ;; esac   # only line-leading records, not prose mentions
+  [[ "$trimmed" =~ $PRE ]] || die2 "malformed EDGE_TEST line: $trimmed"
+  mid="${BASH_REMATCH[2]}"; mkind="${BASH_REMATCH[3]}"; mval="${BASH_REMATCH[4]}"
+  mval="${mval#"${mval%%[![:space:]]*}"}"; mval="${mval%"${mval##*[![:space:]]}"}"
+  if awk -F'\t' -v s="$mid" '$1==s {ok=1} END{exit ok?0:1}' "$TMP/maps"; then echo "$mid" >> "$TMP/mapdups"; continue; fi
+  printf '%s\t%s\t%s\n' "$mid" "$mkind" "$mval" >> "$TMP/maps"
+done < "$BUILDER"
+
+# ---- repo, base, merge-base -----------------------------------------------------------------------------
+case "$BASE" in ""|-*) die2 "invalid --base: '$BASE'" ;; esac
+git -C "$REPO" rev-parse --is-inside-work-tree >/dev/null 2>&1 || die2 "not a git work tree: $REPO"
+git -C "$REPO" rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null 2>&1 || die2 "cannot resolve base ref '$BASE'"
+MB=$(git -C "$REPO" merge-base "$BASE" HEAD 2>/dev/null) || die2 "no merge base between '$BASE' and HEAD"
+
+# added_has <path> <name>: 0 when <name> (fixed string) occurs in a line added to <path>
+added_has() {
+  local p="$1" n="$2" rc
+  if git -C "$REPO" ls-files --error-unmatch -- "$p" >/dev/null 2>&1; then
+    git -C "$REPO" diff -U0 --no-color "$MB" -- "$p" > "$TMP/d" 2>/dev/null || die2 "git diff failed for $p"
+    awk -v n="$n" '/^\+\+\+/ {next} /^\+/ { if (index($0, n) > 0) ok=1 } END{exit ok?0:1}' "$TMP/d"; return $?
+  fi
+  # untracked (new, not yet staged) file: every line is added
+  git -C "$REPO" ls-files --others --exclude-standard -- "$p" > "$TMP/u" 2>/dev/null || die2 "git ls-files failed"
+  [ -s "$TMP/u" ] || return 1
+  [ -f "$REPO/$p" ] || return 1
+  awk -v n="$n" 'index($0, n) > 0 {ok=1} END{exit ok?0:1}' "$REPO/$p"; rc=$?
+  return "$rc"
+}
+
+# ---- check ----------------------------------------------------------------------------------------------
+RC=0; MAPPED=0
+while IFS= read -r d; do [ -n "$d" ] && { echo "DUPLICATE_ID: $d"; RC=1; }; done < "$TMP/dups"
+while IFS= read -r d; do [ -n "$d" ] && { echo "DUPLICATE_ID: $d (EDGE_TEST)"; RC=1; }; done < "$TMP/mapdups"
+PATH_RE='^[A-Za-z0-9_./@+=:,-]+$'
+NAME_RE='^[^[:space:]]{1,200}$'
+while IFS= read -r id; do
+  row=$(awk -F'\t' -v s="$id" '$1==s {print; exit}' "$TMP/maps")
+  if [ -z "$row" ]; then echo "UNMAPPED: $id"; RC=1; continue; fi
+  mkind=$(printf '%s' "$row" | cut -f2); mval=$(printf '%s' "$row" | cut -f3-)
+  if [ "$mkind" = untestable ]; then
+    [ -n "$mval" ] || { echo "EMPTY_REASON: $id"; RC=1; }
+    continue
+  fi
+  case "$mval" in *::*) ;; *) die2 "$id: test= must be <path>::<name>: $mval" ;; esac
+  tpath="${mval%%::*}"; tname="${mval##*::}"
+  case "$tpath" in -*) die2 "$id: test path must not start with '-'" ;; esac
+  [[ "$tpath" =~ $PATH_RE ]] || die2 "$id: invalid test path: $tpath"
+  [[ "$tname" =~ $NAME_RE ]] || die2 "$id: invalid test name"
+  if added_has "$tpath" "$tname"; then MAPPED=$((MAPPED+1)); else echo "TEST_NOT_IN_DIFF: $id $tpath::$tname"; RC=1; fi
+done < "$TMP/ids"
+
+if [ "$RC" -eq 0 ]; then
+  echo "OK: edge cases covered ($(wc -l < "$TMP/ids" | tr -d ' ') id(s))"
+  echo "MAPPED_TESTS: $MAPPED"
+fi
+exit "$RC"

package/scripts/check-edge-cases.test.sh

@@ -0,0 +1,175 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# Fixtures for scripts/check-edge-cases.sh. Run: bash scripts/check-edge-cases.test.sh (bash 3.2 compatible)
+
+set -u
+DIR=$(cd "$(dirname "$0")" && pwd)
+S="$DIR/check-edge-cases.sh"
+T=$(mktemp -d "${TMPDIR:-/tmp}/check-edge-cases-test.XXXXXX")
+trap 'rm -rf "$T"' EXIT
+pass=0; fail=0
+OUT=""; RC=0
+
+g() { git -C "$T/r" -c user.name=t -c user.email=t@example.com -c commit.gpgsign=false "$@" >/dev/null 2>&1; }
+run() { OUT=$(bash "$S" --architect "$T/a" --builder "$T/b" --base staging --repo "$T/r" 2>&1); RC=$?; }
+arch() { { echo '## Plan'; echo '<!-- FORGE:EDGE_CASES:BEGIN -->'; cat; echo '<!-- FORGE:EDGE_CASES:END -->'; echo '<!-- FORGE:ARCHITECT:COMPLETE -->'; } > "$T/a"; }
+builder() { { echo '<!-- FORGE:BUILDER -->'; echo '### Edge Case Coverage'; cat; } > "$T/b"; }
+expect() { # expect <want_rc> <desc> [want_substring]
+  if [ "$RC" = "$1" ] && { [ -z "${3:-}" ] || case "$OUT" in *"$3"*) true ;; *) false ;; esac; }; then
+    pass=$((pass+1))
+  else
+    fail=$((fail+1)); echo "FAIL: $2 (rc=$RC, want $1)"; printf '%s\n' "$OUT" | sed 's/^/    /'
+  fi
+}
+expect_absent() { case "$OUT" in *"$2"*) fail=$((fail+1)); echo "FAIL: $1 (unexpected '$2')"; printf '%s\n' "$OUT" | sed 's/^/    /' ;; *) pass=$((pass+1)) ;; esac; }
+reset_branch() { g checkout -q -f staging; g branch -q -D feat; g checkout -q -b feat; }
+
+mkdir "$T/r"; git -C "$T/r" init -q -b staging >/dev/null 2>&1 || { git -C "$T/r" init -q; g checkout -b staging; }
+mkdir -p "$T/r/tests"
+printf 'def test_existing_case():\n    assert True\n' > "$T/r/tests/test_a.py"
+g add -A; g commit -m base
+g checkout -q -b feat
+
+E1='EDGE: id=e1 kind=edge description=empty input returns nothing'
+E2='EDGE: id=e2 kind=error description=upstream times out with several classes of error'
+add_test() { printf 'def %s():\n    assert True\n' "$1" >> "$T/r/tests/test_a.py"; g add -A; g commit -m "add $1"; }
+
+# (a) empty block / absent block pass
+arch </dev/null; builder </dev/null; run; expect 0 "empty block passes" "SKIP"
+printf '## Plan\nno block\n' > "$T/a"; : > "$T/b"; run; expect 0 "absent block passes" "SKIP"
+
+# (b) unmapped id fails
+arch <<M
+$E1
+M
+builder </dev/null; run; expect 1 "unmapped id fails" "UNMAPPED: e1"
+
+# (c) untestable with a reason passes; (d) empty reason fails
+builder <<M
+EDGE_TEST: id=e1 untestable=pure spec change, no runtime to exercise
+M
+run; expect 0 "untestable with reason passes" "OK:"
+builder <<M
+EDGE_TEST: id=e1 untestable=
+M
+run; expect 1 "empty untestable reason fails" "EMPTY_REASON: e1"
+builder <<M
+EDGE_TEST: id=e1 untestable=   
+M
+run; expect 1 "whitespace-only untestable reason fails" "EMPTY_REASON: e1"
+
+# (e) mapped test absent from the diff fails; present in added lines passes
+builder <<M
+EDGE_TEST: id=e1 test=tests/test_a.py::test_empty_input
+M
+run; expect 1 "mapped test not in diff fails" "TEST_NOT_IN_DIFF: e1"
+add_test test_empty_input
+run; expect 0 "mapped test in committed added lines passes" "MAPPED_TESTS: 1"
+
+# (h) a pre-existing test name never satisfies a new edge case
+builder <<M
+EDGE_TEST: id=e1 test=tests/test_a.py::test_existing_case
+M
+run; expect 1 "pre-existing test name fails" "TEST_NOT_IN_DIFF: e1"
+
+# the name must be in the mapped file, not just anywhere in the diff
+mkdir -p "$T/r/other"; printf 'def test_elsewhere():\n    pass\n' > "$T/r/other/test_b.py"; g add -A; g commit -m other
+builder <<M
+EDGE_TEST: id=e1 test=tests/test_a.py::test_elsewhere
+M
+run; expect 1 "name added in a different file fails" "TEST_NOT_IN_DIFF: e1"
+
+# staged-but-uncommitted and untracked tests count (validate runs before the commit)
+printf 'def test_staged_case():\n    pass\n' >> "$T/r/tests/test_a.py"; g add -A
+printf 'def test_untracked_case():\n    pass\n' > "$T/r/tests/test_new.py"
+arch <<M
+$E1
+$E2
+M
+builder <<M
+EDGE_TEST: id=e1 test=tests/test_a.py::test_staged_case
+EDGE_TEST: id=e2 test=tests/test_new.py::test_untracked_case
+M
+run; expect 0 "staged and untracked tests count" "MAPPED_TESTS: 2"
+reset_branch
+
+# (g) duplicate ids fail (architect side and builder side)
+arch <<M
+$E1
+EDGE: id=e1 kind=error description=same id twice
+M
+builder <<M
+EDGE_TEST: id=e1 untestable=reason one
+M
+run; expect 1 "duplicate architect id fails" "DUPLICATE_ID: e1"
+arch <<M
+$E1
+M
+builder <<M
+EDGE_TEST: id=e1 untestable=reason one
+EDGE_TEST: id=e1 untestable=reason two
+M
+run; expect 1 "duplicate EDGE_TEST id fails" "DUPLICATE_ID: e1"
+
+# mixed: one covered, one unmapped -> only the unmapped id is named
+arch <<M
+$E1
+$E2
+M
+builder <<M
+- EDGE_TEST: id=e1 untestable=reason given
+M
+run; expect 1 "bulleted EDGE_TEST line parses; other id unmapped" "UNMAPPED: e2"
+expect_absent "covered id is not reported" "UNMAPPED: e1"
+
+# prose mentioning EDGE_TEST mid-line is not a record
+builder <<M
+Note: each id needs an EDGE_TEST: line later.
+EDGE_TEST: id=e1 untestable=reason given
+EDGE_TEST: id=e2 untestable=another reason
+M
+run; expect 0 "mid-line EDGE_TEST mention ignored" "OK:"
+
+# (f) bad input is rc 2, never a pass
+builder <<M
+EDGE_TEST: id=e1 untestable=r
+EDGE_TEST: id=e2 test=no-separator
+M
+run; expect 2 "test= without ::name is rc 2" "must be <path>::<name>"
+builder <<M
+EDGE_TEST: id=e1 bogus=1
+M
+run; expect 2 "malformed EDGE_TEST is rc 2" "malformed EDGE_TEST"
+builder <<M
+EDGE_TEST: id=e1 test=--evil::x
+M
+run; expect 2 "test path starting with - is rc 2"
+printf '<!-- FORGE:EDGE_CASES:BEGIN -->\nEDGE: id=bad kind=edge description=x\n<!-- FORGE:EDGE_CASES:END -->\n' > "$T/a"; : > "$T/b"
+run; expect 2 "malformed EDGE id is rc 2" "malformed EDGE record"
+printf '<!-- FORGE:EDGE_CASES:BEGIN -->\nEDGE: id=e1 kind=edge description=x\n' > "$T/a"
+run; expect 2 "unbalanced markers are rc 2" "unbalanced"
+arch <<M
+$E1
+M
+builder <<M
+EDGE_TEST: id=e1 untestable=r
+M
+OUT=$(bash "$S" --architect "$T/a" --builder "$T/b" --base nonexistent --repo "$T/r" 2>&1); RC=$?; expect 2 "unresolvable base is rc 2" "cannot resolve base"
+mkdir -p "$T/notgit"
+OUT=$(bash "$S" --architect "$T/a" --builder "$T/b" --base staging --repo "$T/notgit" 2>&1); RC=$?; expect 2 "non-git repo is rc 2"
+OUT=$(bash "$S" --architect "$T/missing" --builder "$T/b" --base staging --repo "$T/r" 2>&1); RC=$?; expect 2 "missing architect file is rc 2"
+OUT=$(bash "$S" --base staging 2>&1); RC=$?; expect 2 "missing args is rc 2"
+
+# description with spaces and punctuation is data, never parsed or executed
+arch <<'M'
+EDGE: id=e1 kind=concurrency description=two writers $(touch /tmp/pwned) `x` "quoted" a=b
+M
+builder <<M
+EDGE_TEST: id=e1 untestable=reason given
+M
+run; expect 0 "free-text description is inert" "OK:"
+
+echo "check-edge-cases.test.sh: $pass passed, $fail failed"
+[ "$fail" -eq 0 ]

package/scripts/check-spec-markers.sh

@@ -108,12 +108,14 @@ MARKER_REGISTRY="
   DECISION_RECORD
   DECOMPOSED
   DECOMPOSE_BLOCKED
+  DEGRADED_REREVIEW
   DEFERRED_FROM
   DESIGN
   DIFF_SIZE
   DISPATCH
   DISPATCHER
   DOSSIER_UPDATED
+  EDGE_CASES
   ENGINE_FALLBACK
   FAST_PATH
   FINDING_SOURCE
@@ -175,6 +177,8 @@ MARKER_REGISTRY="
   REVIEW_TIER
   REVIEW_STARTED
   SECURITY_AUDIT
+  SELFREVIEW
+  SELFREVIEW_REPAIR
   SIGNAL_RESOLVED
   SIGNAL_UNRESOLVED
   SIZE_OVERRIDE

package/scripts/check-test-tmp-cleanup.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# check-test-tmp-cleanup.sh — fail when a test suite creates a temp dir with no cleanup.
+#
+# Conservative text check (no parsing):
+#   - bin/**/*.test.mjs that mentions mkdtemp/mkdtempSync must import the shared
+#     helper bin/tests/_tmp.mjs (tmpDir registers removal at process exit).
+#   - scripts/*.test.sh that calls mktemp must register an EXIT trap.
+# The helper itself (bin/tests/_tmp.mjs) is not a *.test.mjs file and is not scanned.
+#
+# Usage: bash scripts/check-test-tmp-cleanup.sh [ROOT]
+#   ROOT defaults to the repo root; the test points it at fixture trees.
+# Exit: 0 clean, 1 offenders found (printed one per line), 2 bad ROOT.
+# Bash 3.2 portable: no mapfile, no associative arrays.
+
+set -u
+
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+ROOT="${1:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+[ -d "$ROOT" ] || { echo "check-test-tmp-cleanup: ROOT is not a directory: $ROOT" >&2; exit 2; }
+
+BAD=0
+
+if [ -d "$ROOT/bin" ]; then
+  NODE_FILES=$(find "$ROOT/bin" -name '*.test.mjs' -not -path '*/node_modules/*' | sort)
+  while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    grep -qE 'mkdtemp(Sync)?[[:space:]]*\(|^[[:space:]]*mkdtemp(Sync)?,?[[:space:]]*$|import[^;]*mkdtemp' "$f" || continue
+    if ! grep -qE "^[[:space:]]*import[^;]*from[[:space:]]+['\"][./]+(tests/)?_tmp\.mjs['\"]" "$f"; then
+      echo "VIOLATION: ${f#"$ROOT"/}: uses mkdtemp without importing bin/tests/_tmp.mjs (use tmpDir)"
+      BAD=1
+    fi
+  done <<EOF_NODE
+${NODE_FILES}
+EOF_NODE
+fi
+
+if [ -d "$ROOT/scripts" ]; then
+  SH_FILES=$(find "$ROOT/scripts" -maxdepth 1 -name '*.test.sh' | sort)
+  while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    # a mktemp call: skip comment lines and quoted mentions inside grep -F patterns
+    grep -E '(^|[^[:alnum:]_.-])mktemp([[:space:]]|\)|$)' "$f" | grep -vE '^[[:space:]]*#' | grep -vE "grep[^|]*mktemp" | grep -q . || continue
+    if ! grep -qE '^[^#]*\btrap\b[^#]*\bEXIT\b' "$f"; then
+      echo "VIOLATION: ${f#"$ROOT"/}: uses mktemp without an EXIT trap"
+      BAD=1
+    fi
+  done <<EOF_SH
+${SH_FILES}
+EOF_SH
+fi
+
+[ "$BAD" -eq 0 ] && echo "check-test-tmp-cleanup: OK"
+exit "$BAD"

package/scripts/check-test-tmp-cleanup.test.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# Tests for scripts/check-test-tmp-cleanup.sh (passing and failing fixtures, plus the real tree).
+# Run: bash scripts/check-test-tmp-cleanup.test.sh   (bash 3.2 compatible)
+
+set -u
+DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+LINT="$DIR/check-test-tmp-cleanup.sh"
+T=$(mktemp -d "${TMPDIR:-/tmp}/check-test-tmp-cleanup-test.XXXXXX")
+trap 'rm -rf "$T"' EXIT
+
+PASS=0; FAIL=0
+ok()  { PASS=$((PASS + 1)); echo "  ok - $1"; }
+bad() { FAIL=$((FAIL + 1)); echo "  FAIL - $1"; }
+
+# run_case NAME EXPECT_RC EXPECT_OUT_SUBSTR  (fixture tree = $T/$NAME)
+run_case() {
+  local name="$1" want_rc="$2" want_out="$3" out rc
+  out=$(bash "$LINT" "$T/$name" 2>&1); rc=$?
+  [ "$rc" -eq "$want_rc" ] && ok "$name: exit $want_rc" || bad "$name: exit $rc, wanted $want_rc ($out)"
+  case "$out" in *"$want_out"*) ok "$name: output mentions '$want_out'" ;; *) bad "$name: output lacks '$want_out' ($out)" ;; esac
+}
+
+mk() { mkdir -p "$T/$1/bin/tests" "$T/$1/scripts"; }
+
+mk pass_node
+printf 'import { tmpDir } from "./_tmp.mjs";\nconst d = tmpDir("fd-x-");\n' > "$T/pass_node/bin/tests/a.test.mjs"
+run_case pass_node 0 "OK"
+
+mk pass_node_nested
+mkdir -p "$T/pass_node_nested/bin/stats"
+printf 'import { tmpDir } from "../tests/_tmp.mjs";\nconst d = tmpDir("fd-x-");\n' > "$T/pass_node_nested/bin/stats/a.test.mjs"
+run_case pass_node_nested 0 "OK"
+
+mk fail_node
+printf 'import { mkdtempSync } from "node:fs";\nconst d = mkdtempSync("/tmp/fd-x-");\n' > "$T/fail_node/bin/tests/b.test.mjs"
+run_case fail_node 1 "b.test.mjs"
+
+mk fail_node_multiline_import
+printf 'import {\n  mkdtempSync,\n  rmSync,\n} from "node:fs";\n' > "$T/fail_node_multiline_import/bin/tests/c.test.mjs"
+run_case fail_node_multiline_import 1 "c.test.mjs"
+
+mk pass_sh
+printf '#!/usr/bin/env bash\nT=$(mktemp -d)\ntrap '"'"'rm -rf "$T"'"'"' EXIT\n' > "$T/pass_sh/scripts/a.test.sh"
+run_case pass_sh 0 "OK"
+
+mk fail_sh
+printf '#!/usr/bin/env bash\nT=$(mktemp -d)\necho hi\n' > "$T/fail_sh/scripts/b.test.sh"
+run_case fail_sh 1 "b.test.sh"
+
+mk fail_sh_trap_not_exit
+printf '#!/usr/bin/env bash\nT=$(mktemp)\ntrap '"'"'echo x'"'"' INT\n' > "$T/fail_sh_trap_not_exit/scripts/c.test.sh"
+run_case fail_sh_trap_not_exit 1 "c.test.sh"
+
+mk pass_no_temp
+printf 'const x = 1;\n' > "$T/pass_no_temp/bin/tests/d.test.mjs"
+printf '#!/usr/bin/env bash\n# mktemp is only mentioned in a comment\n' > "$T/pass_no_temp/scripts/d.test.sh"
+run_case pass_no_temp 0 "OK"
+
+out=$(bash "$LINT" "$T/does-not-exist" 2>&1); rc=$?
+[ "$rc" -eq 2 ] && ok "bad ROOT exits 2" || bad "bad ROOT exit $rc ($out)"
+
+out=$(bash "$LINT" 2>&1); rc=$?
+[ "$rc" -eq 0 ] && ok "lint is clean on the real repo tree" || bad "real tree has offenders: $out"
+
+echo "passed=$PASS failed=$FAIL"
+[ "$FAIL" -eq 0 ]

package/scripts/ci-local/adapters/azure-pipelines.mjs

@@ -0,0 +1,113 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// azure-pipelines.mjs - azure-pipelines.yml -> normalised jobs. pr: triggers, stages/jobs/steps, script/bash steps,
+// a small set of known no-op tasks, $(Var) macros from declared and predefined variables. Templates, deployment jobs,
+// variable groups, container jobs and unknown tasks are deferred-to-ci.
+
+import os from 'node:os';
+import { Unsupported, branchMatches, matchesFilter, jobId, deferred, notApplicable, hostClass, DEPLOY_NAME } from '../lib.mjs';
+import { stepsFromScript, loadDoc, parseSafe, baseJob } from './common.mjs';
+
+export const id = 'azure-pipelines';
+export const DEF_RE = /^azure-pipelines\.ya?ml$/;
+const NOOP_TASKS = /^(NodeTool|UsePythonVersion|GoTool|JavaToolInstaller|UseDotNet|Cache|PublishBuildArtifacts|PublishTestResults|PublishCodeCoverageResults|PublishPipelineArtifact)@/;
+
+function varMap(v) {
+  const m = {}; if (!v) return m;
+  if (Array.isArray(v)) { for (const x of v) { if (x.group) throw new Unsupported('variable group'); if (x.template) throw new Unsupported('variable template'); if (x.name) m[x.name] = String(x.value ?? ''); } } else for (const [k, x] of Object.entries(v)) m[k] = String(x && typeof x === 'object' ? x.value ?? '' : x);
+  return m;
+}
+
+function expandMacros(text, vars) {
+  if (/\$\{\{/.test(text)) throw new Unsupported('compile-time ${{ }} expression');
+  return String(text).replace(/\$\(([A-Za-z0-9_.]+)\)/g, (_, n) => { if (n in vars) return vars[n]; throw new Unsupported(`variable $(${n})`); });
+}
+
+function prOk(doc, a) {
+  const pr = doc.pr;
+  if (pr === 'none' || pr === false) return 'pr: none';
+  if (pr === undefined || pr === null) return '';
+  const br = Array.isArray(pr) ? { include: pr } : (pr.branches || {});
+  if (br.include && !branchMatches(a.baseBranch, [].concat(br.include))) return `pr branches exclude base ${a.baseBranch}`;
+  if (br.exclude && branchMatches(a.baseBranch, [].concat(br.exclude))) return `pr branches exclude base ${a.baseBranch}`;
+  if (pr.paths && a.changed.length) {
+    const inc = pr.paths.include || []; const exc = pr.paths.exclude || [];
+    if (!a.changed.some((f) => (!inc.length || matchesFilter(f, inc)) && !matchesFilter(f, exc.length ? exc : ['\0']))) return 'pr paths select none of the changed files';
+  }
+  return '';
+}
+
+function condOk(cond) {
+  if (cond === undefined) return true;
+  const c = String(cond).replace(/\s+/g, '');
+  if (/^(succeeded\(\)|succeeded\('[^']*'\)|always\(\)|succeededOrFailed\(\))$/.test(c)) return true;
+  if (/^eq\(variables\['Build\.Reason'\],'PullRequest'\)$/.test(c)) return true;
+  if (/^ne\(variables\['Build\.Reason'\],'(Manual|Schedule|IndividualCI|BatchedCI)'\)$/.test(c)) return true;
+  if (/^(eq|ne)\(variables\['Build\.Reason'\],/.test(c)) return false;
+  throw new Unsupported('condition ' + String(cond).slice(0, 60));
+}
+
+function osOf(pool) { const img = String((pool && (pool.vmImage || pool.name)) || '').toLowerCase(); if (/windows/.test(img)) return 'win32'; if (/mac/.test(img)) return 'darwin'; if (/ubuntu|linux/.test(img)) return 'linux'; return ''; }
+const runnable = (o) => (o === 'linux' ? hostClass() !== 'win32' : o === hostClass());
+
+export function plan(a) {
+  const out = []; const warnings = []; const used = [];
+  for (const file of a.defFiles(DEF_RE)) {
+    const doc = loadDoc(a, file, parseSafe);
+    if (doc === undefined) { out.push(deferred(jobId('azure', 'pipeline'), 'azure-pipelines', file, 'pipeline YAML unreadable')); continue; }
+    if (!doc || typeof doc !== 'object') continue;
+    used.push(file);
+    const why = prOk(doc, a);
+    if (why) { out.push(notApplicable(jobId('azure', 'pipeline'), 'azure-pipelines', file, why)); continue; }
+    let gvars;
+    try { gvars = varMap(doc.variables); } catch (e) { out.push(deferred(jobId('azure', 'pipeline'), 'azure-pipelines', file, e.message)); continue; }
+    const jobs = [];
+    if (Array.isArray(doc.stages)) for (const st of doc.stages) for (const j of st.jobs || []) jobs.push({ j, pool: doc.pool, stage: st.stage });
+    else if (Array.isArray(doc.jobs)) for (const j of doc.jobs) jobs.push({ j, pool: doc.pool });
+    else if (Array.isArray(doc.steps)) jobs.push({ j: { job: 'build', steps: doc.steps }, pool: doc.pool });
+    for (const { j, pool, stage } of jobs) {
+      const key = j.job || j.deployment || j.template || 'job';
+      const jid = jobId('azure', stage || '', key); const name = j.displayName || key;
+      const def = (r) => out.push(deferred(jid, 'azure-pipelines', name, r));
+      try {
+        if (j.template) { def('job template'); continue; }
+        if (j.deployment) { def('deployment job'); continue; }
+        if (j.container || j.services) { def('container/service job'); continue; }
+        if (DEPLOY_NAME.test(key)) { def('deploy/publish job'); continue; }
+        if (!condOk(j.condition)) { out.push(notApplicable(jid, 'azure-pipelines', name, 'condition is false for pull requests')); continue; }
+        const jvars = { ...gvars, ...varMap(j.variables) };
+        const p = j.pool || pool; const o = osOf(p);
+        if (!o) { def('unknown agent pool'); continue; }
+        if (!runnable(o)) { def(`${o} agent (host is ${hostClass()})`); continue; }
+        const pre = { 'Build.SourcesDirectory': a.repo, 'Build.Repository.LocalPath': a.repo, 'Build.SourceVersion': a.headSha, 'Build.SourceBranch': `refs/heads/${a.headBranch || ''}`, 'Build.SourceBranchName': a.headBranch || '', 'System.PullRequest.TargetBranch': a.baseBranch, 'System.PullRequest.SourceBranch': a.headBranch || '', 'Build.Reason': 'PullRequest', 'Agent.OS': { linux: 'Linux', darwin: 'Darwin', win32: 'Windows_NT' }[hostClass()], 'Agent.TempDirectory': os.tmpdir(), 'Pipeline.Workspace': a.repo, 'Build.ArtifactStagingDirectory': os.tmpdir() };
+        const vars = { ...pre, ...jvars };
+        let combos = [{}]; let tag; let variants = 0;
+        const mx = j.strategy && j.strategy.matrix;
+        if (mx && typeof mx === 'object') { const ks = Object.keys(mx); combos = ks.map((k) => ({ __n: k, ...mx[k] })); variants = combos.length - 1; tag = ks[0]; }
+        const env = {}; for (const [k, v] of Object.entries(combos[0])) if (k !== '__n') { env[k] = String(v); vars[k] = String(v); }
+        const steps = []; let defer = '';
+        for (const s of j.steps || []) {
+          if (s.condition !== undefined && !condOk(s.condition)) continue;
+          if (s.template || s.download || s.getPackage) { defer = defer || 'step template/download'; break; }
+          if (s.checkout !== undefined) continue;
+          if (s.task) {
+            if (NOOP_TASKS.test(s.task)) continue;
+            if (/^Npm@1$/.test(s.task) && s.inputs && ['ci', 'install'].includes(s.inputs.command || 'install')) { steps.push({ name: s.displayName || 'npm ' + (s.inputs.command || 'install'), command: 'npm ' + (s.inputs.command || 'install'), cwd: '.', env: {}, kind: 'install' }); continue; }
+            defer = defer || `unknown task ${s.task}`; break;
+          }
+          const body = s.script ?? s.bash;
+          if (body === undefined) { defer = defer || (s.pwsh || s.powershell ? 'PowerShell step' : 'unsupported step'); break; }
+          const sh = s.bash !== undefined ? 'bash' : undefined;
+          const r = stepsFromScript(expandMacros(body, vars), { name: s.displayName || 'script', cwd: s.workingDirectory ? expandMacros(s.workingDirectory, vars) : '.', env: Object.fromEntries(Object.entries(s.env || {}).map(([k, v]) => [k, expandMacros(v, vars)])), shell: sh, repo: a.repo, continue_on_error: s.continueOnError === true });
+          if (r.defer) { defer = defer || r.defer; break; }
+          steps.push(...r.steps);
+        }
+        if (defer) { def(defer); continue; }
+        out.push(baseJob({ id: jid, source: 'azure-pipelines', name, env: { ...env, BUILD_SOURCESDIRECTORY: a.repo }, steps, needs: [].concat(j.dependsOn || []).map((d) => jobId('azure', stage || '', d)), matrix: tag, timeout_s: j.timeoutInMinutes ? Number(j.timeoutInMinutes) * 60 : undefined }));
+        if (variants) out.push(deferred(jobId(jid, 'variants'), 'azure-pipelines', name, `${variants} matrix variant(s) not run locally`));
+      } catch (e) { if (e instanceof Unsupported) { def(`unsupported construct: ${e.message}`); continue; } throw e; }
+    }
+  }
+  return { jobs: out, warnings, used };
+}

package/scripts/ci-local/adapters/bitbucket.mjs

@@ -0,0 +1,64 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// bitbucket.mjs - bitbucket-pipelines.yml -> normalised jobs. Pull-request (else default) pipeline, step/parallel/stage
+// items, condition.changesets path filters, definition services on host networking. Pipes, deployments, manual
+// triggers, OIDC and credential-like variables are deferred-to-ci.
+
+import { Unsupported, branchMatches, matchesFilter, jobId, deferred, notApplicable, secretLikeVar, hostClass, DEPLOY_NAME } from '../lib.mjs';
+import { stepsFromScript, loadDoc, parseSafe, baseJob, globList } from './common.mjs';
+
+export const id = 'bitbucket';
+export const DEF_RE = /^bitbucket-pipelines\.ya?ml$/;
+
+function flatten(items, parallel = false, out = []) {
+  for (const it of items || []) {
+    if (it.step) out.push({ step: it.step, parallel });
+    else if (it.parallel) flatten(Array.isArray(it.parallel) ? it.parallel : it.parallel.steps, true, out);
+    else if (it.stage) flatten(it.stage.steps, parallel, out);
+  }
+  return out;
+}
+
+export function plan(a) {
+  const out = []; const warnings = []; const used = [];
+  for (const file of a.defFiles(DEF_RE)) {
+    const doc = loadDoc(a, file, parseSafe);
+    if (doc === undefined) { out.push(deferred(jobId('bitbucket', 'pipeline'), 'bitbucket', file, 'pipeline YAML unreadable')); continue; }
+    if (!doc || !doc.pipelines) continue;
+    used.push(file);
+    let items = null; let which = 'default';
+    const pr = doc.pipelines['pull-requests'];
+    if (pr) for (const [pat, v] of Object.entries(pr)) if (branchMatches(a.headBranch || '', [pat])) { items = v; which = `pull-requests:${pat}`; break; }
+    if (!items && Array.isArray(doc.pipelines.default)) items = doc.pipelines.default;
+    if (!items) { out.push(notApplicable(jobId('bitbucket', 'pipeline'), 'bitbucket', file, 'no pull-request or default pipeline matches this branch')); continue; }
+    const steps = flatten(items); let prev = []; let prevIds = [];
+    steps.forEach((entry, idx) => {
+      const s = entry.step; const name = s.name || `step-${idx + 1}`; const jid = jobId('bitbucket', which, String(idx + 1), name);
+      const def = (r) => out.push(deferred(jid, 'bitbucket', name, r));
+      const needs = entry.parallel ? prev : prevIds;
+      const next = () => { if (!entry.parallel) { prevIds = [jid]; prev = [jid]; } else prev = prev.concat([jid]); };
+      try {
+        if (s.trigger === 'manual') { def('manual trigger'); next(); return; }
+        if (s.deployment || DEPLOY_NAME.test(name)) { def('deployment step'); next(); return; }
+        if (s.oidc) { def('OIDC token'); next(); return; }
+        if (s['runs-on']) { def('self-hosted runner'); next(); return; }
+        const inc = s.condition && s.condition.changesets && globList(s.condition.changesets.includePaths);
+        if (inc && inc.length && a.changed.length && !a.changed.some((f) => matchesFilter(f, inc))) { out.push(notApplicable(jid, 'bitbucket', name, 'condition.changesets selects none of the changed files')); next(); return; }
+        const script = s.script || [];
+        if (script.some((l) => typeof l !== 'string')) { def('script uses a pipe'); next(); return; }
+        const svcNames = (s.services || []).filter((x) => x !== 'docker');
+        const services = svcNames.map((n) => { const d = doc.definitions && doc.definitions.services && doc.definitions.services[n]; if (!d || !d.image) throw new Unsupported(`service ${n}`); return { name: n, image: typeof d.image === 'string' ? d.image : d.image.name, env: d.variables || {}, ports: [], options: '', host_network: true }; });
+        if (services.length && hostClass() !== 'linux') { def('service containers need host networking (Linux only)'); next(); return; }
+        const sv = secretLikeVar(script.join('\n'));
+        if (sv) { def(`references credential-like variable $${sv}`); next(); return; }
+        const r = stepsFromScript(script.join('\n'), { name, cwd: '.', env: {}, repo: a.repo });
+        if (r.defer) { def(r.defer); next(); return; }
+        const env = { BITBUCKET_COMMIT: a.headSha, BITBUCKET_BRANCH: a.headBranch || '', BITBUCKET_PR_DESTINATION_BRANCH: a.baseBranch, BITBUCKET_CLONE_DIR: a.repo };
+        out.push(baseJob({ id: jid, source: 'bitbucket', name, env, steps: r.steps, services, needs, timeout_s: s['max-time'] ? Number(s['max-time']) * 60 : undefined, warnings: s.image ? [`image ${typeof s.image === 'string' ? s.image : s.image.name} ignored; running with the host toolchain`] : [] }));
+        next();
+      } catch (e) { if (e instanceof Unsupported) { def(`unsupported construct: ${e.message}`); next(); return; } throw e; }
+    });
+  }
+  return { jobs: out, warnings, used };
+}