sela-core 0.1.0-alpha.1

package/dist/services/PendingPromptLedger.d.ts

@@ -0,0 +1,51 @@
+import type { WorkspaceSnapshotService } from "./WorkspaceSnapshotService";
+import type { HealedEvent } from "./HealReportService";
+export interface PendingPromptEntry {
+    absolutePath: string;
+    relativePath: string;
+    contentBefore: string;
+    contentAfter: string;
+    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
+ * lazily on the first write so we never clutter repos that aren't running
+ * Sela.
+ */
+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 -
+ * subsequent calls in the same process append a NEW file (rare in
+ * practice but keeps the contract simple).
+ *
+ * Returns the absolute path of the written file, or `null` when there is
+ * nothing to persist (so callers can skip the prompt entirely in CI /
+ * empty-mutation runs).
+ */
+export declare function writePendingPromptsLedger(opts: {
+    cwd: string;
+    workspace: WorkspaceSnapshotService;
+    healedEvents: HealedEvent[];
+}): string | null;
+/**
+ * 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 directory is NOT deleted here so the reporter can inspect entries
+ * before calling `clearPendingPromptsLedger()`.
+ */
+export declare function readPendingPromptsLedger(cwd: string): PendingPromptEntry[];
+/** Remove the ledger directory and every file beneath it. Idempotent. */
+export declare function clearPendingPromptsLedger(cwd: string): void;
+//# sourceMappingURL=PendingPromptLedger.d.ts.map

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

@@ -0,0 +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;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

@@ -0,0 +1,205 @@
+"use strict";
+// src/services/PendingPromptLedger.ts
+//
+// Cross-process ledger for the Local DX dual-mode lifecycle.
+//
+// Playwright workers run in separate Node processes from the reporter
+// (main process). The in-memory `WorkspaceSnapshotService` ledger is
+// per-process, so we can't drive an interactive prompt from the reporter
+// using only worker-side state.
+//
+// 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, prints a non-blocking summary via
+// `printHealReview()`, then deletes the directory.
+//
+// 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.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ledgerDir = ledgerDir;
+exports.writePendingPromptsLedger = writePendingPromptsLedger;
+exports.readPendingPromptsLedger = readPendingPromptsLedger;
+exports.clearPendingPromptsLedger = clearPendingPromptsLedger;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const LEDGER_SUBDIR = path.join(".sela", "pending-prompts");
+/**
+ * Resolve the ledger directory for a given cwd. The directory is created
+ * lazily on the first write so we never clutter repos that aren't running
+ * Sela.
+ */
+function ledgerDir(cwd) {
+    return path.join(cwd, LEDGER_SUBDIR);
+}
+/**
+ * Persist this worker's mutated snapshots to a fresh JSON file under
+ * `<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).
+ *
+ * Returns the absolute path of the written file, or `null` when there is
+ * nothing to persist (so callers can skip the prompt entirely in CI /
+ * empty-mutation runs).
+ */
+function writePendingPromptsLedger(opts) {
+    const snaps = opts.workspace.getMutatedSnapshots();
+    if (snaps.length === 0)
+        return null;
+    const entries = snaps.map((s) => snapshotToEntry(s, opts.healedEvents, opts.cwd));
+    const dir = ledgerDir(opts.cwd);
+    fs.mkdirSync(dir, { recursive: true });
+    const fileName = `${process.pid}-${Date.now()}-${randomTag()}.json`;
+    const full = path.join(dir, fileName);
+    fs.writeFileSync(full, JSON.stringify(entries, null, 2), "utf8");
+    return full;
+}
+/**
+ * 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 directory is NOT deleted here so the reporter can inspect entries
+ * before calling `clearPendingPromptsLedger()`.
+ */
+function readPendingPromptsLedger(cwd) {
+    const dir = ledgerDir(cwd);
+    if (!fs.existsSync(dir))
+        return [];
+    const merged = new Map();
+    const files = fs
+        .readdirSync(dir)
+        .filter((f) => f.endsWith(".json"))
+        .sort(); // pid-timestamp prefix gives a stable, time-ordered merge
+    for (const f of files) {
+        const full = path.join(dir, f);
+        try {
+            const raw = fs.readFileSync(full, "utf8");
+            const parsed = JSON.parse(raw);
+            if (!Array.isArray(parsed))
+                continue;
+            for (const entry of parsed) {
+                if (!entry || typeof entry.absolutePath !== "string")
+                    continue;
+                merged.set(path.normalize(entry.absolutePath), entry);
+            }
+        }
+        catch {
+            // Corrupt ledger file - skip rather than crashing the whole review.
+        }
+    }
+    return Array.from(merged.values());
+}
+/** Remove the ledger directory and every file beneath it. Idempotent. */
+function clearPendingPromptsLedger(cwd) {
+    const dir = ledgerDir(cwd);
+    if (!fs.existsSync(dir))
+        return;
+    fs.rmSync(dir, { recursive: true, force: true });
+}
+// ───────────────────────────────────────────────────────────────────
+// Helpers
+// ───────────────────────────────────────────────────────────────────
+function snapshotToEntry(snap, heals, cwd) {
+    return {
+        absolutePath: snap.absolutePath,
+        relativePath: snap.relativePath,
+        contentBefore: snap.contentBefore,
+        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`
+ *      resolves to this snapshot.
+ *   2. `newLineNumber` reported on a heal whose `sourceFile` resolves to
+ *      this snapshot.
+ *   3. `null` (link emitted without a line suffix).
+ */
+function findLineNumberForSnapshot(snap, heals, cwd) {
+    const normSnap = path.normalize(snap.absolutePath);
+    for (const heal of heals) {
+        if (heal.definitionSite) {
+            const defAbs = path.isAbsolute(heal.definitionSite.file)
+                ? path.normalize(heal.definitionSite.file)
+                : path.normalize(path.resolve(cwd, heal.definitionSite.file));
+            if (defAbs === normSnap && heal.definitionSite.line > 0) {
+                return heal.definitionSite.line;
+            }
+        }
+    }
+    for (const heal of heals) {
+        const healAbs = path.isAbsolute(heal.sourceFile)
+            ? path.normalize(heal.sourceFile)
+            : path.normalize(path.resolve(cwd, heal.sourceFile));
+        if (healAbs === normSnap && heal.newLineNumber > 0) {
+            return heal.newLineNumber;
+        }
+    }
+    return null;
+}
+function randomTag() {
+    return Math.random().toString(36).slice(2, 8);
+}

package/dist/services/ReportGenerator.d.ts

@@ -0,0 +1,156 @@
+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;
+    failed: number;
+    protectedCnt: number;
+    iframeCnt: number;
+    shadowCnt: number;
+    /** Estimated developer minutes saved this run. */
+    timeSavedMin: number;
+}
+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[];
+}
+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.
+     */
+    static validateEvent(event: unknown): asserts event is HealEvent;
+    /**
+     * 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 aggregate counters. No clock, no IO — trivially pinnable in tests.
+     */
+    static computeStats(events: ReadonlyArray<HealEvent>): ReportStats;
+    /**
+     * 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".
+     */
+    static formatConfidence(value: unknown): string;
+}
+//# sourceMappingURL=ReportGenerator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ReportGenerator.d.ts","sourceRoot":"","sources":["../../src/services/ReportGenerator.ts"],"names":[],"mappings":"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"}