sela-core 1.0.7 → 1.0.9

package/dist/services/PendingPromptLedger.d.ts

@@ -8,6 +8,13 @@ export interface PendingPromptEntry {
     createdBySela: boolean;
     /** 1-based line number for the vscode:// deeplink, or null when unknown. */
     lineNumber: number | null;
+    /**
+     * Number of healed selectors that landed in THIS file. A single file can
+     * absorb several heals in one run (e.g. two locators in the same spec), so
+     * the DX banner counts fixes from this field rather than from the entry
+     * (= file) count. Older ledgers without the field are treated as 1.
+     */
+    healCount: number;
 }
 /**
  * Resolve the ledger directory for a given cwd. The directory is created
@@ -17,7 +24,7 @@ export interface PendingPromptEntry {
 export declare function ledgerDir(cwd: string): string;
 /**
  * Persist this worker's mutated snapshots to a fresh JSON file under
- * `<cwd>/.sela/pending-prompts/`. Idempotent within a single worker —
+ * `<cwd>/.sela/pending-prompts/`. Idempotent within a single worker -
  * subsequent calls in the same process append a NEW file (rare in
  * practice but keeps the contract simple).
  *
@@ -33,7 +40,7 @@ export declare function writePendingPromptsLedger(opts: {
 /**
  * Drain every per-worker JSON file under the ledger directory and merge
  * their entries into a single de-duplicated list (keyed by absolutePath).
- * The most-recent contentAfter wins on collision — that's the disk truth.
+ * The most-recent contentAfter wins on collision - that's the disk truth.
  *
  * The directory is NOT deleted here so the reporter can inspect entries
  * before calling `clearPendingPromptsLedger()`.

package/dist/services/PendingPromptLedger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PendingPromptLedger.d.ts","sourceRoot":"","sources":["../../src/services/PendingPromptLedger.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAEV,wBAAwB,EACzB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,OAAO,CAAC;IACvB,4EAA4E;IAC5E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAID;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,wBAAwB,CAAC;IACpC,YAAY,EAAE,WAAW,EAAE,CAAC;CAC7B,GAAG,MAAM,GAAG,IAAI,CAehB;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAyB1E;AAED,yEAAyE;AACzE,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAI3D"}
+{"version":3,"file":"PendingPromptLedger.d.ts","sourceRoot":"","sources":["../../src/services/PendingPromptLedger.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAEV,wBAAwB,EACzB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,OAAO,CAAC;IACvB,4EAA4E;IAC5E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAID;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,wBAAwB,CAAC;IACpC,YAAY,EAAE,WAAW,EAAE,CAAC;CAC7B,GAAG,MAAM,GAAG,IAAI,CAehB;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAyB1E;AAED,yEAAyE;AACzE,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAI3D"}

package/dist/services/PendingPromptLedger.js

@@ -11,10 +11,10 @@
 // Solution: each worker SERIALISES its mutated FileSnapshots to a JSON
 // file under `<cwd>/.sela/pending-prompts/`, one file per worker process
 // (keyed by pid + monotonic timestamp). The reporter's onEnd hook reads
-// every file in that directory, drives `runInteractiveReview()` against
-// the merged list, then deletes the directory.
+// every file in that directory, prints a non-blocking summary via
+// `printHealReview()`, then deletes the directory.
 //
-// CRITICAL: workers MUST NOT call `readline` / block on stdin — they have
+// CRITICAL: workers MUST NOT call `readline` / block on stdin - they have
 // no TTY attached. Blocking the event loop here causes the Playwright
 // test timeout to fire. This ledger is the boundary between silent
 // worker-side execution and TTY-bound reporter-side prompting.
@@ -69,7 +69,7 @@ function ledgerDir(cwd) {
 }
 /**
  * Persist this worker's mutated snapshots to a fresh JSON file under
- * `<cwd>/.sela/pending-prompts/`. Idempotent within a single worker —
+ * `<cwd>/.sela/pending-prompts/`. Idempotent within a single worker -
  * subsequent calls in the same process append a NEW file (rare in
  * practice but keeps the contract simple).
  *
@@ -92,7 +92,7 @@ function writePendingPromptsLedger(opts) {
 /**
  * Drain every per-worker JSON file under the ledger directory and merge
  * their entries into a single de-duplicated list (keyed by absolutePath).
- * The most-recent contentAfter wins on collision — that's the disk truth.
+ * The most-recent contentAfter wins on collision - that's the disk truth.
  *
  * The directory is NOT deleted here so the reporter can inspect entries
  * before calling `clearPendingPromptsLedger()`.
@@ -120,7 +120,7 @@ function readPendingPromptsLedger(cwd) {
             }
         }
         catch {
-            // Corrupt ledger file — skip rather than crashing the whole review.
+            // Corrupt ledger file - skip rather than crashing the whole review.
         }
     }
     return Array.from(merged.values());
@@ -143,8 +143,33 @@ function snapshotToEntry(snap, heals, cwd) {
         contentAfter: snap.contentAfter ?? "",
         createdBySela: snap.createdBySela,
         lineNumber: findLineNumberForSnapshot(snap, heals, cwd),
+        healCount: countHealsForSnapshot(snap, heals, cwd),
     };
 }
+/**
+ * Count how many heals mutated `snap`. A heal's mutation target is its
+ * `definitionSite.file` when the write crossed into a const/variable
+ * declaration, otherwise its `sourceFile`. Resolved to absolute form so a
+ * relative event path matches the snapshot's absolute path.
+ *
+ * Falls back to 1 when no heal resolves to the file - the snapshot only
+ * exists because Sela wrote to it, so the file represents at least one fix.
+ */
+function countHealsForSnapshot(snap, heals, cwd) {
+    const normSnap = path.normalize(snap.absolutePath);
+    let n = 0;
+    for (const heal of heals) {
+        const target = heal.definitionSite?.file ?? heal.sourceFile;
+        if (!target)
+            continue;
+        const abs = path.isAbsolute(target)
+            ? path.normalize(target)
+            : path.normalize(path.resolve(cwd, target));
+        if (abs === normSnap)
+            n++;
+    }
+    return n > 0 ? n : 1;
+}
 /**
  * Resolve a 1-based line number for the vscode:// deeplink. Priority:
  *   1. `definitionSite.line` for a heal whose `definitionSite.file`

package/dist/services/ReportGenerator.d.ts

@@ -1,4 +1,77 @@
 import type { HealEvent, HealEventKind } from "./HealReportService";
+export declare const TIME_SAVED_CONSTANTS: {
+    /** A healed selector saved an engineer from manually hunting + patching. */
+    readonly PER_HEAL: 12;
+    /**
+     * Catching a masked regression is worth more — it would have silently
+     * changed test semantics and required a full debugging cycle to uncover.
+     */
+    readonly PER_PROTECT: 18;
+    /**
+     * Partial value: Sela narrowed the debug scope even when it couldn't fix.
+     */
+    readonly PER_FAILED: 4;
+};
+/**
+ * Persisted after every run. Kept in a rolling window of up to 14 entries
+ * by HealReportService. Used to render the Management trend chart.
+ *
+ * **Backend addition required:** HealReportService.flushToDisk() reads
+ * `.sela-history.json`, appends the result of
+ * `ReportGenerator.buildCurrentHistoricalRun()`, trims to 14 entries, writes
+ * it back, and passes the array into `ReportGenerator.generate()`.
+ */
+export interface HistoricalRun {
+    /** Stable identifier — defaults to ISO timestamp but can be CI run ID. */
+    id: string;
+    /** Human-readable x-axis label shown in the trend chart (e.g. "Jan 15"). */
+    label: string;
+    healed: number;
+    protected: number;
+    failed: number;
+    /**
+     * Mean `aiConfidence` across all events in the run (0–100).
+     * Computed by `buildCurrentHistoricalRun()`.
+     * 0 when no events carried a confidence value.
+     */
+    avg_confidence: number;
+    /** Estimated developer minutes saved this run. */
+    time_saved_min: number;
+    /** ISO 8601 — used for deduplication and display sorting. */
+    timestamp: string;
+}
+export interface RoiMetrics {
+    /**
+     * Estimated minutes of developer time saved in THIS run.
+     * Mirrors stats.timeSavedMin — kept here so callers don't need to import
+     * both interfaces.
+     */
+    timeSavedThisRunMin: number;
+    /**
+     * Cumulative minutes saved across all historical runs (including current).
+     * The Management Dashboard renders this as "Total Time Saved This Month"
+     * when the history window covers ~30 days.
+     */
+    timeSavedCumulativeMin: number;
+    /**
+     * Number of PROTECTED events in this run.
+     * Each represents a regression that would have silently mutated test
+     * semantics had Sela auto-applied the AI fix.
+     */
+    bugsPrevented: number;
+    /**
+     * Percentage of all healing attempts (HEALED + PROTECTED) where the
+     * Intent Auditor's final confidence was ≥ 80. Rendered as the
+     * "High Confidence Rate" KPI in the Management view.
+     * `null` when there are no audited events.
+     */
+    highConfidenceRatePct: number | null;
+    /**
+     * Mean aiConfidence across HEALED events only (0–100).
+     * `null` when there are no healed events with a confidence value.
+     */
+    avgHealConfidence: number | null;
+}
 export interface ReportStats {
     total: number;
     healed: number;
@@ -6,64 +79,77 @@ export interface ReportStats {
     protectedCnt: number;
     iframeCnt: number;
     shadowCnt: number;
-    /** Estimated developer time saved, in minutes. */
+    /** Estimated developer minutes saved this run. */
     timeSavedMin: number;
 }
-/**
- * The canonical JSON payload embedded into sela-report.html and
- * mirrored verbatim into sela-report.json.  Treat this as a public
- * contract — additive changes only.
- */
 export interface ReportData {
     generatedAt: string;
     startedAt: string;
     cwd: string;
     events: HealEvent[];
     stats: ReportStats;
+    roi: RoiMetrics;
+    /**
+     * Rolling window of up to 14 runs injected from `.sela-history.json`.
+     * Empty array when no history file exists yet (first run).
+     */
+    historical_runs: HistoricalRun[];
 }
-/**
- * Time-saved heuristics (minutes per event).  Exposed as a constant
- * so tests pin the math against the same source as production.
- */
-export declare const TIME_SAVED_CONSTANTS: {
-    readonly PER_HEAL: 12;
-    readonly PER_PROTECT: 18;
-    readonly PER_FAILED: 4;
-};
 export declare const MANDATORY_FIELDS_BY_KIND: Readonly<Record<HealEventKind, ReadonlyArray<string>>>;
 export declare class ReportGenerator {
     /**
-     * Validates a single event against MANDATORY_FIELDS_BY_KIND.  Throws
-     * a SelaError(subsystem="Report") on the first violation found.  No
-     * partial diagnosis: the report is all-or-nothing.
+     * Validates a single event against MANDATORY_FIELDS_BY_KIND.
+     * Throws a SelaError(subsystem="Report") on the first violation.
      */
     static validateEvent(event: unknown): asserts event is HealEvent;
     /**
-     * Validates every event in the buffer.  Returns the array unchanged
-     * when all events pass.  Throws on the first violation.
+     * Validates every event in the buffer. Returns the typed array when all
+     * events pass. Throws on the first violation.
      */
     static validateAll(events: ReadonlyArray<unknown>): HealEvent[];
     /**
-     * Pure stats computation.  No clock, no IO — easy to pin in tests.
+     * Pure aggregate counters. No clock, no IO — trivially pinnable in tests.
      */
     static computeStats(events: ReadonlyArray<HealEvent>): ReportStats;
     /**
-     * Build the ReportData payload from a raw event buffer.  Validates
-     * every event first.  `now` / `startedAt` are injectable so tests
-     * pin them deterministically.
+     * Derives Management Dashboard KPIs from the event buffer + historical runs.
+     *
+     * `historicalRuns` should already include the current run if you want
+     * cumulative totals to include this run — pass the array AFTER appending
+     * via `buildCurrentHistoricalRun()`.
+     */
+    static computeRoiMetrics(events: ReadonlyArray<HealEvent>, historicalRuns: ReadonlyArray<HistoricalRun>, stats: ReportStats): RoiMetrics;
+    /**
+     * Builds the `HistoricalRun` entry for the current run so the caller can
+     * append it to the persisted sidecar file.
+     *
+     * `runId` — optional override; defaults to ISO timestamp. Pass a CI run ID
+     * (e.g. `process.env.GITHUB_RUN_ID`) when available so deduplication is
+     * reliable across retries.
+     */
+    static buildCurrentHistoricalRun(events: ReadonlyArray<HealEvent>, stats: ReportStats, opts?: {
+        runId?: string;
+        now?: () => Date;
+    }): HistoricalRun;
+    /**
+     * Validates every event, computes all metrics, and assembles the
+     * `ReportData` payload ready for serialisation.
+     *
+     * `historicalRuns` — pass the array from `.sela-history.json` BEFORE
+     * appending the current run; this method appends it internally so the
+     * trend chart always includes the present run.
      */
     static generate(events: ReadonlyArray<unknown>, opts?: {
         cwd?: string;
         startedAt?: string;
+        historicalRuns?: HistoricalRun[];
+        runId?: string;
         now?: () => Date;
     }): ReportData;
     /**
-     * Format a confidence value for UI consumption.  Returns a
-     * percentage string ("87%") for finite numbers, "n/a" for anything
-     * else.  NEVER emits literal "undefined" / "null" / "NaN".
-     *
-     * Public so the HTML template's `fmtPct()` can be replaced by this
-     * single source of truth in a future refactor.
+     * Format a confidence value for UI consumption.
+     * Returns a percentage string ("87%") for finite numbers, "n/a" for
+     * anything else. NEVER emits literal "undefined" / "null" / "NaN".
      */
     static formatConfidence(value: unknown): string;
 }

package/dist/services/ReportGenerator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ReportGenerator.d.ts","sourceRoot":"","sources":["../../src/services/ReportGenerator.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EACV,SAAS,EACT,aAAa,EAId,MAAM,qBAAqB,CAAC;AAM7B,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,KAAK,EAAE,WAAW,CAAC;CACpB;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB;;;;CAIvB,CAAC;AAmCX,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAAC,MAAM,CACpD,aAAa,EACb,aAAa,CAAC,MAAM,CAAC,CACtB,CAIA,CAAC;AAsBF,qBAAa,eAAe;IAC1B;;;;OAIG;IACH,MAAM,CAAC,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,SAAS;IAuChE;;;OAGG;IACH,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,SAAS,EAAE;IAK/D;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,aAAa,CAAC,SAAS,CAAC,GAAG,WAAW;IA4BlE;;;;OAIG;IACH,MAAM,CAAC,QAAQ,CACb,MAAM,EAAE,aAAa,CAAC,OAAO,CAAC,EAC9B,IAAI,GAAE;QACJ,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;KACb,GACL,UAAU;IAYb;;;;;;;OAOG;IACH,MAAM,CAAC,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM;CAOhD"}
+{"version":3,"file":"ReportGenerator.d.ts","sourceRoot":"","sources":["../../src/services/ReportGenerator.ts"],"names":[],"mappings":"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"}

package/dist/services/ReportGenerator.js

@@ -1,49 +1,46 @@
 "use strict";
 // src/services/ReportGenerator.ts
 //
-// Pure (no-IO) report layer.  Takes the HealReportService event buffer
-// and produces a stable, validated JSON shape that the HTML template
-// and any external consumer (CI dashboards, telemetry forwarders)
-// can rely on.
+// Sela Insights — Pure (no-IO) report layer.
 //
-// Design goals:
-//   1. SCHEMA ENFORCED.  Every event passed through ReportGenerator
-//      is validated against MANDATORY_FIELDS_BY_KIND — a SelaError
-//      with subsystem="Report" is thrown for any malformed input.
-//      The HTML template never sees a partial event.
-//
-//   2. CONFIDENCE NEVER LEAKS.  formatConfidence() and the rendered
-//      `confidenceLabel` field always produce either a "<n>%" string
-//      or "n/a" — never `undefined`, `null`, or a stringified
-//      "undefined".  The JS embedded in HealReportService already
-//      uses fmtPct() for the same reason; this module is the
-//      authoritative implementation.
-//
-//   3. STATS DETERMINISTIC.  computeStats() exposes the time-saved
-//      constants via TIME_SAVED_CONSTANTS so tests can pin the math
-//      without duplicating the multipliers.
-//
-//   4. NO IO.  Disk writes still live in HealReportService.flushToDisk
-//      so this module stays trivially unit-testable.
+// Responsibilities:
+//   1. SCHEMA VALIDATION  — every event is validated against
+//      MANDATORY_FIELDS_BY_KIND before the HTML template ever sees it.
+//   2. STATS + METRICS    — computeStats(), computeRoiMetrics(), and
+//      buildCurrentHistoricalRun() are the single source of truth for
+//      every number rendered in the Management Dashboard.
+//   3. CONFIDENCE SAFETY  — formatConfidence() always emits "<n>%" or
+//      "n/a"; never "undefined", "null", or "NaN".
+//   4. NO IO              — disk operations stay in HealReportService so
+//      this module is trivially unit-testable without mocking fs.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ReportGenerator = exports.MANDATORY_FIELDS_BY_KIND = exports.TIME_SAVED_CONSTANTS = void 0;
 const SelaError_1 = require("../errors/SelaError");
-/**
- * Time-saved heuristics (minutes per event).  Exposed as a constant
- * so tests pin the math against the same source as production.
- */
+// ─────────────────────────────────────────────────────────────────────────────
+// TIME-SAVED HEURISTICS  (minutes per event kind)
+// Exposed as a constant so tests can pin the math against the same multipliers
+// as production without duplicating them.
+// ─────────────────────────────────────────────────────────────────────────────
 exports.TIME_SAVED_CONSTANTS = {
+    /** A healed selector saved an engineer from manually hunting + patching. */
     PER_HEAL: 12,
+    /**
+     * Catching a masked regression is worth more — it would have silently
+     * changed test semantics and required a full debugging cycle to uncover.
+     */
     PER_PROTECT: 18,
+    /**
+     * Partial value: Sela narrowed the debug scope even when it couldn't fix.
+     */
     PER_FAILED: 4,
 };
-// ───────────────────────────────────────────────────────────────────
-// Field manifests — mandatory for each event kind
+// ─────────────────────────────────────────────────────────────────────────────
+// FIELD MANIFESTS  — mandatory per event kind
 //
-// "Mandatory" = the HTML template will render an unintelligible card
-// without this field.  Anything optional belongs in the interface
-// declarations in HealReportService.ts but NOT here.
-// ───────────────────────────────────────────────────────────────────
+// "Mandatory" means the HTML card renderer produces a broken / misleading UI
+// without this field. Optional fields belong in the interface declarations in
+// HealReportService.ts but NOT here.
+// ─────────────────────────────────────────────────────────────────────────────
 const COMMON_MANDATORY = [
     "kind",
     "stableId",
@@ -71,9 +68,9 @@ exports.MANDATORY_FIELDS_BY_KIND = {
     PROTECTED: [...COMMON_MANDATORY, ...PROTECTED_MANDATORY],
 };
 const VALID_KINDS = new Set(["HEALED", "FAILED", "PROTECTED"]);
-// ───────────────────────────────────────────────────────────────────
-// Helpers
-// ───────────────────────────────────────────────────────────────────
+// ─────────────────────────────────────────────────────────────────────────────
+// HELPERS
+// ─────────────────────────────────────────────────────────────────────────────
 function throwReport(code, reason, ctx = {}) {
     throw new SelaError_1.SelaError({ subsystem: "Report", code, reason, context: ctx });
 }
@@ -84,14 +81,28 @@ function isPresent(value) {
         return false;
     return true;
 }
-// ───────────────────────────────────────────────────────────────────
+function shortDateLabel(iso) {
+    try {
+        const d = new Date(iso);
+        return d.toLocaleDateString("en-US", { month: "short", day: "numeric" });
+    }
+    catch {
+        return iso.slice(0, 10);
+    }
+}
+function mean(values) {
+    if (values.length === 0)
+        return null;
+    return Math.round(values.reduce((a, b) => a + b, 0) / values.length);
+}
+// ─────────────────────────────────────────────────────────────────────────────
 // ReportGenerator
-// ───────────────────────────────────────────────────────────────────
+// ─────────────────────────────────────────────────────────────────────────────
 class ReportGenerator {
+    // ── Validation ────────────────────────────────────────────────────────────
     /**
-     * Validates a single event against MANDATORY_FIELDS_BY_KIND.  Throws
-     * a SelaError(subsystem="Report") on the first violation found.  No
-     * partial diagnosis: the report is all-or-nothing.
+     * Validates a single event against MANDATORY_FIELDS_BY_KIND.
+     * Throws a SelaError(subsystem="Report") on the first violation.
      */
     static validateEvent(event) {
         if (!event || typeof event !== "object") {
@@ -108,29 +119,25 @@ class ReportGenerator {
                 throwReport(SelaError_1.REPORT_CODES.MISSING_FIELD, `${ev.kind} event missing mandatory field "${field}"`, { stableId: ev.stableId, kind: ev.kind, field });
             }
         }
-        // Field-type sanity for the fields we publicly mandate.
         if (typeof ev.sourceLine !== "number") {
             throwReport(SelaError_1.REPORT_CODES.INVALID_FIELD_TYPE, `Field "sourceLine" must be a number, received ${typeof ev.sourceLine}`, { stableId: ev.stableId, kind: ev.kind, field: "sourceLine" });
         }
     }
     /**
-     * Validates every event in the buffer.  Returns the array unchanged
-     * when all events pass.  Throws on the first violation.
+     * Validates every event in the buffer. Returns the typed array when all
+     * events pass. Throws on the first violation.
      */
     static validateAll(events) {
         for (const e of events)
             ReportGenerator.validateEvent(e);
         return events;
     }
+    // ── Stats ─────────────────────────────────────────────────────────────────
     /**
-     * Pure stats computation.  No clock, no IO — easy to pin in tests.
+     * Pure aggregate counters. No clock, no IO — trivially pinnable in tests.
      */
     static computeStats(events) {
-        let healed = 0;
-        let failed = 0;
-        let protectedCnt = 0;
-        let iframeCnt = 0;
-        let shadowCnt = 0;
+        let healed = 0, failed = 0, protectedCnt = 0, iframeCnt = 0, shadowCnt = 0;
         for (const e of events) {
             if (e.kind === "HEALED")
                 healed++;
@@ -156,34 +163,114 @@ class ReportGenerator {
             timeSavedMin,
         };
     }
+    // ── ROI Metrics ───────────────────────────────────────────────────────────
     /**
-     * Build the ReportData payload from a raw event buffer.  Validates
-     * every event first.  `now` / `startedAt` are injectable so tests
-     * pin them deterministically.
+     * Derives Management Dashboard KPIs from the event buffer + historical runs.
+     *
+     * `historicalRuns` should already include the current run if you want
+     * cumulative totals to include this run — pass the array AFTER appending
+     * via `buildCurrentHistoricalRun()`.
+     */
+    static computeRoiMetrics(events, historicalRuns, stats) {
+        // bugs prevented = all PROTECTED events this run
+        const bugsPrevented = stats.protectedCnt;
+        // cumulative time saved across all historical runs (includes current if
+        // caller appended it before passing here)
+        const timeSavedCumulativeMin = historicalRuns.reduce((sum, r) => sum + r.time_saved_min, 0);
+        // high-confidence rate: among events that have an auditor confidence,
+        // what fraction scored ≥ 80?
+        const audited = events.filter((e) => (e.kind === "HEALED" || e.kind === "PROTECTED") &&
+            e.auditor != null &&
+            typeof e.auditor.confidence === "number" &&
+            isFinite(e.auditor.confidence));
+        const highConfidenceRatePct = audited.length === 0
+            ? null
+            : Math.round((audited.filter((e) => (e.auditor.confidence ?? 0) >= 80).length /
+                audited.length) *
+                100);
+        // avg heal confidence (HEALED events only)
+        const healedWithConf = events.filter((e) => e.kind === "HEALED")
+            .map((e) => e.aiConfidence)
+            .filter((v) => typeof v === "number" && isFinite(v));
+        const avgHealConfidence = mean(healedWithConf);
+        return {
+            timeSavedThisRunMin: stats.timeSavedMin,
+            timeSavedCumulativeMin,
+            bugsPrevented,
+            highConfidenceRatePct,
+            avgHealConfidence,
+        };
+    }
+    // ── Historical run builder ────────────────────────────────────────────────
+    /**
+     * Builds the `HistoricalRun` entry for the current run so the caller can
+     * append it to the persisted sidecar file.
+     *
+     * `runId` — optional override; defaults to ISO timestamp. Pass a CI run ID
+     * (e.g. `process.env.GITHUB_RUN_ID`) when available so deduplication is
+     * reliable across retries.
+     */
+    static buildCurrentHistoricalRun(events, stats, opts = {}) {
+        const now = opts.now ? opts.now() : new Date();
+        const ts = now.toISOString();
+        const confidenceValues = events
+            .filter((e) => typeof e.aiConfidence === "number")
+            .map((e) => e.aiConfidence)
+            .filter((v) => isFinite(v));
+        const avg_confidence = confidenceValues.length > 0
+            ? Math.round(confidenceValues.reduce((a, b) => a + b, 0) /
+                confidenceValues.length)
+            : 0;
+        return {
+            id: opts.runId ?? ts,
+            label: shortDateLabel(ts),
+            healed: stats.healed,
+            protected: stats.protectedCnt,
+            failed: stats.failed,
+            avg_confidence,
+            time_saved_min: stats.timeSavedMin,
+            timestamp: ts,
+        };
+    }
+    // ── Full payload builder ──────────────────────────────────────────────────
+    /**
+     * Validates every event, computes all metrics, and assembles the
+     * `ReportData` payload ready for serialisation.
+     *
+     * `historicalRuns` — pass the array from `.sela-history.json` BEFORE
+     * appending the current run; this method appends it internally so the
+     * trend chart always includes the present run.
      */
     static generate(events, opts = {}) {
         const validated = ReportGenerator.validateAll(events);
         const now = opts.now ?? (() => new Date());
+        const stats = ReportGenerator.computeStats(validated);
+        const currentRun = ReportGenerator.buildCurrentHistoricalRun(validated, stats, { runId: opts.runId, now });
+        // Merge history: drop any prior entry with the same id, append current,
+        // then keep only the most recent HISTORY_WINDOW entries.
+        const HISTORY_WINDOW = 14;
+        const prior = (opts.historicalRuns ?? []).filter((r) => r.id !== currentRun.id);
+        const historical_runs = [...prior, currentRun].slice(-HISTORY_WINDOW);
+        const roi = ReportGenerator.computeRoiMetrics(validated, historical_runs, stats);
         return {
             generatedAt: now().toISOString(),
             startedAt: opts.startedAt ?? now().toISOString(),
             cwd: opts.cwd ?? process.cwd(),
             events: validated,
-            stats: ReportGenerator.computeStats(validated),
+            stats,
+            roi,
+            historical_runs,
         };
     }
+    // ── Confidence formatter ──────────────────────────────────────────────────
     /**
-     * Format a confidence value for UI consumption.  Returns a
-     * percentage string ("87%") for finite numbers, "n/a" for anything
-     * else.  NEVER emits literal "undefined" / "null" / "NaN".
-     *
-     * Public so the HTML template's `fmtPct()` can be replaced by this
-     * single source of truth in a future refactor.
+     * Format a confidence value for UI consumption.
+     * Returns a percentage string ("87%") for finite numbers, "n/a" for
+     * anything else. NEVER emits literal "undefined" / "null" / "NaN".
      */
     static formatConfidence(value) {
         if (typeof value === "number" && Number.isFinite(value)) {
-            const clamped = Math.max(0, Math.min(100, Math.round(value)));
-            return `${clamped}%`;
+            return `${Math.max(0, Math.min(100, Math.round(value)))}%`;
         }
         return "n/a";
     }