forgedock 1.16.2 → 1.18.0

package/bin/stats/github-source.mjs

@@ -0,0 +1,211 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Primary source for `forgedock stats` (forge#3835): the target repo's issues and PRs on GitHub.
+ * Reads labels and ONLY trusted `<!-- FORGE:TELEMETRY v1 -->` comments (same predicate as
+ * scripts/trusted-comments.sh: an author_association in FORGE_TRAIL_TRUSTED_ASSOCIATIONS, a Bot, or a login in
+ * FORGE_TRAIL_TRUSTED_LOGINS). Every `gh` call is argv-based (no shell). The `gh` runner is injectable for tests.
+ * Fetching is incremental: only items updated after the cached watermark (minus a small overlap window) are re-read.
+ */
+import { execFileSync } from "node:child_process";
+import { emptyCache, loadCache, saveCache } from "./cache.mjs";
+
+export const MARKER_RE = /^<!-- FORGE:TELEMETRY v1( part=(\d+))? -->/;
+const OWNER_REPO_RE = /^[\w.-]+\/[\w.-]+$/;
+export const isValidRepo = (r) => typeof r === "string" && OWNER_REPO_RE.test(r) && !r.split("/").some((p) => p === "." || p === "..");
+
+export function defaultGh(args) {
+  return execFileSync("gh", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 120000, maxBuffer: 256 * 1024 * 1024 });
+}
+
+/** `gh api --paginate` prints one JSON array per page; join them into one flat array. */
+export function parsePages(raw) {
+  const t = (raw ?? "").trim();
+  if (!t) return [];
+  return JSON.parse(`[${t.replace(/\]\s*\[/g, "],[")}]`).flat();
+}
+
+export function isTrusted(comment, env = process.env) {
+  const assoc = (env.FORGE_TRAIL_TRUSTED_ASSOCIATIONS ?? "OWNER,MEMBER,COLLABORATOR").split(",").map((s) => s.trim()).filter(Boolean);
+  const logins = (env.FORGE_TRAIL_TRUSTED_LOGINS ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+  return assoc.includes(comment?.author_association ?? "") || (comment?.user?.type ?? "") === "Bot" || logins.includes(comment?.user?.login ?? "");
+}
+
+/**
+ * Trusted FORGE:TELEMETRY comments -> record objects. Parts are all read (order is irrelevant), the fenced `jsonl`
+ * block is parsed line by line (a torn or invalid line is skipped), and records are deduped on `eid` (never on the
+ * line text: identical same-second events carry different ids).
+ */
+export function parseTelemetryComments(comments, env = process.env) {
+  const seen = new Set();
+  const out = [];
+  for (const c of comments) {
+    if (!MARKER_RE.test(c?.body ?? "") || !isTrusted(c, env)) continue;
+    const block = /```jsonl\n([\s\S]*?)(?:\n```|$)/.exec(c.body);
+    if (!block) continue;
+    for (const line of block[1].split("\n")) {
+      if (!line.trim()) continue;
+      let rec;
+      try { rec = JSON.parse(line); } catch { continue; }
+      if (!rec || typeof rec !== "object" || typeof rec.event !== "string" || typeof rec.eid !== "string" || seen.has(rec.eid)) continue;
+      seen.add(rec.eid);
+      out.push(rec);
+    }
+  }
+  return out;
+}
+
+const num = (x) => { const v = Number(x); return x != null && x !== "" && Number.isFinite(v) ? v : null; };
+
+/**
+ * Turn `phase_attempt` / `run_terminal` records into run summaries, finished only when a `run_terminal` exists.
+ * The run id is per engine process, so a `--retry` yields several; they collapse to ONE run per repo#issue, the latest
+ * by start timestamp (tie: greater run id), matching scripts/cost-report.sh (last RUN_START slice). Finished/usage
+ * filtering stays downstream, so an unfinished latest run still excludes the issue. Field names are the ones bin/engine/telemetry-seam.mjs writes (docs/TELEMETRY.md).
+ */
+export function runsFromRecords(records) {
+  const byRun = new Map();
+  for (const r of records) {
+    if ((r.event !== "phase_attempt" && r.event !== "run_terminal") || r.issue == null) continue;
+    const key = `${r.repo}#${r.issue}#${r.run ?? ""}`;
+    const run = byRun.get(key) ?? { source: "github", repo: r.repo ?? null, version: r.forge_version ?? null, issue: r.issue, run: r.run ?? null,
+      finished: false, hydrated: false, usageEvents: 0, reason: null, code: null, remediated: false, startTs: null, endTs: null, wallMs: null,
+      phases: {}, _first: null };
+    byRun.set(key, run);
+    if (!run._first || r.ts < run._first) run._first = r.ts;
+    if (r.event === "run_terminal") {
+      run.finished = true; run.reason = r.reason ?? null; run.code = r.code ?? null; run.endTs = r.ts ?? null; run.wallMs = num(r.wall_ms);
+      continue;
+    }
+    const id = r.phase ?? "other";
+    const p = (run.phases[id] ??= { cr: 0, out: 0, usd: null, ms: null, attempts: 0 });
+    const hasUsage = [r.input_tokens, r.output_tokens, r.cache_read_tokens].some((x) => num(x) != null);
+    if (hasUsage) run.usageEvents++;
+    p.cr += num(r.cache_read_tokens) ?? 0;
+    p.out += num(r.output_tokens) ?? 0;
+    p.attempts++;
+    if (num(r.duration_ms) != null) p.ms = (p.ms ?? 0) + num(r.duration_ms);
+    if (num(r.cost_usd) != null) p.usd = (p.usd ?? 0) + num(r.cost_usd);
+    if (id === "remediate") run.remediated = true;
+  }
+  const latest = new Map();
+  for (const run of byRun.values()) {
+    const k = `${run.repo}#${run.issue}`;
+    const cur = latest.get(k);
+    const a = run._first ?? "", b = cur?._first ?? "";
+    if (!cur || a > b || (a === b && (run.run ?? "") > (cur.run ?? ""))) latest.set(k, run);
+  }
+  return [...latest.values()].map(({ _first, ...run }) => ({ ...run, startTs: _first }));
+}
+
+/** Gate/review records (everything that is not a run record) become aggregate events. */
+export const gateEvents = (records) => records.filter((r) => r.event !== "phase_attempt" && r.event !== "run_terminal")
+  .map((r) => ({ ...r, version: r.forge_version ?? null }));
+
+const CHECKPOINT_EVERY = 25;
+const PAGE_SIZE = 100;
+// The next incremental run re-reads this much before the persisted watermark (an overlap window), so a write that races a
+// crawl or a small clock skew is re-listed. Re-reads are idempotent: items are keyed by issue number.
+const WATERMARK_OVERLAP_MS = 5 * 60 * 1000;
+const MAX_LIST_REQUESTS = 100000;
+
+/** Shift an ISO-8601 timestamp by `ms`; an unparsable value is returned unchanged. */
+export function shiftIso(ts, ms) {
+  const t = Date.parse(ts);
+  return Number.isNaN(t) ? ts : new Date(t + ms).toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
+const sinceParam = (ts) => encodeURIComponent(ts).replace(/%3A/g, ":");
+
+/**
+ * Keyset crawl of the issue listing. The listing is sorted by a MUTABLE key (updated_at), so page-number pagination
+ * (`gh --paginate`) can skip an item updated mid-crawl: it moves to the end of the ordering and the items behind it shift
+ * one page earlier. Instead every request is page 1 from `since=CURSOR`, the cursor moves to the newest `updated_at` read,
+ * and already-seen (number, updated_at) pairs are dropped (the `since` boundary is inclusive). A full page that cannot move
+ * the cursor (more than PAGE_SIZE items share one timestamp) is drained with `page=N` for that timestamp only.
+ * Yields each page's unseen items sorted updated-asc.
+ */
+function* listIssuePages(gh, repo, startSince) {
+  const base = ["state=all", "sort=updated", "direction=asc", `per_page=${PAGE_SIZE}`];
+  const seen = new Set();
+  const key = (it) => `${it.number}@${it.updated_at}`;
+  const take = (page) => {
+    const fresh = page.filter((it) => Number.isInteger(it?.number) && !seen.has(key(it)));
+    for (const it of fresh) seen.add(key(it));
+    return fresh.sort((a, b) => String(a.updated_at).localeCompare(String(b.updated_at)));
+  };
+  const maxTs = (page) => page.reduce((m, it) => (it?.updated_at && (!m || it.updated_at > m) ? it.updated_at : m), null);
+  let cursor = startSince ?? null;
+  for (let n = 0; n < MAX_LIST_REQUESTS; n++) {
+    const get = (extra = []) => parsePages(gh(["api", `repos/${repo}/issues?${[...base, ...(cursor ? [`since=${sinceParam(cursor)}`] : []), ...extra].join("&")}`]));
+    const page = get();
+    const fresh = take(page);
+    if (fresh.length > 0) yield fresh;
+    if (page.length < PAGE_SIZE) return;
+    const next = maxTs(page);
+    if (next && next !== cursor) { cursor = next; continue; }
+    // No cursor progress on a full page: drain this timestamp by page number, then step past it.
+    for (let p = 2; p < MAX_LIST_REQUESTS; p++) {
+      const more = get([`page=${p}`]);
+      const freshMore = take(more);
+      if (freshMore.length > 0) yield freshMore;
+      if (more.length < PAGE_SIZE || freshMore.length === 0) break;
+    }
+    if (!cursor) return;
+    cursor = shiftIso(cursor, 1000);
+  }
+}
+
+const meta = (it) => ({ number: it.number, isPr: Boolean(it.pull_request), createdAt: it.created_at ?? null, closedAt: it.closed_at ?? null,
+  updatedAt: it.updated_at ?? null, labels: (it.labels ?? []).map((l) => (typeof l === "string" ? l : l.name)).filter(Boolean), authorType: it.user?.type ?? null });
+
+/**
+ * Fetch (or incrementally refresh) the repo's issues, PRs and trusted telemetry records.
+ * Returns { items, records, fetched, fromCache }. `refresh` ignores the cache; `useCache:false` never touches disk.
+ */
+export function fetchGithubRecords({ repo, refresh = false, useCache = true, gh = defaultGh, env = process.env } = {}) {
+  if (!isValidRepo(repo)) throw new Error(`invalid repo: ${repo}`);
+  const cache = useCache && !refresh ? loadCache(repo, env) : emptyCache();
+  const startSince = cache.watermark ? shiftIso(cache.watermark, -WATERMARK_OVERLAP_MS) : null;
+  const items = { ...cache.items };
+  let watermark = cache.watermark;
+  let fetched = 0;
+  // Checkpoint: the watermark is the newest updated_at actually processed, and the next run starts WATERMARK_OVERLAP_MS
+  // before it, so it is a safe resume point. A failure mid-crawl (rate limit, 5xx, a hook timeout) then keeps the
+  // progress instead of restarting at zero.
+  const checkpoint = () => { if (useCache) saveCache(repo, { ...emptyCache(), watermark, items }, env); };
+  try {
+    for (const page of listIssuePages(gh, repo, startSince)) for (const it of page) {
+      const m = meta(it);
+      let records = items[it.number]?.records ?? [];
+      // A telemetry comment is edited in place (which may not bump the issue's updated_at), so every listed item with
+      // comments is re-read rather than trusting a cached copy.
+      if ((it.comments ?? 0) > 0) {
+        records = parseTelemetryComments(parsePages(gh(["api", "--paginate", `repos/${repo}/issues/${it.number}/comments`])), env);
+        fetched++;
+      }
+      items[it.number] = { ...m, records };
+      if (m.updatedAt && (!watermark || m.updatedAt > watermark)) watermark = m.updatedAt;
+      if (fetched > 0 && fetched % CHECKPOINT_EVERY === 0 && (it.comments ?? 0) > 0) checkpoint();
+    }
+  } catch (err) {
+    checkpoint();
+    throw err;
+  }
+  checkpoint();
+  const seen = new Set();
+  const records = [];
+  for (const it of Object.values(items)) for (const r of it.records ?? []) {
+    if (!seen.has(r.eid)) { seen.add(r.eid); records.push(r); }
+  }
+  return { items: Object.values(items), records, fetched, fromCache: cache.watermark != null };
+}
+
+/** Aggregate-model inputs for one repo from a fetch result. */
+export function toModel(repo, result) {
+  return {
+    runs: runsFromRecords(result.records.map((r) => ({ ...r, repo: r.repo ?? repo }))),
+    events: gateEvents(result.records.map((r) => ({ ...r, repo: r.repo ?? repo }))),
+    issues: result.items.map((i) => ({ repo, number: i.number, isPr: i.isPr, createdAt: i.createdAt, closedAt: i.closedAt, labels: i.labels, authorType: i.authorType })),
+  };
+}

package/bin/stats/index.mjs

@@ -0,0 +1,154 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * forgedock stats (forge#3835): a deterministic version-over-version report, no model in the loop.
+ * GitHub is the primary source (trusted FORGE:TELEMETRY comments + labels); ~/.forge/stats-cache is an optional,
+ * deletable cache; ~/.forge/runs is an optional extra source for runs that predate telemetry.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { aggregate, DEFAULT_MIN_N } from "./aggregate.mjs";
+import { fetchGithubRecords, isValidRepo, toModel } from "./github-source.mjs";
+import { readLocalRuns, runsDir } from "./local-source.mjs";
+import { renderCompact, renderJson, renderMarkdown } from "./render.mjs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+export const HELP = `Usage: forgedock stats [--since <version|date>] [--repo <owner/repo>] [--json] [--refresh]
+                      [--compact] [--no-local] [--no-cache] [--min-n N] [--release-times FILE]
+
+Version-over-version report: Cost, Time, Flow, Review funnel, Gates and Issue flow per (version, repo), with a
+delta against the previous version and a low-n flag for samples under 10. Missing data prints n/a.
+
+  --since <v|date>      only versions >= <v> (e.g. 1.16.0) or activity on/after <date> (YYYY-MM-DD)
+  --repo <owner/repo>   target repo (default: forge.yaml project, else the git origin remote)
+  --json                machine-readable output
+  --refresh             ignore the local cache and re-read everything from GitHub
+  --compact             one-row-per-version table (embedded in the staging review summary)
+  --no-local            ignore ~/.forge/runs (FORGE_RUNS_DIR)
+  --no-cache            do not read or write ~/.forge/stats-cache
+  --min-n N             low-n threshold (default ${DEFAULT_MIN_N})
+  --release-times FILE  "<version> <epoch-seconds>" lines used to estimate versions of unversioned records
+                        (default: git tags v* of the ForgeDock checkout)
+`;
+
+export function parseArgs(argv) {
+  const o = { since: null, repo: null, json: false, refresh: false, compact: false, local: true, cache: true, minN: DEFAULT_MIN_N, releaseTimes: null, help: false };
+  const val = (i, name) => {
+    const v = argv[i + 1];
+    if (v == null || v.startsWith("--")) throw new Error(`${name} needs a value`);
+    return v;
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const eq = a.startsWith("--") && a.includes("=") ? [a.slice(0, a.indexOf("=")), a.slice(a.indexOf("=") + 1)] : null;
+    const name = eq ? eq[0] : a;
+    const take = () => { if (eq) return eq[1]; const v = val(i, name); i++; return v; };
+    if (name === "--since") o.since = take();
+    else if (name === "--repo") o.repo = take();
+    else if (name === "--release-times") o.releaseTimes = take();
+    else if (name === "--min-n") { const v = take(); if (!/^\d+$/.test(v)) throw new Error("--min-n must be a non-negative integer"); o.minN = Number(v); }
+    else if (name === "--json") o.json = true;
+    else if (name === "--refresh") o.refresh = true;
+    else if (name === "--compact") o.compact = true;
+    else if (name === "--no-local") o.local = false;
+    else if (name === "--no-cache") o.cache = false;
+    else if (name === "--help" || name === "-h") o.help = true;
+    else throw new Error(`unknown argument: ${a}`);
+  }
+  return o;
+}
+
+/** "--since" is a date (YYYY-MM-DD[...]) or a version (1.16.0). */
+export function parseSince(since) {
+  if (!since) return {};
+  if (/^\d{4}-\d{2}-\d{2}/.test(since)) {
+    const ms = Date.parse(since);
+    if (Number.isNaN(ms)) throw new Error(`invalid --since date: ${since}`);
+    return { sinceMs: ms };
+  }
+  if (/^v?\d+(\.\d+)*$/.test(since)) return { sinceVersion: since.replace(/^v/, "") };
+  throw new Error(`--since must be a version (1.16.0) or a date (YYYY-MM-DD): ${since}`);
+}
+
+export function parseReleaseTimes(text) {
+  return String(text ?? "").split("\n").map((l) => l.trim().split(/\s+/))
+    .filter((p) => p.length === 2 && /^\d+$/.test(p[1])).map((p) => ({ v: p[0].replace(/^v/, ""), t: Number(p[1]) }));
+}
+
+function gitTagTimes() {
+  try {
+    const out = execFileSync("git", ["-C", join(here, "..", ".."), "for-each-ref", "refs/tags", "--format=%(refname:short) %(creatordate:unix)"],
+      { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    return parseReleaseTimes(out.split("\n").filter((l) => /^v\d/.test(l)).join("\n"));
+  } catch { return []; }
+}
+
+/** --repo, else forge.yaml project.owner/repo, else the git origin remote. */
+export function resolveRepo(explicit, cwd = process.cwd()) {
+  if (explicit) return explicit;
+  for (const f of ["forge.yaml", ".forge.yaml"]) {
+    const p = join(cwd, f);
+    if (!existsSync(p)) continue;
+    try {
+      const m = /^project:\s*\n((?:[ \t]+.*\n?|\s*\n)*)/m.exec(readFileSync(p, "utf8"));
+      const owner = /^[ \t]+owner:\s*"?([\w.-]+)"?/m.exec(m?.[1] ?? "")?.[1];
+      const repo = /^[ \t]+repo:\s*"?([\w.-]+)"?/m.exec(m?.[1] ?? "")?.[1];
+      if (owner && repo) return `${owner}/${repo}`;
+    } catch { /* fall through */ }
+  }
+  try {
+    const url = execFileSync("git", ["-C", cwd, "remote", "get-url", "origin"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    const m = /[:/]([\w.-]+)\/([\w.-]+?)(?:\.git)?$/.exec(url);
+    if (m) return `${m[1]}/${m[2]}`;
+  } catch { /* none */ }
+  return null;
+}
+
+/** Build the report object. deps: { gh, env, localRuns, now } for tests. Never touches the network when `gh` is stubbed. */
+export function buildReport(opts, deps = {}) {
+  const env = deps.env ?? process.env;
+  const repo = opts.repo;
+  const gh = fetchGithubRecords({ repo, refresh: opts.refresh, useCache: opts.cache, gh: deps.gh, env });
+  const model = toModel(repo, gh);
+  const ghKeys = new Set(model.runs.map((r) => `${r.repo}#${r.issue}`));
+  let local = [];
+  if (opts.local) {
+    local = (deps.localRuns ?? readLocalRuns(runsDir(env))).filter((r) => r.repo === repo && !ghKeys.has(`${r.repo}#${r.issue}`));
+  }
+  let releaseTimes = [];
+  if (opts.releaseTimes) releaseTimes = parseReleaseTimes(readFileSync(opts.releaseTimes, "utf8"));
+  else if (deps.releaseTimes) releaseTimes = deps.releaseTimes;
+  else releaseTimes = gitTagTimes();
+  const report = aggregate({ runs: [...model.runs, ...local], events: model.events, issues: model.issues },
+    { minN: opts.minN, releaseTimes, ...parseSince(opts.since) });
+  return { repo, sources: { github: { items: gh.items.length, records: gh.records.length, cached: gh.fromCache }, local: { runs: local.length } }, ...report };
+}
+
+export async function runStats(argv, deps = {}) {
+  let opts;
+  try { opts = parseArgs(argv); } catch (err) {
+    process.stderr.write(`forgedock stats: ${err.message}\n\n${HELP}`);
+    return 2;
+  }
+  if (opts.help) { process.stdout.write(HELP); return 0; }
+  opts.repo = resolveRepo(opts.repo);
+  if (!opts.repo || !isValidRepo(opts.repo)) {
+    process.stderr.write(`forgedock stats: could not resolve a valid owner/repo (pass --repo owner/repo)\n`);
+    return 2;
+  }
+  try {
+    const report = buildReport(opts, deps);
+    process.stdout.write(`${opts.json ? renderJson(report) : opts.compact ? renderCompact(report) : renderMarkdown(report)}\n`);
+    return 0;
+  } catch (err) {
+    process.stderr.write(`forgedock stats: ${err.message}\n`);
+    return 1;
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  process.exitCode = await runStats(process.argv.slice(2));
+}

package/bin/stats/local-source.mjs

@@ -0,0 +1,79 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Optional extra source for `forgedock stats` (forge#3835): the engine run logs in ~/.forge/runs (FORGE_RUNS_DIR).
+ * Needed only for runs that predate the GitHub `phase_attempt` / `run_terminal` records. Same counting rules as
+ * scripts/cost-report.sh. Old logs lack `ts`, `code`, `version` and `repo`: those fields become null.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const runsDir = (env = process.env) => env.FORGE_RUNS_DIR || join(homedir(), ".forge", "runs");
+
+function parseLog(text) {
+  const out = [];
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    try { const e = JSON.parse(line); if (e && typeof e === "object") out.push(e); } catch { /* truncated or corrupt line */ }
+  }
+  return out;
+}
+
+const n = (x) => (Number.isFinite(x) ? x : 0);
+
+/** Summarise one log: the last RUN_START..end slice. Returns null when there is no RUN_START. */
+export function summariseLog(events, fallbackIssue = null) {
+  let s = -1;
+  events.forEach((e, i) => { if (e.event === "RUN_START") s = i; });
+  if (s < 0) return null;
+  const ev = events.slice(s);
+  const start = ev[0];
+  let t = -1; let r = -1;
+  ev.forEach((e, i) => {
+    if (e.event === "RUN_TERMINAL") t = i;
+    if (e.event === "RUN_REOPEN" || e.event === "RUN_NEXT_CYCLE") r = i;
+  });
+  const attemptPhases = new Set(ev.filter((e) => e.event === "PHASE_ATTEMPT_USAGE").map((e) => e.phase));
+  const phases = {};
+  let usageEvents = 0;
+  for (const e of ev) {
+    const attempt = e.event === "PHASE_ATTEMPT_USAGE";
+    const legacy = (e.event === "PHASE_COMMIT" || e.event === "PHASE_FAILED") && !attemptPhases.has(e.phase);
+    if (!(attempt || legacy) || !e.usage || typeof e.usage !== "object") continue;
+    usageEvents++;
+    const p = (phases[e.phase ?? "other"] ??= { cr: 0, out: 0, usd: null, ms: null, attempts: 0 });
+    p.cr += n(e.usage.cache_read_input_tokens);
+    p.out += n(e.usage.output_tokens);
+    p.attempts++;
+    if (attempt && Number.isFinite(e.duration_ms)) p.ms = (p.ms ?? 0) + e.duration_ms;
+    if (attempt && Number.isFinite(e.cost_usd)) p.usd = (p.usd ?? 0) + e.cost_usd;
+  }
+  const finished = t >= 0 && (r < 0 || t > r);
+  const startTs = start.ts ?? null;
+  const endTs = finished ? ev[t].ts ?? null : null;
+  const a = Date.parse(startTs ?? ""); const b = Date.parse(endTs ?? "");
+  return {
+    source: "local", repo: start.repo ?? null, version: start.version ?? null, issue: start.issue ?? fallbackIssue, run: start.run ?? null,
+    finished, hydrated: start.hydrated === true, usageEvents,
+    reason: finished ? ev[t].reason ?? null : null, code: finished ? ev[t].code ?? null : null,
+    remediated: ev.some((e) => e.event === "PHASE_COMMIT" && e.phase === "remediate"),
+    startTs, endTs, wallMs: finished && !Number.isNaN(a) && !Number.isNaN(b) ? Math.max(0, b - a) : null,
+    phases,
+  };
+}
+
+/** All run summaries in `dir` (a missing dir or an unreadable log yields nothing, never an error). */
+export function readLocalRuns(dir = runsDir()) {
+  if (!existsSync(dir)) return [];
+  const runs = [];
+  for (const f of readdirSync(dir).sort()) {
+    if (!f.endsWith(".jsonl")) continue;
+    try {
+      const m = /^(\d+)\.jsonl$/.exec(f);
+      const sum = summariseLog(parseLog(readFileSync(join(dir, f), "utf8")), m ? Number(m[1]) : null);
+      if (sum) runs.push({ ...sum, mtimeTs: new Date(statSync(join(dir, f)).mtimeMs).toISOString() });
+    } catch { /* unreadable log */ }
+  }
+  return runs;
+}

package/bin/stats/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "forgedock-stats",
+  "private": true,
+  "description": "Directory entry so `node --test bin/stats/` runs the stats suite on Node versions that treat a directory argument as a module path.",
+  "main": "stats.test.mjs"
+}

package/bin/stats/render.mjs

@@ -0,0 +1,82 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** Rendering for `forgedock stats` (forge#3835): full markdown, compact table (review-pr-staging) and JSON. */
+
+const NA = "n/a";
+const isNum = (x) => typeof x === "number" && Number.isFinite(x);
+const k = (x) => (isNum(x) ? `${Math.round(x / 1000)}k` : NA);
+const pct = (x) => (isNum(x) ? `${Math.round(x * 100)}%` : NA);
+const usd = (x) => (isNum(x) ? `$${x.toFixed(2)}` : NA);
+const f1 = (x) => (isNum(x) ? (Math.round(x * 10) / 10).toString() : NA);
+const dur = (ms) => {
+  if (!isNum(ms)) return NA;
+  const s = ms / 1000;
+  if (s < 90) return `${Math.round(s)}s`;
+  if (s < 5400) return `${Math.round(s / 60)}m`;
+  return `${f1(s / 3600)}h`;
+};
+const signed = (x, fmt) => (isNum(x) ? `${x > 0 ? "+" : x < 0 ? "-" : ""}${fmt(Math.abs(x))}` : NA);
+const dpp = (x) => signed(x, (v) => `${Math.round(v * 100)}pp`);
+const flag = (g) => (g.lowN ? ` (low-n <${g.minN})` : "");
+const table = (head, rows) => [`| ${head.join(" | ")} |`, `|${head.map(() => "---").join("|")}|`, ...rows.map((r) => `| ${r.join(" | ")} |`)];
+
+export const renderJson = (report) => JSON.stringify(report, null, 2);
+
+const label = (g) => `${g.version} / ${g.repo}`;
+
+function sections(g) {
+  const out = [`## ${label(g)}  n=${g.n}${flag(g)}`, ""];
+  const c = g.cost;
+  out.push("### Cost", ...table(["metric", "value"], [
+    ["cache-read tokens per issue (mean / median)", `${k(c.cacheReadMean)} / ${k(c.cacheReadMedian)}`],
+    ["output tokens per issue (mean)", k(c.outputMean)],
+    ["per phase (mean)", Object.entries(c.perPhase).filter(([, v]) => isNum(v)).map(([p, v]) => `${p} ${k(v)}`).join(", ") || NA],
+    ["cache-read tokens per merged issue", k(c.perMergedIssue)],
+    ["USD per issue (n=" + c.usdN + ")", usd(c.usdMean)],
+  ]), "");
+  const t = g.time;
+  const phaseRows = Object.entries(t.phases).map(([p, v]) => [p, String(v.n), dur(v.p50), dur(v.p90)]);
+  out.push("### Time", ...table(["phase", "n", "p50", "p90"], [...phaseRows, ["wall per issue", String(t.wall.n), dur(t.wall.p50), dur(t.wall.p90)]]), "");
+  const f = g.flow;
+  out.push("### Flow", ...table(["metric", "value"], [
+    ["merged", pct(f.mergedPct)], ["needs-human", pct(f.needsHumanPct)], ["remediation rate", pct(f.remediationPct)],
+    ["top outcome codes (n=" + f.codesN + ")", f.codes.slice(0, 5).map((x) => `${x.code} ${x.count} (${pct(x.pct)})`).join(", ") || NA],
+  ]), "");
+  const r = g.funnel;
+  const sev = Object.entries(r.bySeverity).map(([s, d]) => [s, String(d.total), f1(d.perReview), String(d.ISSUE), String(d.NOTE), String(d.INPR_FIX)]);
+  out.push("### Review funnel", `${r.reviews} reviews, ${r.findings} findings (${f1(r.perReview)} per review). Validated issues: ${r.validated}, false positives: ${r.falsePositive}.`, "",
+    ...(sev.length ? table(["severity", "findings", "per review", "ISSUE", "NOTE", "in-PR fix"], sev) : [`No finding records: ${NA}`]), "");
+  const q = g.gates;
+  const rate = (x) => (x.n ? `${pct(x.rate)} (${x.blocked}/${x.n})` : NA);
+  out.push("### Gates", ...table(["gate", "block rate"], [
+    ["acceptance", rate(q.acceptance)], ["diff size (OVER)", rate(q.diffSize)], ["ci", rate(q.ci)], ["liveness", rate(q.liveness)],
+  ]), `Malformed-check rate: ${pct(q.malformedRate)}. Diff size: COHESIVE ${q.diffSize.cohesive}, OVER ${q.diffSize.over}.`, "");
+  const i = g.issueFlow;
+  const kv = (o) => Object.entries(o).map(([a, b]) => `${a} ${b}`).join(", ") || NA;
+  out.push("### Issue flow", ...table(["metric", "value"], [
+    ["created by source", kv(i.created)], ["closed by kind", kv(i.closed)],
+    ["net flow (created - closed)", isNum(i.net) ? signed(i.net, String) : NA], ["findings per merged issue", f1(i.findingsPerMerge)],
+  ]), "");
+  if (g.delta) {
+    const d = g.delta;
+    out.push(`Delta vs ${d.against}: cache-read/issue ${signed(d.cacheReadMean, k)}, merged ${dpp(d.mergedPct)}, needs-human ${dpp(d.needsHumanPct)}, remediation ${dpp(d.remediationPct)}, wall p50 ${signed(d.wallP50, dur)}`, "");
+  } else out.push(`Delta: ${NA} (no previous version)`, "");
+  return out;
+}
+
+export function renderMarkdown(report) {
+  const out = ["# ForgeDock stats", ""];
+  if (!report.groups.length) out.push("No data: no finished runs, telemetry records or issues were found.", "");
+  for (const g of report.groups) out.push(...sections(g));
+  const e = report.excluded;
+  out.push(`Finished runs only. Excluded: ${e.unfinished} unfinished, ${e.noUsage} without usage data (hydrated or empty). "~" = version estimated from release times; "unknown" = no version available. Groups with n < ${report.minN} are flagged low-n.`);
+  return out.join("\n");
+}
+
+/** One row per (version, repo): the embedded table for the staging review summary. */
+export function renderCompact(report) {
+  if (!report.groups.length) return "No stats data.";
+  const rows = report.groups.map((g) => [g.version, g.repo, String(g.n), k(g.cost.cacheReadMean), pct(g.flow.mergedPct), pct(g.flow.needsHumanPct),
+    pct(g.flow.remediationPct), dur(g.time.wall.p50), f1(g.funnel.perReview), pct(g.gates.acceptance.rate), g.delta ? signed(g.delta.cacheReadMean, k) : NA, g.lowN ? `low-n (<${g.minN})` : "ok"]);
+  return table(["Version", "Repo", "n", "Cache-read/issue", "Merged", "Needs-human", "Remediated", "Wall p50", "Findings/review", "Acceptance block", "Delta tokens", "Confidence"], rows).join("\n");
+}