omp-conductor 0.15.10 → 0.15.12

package/src/stats.ts

@@ -0,0 +1,331 @@
+/**
+ * `stats` — what the fleet accomplished and at what cost, over a window
+ * (#282, legibility 5/5).
+ *
+ * Pure by construction: every fact arrives as injected run rows, a window and
+ * a gh-call count, so the aggregation is testable without a daemon or a store
+ * (the same seam split `doctor` uses). The CLI command in ./commands/stats.ts
+ * supplies the rows through read-only store queries, then renders the same
+ * numbers the --json shape carries.
+ *
+ * The unit of outcome is the **issue journey**, never the run row: an issue
+ * that took six attempts is one merged outcome with six runs and one lead
+ * time. Counting rows would make a stranded issue look like productive
+ * throughput, which is the exact misreading this surface exists to prevent.
+ *
+ * Spend semantics follow the store's own convention (README Limitations, and
+ * the doctor `spend-telemetry` finding): a run whose `spendUsd` reads 0.00
+ * means harness telemetry was absent, not that the run was free. Such runs are
+ * counted separately as **unmetered** and never averaged into a per-issue cost.
+ */
+
+import type { RunRecord } from "./types.ts";
+
+/** The bounded window a report answers over. Day keys are UTC (`YYYY-MM-DD`). */
+export interface StatsWindow {
+  sinceDay: string;
+  untilDay: string;
+  sinceEpochMs: number;
+  untilEpochMs: number;
+}
+
+/** One aggregate, per repo and for the whole selection. */
+export interface RepoStats {
+  /** The repo name; `"(all)"` on the totals row. */
+  repo: string;
+  /** Distinct issues whose PR merged and settled inside the window. */
+  merged: number;
+  /** `merged` plus issues whose terminal state inside the window did not merge. */
+  settled: number;
+  /** `merged / settled`; `null` when nothing settled (never a fake 0). */
+  mergeRate: number | null;
+  /** Mean attempts per merged issue, over the whole continuation chain. */
+  runsPerMerged: number | null;
+  /** First queue-label claim → merge settlement, over merged issues, in ms. */
+  leadTimeMedianMs: number | null;
+  leadTimeP90Ms: number | null;
+  /** Metered (spendUsd > 0) spend across merged chains, rounded to cents. */
+  spendUsd: number;
+  /** `spendUsd / merged issues with ≥1 metered run`; null when none. */
+  spendPerMerged: number | null;
+  /** Runs examined with `spendUsd === 0` — telemetry absent, not free. */
+  unmeteredRuns: number;
+  /** Merged issues whose whole chain metered nothing — cost unknown, not $0. */
+  unmeteredMerged: number;
+  /** Terminal non-merged runs in the window, bucketed by failure class. */
+  failureClasses: Record<string, number>;
+}
+
+/** The stable report shape `--json` prints; the human renderer reads it too. */
+export interface StatsReport {
+  project: string;
+  window: StatsWindow;
+  /** Tracked GitHub API calls over the window's UTC days (#198). */
+  ghCalls: number;
+  /**
+   * True when nothing settled in the window: a fresh store or an idle fleet.
+   * A consumer must render this as "no measurements", never as zero outcomes.
+   */
+  empty: boolean;
+  /** The whole selection (`--project NAME`, or the sole configured project). */
+  total: RepoStats;
+  /** Per-repo aggregates of the same shape, busiest (by merges) first. */
+  repos: RepoStats[];
+}
+
+/** Terminal non-merged run states — everything the failure histogram counts. */
+const FAILED_STATES: ReadonlySet<RunRecord["state"]> = new Set([
+  "failed",
+  "blocked",
+  "killed",
+  "orphaned",
+  "stopped",
+]);
+
+/** Runs with no classified failure fall into this explicit bucket. */
+export const UNCLASSIFIED = "unclassified";
+
+/** The timestamp a run is placed on the window timeline. Mirrors the store's
+ *  `COALESCE(endedAt, startedAt)` convention everywhere else in this package. */
+const WINDOW_KEY = (run: RunRecord): number => run.endedAt ?? run.startedAt;
+
+/** One issue's settled outcome, reduced from its full attempt chain. */
+interface IssueOutcome {
+  repo: string;
+  merged: boolean;
+  /** Attempts in the whole chain (continuations collapse into one journey). */
+  attempts: number;
+  /** First claim → merge settlement, in ms. Present iff `merged`. */
+  leadTimeMs?: number;
+  /** Sum of metered (spendUsd > 0) spend across the chain, in USD. */
+  meteredSpend: number;
+  /** Runs in the chain whose spend actually metered. */
+  meteredRuns: number;
+}
+
+function median(sorted: readonly number[]): number {
+  if (sorted.length === 0) return Number.NaN;
+  const lo = sorted[Math.floor((sorted.length - 1) / 2)]!;
+  const hi = sorted[Math.ceil((sorted.length - 1) / 2)]!;
+  return (lo + hi) / 2;
+}
+
+/** Nearest-rank p90: at least 90% of the samples are at or below the result. */
+function p90(sorted: readonly number[]): number {
+  if (sorted.length === 0) return Number.NaN;
+  return sorted[Math.min(sorted.length - 1, Math.ceil(0.9 * sorted.length) - 1)]!;
+}
+
+function cents(usd: number): number {
+  return Math.round(usd * 100) / 100;
+}
+
+function emptyRepo(repo: string): RepoStats {
+  return {
+    repo,
+    merged: 0,
+    settled: 0,
+    mergeRate: null,
+    runsPerMerged: null,
+    leadTimeMedianMs: null,
+    leadTimeP90Ms: null,
+    spendUsd: 0,
+    spendPerMerged: null,
+    unmeteredRuns: 0,
+    unmeteredMerged: 0,
+    failureClasses: {},
+  };
+}
+
+/**
+ * Aggregate one repo's settled issues and failure runs into {@link RepoStats}.
+ * Lead times and per-issue cost are reported only where a merged issue exists;
+ * `null` is "not measured", never a zero that could read as a measurement.
+ */
+function summarize(args: {
+  repo: string;
+  outcomes: readonly IssueOutcome[];
+  failureRuns: readonly { repo: string; cls: string }[];
+  unmeteredRuns: number;
+}): RepoStats {
+  const out = emptyRepo(args.repo);
+  const merged = args.outcomes.filter((o) => o.merged);
+  const leadTimes = merged
+    .map((o) => o.leadTimeMs!)
+    .sort((a, b) => a - b);
+  const meteredMerged = merged.filter((o) => o.meteredRuns > 0);
+  const meteredSpend = merged.reduce((sum, o) => sum + o.meteredSpend, 0);
+
+  out.merged = merged.length;
+  out.settled = args.outcomes.length;
+  out.mergeRate = args.outcomes.length === 0 ? null : merged.length / args.outcomes.length;
+  if (merged.length > 0) {
+    out.runsPerMerged = merged.reduce((sum, o) => sum + o.attempts, 0) / merged.length;
+    out.leadTimeMedianMs = Math.round(median(leadTimes));
+    out.leadTimeP90Ms = Math.round(p90(leadTimes));
+  }
+  out.spendUsd = cents(meteredSpend);
+  out.spendPerMerged = meteredMerged.length === 0 ? null : cents(meteredSpend / meteredMerged.length);
+  out.unmeteredMerged = merged.filter((o) => o.meteredRuns === 0).length;
+  out.unmeteredRuns = args.unmeteredRuns;
+  for (const run of args.failureRuns) {
+    out.failureClasses[run.cls] = (out.failureClasses[run.cls] ?? 0) + 1;
+  }
+  return out;
+}
+
+/**
+ * Compute the report from store rows. `runs` is whatever the store's
+ * stats-window query returned for the project: rows settling at or after
+ * `window.sinceEpochMs`, plus the full chain of every issue whose merge
+ * settled there. Rows within an issue must be ordered by `startedAt`, so the
+ * first row of a chain is its first queue-label claim.
+ */
+export function computeStats(args: {
+  project: string;
+  window: StatsWindow;
+  ghCalls: number;
+  runs: readonly RunRecord[];
+}): StatsReport {
+  const chains = new Map<number, RunRecord[]>();
+  for (const run of args.runs) {
+    const chain = chains.get(run.issue);
+    if (chain === undefined) chains.set(run.issue, [run]);
+    else chain.push(run);
+  }
+
+  const outcomes: IssueOutcome[] = [];
+  const byRepo = new Map<string, IssueOutcome[]>();
+  const failureRuns: { repo: string; cls: string }[] = [];
+  let unmeteredRuns = 0;
+  const unmeteredByRepo = new Map<string, number>();
+
+  for (const chain of chains.values()) {
+    // One issue merges once; if a weird history ever carried two merged rows,
+    // the newest settlement wins.
+    let merged: RunRecord | undefined;
+    for (const run of chain) {
+      if (
+        run.state === "merged" &&
+        (merged === undefined || WINDOW_KEY(run) > WINDOW_KEY(merged))
+      ) {
+        merged = run;
+      }
+    }
+
+    const terminatedInWindow = chain.some(
+      (run) => FAILED_STATES.has(run.state) && WINDOW_KEY(run) >= args.window.sinceEpochMs,
+    );
+    // A chain appears in the result for two reasons: its merge settled in the
+    // window, or an individual run ended there. Without a merged row and
+    // without a terminal row in the window it is still in flight — news, not
+    // an outcome.
+    if (merged === undefined && !terminatedInWindow) continue;
+
+    for (const run of chain) {
+      if (run.spendUsd === 0) {
+        unmeteredRuns += 1;
+        unmeteredByRepo.set(run.repo, (unmeteredByRepo.get(run.repo) ?? 0) + 1);
+      }
+      if (merged === undefined && FAILED_STATES.has(run.state) && WINDOW_KEY(run) >= args.window.sinceEpochMs) {
+        failureRuns.push({ repo: run.repo, cls: run.failureClass ?? UNCLASSIFIED });
+      }
+    }
+
+    const claimAt = chain[0]!.startedAt;
+    const mergedAt = merged === undefined ? undefined : WINDOW_KEY(merged);
+    const repo =
+      merged?.repo ??
+      chain.find((r) => FAILED_STATES.has(r.state) && WINDOW_KEY(r) >= args.window.sinceEpochMs)!.repo;
+    const outcome: IssueOutcome = {
+      repo,
+      merged: merged !== undefined,
+      attempts: chain.length,
+      leadTimeMs: mergedAt === undefined ? undefined : Math.max(0, mergedAt - claimAt),
+      meteredSpend: chain.reduce((sum, run) => sum + (run.spendUsd > 0 ? run.spendUsd : 0), 0),
+      meteredRuns: chain.filter((run) => run.spendUsd > 0).length,
+    };
+    outcomes.push(outcome);
+    const bucket = byRepo.get(repo);
+    if (bucket === undefined) byRepo.set(repo, [outcome]);
+    else bucket.push(outcome);
+  }
+
+  const repos = [...byRepo.entries()]
+    .map(([repo, list]) =>
+      summarize({
+        repo,
+        outcomes: list,
+        failureRuns: failureRuns.filter((r) => r.repo === repo),
+        unmeteredRuns: unmeteredByRepo.get(repo) ?? 0,
+      }),
+    )
+    .sort((a, b) => b.merged - a.merged || b.settled - a.settled || a.repo.localeCompare(b.repo));
+
+  return {
+    project: args.project,
+    window: args.window,
+    ghCalls: args.ghCalls,
+    empty: outcomes.length === 0,
+    total: summarize({ repo: "(all)", outcomes, failureRuns, unmeteredRuns }),
+    repos,
+  };
+}
+
+/** `N` and its unit, for a count line that must not print "0" as a measure. */
+function countLine(n: number, noun: string, plural: string): string {
+  return `${n} ${n === 1 ? noun : plural}`;
+}
+
+function humanDuration(ms: number): string {
+  const s = Math.max(0, Math.round(ms / 1000));
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ${String(s % 60).padStart(2, "0")}s`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ${String(m % 60).padStart(2, "0")}m`;
+  return `${Math.floor(h / 24)}d ${String(h % 24).padStart(2, "0")}h`;
+}
+
+function renderRepo(repo: RepoStats, indent: string): string {
+  const lines: string[] = [];
+  const leadTimeMedian = repo.leadTimeMedianMs;
+  const leadTimeP90 = repo.leadTimeP90Ms;
+  const lead =
+    leadTimeMedian === null || leadTimeP90 === null
+      ? "—"
+      : `median ${humanDuration(leadTimeMedian)} · p90 ${humanDuration(leadTimeP90)}`;
+  const cost =
+    repo.spendPerMerged === null
+      ? `$${repo.spendUsd.toFixed(2)} metered on merged work (no metered merge to divide by)`
+      : `$${repo.spendUsd.toFixed(2)} metered ($${repo.spendPerMerged.toFixed(2)}/merged)`;
+  const unmetered: string[] = [];
+  if (repo.unmeteredRuns > 0) unmetered.push(`${countLine(repo.unmeteredRuns, "run", "runs")} unmetered`);
+  if (repo.unmeteredMerged > 0) unmetered.push(`${countLine(repo.unmeteredMerged, "merged issue", "merged issues")} never metered`);
+  const rates = repo.mergeRate === null ? "nothing settled" : `${(repo.mergeRate * 100).toFixed(1)}% of ${repo.settled} settled`;
+  const attempts = repo.runsPerMerged === null ? "—" : `${repo.runsPerMerged.toFixed(2)} per merged issue`;
+  lines.push(`${indent}${repo.repo}  merged ${repo.merged} (${rates})`);
+  lines.push(`${indent}  lead       ${lead} (first claim → merge)`);
+  lines.push(`${indent}  attempts   ${attempts}`);
+  lines.push(`${indent}  cost       ${cost}${unmetered.length === 0 ? "" : ` · ${unmetered.join(" · ")}`}`);
+  const classes = Object.entries(repo.failureClasses).sort((a, b) => b[1] - a[1]);
+  if (classes.length > 0) {
+    lines.push(`${indent}  failures   ${classes.map(([cls, n]) => `${cls}: ${n}`).join(" · ")}`);
+  }
+  return lines.join("\n");
+}
+
+/** Render the human form of the same {@link StatsReport} `--json` prints. */
+export function renderStatsHuman(report: StatsReport): string {
+  const w = report.window;
+  const header = `${report.project} — outcomes ${w.sinceDay} → ${w.untilDay}`;
+  if (report.empty) {
+    return `${header}\n  nothing settled in the window — no runs recorded, so there are no measurements to report yet (a fresh store or an idle fleet).\n`;
+  }
+  const lines = [header, renderRepo(report.total, "  "), `  gh api     ${report.ghCalls} tracked ${report.ghCalls === 1 ? "call" : "calls"} in the window`];
+  if (report.repos.length > 0) {
+    lines.push("  per repo:");
+    for (const repo of report.repos) lines.push(renderRepo(repo, "    "));
+  }
+  return `${lines.join("\n")}\n`;
+}