forgedock 1.40.0 → 1.42.0

package/pool/image/warm-refresh.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Refreshes a warm sandbox's checkout to the lane's base ref (#4912): an incremental fetch into the existing clone, then
+# a hard reset, so installed dependencies and ignored files stay. Usage: warm-refresh.sh [<ref>] (run in the checkout).
+set -euo pipefail
+ref="${1:-}"
+if [ -n "$ref" ]; then
+  git fetch --quiet origin "$ref"
+  git checkout --quiet --force -B "$ref" FETCH_HEAD
+else
+  git fetch --quiet origin HEAD
+fi
+git reset --quiet --hard FETCH_HEAD

package/scripts/conformance-calibrate.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Conformance calibration: scores labelled gate verdicts (and an optional replay corpus) per check kind and prints
+ * precision, recall and false-block rate, with the mode each kind has earned: enforce only at ~0 false blocks.
+ *
+ *   node scripts/conformance-calibrate.mjs --labels <labels.json> [--replay <corpus.json>] [--events <run-log>] [--min-blocks N] [--max-false-rate R] [--json]
+ *
+ * A case is {id, kind, label} with label true-block | false-block | missed | true-pass, or {id, kind, expected_block, blocked}
+ * (the replay-bench shape). A file is `{cases: [...]}` or a bare array. `kind` is any failure code; none is built in.
+ * `--events` reads run-log events (JSONL, a JSON array or `{events}`) and adds the mutation-check metrics (#4929).
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+export const LABELS = Object.freeze(["true-block", "false-block", "missed", "true-pass"]);
+export const DEFAULT_MIN_BLOCKS = 3;
+export const DEFAULT_MAX_FALSE_RATE = 0;
+
+/** The label of a case, from `label` or derived from `expected_block` and `blocked`; null when neither is usable. */
+export function labelOf(c) {
+  if (LABELS.includes(c?.label)) return c.label;
+  if (typeof c?.expected_block !== "boolean" || typeof c?.blocked !== "boolean") return null;
+  return c.blocked ? (c.expected_block ? "true-block" : "false-block") : c.expected_block ? "missed" : "true-pass";
+}
+
+export function casesOf(doc) {
+  return (Array.isArray(doc) ? doc : doc?.cases ?? []).filter((c) => c && typeof c.kind === "string" && c.kind && labelOf(c));
+}
+
+/**
+ * Per-kind counts and rates. precision = TP/(TP+FP), recall = TP/(TP+FN), falseBlockRate = FP/(TP+FP) (blocks that were wrong);
+ * a rate is null when its denominator is 0. `mode` is enforce only with at least minBlocks blocks and a false-block rate <= maxFalseRate.
+ */
+export function scoreKinds(cases, { minBlocks = DEFAULT_MIN_BLOCKS, maxFalseRate = DEFAULT_MAX_FALSE_RATE } = {}) {
+  const by = {};
+  for (const c of cases ?? []) {
+    const t = (by[c.kind] ??= { kind: c.kind, tp: 0, fp: 0, fn: 0, tn: 0 });
+    const l = labelOf(c);
+    if (l === "true-block") t.tp++; else if (l === "false-block") t.fp++; else if (l === "missed") t.fn++; else if (l === "true-pass") t.tn++;
+  }
+  const ratio = (n, d) => (d ? n / d : null);
+  return Object.values(by).sort((a, b) => a.kind.localeCompare(b.kind)).map((t) => {
+    const blocks = t.tp + t.fp, falseBlockRate = ratio(t.fp, blocks);
+    const mode = blocks >= minBlocks && falseBlockRate !== null && falseBlockRate <= maxFalseRate ? "enforce" : "shadow";
+    return { ...t, blocks, precision: ratio(t.tp, blocks), recall: ratio(t.tp, t.tp + t.fn), falseBlockRate, mode };
+  });
+}
+
+export const MUTATION_EVENT = "REQUIREMENT_MUTATION_SURVIVED";
+export const MUTATION_KIND = "conformance.mutation_survived";
+
+/** Events from a run-log file: JSONL text, a JSON array or `{events}`; unparseable lines are dropped. */
+export function eventsOf(text) {
+  const t = String(text ?? "").trim();
+  if (!t) return [];
+  try {
+    const doc = JSON.parse(t);
+    return (Array.isArray(doc) ? doc : doc?.events ?? (doc?.event ? [doc] : [])).filter((e) => e && typeof e === "object");
+  } catch { /* JSONL */ }
+  return t.split("\n").flatMap((l) => { try { const e = JSON.parse(l); return e && typeof e === "object" ? [e] : []; } catch { return []; } });
+}
+
+/**
+ * Mutation-check metrics for engine.conformance_mutation promotion. survivedShare = survived ids / checked requirements over the
+ * REQUIREMENT_MUTATION_SURVIVED events (an event with no ids is a clean check); falseSurvivedRate = false-block / (true-block + false-block)
+ * over labelled cases of kind conformance.mutation_survived (a survived verdict on a test that was real). A rate is null with no denominator.
+ */
+export function mutationStats(events, cases) {
+  const evs = (events ?? []).filter((e) => e?.event === MUTATION_EVENT);
+  let checked = 0, survived = 0, skippedRuns = 0;
+  for (const e of evs) {
+    checked += Number(e.checked) || 0;
+    survived += Array.isArray(e.ids) ? e.ids.length : 0;
+    if (e.skipped) skippedRuns++;
+  }
+  let falseSurvived = 0, labelledSurvived = 0;
+  for (const c of cases ?? []) {
+    if (c.kind !== MUTATION_KIND) continue;
+    const l = labelOf(c);
+    if (l === "false-block") { falseSurvived++; labelledSurvived++; } else if (l === "true-block") labelledSurvived++;
+  }
+  const ratio = (n, d) => (d ? n / d : null);
+  return { events: evs.length, checked, survived, survivedShare: ratio(survived, checked), skippedRuns, falseSurvived, labelledSurvived, falseSurvivedRate: ratio(falseSurvived, labelledSurvived) };
+}
+
+const pct = (x) => (x === null ? "n/a" : `${Math.round(x * 1000) / 10}%`);
+
+export function formatKindReport(rows) {
+  const head = ["kind", "blocks", "precision", "recall", "false-block", "mode"];
+  const body = rows.map((r) => [r.kind, String(r.blocks), pct(r.precision), pct(r.recall), `${r.fp}/${r.blocks} (${pct(r.falseBlockRate)})`, r.mode]);
+  const w = head.map((h, i) => Math.max(h.length, ...body.map((b) => b[i].length)));
+  const line = (cells) => cells.map((c, i) => c.padEnd(w[i])).join("  ").trimEnd();
+  const enforce = rows.filter((r) => r.mode === "enforce").map((r) => `${r.kind}=enforce`);
+  return [line(head), ...body.map(line), "", enforce.length ? `engine.conformance_kinds: "${enforce.join(", ")}"` : "engine.conformance_kinds: (none earned enforcement)"].join("\n");
+}
+
+export function formatMutationReport(m) {
+  return ["mutation check (engine.conformance_mutation)",
+    `survived-mutation share: ${m.survived}/${m.checked} (${pct(m.survivedShare)}) over ${m.events} event(s), ${m.skippedRuns} skipped`,
+    `false survived: ${m.falseSurvived}/${m.labelledSurvived} (${pct(m.falseSurvivedRate)}) labelled ${MUTATION_KIND} case(s)`].join("\n");
+}
+
+export function parseCalibrateArgs(argv) {
+  const o = { labels: null, replay: null, events: null, minBlocks: DEFAULT_MIN_BLOCKS, maxFalseRate: DEFAULT_MAX_FALSE_RATE, json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--labels") o.labels = argv[++i];
+    else if (a === "--replay") o.replay = argv[++i];
+    else if (a === "--events") o.events = argv[++i];
+    else if (a === "--min-blocks") o.minBlocks = Number(argv[++i]);
+    else if (a === "--max-false-rate") o.maxFalseRate = Number(argv[++i]);
+    else if (a === "--json") o.json = true;
+    else throw new Error(`unknown argument ${a}`);
+  }
+  if (!o.labels && !o.replay) throw new Error("usage: conformance-calibrate.mjs --labels <labels.json> [--replay <corpus.json>] [--events <run-log>] [--min-blocks N] [--max-false-rate R] [--json]");
+  return o;
+}
+
+export function run(argv, read = (p) => JSON.parse(readFileSync(p, "utf8")), readText = (p) => readFileSync(p, "utf8")) {
+  const o = parseCalibrateArgs(argv);
+  const cases = [o.labels, o.replay].filter(Boolean).flatMap((p) => casesOf(read(p)));
+  const rows = scoreKinds(cases, o);
+  const mutation = o.events ? mutationStats(eventsOf(readText(o.events)), cases) : null;
+  if (o.json) return JSON.stringify({ cases: cases.length, kinds: rows, ...(mutation ? { mutation } : {}) }, null, 2);
+  return `${cases.length} labelled case(s)\n${formatKindReport(rows)}${mutation ? `\n\n${formatMutationReport(mutation)}` : ""}`;
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  try { console.log(run(process.argv.slice(2))); } catch (e) { console.error(e.message); process.exit(2); }
+}

package/scripts/file-deferred-followups.sh

@@ -5,7 +5,7 @@
 #
 # The builder decides fold-vs-defer (judgment, build.md B2.0); this script does the mechanics for the items
 # that stay deferred: trusted lookup (claim marker <!-- FORGE:DEFERRED_ISSUE: #M --> on the parent, then a state-all search) of a follow-up carrying
-# <!-- FORGE:DEFERRED_FROM: #N -->, append the missing items (exact path match; a closed one is reopened), or create ONE issue
+# <!-- FORGE:DEFERRED_FROM: #N -->, append the missing items (exact path match; a closed one is reopened only if completed, not resolved by a person, and given new items), or create ONE issue
 # with a checklist, claim it on the parent and re-check once for a concurrent lower-numbered duplicate.
 # Items are grouped by class (engineering | post-deploy | external | ops, #4664): one follow-up per class per parent, each
 # labelled `followup:<class>`, carrying `<!-- FORGE:DEFERRED_CLASS: <class> -->` (absent = engineering, for older issues) and the
@@ -142,14 +142,22 @@ search_nums() {
   | jq -r --arg assoc "$TRUSTED_ASSOC" --arg logins "$TRUSTED_LOGINS" --arg m "$MARKER" "$JQ_PRE"'
       [.items[] | select(trusted) | select((.body // "") | contains($m)) | .number] | sort | .[]' 2>/dev/null
 }
-verify_num() { # number -> `number<TAB>state` when a trusted, non-PR issue of class $CLS carries the marker; empty when not (a 404 is "not it")
+verify_num() { # number -> `number<TAB>state` when a trusted, non-PR issue of class $CLS carries the marker (a closed one only if completed and not resolved by a person); empty when not (a 404 is "not it")
   local out rc
   out=$(gh api "repos/${REPO}/issues/$1" 2>"$TMP/verr"); rc=$?
   if [ "$rc" -ne 0 ]; then grep -qE '404|Not Found|410' "$TMP/verr" 2>/dev/null && return 0; return 1; fi
-  printf '%s' "$out" | jq -r --arg assoc "$TRUSTED_ASSOC" --arg logins "$TRUSTED_LOGINS" --arg m "$MARKER" --arg cls "$CLS" "$JQ_PRE"'
+  out=$(printf '%s' "$out" | jq -r --arg assoc "$TRUSTED_ASSOC" --arg logins "$TRUSTED_LOGINS" --arg m "$MARKER" --arg cls "$CLS" "$JQ_PRE"'
       select(.pull_request == null) | select(trusted) | select((.body // "") | contains($m))
       | select((((.body // "") | capture("FORGE:DEFERRED_CLASS: (?<c>[a-z-]+)") | .c) // "engineering") == $cls)
-      | "\(.number)\t\(.state)"' 2>/dev/null
+      | select(.state != "closed" or .state_reason == "completed")
+      | "\(.number)\t\(.state)"' 2>/dev/null) || return 1
+  # #4924: a closed tracker was resolved on purpose when a person had the last word (fold, supersede, invalid): not reusable.
+  case "$out" in *$'\t'closed)
+    local last
+    last=$(gh api "repos/${REPO}/issues/$1/comments?per_page=100" 2>/dev/null | jq -r 'if type == "array" and length > 0 then (last | .user.type // "") else "" end' 2>/dev/null) || return 1
+    [ -z "$last" ] || [ "$last" = "Bot" ] || out="" ;;
+  esac
+  printf '%s' "$out"
 }
 CANON=""; CSTATE=""
 pick_verified() { # numbers... ; sets CANON/CSTATE from the first verified one; non-zero only when a fetch failed
@@ -323,10 +331,15 @@ append_items() { # number state ; non-zero = failure
     else
       gh issue edit "$num" -R "$REPO" --body-file "$TMP/newbody" >/dev/null 2>&1 || return 1
     fi
-  fi
-  if [ "$state" = "closed" ]; then
-    if [ -n "${DRY_RUN:-}" ]; then echo "DRY_RUN: gh issue reopen $num" >&2
-    else gh issue reopen "$num" -R "$REPO" >/dev/null 2>&1 || return 1; fi
+    # #4924: reopen only for new items, and say why.
+    if [ "$state" = "closed" ]; then
+      if [ -n "${DRY_RUN:-}" ]; then echo "DRY_RUN: gh issue reopen $num" >&2
+      else
+        gh issue reopen "$num" -R "$REPO" >/dev/null 2>&1 || return 1
+        gh issue comment "$num" -R "$REPO" --body "$(printf '<!-- FORGE:FOLLOWUP_REOPENED -->\nReopened by the run of #%s%s: it deferred new items not yet tracked here:\n\n%s' "$PARENT" "${FORGE_RUN_ID:+ (run \`$FORGE_RUN_ID\`)}" "$(cat "$TMP/add")")" >/dev/null 2>&1 \
+          || echo "file-deferred-followups: warning: could not post reopen comment on #${num}" >&2
+      fi
+    fi
   fi
   return 0
 }

package/scripts/file-deferred-followups.test.sh

@@ -29,6 +29,7 @@ if [ "$1" = api ]; then
   case "$*" in "api repos/o/r/milestones"*) cat "$T_DIR/milestones.json"; exit 0 ;; esac
   case "$*" in "api repos/o/r/issues/10 --jq"*) cat "$T_DIR/parent.milestone"; exit 0 ;; esac
   case "$*" in *--jq*) cat "$ISSUE_BODY"; exit 0 ;; esac
+  case "$2" in repos/o/r/issues/*/comments*) c="${2#repos/o/r/issues/}"; c="$T_DIR/comments.${c%%/*}.json"; if [ -f "$c" ]; then cat "$c"; else echo '[]'; fi; exit 0 ;; esac
   n="${2##*/}"; [ -f "$T_DIR/issue.$n.json" ] && { cat "$T_DIR/issue.$n.json"; exit 0; }
   echo "HTTP 404: Not Found" >&2; exit 1
 fi
@@ -40,11 +41,12 @@ PASS=0; FAIL=0
 ok() { PASS=$((PASS+1)); echo "PASS: $1"; }
 bad() { FAIL=$((FAIL+1)); echo "FAIL: $1"; }
 check() { if eval "$2"; then ok "$1"; else bad "$1"; fi; }
-reset() { : > "$GH_LOG"; rm -f "$ISSUE_BODY.edited" "$T"/issue.*.json "$T/create.n"; unset LOOKUP_FAIL CREATE_FAIL EDIT_FAIL CLAIM_FAIL COMMENT_FAIL REOPEN_FAIL CLOSE_FAIL DRY_RUN FORGE_FOLLOWUP_MILESTONE FORGE_FOLLOWUPS_DEFAULT_MILESTONE FORGE_EXTERNAL_PREREQ
+reset() { : > "$GH_LOG"; rm -f "$ISSUE_BODY.edited" "$T"/issue.*.json "$T"/comments.*.json "$T/create.n"; unset LOOKUP_FAIL CREATE_FAIL EDIT_FAIL CLAIM_FAIL COMMENT_FAIL REOPEN_FAIL CLOSE_FAIL DRY_RUN FORGE_FOLLOWUP_MILESTONE FORGE_FOLLOWUPS_DEFAULT_MILESTONE FORGE_EXTERNAL_PREREQ
   echo '[]' > "$T/milestones.json"; : > "$T/parent.milestone"
   echo '{"items":[]}' > "$SEARCH_JSON"; echo '[]' > "$COMMENTS_JSON"; }
-# issue_json NUMBER STATE ASSOCIATION [PARENT]: REST view of a follow-up carrying the DEFERRED_FROM marker
-issue_json() { printf '{"number":%s,"state":"%s","author_association":"%s","user":{"type":"User"},"body":"<!-- FORGE:DEFERRED_FROM: #%s -->"}\n' "$1" "$2" "$3" "${4:-10}" > "$T/issue.$1.json"; }
+# issue_json NUMBER STATE ASSOCIATION [PARENT] [STATE_REASON]: REST view of a follow-up carrying the DEFERRED_FROM marker
+# (no sed -i: BSD sed on macOS reads the script as the backup suffix, so state_reason was never written there)
+issue_json() { printf '{"number":%s,"state":"%s",%s"author_association":"%s","user":{"type":"User"},"body":"<!-- FORGE:DEFERRED_FROM: #%s -->"}\n' "$1" "$2" "${5:+\"state_reason\":\"$5\",}" "$3" "${4:-10}" > "$T/issue.$1.json"; }
 # claim_json ASSOCIATION NUMBER...: parent comments carrying claim markers
 claim_json() { local a="$1" out="" n; shift; for n in "$@"; do out="${out:+$out,}{\"author_association\":\"$a\",\"user\":{\"type\":\"User\"},\"body\":\"<!-- FORGE:DEFERRED_ISSUE: #$n -->\"}"; done; echo "[$out]" > "$COMMENTS_JSON"; }
 printf 'a/x.sh\twhy a\t\nb/y.sh\twhy b\tknown-flaw\nc/z.sh\twhy c\t\n' > "$T/items.tsv"
@@ -128,16 +130,35 @@ check "index-lag: search never needed" "! grep -q search/issues '$GH_LOG'"
 
 # 10. e2: closed follow-up (found only by a state-all search) is reused and reopened
 reset
-printf 'x\n' > "$ISSUE_BODY"; issue_json 77 closed OWNER
+printf 'x\n' > "$ISSUE_BODY"; issue_json 77 closed OWNER 10 completed
 echo '{"items":[{"number":77,"author_association":"OWNER","user":{"type":"User"},"body":"<!-- FORGE:DEFERRED_FROM: #10 -->"}]}' > "$SEARCH_JSON"
 OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/items.tsv"); RC=$?
 check "closed: reused, reopened, no create" "[ $RC -eq 0 ] && grep -q '^issue reopen 77' '$GH_LOG' && ! grep -q '^issue create' '$GH_LOG'"
 check "closed: search query covers all states" "grep -q 'is:issue' '$GH_LOG' && ! grep 'api -X' '$GH_LOG' | grep -q 'is:open'"
 reset; export REOPEN_FAIL=1
-printf 'x\n' > "$ISSUE_BODY"; issue_json 77 closed OWNER; claim_json OWNER 77
+printf 'x\n' > "$ISSUE_BODY"; issue_json 77 closed OWNER 10 completed; claim_json OWNER 77
 bash "$S" --parent 10 --repo o/r --items "$T/items.tsv" >/dev/null; RC=$?
 check "closed: reopen failure is rc 4" "[ $RC -eq 4 ]"
 
+# 10b. #4924: closed trackers are reopened only when completed, unresolved by a person, and given new items
+reset
+printf 'x\n' > "$ISSUE_BODY"; issue_json 77 closed OWNER 10 not_planned; claim_json OWNER 77
+bash "$S" --parent 10 --repo o/r --items "$T/items.tsv" >/dev/null; RC=$?
+check "not planned: stays closed, fresh tracker created" "[ $RC -eq 0 ] && ! grep -q '^issue reopen' '$GH_LOG' && ! grep -q '^issue edit 77' '$GH_LOG' && grep -q '^issue create' '$GH_LOG'"
+reset
+printf 'x\n' > "$ISSUE_BODY"; issue_json 77 closed OWNER 10 completed; claim_json OWNER 77
+echo '[{"user":{"type":"User"},"body":"folded into #5"}]' > "$T/comments.77.json"
+bash "$S" --parent 10 --repo o/r --items "$T/items.tsv" >/dev/null; RC=$?
+check "folded by a person: stays closed, fresh tracker created" "[ $RC -eq 0 ] && ! grep -q '^issue reopen' '$GH_LOG' && grep -q '^issue create' '$GH_LOG'"
+reset
+printf -- '- [ ] `a/x.sh`\n- [ ] `b/y.sh`\n- [ ] `c/z.sh`\n' > "$ISSUE_BODY"; issue_json 77 closed OWNER 10 completed; claim_json OWNER 77
+bash "$S" --parent 10 --repo o/r --items "$T/items.tsv" >/dev/null; RC=$?
+check "completed, nothing new: stays closed, no create" "[ $RC -eq 0 ] && ! grep -q '^issue reopen' '$GH_LOG' && ! grep -q '^issue create' '$GH_LOG'"
+reset
+printf -- '- [ ] `a/x.sh`\n' > "$ISSUE_BODY"; issue_json 77 closed OWNER 10 completed; claim_json OWNER 77
+FORGE_RUN_ID=core_10 bash "$S" --parent 10 --repo o/r --items "$T/items.tsv" >/dev/null; RC=$?
+check "completed, new items: reopened with a comment naming parent, run and items" "[ $RC -eq 0 ] && grep -q '^issue reopen 77' '$GH_LOG' && grep '^issue comment 77' '$GH_LOG' | grep -q 'FORGE:FOLLOWUP_REOPENED' && grep -q 'Reopened by the run of #10 (run .core_10.)' '$GH_LOG' && grep -q 'b/y.sh' '$GH_LOG'"
+
 # 11. create posts the claim marker on the parent
 reset
 OUT=$(bash "$S" --parent 10 --repo o/r --items "$T/items.tsv"); RC=$?
@@ -195,7 +216,7 @@ check "multi-claim: lowest valid (80) wins, missing 70 skipped" "[ $RC -eq 0 ] &
 
 # 17. DRY_RUN: no claim, reopen or close
 reset; export DRY_RUN=1
-printf 'x\n' > "$ISSUE_BODY"; issue_json 77 closed OWNER; claim_json OWNER 77
+printf 'x\n' > "$ISSUE_BODY"; issue_json 77 closed OWNER 10 completed; claim_json OWNER 77
 bash "$S" --parent 10 --repo o/r --items "$T/items.tsv" >/dev/null 2>&1
 check "dry-run: no comment/reopen/close/edit" "! grep -qE '^issue (comment|reopen|close|edit|create)' '$GH_LOG'"