sela-core 1.0.7 → 1.0.9

package/dist/reporter/SelaReporter.d.ts

@@ -2,7 +2,7 @@ import type { Reporter, TestCase, TestResult, FullConfig, Suite, FullResult } fr
 import { HealReportService } from "../services/HealReportService.js";
 import type { SelaEngine } from "../engine/SelaEngine.js";
 import { type PendingPromptEntry } from "../services/PendingPromptLedger.js";
-import { type InteractiveReviewOutcome } from "../services/InteractiveReview.js";
+import { type PrintReviewDeps } from "../services/InteractiveReview.js";
 export interface ReporterEngine {
     commitUpdates(): Promise<void>;
 }
@@ -27,22 +27,34 @@ export interface SelaReporterOpts {
     /** 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
+     * 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 interactive review runner. Tests stub this to assert that
-     * the reporter wires the ledger entries through unchanged.
+     * Inject the review printer. Tests stub this to assert that the
+     * reporter wires the ledger entries + HTML report path through unchanged.
      */
-    runReview?: (entries: PendingPromptEntry[]) => Promise<InteractiveReviewOutcome[]>;
+    printReview?: (deps: PrintReviewDeps) => void;
     /**
-     * Override the CI detection — true means "behave as CI" (skip the
-     * interactive review). Defaults to checking `process.env.CI`.
+     * 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;
@@ -52,8 +64,12 @@ export declare class SelaReporter implements Reporter {
     private readonly cwd;
     private readonly readLedger;
     private readonly clearLedger;
-    private readonly runReview;
+    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
@@ -73,19 +89,36 @@ export declare class SelaReporter implements Reporter {
     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. */
+    /** 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
+     * 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. */
+    /** Test hook - read-only snapshot of recorded failures. */
     getRecordedFailures(): ReadonlyArray<{
         sourceFile: string;
         sourceLine?: number;
@@ -93,7 +126,7 @@ export declare class SelaReporter implements Reporter {
         status: string;
         hasScreenshot: boolean;
     }>;
-    /** Test hook — number of screenshots still waiting for a FailedEvent. */
+    /** Test hook - number of screenshots still waiting for a FailedEvent. */
     getPendingScreenshotCount(): number;
     private pendingKey;
     private normalisePath;

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

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

package/dist/reporter/SelaReporter.js

@@ -1,27 +1,30 @@
 "use strict";
 // src/reporter/SelaReporter.ts
 //
-// SelaReporter — Playwright Reporter implementation that drives the
+// 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 so future fixture-aware code
-//      can detect that a reporter is present.
-//   2. onTestEnd — extracts the first PNG screenshot from
+//   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 (surfaces a friendly
-//      SelaError(LLMService, NO_API_KEY) when missing instead of
-//      crashing), flushes pending screenshots onto matching FAILED
-//      events, and invokes SelaEngine.commitUpdates() so the HTML
-//      report + PR automation still fire even when the fixture
-//      teardown never ran.
+//   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.
+// 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) {
@@ -77,8 +80,12 @@ class SelaReporter {
     cwd;
     readLedger;
     clearLedger;
-    runReview;
+    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
@@ -106,10 +113,10 @@ class SelaReporter {
         this.cwd = opts.cwd ?? process.cwd();
         this.readLedger = opts.readLedger ?? PendingPromptLedger_js_1.readPendingPromptsLedger;
         this.clearLedger = opts.clearLedger ?? PendingPromptLedger_js_1.clearPendingPromptsLedger;
-        this.runReview =
-            opts.runReview ??
-                ((entries) => (0, InteractiveReview_js_1.runInteractiveReview)({ entries }));
+        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
@@ -119,6 +126,9 @@ class SelaReporter {
         // 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")
@@ -128,12 +138,12 @@ class SelaReporter {
         const testTitle = test.title;
         const base64Png = this.extractScreenshotBase64(result);
         if (base64Png) {
-            // First try to attach immediately — the engine may have already
+            // 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
+                // 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);
@@ -149,11 +159,14 @@ class SelaReporter {
         });
     }
     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. " +
+                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
@@ -169,36 +182,34 @@ class SelaReporter {
             const msg = err instanceof Error ? err.message : String(err);
             this.logger.error(`[Sela] reporter commitUpdates failed: ${msg}`);
         }
-        // ── Local DX — Interactive review drain ──────────────────────
+        // ── Local DX - Write-and-notify summary ─────────────────────
         //
         // Workers serialise their mutated FileSnapshots to
-        // `<cwd>/.sela/pending-prompts/*.json` because they have no TTY.
-        // The reporter (main process, has stdin/stdout) drains that ledger
-        // here, prompts the developer for each fix, then deletes the dir.
+        // `<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 this entirely — PR automation already handled the
-        // mutations on its isolated branch.
+        // 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);
-                if (entries.length > 0) {
-                    // Banner on stderr so Playwright's stdout summary cannot
-                    // mask it. Visible to the developer even if the readline
-                    // prompt itself races with terminal redraws.
-                    process.stderr.write(`\n[Sela] 🔧 Local DX review starting (${entries.length} fix${entries.length > 1 ? "es" : ""} pending)\n`);
-                    await this.runReview(entries);
+                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] interactive review failed: ${msg}`);
+                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.
+                    // Cleanup failures are non-fatal - the next run will overwrite.
                 }
             }
         }
@@ -213,19 +224,98 @@ class SelaReporter {
             }
         }
     }
-    /** Reporter prints nothing of its own — Playwright stdio stays clean. */
+    /** Reporter prints nothing of its own - Playwright stdio stays clean. */
     printsToStdio() {
         return false;
     }
     // ─────────────────────────────────────────────────────────────
-    // Internals (exposed for testing — prefixed underscore is the
+    // 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
+     * never arrived - most likely worker crashed before the engine
      * could record one).
      *
      * Returns the number of FailedEvents touched.
@@ -248,11 +338,11 @@ class SelaReporter {
         }
         return total;
     }
-    /** Test hook — read-only snapshot of recorded failures. */
+    /** Test hook - read-only snapshot of recorded failures. */
     getRecordedFailures() {
         return this.failures.slice();
     }
-    /** Test hook — number of screenshots still waiting for a FailedEvent. */
+    /** Test hook - number of screenshots still waiting for a FailedEvent. */
     getPendingScreenshotCount() {
         return this.pendingScreenshots.size;
     }
@@ -287,7 +377,7 @@ class SelaReporter {
             const contentType = (att.contentType ?? "").toLowerCase();
             const looksLikePng = contentType.includes("png") ||
                 (att.name ?? "").toLowerCase().includes("screenshot") ||
-                ((att.path ?? "").toLowerCase().endsWith(".png"));
+                (att.path ?? "").toLowerCase().endsWith(".png");
             if (!looksLikePng)
                 continue;
             // Playwright >= 1.46 sometimes inlines the body for small images.
@@ -303,7 +393,7 @@ class SelaReporter {
                     return bytes.toString("base64");
                 }
                 catch {
-                    // Temp file already gone — nothing we can do.
+                    // Temp file already gone - nothing we can do.
                 }
             }
         }
@@ -323,6 +413,16 @@ function defaultIsCi() {
     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

@@ -1,6 +1,9 @@
 import { SelectorSegment } from "./LLMService";
 import { AdvisoryBuffer } from "./HealingAdvisory";
 import type { SmartChainSegment } from "./LLMService";
+import { TraceOutcome } from "./TraceBackEngine";
+import { Decision } from "./DecisionEngine";
+import { FileBatch, ApplyOutcome, ApplyOptions } from "./MutationApplier";
 export interface ASTUpdateResult {
     success: boolean;
     reason: string;
@@ -21,14 +24,55 @@ interface CallerContext {
     filePath: string;
     line: number;
 }
+export interface ComposeHealInput {
+    filePath: string;
+    /** 1-based line of the failing call-site. */
+    line: number;
+    /** 0-based column; when omitted the first non-whitespace char of the line is used. */
+    column?: number;
+    /**
+     * Healed locator EXPRESSION text, e.g. `page.locator(".btn-v2")`. When
+     * omitted, it is BUILT from `newSelector` + the traced target's root
+     * receiver (internal selectors → idiomatic method form).
+     */
+    newLocatorExpr?: string;
+    /** Raw healed selector string (may be an `internal:` engine selector). */
+    newSelector?: string;
+    /** Runtime: only the failing test needs the new selector. */
+    contextSpecific?: boolean;
+    /** Runtime: selector rot is global across all consumers. */
+    globalCorrect?: boolean;
+    /** When true, write the result via MutationApplier (with the gate). */
+    apply?: boolean;
+    applyOptions?: ApplyOptions;
+}
+export interface ComposeHealResult {
+    kind: "decision" | "abort";
+    trace: TraceOutcome;
+    decision?: Decision;
+    batch?: FileBatch;
+    outcome?: ApplyOutcome;
+    /** 1-based line of the mutated target node (for report/diff). */
+    writtenLine?: number;
+}
 export declare class ASTSourceUpdater {
     private project;
     readonly advisoryBuffer: AdvisoryBuffer;
     flushAdvisories(): void;
+    /**
+     * Trace the failing call-site back to its source declaration, decide the
+     * mutation strategy (in-place / fork / prompt), and — when `apply` is set —
+     * write it to disk through the type-safety gate.
+     */
+    static composeHeal(input: ComposeHealInput): ComposeHealResult;
+    /** Drain-loop entry: apply pre-built batches through the write gate. */
+    static applyMutationBatches(batches: FileBatch[], opts?: ApplyOptions): ApplyOutcome[];
+    /** Convert a DecisionEngine result into an anchored MutationApplier batch. */
+    static decisionToBatch(filePath: string, decision: Decision): FileBatch;
     /**
      * 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
+     * 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`.
      */
@@ -39,7 +83,7 @@ export declare class ASTSourceUpdater {
         matchedLine?: number;
     };
     /**
-     * Convenience helper — runs `scanFailFastDirective` and throws the
+     * Convenience helper - runs `scanFailFastDirective` and throws the
      * canonical SelaError when the directive is present. Used by SelaEngine
      * as the very first gate inside `heal()`.
      */
@@ -67,7 +111,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;
@@ -86,6 +130,7 @@ export declare class ASTSourceUpdater {
     private lineToOffset;
     resolveFilePath(raw: string): string | null;
     private semanticDispatch;
+    private applyDefinitionSiteHeal;
     private handleIdentifierArg;
     private handlePropertyAccessArg;
     private handleTemplateLiteralArg;

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

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