forgedock 1.35.0 → 1.37.0

package/bin/review-context.mjs

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * review-context.mjs — detect and refresh a stale forge.yaml `review.context` / `review.tech_stack` (#4666).
+ *
+ * The checks are deterministic (no LLM): manifests, the decision log and the context text are compared directly.
+ * Only `proposeRefresh` may use the enrichment backend, and only when the caller passes one in.
+ *
+ *   node bin/review-context.mjs check --config <forge.yaml> [--root <dir>] [--repo owner/name] --json
+ *
+ * Exit 0 always for `check` (a failing check must never block a review); the JSON carries the result.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { execFileSync } from "child_process";
+import { fileURLToPath } from "url";
+
+export const DEFAULT_MAX_MERGED_PRS = 50;
+export const DECISION_LOG_CANDIDATES = ["docs/decisions.md", "DECISIONS.md", "docs/decision-log.md", "devdocs/project/decisions.md"];
+
+// label as written in tech_stack -> package name as written in a manifest
+const FRAMEWORKS = [
+  ["Next.js", "next"], ["React", "react"], ["Vue", "vue"], ["Nuxt", "nuxt"], ["Svelte", "svelte"], ["SvelteKit", "@sveltejs/kit"],
+  ["Angular", "@angular/core"], ["Remix", "@remix-run/react"], ["Astro", "astro"], ["Express", "express"], ["Fastify", "fastify"],
+  ["NestJS", "@nestjs/core"], ["Tailwind", "tailwindcss"], ["Prisma", "prisma"], ["Drizzle", "drizzle-orm"],
+  ["FastAPI", "fastapi"], ["Django", "django"], ["Flask", "flask"], ["SQLAlchemy", "sqlalchemy"],
+  ["Rails", "rails"], ["Laravel", "laravel/framework"], ["Gin", "gin-gonic/gin"], ["Axum", "axum"], ["Actix", "actix-web"],
+];
+
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", ".next", ".venv", "venv", "vendor", "target", "__pycache__", ".claude", ".forge-lean"]);
+const MANIFEST_RE = /^(package\.json|pyproject\.toml|requirements[\w.-]*\.txt|go\.mod|Cargo\.toml|Gemfile|composer\.json)$/;
+
+const esc = (s) => s.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+const wordRe = (w, flags = "i") => new RegExp(`(^|[^A-Za-z0-9_.-])${esc(w)}($|[^A-Za-z0-9_.-])`, flags);
+
+// ── forge.yaml review block (no YAML parser in this repo: a tolerant line scanner) ──────────────────────────────
+
+function reviewRange(lines) {
+  const start = lines.findIndex((l) => /^review:\s*(#.*)?$/.test(l));
+  if (start === -1) return null;
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) if (/^\S/.test(lines[i]) && !lines[i].startsWith("#")) { end = i; break; }
+  return { start, end };
+}
+
+function scalar(raw) {
+  const v = raw.trim();
+  if (v.startsWith('"')) { try { return JSON.parse(v.replace(/\s+#.*$/, "")); } catch { return v.slice(1, -1); } }
+  if (v.startsWith("'")) return v.slice(1, v.lastIndexOf("'")).replace(/''/g, "'");
+  return v.replace(/\s+#.*$/, "");
+}
+
+/** Reads the scalar keys of the top-level `review:` block (block scalars `|`/`>` included). Missing -> "". */
+export function readReviewFields(yamlText) {
+  const lines = yamlText.split(/\r?\n/);
+  const r = reviewRange(lines);
+  const out = {};
+  if (!r) return out;
+  for (let i = r.start + 1; i < r.end; i++) {
+    const m = /^  ([A-Za-z_]+):\s*(.*)$/.exec(lines[i]);
+    if (!m) continue;
+    const [, key, rest] = m;
+    if (/^[|>][+-]?\s*(#.*)?$/.test(rest)) {
+      const body = [];
+      let j = i + 1;
+      while (j < r.end && (/^\s*$/.test(lines[j]) || /^ {3,}/.test(lines[j]))) body.push(lines[j++].replace(/^ {4}/, "").replace(/^ +$/, ""));
+      out[key] = body.join("\n").replace(/\n+$/, "");
+      i = j - 1;
+    } else if (rest.trim() !== "") out[key] = scalar(rest);
+  }
+  return out;
+}
+
+/** Returns yamlText with the given review keys replaced (or added). Every other line is left untouched. */
+export function writeReviewFields(yamlText, fields) {
+  const lines = yamlText.split("\n");
+  let r = reviewRange(lines);
+  if (!r) {
+    if (lines[lines.length - 1] !== "") lines.push("");
+    lines.push("review:");
+    r = { start: lines.length - 1, end: lines.length };
+  }
+  const keys = Object.keys(fields);
+  const kept = [];
+  for (let i = r.start + 1; i < r.end; i++) {
+    const m = /^  ([A-Za-z_]+):/.exec(lines[i]);
+    if (m && keys.includes(m[1])) {
+      while (i + 1 < r.end && (/^ {3,}/.test(lines[i + 1]) || (/^\s*$/.test(lines[i + 1]) && /^ {3,}/.test(lines[i + 2] || "")))) i++;
+      continue;
+    }
+    kept.push(lines[i]);
+  }
+  const added = [];
+  for (const k of keys) {
+    const v = String(fields[k]);
+    if (v.includes("\n")) added.push(`  ${k}: |`, ...v.replace(/\n+$/, "").split("\n").map((l) => (l ? `    ${l}` : "")));
+    else added.push(`  ${k}: ${JSON.stringify(v)}`);
+  }
+  return [...lines.slice(0, r.start + 1), ...added, ...kept, ...lines.slice(r.end)].join("\n");
+}
+
+// ── facts: manifests and the decision log ────────────────────────────────────────────────────────────────────────
+
+/** Dependency names and raw manifest text under `root` (depth <= 3, skipping vendored dirs). */
+export function collectManifestFacts(root) {
+  const files = [];
+  const walk = (dir, depth) => {
+    let entries;
+    try { entries = readdirSync(dir); } catch { return; }
+    for (const name of entries) {
+      if (files.length >= 200) return;
+      const p = join(dir, name);
+      let st;
+      try { st = statSync(p); } catch { continue; }
+      if (st.isDirectory()) { if (depth < 3 && !SKIP_DIRS.has(name)) walk(p, depth + 1); }
+      else if (MANIFEST_RE.test(name) && st.size < 2_000_000) files.push(p);
+    }
+  };
+  walk(root, 0);
+  const parts = [];
+  let hasSourceManifest = false;
+  for (const f of files) {
+    let text;
+    try { text = readFileSync(f, "utf8"); } catch { continue; }
+    if (f.endsWith("package.json")) {
+      try {
+        const j = JSON.parse(text);
+        const deps = ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"].flatMap((k) => Object.keys(j[k] || {}));
+        if (deps.length) hasSourceManifest = true;
+        parts.push(deps.join("\n"));
+      } catch { /* unparsable manifest: ignore */ }
+    } else {
+      hasSourceManifest = true;
+      parts.push(text);
+    }
+  }
+  return { files, hasSourceManifest, haystack: parts.join("\n").toLowerCase() };
+}
+
+export function findDecisionLog(root, configured) {
+  for (const rel of [configured, ...DECISION_LOG_CANDIDATES].filter(Boolean)) {
+    const p = resolve(root, rel);
+    if (existsSync(p)) { try { return readFileSync(p, "utf8"); } catch { /* next */ } }
+  }
+  return "";
+}
+
+const ID_RE = /\b(?:[A-Z]{1,5}-?\d{1,4})\b/g;
+
+/** IDs the decision log marks superseded: "D-12 ... superseded", "Status: superseded" under a "## D-12" heading, "D-15 supersedes D-12". */
+export function supersededDecisionIds(logText) {
+  const out = new Set();
+  let lastId = [];
+  for (const line of logText.split(/\r?\n/)) {
+    const m = /supersed\w*/i.exec(line);
+    if (!m) {
+      const ids = line.match(ID_RE);
+      if (ids) lastId = ids;
+      continue;
+    }
+    if (/^supersedes$/i.test(m[0])) (line.slice(m.index).match(ID_RE) || []).forEach((i) => out.add(i));
+    else {
+      const before = line.slice(0, m.index).match(ID_RE) || [];
+      (before.length ? before : lastId).forEach((i) => out.add(i));
+    }
+  }
+  return out;
+}
+
+// ── detection ────────────────────────────────────────────────────────────────────────────────────────────────────
+
+/** Reasons the context is stale: [{code, detail}]. Empty = fresh (or nothing to compare against). */
+export function detectStale({ techStack = "", context = "", manifests, decisionLogText = "" }) {
+  const reasons = [];
+  if (manifests?.hasSourceManifest) {
+    const absent = FRAMEWORKS.filter(([label, pkg]) => wordRe(label).test(techStack) && !wordRe(pkg).test(manifests.haystack)).map(([l]) => l);
+    if (absent.length) reasons.push({ code: "tech_stack_absent", detail: `tech_stack names ${absent.join(", ")} but no manifest lists it` });
+    if (/docs[- ]only|\bno (?:product |source |application )?code\b/i.test(context)) {
+      reasons.push({ code: "docs_only_phrasing", detail: "context says the repo is docs-only / has no code, but source manifests exist" });
+    }
+  }
+  if (decisionLogText && context) {
+    const cited = [...supersededDecisionIds(decisionLogText)].filter((id) => wordRe(id, "").test(context));
+    if (cited.length) reasons.push({ code: "superseded_decision", detail: `context cites superseded decision(s) ${cited.join(", ")}` });
+  }
+  return reasons;
+}
+
+/** Advisory once more than `maxMergedPrs` PRs merged since the context was generated. Unknown count = not advisory. */
+export function contextAge({ generatedAt = "", mergedSince = null, maxMergedPrs = DEFAULT_MAX_MERGED_PRS }) {
+  const max = Number.isFinite(maxMergedPrs) && maxMergedPrs > 0 ? maxMergedPrs : DEFAULT_MAX_MERGED_PRS;
+  return { generatedAt, mergedSince, maxMergedPrs: max, advisory: Boolean(generatedAt) && mergedSince != null && mergedSince > max };
+}
+
+/** Merged PR count since `generatedAt` via gh; null when it cannot be determined. */
+export function countMergedSince(repo, generatedAt, run = execFileSync) {
+  if (!repo || !/^\d{4}-\d{2}-\d{2}/.test(generatedAt)) return null;
+  try {
+    const out = run("gh", ["pr", "list", "-R", repo, "--state", "merged", "--search", `merged:>=${generatedAt.slice(0, 10)}`, "--json", "number", "--limit", "200"], { encoding: "utf8", timeout: 20000, stdio: ["ignore", "pipe", "ignore"] });
+    const n = JSON.parse(out);
+    return Array.isArray(n) ? n.length : null;
+  } catch { return null; }
+}
+
+/** Full check of one forge.yaml. `mergedCount` is injectable for tests. */
+export function checkContext({ configPath, root, repo, mergedCount = countMergedSince }) {
+  let text = "";
+  try { text = readFileSync(configPath, "utf8"); } catch { return { stale: false, reasons: [], generated_at: "", merged_since: null, advisory: false, max_merged_prs: DEFAULT_MAX_MERGED_PRS }; }
+  const f = readReviewFields(text);
+  const manifests = collectManifestFacts(root);
+  const reasons = detectStale({ techStack: f.tech_stack || "", context: f.context || "", manifests, decisionLogText: findDecisionLog(root, f.decision_log) });
+  const generatedAt = f.context_generated_at || "";
+  const age = contextAge({ generatedAt, mergedSince: generatedAt ? mergedCount(repo, generatedAt) : null, maxMergedPrs: parseInt(f.context_max_merged_prs, 10) });
+  return { stale: reasons.length > 0, reasons, generated_at: generatedAt, merged_since: age.mergedSince, advisory: age.advisory, max_merged_prs: age.maxMergedPrs };
+}
+
+// ── refresh ──────────────────────────────────────────────────────────────────────────────────────────────────────
+
+/** Tech stack from the frameworks the manifests actually list. */
+export function techStackFromManifests(manifests) {
+  return FRAMEWORKS.filter(([, pkg]) => wordRe(pkg).test(manifests.haystack)).map(([l]) => l).join(", ");
+}
+
+/** Drops the sentences that made the context stale (docs-only phrasing, superseded decision IDs). */
+export function pruneContext(context, { hasSourceManifest, superseded }) {
+  const stale = (s) => (hasSourceManifest && /docs[- ]only|\bno (?:product |source |application )?code\b/i.test(s)) || [...superseded].some((id) => wordRe(id, "").test(s));
+  return context.split("\n").map((line) => line.split(/(?<=[.!?])\s+/).filter((s) => !stale(s)).join(" ")).join("\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+
+/**
+ * Proposes new review fields from the current manifests and decision log, deterministically: tech_stack is rebuilt from
+ * the manifests, stale sentences are pruned from the context. `enrichFn({tech_stack, context, decisionLog, manifestFiles})`
+ * (optional, async) may rewrite them further.
+ */
+export async function proposeRefresh({ yamlText, root, now = new Date(), enrichFn, mergedTotal }) {
+  const cur = readReviewFields(yamlText);
+  const manifests = collectManifestFacts(root);
+  const log = findDecisionLog(root, cur.decision_log);
+  const names = manifests.files.map((p) => p.slice(root.length + 1));
+  const stack = techStackFromManifests(manifests) || cur.tech_stack || "";
+  const fields = {
+    tech_stack: stack,
+    context: pruneContext(cur.context || "", { hasSourceManifest: manifests.hasSourceManifest, superseded: supersededDecisionIds(log) }),
+  };
+  if (!fields.context && names.length) fields.context = `Source manifests: ${names.join(", ")}.`;
+  if (enrichFn) {
+    const e = await enrichFn({ ...fields, decisionLog: log, manifestFiles: names });
+    if (e && typeof e === "object") { if (e.tech_stack) fields.tech_stack = e.tech_stack; if (e.context) fields.context = e.context; }
+  }
+  fields.context_generated_at = now.toISOString().slice(0, 10);
+  if (mergedTotal != null) fields.context_generated_pr_count = String(mergedTotal);
+  const next = writeReviewFields(yamlText, fields);
+  return { next, diff: simpleDiff(yamlText, next), changed: next !== yamlText };
+}
+
+/**
+ * `forgedock init --refresh-context`: show the diff, write only on approval. `deps` = {confirm, backup, write, interactive}.
+ * Returns the exit code (0 written or nothing to do, 1 declined / non-interactive / no forge.yaml).
+ */
+export async function refreshContextFlow({ cwd, out, deps, enrichFn, mergedTotal }) {
+  const path = join(cwd, "forge.yaml");
+  if (!existsSync(path)) { out.write("\n  No forge.yaml here — run: npx forgedock init\n"); return 1; }
+  const { next, diff, changed } = await proposeRefresh({ yamlText: readFileSync(path, "utf8"), root: cwd, enrichFn, mergedTotal });
+  out.write(`\n  review.context / review.tech_stack refresh (from manifests + decision log):\n\n${diff.split("\n").map((l) => `    ${l}`).join("\n")}\n\n`);
+  if (!changed) { out.write("  Nothing to change.\n"); return 0; }
+  if (!deps.interactive) { out.write("  Non-interactive run — forge.yaml left untouched. Re-run in a terminal to approve.\n"); return 1; }
+  if (!(await deps.confirm("Apply this change to forge.yaml? A backup will be created.", false))) { out.write("  Refresh cancelled — forge.yaml left untouched.\n"); return 1; }
+  const backup = deps.backup(path);
+  if (backup) out.write(`  Backed up: forge.yaml → ${backup.backupName}\n`);
+  deps.write(path, next);
+  out.write("  forge.yaml updated.\n");
+  return 0;
+}
+
+/** Minimal line diff (removed `-`, added `+`) over the lines that differ; enough for an approval prompt. */
+export function simpleDiff(a, b) {
+  const x = a.split("\n"), y = b.split("\n");
+  let s = 0;
+  while (s < x.length && s < y.length && x[s] === y[s]) s++;
+  let e = 0;
+  while (e < x.length - s && e < y.length - s && x[x.length - 1 - e] === y[y.length - 1 - e]) e++;
+  return [...x.slice(s, x.length - e).map((l) => `- ${l}`), ...y.slice(s, y.length - e).map((l) => `+ ${l}`)].join("\n");
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const [cmd, ...rest] = process.argv.slice(2);
+  const opt = (n) => { const i = rest.indexOf(n); return i === -1 ? "" : rest[i + 1] || ""; };
+  if (cmd !== "check" || !opt("--config")) {
+    process.stderr.write("usage: review-context.mjs check --config <forge.yaml> [--root <dir>] [--repo owner/name] --json\n");
+    process.exit(2);
+  }
+  const configPath = resolve(opt("--config"));
+  const res = checkContext({ configPath, root: resolve(opt("--root") || dirname(configPath)), repo: opt("--repo") });
+  process.stdout.write(JSON.stringify(res) + "\n");
+}

package/bin/runner.mjs

@@ -2001,6 +2001,17 @@ export function listDescendants(pid, { psFn = null, maxCmd = 200 } = {}) {
 /** #4410: cap of the tool uses one stream session records. */
 const TOOL_USES_MAX = 5000;
 
+/**
+ * #4690: limit events of the systemd scope the process `pid` runs in: `tasks` (pids.events `max`: forks refused at TasksMax)
+ * and `memory` (memory.events `oom_kill`). null when its cgroup or the counters are unreadable (no cgroup v2, no scope).
+ */
+export function readScopeLimitEvents(pid, { procRoot = "/proc", cgroupRoot = "/sys/fs/cgroup" } = {}) {
+  const line = readFileSync(join(procRoot, String(pid), "cgroup"), "utf8").split("\n").find((l) => l.startsWith("0::"));
+  const path = line?.slice(3).trim();
+  if (!path || !path.endsWith(".scope")) return null;
+  const count = (file, key) => { try { return Number((readFileSync(join(cgroupRoot, path, file), "utf8").match(new RegExp(`^${key} (\\d+)`, "m")) ?? [])[1]) || 0; } catch { return 0; } };
+  return { tasks: count("pids.events", "max"), memory: count("memory.events", "oom_kill") };
+}
 /**
  * Async twin of runCliBackend (core work-on live comments): the CLI runs under child_process.spawn so the caller's event
  * loop keeps turning while the session runs. It returns the SAME envelope (and throws the same errors) because the
@@ -2024,7 +2035,7 @@ const TOOL_USES_MAX = 5000;
  * (deduped by tool_use id, capped at TOOL_USES_MAX), for bin/lean/toolstats.mjs; absent on the non-stream path.
  */
 export async function runCliBackendAsync(opts) {
-  const { spawnFn: _ignored, onSpawn = null, idleMs = 0, maxMs = 0, stream = false, wrap = null, control = null, contextMax = 0, turnMax = 0, busy = null, busyMs = 0, onIdleExtend = null, ...rest } = opts;
+  const { spawnFn: _ignored, onSpawn = null, idleMs = 0, maxMs = 0, stream = false, wrap = null, control = null, contextMax = 0, turnMax = 0, busy = null, busyMs = 0, onIdleExtend = null, limitProbe = readScopeLimitEvents, ...rest } = opts;
   let captured = null;
   try {
     runCliBackend({ ...rest, spawnFn: (bin, args, o) => {
@@ -2047,7 +2058,9 @@ export async function runCliBackendAsync(opts) {
     const j = args.indexOf("--output-format");
     if (j >= 0) { args[j + 1] = "stream-json"; if (!args.includes("--verbose")) args.splice(j + 2, 0, "--verbose"); }
   }
-  if (typeof wrap === "function") ({ bin, args } = wrap(bin, args));
+  let scopeUnit = null; // #4690: set when `wrap` put the child in a limited systemd scope
+  if (typeof wrap === "function") { const w = wrap(bin, args); ({ bin, args } = w); scopeUnit = w.unit ?? null; }
+  let limitInfo = null;
   const ceiling = maxMs > 0 ? maxMs : o.timeout;
   let collected, idleInfo = null, ctxInfo = null, turnInfo = null;
   const msgUsage = new Map(); // #4390: assistant message id -> its usage (a message spans several stream lines)
@@ -2099,7 +2112,12 @@ export async function runCliBackendAsync(opts) {
           }
         }
         // #4405: a separate check, so the absolute ceiling still applies while the idle kill is extended (busy) or settling.
-        if (!timedOut && !idleInfo && !ctxInfo && !turnInfo && now - startedAt - pausedTotal - (paused ? now - pausedAt : 0) >= ceiling) { timedOut = true; kill(); }
+        // #4690: the scope's pids/memory events say the lane hit its own limit (the scope cgroup is gone once the child exits, so sample live)
+        if (scopeUnit && !limitInfo && !timedOut && !idleInfo && !ctxInfo && !turnInfo) {
+          let ev = null; try { ev = limitProbe(child.pid); } catch { ev = null; }
+          if (ev && (ev.tasks > 0 || ev.memory > 0)) { limitInfo = { limit: ev.tasks > 0 ? "tasks" : "memory", unit: scopeUnit, events: ev }; kill(); }
+        }
+        if (!timedOut && !idleInfo && !ctxInfo && !turnInfo && !limitInfo && now - startedAt - pausedTotal - (paused ? now - pausedAt : 0) >= ceiling) { timedOut = true; kill(); }
       }, tick);
       timer.unref?.();
       const noteLine = (line) => {
@@ -2143,6 +2161,11 @@ export async function runCliBackendAsync(opts) {
   } finally { if (sysDir) rmSync(sysDir, { recursive: true, force: true }); }
   const sum = (k) => [...msgUsage.values()].reduce((a, u) => a + toFiniteUsageNumber(u[k]), 0);
   const streamUsage = () => (msgUsage.size ? { input_tokens: sum("input_tokens"), output_tokens: sum("output_tokens"), cache_creation_input_tokens: sum("cache_creation_input_tokens"), cache_read_input_tokens: sum("cache_read_input_tokens") } : null);
+  if (limitInfo) {
+    const err = new Error(`claude CLI lane hit its scope ${limitInfo.limit} limit (${limitInfo.unit}) and was stopped`);
+    err.code = "CLI_LANE_LIMIT"; err.limit = limitInfo.limit; err.unit = limitInfo.unit; err.events = limitInfo.events; err.toolUses = [...toolUses.values()];
+    throw err;
+  }
   if (turnInfo) {
     const err = new Error(`claude CLI session reached its turn budget (${turnMax} turns) and was stopped`);
     err.code = "CLI_TURNS"; err.turns = msgUsage.size; err.turnMax = turnMax; err.lastTool = turnInfo.lastTool; err.usage = streamUsage(); err.toolUses = [...toolUses.values()];

package/bin/stats/aggregate.mjs

@@ -86,7 +86,7 @@ function costSection(runs) {
     n, cacheReadMean: mean(cr), cacheReadMedian: percentile(cr, 50), perPhase,
     outputMean: n ? sum(runs.map((r) => sum(Object.values(r.phases).map((p) => p.out ?? 0)))) / n : null,
     perMergedIssue: merged ? sum(cr) / merged : null,
-    usdN: usd.length, usdMean: mean(usd), usdTotal: usd.length ? sum(usd) : null,
+    usdN: usd.length, usdMean: mean(usd), usdMedian: percentile(usd, 50), usdTotal: usd.length ? sum(usd) : null,
   };
 }
 

package/bin/stats/compounding.mjs

@@ -0,0 +1,157 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * #4696: compounding metrics for `forgedock stats --compounding`: does a repo get safer the longer ForgeDock works on it.
+ * Deterministic (0 LLM calls): guards (#4692 FORGE:GUARD comments), `reopened` issue events, git blame, and gate events
+ * from the FORGE:TELEMETRY records. The report core is pure; `gatherCompounding` supplies the GitHub and git inputs.
+ *   reintroduction: a guarded fix whose issue was reopened after the lane closed it (a), or whose merge commit is the blame
+ *     of the old-side lines of a later guarded fix within 90 days (b; squash and rebase merges, where merge_sha is the commit)
+ *   reopen_after_close: lane-closed (merged) issues that were reopened afterwards
+ *   guard / decision counts: gate events guard_run, guard_broken, supersedes_accepted, decision_superseded,
+ *     decision_violation (#4693, #4695); null (n/a) until a repo has recorded any of that kind
+ * Grouped as a rolling window, per release and per lane-age bucket (lane rank = merge order of the repo's lanes).
+ */
+import { execFileSync } from "node:child_process";
+import { collectGuards } from "../lean/guards.mjs";
+import { parsePages } from "./github-source.mjs";
+
+export const REINTRO_DAYS = 90;
+export const DEFAULT_BUCKETS = [100, 500];
+export const DEFAULT_WINDOW_MS = 30 * 86400000;
+export const COUNTED_EVENTS = ["guard_run", "guard_broken", "supersedes_accepted", "decision_superseded", "decision_violation"];
+const DAY = 86400000;
+const ratio = (a, b) => (b ? Math.round((a / b) * 1000) / 1000 : null);
+const ms = (ts) => { const t = Date.parse(ts ?? ""); return Number.isFinite(t) ? t : null; };
+
+export const bucketLabel = (rank, edges) => {
+  if (rank == null) return "unranked";
+  let lo = 1;
+  for (const e of edges) { if (rank <= e) return `${lo}-${e}`; lo = e + 1; }
+  return `${lo}+`;
+};
+
+/** Guards whose fixed lines a later guarded fix changed within 90 days: [{fix, by}] (fix = earlier guard's issue). Git probes may return null (unresolved). */
+export function blameLineage(guards, git) {
+  const t = new Map(), hits = [];
+  const time = (g) => { if (!t.has(g.merge_sha)) t.set(g.merge_sha, git.time(g.merge_sha)); return t.get(g.merge_sha); };
+  const byCommit = new Map(guards.filter((g) => g.merge_sha).map((g) => [g.merge_sha, g]));
+  let unresolved = 0;
+  for (const g2 of guards) {
+    if (!g2.merge_sha) { unresolved++; continue; }
+    const ranges = git.oldRanges(g2.merge_sha);
+    if (!ranges) { unresolved++; continue; }
+    const seen = new Set();
+    for (const r of ranges) for (const sha of git.blame(`${g2.merge_sha}^`, r.file, r.start, r.end) ?? []) {
+      const g1 = byCommit.get(sha);
+      if (!g1 || g1.issue === g2.issue || seen.has(g1.issue)) continue;
+      const a = time(g1), b = time(g2);
+      if (a == null || b == null || b < a || b - a > REINTRO_DAYS * 86400) continue;
+      seen.add(g1.issue); hits.push({ fix: g1.issue, by: g2.issue });
+    }
+  }
+  return { hits, unresolved };
+}
+
+/** Metrics of one group of lane entries and the gate events falling in it. */
+function summarize(entries, events, have, minN) {
+  const guarded = entries.filter((e) => e.guarded), lanes = entries.filter((e) => e.merged);
+  const count = (k) => (have[k] ? events.filter((e) => e.event === k).length : null);
+  return {
+    lanes: lanes.length,
+    reopen_after_close: { reopened: lanes.filter((e) => e.reopened).length, rate: ratio(lanes.filter((e) => e.reopened).length, lanes.length) },
+    reintroduction: { guarded: guarded.length, reintroduced: guarded.filter((e) => e.reintroduced).length, rate: ratio(guarded.filter((e) => e.reintroduced).length, guarded.length) },
+    guard: { tests_run: count("guard_run"), broken_caught: count("guard_broken"), supersedes_accepted: count("supersedes_accepted") },
+    decisions: { superseded: count("decision_superseded"), violations: count("decision_violation") },
+    low_n: Math.max(lanes.length, guarded.length) < minN,
+  };
+}
+
+/**
+ * Pure report. guards: parsed FORGE:GUARD objects; reopens: [{issue, ts}]; runs: toModel runs; events: toModel gate events;
+ * git: {time(sha)->epoch s|null, oldRanges(sha)->[{file,start,end}]|null, blame(rev,file,start,end)->[sha]|null}.
+ */
+export function compoundingReport({ guards = [], reopens = [], runs = [], events = [], git, windowMs = DEFAULT_WINDOW_MS, buckets = DEFAULT_BUCKETS, now = Date.now(), minN = 10 }) {
+  const merged = runs.filter((r) => r.reason === "merged").sort((a, b) => (ms(a.endTs) ?? 0) - (ms(b.endTs) ?? 0) || a.issue - b.issue);
+  const byIssue = new Map(merged.map((r, i) => [r.issue, { issue: r.issue, merged: true, rank: i + 1, version: r.version ?? null, at: ms(r.endTs), guarded: false, reopened: false, reintroduced: false }]));
+  const gset = new Map();
+  for (const g of guards) if (!gset.has(g.issue)) gset.set(g.issue, g);
+  const uniq = [...gset.values()];
+  for (const g of uniq) {
+    const e = byIssue.get(g.issue) ?? { issue: g.issue, merged: false, rank: null, version: null, at: null, guarded: false, reopened: false, reintroduced: false };
+    e.guarded = true;
+    const secs = git?.time && g.merge_sha ? git.time(g.merge_sha) : null;
+    if (e.at == null && secs != null) e.at = secs * 1000;
+    byIssue.set(g.issue, e);
+  }
+  for (const e of byIssue.values()) { // (a) and reopen-after-close: a reopen after the lane closed the issue
+    e.reopened = reopens.some((r) => r.issue === e.issue && (e.at == null || (ms(r.ts) ?? 0) > e.at));
+    if (e.guarded && e.reopened) e.reintroduced = true;
+  }
+  const lineage = git && uniq.length ? blameLineage(uniq, git) : { hits: [], unresolved: uniq.length };
+  for (const h of lineage.hits) if (byIssue.has(h.fix)) byIssue.get(h.fix).reintroduced = true;
+  const entries = [...byIssue.values()];
+  const have = Object.fromEntries(COUNTED_EVENTS.map((k) => [k, events.some((e) => e.event === k)]));
+  const evMs = (e) => ms(e.ts);
+  const out = { rolling: null, by_release: {}, by_lane_age: {}, sources: { guards: uniq.length, reopens: reopens.length, blame_hits: lineage.hits.length, blame_unresolved: lineage.unresolved }, buckets };
+  out.rolling = { window_days: Math.round(windowMs / DAY), ...summarize(entries.filter((e) => e.at != null && now - e.at <= windowMs && e.at <= now),
+    events.filter((e) => evMs(e) != null && now - evMs(e) <= windowMs && evMs(e) <= now), have, minN) };
+  const versions = [...new Set([...entries.map((e) => e.version), ...events.map((e) => e.version)].filter(Boolean))].sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
+  for (const v of versions) out.by_release[v] = summarize(entries.filter((e) => e.version === v), events.filter((e) => e.version === v), have, minN);
+  const labels = [...new Set(entries.map((e) => bucketLabel(e.rank, buckets)))];
+  const order = (l) => (l === "unranked" ? Infinity : Number.parseInt(l, 10));
+  for (const l of labels.sort((a, b) => order(a) - order(b))) {
+    const inB = entries.filter((e) => bucketLabel(e.rank, buckets) === l);
+    const evs = events.filter((e) => { const r = byIssue.get(e.issue); return r && bucketLabel(r.rank, buckets) === l; });
+    out.by_lane_age[l] = summarize(inB, evs, have, minN);
+  }
+  return out;
+}
+
+const pct = (x) => (x == null ? "n/a" : `${Math.round(x * 1000) / 10}%`);
+const n = (x) => (x == null ? "n/a" : String(x));
+function line(label, s) {
+  return `  ${label}: ${s.lanes} lanes, reintroduction ${pct(s.reintroduction.rate)} (${s.reintroduction.reintroduced}/${s.reintroduction.guarded}), reopen-after-close ${pct(s.reopen_after_close.rate)}, `
+    + `guard runs ${n(s.guard.tests_run)} broken ${n(s.guard.broken_caught)} supersedes ${n(s.guard.supersedes_accepted)}, decisions superseded ${n(s.decisions.superseded)} violations ${n(s.decisions.violations)}${s.low_n ? " (low n)" : ""}`;
+}
+
+export function renderCompounding(r) {
+  const rows = [`compounding: ${r.sources.guards} guards, ${r.sources.reopens} reopen events, ${r.sources.blame_hits} blame hits (${r.sources.blame_unresolved} guards unresolved)`,
+    line(`rolling ${r.rolling.window_days}d`, r.rolling), "by lane age:", ...Object.entries(r.by_lane_age).map(([k, s]) => line(k, s))];
+  const rel = Object.entries(r.by_release);
+  return [...rows, "by release:", ...(rel.length ? rel.map(([k, s]) => line(k, s)) : ["  n/a"])].join("\n");
+}
+
+const tryGit = (cwd, args) => { try { return execFileSync("git", ["-C", cwd, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], maxBuffer: 64 * 1024 * 1024 }); } catch { return null; } };
+
+/** git probes over a local clone; every miss (unknown sha, shallow clone) is null, never a thrown error. */
+export function gitProbes(cwd) {
+  return {
+    time: (sha) => { const t = Number(tryGit(cwd, ["show", "-s", "--format=%ct", sha])?.trim()); return Number.isFinite(t) && t > 0 ? t : null; },
+    oldRanges: (sha) => {
+      const d = tryGit(cwd, ["diff", "-U0", "--no-renames", `${sha}^`, sha]);
+      if (d == null) return null;
+      const out = []; let file = null;
+      for (const l of d.split("\n")) {
+        if (l.startsWith("--- ")) { file = l === "--- /dev/null" ? null : l.replace(/^--- a\//, ""); continue; }
+        const m = /^@@ -(\d+)(?:,(\d+))? \+/.exec(l);
+        if (m && file && m[2] !== "0") out.push({ file, start: Number(m[1]), end: Number(m[1]) + (m[2] === undefined ? 1 : Number(m[2])) - 1 });
+      }
+      return out;
+    },
+    blame: (rev, file, start, end) => {
+      const o = tryGit(cwd, ["blame", "--porcelain", "-L", `${start},${end}`, rev, "--", file]);
+      return o == null ? null : [...new Set(o.split("\n").filter((l) => /^[0-9a-f]{40} \d+ \d+/.test(l)).map((l) => l.slice(0, 40)))];
+    },
+  };
+}
+
+/** GitHub + git inputs for compoundingReport: guards from FORGE:GUARD comments, reopen events from one paginated events call. */
+export async function gatherCompounding({ repo, gh, cwd = process.cwd() }) {
+  const guards = await collectGuards({ gh, repo });
+  let reopens = [];
+  try {
+    reopens = parsePages(await gh(["api", "--paginate", `repos/${repo}/issues/events?per_page=100`]))
+      .filter((e) => e?.event === "reopened" && Number.isSafeInteger(e.issue?.number)).map((e) => ({ issue: e.issue.number, ts: e.created_at }));
+  } catch { /* events unreadable: reopen metrics read 0 reopens, shown with the count in sources */ }
+  return { guards, reopens, git: gitProbes(cwd) };
+}

package/bin/stats/compounding.test.mjs

@@ -0,0 +1,74 @@
+// 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 { compoundingReport, renderCompounding, bucketLabel, gitProbes } from "./compounding.mjs";
+import { parseArgs } from "./index.mjs";
+
+const NOW = Date.parse("2026-10-24T00:00:00Z"), DAY = 86400000, S = (d) => Math.floor((NOW - d * DAY) / 1000);
+const run = (issue, daysAgo, version = "1.0.0") => ({ issue, reason: "merged", version, endTs: new Date(NOW - daysAgo * DAY).toISOString() });
+const guard = (issue, sha) => ({ v: 1, issue, merge_sha: sha, tests: [{ path: "t.mjs", ids: [] }], hunks: [] });
+// shas: a (issue 1, 40d ago), b (issue 2, 10d ago), c (issue 3, 1d ago)
+const TIMES = { a: S(40), b: S(10), c: S(1) };
+const fakeGit = (blames = {}) => ({ time: (s) => TIMES[s] ?? null, oldRanges: (s) => [{ file: "f.mjs", start: 1, end: 3 }], blame: (rev) => blames[rev] ?? [] });
+const base = { runs: [run(1, 40), run(2, 10), run(3, 1)], guards: [guard(1, "a"), guard(2, "b"), guard(3, "c")], now: NOW, minN: 1 };
+
+test("reintroduction (b): a later fix whose old lines blame to an earlier fix within 90 days", () => {
+  const r = compoundingReport({ ...base, git: fakeGit({ "b^": ["a"] }) });
+  assert.deepEqual(r.rolling.reintroduction, { guarded: 2, reintroduced: 0, rate: 0 }); // 30d window holds fixes 2, 3; the broken fix is #1 (40d ago)
+  assert.equal(r.sources.blame_hits, 1);
+  const all = Object.values(r.by_lane_age)[0];
+  assert.deepEqual(all.reintroduction, { guarded: 3, reintroduced: 1, rate: 0.333 });
+});
+
+test("reintroduction (b): older than 90 days or unknown time does not count; unresolved is reported, not zeroed", () => {
+  const far = { ...base, guards: [guard(1, "a"), guard(2, "b")], runs: [run(1, 200), run(2, 10)] };
+  const r = compoundingReport({ ...far, git: { ...fakeGit({ "b^": ["a"] }), time: (s) => ({ a: S(200), b: S(10) })[s] ?? null } });
+  assert.equal(r.sources.blame_hits, 0);
+  const u = compoundingReport({ ...base, git: { time: () => null, oldRanges: () => null, blame: () => null } });
+  assert.equal(u.sources.blame_unresolved, 3);
+  assert.equal(u.sources.blame_hits, 0);
+});
+
+test("reintroduction (a) and reopen-after-close: reopen after the lane closed the issue", () => {
+  const reopens = [{ issue: 2, ts: new Date(NOW - 5 * DAY).toISOString() }, { issue: 3, ts: new Date(NOW - 3 * DAY).toISOString() /* before close? no: close was 1d ago */ }];
+  const r = compoundingReport({ ...base, reopens, git: fakeGit() });
+  assert.equal(r.rolling.reopen_after_close.reopened, 1); // issue 2 reopened after its close; issue 3's reopen predates its close
+  assert.equal(r.rolling.reintroduction.reintroduced, 1);
+  assert.equal(r.rolling.lanes, 2);
+});
+
+test("guard and decision counts are n/a until a kind is recorded, then counted per window", () => {
+  const none = compoundingReport({ ...base, git: fakeGit() });
+  assert.equal(none.rolling.guard.broken_caught, null);
+  assert.equal(none.rolling.decisions.violations, null);
+  const events = [{ event: "guard_broken", issue: 2, ts: new Date(NOW - DAY).toISOString(), version: "1.0.0" }, { event: "guard_broken", issue: 1, ts: new Date(NOW - 60 * DAY).toISOString(), version: "1.0.0" }];
+  const r = compoundingReport({ ...base, events, git: fakeGit() });
+  assert.equal(r.rolling.guard.broken_caught, 1);
+  assert.equal(r.rolling.guard.tests_run, null);
+  assert.equal(r.by_release["1.0.0"].guard.broken_caught, 2);
+});
+
+test("lane-age buckets by merge order and rendering", () => {
+  assert.deepEqual([1, 100, 101, 500, 501, null].map((n) => bucketLabel(n, [100, 500])), ["1-100", "1-100", "101-500", "101-500", "501+", "unranked"]);
+  const runs = Array.from({ length: 4 }, (_, i) => run(i + 1, 40 - i));
+  const r = compoundingReport({ runs, guards: [], buckets: [2], now: NOW, minN: 1, git: fakeGit() });
+  assert.deepEqual(Object.keys(r.by_lane_age), ["1-2", "3+"]);
+  assert.equal(r.by_lane_age["3+"].lanes, 2);
+  assert.match(renderCompounding(r), /by lane age:\n  1-2: 2 lanes, reintroduction n\/a \(0\/0\)/);
+});
+
+test("gitProbes degrades to null outside a repo or for an unknown sha", () => {
+  const g = gitProbes("/nonexistent-dir-for-compounding");
+  assert.equal(g.time("deadbeef"), null);
+  assert.equal(g.oldRanges("deadbeef"), null);
+  assert.equal(g.blame("deadbeef^", "x", 1, 2), null);
+});
+
+test("parseArgs: --compounding takes --window and --bucket; --bucket alone is rejected", () => {
+  const o = parseArgs(["--compounding", "--window", "30d", "--bucket", "50,200"]);
+  assert.equal(o.compounding, true);
+  assert.deepEqual(o.bucket, [50, 200]);
+  assert.throws(() => parseArgs(["--bucket", "10"]), /needs --compounding/);
+  assert.throws(() => parseArgs(["--compounding", "--bucket", "9,5"]), /increasing/);
+});