sela-core 0.1.0-alpha.1

package/dist/services/ChainValidator.js

@@ -0,0 +1,570 @@
+"use strict";
+// src/services/ChainValidator.ts
+//
+// ═══════════════════════════════════════════════════════════════════
+// VALIDATION LAYER for AI-generated chain segments
+//
+// Runs 5 sequential guards before any AST mutation occurs:
+//
+//   [1] SchemaValidator    - required fields, no unknown segment types
+//   [2] TypeFlowValidator  - tracks Locator|FrameLocator state
+//   [3] ReceiverValidator  - root must match original chain's receiver
+//   [4] PlacementValidator - filter() / nth() / first() only after Locator
+//   [5] SemanticUpgrader   - upgrades flat CSS to semantic where possible
+//
+// Each guard returns a ValidationResult. The pipeline short-circuits on
+// the first REJECT, falling back to the original flat-CSS strategy.
+// ═══════════════════════════════════════════════════════════════════
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChainValidator = void 0;
+exports.segmentsToCode = segmentsToCode;
+const logger_1 = require("../utils/logger");
+// ─────────────────────────────────────────────────────────────────
+// CONSTANTS
+// ─────────────────────────────────────────────────────────────────
+const KNOWN_SEGMENT_TYPES = new Set([
+    "locator",
+    "frameLocator",
+    "getByRole",
+    "getByLabel",
+    "getByText",
+    "getByPlaceholder",
+    "getByTestId",
+    "getByAltText",
+    "getByTitle",
+    "filter",
+    "first",
+    "last",
+    "nth",
+]);
+// Methods that produce a Locator (not FrameLocator)
+const LOCATOR_PRODUCERS = new Set([
+    "locator",
+    "getByRole",
+    "getByLabel",
+    "getByText",
+    "getByPlaceholder",
+    "getByTestId",
+    "getByAltText",
+    "getByTitle",
+    "filter",
+    "first",
+    "last",
+    "nth",
+]);
+// Methods valid only when current return type is Locator
+const REQUIRES_LOCATOR = new Set(["filter", "first", "last", "nth"]);
+// Methods that can chain on both Locator and FrameLocator (or start fresh)
+const WORKS_ON_FRAME_LOCATOR = new Set([
+    "locator",
+    "getByRole",
+    "getByLabel",
+    "getByText",
+    "getByPlaceholder",
+    "getByTestId",
+    "getByAltText",
+    "getByTitle",
+    "frameLocator",
+]);
+const VALID_ARIA_ROLES = new Set([
+    // Interactive
+    "button",
+    "textbox",
+    "searchbox",
+    "checkbox",
+    "radio",
+    "switch",
+    "combobox",
+    "listbox",
+    "option",
+    "menuitem",
+    "menuitemcheckbox",
+    "menuitemradio",
+    "link",
+    "tab",
+    "tabpanel",
+    "slider",
+    "spinbutton",
+    "progressbar",
+    "scrollbar",
+    "grid",
+    "gridcell",
+    "row",
+    "rowheader",
+    "columnheader",
+    "cell",
+    "treeitem",
+    "tree",
+    "treegrid",
+    "dialog",
+    "alertdialog",
+    // Structural
+    "heading",
+    "banner",
+    "main",
+    "navigation",
+    "nav",
+    "complementary",
+    "aside",
+    "contentinfo",
+    "footer",
+    "region",
+    "landmark",
+    "article",
+    "section",
+    "list",
+    "listitem",
+    "term",
+    "definition",
+    "figure",
+    "img",
+    "presentation",
+    "none",
+    "separator",
+    "log",
+    "marquee",
+    "status",
+    "timer",
+    "alert",
+    "form",
+    "group",
+    "toolbar",
+    "menubar",
+    "menu",
+    "tooltip",
+    "math",
+    "note",
+    "application",
+    "document",
+    "feed",
+    "generic",
+]);
+// ─────────────────────────────────────────────────────────────────
+// GUARD 1 - Schema Validator
+// ─────────────────────────────────────────────────────────────────
+function schemaValidate(segments) {
+    if (!Array.isArray(segments) || segments.length === 0) {
+        return { valid: false, reason: "segments must be a non-empty array" };
+    }
+    for (let i = 0; i < segments.length; i++) {
+        const seg = segments[i];
+        if (typeof seg !== "object" || seg === null) {
+            return { valid: false, reason: `segment[${i}] is not an object` };
+        }
+        if (!KNOWN_SEGMENT_TYPES.has(seg.type)) {
+            return {
+                valid: false,
+                reason: `segment[${i}] has unknown type "${seg.type}"`,
+            };
+        }
+        // Per-type required fields
+        switch (seg.type) {
+            case "locator":
+            case "frameLocator":
+                if (typeof seg.selector !== "string" || seg.selector.trim() === "") {
+                    return {
+                        valid: false,
+                        reason: `segment[${i}] type="${seg.type}" requires non-empty selector`,
+                    };
+                }
+                break;
+            case "getByRole":
+                if (typeof seg.role !== "string" || seg.role.trim() === "") {
+                    return {
+                        valid: false,
+                        reason: `segment[${i}] getByRole requires non-empty role`,
+                    };
+                }
+                if (!VALID_ARIA_ROLES.has(seg.role.toLowerCase())) {
+                    return {
+                        valid: false,
+                        reason: `segment[${i}] getByRole has invalid ARIA role "${seg.role}"`,
+                    };
+                }
+                break;
+            case "getByLabel":
+            case "getByText":
+            case "getByPlaceholder":
+            case "getByAltText":
+            case "getByTitle":
+                if (typeof seg.text !== "string" || seg.text.trim() === "") {
+                    return {
+                        valid: false,
+                        reason: `segment[${i}] type="${seg.type}" requires non-empty text`,
+                    };
+                }
+                break;
+            case "getByTestId":
+                if (typeof seg.testId !== "string" || seg.testId.trim() === "") {
+                    return {
+                        valid: false,
+                        reason: `segment[${i}] getByTestId requires non-empty testId`,
+                    };
+                }
+                break;
+            case "nth":
+                if (typeof seg.index !== "number" || !Number.isInteger(seg.index)) {
+                    return {
+                        valid: false,
+                        reason: `segment[${i}] nth requires integer index`,
+                    };
+                }
+                break;
+            case "filter":
+                if (seg.hasText === undefined &&
+                    seg.hasNotText === undefined &&
+                    seg.has === undefined &&
+                    seg.hasNot === undefined) {
+                    return {
+                        valid: false,
+                        reason: `segment[${i}] filter requires at least one of: hasText, hasNotText, has, hasNot`,
+                    };
+                }
+                break;
+            // first / last have no required fields beyond type
+        }
+    }
+    return { valid: true };
+}
+// ─────────────────────────────────────────────────────────────────
+// GUARD 2 - Type Flow Validator
+//
+// Simulates the chain execution, tracking whether the current
+// expression is a Locator, FrameLocator, or Page/unknown.
+// ─────────────────────────────────────────────────────────────────
+function typeFlowValidate(segments, rootType) {
+    let currentType = rootType;
+    for (let i = 0; i < segments.length; i++) {
+        const seg = segments[i];
+        if (seg.type === "frameLocator") {
+            // frameLocator() is valid on Page or FrameLocator, not Locator
+            if (currentType === "Locator") {
+                return {
+                    valid: false,
+                    reason: `segment[${i}] frameLocator() cannot be called on a Locator (type flow: ${currentType} → invalid)`,
+                };
+            }
+            currentType = "FrameLocator";
+            continue;
+        }
+        if (REQUIRES_LOCATOR.has(seg.type)) {
+            if (currentType !== "Locator") {
+                return {
+                    valid: false,
+                    reason: `segment[${i}] .${seg.type}() requires a Locator receiver but current type is "${currentType}"`,
+                };
+            }
+            currentType = "Locator";
+            continue;
+        }
+        if (LOCATOR_PRODUCERS.has(seg.type)) {
+            // These methods are valid on Page, FrameLocator, or Locator
+            currentType = "Locator";
+            continue;
+        }
+    }
+    // Final chain must end in a Locator (not FrameLocator) for assertions to work
+    if (currentType === "FrameLocator") {
+        return {
+            valid: false,
+            reason: "chain ends on FrameLocator - assertions require a Locator at the end",
+        };
+    }
+    return { valid: true };
+}
+// ─────────────────────────────────────────────────────────────────
+// GUARD 3 - Receiver Validator
+//
+// The first segment's effective receiver must be compatible with
+// the original code's root receiver. Prevents `page.getByRole()`
+// from replacing `userRow.getByRole()`.
+// ─────────────────────────────────────────────────────────────────
+function receiverValidate(segments, originalRootReceiver, proposedRootReceiver) {
+    const orig = originalRootReceiver.trim();
+    const proposed = proposedRootReceiver.trim();
+    // If both are "page" or both are the same variable, we're fine
+    if (orig === proposed)
+        return { valid: true };
+    // "page" is a global receiver - the AI sometimes proposes it even when
+    // the original chain was scoped. This is only acceptable if the original
+    // chain itself started from "page".
+    const PAGE_RECEIVERS = new Set(["page", "context", "browser"]);
+    if (PAGE_RECEIVERS.has(proposed) && !PAGE_RECEIVERS.has(orig)) {
+        return {
+            valid: false,
+            reason: `receiver mismatch: original chain rooted at "${orig}" but proposed chain starts from "${proposed}" - this would change element scope`,
+        };
+    }
+    // If the original root is a local variable and proposed is different,
+    // accept only if proposed is also a valid-looking identifier (not page).
+    // We allow this since sometimes variables are renamed but semantically
+    // equivalent.
+    if (!PAGE_RECEIVERS.has(orig) && !PAGE_RECEIVERS.has(proposed)) {
+        // Both are custom variables - trust the AI's context
+        logger_1.logger.warn(`Receiver mismatch: "${orig}" vs "${proposed}" - proceeding cautiously`);
+        return { valid: true };
+    }
+    return { valid: true };
+}
+// ─────────────────────────────────────────────────────────────────
+// GUARD 4 - Placement Validator
+//
+// Validates placement-sensitive rules:
+//   - filter/first/last/nth must follow a Locator-producing segment
+//   - frameLocator cannot follow a Locator
+//   - No duplicate consecutive locator calls without a filter between them
+//     when that would be ambiguous (e.g. locator(".a").locator(".a"))
+// ─────────────────────────────────────────────────────────────────
+function placementValidate(segments) {
+    for (let i = 0; i < segments.length; i++) {
+        const seg = segments[i];
+        const prev = i > 0 ? segments[i - 1] : null;
+        if (REQUIRES_LOCATOR.has(seg.type) && prev !== null) {
+            if (prev.type === "frameLocator") {
+                return {
+                    valid: false,
+                    reason: `segment[${i}] .${seg.type}() placed immediately after frameLocator() - invalid`,
+                };
+            }
+        }
+        // filter() must have a non-empty content
+        if (seg.type === "filter") {
+            const hasAnyPredicate = (seg.hasText && seg.hasText.trim() !== "") ||
+                (seg.hasNotText && seg.hasNotText.trim() !== "") ||
+                (seg.has && seg.has.trim() !== "") ||
+                (seg.hasNot && seg.hasNot.trim() !== "");
+            if (!hasAnyPredicate) {
+                return {
+                    valid: false,
+                    reason: `segment[${i}] filter() has all-empty predicates - would be a no-op`,
+                };
+            }
+        }
+    }
+    return { valid: true };
+}
+// ─────────────────────────────────────────────────────────────────
+// GUARD 5 - Semantic Upgrader
+//
+// Opportunistically upgrades flat CSS locator segments to semantic
+// equivalents following Playwright's priority hierarchy:
+//   1. getByTestId  (data-testid)
+//   2. getByRole    (aria role inference from CSS)
+//   3. getByLabel   (form elements)
+//   4. locator      (CSS - unchanged)
+//
+// This guard NEVER rejects - it only upgrades and returns the
+// possibly-improved segments.
+// ─────────────────────────────────────────────────────────────────
+const ROLE_BY_TAG = {
+    button: "button",
+    a: "link",
+    input: "textbox", // overridden for checkboxes etc. below
+    textarea: "textbox",
+    select: "combobox",
+    h1: "heading",
+    h2: "heading",
+    h3: "heading",
+    h4: "heading",
+    h5: "heading",
+    h6: "heading",
+    nav: "navigation",
+    main: "main",
+    header: "banner",
+    footer: "contentinfo",
+    aside: "complementary",
+};
+function tryUpgradeToSemantic(seg) {
+    if (seg.type !== "locator")
+        return seg;
+    const css = seg.selector.trim();
+    // Priority 1: data-testid
+    const testIdMatch = css.match(/\[data-testid=["']([^"']+)["']\]/);
+    if (testIdMatch) {
+        return { type: "getByTestId", testId: testIdMatch[1] };
+    }
+    // Priority 2: aria-label
+    const ariaLabelMatch = css.match(/\[aria-label=["']([^"']+)["']\]/);
+    if (ariaLabelMatch) {
+        return { type: "getByLabel", text: ariaLabelMatch[1] };
+    }
+    // Priority 3: role inference from pure tag selectors
+    const tagOnlyMatch = css.match(/^([a-zA-Z][a-zA-Z0-9]*)$/);
+    if (tagOnlyMatch) {
+        const tag = tagOnlyMatch[1].toLowerCase();
+        const role = ROLE_BY_TAG[tag];
+        if (role) {
+            return { type: "getByRole", role };
+        }
+    }
+    // Priority 3b: button[type="submit"] or button.classname - still a button role
+    const buttonMatch = css.match(/^button(?:[.[#][^\s]*)?$/);
+    if (buttonMatch) {
+        return { type: "getByRole", role: "button" };
+    }
+    // Priority 4: has-text() - convert to getByText
+    const hasTextMatch = css.match(/^.*:has-text\(["']([^"']+)["']\)$/);
+    if (hasTextMatch) {
+        return { type: "getByText", text: hasTextMatch[1] };
+    }
+    // Otherwise leave as CSS locator
+    return seg;
+}
+function semanticUpgrade(segments) {
+    return segments.map(tryUpgradeToSemantic);
+}
+// ─────────────────────────────────────────────────────────────────
+// CODE GENERATOR
+//
+// Converts validated ChainSegment[] into clean TypeScript source code.
+// Respects developer style: multi-segment chains get line-broken only
+// when depth >= 3 (configurable).
+// ─────────────────────────────────────────────────────────────────
+function segmentsToCode(receiver, segments, multiLine = false) {
+    const sep = multiLine ? "\n  " : "";
+    let code = receiver;
+    for (const seg of segments) {
+        const prefix = multiLine ? `\n  ` : "";
+        switch (seg.type) {
+            case "locator":
+                code += `${prefix}.locator(${q(seg.selector)})`;
+                break;
+            case "frameLocator":
+                code += `${prefix}.frameLocator(${q(seg.selector)})`;
+                break;
+            case "getByRole": {
+                const opts = [];
+                if (seg.name !== undefined)
+                    opts.push(`name: ${q(seg.name)}`);
+                if (seg.exact !== undefined)
+                    opts.push(`exact: ${seg.exact}`);
+                const optStr = opts.length > 0 ? `, { ${opts.join(", ")} }` : "";
+                code += `${prefix}.getByRole(${q(seg.role)}${optStr})`;
+                break;
+            }
+            case "getByLabel": {
+                const opts = seg.exact !== undefined ? `, { exact: ${seg.exact} }` : "";
+                code += `${prefix}.getByLabel(${q(seg.text)}${opts})`;
+                break;
+            }
+            case "getByText": {
+                const opts = seg.exact !== undefined ? `, { exact: ${seg.exact} }` : "";
+                code += `${prefix}.getByText(${q(seg.text)}${opts})`;
+                break;
+            }
+            case "getByPlaceholder":
+                code += `${prefix}.getByPlaceholder(${q(seg.text)})`;
+                break;
+            case "getByTestId":
+                code += `${prefix}.getByTestId(${q(seg.testId)})`;
+                break;
+            case "getByAltText":
+                code += `${prefix}.getByAltText(${q(seg.text)})`;
+                break;
+            case "getByTitle":
+                code += `${prefix}.getByTitle(${q(seg.text)})`;
+                break;
+            case "filter": {
+                const parts = [];
+                if (seg.hasText)
+                    parts.push(`hasText: ${q(seg.hasText)}`);
+                if (seg.hasNotText)
+                    parts.push(`hasNotText: ${q(seg.hasNotText)}`);
+                if (seg.has)
+                    parts.push(`has: ${seg.has}`); // has is a Locator expr
+                if (seg.hasNot)
+                    parts.push(`hasNot: ${seg.hasNot}`);
+                code += `${prefix}.filter({ ${parts.join(", ")} })`;
+                break;
+            }
+            case "first":
+                code += `${prefix}.first()`;
+                break;
+            case "last":
+                code += `${prefix}.last()`;
+                break;
+            case "nth":
+                code += `${prefix}.nth(${seg.index})`;
+                break;
+        }
+    }
+    return code;
+}
+// Helper: quote a string safely, escaping internal double quotes
+function q(s) {
+    return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+class ChainValidator {
+    validate(input) {
+        const { segments: rawSegments, originalRootReceiver, proposedRootReceiver, rootType = "unknown", applySemanticUpgrade = true, } = input;
+        // Guard 1: Schema
+        const schemaResult = schemaValidate(rawSegments);
+        if (!schemaResult.valid) {
+            logger_1.logger.warn(`Schema: ${schemaResult.reason}`);
+            return schemaResult;
+        }
+        let segments = rawSegments;
+        // Guard 2: Type flow
+        const effectiveRootType = rootType === "unknown" ? "Locator" : rootType;
+        // For Page-level (page.xxx), the root is not yet a Locator/FrameLocator
+        // - we treat the first segment as the producer.
+        const isPageReceiver = originalRootReceiver === "page" ||
+            originalRootReceiver === "context" ||
+            originalRootReceiver === "browser";
+        const typeFlowResult = typeFlowValidate(segments, isPageReceiver ? "unknown" : effectiveRootType);
+        if (!typeFlowResult.valid) {
+            logger_1.logger.warn(`TypeFlow: ${typeFlowResult.reason}`);
+            return typeFlowResult;
+        }
+        // Guard 3: Receiver compatibility
+        const receiverResult = receiverValidate(segments, originalRootReceiver, proposedRootReceiver);
+        if (!receiverResult.valid) {
+            logger_1.logger.warn(`Receiver: ${receiverResult.reason}`);
+            return receiverResult;
+        }
+        // Guard 4: Placement
+        const placementResult = placementValidate(segments);
+        if (!placementResult.valid) {
+            logger_1.logger.warn(`Placement: ${placementResult.reason}`);
+            return placementResult;
+        }
+        // Guard 5: Semantic upgrade (non-rejecting)
+        if (applySemanticUpgrade) {
+            segments = semanticUpgrade(segments);
+        }
+        // Generate code
+        const multiLine = segments.length >= 3;
+        const code = segmentsToCode(proposedRootReceiver, segments, multiLine);
+        logger_1.logger.debug(`Valid chain (${segments.length} segments): ${code}`);
+        return { valid: true, segments, code, multiLine };
+    }
+    /**
+     * Lightweight check: does this segment array describe the same
+     * semantic intent as the old flat selector string?
+     * Used as a sanity check before committing an AST write.
+     */
+    intentMatches(segments, oldFlatSelector) {
+        const lastSeg = segments[segments.length - 1];
+        if (!lastSeg)
+            return false;
+        const oldLower = oldFlatSelector.toLowerCase();
+        switch (lastSeg.type) {
+            case "locator":
+                return oldLower.includes(lastSeg.selector.toLowerCase());
+            case "getByRole":
+                return (oldLower.includes(lastSeg.role.toLowerCase()) ||
+                    oldLower.includes("role="));
+            case "getByLabel":
+            case "getByText":
+            case "getByPlaceholder":
+            case "getByAltText":
+            case "getByTitle":
+                return oldLower.includes(lastSeg.text.toLowerCase());
+            case "getByTestId":
+                return oldLower.includes(lastSeg.testId.toLowerCase());
+            default:
+                return true;
+        }
+    }
+}
+exports.ChainValidator = ChainValidator;

package/dist/services/CrossFileHealer.d.ts

@@ -0,0 +1,6 @@
+import { Project } from "ts-morph";
+import type { ASTUpdateResult } from "./ASTSourceUpdater.js";
+export declare class CrossFileHealer {
+    static heal(modulePath: string, symbolName: string, newValue: string, callerFilePath: string, project: Project, depth?: number): ASTUpdateResult;
+}
+//# sourceMappingURL=CrossFileHealer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CrossFileHealer.d.ts","sourceRoot":"","sources":["../../src/services/CrossFileHealer.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAGnC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAoB7D,qBAAa,eAAe;IAC1B,MAAM,CAAC,IAAI,CACT,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,OAAO,EAChB,KAAK,SAAI,GACR,eAAe;CAqFnB"}