sela-core 1.0.6 → 1.0.8

package/dist/index.js

@@ -1,10 +1,10 @@
 "use strict";
-// sela-core — AI self-healing Playwright wrapper
+// sela-core - AI self-healing Playwright wrapper
 //
 // Drop-in replacement for @playwright/test:
 //   import { test, expect } from 'sela-core'
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.expect = exports.test = exports.selectors = exports.devices = exports.webkit = exports.firefox = exports.chromium = exports.defineConfig = void 0;
+exports.SelaReporter = exports.expect = exports.test = exports.selectors = exports.devices = exports.webkit = exports.firefox = exports.chromium = exports.defineConfig = void 0;
 // Config DSL exported FIRST so `sela.config.ts` can `import { defineConfig }`
 // without triggering the heavier fixtures/engine graph during config load.
 var defineConfig_js_1 = require("./config/defineConfig.js");
@@ -16,11 +16,16 @@ Object.defineProperty(exports, "firefox", { enumerable: true, get: function () {
 Object.defineProperty(exports, "webkit", { enumerable: true, get: function () { return test_1.webkit; } });
 Object.defineProperty(exports, "devices", { enumerable: true, get: function () { return test_1.devices; } });
 Object.defineProperty(exports, "selectors", { enumerable: true, get: function () { return test_1.selectors; } });
-// Sela's extended test — includes DNA capture, trace collection,
+// Sela's extended test - includes DNA capture, trace collection,
 // locator proxy, and fixture-scoped healing expect
 var index_js_1 = require("./fixtures/index.js");
 Object.defineProperty(exports, "test", { enumerable: true, get: function () { return index_js_1.test; } });
-// Sela's healing expect — works standalone (import { expect } from 'sela-core')
+// Sela's healing expect - works standalone (import { expect } from 'sela-core')
 // Detects page from locator, falls back to raw PW expect for non-locators
 var moduleExpect_js_1 = require("./fixtures/moduleExpect.js");
 Object.defineProperty(exports, "expect", { enumerable: true, get: function () { return moduleExpect_js_1.expect; } });
+// Playwright Reporter - drop into `reporter: [['sela-core/reporter']]`
+// in playwright.config.ts to drive heal-and-report at the reporter layer
+// (safety net for worker crashes + Playwright failure screenshot capture).
+var SelaReporter_js_1 = require("./reporter/SelaReporter.js");
+Object.defineProperty(exports, "SelaReporter", { enumerable: true, get: function () { return SelaReporter_js_1.SelaReporter; } });

package/dist/reporter/SelaReporter.d.ts

@@ -0,0 +1,143 @@
+import type { Reporter, TestCase, TestResult, FullConfig, Suite, FullResult } from "@playwright/test/reporter";
+import { HealReportService } from "../services/HealReportService.js";
+import type { SelaEngine } from "../engine/SelaEngine.js";
+import { type PendingPromptEntry } from "../services/PendingPromptLedger.js";
+import { type PrintReviewDeps } from "../services/InteractiveReview.js";
+export interface ReporterEngine {
+    commitUpdates(): Promise<void>;
+}
+export interface ReporterLogger {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+}
+export interface SelaReporterOpts {
+    /**
+     * Skip the `ANTHROPIC_API_KEY` presence check. Tests inject this so
+     * the reporter does not surface a noisy warning when no real key is
+     * required to drive the lifecycle.
+     */
+    skipApiKeyCheck?: boolean;
+    /** Override the engine. Defaults to `sharedEngine`. */
+    engine?: ReporterEngine | SelaEngine;
+    /** Override the report buffer. Defaults to `sharedHealReport`. */
+    report?: HealReportService;
+    /** Override the logger (defaults to `console`). */
+    logger?: ReporterLogger;
+    /** Override cwd used to locate the pending-prompts ledger. Defaults to process.cwd(). */
+    cwd?: string;
+    /**
+     * Inject the ledger reader - tests stub this so they don't have to
+     * touch the real filesystem.
+     */
+    readLedger?: (cwd: string) => PendingPromptEntry[];
+    /** Inject the ledger cleaner. */
+    clearLedger?: (cwd: string) => void;
+    /**
+     * Inject the review printer. Tests stub this to assert that the
+     * reporter wires the ledger entries + HTML report path through unchanged.
+     */
+    printReview?: (deps: PrintReviewDeps) => void;
+    /**
+     * Override the resolution of the HTML report path. Returns `null` when
+     * no report exists. Defaults to `<cwd>/sela-report.html` when the file
+     * is on disk.
+     */
+    resolveReportPath?: (cwd: string) => string | null;
+    /**
+     * Override the CI detection - true means "behave as CI" (skip the
+     * post-run notify). Defaults to checking `process.env.CI`.
+     */
+    isCi?: () => boolean;
+    /**
+     * Install process-level SIGINT/SIGTERM handlers in onBegin. Defaults
+     * to true. Tests pass `false` so vitest's own signal lifecycle isn't
+     * polluted by leftover handlers between cases.
+     */
+    installSignalHandlers?: boolean;
+}
+export declare class SelaReporter implements Reporter {
+    private readonly engine;
+    private readonly report;
+    private readonly logger;
+    private readonly skipApiKeyCheck;
+    private readonly cwd;
+    private readonly readLedger;
+    private readonly clearLedger;
+    private readonly printReview;
+    private readonly resolveReportPath;
+    private readonly isCi;
+    private readonly shouldInstallSignalHandlers;
+    private shutdownHandler;
+    private shuttingDown;
+    /**
+     * Screenshots that arrived before a matching FailedEvent existed in
+     * the shared report. Re-flushed once at onEnd time so worker-crash
+     * scenarios (no fixture teardown ⇒ no engine-side FailedEvent yet)
+     * still get their visual context attached.
+     *
+     * Key shape: `${normalisedSourceFile}::${testTitle}`.
+     */
+    private readonly pendingScreenshots;
+    /**
+     * Mirror of the failures the reporter observed, kept so external
+     * consumers (and tests) can audit what the reporter saw without
+     * having to subscribe to the entire Playwright Reporter API.
+     */
+    private readonly failures;
+    constructor(opts?: SelaReporterOpts);
+    onBegin(_config?: FullConfig, _suite?: Suite): void;
+    onTestEnd(test: TestCase, result: TestResult): void;
+    onEnd(_result?: FullResult): Promise<void>;
+    /** Reporter prints nothing of its own - Playwright stdio stays clean. */
+    printsToStdio(): boolean;
+    /**
+     * Install the SIGINT/SIGTERM listener once per reporter. First signal
+     * triggers an orderly drain; second signal hard-exits with code 130
+     * (SIGINT) / 143 (SIGTERM) so the user can always escape if the drain
+     * itself wedges (e.g. a stuck LLM call).
+     */
+    private installShutdownHandler;
+    private uninstallShutdownHandler;
+    /**
+     * Best-effort drain on signal. Mirrors the orderly onEnd path but
+     * swallows every error - we never want to throw inside a signal
+     * handler because Node prints raw stack traces otherwise.
+     *
+     * Exposed for tests so they can drive the shutdown without raising
+     * a real signal in the vitest process.
+     */
+    gracefulShutdown(): Promise<void>;
+    /**
+     * Walk every buffered pending screenshot and try to attach it to a
+     * now-existing FailedEvent. Successfully-attached entries are
+     * removed; unmatched entries are dropped (the matching FailedEvent
+     * never arrived - most likely worker crashed before the engine
+     * could record one).
+     *
+     * Returns the number of FailedEvents touched.
+     */
+    flushPendingScreenshots(): number;
+    /** Test hook - read-only snapshot of recorded failures. */
+    getRecordedFailures(): ReadonlyArray<{
+        sourceFile: string;
+        sourceLine?: number;
+        testTitle: string;
+        status: string;
+        hasScreenshot: boolean;
+    }>;
+    /** Test hook - number of screenshots still waiting for a FailedEvent. */
+    getPendingScreenshotCount(): number;
+    private pendingKey;
+    private normalisePath;
+    /**
+     * Convert the first PNG attachment on a TestResult into a Base64
+     * string immediately. Prefers an in-memory `body` when Playwright
+     * already inlined the bytes (faster, no IO); falls back to reading
+     * the attachment `path` synchronously BEFORE Playwright has a chance
+     * to clean up its temp folder.
+     */
+    private extractScreenshotBase64;
+}
+export default SelaReporter;
+//# sourceMappingURL=SelaReporter.d.ts.map

package/dist/reporter/SelaReporter.d.ts.map

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

package/dist/reporter/SelaReporter.js

@@ -0,0 +1,428 @@
+"use strict";
+// src/reporter/SelaReporter.ts
+//
+// SelaReporter - Playwright Reporter implementation that drives the
+// Sela heal-and-report pipeline at the reporter layer instead of the
+// fixture teardown layer. The fixture path remains the primary trigger
+// for in-test heals; this reporter is the SAFETY NET for worker crashes,
+// timeouts, and any failure mode that skips fixture teardown.
+//
+// Responsibilities:
+//   1. onBegin - flips SELA_REPORTER_ACTIVE, installs SIGINT/SIGTERM
+//      graceful-shutdown handlers.
+//   2. onTestEnd - extracts the first PNG screenshot from
+//      TestResult.attachments and converts it to Base64 IMMEDIATELY.
+//      Playwright's temp folder is cleaned up between runs, so the
+//      bytes MUST be captured into memory before the reporter loop ends.
+//   3. onEnd - checks for ANTHROPIC_API_KEY, flushes pending screenshots,
+//      runs SelaEngine.commitUpdates(), then prints a *non-blocking*
+//      write-and-notify summary (unified diff per healed file +
+//      vscode://file deeplink + sela-report.html deeplink). MVP flow -
+//      no Y/N prompt, no rollback. Mutations are already on disk by the
+//      time we reach this hook.
+//   4. SIGINT / SIGTERM - runs gracefulShutdown() once, second signal
+//      hard-exits. Prevents stranded child processes from showing raw
+//      Node unhandledRejection stack traces on Ctrl+C.
+//
+// Clean Architecture: zero business logic - IO + aggregation only.
+// Heal decisions live in SelaEngine, validation in ReportGenerator,
+// rendering in HealReportService.
+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.SelaReporter = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const HealReportService_js_1 = require("../services/HealReportService.js");
+const singleton_js_1 = require("../engine/singleton.js");
+const SelaError_js_1 = require("../errors/SelaError.js");
+const PendingPromptLedger_js_1 = require("../services/PendingPromptLedger.js");
+const InteractiveReview_js_1 = require("../services/InteractiveReview.js");
+// ───────────────────────────────────────────────────────────────────
+// SelaReporter
+// ───────────────────────────────────────────────────────────────────
+class SelaReporter {
+    engine;
+    report;
+    logger;
+    skipApiKeyCheck;
+    cwd;
+    readLedger;
+    clearLedger;
+    printReview;
+    resolveReportPath;
+    isCi;
+    shouldInstallSignalHandlers;
+    shutdownHandler = null;
+    shuttingDown = false;
+    /**
+     * Screenshots that arrived before a matching FailedEvent existed in
+     * the shared report. Re-flushed once at onEnd time so worker-crash
+     * scenarios (no fixture teardown ⇒ no engine-side FailedEvent yet)
+     * still get their visual context attached.
+     *
+     * Key shape: `${normalisedSourceFile}::${testTitle}`.
+     */
+    pendingScreenshots = new Map();
+    /**
+     * Mirror of the failures the reporter observed, kept so external
+     * consumers (and tests) can audit what the reporter saw without
+     * having to subscribe to the entire Playwright Reporter API.
+     */
+    failures = [];
+    constructor(opts = {}) {
+        this.engine = (opts.engine ?? singleton_js_1.sharedEngine);
+        this.report = opts.report ?? HealReportService_js_1.sharedHealReport;
+        this.skipApiKeyCheck = opts.skipApiKeyCheck ?? false;
+        this.logger = opts.logger ?? {
+            info: (m) => console.log(m),
+            warn: (m) => console.warn(m),
+            error: (m) => console.error(m),
+        };
+        this.cwd = opts.cwd ?? process.cwd();
+        this.readLedger = opts.readLedger ?? PendingPromptLedger_js_1.readPendingPromptsLedger;
+        this.clearLedger = opts.clearLedger ?? PendingPromptLedger_js_1.clearPendingPromptsLedger;
+        this.printReview = opts.printReview ?? InteractiveReview_js_1.printHealReview;
+        this.resolveReportPath = opts.resolveReportPath ?? defaultResolveReportPath;
+        this.isCi = opts.isCi ?? defaultIsCi;
+        this.shouldInstallSignalHandlers = opts.installSignalHandlers ?? true;
+    }
+    // ─────────────────────────────────────────────────────────────
+    // Playwright Reporter API
+    // ─────────────────────────────────────────────────────────────
+    onBegin(_config, _suite) {
+        // Signal to future fixture-aware code that a reporter is driving
+        // finalisation. Today the fixture still calls engine.commitUpdates()
+        // itself; the env flag is reserved for the planned dedup guard.
+        process.env.SELA_REPORTER_ACTIVE = "1";
+        if (this.shouldInstallSignalHandlers) {
+            this.installShutdownHandler();
+        }
+    }
+    onTestEnd(test, result) {
+        if (result.status !== "failed" && result.status !== "timedOut")
+            return;
+        const sourceFile = test.location?.file ?? "";
+        const sourceLine = test.location?.line;
+        const testTitle = test.title;
+        const base64Png = this.extractScreenshotBase64(result);
+        if (base64Png) {
+            // First try to attach immediately - the engine may have already
+            // recorded the FailedEvent during fixture teardown for in-test
+            // heal failures. This is the happy path.
+            const matched = this.report.attachFailureScreenshot({ sourceFile: this.normalisePath(sourceFile), testTitle }, base64Png);
+            if (matched === 0) {
+                // No matching FailedEvent yet - buffer for the onEnd retry. This
+                // covers worker-crash and fixture-skip cases where the engine
+                // never got a chance to record the FailedEvent in-flight.
+                const key = this.pendingKey(sourceFile, testTitle);
+                this.pendingScreenshots.set(key, base64Png);
+            }
+        }
+        this.failures.push({
+            sourceFile,
+            sourceLine,
+            testTitle,
+            status: result.status,
+            hasScreenshot: !!base64Png,
+        });
+    }
+    async onEnd(_result) {
+        // Detach signal handlers first - a natural onEnd is the orderly path,
+        // so we don't want a late SIGINT to double-invoke shutdown logic.
+        this.uninstallShutdownHandler();
+        if (!this.skipApiKeyCheck && !process.env.ANTHROPIC_API_KEY) {
+            const err = new SelaError_js_1.SelaError({
+                subsystem: "LLMService",
+                code: SelaError_js_1.LLM_SERVICE_CODES.NO_API_KEY,
+                reason: "ANTHROPIC_API_KEY not set - SelaReporter cannot drive the heal pipeline. " +
+                    "Set the env var (or remove the reporter entry from playwright.config.ts).",
+            });
+            // Graceful degradation: surface the error and continue flushing
+            // any report content the fixture path already produced.
+            this.logger.warn(err.message);
+        }
+        // Late-bind any screenshots that arrived before their FailedEvents.
+        this.flushPendingScreenshots();
+        try {
+            await this.engine.commitUpdates();
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            this.logger.error(`[Sela] reporter commitUpdates failed: ${msg}`);
+        }
+        // ── Local DX - Write-and-notify summary ─────────────────────
+        //
+        // Workers serialise their mutated FileSnapshots to
+        // `<cwd>/.sela/pending-prompts/*.json`. The reporter drains that
+        // ledger here and prints a non-blocking summary (diff + vscode
+        // deeplink + HTML report deeplink). No Y/N prompt - the files are
+        // already mutated on disk by the time we get here.
+        //
+        // CI runs skip the notify entirely - PR automation already handled
+        // the mutations on its isolated branch.
+        if (!this.isCi()) {
+            try {
+                const entries = this.readLedger(this.cwd);
+                const reportHtmlPath = this.resolveReportPath(this.cwd);
+                if (entries.length > 0 || reportHtmlPath) {
+                    this.printReview({ entries, reportHtmlPath });
+                }
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                this.logger.error(`[Sela] review summary failed: ${msg}`);
+            }
+            finally {
+                try {
+                    this.clearLedger(this.cwd);
+                }
+                catch {
+                    // Cleanup failures are non-fatal - the next run will overwrite.
+                }
+            }
+        }
+        else {
+            // CI path: drop the ledger so a follow-up local run doesn't replay
+            // mutations from a previous CI session.
+            try {
+                this.clearLedger(this.cwd);
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    /** Reporter prints nothing of its own - Playwright stdio stays clean. */
+    printsToStdio() {
+        return false;
+    }
+    // ─────────────────────────────────────────────────────────────
+    // Graceful shutdown - SIGINT / SIGTERM
+    // ─────────────────────────────────────────────────────────────
+    /**
+     * Install the SIGINT/SIGTERM listener once per reporter. First signal
+     * triggers an orderly drain; second signal hard-exits with code 130
+     * (SIGINT) / 143 (SIGTERM) so the user can always escape if the drain
+     * itself wedges (e.g. a stuck LLM call).
+     */
+    installShutdownHandler() {
+        if (this.shutdownHandler)
+            return;
+        const handler = (signal) => {
+            if (this.shuttingDown) {
+                process.stderr.write(`\n[Sela] ⏹  Force exit on second ${signal}.\n`);
+                process.exit(signal === "SIGTERM" ? 143 : 130);
+                return;
+            }
+            this.shuttingDown = true;
+            process.stderr.write(`\n[Sela] 🛑 ${signal} received - flushing state and shutting down...\n`);
+            this.gracefulShutdown()
+                .catch((err) => {
+                const msg = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`[Sela] Shutdown error: ${msg}\n`);
+            })
+                .finally(() => {
+                process.stderr.write(`[Sela] 👋 Goodbye.\n`);
+                process.exit(signal === "SIGTERM" ? 143 : 130);
+            });
+        };
+        this.shutdownHandler = handler;
+        process.on("SIGINT", handler);
+        process.on("SIGTERM", handler);
+    }
+    uninstallShutdownHandler() {
+        if (!this.shutdownHandler)
+            return;
+        process.off("SIGINT", this.shutdownHandler);
+        process.off("SIGTERM", this.shutdownHandler);
+        this.shutdownHandler = null;
+    }
+    /**
+     * Best-effort drain on signal. Mirrors the orderly onEnd path but
+     * swallows every error - we never want to throw inside a signal
+     * handler because Node prints raw stack traces otherwise.
+     *
+     * Exposed for tests so they can drive the shutdown without raising
+     * a real signal in the vitest process.
+     */
+    async gracefulShutdown() {
+        try {
+            this.flushPendingScreenshots();
+        }
+        catch {
+            // ignore
+        }
+        try {
+            await this.engine.commitUpdates();
+        }
+        catch {
+            // ignore
+        }
+        try {
+            const entries = this.isCi() ? [] : this.readLedger(this.cwd);
+            const reportHtmlPath = this.resolveReportPath(this.cwd);
+            if (entries.length > 0 || reportHtmlPath) {
+                this.printReview({ entries, reportHtmlPath });
+            }
+        }
+        catch {
+            // ignore
+        }
+        try {
+            this.clearLedger(this.cwd);
+        }
+        catch {
+            // ignore
+        }
+    }
+    // ─────────────────────────────────────────────────────────────
+    // Internals (exposed for testing - prefixed underscore is the
+    // convention used elsewhere in the codebase for proxy back-doors).
+    // ─────────────────────────────────────────────────────────────
+    /**
+     * Walk every buffered pending screenshot and try to attach it to a
+     * now-existing FailedEvent. Successfully-attached entries are
+     * removed; unmatched entries are dropped (the matching FailedEvent
+     * never arrived - most likely worker crashed before the engine
+     * could record one).
+     *
+     * Returns the number of FailedEvents touched.
+     */
+    flushPendingScreenshots() {
+        let total = 0;
+        for (const [key, base64] of Array.from(this.pendingScreenshots.entries())) {
+            const sepIndex = key.indexOf("::");
+            if (sepIndex < 0) {
+                this.pendingScreenshots.delete(key);
+                continue;
+            }
+            const filePart = key.slice(0, sepIndex);
+            const titlePart = key.slice(sepIndex + 2);
+            const matched = this.report.attachFailureScreenshot({ sourceFile: filePart, testTitle: titlePart }, base64);
+            if (matched > 0) {
+                total += matched;
+                this.pendingScreenshots.delete(key);
+            }
+        }
+        return total;
+    }
+    /** Test hook - read-only snapshot of recorded failures. */
+    getRecordedFailures() {
+        return this.failures.slice();
+    }
+    /** Test hook - number of screenshots still waiting for a FailedEvent. */
+    getPendingScreenshotCount() {
+        return this.pendingScreenshots.size;
+    }
+    // ─────────────────────────────────────────────────────────────
+    // Private helpers
+    // ─────────────────────────────────────────────────────────────
+    pendingKey(sourceFile, testTitle) {
+        return `${this.normalisePath(sourceFile)}::${testTitle}`;
+    }
+    normalisePath(p) {
+        if (!p)
+            return "";
+        try {
+            const abs = path.isAbsolute(p) ? p : path.resolve(process.cwd(), p);
+            const rel = path.relative(process.cwd(), abs);
+            return (rel || abs).split("\\").join("/");
+        }
+        catch {
+            return p.split("\\").join("/");
+        }
+    }
+    /**
+     * Convert the first PNG attachment on a TestResult into a Base64
+     * string immediately. Prefers an in-memory `body` when Playwright
+     * already inlined the bytes (faster, no IO); falls back to reading
+     * the attachment `path` synchronously BEFORE Playwright has a chance
+     * to clean up its temp folder.
+     */
+    extractScreenshotBase64(result) {
+        const attachments = result.attachments ?? [];
+        for (const att of attachments) {
+            const contentType = (att.contentType ?? "").toLowerCase();
+            const looksLikePng = contentType.includes("png") ||
+                (att.name ?? "").toLowerCase().includes("screenshot") ||
+                (att.path ?? "").toLowerCase().endsWith(".png");
+            if (!looksLikePng)
+                continue;
+            // Playwright >= 1.46 sometimes inlines the body for small images.
+            const inline = att.body;
+            if (inline && inline.length > 0) {
+                return Buffer.isBuffer(inline)
+                    ? inline.toString("base64")
+                    : Buffer.from(inline).toString("base64");
+            }
+            if (att.path) {
+                try {
+                    const bytes = fs.readFileSync(att.path);
+                    return bytes.toString("base64");
+                }
+                catch {
+                    // Temp file already gone - nothing we can do.
+                }
+            }
+        }
+        return undefined;
+    }
+}
+exports.SelaReporter = SelaReporter;
+/**
+ * Mirror of the CI detection used by `SelaEngine.commitUpdates()`.
+ * Accepts the standard `CI=1`/`CI=true` convention; everything else
+ * (empty string, undefined, `0`, `false`) is Local DX mode.
+ */
+function defaultIsCi() {
+    const raw = process.env.CI;
+    if (raw === undefined || raw === null)
+        return false;
+    const v = String(raw).trim().toLowerCase();
+    return v !== "" && v !== "0" && v !== "false";
+}
+/**
+ * Default HTML report locator. Returns the absolute path when
+ * `<cwd>/sela-report.html` exists on disk after `commitUpdates()` has
+ * had its chance to flush, otherwise null so the printer can skip the
+ * "Insights report:" footer entirely.
+ */
+function defaultResolveReportPath(cwd) {
+    const candidate = path.join(cwd, "sela-report.html");
+    return fs.existsSync(candidate) ? candidate : null;
+}
+// Default export so Playwright can resolve `reporter: [['sela-core/reporter']]`
+// without needing the consumer to spell out the named import.
+exports.default = SelaReporter;

package/dist/services/ASTSourceUpdater.d.ts

@@ -25,6 +25,25 @@ export declare class ASTSourceUpdater {
     private project;
     readonly advisoryBuffer: AdvisoryBuffer;
     flushAdvisories(): void;
+    /**
+     * Centralised write hook for every ts-morph `saveSync` call in this class.
+     * When `SELA_DRY_RUN` is active the AST mutation stays in memory but the
+     * on-disk file is left untouched - the heal pipeline can still compute a
+     * candidate diff via `sourceFile.getFullText()` and the report layer
+     * tags the event with `dryRun: true`.
+     */
+    private _persistChanges;
+    scanFailFastDirective(caller: CallerContext): {
+        failFast: boolean;
+        matchedComment?: string;
+        matchedLine?: number;
+    };
+    /**
+     * Convenience helper - runs `scanFailFastDirective` and throws the
+     * canonical SelaError when the directive is present. Used by SelaEngine
+     * as the very first gate inside `heal()`.
+     */
+    enforceFailFastDirective(caller: CallerContext): void;
     constructor();
     private readonly WRAPPER_IDENTIFIERS;
     private readonly STRUCTURAL_ROLES;
@@ -48,7 +67,7 @@ export declare class ASTSourceUpdater {
     /**
      * Guard: returns false when replacing oldNode with proposedNewText would
      * substitute a hardcoded string literal for an Identifier or
-     * PropertyAccessExpression — which is the definition-site mutation bug.
+     * PropertyAccessExpression - which is the definition-site mutation bug.
      * All other replacements are allowed.
      */
     private static isSafeReplacement;

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

@@ -1 +1 @@
-{"version":3,"file":"ASTSourceUpdater.d.ts","sourceRoot":"","sources":["../../src/services/ASTSourceUpdater.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAQ/C,OAAO,EAAE,cAAc,EAAgB,MAAM,mBAAmB,CAAC;AAOjE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAMtD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kGAAkG;IAClG,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,wEAAwE;IACxE,cAAc,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAChD,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,UAAU,aAAa;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAg5DD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,OAAO,CAAU;IACzB,QAAQ,CAAC,cAAc,iBAAwB;IAE/C,eAAe,IAAI,IAAI;;IAiBvB,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAcjC;IAEH,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CA8B9B;IAEH,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAuB/B;IAMH,MAAM,CACJ,MAAM,EAAE,aAAa,EACrB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,eAAe,EAAE,EAC9B,mBAAmB,CAAC,EAAE,MAAM,EAC5B,aAAa,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EACpD,kBAAkB,CAAC,EAAE,iBAAiB,EAAE,EACxC,iBAAiB,CAAC,EAAE,iBAAiB,EAAE,GACtC,eAAe;IA8PlB,OAAO,CAAC,kBAAkB;IAsM1B,OAAO,CAAC,uBAAuB;IA6F/B,OAAO,CAAC,qBAAqB;IAyF7B,OAAO,CAAC,YAAY;IAkDpB,OAAO,CAAC,qBAAqB;IA0G7B,OAAO,CAAC,4BAA4B;IAoRpC,OAAO,CAAC,yBAAyB;IAsGjC,OAAO,CAAC,uBAAuB;IA4E/B,OAAO,CAAC,4BAA4B;IA4EpC,OAAO,CAAC,qBAAqB;IA6B7B,OAAO,CAAC,oBAAoB;IAwB5B,OAAO,CAAC,gBAAgB;IAwBxB;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAUhC,OAAO,CAAC,mBAAmB;IAuC3B,OAAO,CAAC,kBAAkB;IA2B1B,OAAO,CAAC,kBAAkB;IAuB1B,OAAO,CAAC,2BAA2B;IAsCnC,OAAO,CAAC,yBAAyB;IAqCjC,OAAO,CAAC,yBAAyB;IA+CjC,OAAO,CAAC,qBAAqB;IAQ7B,OAAO,CAAC,cAAc;IAYtB,OAAO,CAAC,0BAA0B;IAmBlC,OAAO,CAAC,sBAAsB;IA2B9B,OAAO,CAAC,2BAA2B;IAoCnC,OAAO,CAAC,oBAAoB;IA2B5B,OAAO,CAAC,YAAY;IAUpB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAkB3C,OAAO,CAAC,gBAAgB;IAkExB,OAAO,CAAC,mBAAmB;IAiF3B,OAAO,CAAC,uBAAuB;IAiF/B,OAAO,CAAC,wBAAwB;IAkFhC,OAAO,CAAC,mBAAmB;IA8C3B,OAAO,CAAC,uBAAuB;IAoF/B,OAAO,CAAC,kBAAkB;IAwB1B,OAAO,CAAC,kBAAkB;CAgB3B"}
+{"version":3,"file":"ASTSourceUpdater.d.ts","sourceRoot":"","sources":["../../src/services/ASTSourceUpdater.ts"],"names":[],"mappings":"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"}