sela-core 0.1.0-alpha.1

package/dist/services/TemplateDiffService.d.ts

@@ -0,0 +1,25 @@
+import { TemplateExpression } from "ts-morph";
+export type DiffPatchResult = {
+    ok: true;
+    /** Full patched template string, backtick-wrapped, ready for replaceWithText(). */
+    patchedTemplate: string;
+    /** Zero-based indices of static segments that changed. */
+    changedSegmentIndices: number[];
+} | {
+    ok: false;
+    reason: string;
+    /**
+     * Populated when alignWithNew fails due to structural simplification:
+     * what each span expression needs to evaluate to satisfy resolvedNew.
+     * Use for span-tracing fallback (resolve each span's source independently).
+     */
+    newSpanValues?: string[];
+};
+export declare class TemplateDiffService {
+    static diffAndPatch(templateText: string, resolvedOld: string, resolvedNew: string): DiffPatchResult;
+    static computeNodePatch(templateNode: TemplateExpression, resolvedOld: string, resolvedNew: string): DiffPatchResult;
+    static extractNodeSpanValues(templateNode: TemplateExpression, resolved: string): string[] | null;
+}
+/** Escape characters that would break a template literal. */
+export declare function escapeForTemplate(text: string): string;
+//# sourceMappingURL=TemplateDiffService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TemplateDiffService.d.ts","sourceRoot":"","sources":["../../src/services/TemplateDiffService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,kBAAkB,EAAc,MAAM,UAAU,CAAC;AAMhE,MAAM,MAAM,eAAe,GACvB;IACE,EAAE,EAAE,IAAI,CAAC;IACT,mFAAmF;IACnF,eAAe,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,qBAAqB,EAAE,MAAM,EAAE,CAAC;CACjC,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B,CAAC;AA6BN,qBAAa,mBAAmB;IAW9B,MAAM,CAAC,YAAY,CACjB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,eAAe;IAiHlB,MAAM,CAAC,gBAAgB,CACrB,YAAY,EAAE,kBAAkB,EAChC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,eAAe;IAoFlB,MAAM,CAAC,qBAAqB,CAC1B,YAAY,EAAE,kBAAkB,EAChC,QAAQ,EAAE,MAAM,GACf,MAAM,EAAE,GAAG,IAAI;CASnB;AAgJD,6DAA6D;AAC7D,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKtD"}

package/dist/services/TemplateDiffService.js

