sela-core 1.0.8 → 1.0.9

package/dist/services/AnchorResolver.d.ts

@@ -0,0 +1,157 @@
+import { Node, SourceFile } from "ts-morph";
+/**
+ * Line-number-free identity of a single AST node, stable across the
+ * read-modify-write lifecycle of a shared source file. See module header.
+ */
+export interface AnchorKey {
+    /** Absolute path of the file the node lives in. */
+    filePath: string;
+    /**
+     * Name of the variable / property / object-property that owns the
+     * target node (e.g. "submitBtn"). Used for content-addressed recovery
+     * when the structural index drifts. Empty string when the node has no
+     * named owner.
+     */
+    symbolName: string;
+    /**
+     * Kind-indexed path from the SourceFile root to the node, e.g.
+     * "SyntaxList[0]/VariableStatement[2]/.../CallExpression[0]".
+     * Immune to pure line shifts.
+     */
+    structuralPath: string;
+    /** sha256 hex of the target node's `getText()` at flag-time. */
+    nodeTextSha: string;
+    /** ts-morph SyntaxKind NAME of the target node (e.g. "CallExpression"). */
+    kind: string;
+    /**
+     * Name of the enclosing test/hook block — `test("...")` title,
+     * or hook name like "beforeEach" — used to disambiguate identical
+     * declarations across multiple test blocks (§1.3 fork detection).
+     * Undefined when the node is module-scoped.
+     */
+    enclosingFnName?: string;
+}
+export type MutationStrategy = "SOURCE_MUTATE" | "FORK_AT_TEST" | "CALLSITE_PATCH" | "WARN_NONBLOCKING" | "PROMPT_INTERACTIVE";
+/** What broke at runtime and what the healed selector should become. */
+export interface RuntimeEvidence {
+    /** The selector chain that failed at runtime. */
+    failedSelector: string;
+    /** The healed selector the engine proposes to write. */
+    proposedSelector: string;
+    /**
+     * For chained cascades (§1.1): the narrowest selector segment that
+     * actually resolved to 0 / ambiguous elements. Undefined when unknown.
+     */
+    brokenSegment?: string;
+    /** Element count the broken segment resolved to at fail-time, if known. */
+    resolvedCount?: number;
+}
+/**
+ * Worker-emitted record. Workers NEVER write source (§3.1) — they serialise
+ * MutationProposals; the single-writer main loop resolves + applies them.
+ */
+export interface MutationProposal {
+    anchor: AnchorKey;
+    evidence: RuntimeEvidence;
+    /** Strategy the worker-side analysis recommends; main loop may override. */
+    strategyHint: MutationStrategy;
+    /** 0..1 confidence used for routing (§5.3). */
+    confidence: number;
+    /** Emitting worker's pid — provenance + collision diagnostics. */
+    workerPid: number;
+    /**
+     * ISO timestamp of when the proposal was created. Passed in by the caller
+     * (core stays clock-free so it is deterministic / resumable).
+     */
+    createdAtIso: string;
+}
+/** Character offsets into the file text — `[start, end)`. */
+export interface SourceSpan {
+    start: number;
+    end: number;
+}
+/**
+ * Output of the trace-back engine: a concrete, ready-to-apply edit.
+ * `targetSpan` is recomputed from the anchor at apply-time against the
+ * fresh file (see resolveAnchor) — never trusted from flag-time.
+ */
+export interface MutationPlan {
+    targetFile: string;
+    targetSpan: SourceSpan;
+    replacementText: string;
+    strategy: MutationStrategy;
+    confidence: number;
+    anchor: AnchorKey;
+}
+export type ResolveAnchorResult = {
+    status: "resolved";
+    node: Node;
+    via: "structural" | "content";
+} | {
+    status: "stale";
+    node: Node;
+    reason: string;
+} | {
+    status: "ambiguous";
+    matches: number;
+    reason: string;
+} | {
+    status: "not-found";
+    reason: string;
+};
+/** sha256 hex of an arbitrary string. Stable across processes. */
+export declare function sha256(text: string): string;
+/**
+ * Build an AnchorKey for `node`. The inverse of resolveAnchor: feeding the
+ * result back into resolveAnchor against the SAME (or line-shifted) file
+ * must re-locate `node`.
+ */
+export declare function computeAnchor(node: Node): AnchorKey;
+/**
+ * Dedup key for collapsing identical proposals (§3.5). Two proposals that
+ * target the same node identity in the same file share this key regardless
+ * of which worker emitted them.
+ */
+export declare function anchorDedupeKey(a: AnchorKey): string;
+/**
+ * Re-locate the node an AnchorKey points to, in a freshly-parsed
+ * SourceFile. PURE — no writes, never throws.
+ *
+ * Resolution order:
+ *   1. Structural path. If it lands on a node of the recorded kind whose
+ *      text sha matches → resolved("structural"). This is the fast path and
+ *      the ONLY path needed for pure line shifts.
+ *   2. Content-addressed recovery. When the structural index drifted (a new
+ *      sibling was inserted ahead of the target), search the file for nodes
+ *      of the recorded kind whose sha matches, then narrow by symbolName and
+ *      enclosingFnName. Exactly one → resolved("content"); more than one →
+ *      ambiguous.
+ *   3. Stale. The structural path resolved to a node of the right kind but
+ *      the bytes changed (someone edited the selector) and no content match
+ *      exists → the node moved/changed under us; refuse to blind-write.
+ *   4. not-found. Nothing matches.
+ */
+export declare function resolveAnchor(sourceFile: SourceFile, anchor: AnchorKey): ResolveAnchorResult;
+/**
+ * Kind-indexed path from the SourceFile root down to `node`. Each segment is
+ * `KindName[i]` where `i` is the node's index among its parent's children
+ * OF THE SAME KIND. Indexing per-kind (rather than absolute child index)
+ * keeps the path readable and resilient to trivia/token reshuffling.
+ */
+export declare function structuralPathOf(node: Node): string;
+/** Walk a structuralPath from the SourceFile root. Returns null on any miss. */
+export declare function followStructuralPath(sourceFile: SourceFile, structuralPath: string): Node | null;
+/**
+ * Name of the nearest declaration owning `node`:
+ *   const NAME = … | NAME: … (object prop) | NAME = page.locator() (POM prop).
+ * Null when there is no named owner (e.g. a bare expression statement).
+ */
+export declare function enclosingSymbolName(node: Node): string | null;
+/**
+ * Name of the enclosing test/hook block, used to disambiguate identical
+ * declarations across blocks. Returns the string-literal title for
+ * `test("title", …)` / `describe`/`it`, or the hook name for
+ * `beforeEach(…)` / `afterAll(…)`. Undefined when module-scoped.
+ */
+export declare function enclosingFnName(node: Node): string | undefined;
+//# sourceMappingURL=AnchorResolver.d.ts.map

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

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

