sela-core 1.0.8 → 1.0.9

package/dist/services/SelectorSanitizer.d.ts

@@ -0,0 +1,52 @@
+/**
+ * True when `value` is (or contains, in a `>>` chain) a Playwright internal
+ * engine selector. These start with the `internal:` engine prefix.
+ */
+export declare function isInternalEngineSelector(value: string): boolean;
+interface MethodDescriptor {
+    method: string;
+    primaryArg: string;
+    options?: Record<string, string | boolean | number>;
+}
+/**
+ * Parse a SINGLE internal selector segment into a method descriptor, or null
+ * when it is not a recognised internal form (so callers REFUSE rather than
+ * guess). Mirrors the engine→public mapping used by ASTSourceUpdater.
+ */
+export declare function parseInternalSelector(selector: string): MethodDescriptor | null;
+export declare function buildMethodCall(receiver: string, desc: MethodDescriptor): string;
+/**
+ * Translate an internal selector string into an idiomatic Playwright method
+ * expression rooted at `receiver`. Handles `>>` chains by chaining each
+ * segment. Returns null when ANY segment is an unrecognised internal form
+ * (frame `internal:control=…` plumbing, unknown engines) — the caller must
+ * then refuse rather than emit something fragile.
+ */
+export declare function internalToMethodExpression(selector: string, receiver?: string): string | null;
+/**
+ * Convert an internal engine selector into a VALID PUBLIC `.locator()` string,
+ * preserving `>>` chaining. Returns null when ANY internal segment has no
+ * public string engine (so the caller must method-shift or refuse instead of
+ * stuffing an unusable string into a constant).
+ *
+ * Example: `internal:role=button[name="Update System"i]`
+ *        → `role=button[name="Update System"]`
+ */
+export declare function internalToPublicSelectorString(selector: string): string | null;
+export interface SanitizeResult {
+    /** The (possibly rewritten) expression text. */
+    text: string;
+    /** True when the original contained an internal selector that was rewritten. */
+    sanitized: boolean;
+    /** False when an internal selector remained that could NOT be translated. */
+    safe: boolean;
+}
+/**
+ * Rewrite any `recv.locator("internal:…")` / `recv.frameLocator("internal:…")`
+ * inside `expr` to its idiomatic method form. Returns `safe:false` when an
+ * internal selector remains that cannot be translated, so the caller refuses
+ * to write it.
+ */
+export declare function sanitizeLocatorExpression(expr: string): SanitizeResult;
+export {};
+//# sourceMappingURL=SelectorSanitizer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SelectorSanitizer.d.ts","sourceRoot":"","sources":["../../src/services/SelectorSanitizer.ts"],"names":[],"mappings":"AAoCA;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAK/D;AAMD,UAAU,gBAAgB;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC,CAAC;CACrD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CA6D/E;AAWD,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAyBhF;AAMD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,MAAM,EAChB,QAAQ,SAAS,GAChB,MAAM,GAAG,IAAI,CAmBf;AAgDD;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAkB9E;AAMD,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,SAAS,EAAE,OAAO,CAAC;IACnB,6EAA6E;IAC7E,IAAI,EAAE,OAAO,CAAC;CACf;AAID;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAgEtE"}

package/dist/services/SelectorSanitizer.js