@@ -0,0 +1,334 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TemplateDiffService = void 0;
+exports.escapeForTemplate = escapeForTemplate;
+// ═══════════════════════════════════════════════════════════════════
+// TemplateDiffService
+//
+// T-8: String-based API - diffAndPatch()
+//   Given a template source like `input[data-role="${role}_legacy"]`,
+//   its resolved old string, and an AI-proposed new string, compute
+//   the patched template that preserves ${...} spans while updating
+//   only the changed static segments.
+//
+// T-8.1: Node-based API - computeNodePatch()
+//   Wraps diffAndPatch() using the TemplateExpression AST node as the
+//   source of truth (avoids text-parsing ambiguity). Returns the full
+//   patched template text for use with templateNode.replaceWithText().
+// ═══════════════════════════════════════════════════════════════════
+class TemplateDiffService {
+    // ─────────────────────────────────────────────────────────────────
+    // T-8: String-based API
+    //
+    // templateText: the template source (backticks optional), e.g.
+    //   `input[data-role="${role}_legacy"]`  or
+    //    input[data-role="${role}_legacy"]
+    // resolvedOld: what the template evaluates to at the failing call site
+    // resolvedNew: the AI-proposed replacement string (flat, no ${...})
+    // ─────────────────────────────────────────────────────────────────
+    static diffAndPatch(templateText, resolvedOld, resolvedNew) {
+        const segments = parseTemplateSource(templateText);
+        const staticSegs = segments
+            .filter((s) => s.type === "static")
+            .map((s) => s.text);
+        const exprSegs = segments
+            .filter((s) => s.type === "expr")
+            .map((s) => s.text);
+        // No spans - the "template" is just a plain string.
+        if (exprSegs.length === 0) {
+            if (resolvedOld !== resolvedNew) {
+                return {
+                    ok: true,
+                    patchedTemplate: "`" + escapeForTemplate(resolvedNew) + "`",
+                    changedSegmentIndices: [0],
+                };
+            }
+            return {
+                ok: false,
+                reason: "resolvedOld === resolvedNew - no change needed",
+            };
+        }
+        // Extract span values from resolvedOld using static segments as anchors.
+        const spanValues = extractSpanValues(staticSegs, resolvedOld);
+        if (!spanValues) {
+            return {
+                ok: false,
+                reason: "template static segments don't align with resolvedOld - possible desync. " +
+                    `template="${templateText}", resolvedOld="${resolvedOld}"`,
+            };
+        }
+        // Verify reconstruction - extractSpanValues already guarantees this
+        // implicitly, but an explicit check catches any edge-case bugs early.
+        {
+            let check = "";
+            for (let i = 0; i < staticSegs.length; i++) {
+                check += staticSegs[i];
+                if (i < spanValues.length)
+                    check += spanValues[i];
+            }
+            if (check !== resolvedOld) {
+                return {
+                    ok: false,
+                    reason: `reconstruction mismatch: expected "${resolvedOld}", got "${check}"`,
+                };
+            }
+        }
+        // Align resolvedNew against the extracted span values.
+        const newStaticSegs = alignWithNew(spanValues, resolvedNew);
+        if (!newStaticSegs) {
+            return {
+                ok: false,
+                reason: `dynamic span value(s) [${spanValues.map((v) => `"${v}"`).join(", ")}] ` +
+                    `not found in resolvedNew="${resolvedNew}" - structural change, manual review required`,
+            };
+        }
+        if (newStaticSegs.length !== staticSegs.length) {
+            return {
+                ok: false,
+                reason: "static segment count mismatch after alignment - structural change",
+            };
+        }
+        // Diff: find which static segments changed.
+        const changedIndices = [];
+        for (let i = 0; i < staticSegs.length; i++) {
+            if (staticSegs[i] !== newStaticSegs[i])
+                changedIndices.push(i);
+        }
+        if (changedIndices.length === 0) {
+            return {
+                ok: false,
+                reason: "no static segment changed - the difference is in a dynamic span. " +
+                    "Update the argument passed to the function instead.",
+            };
+        }
+        if (changedIndices.length > 1) {
+            return {
+                ok: false,
+                reason: `${changedIndices.length} static segments changed simultaneously - ` +
+                    "ambiguous, manual review required",
+            };
+        }
+        // Build the patched template.
+        const patchedStatics = [...staticSegs];
+        patchedStatics[changedIndices[0]] = newStaticSegs[changedIndices[0]];
+        return {
+            ok: true,
+            patchedTemplate: buildTemplate(segments, patchedStatics),
+            changedSegmentIndices: changedIndices,
+        };
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // T-8.1: Node-based API
+    //
+    // Uses the TemplateExpression AST node as the authoritative source
+    // of static/expr segments (avoids text-parsing edge cases).
+    // Returns `patchedText` - pass directly to templateNode.replaceWithText().
+    // ─────────────────────────────────────────────────────────────────
+    static computeNodePatch(templateNode, resolvedOld, resolvedNew) {
+        // Extract static segments and expr texts directly from the AST.
+        const head = templateNode.getHead();
+        const spans = templateNode.getTemplateSpans();
+        const staticSegs = [head.getLiteralText()];
+        const exprTexts = [];
+        for (const span of spans) {
+            exprTexts.push(span.getExpression().getText());
+            staticSegs.push(span.getLiteral().getLiteralText());
+        }
+        // Rebuild equivalent segments array for buildTemplate().
+        const segments = [];
+        for (let i = 0; i < staticSegs.length; i++) {
+            segments.push({ type: "static", text: staticSegs[i] });
+            if (i < exprTexts.length) {
+                segments.push({ type: "expr", text: exprTexts[i] });
+            }
+        }
+        // No spans case.
+        if (exprTexts.length === 0) {
+            return {
+                ok: true,
+                patchedTemplate: "`" + escapeForTemplate(resolvedNew) + "`",
+                changedSegmentIndices: [0],
+            };
+        }
+        const spanValues = extractSpanValues(staticSegs, resolvedOld);
+        if (!spanValues) {
+            return {
+                ok: false,
+                reason: `template AST doesn't reconstruct to "${resolvedOld}"`,
+            };
+        }
+        const newStaticSegs = alignWithNew(spanValues, resolvedNew);
+        if (!newStaticSegs) {
+            const newSpanFromNew = extractSpanValues(staticSegs, resolvedNew);
+            return {
+                ok: false,
+                reason: `span values [${spanValues.map((v) => `"${v}"`).join(", ")}] ` +
+                    `not found in new selector "${resolvedNew}"`,
+                ...(newSpanFromNew ? { newSpanValues: newSpanFromNew } : {}),
+            };
+        }
+        const changedIndices = [];
+        for (let i = 0; i < staticSegs.length; i++) {
+            if (staticSegs[i] !== newStaticSegs[i])
+                changedIndices.push(i);
+        }
+        if (changedIndices.length === 0) {
+            return {
+                ok: false,
+                reason: "difference is in dynamic span - update call-site argument",
+            };
+        }
+        if (changedIndices.length > 1) {
+            return {
+                ok: false,
+                reason: `${changedIndices.length} static segments changed - ambiguous`,
+            };
+        }
+        const patchedStatics = [...staticSegs];
+        patchedStatics[changedIndices[0]] = newStaticSegs[changedIndices[0]];
+        return {
+            ok: true,
+            patchedTemplate: buildTemplate(segments, patchedStatics),
+            changedSegmentIndices: changedIndices,
+        };
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // Extract span values from a TemplateExpression node and a resolved string.
+    // Public so callers can derive old/new span values for span tracing.
+    // ─────────────────────────────────────────────────────────────────
+    static extractNodeSpanValues(templateNode, resolved) {
+        const head = templateNode.getHead();
+        const spans = templateNode.getTemplateSpans();
+        const staticSegs = [head.getLiteralText()];
+        for (const span of spans) {
+            staticSegs.push(span.getLiteral().getLiteralText());
+        }
+        return extractSpanValues(staticSegs, resolved);
+    }
+}
+exports.TemplateDiffService = TemplateDiffService;
+// ═══════════════════════════════════════════════════════════════════
+// Private helpers
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * Parse a template literal source string into alternating static/expr segments.
+ * Strips surrounding backticks if present.
+ *
+ * `` `head${role}_tail` `` → [static:"head", expr:"role", static:"_tail"]
+ */
+function parseTemplateSource(text) {
+    let src = text.trim();
+    if (src.startsWith("`") && src.endsWith("`")) {
+        src = src.slice(1, -1);
+    }
+    const segments = [];
+    const exprPattern = /\$\{([^}]+)\}/g;
+    let lastIndex = 0;
+    let match;
+    while ((match = exprPattern.exec(src)) !== null) {
+        // Static segment before this expression.
+        segments.push({ type: "static", text: src.slice(lastIndex, match.index) });
+        segments.push({ type: "expr", text: match[1].trim() });
+        lastIndex = match.index + match[0].length;
+    }
+    // Trailing static segment (may be empty).
+    segments.push({ type: "static", text: src.slice(lastIndex) });
+    return segments;
+}
+/**
+ * Given the static segments of a template and a resolved string,
+ * extract the dynamic span values by matching statics as anchors.
+ *
+ * Algorithm: iterate over all static segments in order. After consuming
+ * each static segment, find the next static as the delimiter for the
+ * span value - then advance pos to the start of that next static so
+ * the following iteration can consume it. This ensures pos is always
+ * consistent at the start of each static segment.
+ *
+ * Returns null if alignment fails (desync or ambiguous adjacent spans).
+ */
+function extractSpanValues(staticSegments, resolved) {
+    const spanValues = [];
+    let pos = 0;
+    for (let i = 0; i < staticSegments.length; i++) {
+        // Consume static[i].
+        const s = staticSegments[i];
+        if (resolved.slice(pos, pos + s.length) !== s)
+            return null;
+        pos += s.length;
+        // If this is the last static segment, we're done.
+        if (i === staticSegments.length - 1)
+            break;
+        // Find span[i] value: delimited by static[i+1].
+        const nextStatic = staticSegments[i + 1];
+        if (nextStatic === "" && i + 1 === staticSegments.length - 1) {
+            // Empty trailing static: span value extends to end of string.
+            spanValues.push(resolved.slice(pos));
+            pos = resolved.length;
+            break;
+        }
+        if (nextStatic === "") {
+            // Empty non-trailing static: adjacent spans - boundary is ambiguous.
+            return null;
+        }
+        const delimIdx = resolved.indexOf(nextStatic, pos);
+        if (delimIdx === -1)
+            return null;
+        spanValues.push(resolved.slice(pos, delimIdx));
+        // Advance pos to start of nextStatic so the next iteration consumes it.
+        pos = delimIdx;
+    }
+    if (pos !== resolved.length)
+        return null;
+    return spanValues;
+}
+/**
+ * Given known span values (anchors) and a new resolved string,
+ * extract what the static segments should be in the patched template.
+ *
+ * Uses each span value as a positional anchor, in order.
+ * Returns null if any span value is missing from resolvedNew.
+ */
+function alignWithNew(spanValues, resolvedNew) {
+    const newStatics = [];
+    let pos = 0;
+    for (const spanVal of spanValues) {
+        if (spanVal.length === 0) {
+            // Can't anchor on empty span value.
+            return null;
+        }
+        const spanPos = resolvedNew.indexOf(spanVal, pos);
+        if (spanPos === -1)
+            return null;
+        newStatics.push(resolvedNew.slice(pos, spanPos));
+        pos = spanPos + spanVal.length;
+    }
+    // Last static segment: everything remaining in resolvedNew.
+    newStatics.push(resolvedNew.slice(pos));
+    return newStatics;
+}
+/**
+ * Reconstruct a full template literal string (with backticks) from
+ * alternating segments and new static values.
+ */
+function buildTemplate(segments, newStaticValues) {
+    let result = "`";
+    let staticIdx = 0;
+    for (const seg of segments) {
+        if (seg.type === "static") {
+            result += escapeForTemplate(newStaticValues[staticIdx++]);
+        }
+        else {
+            result += "${" + seg.text + "}";
+        }
+    }
+    result += "`";
+    return result;
+}
+/** Escape characters that would break a template literal. */
+function escapeForTemplate(text) {
+    return text
+        .replace(/\\/g, "\\\\")
+        .replace(/`/g, "\\`")
+        .replace(/\$\{/g, "\\${");
+}

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"}