package/dist/services/AnchorResolver.js

@@ -0,0 +1,289 @@
+"use strict";
+// src/services/AnchorResolver.ts
+//
+// Ticket #2 — Stage 1: Core Types & the Identity Anchor.
+//
+// THE PROBLEM (architecture doc §3.3): Playwright runs each worker in its
+// own OS process. Workers flag mutations into `.sela/pending-prompts*`,
+// drained later by the main process. Between flag-time and apply-time the
+// file can shift: Worker A inserts a line at the top → every line below
+// moves down. Any anchor that stored `{ line, col }` now points at the
+// WRONG code.
+//
+// THE FIX: never persist coordinates. Persist an IDENTITY ANCHOR:
+//   • structuralPath — kind-indexed path from the SourceFile root to the
+//     node. Immune to pure line shifts (adding blank lines / comments above
+//     the target does NOT change a node's structural index).
+//   • nodeTextSha    — sha256 of the target node's text at flag-time. The
+//     integrity check: if the bytes under the anchor changed, we KNOW the
+//     node drifted and refuse to blind-write (status: "stale").
+//   • symbolName / enclosingFnName — content-addressed recovery keys used
+//     when the structural index DID drift (a new sibling statement was
+//     inserted ahead of the target).
+//
+// resolveAnchor() is PURE and SIDE-EFFECT-FREE: given a freshly-parsed
+// SourceFile + an AnchorKey, it re-locates the node or reports precisely
+// why it could not. It never throws on bad input — every failure mode is a
+// typed result variant so the drain loop can branch without try/catch.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sha256 = sha256;
+exports.computeAnchor = computeAnchor;
+exports.anchorDedupeKey = anchorDedupeKey;
+exports.resolveAnchor = resolveAnchor;
+exports.structuralPathOf = structuralPathOf;
+exports.followStructuralPath = followStructuralPath;
+exports.enclosingSymbolName = enclosingSymbolName;
+exports.enclosingFnName = enclosingFnName;
+const crypto_1 = require("crypto");
+const ts_morph_1 = require("ts-morph");
+// ═══════════════════════════════════════════════════════════════════
+// PUBLIC API
+// ═══════════════════════════════════════════════════════════════════
+/** sha256 hex of an arbitrary string. Stable across processes. */
+function sha256(text) {
+    return (0, crypto_1.createHash)("sha256").update(text, "utf8").digest("hex");
+}
+/**
+ * Build an AnchorKey for `node`. The inverse of resolveAnchor: feeding the
+ * result back into resolveAnchor against the SAME (or line-shifted) file
+ * must re-locate `node`.
+ */
+function computeAnchor(node) {
+    const sf = node.getSourceFile();
+    return {
+        filePath: sf.getFilePath(),
+        symbolName: enclosingSymbolName(node) ?? "",
+        structuralPath: structuralPathOf(node),
+        nodeTextSha: sha256(node.getText()),
+        kind: node.getKindName(),
+        enclosingFnName: enclosingFnName(node),
+    };
+}
+/**
+ * Dedup key for collapsing identical proposals (§3.5). Two proposals that
+ * target the same node identity in the same file share this key regardless
+ * of which worker emitted them.
+ */
+function anchorDedupeKey(a) {
+    return `${a.filePath}::${a.structuralPath}::${a.symbolName}::${a.kind}`;
+}
+/**
+ * Re-locate the node an AnchorKey points to, in a freshly-parsed
+ * SourceFile. PURE — no writes, never throws.
+ *
+ * Resolution order:
+ *   1. Structural path. If it lands on a node of the recorded kind whose
+ *      text sha matches → resolved("structural"). This is the fast path and
+ *      the ONLY path needed for pure line shifts.
+ *   2. Content-addressed recovery. When the structural index drifted (a new
+ *      sibling was inserted ahead of the target), search the file for nodes
+ *      of the recorded kind whose sha matches, then narrow by symbolName and
+ *      enclosingFnName. Exactly one → resolved("content"); more than one →
+ *      ambiguous.
+ *   3. Stale. The structural path resolved to a node of the right kind but
+ *      the bytes changed (someone edited the selector) and no content match
+ *      exists → the node moved/changed under us; refuse to blind-write.
+ *   4. not-found. Nothing matches.
+ */
+function resolveAnchor(sourceFile, anchor) {
+    // Guard: the anchor must belong to this file. Comparing normalised paths
+    // avoids "/a/b" vs "/a/./b" false negatives.
+    if (!samePath(sourceFile.getFilePath(), anchor.filePath)) {
+        return {
+            status: "not-found",
+            reason: `anchor file "${anchor.filePath}" != source file "${sourceFile.getFilePath()}"`,
+        };
+    }
+    // ── 1. Structural fast path ──────────────────────────────────────
+    //
+    // Accept ONLY when kind + sha match AND the enclosing context the anchor
+    // recorded still holds. The context check is what stops a drifted path
+    // from landing on an identical-sha TWIN in a different declaration / test
+    // block (the multi-consumer hazard, §1.3): after a same-kind sibling is
+    // inserted ahead, ExpressionStatement[1] may now point at a different
+    // block whose duplicate selector hashes identically. Without this guard
+    // we would confidently mutate the wrong copy.
+    const structuralNode = followStructuralPath(sourceFile, anchor.structuralPath);
+    if (structuralNode &&
+        structuralNode.getKindName() === anchor.kind &&
+        sha256(structuralNode.getText()) === anchor.nodeTextSha &&
+        contextMatches(structuralNode, anchor)) {
+        return { status: "resolved", node: structuralNode, via: "structural" };
+    }
+    // ── 2. Content-addressed recovery ────────────────────────────────
+    let matches = sourceFile
+        .getDescendants()
+        .filter((n) => n.getKindName() === anchor.kind &&
+        sha256(n.getText()) === anchor.nodeTextSha);
+    if (matches.length > 1 && anchor.symbolName) {
+        const bySymbol = matches.filter((n) => enclosingSymbolName(n) === anchor.symbolName);
+        if (bySymbol.length > 0)
+            matches = bySymbol;
+    }
+    if (matches.length > 1 && anchor.enclosingFnName) {
+        const byFn = matches.filter((n) => enclosingFnName(n) === anchor.enclosingFnName);
+        if (byFn.length > 0)
+            matches = byFn;
+    }
+    if (matches.length === 1) {
+        return { status: "resolved", node: matches[0], via: "content" };
+    }
+    if (matches.length > 1) {
+        return {
+            status: "ambiguous",
+            matches: matches.length,
+            reason: `${matches.length} nodes match kind+sha; symbolName/enclosingFnName insufficient to disambiguate`,
+        };
+    }
+    // ── 3. Stale: located structurally but the bytes drifted ─────────
+    if (structuralNode && structuralNode.getKindName() === anchor.kind) {
+        return {
+            status: "stale",
+            node: structuralNode,
+            reason: `node at structural path changed: sha mismatch (expected ${short(anchor.nodeTextSha)})`,
+        };
+    }
+    // ── 4. Gone ──────────────────────────────────────────────────────
+    return {
+        status: "not-found",
+        reason: `no node of kind "${anchor.kind}" with matching sha; structural path ${structuralNode ? "resolved to wrong kind" : "did not resolve"}`,
+    };
+}
+// ═══════════════════════════════════════════════════════════════════
+// STRUCTURAL PATH
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * Kind-indexed path from the SourceFile root down to `node`. Each segment is
+ * `KindName[i]` where `i` is the node's index among its parent's children
+ * OF THE SAME KIND. Indexing per-kind (rather than absolute child index)
+ * keeps the path readable and resilient to trivia/token reshuffling.
+ */
+function structuralPathOf(node) {
+    const segs = [];
+    let cur = node;
+    while (cur && !ts_morph_1.Node.isSourceFile(cur)) {
+        const parent = cur.getParent();
+        if (!parent)
+            break;
+        const kindName = cur.getKindName();
+        // forEachChildAsArray() mirrors the compiler's ts.forEachChild — it
+        // excludes synthetic SyntaxList nodes and punctuation tokens, so it is
+        // the exact inverse of getParent(). Using getChildren() here would be
+        // asymmetric (it injects SyntaxList layers getParent() skips).
+        const sameKind = parent
+            .forEachChildAsArray()
+            .filter((c) => c.getKindName() === kindName);
+        const idx = sameKind.indexOf(cur);
+        segs.push(`${kindName}[${idx < 0 ? 0 : idx}]`);
+        cur = parent;
+    }
+    segs.reverse();
+    return segs.join("/");
+}
+/** Walk a structuralPath from the SourceFile root. Returns null on any miss. */
+function followStructuralPath(sourceFile, structuralPath) {
+    if (!structuralPath)
+        return null;
+    let cur = sourceFile;
+    for (const seg of structuralPath.split("/")) {
+        const m = /^(.+)\[(\d+)\]$/.exec(seg);
+        if (!m)
+            return null;
+        const kindName = m[1];
+        const idx = Number(m[2]);
+        const sameKind = cur
+            .forEachChildAsArray()
+            .filter((c) => c.getKindName() === kindName);
+        if (idx < 0 || idx >= sameKind.length)
+            return null;
+        cur = sameKind[idx];
+    }
+    return cur;
+}
+// ═══════════════════════════════════════════════════════════════════
+// ENCLOSING-CONTEXT HELPERS
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * Name of the nearest declaration owning `node`:
+ *   const NAME = … | NAME: … (object prop) | NAME = page.locator() (POM prop).
+ * Null when there is no named owner (e.g. a bare expression statement).
+ */
+function enclosingSymbolName(node) {
+    let cur = node;
+    while (cur && !ts_morph_1.Node.isSourceFile(cur)) {
+        if (ts_morph_1.Node.isVariableDeclaration(cur))
+            return cur.getName();
+        if (ts_morph_1.Node.isPropertyAssignment(cur))
+            return cur.getName();
+        if (ts_morph_1.Node.isPropertyDeclaration(cur))
+            return cur.getName();
+        if (ts_morph_1.Node.isShorthandPropertyAssignment(cur))
+            return cur.getName();
+        cur = cur.getParent();
+    }
+    return null;
+}
+/**
+ * Name of the enclosing test/hook block, used to disambiguate identical
+ * declarations across blocks. Returns the string-literal title for
+ * `test("title", …)` / `describe`/`it`, or the hook name for
+ * `beforeEach(…)` / `afterAll(…)`. Undefined when module-scoped.
+ */
+function enclosingFnName(node) {
+    const HOOK_OR_TEST = /^(test|it|describe|beforeEach|beforeAll|afterEach|afterAll)(\.\w+)?$/;
+    let cur = node.getParent();
+    while (cur && !ts_morph_1.Node.isSourceFile(cur)) {
+        if (ts_morph_1.Node.isCallExpression(cur)) {
+            const calleeText = cur.getExpression().getText();
+            const base = calleeText.split("(")[0];
+            if (HOOK_OR_TEST.test(base)) {
+                const firstArg = cur.getArguments()[0];
+                if (firstArg && ts_morph_1.Node.isStringLiteral(firstArg)) {
+                    return firstArg.getLiteralValue();
+                }
+                if (firstArg &&
+                    ts_morph_1.Node.isNoSubstitutionTemplateLiteral(firstArg)) {
+                    return firstArg.getLiteralValue();
+                }
+                // Hook with no title (beforeEach) — use the hook keyword itself.
+                return base;
+            }
+        }
+        cur = cur.getParent();
+    }
+    return undefined;
+}
+// ═══════════════════════════════════════════════════════════════════
+// PRIVATE
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * True when `node`'s enclosing symbol/test-block still match what the anchor
+ * recorded. Only fields the anchor actually carries are checked — a coarse
+ * anchor (no symbolName / no enclosingFnName) imposes no extra constraint.
+ */
+function contextMatches(node, anchor) {
+    if (anchor.symbolName) {
+        if (enclosingSymbolName(node) !== anchor.symbolName)
+            return false;
+    }
+    if (anchor.enclosingFnName !== undefined) {
+        if (enclosingFnName(node) !== anchor.enclosingFnName)
+            return false;
+    }
+    return true;
+}
+function samePath(a, b) {
+    return normPath(a) === normPath(b);
+}
+function normPath(p) {
+    // ts-morph reports posix-style paths; normalise separators + drop "/./"
+    // and trailing slashes so equivalent paths compare equal cross-platform.
+    return p
+        .replace(/\\/g, "/")
+        .replace(/\/\.\//g, "/")
+        .replace(/\/+$/g, "")
+        .toLowerCase();
+}
+function short(sha) {
+    return sha.slice(0, 8);
+}

package/dist/services/DecisionEngine.d.ts

@@ -0,0 +1,51 @@
+import { Node, Block } from "ts-morph";
+import { AnchorKey, SourceSpan } from "./AnchorResolver";
+import { TraceTarget } from "./TraceBackEngine";
+export type DecisionStrategy = "MUTATE_IN_PLACE" | "FORK_AT_TEST" | "PROMPT_INTERACTIVE";
+export interface Edit {
+    kind: "replace" | "insert";
+    span: SourceSpan;
+    replacement: string;
+}
+export interface Decision {
+    strategy: DecisionStrategy;
+    reason: string;
+    /** Read-reference count to the declaration (the blast radius). */
+    blastRadius: number;
+    /** Distinct test/it blocks referencing the declaration. */
+    consumerTests: number;
+    /** Ordered edits. Apply via applyEdits (high→low offset). */
+    edits: Edit[];
+    /** When forking, the (possibly fresh) shadow variable name. */
+    forkVarName?: string;
+    /** 0..1 routing confidence (§5.3). */
+    confidence: number;
+    anchor: AnchorKey;
+}
+export interface DecideInput {
+    target: TraceTarget;
+    /** A node inside the FAILING statement — used to locate the test block. */
+    failingCallSite: Node;
+    /** Healed locator EXPRESSION text, e.g. `page.locator(".btn-v2")`. */
+    newLocatorExpr: string;
+    /** Runtime: only the failing test needs the new selector. */
+    contextSpecific: boolean;
+    /** Runtime: the selector rotted for ALL consumers (proven global). */
+    globalCorrect: boolean;
+}
+export declare class DecisionEngine {
+    static decide(input: DecideInput): Decision;
+}
+/**
+ * The Block of the nearest enclosing `test(...)` / `it(...)` callback. Hooks
+ * (`beforeEach`, etc.) are intentionally NOT matched — we fork into the test
+ * that failed, never into the shared hook.
+ */
+export declare function findEnclosingTestBlock(node: Node): Block | null;
+/**
+ * Apply edits to `original`, highest offset first so earlier offsets stay
+ * valid (the reverse-offset rule from the concurrency design §3.3.4).
+ * Throws on overlapping replace spans — never produces torn text.
+ */
+export declare function applyEdits(original: string, edits: Edit[]): string;
+//# sourceMappingURL=DecisionEngine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"DecisionEngine.d.ts","sourceRoot":"","sources":["../../src/services/DecisionEngine.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,IAAI,EAAc,KAAK,EAAE,MAAM,UAAU,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEzD,OAAO,EACL,WAAW,EAGZ,MAAM,mBAAmB,CAAC;AAM3B,MAAM,MAAM,gBAAgB,GACxB,iBAAiB,GACjB,cAAc,GACd,oBAAoB,CAAC;AAEzB,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC3B,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,aAAa,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,SAAS,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,WAAW,CAAC;IACpB,2EAA2E;IAC3E,eAAe,EAAE,IAAI,CAAC;IACtB,sEAAsE;IACtE,cAAc,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,eAAe,EAAE,OAAO,CAAC;IACzB,sEAAsE;IACtE,aAAa,EAAE,OAAO,CAAC;CACxB;AAMD,qBAAa,cAAc;IACzB,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,QAAQ;CAuD5C;AAqJD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,IAAI,GAAG,KAAK,GAAG,IAAI,CAc/D;AAwCD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,CAsBlE"}