forgedock 1.35.0 → 1.37.0

package/bin/lean/guardgate.test.mjs

@@ -0,0 +1,153 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import test from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { oldRanges, selectGuards, runGuards, commandFor, basePathOf, guardFailures, supersessionComment, supersededIds, loadGuards } from "./guardgate.mjs";
+import { applyAmendments, precheck } from "./conformance.mjs";
+import { tmpDir } from "../tests/_tmp.mjs";
+
+const sh = (cwd, ...a) => execFileSync("git", a, { cwd, encoding: "utf8", env: { ...process.env, GIT_AUTHOR_NAME: "t", GIT_AUTHOR_EMAIL: "t@t", GIT_COMMITTER_NAME: "t", GIT_COMMITTER_EMAIL: "t@t" } });
+const gitIn = (cwd) => async (args) => sh(cwd, ...args);
+const { NODE_TEST_CONTEXT: _ctx, ...CLEAN_ENV } = process.env; // the fixture runs node --test inside a test
+const runCommand = async ({ command, cwd }) => { const r = spawnSync("sh", ["-c", command], { cwd, encoding: "utf8", env: CLEAN_ENV }); return { rc: r.status ?? 1, output: `${r.stdout}${r.stderr}` }; };
+const put = (cwd, p, body) => { mkdirSync(join(cwd, p, ".."), { recursive: true }); writeFileSync(join(cwd, p), body); };
+
+const TEST_SRC = (v) => `import test from "node:test";\nimport assert from "node:assert/strict";\nimport { price } from "./a.mjs";\ntest("price is ${v}", () => assert.equal(price(), ${v}));\n`;
+
+/** A repo whose fix commit (merge_sha) made price() return 2, guarded by src/a.test.mjs; the lane starts from it. */
+function fixture() {
+  const d = tmpDir("guardgate-");
+  sh(d, "init", "-q", "-b", "main");
+  put(d, "src/a.mjs", "export function price() {\n  return 1;\n}\n");
+  sh(d, "add", "-A"); sh(d, "commit", "-qm", "init");
+  put(d, "src/a.mjs", "export function price() {\n  return 2;\n}\n");
+  put(d, "src/a.test.mjs", TEST_SRC(2));
+  sh(d, "add", "-A"); sh(d, "commit", "-qm", "fix: price");
+  const sha = sh(d, "rev-parse", "HEAD").trim();
+  put(d, "src/other.mjs", "export const x = 1;\n");
+  sh(d, "add", "-A"); sh(d, "commit", "-qm", "later");
+  sh(d, "update-ref", "refs/remotes/origin/main", "HEAD");
+  sh(d, "checkout", "-qb", "lane");
+  const guard = { v: 1, issue: 7, pr: 9, merge_sha: sha, tests: [{ path: "src/a.test.mjs", ids: [] }], hunks: [{ file: "src/a.mjs", start: 2, end: 2, symbol: "price" }], why: "price must be 2" };
+  return { d, guard };
+}
+const commit = (d, m) => { sh(d, "add", "-A"); sh(d, "commit", "-qm", m); };
+const files = (d) => sh(d, "diff", "--name-only", "origin/main...HEAD").split("\n").filter(Boolean);
+const gate = async (d, guard, contract = {}) => {
+  const git = gitIn(d);
+  const { selected, mergeBase } = await selectGuards({ guards: [guard], files: files(d), git, base: "origin/main" });
+  const r = selected.length ? await runGuards({ selected, mergeBase, contract, git, runCommand, cwd: d, env: process.env }) : null;
+  return { selected, r };
+};
+
+test("a lane that reverts a guarded fix fails guard_broken even when it also edits the guard's test to pass", async () => {
+  const { d, guard } = fixture();
+  put(d, "src/a.mjs", "export function price() {\n  return 1;\n}\n"); // reverts the fix
+  put(d, "src/a.test.mjs", TEST_SRC(1)); // and weakens the test so the lane's own copy passes
+  commit(d, "revert");
+  assert.equal((await runCommand({ command: "node --test src/a.test.mjs", cwd: d })).rc, 0, "the lane's own edited test passes");
+  const { selected, r } = await gate(d, guard);
+  assert.equal(selected.length, 1);
+  assert.match(selected[0].reason, /src\/a\.mjs/);
+  assert.equal(r.failures.length, 1, JSON.stringify({ runs: r.runs, skipped: r.skipped }));
+  assert.equal(r.failures[0].code, "conformance.guard_broken");
+  assert.equal(r.failures[0].guard, "#7");
+  assert.match(r.failures[0].detail, /price must be 2/);
+  assert.match(r.failures[0].detail, /src\/a\.test\.mjs/);
+  assert.deepEqual(readdirSync(join(d, "src")).filter((f) => f.includes("__guardbase")), [], "base copies are removed");
+  const pc = precheck({ contract: { requirements: [], deliverables: [{ id: "D1", path: "src/a.mjs" }, { id: "D2", path: "src/a.test.mjs" }], validate: [] }, result: {}, changedFiles: files(d), guardFailures: r.failures });
+  assert.deepEqual(pc.failures.filter((f) => f.kind === "guard_broken").map((f) => f.guard), ["#7"]);
+  assert.equal(pc.ok, false);
+});
+
+test("an accepted supersedes amendment passes the precheck and names the superseded guard for the issue comment", async () => {
+  const { d, guard } = fixture();
+  put(d, "src/a.mjs", "export function price() {\n  return 3;\n}\n");
+  commit(d, "change");
+  const { selected, r } = await gate(d, guard);
+  assert.equal(r.failures.length, 1);
+  const frozen = { requirements: [], deliverables: [{ id: "D1", path: "src/a.mjs" }], validate: [] };
+  const a = applyAmendments(frozen, [{ kind: "supersedes", guard: "#7", why: "price is now 3 by product decision" }]);
+  assert.deepEqual(a.problems, []);
+  assert.deepEqual(a.applied, [{ kind: "supersedes", target: "#7", why: "price is now 3 by product decision" }]);
+  const pc = precheck({ contract: a.contract, result: {}, changedFiles: ["src/a.mjs"], guardFailures: r.failures });
+  assert.equal(pc.ok, true, JSON.stringify(pc.failures));
+  const sup = supersededIds(a.contract, selected);
+  assert.deepEqual(sup.map((s) => s.guard), ["#7"]);
+  assert.match(supersessionComment({ guard: "#7", pr: 12, why: sup[0].why }), /#7 was superseded by PR #12: price is now 3/);
+  assert.deepEqual(supersededIds(a.contract, []), [], "only selected guards are retired");
+});
+
+test("a supersedes amendment without a guard id is rejected", () => {
+  const a = applyAmendments({ requirements: [], deliverables: [] }, [{ kind: "supersedes", why: "x" }, { kind: "supersedes", guard: "abc", why: "x" }]);
+  assert.equal(a.problems.length, 2);
+  assert.match(a.problems[0], /needs guard/);
+});
+
+test("a lane touching no guarded hunk selects nothing and runs no git or test", async () => {
+  const { d, guard } = fixture();
+  put(d, "src/other.mjs", "export const x = 2;\n");
+  commit(d, "unrelated");
+  const calls = [];
+  const git = async (a) => { calls.push(a[0]); return gitIn(d)(a); };
+  const r = await selectGuards({ guards: [guard], files: files(d), git, base: "origin/main" });
+  assert.deepEqual(r.selected, []);
+  assert.deepEqual(calls, [], "no git call at all");
+  // same file as the guard but lines far from the hunk, with the guard's commit not the blamed one
+  const big = { ...guard, hunks: [{ file: "src/a.mjs", start: 200, end: 210 }] };
+  assert.deepEqual((await selectGuards({ guards: [big], files: files(d).concat("src/a.mjs"), git: gitIn(d), base: "origin/main" })).selected, []);
+});
+
+test("deleting or editing a guard's test selects it even when no guarded line changed", async () => {
+  const { d, guard } = fixture();
+  sh(d, "rm", "-q", "src/a.test.mjs");
+  commit(d, "drop test");
+  const { selected, r } = await gate(d, guard);
+  assert.equal(selected.length, 1);
+  assert.match(selected[0].reason, /edits or deletes its test/);
+  assert.deepEqual(r.failures, [], "the base test still passes against the unchanged code");
+  assert.equal(r.runs.length, 1);
+});
+
+test("a base test that cannot run in the cap, or has no known runner, is skipped and never blocks", async () => {
+  const { d, guard } = fixture();
+  put(d, "src/a.mjs", "export function price() {\n  return 1;\n}\n");
+  commit(d, "revert");
+  const git = gitIn(d);
+  const { selected, mergeBase } = await selectGuards({ guards: [guard], files: files(d), git, base: "origin/main" });
+  const slow = await runGuards({ selected, mergeBase, contract: {}, git, runCommand: async () => ({ rc: 124, output: "" }), cwd: d, env: {} });
+  assert.deepEqual(slow.failures, []);
+  assert.match(slow.skipped[0], /guard cap/);
+  const none = await runGuards({ selected: [{ guard: { ...guard, tests: [{ path: "src/a.test.rb" }] }, reason: "" }], mergeBase, contract: {}, git, runCommand, cwd: d, env: {} });
+  assert.match(none.skipped[0], /no runner/);
+  assert.equal(existsSync(join(d, basePathOf("src/a.test.mjs"))), false);
+});
+
+test("pytest-style guards run through the contract's own validate command with the path substituted", () => {
+  assert.equal(commandFor("tests/test_a__guardbase.py", { validate: [{ command: "pytest -q tests/test_a.py" }] }), "pytest -q tests/test_a__guardbase.py");
+  assert.equal(commandFor("tests/test_a__guardbase.py", {}), "python -m pytest -q tests/test_a__guardbase.py");
+  assert.equal(commandFor("src/a.test__guardbase.mjs", { validate: [{ command: "node --test src/a.test.mjs -t x" }] }), "node --test src/a.test__guardbase.mjs");
+  assert.equal(commandFor("a.rb", {}), null);
+  assert.equal(basePathOf("src/a.test.mjs"), "src/a.test__guardbase.mjs");
+});
+
+test("oldRanges reads old-side lines of non-test files and skips pure insertions", () => {
+  const diff = "--- a/src/a.mjs\n+++ b/src/a.mjs\n@@ -3,2 +3 @@\n-a\n-b\n+c\n@@ -9,0 +9,2 @@\n+x\n+y\n@@ -20 +19,0 @@\n-z\n--- a/src/a.test.mjs\n+++ b/src/a.test.mjs\n@@ -1 +1 @@\n";
+  assert.deepEqual(oldRanges(diff), { "src/a.mjs": [[3, 4], [20, 20]] });
+});
+
+test("guardFailures keeps only failing runs and loadGuards falls back to a stale index when GitHub is down", async () => {
+  assert.deepEqual(guardFailures([{ issue: 1, rc: 0 }]), []);
+  const root = tmpDir("guardgate-idx-");
+  const fs = await import("node:fs");
+  const { writeIndex } = await import("./guards.mjs");
+  writeIndex("o/r", [{ issue: 3 }], { root });
+  const old = new Date(Date.now() - 48 * 3600000);
+  fs.utimesSync(join(root, "o_r.json"), old, old);
+  const down = await loadGuards({ repo: "o/r", gh: async () => { throw new Error("offline"); }, root });
+  assert.deepEqual(down, [{ issue: 3 }]);
+  assert.deepEqual(await loadGuards({ repo: "o/none", gh: async () => "[]", root }), []);
+});

package/bin/lean/guards.mjs

@@ -0,0 +1,243 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Fix guards (#4692): a merged lane whose frozen contract names a regression/repro test records a guard on its issue as
+ * `<!-- FORGE:GUARD {json} -->`: {v, issue, pr, merge_sha, tests:[{path, ids}], hunks:[{file, start, end, symbol}], why}.
+ * GitHub is the register; `~/.forge/guards/<repo>.json` is a cache rebuilt from those comments. Codebase-agnostic and
+ * deterministic (0 LLM calls): test identity comes from the contract's repro_test and validate commands, never from a
+ * language parser; without per-test ids a guard is file-granular (ids: []). Protected hunks come from the merged diff
+ * against the merge commit's first parent, which is the base for both merge-commit and squash merges.
+ */
+import * as nodeFs from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { isTestPath } from "./enumerating.mjs";
+import { parseContractComment } from "./render.mjs";
+
+export const GUARD_MARKER = "FORGE:GUARD";
+const GUARD_RE = /<!-- FORGE:GUARD (\{[\s\S]*?\}) -->/;
+const PATHISH = /^[\w@.+/-]+\.[A-Za-z0-9]+$/;
+const hasMarker = (b) => GUARD_RE.test(String(b ?? ""));
+
+export const guardsIndexPath = (repo, root = join(homedir(), ".forge", "guards")) => join(root, `${String(repo).replace(/[^A-Za-z0-9._-]/g, "_")}.json`);
+
+/** Test ids a validate/repro command names: `-k expr`, `--test-name-pattern x`, `-t x`, `--grep x`, and `file::name` pytest ids. */
+function idsOf(command, path) {
+  const toks = String(command ?? "").match(/(?:[^\s"']|"[^"]*"|'[^']*')+/g) ?? [];
+  const unq = (t) => t.replace(/^(["'])(.*)\1$/, "$2");
+  const ids = [];
+  toks.forEach((t, i) => {
+    const v = unq(t);
+    if (/^(?:-k|-t|--grep|--test-name-pattern|--testNamePattern)$/.test(v) && toks[i + 1]) ids.push(unq(toks[i + 1]));
+    else if (/^--(?:k|grep|test-name-pattern|testNamePattern)=/.test(v)) ids.push(unq(v.split("=").slice(1).join("=")));
+    else if (v.startsWith(`${path}::`)) ids.push(v.slice(path.length + 2));
+  });
+  return ids;
+}
+
+/** Test files (and ids) from the contract's repro_test and validate commands. [] when the contract names no test. */
+export function guardTests(contract) {
+  const by = new Map();
+  const add = (path, ids) => { const e = by.get(path) ?? new Set(); ids.filter(Boolean).forEach((i) => e.add(i)); by.set(path, e); };
+  const t = contract?.repro_test;
+  const cmds = [];
+  if (t && typeof t === "object") {
+    if (t.path) add(String(t.path), t.id ? [String(t.id)] : []);
+    cmds.push(t.command);
+  }
+  for (const v of contract?.validate ?? []) cmds.push(v?.command);
+  for (const c of cmds) {
+    for (const tok of String(c ?? "").match(/[^\s"']+/g) ?? []) {
+      const p = tok.split("::")[0];
+      if (PATHISH.test(p) && isTestPath(p)) add(p, idsOf(c, p));
+    }
+  }
+  if (t && typeof t === "object" && t.path) add(String(t.path), []);
+  return [...by].map(([path, ids]) => ({ path, ids: [...ids] }));
+}
+
+/** Hunks of a `git diff -U0` text for non-test files: [{file, start, end, symbol}] in post-image lines (deletions anchor at the line after). */
+export function parseHunks(diff) {
+  const out = [];
+  let file = null;
+  for (const line of String(diff ?? "").split("\n")) {
+    if (line.startsWith("+++ ")) { file = line === "+++ /dev/null" ? null : line.replace(/^\+\+\+ b\//, ""); continue; }
+    if (line.startsWith("--- ")) { if (line === "--- /dev/null") file = null; continue; }
+    const m = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@ ?(.*)$/.exec(line);
+    if (!m || !file || isTestPath(file)) continue;
+    const delOnly = m[4] === "0", start = Number(m[3]) + (delOnly ? 1 : 0), len = m[4] === undefined ? 1 : Number(m[4]);
+    out.push({ file, start, end: delOnly ? start : start + len - 1, symbol: m[5].trim().slice(0, 120) || null });
+  }
+  return out;
+}
+
+/** The guard for a merged lane, or {skipped, reason} when its contract names no regression/repro test. */
+export function buildGuard({ issue, title = "", pr = null, mergeSha = null, contract, diff = "" }) {
+  const tests = guardTests(contract);
+  if (!tests.length) {
+    const why = contract?.repro_test === "none" ? `repro_test none (${String(contract.repro_test_reason ?? "").slice(0, 120)})` : "contract names no test file";
+    return { skipped: true, reason: `no guard for #${issue}: ${why}` };
+  }
+  return { guard: { v: 1, issue, pr, merge_sha: mergeSha, tests, hunks: parseHunks(diff), why: String(title).replace(/\s+/g, " ").trim().slice(0, 200) } };
+}
+
+export const renderGuard = (g) => `<!-- ${GUARD_MARKER} ${JSON.stringify(g).replace(/</g, "\\u003c").replace(/>/g, "\\u003e")} -->`;
+export function parseGuard(body) {
+  const m = GUARD_RE.exec(String(body ?? ""));
+  if (!m) return null;
+  try { const g = JSON.parse(m[1]); return g && g.v === 1 && Number.isInteger(g.issue) ? g : null; } catch { return null; }
+}
+
+const json = (s, d) => { try { return JSON.parse(String(s) || "null") ?? d; } catch { return d; } };
+
+/**
+ * Build the guard for one merged issue from GitHub alone (its FORGE:CONTRACT comment, merged PR and merge commit) and post it
+ * once. Idempotent: an issue that already has a FORGE:GUARD comment is left alone. Returns {posted|exists|skipped, ...}.
+ */
+export async function guardIssue({ gh, git, repo, issue, pr = null, post = null, dryRun = false }) {
+  const iss = json(await gh(["issue", "view", String(issue), "-R", repo, "--json", "number,title,comments"]), null);
+  if (!iss) return { skipped: true, reason: `#${issue}: issue not readable` };
+  const bodies = (iss.comments ?? []).map((c) => c?.body ?? "");
+  const existing = bodies.map(parseGuard).find(Boolean);
+  if (existing) return { exists: true, guard: existing };
+  const cb = [...bodies].reverse().find((b) => b.startsWith("<!-- FORGE:CONTRACT -->") && parseContractComment(b));
+  if (!cb) return { skipped: true, reason: `no guard for #${issue}: no frozen FORGE:CONTRACT comment` };
+  const contract = parseContractComment(cb).contract;
+  let prn = pr, sha = null;
+  const view = prn
+    ? json(await gh(["pr", "view", String(prn), "-R", repo, "--json", "number,state,mergeCommit"]), null)
+    : json(await gh(["pr", "list", "-R", repo, "--state", "merged", "--search", `#${issue} in:body`, "--limit", "5", "--json", "number,mergeCommit,body"]), []).find((p) => new RegExp(`(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\\s+#${issue}\\b`, "i").test(p.body ?? "")) ?? null;
+  if (view) { prn = view.number ?? prn; sha = view.mergeCommit?.oid ?? null; }
+  if (!sha) return { skipped: true, reason: `no guard for #${issue}: no merged PR with a merge commit` };
+  let diff = "";
+  const getDiff = async () => String(await git(["diff", "-U0", "--no-color", "--no-renames", `${sha}^1`, sha]));
+  try {
+    try { diff = await getDiff(); } catch { await git(["fetch", "origin", sha]); diff = await getDiff(); } // merge commit not local yet: fetch it by sha
+  } catch (e) {
+    return { skipped: true, reason: `no guard for #${issue}: merge commit ${sha.slice(0, 10)} not available locally (${String(e?.message ?? e).split("\n")[0].slice(0, 100)})` };
+  }
+  const built = buildGuard({ issue, title: iss.title, pr: prn, mergeSha: sha, contract, diff });
+  if (built.skipped) return built;
+  if (!dryRun) await (post ?? ((b) => gh(["issue", "comment", String(issue), "-R", repo, "--body", b])))(renderGuard(built.guard));
+  return { posted: true, guard: built.guard };
+}
+
+/** Guards read from a repo's issue comments (the register of record). */
+export async function collectGuards({ gh, repo, limit = 500 }) {
+  const rows = json(await gh(["issue", "list", "-R", repo, "--state", "all", "--search", `${GUARD_MARKER} in:comments`, "--limit", String(limit), "--json", "number,comments"]), []);
+  const guards = [];
+  for (const r of rows) for (const c of r.comments ?? []) { const g = hasMarker(c?.body) ? parseGuard(c.body) : null; if (g) { guards.push(g); break; } }
+  return guards;
+}
+
+/** Rewrite the local cache from the guards found on GitHub. */
+export function writeIndex(repo, guards, { root, fs = nodeFs } = {}) {
+  const p = guardsIndexPath(repo, root);
+  fs.mkdirSync(dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify({ v: 1, repo, guards }, null, 1));
+  return p;
+}
+export function readIndex(repo, { root, fs = nodeFs } = {}) {
+  try { const j = JSON.parse(fs.readFileSync(guardsIndexPath(repo, root), "utf8")); return Array.isArray(j?.guards) ? j.guards : null; } catch { return null; }
+}
+
+/** Guards covering `path` (a protected hunk file or a guarding test file; a directory prefix matches too). No path: all. */
+export function listGuards(guards, { path = null } = {}) {
+  if (!path) return guards;
+  const p = String(path).replace(/^\.\//, "").replace(/\/$/, "");
+  const hit = (f) => f === p || f.startsWith(`${p}/`);
+  return guards.filter((g) => (g.hunks ?? []).some((h) => hit(h.file)) || (g.tests ?? []).some((t) => hit(t.path)));
+}
+
+const H_ROW = /^H\d+$/;
+const dirOf = (f) => String(f).split("/").slice(0, -1).join("/");
+
+/**
+ * History preserve rows (#4694): at most `cap` `{id:"H<n>", what, source:"guard"}` rows for the guards covering the deliverable
+ * paths. Pure and deterministic: score 3 = a protected hunk file is a deliverable, 2 = a guarding test file is, 1 = either sits
+ * under a deliverable's directory; ties go to the newest issue. The lane's own issue is skipped.
+ */
+export function historyPreserve({ guards, deliverables, issue = null, cap = 5 }) {
+  const paths = [...new Set((deliverables ?? []).map((d) => String(d?.path ?? d ?? "").replace(/^\.\//, "")).filter(Boolean))];
+  if (!paths.length || !Array.isArray(guards) || !guards.length) return [];
+  const dirs = paths.map(dirOf).filter(Boolean);
+  const under = (f) => dirs.some((d) => f.startsWith(`${d}/`));
+  const scored = [];
+  for (const g of guards) {
+    if (!g || g.issue == null || String(g.issue) === String(issue)) continue;
+    const hunks = (g.hunks ?? []).map((h) => String(h.file)), tests = (g.tests ?? []).map((t) => String(t.path));
+    const score = hunks.some((f) => paths.includes(f)) ? 3 : tests.some((f) => paths.includes(f)) ? 2 : [...hunks, ...tests].some(under) ? 1 : 0;
+    if (score) scored.push({ g, score });
+  }
+  scored.sort((a, b) => b.score - a.score || Number(b.g.issue) - Number(a.g.issue) || (Number(a.g.pr) || 0) - (Number(b.g.pr) || 0));
+  const seen = new Set();
+  return scored.filter(({ g }) => !seen.has(String(g.issue)) && seen.add(String(g.issue))).slice(0, cap).map(({ g }, i) => ({
+    id: `H${i + 1}`,
+    what: `${String(g.why ?? "").replace(/\s+/g, " ").trim().slice(0, 160) || "guarded fix"} (#${g.issue}${g.pr ? `, PR #${g.pr}` : ""})`,
+    source: "guard",
+  }));
+}
+
+/** The contract with H-rows from the local guards index appended to preserve; the same object when nothing applies. Never throws. */
+export function withHistoryRows(contract, { repo, issue, root, fs = nodeFs } = {}) {
+  try {
+    const guards = readIndex(repo, { root, fs });
+    if (!guards?.length) return contract;
+    const rows = historyPreserve({ guards, deliverables: contract?.deliverables, issue });
+    if (!rows.length) return contract;
+    return { ...contract, preserve: [...(contract.preserve ?? []).filter((p) => !(H_ROW.test(p?.id) && p?.source === "guard")), ...rows] };
+  } catch { return contract; }
+}
+
+/**
+ * Backfill guards for issues closed since `since` (ISO date) that ran through the lean lane (a FORGE:CONTRACT comment and a
+ * merged PR). Lanes without a test yield no guard; the reason is reported in `logs`. Idempotent.
+ */
+export async function backfill({ gh, git, repo, since, dryRun = false, log = () => {} }) {
+  const rows = json(await gh(["issue", "list", "-R", repo, "--state", "closed", "--search", `closed:>=${since}`, "--limit", "500", "--json", "number"]), []);
+  const res = { posted: [], exists: [], skipped: [] };
+  for (const { number } of rows) {
+    let r;
+    try { r = await guardIssue({ gh, git, repo, issue: number, dryRun }); } catch (e) { r = { skipped: true, reason: `#${number}: ${String(e?.message ?? e).split("\n")[0].slice(0, 160)}` }; }
+    if (r.posted) res.posted.push(number); else if (r.exists) res.exists.push(number);
+    else { res.skipped.push({ issue: number, reason: r.reason }); log(r.reason); }
+  }
+  return res;
+}
+
+/** Lane hook: after a merge, fetch the base so the merge commit is local, then guard the issue. Best effort: never throws. */
+export async function guardAfterMerge({ io, repo, issue, pr, cwd, base = null, root }) {
+  try {
+    const branch = base ? String(base).replace(/^(?:refs\/remotes\/)?origin\//, "") : null; // lean.mjs passes `origin/<lane>`
+    if (branch) { try { await io.git(["fetch", "origin", branch], { cwd }); } catch { /* offline: use the local ref */ } }
+    const r = await guardIssue({ gh: (a) => io.gh(a), git: (a) => io.git(a, { cwd }), repo, issue, pr });
+    if (r.posted) { // #4694: keep the local cache current so the next lane's freeze sees this guard; only extend an existing index
+      try { const cur = readIndex(repo, { root }); if (cur) writeIndex(repo, [...cur.filter((g) => g.issue !== r.guard.issue), r.guard], { root }); } catch { /* cache only */ }
+    }
+    return r;
+  } catch (e) { return { skipped: true, reason: `guard failed: ${String(e?.message ?? e).split("\n")[0].slice(0, 160)}` }; }
+}
+
+/** `forgedock guards list [--path p] [--json] | backfill --since <date> [--dry-run]`. Returns the exit code. */
+export async function guardsCli(argv, { gh, git, repo, print = console.log, root, fs = nodeFs } = {}) {
+  const sub = argv[0];
+  const flag = (n) => { const i = argv.indexOf(n); return i >= 0 ? argv[i + 1] : null; };
+  if (sub === "list") {
+    let guards = null;
+    try { guards = await collectGuards({ gh, repo }); writeIndex(repo, guards, { root, fs }); } catch { guards = readIndex(repo, { root, fs }); }
+    if (!guards) throw new Error("guards list: GitHub is unreachable and there is no local index");
+    const hits = listGuards(guards, { path: flag("--path") });
+    if (argv.includes("--json")) print(JSON.stringify(hits, null, 1));
+    else if (!hits.length) print("No guards" + (flag("--path") ? ` cover ${flag("--path")}` : "") + ".");
+    else for (const g of hits) print(`#${g.issue} (PR ${g.pr ?? "?"}, ${String(g.merge_sha ?? "").slice(0, 10)}): ${g.why}\n  tests: ${g.tests.map((t) => t.path + (t.ids.length ? ` [${t.ids.join(", ")}]` : "")).join(", ")}\n  hunks: ${(g.hunks ?? []).map((h) => `${h.file}:${h.start}-${h.end}${h.symbol ? ` (${h.symbol})` : ""}`).join(", ") || "none"}`);
+    return 0;
+  }
+  if (sub === "backfill") {
+    const since = flag("--since");
+    if (!since || Number.isNaN(Date.parse(since))) throw new Error("usage: forgedock guards backfill --since <YYYY-MM-DD> [--dry-run]");
+    const r = await backfill({ gh, git, repo, since, dryRun: argv.includes("--dry-run"), log: (m) => print(m) });
+    print(`guards backfill: ${r.posted.length} ${argv.includes("--dry-run") ? "would be posted" : "posted"}, ${r.exists.length} already guarded, ${r.skipped.length} skipped`);
+    return 0;
+  }
+  throw new Error("usage: forgedock guards list [--path p] [--json] | backfill --since <date> [--dry-run]");
+}

package/bin/lean/guards.test.mjs

@@ -0,0 +1,177 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+import test from "node:test";
+import assert from "node:assert/strict";
+import { buildGuard, guardTests, parseHunks, renderGuard, parseGuard, guardIssue, listGuards, backfill, guardsCli, readIndex, guardAfterMerge, historyPreserve, withHistoryRows, writeIndex } from "./guards.mjs";
+import { renderContract } from "./render.mjs";
+import { tmpDir } from "../tests/_tmp.mjs";
+
+const DIFF = `diff --git a/src/a.mjs b/src/a.mjs
+--- a/src/a.mjs
++++ b/src/a.mjs
+@@ -10,2 +10,3 @@ export function fixed() {
+-x
++y
++z
+@@ -30 +31,0 @@ function other() {
+-gone
+diff --git a/test/a.test.mjs b/test/a.test.mjs
+--- a/test/a.test.mjs
++++ b/test/a.test.mjs
+@@ -1,0 +2,3 @@
++t
+`;
+const nodeContract = { repro_test: { path: "test/a.test.mjs", id: "fixed keeps x", command: "node --test test/a.test.mjs" }, validate: [{ id: "V1", command: "node --test test/a.test.mjs --test-name-pattern=\"fixed keeps x\"" }] };
+const pyContract = { repro_test: { path: "tests/test_a.py", command: "pytest -q tests/test_a.py::test_fixed" }, validate: [{ id: "V1", command: "pytest -q tests/test_a.py -k fixed" }, { id: "V2", command: "pytest -q tests/test_b.py" }] };
+
+test("node --test fixture: file and id, hunks exclude test files with symbol and deletion anchor", () => {
+  const { guard } = buildGuard({ issue: 7, title: "Fix  x\nbug", pr: 9, mergeSha: "abc", contract: nodeContract, diff: DIFF });
+  assert.deepEqual(guard.tests, [{ path: "test/a.test.mjs", ids: ["fixed keeps x"] }]);
+  assert.deepEqual(guard.hunks, [{ file: "src/a.mjs", start: 10, end: 12, symbol: "export function fixed() {" }, { file: "src/a.mjs", start: 32, end: 32, symbol: "function other() {" }]);
+  assert.equal(guard.why, "Fix x bug");
+});
+
+test("pytest fixture: ::ids and -k, every test file named", () => {
+  const t = guardTests(pyContract);
+  assert.deepEqual(t.find((x) => x.path === "tests/test_a.py").ids.sort(), ["fixed", "test_fixed"]);
+  assert.deepEqual(t.find((x) => x.path === "tests/test_b.py").ids, []); // file granularity
+});
+
+test("a contract without a test yields no guard and says why", () => {
+  assert.match(buildGuard({ issue: 1, contract: { repro_test: "none", repro_test_reason: "docs only", validate: [{ command: "npm run lint" }] } }).reason, /repro_test none \(docs only\)/);
+  assert.match(buildGuard({ issue: 1, contract: { validate: [] } }).reason, /names no test/);
+});
+
+test("render/parse round trip survives '-->', '--!>' and '<x>' in a field", () => {
+  const g = { v: 1, issue: 3, why: "a --> b --!> c <x>", tests: [{ path: "t --!> <y>", ids: ["--!>"] }], hunks: [] };
+  const body = renderGuard(g);
+  const inner = body.slice(0, -" -->".length);
+  assert.ok(body.endsWith(" -->"));
+  assert.equal(inner.includes(">"), false); // no terminator variant can appear before the closing -->
+  assert.deepEqual(parseGuard(body), g);
+});
+
+function fakeGh({ contract, comments = [], title = "Fix the thing" }) {
+  const posted = [];
+  const body = `<!-- FORGE:CONTRACT -->\n${renderContract({ requirements: [], deliverables: [], preserve: [], validate: [], ...contract }, "abcdef123456")}`;
+  const gh = async (a) => {
+    if (a[0] === "issue" && a[1] === "view") return JSON.stringify({ number: 7, title, comments: [{ body }, ...comments, ...posted.map((b) => ({ body: b }))] });
+    if (a[0] === "pr" && a[1] === "view") return JSON.stringify({ number: 9, mergeCommit: { oid: "deadbeefcafe" } });
+    if (a[0] === "issue" && a[1] === "comment") { posted.push(a[a.indexOf("--body") + 1]); return ""; }
+    throw new Error(`unexpected gh ${a.join(" ")}`);
+  };
+  return { gh, posted };
+}
+const git = async (a) => { assert.deepEqual(a.slice(0, 2), ["diff", "-U0"]); assert.ok(a.includes("deadbeefcafe^1")); return DIFF; };
+
+test("guardIssue posts exactly one FORGE:GUARD and is idempotent on rerun", async () => {
+  const f = fakeGh({ contract: nodeContract });
+  const r1 = await guardIssue({ gh: f.gh, git, repo: "o/r", issue: 7, pr: 9 });
+  assert.ok(r1.posted);
+  const r2 = await guardIssue({ gh: f.gh, git, repo: "o/r", issue: 7, pr: 9 });
+  assert.ok(r2.exists);
+  assert.equal(f.posted.length, 1);
+  assert.equal(parseGuard(f.posted[0]).merge_sha, "deadbeefcafe");
+});
+
+test("guardIssue: no test posts nothing; unavailable merge commit is a logged skip", async () => {
+  const f = fakeGh({ contract: { repro_test: "none", repro_test_reason: "n/a" } });
+  assert.ok((await guardIssue({ gh: f.gh, git, repo: "o/r", issue: 7, pr: 9 })).skipped);
+  assert.equal(f.posted.length, 0);
+  const g = fakeGh({ contract: nodeContract });
+  const r = await guardIssue({ gh: g.gh, git: async () => { throw new Error("bad object"); }, repo: "o/r", issue: 7, pr: 9 });
+  assert.match(r.reason, /not available locally/);
+});
+
+test("listGuards filters by hunk file, test file or directory", () => {
+  const gs = [buildGuard({ issue: 7, contract: nodeContract, diff: DIFF }).guard, buildGuard({ issue: 8, contract: pyContract, diff: "" }).guard];
+  assert.deepEqual(listGuards(gs, { path: "src/a.mjs" }).map((g) => g.issue), [7]);
+  assert.deepEqual(listGuards(gs, { path: "tests" }).map((g) => g.issue), [8]);
+  assert.deepEqual(listGuards(gs, { path: "nope.js" }), []);
+  assert.equal(listGuards(gs).length, 2);
+});
+
+test("backfill guards merged lanes and logs why a lane without a test yields none", async () => {
+  const withTest = fakeGh({ contract: nodeContract }), noTest = fakeGh({ contract: { validate: [] } });
+  const by = { 1: withTest, 2: noTest };
+  const gh = async (a) => {
+    if (a[0] === "issue" && a[1] === "list") return JSON.stringify([{ number: 1 }, { number: 2 }]);
+    if (a[0] === "pr" && a[1] === "list") return JSON.stringify([{ number: 9, body: `Closes #${a.join(" ").match(/#(\d+) in:body/)[1]}`, mergeCommit: { oid: "deadbeefcafe" } }]);
+    return by[a[2]].gh(a);
+  };
+  const logs = [];
+  const r = await backfill({ gh, git, repo: "o/r", since: "2026-01-01", log: (m) => logs.push(m) });
+  assert.deepEqual(r.posted, [1]);
+  assert.equal(r.skipped[0].issue, 2);
+  assert.match(logs[0], /names no test/);
+  assert.equal(withTest.posted.length, 1);
+});
+
+test("guards list prints guards for a path and caches the index; falls back to it offline", async () => {
+  const root = tmpDir("guards-");
+  {
+    const g = buildGuard({ issue: 7, title: "t", contract: nodeContract, diff: DIFF }).guard;
+    const gh = async () => JSON.stringify([{ number: 7, comments: [{ body: renderGuard(g) }] }]);
+    const out = [];
+    assert.equal(await guardsCli(["list", "--path", "src/a.mjs"], { gh, repo: "o/r", print: (m) => out.push(m), root }), 0);
+    assert.match(out[0], /#7/);
+    assert.equal(readIndex("o/r", { root }).length, 1);
+    const off = [];
+    await guardsCli(["list", "--path", "test/a.test.mjs"], { gh: async () => { throw new Error("offline"); }, repo: "o/r", print: (m) => off.push(m), root });
+    assert.match(off[0], /#7/);
+  }
+});
+test("parseHunks ignores deleted files", () => {
+  assert.deepEqual(parseHunks("--- a/x.js\n+++ /dev/null\n@@ -1,2 +0,0 @@\n"), []);
+});
+test("guardAfterMerge fetches the bare branch (not origin/<lane>) and the merge sha when absent locally", async () => {
+  const calls = [];
+  let have = false;
+  const body = `<!-- FORGE:CONTRACT -->\n${renderContract({ requirements: [], deliverables: [], preserve: [], ...nodeContract }, "abcdef123456")}`;
+  const io = {
+    gh: async (a) => a[0] === "issue" ? JSON.stringify({ number: 9, title: "t", comments: [{ body }] }) : a[0] === "pr" ? JSON.stringify({ number: 3, mergeCommit: { oid: "abc123" } }) : "",
+    git: async (a) => { calls.push(a.join(" ")); if (a[0] === "diff") { if (!have) throw new Error("bad object"); return DIFF; } if (a.join(" ") === "fetch origin abc123") have = true; return ""; },
+  };
+  const r = await guardAfterMerge({ io, repo: "o/r", issue: 9, pr: 3, cwd: "/x", base: "origin/staging" });
+  assert.ok(calls.includes("fetch origin staging"));
+  assert.ok(!calls.some((c) => c.includes("origin/staging")));
+  assert.ok(r.posted, JSON.stringify(r));
+});
+
+const G = (issue, file, over = {}) => ({ v: 1, issue, pr: issue + 100, merge_sha: "s", tests: [{ path: "test/x.test.mjs", ids: [] }], hunks: [{ file, start: 1, end: 2, symbol: null }], why: `fix ${issue}`, ...over });
+test("historyPreserve: guarded deliverable yields rows, unguarded none, own issue skipped", () => {
+  const guards = [G(5, "src/a.mjs"), G(6, "lib/other.mjs"), G(7, "src/a.mjs")];
+  const rows = historyPreserve({ guards, deliverables: [{ path: "src/a.mjs" }], issue: 7 });
+  assert.deepEqual(rows, [{ id: "H1", what: "fix 5 (#5, PR #105)", source: "guard" }]);
+  assert.deepEqual(historyPreserve({ guards, deliverables: [{ path: "src/zzz/q.mjs" }], issue: 1 }), []);
+});
+test("historyPreserve: deterministic under input order, capped at 5, proximity then recency", () => {
+  const guards = [G(1, "lib/z.mjs"), G(2, "src/a.mjs"), G(3, "src/b.mjs"), G(4, "src/c.mjs"), G(5, "src/d.mjs"), G(6, "src/e.mjs"), G(8, "x/y.mjs", { tests: [{ path: "src/a.mjs", ids: [] }] }), G(9, "src/a.mjs")];
+  const d = [{ path: "src/a.mjs" }];
+  const a = historyPreserve({ guards, deliverables: d, issue: 99 });
+  const b = historyPreserve({ guards: [...guards].reverse(), deliverables: d, issue: 99 });
+  assert.deepEqual(a, b);
+  assert.equal(a.length, 5);
+  assert.deepEqual(a.map((r) => r.what.match(/#(\d+),/)[1]), ["9", "2", "8", "6", "5"], "hunk match first, then test match, then same directory by recency");
+  assert.deepEqual(a.map((r) => r.id), ["H1", "H2", "H3", "H4", "H5"]);
+});
+test("withHistoryRows reads the local index; no index or no match returns the same contract", () => {
+  const root = tmpDir("guards-hist-");
+  const c = { requirements: [], deliverables: [{ id: "D1", path: "src/a.mjs" }], preserve: [{ id: "P1", what: "keep" }, { id: "H9", what: "old", source: "guard" }], validate: [] };
+  assert.equal(withHistoryRows(c, { repo: "o/r", issue: 1, root }), c, "no index");
+  writeIndex("o/r", [G(5, "src/a.mjs")], { root });
+  const w = withHistoryRows(c, { repo: "o/r", issue: 1, root });
+  assert.deepEqual(w.preserve.map((p) => p.id), ["P1", "H1"]);
+  const none = { ...c, deliverables: [{ id: "D1", path: "docs/q.md" }] };
+  assert.equal(withHistoryRows(none, { repo: "o/r", issue: 1, root }), none);
+});
+test("guardAfterMerge adds the posted guard to an existing local index only", async () => {
+  const root = tmpDir("guards-idx-");
+  const body = `<!-- FORGE:CONTRACT -->\n${renderContract({ requirements: [], deliverables: [], preserve: [], ...nodeContract }, "abcdef123456")}`;
+  const io = { gh: async (a) => a[0] === "issue" ? JSON.stringify({ number: 9, title: "t", comments: [{ body }] }) : a[0] === "pr" ? JSON.stringify({ number: 3, mergeCommit: { oid: "abc123" } }) : "", git: async (a) => (a[0] === "diff" ? DIFF : "") };
+  assert.ok((await guardAfterMerge({ io, repo: "o/r", issue: 9, pr: 3, cwd: "/x", root })).posted);
+  assert.equal(readIndex("o/r", { root }), null, "no index is not created from one guard");
+  writeIndex("o/r", [G(5, "src/a.mjs")], { root });
+  await guardAfterMerge({ io, repo: "o/r", issue: 9, pr: 3, cwd: "/x", root });
+  assert.deepEqual(readIndex("o/r", { root }).map((g) => g.issue), [5, 9]);
+});