@@ -0,0 +1,318 @@
+"use strict";
+// src/services/SelectorSanitizer.ts
+//
+// THE ABSOLUTE RULE (Ticket #2 hardening):
+// Playwright's `internal:` engine selectors (e.g.
+// `internal:role=button[name="Update System"i]`) are a PRIVATE runtime
+// serialization. They must NEVER be written verbatim into user source — not
+// as a `.locator()` string argument, and not into a string-literal constant
+// consumed by `.locator()`. Although the engine happens to accept them at
+// runtime, they are undocumented, version-fragile, and leak internals into
+// the developer's clean code (bad DX, the exact bug this module prevents).
+//
+// This module is the single source of truth for:
+//   1. DETECTING an internal engine selector (`isInternalEngineSelector`).
+//   2. TRANSLATING it to the idiomatic public method form
+//      (`internalToMethodExpression`) — `getByRole(...)`, `getByText(...)`, …
+//   3. SANITIZING a full locator expression (`sanitizeLocatorExpression`):
+//      rewriting `recv.locator("internal:…")` → `recv.getByRole(…)`, and
+//      reporting whether anything internal remains (unconvertible ⇒ unsafe).
+//
+// Pure, dependency-light (ts-morph only for expression rewriting). Every
+// write-head (InitializerUpdater, MutationApplier, SourceUpdater regex gate)
+// consults this so the invariant holds across all heal paths.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isInternalEngineSelector = isInternalEngineSelector;
+exports.parseInternalSelector = parseInternalSelector;
+exports.buildMethodCall = buildMethodCall;
+exports.internalToMethodExpression = internalToMethodExpression;
+exports.internalToPublicSelectorString = internalToPublicSelectorString;
+exports.sanitizeLocatorExpression = sanitizeLocatorExpression;
+const ts_morph_1 = require("ts-morph");
+// ═══════════════════════════════════════════════════════════════════
+// DETECTION
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * True when `value` is (or contains, in a `>>` chain) a Playwright internal
+ * engine selector. These start with the `internal:` engine prefix.
+ */
+function isInternalEngineSelector(value) {
+    if (!value)
+        return false;
+    return value
+        .split(">>")
+        .some((seg) => seg.trim().toLowerCase().startsWith("internal:"));
+}
+/**
+ * Parse a SINGLE internal selector segment into a method descriptor, or null
+ * when it is not a recognised internal form (so callers REFUSE rather than
+ * guess). Mirrors the engine→public mapping used by ASTSourceUpdater.
+ */
+function parseInternalSelector(selector) {
+    // Match against the raw (trimmed) selector. The case-insensitivity `i` flag
+    // is significant per-pattern (trailing for text/label, inside `[…]` for
+    // role), so it must NOT be stripped globally up front.
+    const s = selector.trim();
+    // internal:role=button[name="X"i][level=2]
+    const roleMatch = s.match(/^internal:role=([a-zA-Z]+)(\[.*\])?$/);
+    if (roleMatch) {
+        const desc = {
+            method: "getByRole",
+            primaryArg: roleMatch[1],
+        };
+        const attrs = roleMatch[2] ?? "";
+        const nameMatch = attrs.match(/name="([^"]*)"(i)?/);
+        const options = {};
+        if (nameMatch) {
+            options.name = nameMatch[1];
+            if (!nameMatch[2])
+                options.exact = true; // no `i` flag → exact match
+        }
+        const levelMatch = attrs.match(/level=(\d+)/);
+        if (levelMatch)
+            options.level = Number(levelMatch[1]);
+        if (Object.keys(options).length)
+            desc.options = options;
+        return desc;
+    }
+    // internal:label="X"i  |  internal:label=X
+    const labelQuoted = s.match(/^internal:label="([^"]*)"(i)?$/);
+    if (labelQuoted) {
+        return labelQuoted[2]
+            ? { method: "getByLabel", primaryArg: labelQuoted[1] }
+            : { method: "getByLabel", primaryArg: labelQuoted[1], options: { exact: true } };
+    }
+    const labelBare = s.match(/^internal:label=([^[]+)$/);
+    if (labelBare) {
+        return { method: "getByLabel", primaryArg: labelBare[1].trim() };
+    }
+    // internal:text="X"i
+    const textMatch = s.match(/^internal:text="([^"]*)"(i)?$/);
+    if (textMatch) {
+        return textMatch[2]
+            ? { method: "getByText", primaryArg: textMatch[1] }
+            : { method: "getByText", primaryArg: textMatch[1], options: { exact: true } };
+    }
+    // internal:attr=[placeholder="X"] / [alt="X"] / [title="X"]
+    const placeholder = s.match(/^internal:attr=\[placeholder="([^"]*)"\]$/);
+    if (placeholder)
+        return { method: "getByPlaceholder", primaryArg: placeholder[1] };
+    const alt = s.match(/^internal:attr=\[alt="([^"]*)"\]$/);
+    if (alt)
+        return { method: "getByAltText", primaryArg: alt[1] };
+    const title = s.match(/^internal:attr=\[title="([^"]*)"\]$/);
+    if (title)
+        return { method: "getByTitle", primaryArg: title[1] };
+    // internal:testid=X  |  internal:attr=[data-testid="X"]
+    const testId = s.match(/^internal:testid=(.+)$/) ||
+        s.match(/^internal:attr=\[data-testid="([^"]*)"\]$/);
+    if (testId)
+        return { method: "getByTestId", primaryArg: testId[1].trim() };
+    return null; // unrecognised internal form → caller must refuse
+}
+// ═══════════════════════════════════════════════════════════════════
+// BUILD  (method descriptor → idiomatic call text)
+// ═══════════════════════════════════════════════════════════════════
+function q(s) {
+    // Prefer double quotes, escaping any embedded ones.
+    return `"${s.replace(/"/g, '\\"')}"`;
+}
+function buildMethodCall(receiver, desc) {
+    switch (desc.method) {
+        case "getByRole": {
+            const opts = [];
+            if (desc.options?.name !== undefined)
+                opts.push(`name: ${q(String(desc.options.name))}`);
+            if (desc.options?.exact === true)
+                opts.push(`exact: true`);
+            if (desc.options?.level !== undefined)
+                opts.push(`level: ${desc.options.level}`);
+            const optStr = opts.length ? `, { ${opts.join(", ")} }` : "";
+            return `${receiver}.getByRole(${q(desc.primaryArg)}${optStr})`;
+        }
+        case "getByText":
+        case "getByLabel": {
+            const exact = desc.options?.exact === true ? `, { exact: true }` : "";
+            return `${receiver}.${desc.method}(${q(desc.primaryArg)}${exact})`;
+        }
+        case "getByPlaceholder":
+        case "getByAltText":
+        case "getByTitle":
+        case "getByTestId":
+            return `${receiver}.${desc.method}(${q(desc.primaryArg)})`;
+        default:
+            return `${receiver}.locator(${q(desc.primaryArg)})`;
+    }
+}
+// ═══════════════════════════════════════════════════════════════════
+// TRANSLATE  (full internal selector string → method expression)
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * Translate an internal selector string into an idiomatic Playwright method
+ * expression rooted at `receiver`. Handles `>>` chains by chaining each
+ * segment. Returns null when ANY segment is an unrecognised internal form
+ * (frame `internal:control=…` plumbing, unknown engines) — the caller must
+ * then refuse rather than emit something fragile.
+ */
+function internalToMethodExpression(selector, receiver = "page") {
+    const segments = selector
+        .split(">>")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    if (segments.length === 0)
+        return null;
+    let expr = receiver;
+    for (const seg of segments) {
+        if (seg.toLowerCase().startsWith("internal:")) {
+            const desc = parseInternalSelector(seg);
+            if (!desc)
+                return null; // unconvertible internal form
+            expr = buildMethodCall(expr, desc);
+        }
+        else {
+            // Plain CSS / text segment — stays a public .locator() string.
+            expr = `${expr}.locator(${q(seg)})`;
+        }
+    }
+    return expr;
+}
+// ═══════════════════════════════════════════════════════════════════
+// TRANSLATE  (internal selector → valid PUBLIC .locator() string)
+// ═══════════════════════════════════════════════════════════════════
+function escAttr(s) {
+    return s.replace(/"/g, '\\"');
+}
+/**
+ * Convert a single internal segment to a valid PUBLIC `.locator()` selector
+ * string (the documented selector engines: `role=`, `text=`, css attribute).
+ * Returns null for forms that have NO public string engine (label is an
+ * associative relationship, not an attribute — only `getByLabel(...)` works).
+ */
+function segmentToPublicSelector(seg) {
+    const desc = parseInternalSelector(seg);
+    if (!desc)
+        return null;
+    switch (desc.method) {
+        case "getByRole": {
+            const attrs = [];
+            if (desc.options?.name !== undefined)
+                attrs.push(`name="${escAttr(String(desc.options.name))}"`);
+            if (desc.options?.level !== undefined)
+                attrs.push(`level=${desc.options.level}`);
+            const attrStr = attrs.length ? `[${attrs.join("][")}]` : "";
+            return `role=${desc.primaryArg}${attrStr}`;
+        }
+        case "getByText":
+            // Quoted text engine = exact-ish; unquoted = substring (i-flag default).
+            return desc.options?.exact
+                ? `text="${escAttr(desc.primaryArg)}"`
+                : `text=${desc.primaryArg}`;
+        case "getByPlaceholder":
+            return `[placeholder="${escAttr(desc.primaryArg)}"]`;
+        case "getByAltText":
+            return `[alt="${escAttr(desc.primaryArg)}"]`;
+        case "getByTitle":
+            return `[title="${escAttr(desc.primaryArg)}"]`;
+        case "getByTestId":
+            return `[data-testid="${escAttr(desc.primaryArg)}"]`;
+        case "getByLabel":
+        default:
+            return null; // no public string-engine equivalent
+    }
+}
+/**
+ * Convert an internal engine selector into a VALID PUBLIC `.locator()` string,
+ * preserving `>>` chaining. Returns null when ANY internal segment has no
+ * public string engine (so the caller must method-shift or refuse instead of
+ * stuffing an unusable string into a constant).
+ *
+ * Example: `internal:role=button[name="Update System"i]`
+ *        → `role=button[name="Update System"]`
+ */
+function internalToPublicSelectorString(selector) {
+    const segments = selector
+        .split(">>")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    if (segments.length === 0)
+        return null;
+    const out = [];
+    for (const seg of segments) {
+        if (seg.toLowerCase().startsWith("internal:")) {
+            const pub = segmentToPublicSelector(seg);
+            if (!pub)
+                return null;
+            out.push(pub);
+        }
+        else {
+            out.push(seg); // already a public css/text segment
+        }
+    }
+    return out.join(" >> ");
+}
+let probeCounter = 0;
+/**
+ * Rewrite any `recv.locator("internal:…")` / `recv.frameLocator("internal:…")`
+ * inside `expr` to its idiomatic method form. Returns `safe:false` when an
+ * internal selector remains that cannot be translated, so the caller refuses
+ * to write it.
+ */
+function sanitizeLocatorExpression(expr) {
+    // Fast path: nothing internal anywhere.
+    if (!expr.includes("internal:")) {
+        return { text: expr, sanitized: false, safe: true };
+    }
+    const project = new ts_morph_1.Project({
+        useInMemoryFileSystem: true,
+        compilerOptions: { allowJs: true, noEmit: true, skipLibCheck: true, noResolve: true },
+    });
+    let current = expr;
+    let sanitized = false;
+    // Iteratively rewrite the first internal locator call until none remain.
+    // replaceWithText invalidates nodes, so we re-parse each pass.
+    for (let pass = 0; pass < 32; pass++) {
+        let sf;
+        try {
+            sf = project.createSourceFile(`__san${probeCounter++}.ts`, `const __x = ${current};`, {
+                overwrite: true,
+            });
+        }
+        catch {
+            return { text: expr, sanitized, safe: false };
+        }
+        const call = sf
+            .getDescendantsOfKind(ts_morph_1.SyntaxKind.CallExpression)
+            .find((c) => {
+            const callee = c.getExpression();
+            if (!ts_morph_1.Node.isPropertyAccessExpression(callee))
+                return false;
+            const m = callee.getName();
+            if (m !== "locator" && m !== "frameLocator")
+                return false;
+            const arg = c.getArguments()[0];
+            if (!arg)
+                return false;
+            const lit = ts_morph_1.Node.isStringLiteral(arg) || ts_morph_1.Node.isNoSubstitutionTemplateLiteral(arg)
+                ? arg.getLiteralValue()
+                : null;
+            return lit !== null && isInternalEngineSelector(lit);
+        });
+        if (!call)
+            break; // no more internal locator calls
+        const callee = call.getExpression();
+        const receiver = callee.getExpression().getText();
+        const arg = call.getArguments()[0];
+        const internalSel = arg.getLiteralValue();
+        const methodExpr = internalToMethodExpression(internalSel, receiver);
+        if (!methodExpr) {
+            // Unconvertible — leave as-is and report unsafe.
+            return { text: current, sanitized, safe: false };
+        }
+        call.replaceWithText(methodExpr);
+        current = sf.getVariableDeclaration("__x").getInitializer().getText();
+        sanitized = true;
+    }
+    // Final integrity check: nothing internal must survive.
+    const safe = !isInternalEngineSelector(current) && !current.includes("internal:");
+    return { text: current, sanitized, safe };
+}

package/dist/services/SnapshotService.js

@@ -39,7 +39,7 @@ const path = __importStar(require("path"));
 class SnapshotService {
     baseDir;
     constructor() {
-        this.baseDir = path.join(process.cwd(), "fixwright-snapshots");
+        this.baseDir = path.join(process.cwd(), "sela-snapshots");
         if (!fs.existsSync(this.baseDir)) {
             fs.mkdirSync(this.baseDir, { recursive: true });
         }

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

@@ -1 +1 @@
-{"version":3,"file":"SourceUpdater.d.ts","sourceRoot":"","sources":["../../src/services/SourceUpdater.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AA4BtD,UAAU,YAAY;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iFAAiF;IACjF,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,wEAAwE;IACxE,cAAc,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAChD,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,UAAU,aAAa;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAqZD,qBAAa,aAAa;IAMxB,MAAM,CAAC,MAAM,CACX,MAAM,EAAE,aAAa,EACrB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,MAAM,EACnB,WAAW,CAAC,EAAE,MAAM,EACpB,mBAAmB,CAAC,EAAE,MAAM,EAC5B,UAAU,CAAC,EAAE,eAAe,EAAE,EAC9B,aAAa,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EACpD,kBAAkB,CAAC,EAAE,iBAAiB,EAAE,EACxC,iBAAiB,CAAC,EAAE,iBAAiB,EAAE,EACvC,cAAc,CAAC,EAAE,SAAS,GAAG,aAAa,GAAG,QAAQ,EACrD,UAAU,CAAC,EAAE,OAAO,GACnB,YAAY;IAoDf,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAwC/B,OAAO,CAAC,MAAM,CAAC,WAAW;IAkT1B,OAAO,CAAC,MAAM,CAAC,2BAA2B;IA8E1C,OAAO,CAAC,MAAM,CAAC,wBAAwB;IA8EvC,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAoErC,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAsBjC,OAAO,CAAC,MAAM,CAAC,qBAAqB;IA6DpC,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAuCpC,OAAO,CAAC,MAAM,CAAC,wBAAwB;IA6CvC,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAqCrC,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAqGrC,OAAO,CAAC,MAAM,CAAC,kBAAkB;IA0BjC,OAAO,CAAC,MAAM,CAAC,uBAAuB;IAatC,MAAM,CAAC,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAgBlD,MAAM,CAAC,cAAc,CACnB,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,YAAY;IA0Cf,0FAA0F;IAC1F,MAAM,CAAC,eAAe,IAAI,IAAI;CAG/B"}
+{"version":3,"file":"SourceUpdater.d.ts","sourceRoot":"","sources":["../../src/services/SourceUpdater.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AA6BtD,UAAU,YAAY;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iFAAiF;IACjF,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,wEAAwE;IACxE,cAAc,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAChD,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,UAAU,aAAa;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAqZD,qBAAa,aAAa;IAMxB,MAAM,CAAC,MAAM,CACX,MAAM,EAAE,aAAa,EACrB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,MAAM,EACnB,WAAW,CAAC,EAAE,MAAM,EACpB,mBAAmB,CAAC,EAAE,MAAM,EAC5B,UAAU,CAAC,EAAE,eAAe,EAAE,EAC9B,aAAa,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EACpD,kBAAkB,CAAC,EAAE,iBAAiB,EAAE,EACxC,iBAAiB,CAAC,EAAE,iBAAiB,EAAE,EACvC,cAAc,CAAC,EAAE,SAAS,GAAG,aAAa,GAAG,QAAQ,EACrD,UAAU,CAAC,EAAE,OAAO,GACnB,YAAY;IAoDf,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAwC/B,OAAO,CAAC,MAAM,CAAC,WAAW;IAsU1B,OAAO,CAAC,MAAM,CAAC,2BAA2B;IA8E1C,OAAO,CAAC,MAAM,CAAC,wBAAwB;IA8EvC,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAoErC,OAAO,CAAC,MAAM,CAAC,kBAAkB;IAsBjC,OAAO,CAAC,MAAM,CAAC,qBAAqB;IA6DpC,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAuCpC,OAAO,CAAC,MAAM,CAAC,wBAAwB;IA6CvC,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAqCrC,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAqGrC,OAAO,CAAC,MAAM,CAAC,kBAAkB;IA0BjC,OAAO,CAAC,MAAM,CAAC,uBAAuB;IAatC,MAAM,CAAC,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAgBlD,MAAM,CAAC,cAAc,CACnB,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,YAAY;IA0Cf,0FAA0F;IAC1F,MAAM,CAAC,eAAe,IAAI,IAAI;CAG/B"}

package/dist/services/SourceUpdater.js

@@ -41,6 +41,7 @@ const ASTSourceUpdater_1 = require("./ASTSourceUpdater");
 const DryRunGuard_1 = require("../config/DryRunGuard");
 const WorkspaceSnapshotService_1 = require("./WorkspaceSnapshotService");
 const SelaError_1 = require("../errors/SelaError");
+const SelectorSanitizer_1 = require("./SelectorSanitizer");
 // Centralised write gate - every disk-mutating `fs.writeFileSync` call in
 // this module routes through `persistFile` so the SELA_DRY_RUN bypass is
 // enforced in one place, and the Clean-Room WorkspaceSnapshotService
@@ -475,6 +476,22 @@ class SourceUpdater {
             }
             console.warn(`[SourceUpdater] ⚠️ AST engine error: ${astError.message}. Falling back to Regex`);
         }
+        // ── ABSOLUTE GUARD: internal engine selector ───────────────────
+        // The AST engine declined to mutate (could not method-shift). The regex
+        // fallback only does RAW string substitution of `oldSelector → newSelector`,
+        // which would stamp the private `internal:role=…` engine string into the
+        // developer's source (the bug this guard kills). A `.locator()` string
+        // cannot express a semantic locator, so there is no safe regex outcome:
+        // refuse, leave source untouched. The in-memory proxy swap already keeps
+        // this run green; the correct method-shift is the new composeHeal pipeline.
+        if ((0, SelectorSanitizer_1.isInternalEngineSelector)(effectiveNewSelector)) {
+            console.warn(`[SourceUpdater] 🛑 Regex blocked - internal engine selector cannot be ` +
+                `string-substituted into source. Method-shift required. Source unchanged.`);
+            return {
+                success: false,
+                reason: "INTERNAL_SELECTOR_GUARD: refusing regex string-substitution of an internal engine selector (method-shift required)",
+            };
+        }
         // ── 2. Regex Fallback ──────────────────────────────────────────
         console.log(`[SourceUpdater] 🔄 Using Regex fallback strategies...`);
         const raw = fs.readFileSync(filePath, "utf8");

package/dist/services/TraceBackEngine.d.ts

@@ -0,0 +1,67 @@
+import { Node, SourceFile, CallExpression } from "ts-morph";
+import { AnchorKey } from "./AnchorResolver";
+export type MethodCategory = "selector" | "frame" | "modifier" | "action" | "unknown";
+export declare function categorizeMethod(name: string): MethodCategory;
+export type TraceAbortCode = "PARAMETER" | "FACTORY" | "DYNAMIC_SELECTOR" | "DESTRUCTURED" | "REASSIGNED" | "CROSS_FILE" | "DEFINITION_NOT_FOUND" | "MAX_DEPTH" | "UNSUPPORTED";
+export type TraceSeverity = "soft" | "hard";
+export interface ChainMethod {
+    name: string;
+    category: MethodCategory;
+}
+export type DeclKind = "VariableDeclaration" | "PropertyDeclaration" | "PropertyAssignment" | "InlineCallSite";
+export interface TraceTarget {
+    declKind: DeclKind;
+    /**
+     * The node to mutate at source: the locator-chain expression (a
+     * VariableDeclaration's initializer, a POM property's value, or the inline
+     * selector chain with trailing actions stripped).
+     */
+    targetNode: Node;
+    /** The owning declaration node; null for an inline call-site. */
+    declaration: Node | null;
+    /** Variable / property name owning the target, or null. */
+    symbolName: string | null;
+    /** Stable chain root ("page", "context", …). */
+    rootReceiver: string;
+    /** Stage-1 identity anchor for the target node. */
+    anchor: AnchorKey;
+}
+export type TraceOutcome = {
+    status: "target";
+    target: TraceTarget;
+    /** Methods seen on the failing call-site chain, root→leaf. */
+    callSiteChain: ChainMethod[];
+    /**
+     * For chained cascades (§1.1) — every upstream VariableDeclaration the
+     * target depends on, root-most first, target last. Single-element when
+     * there is no cascade. Runtime evidence later picks the broken link.
+     */
+    dependencyChain: TraceTarget[];
+} | {
+    status: "abort";
+    severity: TraceSeverity;
+    code: TraceAbortCode;
+    reason: string;
+    node?: Node;
+};
+export declare class TraceBackEngine {
+    /** Phase 0 convenience: resolve (1-based line, 0-based col) → node → trace. */
+    static traceFromPosition(sourceFile: SourceFile, line: number, column: number): TraceOutcome;
+    /** Phases 1–5. */
+    static traceFromNode(start: Node): TraceOutcome;
+}
+export declare function climbToTopCall(start: Node): CallExpression | null;
+export declare function getLeftmostReceiver(topCall: CallExpression): {
+    leftmost: Node;
+    chain: ChainMethod[];
+};
+/**
+ * Lexical-scope resolution of `name` as seen from `useOffset`. Walks
+ * enclosing scopes outward: parameters of enclosing functions, then
+ * variable/function declarations introduced in each enclosing block /
+ * source file. Pure compiler-API traversal — no language service.
+ */
+export declare function resolveValueDeclaration(fromNode: Node, name: string, useOffset: number): Node | null;
+/** Strip trailing action/query calls, returning the locator-chain node. */
+export declare function stripTrailingActions(topCall: CallExpression): Node;
+//# sourceMappingURL=TraceBackEngine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TraceBackEngine.d.ts","sourceRoot":"","sources":["../../src/services/TraceBackEngine.ts"],"names":[],"mappings":"AAwBA,OAAO,EACL,IAAI,EACJ,UAAU,EACV,cAAc,EAIf,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,SAAS,EAAsC,MAAM,kBAAkB,CAAC;AAsFjF,MAAM,MAAM,cAAc,GACtB,UAAU,GACV,OAAO,GACP,UAAU,GACV,QAAQ,GACR,SAAS,CAAC;AAEd,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAM7D;AAMD,MAAM,MAAM,cAAc,GACtB,WAAW,GACX,SAAS,GACT,kBAAkB,GAClB,cAAc,GACd,YAAY,GACZ,YAAY,GACZ,sBAAsB,GACtB,WAAW,GACX,aAAa,CAAC;AAElB,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,CAAC;AAE5C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED,MAAM,MAAM,QAAQ,GAChB,qBAAqB,GACrB,qBAAqB,GACrB,oBAAoB,GACpB,gBAAgB,CAAC;AAErB,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,QAAQ,CAAC;IACnB;;;;OAIG;IACH,UAAU,EAAE,IAAI,CAAC;IACjB,iEAAiE;IACjE,WAAW,EAAE,IAAI,GAAG,IAAI,CAAC;IACzB,2DAA2D;IAC3D,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,gDAAgD;IAChD,YAAY,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,MAAM,EAAE,SAAS,CAAC;CACnB;AAED,MAAM,MAAM,YAAY,GACpB;IACE,MAAM,EAAE,QAAQ,CAAC;IACjB,MAAM,EAAE,WAAW,CAAC;IACpB,8DAA8D;IAC9D,aAAa,EAAE,WAAW,EAAE,CAAC;IAC7B;;;;OAIG;IACH,eAAe,EAAE,WAAW,EAAE,CAAC;CAChC,GACD;IACE,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,aAAa,CAAC;IACxB,IAAI,EAAE,cAAc,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,IAAI,CAAC;CACb,CAAC;AAQN,qBAAa,eAAe;IAC1B,+EAA+E;IAC/E,MAAM,CAAC,iBAAiB,CACtB,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,YAAY;IAqBf,kBAAkB;IAClB,MAAM,CAAC,aAAa,CAAC,KAAK,EAAE,IAAI,GAAG,YAAY;CAoChD;AAMD,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,GAAG,cAAc,GAAG,IAAI,CA6BjE;AAMD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,cAAc,GAAG;IAC5D,QAAQ,EAAE,IAAI,CAAC;IACf,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB,CA6BA;AAuWD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,IAAI,EACd,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAChB,IAAI,GAAG,IAAI,CAmBb;AAmHD,2EAA2E;AAC3E,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAelE"}