sela-core 0.1.0-alpha.1

package/dist/reporter/SelaReporter.js

@@ -0,0 +1,517 @@
+"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 ReportMergeService_js_1 = require("../services/ReportMergeService.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");
+const logger_js_1 = require("../utils/logger.js");
+const SummaryTable_js_1 = require("../utils/SummaryTable.js");
+// ───────────────────────────────────────────────────────────────────
+// SelaReporter
+// ───────────────────────────────────────────────────────────────────
+class SelaReporter {
+    engine;
+    report;
+    logger;
+    skipApiKeyCheck;
+    cwd;
+    readLedger;
+    clearLedger;
+    printReview;
+    resolveReportPath;
+    isCi;
+    mergeShards;
+    shouldInstallSignalHandlers;
+    shutdownHandler = null;
+    shuttingDown = false;
+    /** Total tests in the suite, captured at onBegin for the end-of-run summary. */
+    totalTests = 0;
+    /**
+     * 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 ?? logger_js_1.logger;
+        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.mergeShards = opts.mergeShards ?? defaultMergeShards;
+        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";
+        // Snapshot the suite size for the end-of-run summary table. Guarded:
+        // allTests() exists on real Playwright suites but not on test stubs.
+        try {
+            this.totalTests = suite?.allTests?.().length ?? 0;
+        }
+        catch {
+            this.totalTests = 0;
+        }
+        // SELA-5: drop any report shards stranded by a previously crashed run so
+        // this run's merge sees only its own workers' data.
+        try {
+            (0, HealReportService_js_1.clearReportShards)(this.cwd);
+        }
+        catch {
+            /* best-effort — a stale shard dir is non-fatal */
+        }
+        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();
+        // Snapshot the run tallies BEFORE commitUpdates() — it flushes the report
+        // to disk and then clears the in-memory event buffer.
+        const summary = this.collectRunSummary();
+        try {
+            await this.engine.commitUpdates();
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            this.logger.error(`[Sela] reporter commitUpdates failed: ${msg}`);
+        }
+        // ── SELA-5: fan in per-worker heal shards ───────────────────
+        // Local multi-worker runs write one shard per worker (commitUpdates) to
+        // avoid clobbering a shared report file. The reporter is the single
+        // main-process writer, so it is the safe place to merge them into the
+        // final sela-report.{html,json}. CI uses cross-machine `sela merge`.
+        if (!this.isCi()) {
+            try {
+                this.mergeShards(this.cwd);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                this.logger.error(`[Sela] shard merge 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
+            }
+        }
+        // End-of-run ASCII summary (skipped on a clean no-activity run).
+        this.renderRunSummary(summary);
+    }
+    /** Reporter prints nothing of its own - Playwright stdio stays clean. */
+    printsToStdio() {
+        return false;
+    }
+    // ─────────────────────────────────────────────────────────────
+    // End-of-run summary
+    // ─────────────────────────────────────────────────────────────
+    /**
+     * Tally the run's outcome from the report buffer. MUST be called before
+     * commitUpdates() clears the in-memory events. "Errors detected" counts
+     * every broken selector Sela engaged (healed + held + failed); "skipped"
+     * counts heals declined by a developer fail-fast directive.
+     */
+    collectRunSummary() {
+        const healed = this.report.getHealedEvents().length;
+        const held = this.report.getProtectedEvents().length;
+        const failedEvents = this.report.getFailedEvents();
+        const skipped = failedEvents.filter((e) => typeof e.reason === "string" &&
+            e.reason.startsWith("Skipped by Developer")).length;
+        return {
+            testsScanned: this.totalTests,
+            errorsDetected: healed + held + failedEvents.length,
+            successfulHeals: healed,
+            skippedFiles: skipped,
+        };
+    }
+    /**
+     * Render the summary table — but only when Sela actually did something.
+     * A run with zero detected errors prints nothing, keeping the terminal
+     * clean for the common all-green case.
+     */
+    renderRunSummary(summary) {
+        if (summary.errorsDetected === 0)
+            return;
+        this.logger.info("\nSela run summary:");
+        this.logger.info((0, SummaryTable_js_1.renderSummaryTable)(summary));
+    }
+    // ─────────────────────────────────────────────────────────────
+    // 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 shard fan-in (SELA-5). Discovers this run's per-worker shards under
+ * `<cwd>/.sela/report-shards/` and merges them into the final
+ * sela-report.{html,json} + rolling history via ReportMergeService, then clears
+ * the shard dir. A no-op when no shards exist (single-process / no-heal runs),
+ * so it is safe to call unconditionally on every local run.
+ */
+function defaultMergeShards(cwd) {
+    const shardFiles = ReportMergeService_js_1.ReportMergeService.discoverShardFiles((0, HealReportService_js_1.reportShardDir)(cwd), "sela-shard-*.json");
+    if (shardFiles.length === 0)
+        return;
+    try {
+        ReportMergeService_js_1.ReportMergeService.merge({ shardFiles, targetDir: cwd });
+    }
+    finally {
+        (0, HealReportService_js_1.clearReportShards)(cwd);
+    }
+}
+// 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

@@ -0,0 +1,143 @@
+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;
+    strategy: string;
+    lineUpdated?: number;
+    cascadeFixed?: number;
+    /** The normalized locator string that was written to disk. Single source of truth for runtime. */
+    healedLocatorString?: string;
+    /** Populated by semantic dispatch: where the definition was mutated. */
+    definitionSite?: {
+        file: string;
+        line: number;
+    };
+    /** Number of test functions referencing the mutated constant (blast radius). */
+    blastRadius?: number;
+}
+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
+     * 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;
+    private readonly INTERACTIVE_ROLES;
+    update(caller: CallerContext, oldSelector: string, newSelector: string, aiSegments?: SelectorSegment[], fullSelectorContext?: string, contentChange?: {
+        oldText: string;
+        newText: string;
+    }, smartChainSegments?: SmartChainSegment[], originalChainHint?: SmartChainSegment[]): ASTUpdateResult;
+    private strategySmartChain;
+    private attemptPartialChainHeal;
+    private strategyChainCollapse;
+    private runStrategyG;
+    private strategyFrameUpstream;
+    private strategyDeepSymbolResolution;
+    private strategyInlineSemanticFix;
+    private strategyTemplateLiteral;
+    private strategySemanticFragmentScan;
+    private findMatchingChainTail;
+    private replaceChainTailOnly;
+    private applySemanticFix;
+    /**
+     * 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.
+     * All other replacements are allowed.
+     */
+    private static isSafeReplacement;
+    private replaceCallArgument;
+    private semanticToInternal;
+    private performCascadeHeal;
+    private fixPropertyAccessDefinition;
+    private isBlockedByStructuralWall;
+    private identifySuspectIdentifier;
+    private getEnclosingStatement;
+    private findNodeAtLine;
+    private findCallExpressionsInRange;
+    private replaceFrameLocatorArg;
+    private replaceStringLiteralInRange;
+    private updateObjectProperty;
+    private lineToOffset;
+    resolveFilePath(raw: string): string | null;
+    private semanticDispatch;
+    private applyDefinitionSiteHeal;
+    private handleIdentifierArg;
+    private handlePropertyAccessArg;
+    private handleTemplateLiteralArg;
+    private traceSpanExpression;
+    private handleCallExpressionArg;
+    private validateFileSyntax;
+    private broadcastAndReturn;
+}
+export {};
+//# sourceMappingURL=ASTSourceUpdater.d.ts.map

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

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