sela-core 1.0.7 → 1.0.9

package/dist/services/ASTSourceUpdater.js

@@ -49,8 +49,12 @@ const InitializerUpdater_1 = require("./InitializerUpdater");
 const CrossFileHealer_1 = require("./CrossFileHealer");
 const HealingAdvisory_1 = require("./HealingAdvisory");
 const ChainValidator_1 = require("./ChainValidator");
+const TraceBackEngine_1 = require("./TraceBackEngine");
+const DecisionEngine_1 = require("./DecisionEngine");
+const MutationApplier_1 = require("./MutationApplier");
+const SelectorSanitizer_1 = require("./SelectorSanitizer");
 // ═══════════════════════════════════════════════════════════════════
-// FIX #1 — normalizeSelector utility
+// FIX #1 - normalizeSelector utility
 // ═══════════════════════════════════════════════════════════════════
 function normalizeSelector(s) {
     return s
@@ -70,7 +74,7 @@ function normalizeSelector(s) {
 // of "varName", or null otherwise.
 //
 // Why this matters:
-//   const shadowBtn = shadowBtn.getByRole(…)   ← CIRCULAR — must be caught
+//   const shadowBtn = shadowBtn.getByRole(…)   ← CIRCULAR - must be caught
 //   const shadowBtn = page.getByRole(…)        ← CORRECT
 //
 // We walk UP the ancestor chain from the call node looking for a
@@ -83,7 +87,7 @@ function getEnclosingVariableDeclaration(node) {
         if (ts_morph_1.Node.isVariableDeclaration(current)) {
             return current;
         }
-        // Stop climbing past statement boundaries — we only want the immediate
+        // Stop climbing past statement boundaries - we only want the immediate
         // enclosing declaration, not a declaration somewhere further up the tree.
         if (ts_morph_1.Node.isBlock(current) ||
             ts_morph_1.Node.isSourceFile(current) ||
@@ -121,7 +125,7 @@ function isInsideOwnInitializer(callNode, varName) {
 function resolveSafeReceiver(proposedReceiver, rootReceiver, callNode) {
     if (isInsideOwnInitializer(callNode, proposedReceiver)) {
         console.log(`[ScopeGuard] 🔒 Circular reference prevented: ` +
-            `"${proposedReceiver}" is being initialized — ` +
+            `"${proposedReceiver}" is being initialized - ` +
             `falling back to root receiver "${rootReceiver}"`);
         return rootReceiver;
     }
@@ -554,7 +558,7 @@ class MethodMapper {
         for (const seg of segments) {
             const callText = MethodMapper.build(currentReceiver, seg);
             if (callText === null) {
-                console.warn(`[MethodMapper] Cannot build segment type "${seg.type}" — aborting chain`);
+                console.warn(`[MethodMapper] Cannot build segment type "${seg.type}" - aborting chain`);
                 return null;
             }
             const methodPart = callText.slice(currentReceiver.length);
@@ -617,7 +621,7 @@ function deduplicateChainSegments(aiSegments, contextSegments) {
     if (overlap === 0)
         return { deduped: aiSegments, stripped: 0 };
     console.log(`[ChainDedup] ✂️  Stripping ${overlap}/${contextSegments.length} duplicate leading ` +
-        `segment(s) — context already encodes them`);
+        `segment(s) - context already encodes them`);
     return { deduped: aiSegments.slice(overlap), stripped: overlap };
 }
 const PAGE_ROOT_NAMES = new Set([
@@ -731,15 +735,15 @@ function resolveVariableToSegments(sourceFile, varName, beforeLine, depth = 0) {
 // Module-level write gate shared between `ASTSourceUpdater` and the
 // internal `NodeTransformationStrategy`. Centralises three concerns
 // every `saveSync` call site needs:
-//   1. `DryRunGuard.active()` short-circuit — keeps the mutation in
+//   1. `DryRunGuard.active()` short-circuit - keeps the mutation in
 //      memory but suppresses the on-disk write under SELA_DRY_RUN.
-//   2. `sharedWorkspaceSnapshot.preWrite()` — captures `contentBefore`
+//   2. `sharedWorkspaceSnapshot.preWrite()` - captures `contentBefore`
 //      so the Clean-Room ledger / Local DX rollback can rewind.
-//   3. `sharedWorkspaceSnapshot.postWrite()` — refreshes `contentAfter`
+//   3. `sharedWorkspaceSnapshot.postWrite()` - refreshes `contentAfter`
 //      so `getMutatedSnapshots()` (driving the pending-prompts ledger
 //      and the interactive CLI prompt) sees the new disk state.
 //
-// Strategies do NOT receive the persistence service via DI — they call
+// Strategies do NOT receive the persistence service via DI - they call
 // this helper directly. Same singleton, zero coupling, one code path.
 // ═══════════════════════════════════════════════════════════════════
 function persistSourceFile(sourceFile) {
@@ -753,7 +757,7 @@ function persistSourceFile(sourceFile) {
     WorkspaceSnapshotService_1.sharedWorkspaceSnapshot.postWrite(fp);
 }
 // ═══════════════════════════════════════════════════════════════════
-// NODE TRANSFORMATION STRATEGY — Scope-Aware, Zero-Redundancy
+// NODE TRANSFORMATION STRATEGY - Scope-Aware, Zero-Redundancy
 // ═══════════════════════════════════════════════════════════════════
 class NodeTransformationStrategy {
     chainValidator;
@@ -823,8 +827,10 @@ class NodeTransformationStrategy {
         // When AI's first segment TYPE matches the receiver variable's defining type
         // but with a different selector, the AI is replacing the receiver context.
         // Strategy: update the receiver variable's definition, then use remaining
-        // segments with the receiver var — preserving developer's variable structure.
-        if (!forcedReceiver && discoveredAstRoot && !PAGE_ROOT_NAMES.has(discoveredAstRoot)) {
+        // segments with the receiver var - preserving developer's variable structure.
+        if (!forcedReceiver &&
+            discoveredAstRoot &&
+            !PAGE_ROOT_NAMES.has(discoveredAstRoot)) {
             const typeCheckRes = resolveVariableToSegments(sourceFile, discoveredAstRoot, caller.line);
             if (typeCheckRes.segments.length > 0 && workingSegments.length > 0) {
                 const receiverDefType = typeCheckRes.segments[typeCheckRes.segments.length - 1].type;
@@ -923,8 +929,9 @@ class NodeTransformationStrategy {
             // to prevent.  Skip the candidate; the semantic gate owns this case.
             const firstArg = call.getArguments()[0];
             if (firstArg &&
-                (ts_morph_1.Node.isIdentifier(firstArg) || ts_morph_1.Node.isPropertyAccessExpression(firstArg))) {
-                console.log(`[NodeTransform] 🛑 skip — first arg is ${firstArg.getKindName()} ` +
+                (ts_morph_1.Node.isIdentifier(firstArg) ||
+                    ts_morph_1.Node.isPropertyAccessExpression(firstArg))) {
+                console.log(`[NodeTransform] 🛑 skip - first arg is ${firstArg.getKindName()} ` +
                     `"${firstArg.getText()}" (semantic dispatch owns definition-site mutations)`);
                 continue;
             }
@@ -936,12 +943,12 @@ class NodeTransformationStrategy {
             // Before we build code, we must verify that the proposed receiver
             // does not create a circular self-reference.
             //
-            // Case A — forcedReceiver is set (strip-and-force path):
+            // Case A - forcedReceiver is set (strip-and-force path):
             //   Check if the chainTop lives inside the initializer of that var.
             //   If yes, fall back to the actual AST root (e.g. "page").
             //
-            // Case B — no forced receiver:
-            //   Use astRoot directly — it was walked up from the call node and
+            // Case B - no forced receiver:
+            //   Use astRoot directly - it was walked up from the call node and
             //   is always either "page" or a stable variable reference.
             // ══════════════════════════════════════════════════════════════
             let effectiveReceiver;
@@ -1191,7 +1198,7 @@ class NodeTransformationStrategy {
     }
     updateReceiverDefinition(sourceFile, varName, segType, newSelector, callerLine) {
         // Collect all matching declarations, then pick the closest one that
-        // appears strictly BEFORE callerLine — prevents accidentally updating
+        // appears strictly BEFORE callerLine - prevents accidentally updating
         // a same-named variable in a different test block that happens to be
         // within the 100-line distance window.
         const declarations = sourceFile.getDescendantsOfKind(ts_morph_1.SyntaxKind.VariableDeclaration);
@@ -1302,7 +1309,7 @@ class NodeTransformationStrategy {
                         .map((d) => `[TS${d.getCode()}] ${d.getMessageText()}`)
                         .join(", "));
                 if (/\.(getBy\w+|frameLocator)\s*\(/.test(code)) {
-                    console.warn(`[NodeTransform] ⚠️  Semantic method detected — bypassing validation`);
+                    console.warn(`[NodeTransform] ⚠️  Semantic method detected - bypassing validation`);
                     return true;
                 }
                 return false;
@@ -1550,19 +1557,145 @@ function findAssertionsInWindow(sourceFile, locatorVarName, callerLine, windowLi
     }
     return results;
 }
-// ═══════════════════════════════════════════════════════════════════
-// MAIN CLASS
-// ═══════════════════════════════════════════════════════════════════
+/**
+ * Build a locator EXPRESSION from a raw healed selector + chain root.
+ * Internal engine selectors become their idiomatic method form
+ * (`page.getByRole(...)`); otherwise a `root.locator("selector")` call.
+ */
+function buildLocatorExpr(rawSelector, rootReceiver) {
+    const root = rootReceiver || "page";
+    if (!rawSelector)
+        return `${root}.locator("")`;
+    if ((0, SelectorSanitizer_1.isInternalEngineSelector)(rawSelector)) {
+        const method = (0, SelectorSanitizer_1.internalToMethodExpression)(rawSelector, root);
+        if (method)
+            return method;
+        const publicStr = (0, SelectorSanitizer_1.internalToPublicSelectorString)(rawSelector);
+        return `${root}.locator(${JSON.stringify(publicStr ?? rawSelector)})`;
+    }
+    return `${root}.locator(${JSON.stringify(rawSelector)})`;
+}
+/** 0-based column of the first non-whitespace char on a 1-based line. */
+function firstNonWhitespaceColumn(text, line1Based) {
+    const lines = text.split(/\r?\n/);
+    const idx = line1Based - 1;
+    if (idx < 0 || idx >= lines.length)
+        return 0;
+    const m = lines[idx].match(/^(\s*)/);
+    return m ? m[1].length : 0;
+}
 class ASTSourceUpdater {
     project;
     advisoryBuffer = new HealingAdvisory_1.AdvisoryBuffer();
     flushAdvisories() {
         this.advisoryBuffer.flush();
     }
+    // ═══════════════════════════════════════════════════════════════════
+    // STAGE 4 — end-to-end trace → decide → apply (Stages 1-3 wired in)
+    //
+    // Additive entry point. The legacy heal paths below are untouched; this
+    // is the new write-disciplined pipeline that composes AnchorResolver,
+    // TraceBackEngine, DecisionEngine and MutationApplier.
+    // ═══════════════════════════════════════════════════════════════════
+    /**
+     * 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) {
+        const original = fs.readFileSync(input.filePath, "utf8");
+        const project = new ts_morph_1.Project({
+            useInMemoryFileSystem: true,
+            compilerOptions: {
+                allowJs: true,
+                noEmit: true,
+                skipLibCheck: true,
+                noResolve: true,
+            },
+        });
+        const sf = project.createSourceFile(input.filePath, original, {
+            overwrite: true,
+        });
+        // Resolve a robust position: when no explicit column is given, use the
+        // first non-whitespace char of the line (avoids landing on indentation).
+        const column = input.column ?? firstNonWhitespaceColumn(original, input.line);
+        const trace = TraceBackEngine_1.TraceBackEngine.traceFromPosition(sf, input.line, column);
+        if (trace.status !== "target") {
+            return { kind: "abort", trace };
+        }
+        // Re-resolve the node at the failing position for fork test-block lookup.
+        let failingNode;
+        try {
+            failingNode = sf.getDescendantAtPos(sf.compilerNode.getPositionOfLineAndCharacter(input.line - 1, column));
+        }
+        catch {
+            failingNode = undefined;
+        }
+        if (!failingNode)
+            failingNode = trace.target.targetNode;
+        // Build the replacement EXPRESSION. Explicit newLocatorExpr wins; else
+        // synthesise it from the raw healed selector + the traced root receiver,
+        // translating internal engine selectors to their idiomatic method form.
+        const newLocatorExpr = input.newLocatorExpr ??
+            buildLocatorExpr(input.newSelector ?? "", trace.target.rootReceiver);
+        const decision = DecisionEngine_1.DecisionEngine.decide({
+            target: trace.target,
+            failingCallSite: failingNode,
+            newLocatorExpr,
+            contextSpecific: input.contextSpecific ?? false,
+            globalCorrect: input.globalCorrect ?? false,
+        });
+        const batch = ASTSourceUpdater.decisionToBatch(input.filePath, decision);
+        const result = {
+            kind: "decision",
+            trace,
+            decision,
+            batch,
+            writtenLine: trace.target.targetNode.getStartLineNumber(),
+        };
+        if (input.apply && batch.edits.length > 0) {
+            result.outcome = MutationApplier_1.MutationApplier.applyFileBatch(batch, input.applyOptions ?? {});
+        }
+        return result;
+    }
+    /** Drain-loop entry: apply pre-built batches through the write gate. */
+    static applyMutationBatches(batches, opts = {}) {
+        return MutationApplier_1.MutationApplier.applyBatches(batches, opts);
+    }
+    /** Convert a DecisionEngine result into an anchored MutationApplier batch. */
+    static decisionToBatch(filePath, decision) {
+        const edits = decision.edits.map((e) => {
+            if (e.kind === "insert") {
+                return {
+                    kind: "insert",
+                    replacement: e.replacement,
+                    span: e.span,
+                    requireLocator: false,
+                };
+            }
+            // MUTATE_IN_PLACE replace → anchor-resolved + Locator-type-gated.
+            if (decision.strategy === "MUTATE_IN_PLACE") {
+                return {
+                    kind: "replace",
+                    replacement: e.replacement,
+                    anchor: decision.anchor,
+                    requireLocator: true,
+                };
+            }
+            // FORK call-site receiver rewrite → identifier, not a locator.
+            return {
+                kind: "replace",
+                replacement: e.replacement,
+                span: e.span,
+                requireLocator: false,
+            };
+        });
+        return { filePath, edits };
+    }
     /**
      * 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`.
      */
@@ -1579,7 +1712,7 @@ class ASTSourceUpdater {
     // BEFORE the LLM call and record a FailedEvent in the "Skipped by
     // Developer" category.
     //
-    // Implementation note — ts-morph's `Node.getLeadingCommentRanges()`
+    // Implementation note - ts-morph's `Node.getLeadingCommentRanges()`
     // returns `ts.CommentRange[]` (offsets, not text). We slice the full
     // source text by `(pos, end)` to recover the raw comment for each
     // range, matching both `//` line comments and `/* */` block comments
@@ -1643,7 +1776,7 @@ class ASTSourceUpdater {
         return { failFast: false };
     }
     /**
-     * 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()`.
      */
@@ -1790,7 +1923,7 @@ class ASTSourceUpdater {
             sourceFile = this.project.addSourceFileAtPath(filePath);
         }
         if (caller.line <= 0) {
-            console.log(`[ASTUpdater] ⚠️  line ${caller.line} invalid — Attempting Global Template Strategy`);
+            console.log(`[ASTUpdater] ⚠️  line ${caller.line} invalid - Attempting Global Template Strategy`);
             const globalResult = this.strategyTemplateLiteral(sourceFile, caller, oldSelector, newSelector);
             if (globalResult && globalResult.success) {
                 if (contentChange)
@@ -1814,7 +1947,7 @@ class ASTSourceUpdater {
         // node when they differ) for `// sela-fail-fast`. When present, abort
         // all heal work with SelaError(AST_HEAL_DISABLED_BY_DIRECTIVE) so the
         // engine records a FailedEvent in the "Skipped by Developer" bucket.
-        // Defense-in-depth — SelaEngine also calls this at the very start of
+        // Defense-in-depth - SelaEngine also calls this at the very start of
         // heal() to skip the LLM round-trip entirely.
         this.enforceFailFastDirective(caller);
         const suspectIdentifier = statement
@@ -1827,7 +1960,7 @@ class ASTSourceUpdater {
         // HARD EXIT: any non-null result (success OR failure) stops all
         // subsequent AST strategies.  When the locator argument is an
         // Identifier, PropertyAccess, or TemplateLiteral, the gate owns
-        // the mutation — NT/H must never override the symbolic reference.
+        // the mutation - NT/H must never override the symbolic reference.
         const semanticResult = this.semanticDispatch(sourceFile, caller, oldSelector, newSelector);
         if (semanticResult !== null) {
             if (semanticResult.success) {
@@ -1836,7 +1969,7 @@ class ASTSourceUpdater {
                 }
                 return this.broadcastAndReturn(semanticResult, oldSelector, newSelector, caller);
             }
-            // Failure (blast-radius block, trace failed, syntax error) — hard stop.
+            // Failure (blast-radius block, trace failed, syntax error) - hard stop.
             console.log(`[SemanticDispatch] 🚫 Hard stop (${semanticResult.strategy}): ${semanticResult.reason}`);
             return semanticResult;
         }
@@ -1885,7 +2018,7 @@ class ASTSourceUpdater {
         };
     }
     // ═══════════════════════════════════════════════════════════════
-    // STRATEGY H — Smart Chain (Legacy fallback)
+    // STRATEGY H - Smart Chain (Legacy fallback)
     // ═══════════════════════════════════════════════════════════════
     strategySmartChain(sourceFile, caller, oldSelector, oldSem, smartSegments, originalChainHint, suspectIdentifier) {
         console.log(`[ASTUpdater] 🔗 Strategy H v2: Smart Chain (${smartSegments.length} segments)`);
@@ -1959,13 +2092,14 @@ class ASTSourceUpdater {
             return b.chainDepth - a.chainDepth;
         });
         for (const { leafCall, chainTop, rootReceiver, chainDepth, originalText, } of candidates) {
-            // Identifier/PropertyAccess guard — mirrors the NT guard.
+            // Identifier/PropertyAccess guard - mirrors the NT guard.
             // Strategy H must never substitute a hardcoded string for a symbolic
             // reference; the semantic dispatch gate owns definition-site mutations.
             const firstArgH = leafCall.getArguments()[0];
             if (firstArgH &&
-                (ts_morph_1.Node.isIdentifier(firstArgH) || ts_morph_1.Node.isPropertyAccessExpression(firstArgH))) {
-                console.log(`[StrategyH] 🛑 skip — first arg is ${firstArgH.getKindName()} ` +
+                (ts_morph_1.Node.isIdentifier(firstArgH) ||
+                    ts_morph_1.Node.isPropertyAccessExpression(firstArgH))) {
+                console.log(`[StrategyH] 🛑 skip - first arg is ${firstArgH.getKindName()} ` +
                     `"${firstArgH.getText()}" (semantic dispatch owns definition-site mutations)`);
                 continue;
             }
@@ -2035,8 +2169,9 @@ class ASTSourceUpdater {
         // Block H-partial from substituting a literal for an Identifier/PropertyAccess arg.
         const targetFirstArg = targetCall.getArguments()[0];
         if (targetFirstArg &&
-            (ts_morph_1.Node.isIdentifier(targetFirstArg) || ts_morph_1.Node.isPropertyAccessExpression(targetFirstArg))) {
-            console.log(`[H-partial] 🛑 skip — arg is ${targetFirstArg.getKindName()} ` +
+            (ts_morph_1.Node.isIdentifier(targetFirstArg) ||
+                ts_morph_1.Node.isPropertyAccessExpression(targetFirstArg))) {
+            console.log(`[H-partial] 🛑 skip - arg is ${targetFirstArg.getKindName()} ` +
                 `"${targetFirstArg.getText()}" (semantic dispatch owns this)`);
             return null;
         }
@@ -2072,7 +2207,7 @@ class ASTSourceUpdater {
         }
     }
     // ─────────────────────────────────────────────────────────────
-    // STRATEGY F — Chain Collapse
+    // STRATEGY F - Chain Collapse
     // ─────────────────────────────────────────────────────────────
     strategyChainCollapse(sourceFile, caller, oldSelector, newSelector, oldSem, newSem) {
         console.log(`[ASTUpdater] ⛓️  Strategy F: Chain Collapse (upward traversal)`);
@@ -2138,7 +2273,7 @@ class ASTSourceUpdater {
         };
     }
     // ─────────────────────────────────────────────────────────────
-    // STRATEGY G — Assertion Healing
+    // STRATEGY G - Assertion Healing
     // ─────────────────────────────────────────────────────────────
     runStrategyG(sourceFile, caller, locatorVarName, contentChange) {
         if (!contentChange)
@@ -2170,7 +2305,7 @@ class ASTSourceUpdater {
         return null;
     }
     // ─────────────────────────────────────────────────────────────
-    // STRATEGY A — Frame Upstream Healing
+    // STRATEGY A - Frame Upstream Healing
     // ─────────────────────────────────────────────────────────────
     strategyFrameUpstream(sourceFile, caller, oldElementSelector, aiSegments, fullSelectorContext) {
         console.log(`[ASTUpdater] 🧠 Strategy A: Frame Upstream`);
@@ -2246,7 +2381,7 @@ class ASTSourceUpdater {
         };
     }
     // ─────────────────────────────────────────────────────────────
-    // STRATEGY B — Deep Symbol Resolution
+    // STRATEGY B - Deep Symbol Resolution
     // ─────────────────────────────────────────────────────────────
     strategyDeepSymbolResolution(sourceFile, caller, oldSelector, newSelector, oldSem, newSem, suspectIdentifier) {
         console.log(`[ASTUpdater] 🔭 Strategy B: Deep Symbol Resolution`);
@@ -2430,7 +2565,7 @@ class ASTSourceUpdater {
         };
     }
     // ─────────────────────────────────────────────────────────────
-    // STRATEGY C — Inline Semantic Fix
+    // STRATEGY C - Inline Semantic Fix
     // ─────────────────────────────────────────────────────────────
     strategyInlineSemanticFix(sourceFile, caller, oldSelector, newSelector, oldSem, newSem) {
         console.log(`[ASTUpdater] 🎯 Strategy C: Inline Semantic Fix`);
@@ -2488,7 +2623,7 @@ class ASTSourceUpdater {
         };
     }
     // ─────────────────────────────────────────────────────────────
-    // STRATEGY D — Template Literal
+    // STRATEGY D - Template Literal
     // ─────────────────────────────────────────────────────────────
     strategyTemplateLiteral(sourceFile, caller, oldSelector, newSelector) {
         console.log(`[ASTUpdater] 🔤 Strategy D: Template Literal`);
@@ -2545,7 +2680,7 @@ class ASTSourceUpdater {
         };
     }
     // ─────────────────────────────────────────────────────────────
-    // STRATEGY E — Semantic Fragment Scan
+    // STRATEGY E - Semantic Fragment Scan
     // ─────────────────────────────────────────────────────────────
     strategySemanticFragmentScan(sourceFile, caller, oldSelector, newSelector, oldSem, newSem) {
         console.log(`[ASTUpdater] 🔎 Strategy E: Semantic Fragment Scan`);
@@ -2666,7 +2801,7 @@ 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.
      */
     static isSafeReplacement(oldNode, proposedNewText) {
@@ -2690,7 +2825,7 @@ class ASTSourceUpdater {
                 firstArg.replaceWithText(`"${safe}"`);
             }
             else {
-                console.warn(`[ASTUpdater] ⚠️ replaceCallArgument: blocked unsafe replacement — ` +
+                console.warn(`[ASTUpdater] ⚠️ replaceCallArgument: blocked unsafe replacement - ` +
                     `arg is ${firstArg.getKindName()}, not a string literal. ` +
                     `Heal at definition site instead.`);
                 return false;
@@ -2992,10 +3127,10 @@ class ASTSourceUpdater {
                     shape === "PROPERTY_ACCESS" ||
                     shape === "TEMPLATE_LITERAL") {
                     console.log(`[SemanticDispatch] 🛑 hard-block: "${node.getText()}" is ${shape} ` +
-                        `but trace failed — preserving call site`);
+                        `but trace failed - preserving call site`);
                     return {
                         success: false,
-                        reason: `semantic guard: could not trace "${node.getText()}" — call site preserved`,
+                        reason: `semantic guard: could not trace "${node.getText()}" - call site preserved`,
                         strategy: "semantic-guard",
                     };
                 }
@@ -3007,6 +3142,72 @@ class ASTSourceUpdater {
             return null;
         }
     }
+    // ═══════════════════════════════════════════════════════════════════
+    // DEFINITION-SITE WRITE (with internal→public Method-Shift fallback)
+    //
+    // A `const X = "selector"` consumed by `.locator(X)` cannot hold a semantic
+    // locator (page.getByRole(...) would reference `page` out of scope at the
+    // declaration). So when the AI heals to an internal engine selector
+    // (`internal:role=…`), we DON'T abort and we DON'T leak the engine string:
+    // we translate it to a VALID PUBLIC selector string (`role=button[name="…"]`)
+    // and write THAT into the constant — keeping the developer's architecture
+    // intact — while surfacing the cleaner semantic method form (getByRole) as
+    // a suggested upgrade in the advisory/report.
+    // ═══════════════════════════════════════════════════════════════════
+    applyDefinitionSiteHeal(targetNode, targetFile, newSelector, strategy, blastRadius) {
+        const wasInternal = (0, SelectorSanitizer_1.isInternalEngineSelector)(newSelector);
+        let writeValue = newSelector;
+        if (wasInternal) {
+            const publicStr = (0, SelectorSanitizer_1.internalToPublicSelectorString)(newSelector);
+            if (!publicStr) {
+                // No public string engine (e.g. label association) → a .locator()
+                // string constant genuinely cannot express it. Preserve the call site.
+                return {
+                    success: false,
+                    reason: `semantic guard: internal selector "${newSelector.slice(0, 48)}" has no public ` +
+                        `.locator() string form - call site preserved (method-shift required)`,
+                    strategy: "semantic-guard",
+                };
+            }
+            writeValue = publicStr;
+            console.log(`[SemanticDispatch] 🔁 Method-Shift fallback: internal selector → public string "${writeValue}"`);
+        }
+        const result = InitializerUpdater_1.InitializerUpdater.apply(targetNode, targetFile, writeValue);
+        if (!result)
+            return null;
+        if (!this.validateFileSyntax(targetFile)) {
+            return {
+                success: false,
+                reason: "post-mutation syntax validation failed - reverted",
+                strategy,
+            };
+        }
+        if (wasInternal) {
+            const methodExpr = (0, SelectorSanitizer_1.internalToMethodExpression)(newSelector, "page");
+            this.advisoryBuffer.push({
+                code: HealingAdvisory_1.AdvisoryCode.SEMANTIC_UPGRADE_SUGGESTED,
+                message: `Healed constant to public selector string "${writeValue}". ` +
+                    `Cleaner semantic form: ${methodExpr ?? "a getBy* method"}.`,
+                affectedFile: targetFile.getFilePath(),
+                affectedLine: result.lineUpdated,
+                suggestedAction: `For more resilient code, rewrite the call site to ${methodExpr ?? "the semantic locator"} ` +
+                    `instead of the string constant.`,
+            });
+        }
+        return {
+            success: true,
+            reason: `definition-site heal via ${strategy} trace` +
+                (wasInternal ? " (internal→public string; semantic upgrade suggested)" : ""),
+            strategy,
+            lineUpdated: result.lineUpdated,
+            healedLocatorString: result.healedLocatorString,
+            definitionSite: {
+                file: targetFile.getFilePath(),
+                line: result.lineUpdated,
+            },
+            blastRadius,
+        };
+    }
     handleIdentifierArg(node, sourceFile, caller, newSelector) {
         const traceResult = DefinitionTracer_1.DefinitionTracer.traceIdentifier(node, sourceFile, caller.line);
         if (traceResult.found) {
@@ -3018,45 +3219,27 @@ class ASTSourceUpdater {
             if (blast.risk === "high") {
                 this.advisoryBuffer.push({
                     code: HealingAdvisory_1.AdvisoryCode.BLAST_RADIUS_BLOCKED,
-                    message: `Mutation blocked — ${blast.testFunctionCount} tests reference this constant.`,
+                    message: `Mutation blocked - ${blast.testFunctionCount} tests reference this constant.`,
                     affectedFile: targetFile.getFilePath(),
                     affectedLine: targetNode.getStartLineNumber() - 1,
                     suggestedAction: "Review all referencing tests before changing this constant.",
                 });
                 return {
                     success: false,
-                    reason: `BlastRadius BLOCKED: ${blast.testFunctionCount} tests reference this constant — manual review required`,
+                    reason: `BlastRadius BLOCKED: ${blast.testFunctionCount} tests reference this constant - manual review required`,
                     strategy: "semantic-identifier",
                 };
             }
             if (blast.risk === "medium") {
                 this.advisoryBuffer.push({
                     code: HealingAdvisory_1.AdvisoryCode.BLAST_RADIUS_WARNING,
-                    message: `Mutated constant used in ${blast.testFunctionCount} tests — verify no regressions.`,
+                    message: `Mutated constant used in ${blast.testFunctionCount} tests - verify no regressions.`,
                     affectedFile: targetFile.getFilePath(),
                     affectedLine: targetNode.getStartLineNumber() - 1,
                     suggestedAction: "Run the full test suite to confirm all references still pass.",
                 });
             }
-            const result = InitializerUpdater_1.InitializerUpdater.apply(targetNode, targetFile, newSelector);
-            if (!result)
-                return null;
-            if (!this.validateFileSyntax(targetFile)) {
-                return {
-                    success: false,
-                    reason: "post-mutation syntax validation failed — reverted",
-                    strategy: "semantic-identifier",
-                };
-            }
-            return {
-                success: true,
-                reason: `definition-site heal via identifier trace`,
-                strategy: "semantic-identifier",
-                lineUpdated: result.lineUpdated,
-                healedLocatorString: result.healedLocatorString,
-                definitionSite: { file: targetFile.getFilePath(), line: result.lineUpdated },
-                blastRadius: blast.testFunctionCount,
-            };
+            return this.applyDefinitionSiteHeal(targetNode, targetFile, newSelector, "semantic-identifier", blast.testFunctionCount);
         }
         if (!traceResult.found && traceResult.crossFile) {
             const xResult = CrossFileHealer_1.CrossFileHealer.heal(traceResult.modulePath, traceResult.symbolName, newSelector, caller.filePath, this.project);
@@ -3083,45 +3266,27 @@ class ASTSourceUpdater {
             if (blast.risk === "high") {
                 this.advisoryBuffer.push({
                     code: HealingAdvisory_1.AdvisoryCode.BLAST_RADIUS_BLOCKED,
-                    message: `Mutation blocked — ${blast.testFunctionCount} tests reference this property.`,
+                    message: `Mutation blocked - ${blast.testFunctionCount} tests reference this property.`,
                     affectedFile: targetFile.getFilePath(),
                     affectedLine: targetNode.getStartLineNumber() - 1,
                     suggestedAction: "Review all referencing tests before changing this property.",
                 });
                 return {
                     success: false,
-                    reason: `BlastRadius BLOCKED: ${blast.testFunctionCount} tests reference this property — manual review required`,
+                    reason: `BlastRadius BLOCKED: ${blast.testFunctionCount} tests reference this property - manual review required`,
                     strategy: "semantic-property-access",
                 };
             }
             if (blast.risk === "medium") {
                 this.advisoryBuffer.push({
                     code: HealingAdvisory_1.AdvisoryCode.BLAST_RADIUS_WARNING,
-                    message: `Mutated property used in ${blast.testFunctionCount} tests — verify no regressions.`,
+                    message: `Mutated property used in ${blast.testFunctionCount} tests - verify no regressions.`,
                     affectedFile: targetFile.getFilePath(),
                     affectedLine: targetNode.getStartLineNumber() - 1,
                     suggestedAction: "Run the full test suite to confirm all references still pass.",
                 });
             }
-            const result = InitializerUpdater_1.InitializerUpdater.apply(targetNode, targetFile, newSelector);
-            if (!result)
-                return null;
-            if (!this.validateFileSyntax(targetFile)) {
-                return {
-                    success: false,
-                    reason: "post-mutation syntax validation failed — reverted",
-                    strategy: "semantic-property-access",
-                };
-            }
-            return {
-                success: true,
-                reason: `definition-site heal via property access trace`,
-                strategy: "semantic-property-access",
-                lineUpdated: result.lineUpdated,
-                healedLocatorString: result.healedLocatorString,
-                definitionSite: { file: targetFile.getFilePath(), line: result.lineUpdated },
-                blastRadius: blast.testFunctionCount,
-            };
+            return this.applyDefinitionSiteHeal(targetNode, targetFile, newSelector, "semantic-property-access", blast.testFunctionCount);
         }
         if (!traceResult.found && traceResult.crossFile) {
             const xResult = CrossFileHealer_1.CrossFileHealer.heal(traceResult.modulePath, traceResult.symbolName, newSelector, caller.filePath, this.project);
@@ -3163,10 +3328,11 @@ class ASTSourceUpdater {
                     }
                 }
             }
-            if (patchResult.reason.includes("structural") || patchResult.reason.includes("not found")) {
+            if (patchResult.reason.includes("structural") ||
+                patchResult.reason.includes("not found")) {
                 this.advisoryBuffer.push({
                     code: HealingAdvisory_1.AdvisoryCode.MANUAL_REVIEW_TEMPLATE_COMPLEX,
-                    message: `Template literal requires structural change — automated patch skipped.`,
+                    message: `Template literal requires structural change - automated patch skipped.`,
                     affectedFile: sourceFile.getFilePath(),
                     affectedLine: node.getStartLineNumber() - 1,
                     suggestedAction: "Manually update the template literal and its callers.",
@@ -3180,7 +3346,7 @@ class ASTSourceUpdater {
         if (!this.validateFileSyntax(sourceFile)) {
             return {
                 success: false,
-                reason: "post-mutation syntax validation failed — reverted",
+                reason: "post-mutation syntax validation failed - reverted",
                 strategy: "semantic-template",
             };
         }
@@ -3208,7 +3374,8 @@ class ASTSourceUpdater {
             if (ts_morph_1.Node.isCallExpression(init)) {
                 return this.handleCallExpressionArg(init, sourceFile, oldSpanVal, newSpanVal);
             }
-            if (ts_morph_1.Node.isStringLiteral(init) || ts_morph_1.Node.isNoSubstitutionTemplateLiteral(init)) {
+            if (ts_morph_1.Node.isStringLiteral(init) ||
+                ts_morph_1.Node.isNoSubstitutionTemplateLiteral(init)) {
                 const result = InitializerUpdater_1.InitializerUpdater.apply(init, sourceFile, newSpanVal);
                 if (!result)
                     return null;
@@ -3219,7 +3386,10 @@ class ASTSourceUpdater {
                     strategy: "semantic-template",
                     lineUpdated: result.lineUpdated,
                     healedLocatorString: result.healedLocatorString,
-                    definitionSite: { file: sourceFile.getFilePath(), line: result.lineUpdated },
+                    definitionSite: {
+                        file: sourceFile.getFilePath(),
+                        line: result.lineUpdated,
+                    },
                 };
             }
             if (ts_morph_1.Node.isTemplateExpression(init)) {
@@ -3233,7 +3403,7 @@ class ASTSourceUpdater {
         if (fnAnalysis.kind === "complex") {
             this.advisoryBuffer.push({
                 code: HealingAdvisory_1.AdvisoryCode.MANUAL_REVIEW_CONDITIONAL_RETURN,
-                message: `Function has conditional/complex return — automated patch skipped. Reason: ${fnAnalysis.reason}`,
+                message: `Function has conditional/complex return - automated patch skipped. Reason: ${fnAnalysis.reason}`,
                 affectedFile: sourceFile.getFilePath(),
                 suggestedAction: "Manually update the function's return expression.",
             });
@@ -3246,7 +3416,7 @@ class ASTSourceUpdater {
             if (!this.validateFileSyntax(fnAnalysis.functionFile)) {
                 return {
                     success: false,
-                    reason: "post-mutation syntax validation failed — reverted",
+                    reason: "post-mutation syntax validation failed - reverted",
                     strategy: "semantic-call-expression",
                 };
             }
@@ -3256,7 +3426,10 @@ class ASTSourceUpdater {
                 strategy: "semantic-call-expression",
                 lineUpdated: result.lineUpdated,
                 healedLocatorString: result.healedLocatorString,
-                definitionSite: { file: fnAnalysis.functionFile.getFilePath(), line: result.lineUpdated },
+                definitionSite: {
+                    file: fnAnalysis.functionFile.getFilePath(),
+                    line: result.lineUpdated,
+                },
             };
         }
         if (fnAnalysis.kind === "template") {
@@ -3266,7 +3439,7 @@ class ASTSourceUpdater {
                 if (patchResult.reason.includes("structural")) {
                     this.advisoryBuffer.push({
                         code: HealingAdvisory_1.AdvisoryCode.MANUAL_REVIEW_TEMPLATE_COMPLEX,
-                        message: `Function template return requires structural change — automated patch skipped.`,
+                        message: `Function template return requires structural change - automated patch skipped.`,
                         affectedFile: fnAnalysis.functionFile.getFilePath(),
                         affectedLine: fnAnalysis.functionLine - 1,
                         suggestedAction: "Manually update the function's template literal.",
@@ -3280,7 +3453,7 @@ class ASTSourceUpdater {
             if (!this.validateFileSyntax(fnAnalysis.functionFile)) {
                 return {
                     success: false,
-                    reason: "post-mutation syntax validation failed — reverted",
+                    reason: "post-mutation syntax validation failed - reverted",
                     strategy: "semantic-call-expression",
                 };
             }
@@ -3290,7 +3463,10 @@ class ASTSourceUpdater {
                 strategy: "semantic-call-expression",
                 lineUpdated,
                 healedLocatorString: newSelector,
-                definitionSite: { file: fnAnalysis.functionFile.getFilePath(), line: lineUpdated },
+                definitionSite: {
+                    file: fnAnalysis.functionFile.getFilePath(),
+                    line: lineUpdated,
+                },
             };
         }
         return null;
@@ -3306,11 +3482,13 @@ class ASTSourceUpdater {
             return !ALLOWED_CODES.has(d.getCode());
         });
         if (syntaxErrors.length > 0) {
-            const msgs = syntaxErrors.map((d) => String(d.getMessageText())).join("; ");
-            console.warn(`[SemanticDispatch] ⚠️ syntax errors after mutation: ${msgs} — reverting`);
+            const msgs = syntaxErrors
+                .map((d) => String(d.getMessageText()))
+                .join("; ");
+            console.warn(`[SemanticDispatch] ⚠️ syntax errors after mutation: ${msgs} - reverting`);
             this.advisoryBuffer.push({
                 code: HealingAdvisory_1.AdvisoryCode.POST_MUTATION_TYPE_ERROR,
-                message: `Post-mutation type errors detected — mutation reverted. Errors: ${msgs}`,
+                message: `Post-mutation type errors detected - mutation reverted. Errors: ${msgs}`,
                 affectedFile: sourceFile.getFilePath(),
                 suggestedAction: "Manually inspect and fix the type errors introduced by this heal.",
             });