sela-core 1.0.0

package/dist/services/SafetyGuard.js

@@ -0,0 +1,524 @@
+"use strict";
+// src/services/SafetyGuard.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SafetyGuard = void 0;
+const IntentAuditor_1 = require("./IntentAuditor");
+// ═══════════════════════════════════════════════════════════════════
+// DEFAULT THRESHOLDS  (match pre-config hardcoded values exactly)
+// ═══════════════════════════════════════════════════════════════════
+const DEFAULT_THRESHOLDS = {
+    confidenceHardStop: 85,
+    confidenceReviewThreshold: 95,
+    assertionSimilarityFloor: 0.7,
+    auditorConfidenceMin: 75,
+    allowSuspicious: false,
+    auditorStrictness: "balanced",
+};
+// Binary semantic opposites — always trigger FAIL_HARD regardless of mode,
+// because they indicate a state inversion (pass→fail, success→error, etc.)
+// that almost certainly masks a real logical regression.
+const SEMANTIC_OPPOSITE_PAIRS = new Set([
+    "denied|welcome",
+    "welcome|denied",
+    "login|logout",
+    "logout|login",
+    "success|failure",
+    "failure|success",
+    "success|error",
+    "error|success",
+    "pass|fail",
+    "fail|pass",
+    "approved|rejected",
+    "rejected|approved",
+    "active|inactive",
+    "inactive|active",
+    "enabled|disabled",
+    "disabled|enabled",
+    "open|closed",
+    "closed|open",
+    "visible|hidden",
+    "hidden|visible",
+    "on|off",
+    "off|on",
+    "true|false",
+    "false|true",
+    "allowed|denied",
+    "denied|allowed",
+    "granted|denied",
+    "denied|granted",
+    "locked|unlocked",
+    "unlocked|locked",
+    "connected|disconnected",
+    "disconnected|connected",
+    "running|stopped",
+    "stopped|running",
+    "valid|invalid",
+    "invalid|valid",
+]);
+const ROLE_KEYWORDS = new Map([
+    [
+        "SUBMIT",
+        new Set([
+            "submit",
+            "send",
+            "confirm",
+            "save",
+            "ok",
+            "done",
+            "apply",
+            "proceed",
+            "continue",
+            "execute",
+            "finish",
+            "complete",
+            "publish",
+            "post",
+        ]),
+    ],
+    [
+        "CANCEL",
+        new Set([
+            "cancel",
+            "abort",
+            "dismiss",
+            "close",
+            "back",
+            "exit",
+            "skip",
+            "no",
+            "discard",
+            "reject",
+            "decline",
+        ]),
+    ],
+    [
+        "DELETE",
+        new Set([
+            "delete",
+            "remove",
+            "clear",
+            "erase",
+            "destroy",
+            "trash",
+            "purge",
+            "drop",
+            "wipe",
+        ]),
+    ],
+    [
+        "NAVIGATE",
+        new Set([
+            "next",
+            "previous",
+            "prev",
+            "forward",
+            "backward",
+            "go",
+            "navigate",
+            "open",
+            "view",
+            "home",
+            "return",
+            "redirect",
+        ]),
+    ],
+    [
+        "AUTH",
+        new Set([
+            "login",
+            "logout",
+            "sign in",
+            "sign out",
+            "register",
+            "sign up",
+            "log in",
+            "log out",
+            "authenticate",
+            "authorize",
+        ]),
+    ],
+    [
+        "STATUS_POSITIVE",
+        new Set([
+            "success",
+            "approved",
+            "active",
+            "enabled",
+            "visible",
+            "on",
+            "open",
+            "allowed",
+            "welcome",
+            "pass",
+            "passed",
+            "valid",
+            "granted",
+            "connected",
+            "running",
+            "unlocked",
+            "online",
+            "available",
+        ]),
+    ],
+    [
+        "STATUS_NEGATIVE",
+        new Set([
+            "error",
+            "failure",
+            "failed",
+            "denied",
+            "inactive",
+            "disabled",
+            "hidden",
+            "off",
+            "closed",
+            "blocked",
+            "rejected",
+            "invalid",
+            "locked",
+            "disconnected",
+            "stopped",
+            "offline",
+            "unavailable",
+            "forbidden",
+            "unauthorized",
+        ]),
+    ],
+]);
+// ═══════════════════════════════════════════════════════════════════
+// SafetyGuard
+// ═══════════════════════════════════════════════════════════════════
+class SafetyGuard {
+    intentAuditor;
+    thresholds;
+    constructor(thresholds) {
+        this.thresholds = thresholds ?? DEFAULT_THRESHOLDS;
+        this.intentAuditor = new IntentAuditor_1.IntentAuditor();
+    }
+    // ─────────────────────────────────────────────────────────────
+    // PUBLIC ENTRY POINT
+    // ─────────────────────────────────────────────────────────────
+    async evaluate(context, aiFix) {
+        const { confidence, liveText, dnaBaselineText } = aiFix;
+        const { mode } = context;
+        // ── 0. Visibility Gate ───────────────────────────────────────
+        // Runs before any confidence or content checks.  A ghost element
+        // can never be safely acted upon regardless of AI confidence.
+        // Occlusion policy is branch-dependent (spec open question Q2
+        // decision: hard-fail on main, REQUIRES_REVIEW elsewhere).
+        if (aiFix.liveVisibility) {
+            const vis = aiFix.liveVisibility;
+            if (vis.isGhost) {
+                return {
+                    level: "FAIL_HARD",
+                    reason: `Visibility Gate: candidate element is a Ghost (${vis.ghostReason}) — ` +
+                        `functionally absent from the user's perspective`,
+                    canProceed: false,
+                };
+            }
+            if (vis.isOccluded) {
+                const isMainBranch = context.branch === "main" || context.branch === "master";
+                if (isMainBranch) {
+                    return {
+                        level: "FAIL_HARD",
+                        reason: `Visibility Gate: candidate element is occluded by an overlay on branch "${context.branch}" — ` +
+                            `hard-fail policy active on main`,
+                        canProceed: false,
+                    };
+                }
+                console.warn(`[SafetyGuard] ⚠️  Occlusion detected on branch "${context.branch ?? "unknown"}" — ` +
+                    `escalating to REQUIRES_REVIEW (not hard-failing on non-main branch)`);
+                return {
+                    level: "REQUIRES_REVIEW",
+                    reason: `Visibility Gate: candidate element is occluded by an overlay ` +
+                        `(branch: ${context.branch ?? "unknown"})`,
+                    canProceed: true,
+                };
+            }
+        }
+        // ── 1. Hard confidence stop ──────────────────────────────────
+        if (confidence < this.thresholds.confidenceHardStop) {
+            return {
+                level: "BLOCKED",
+                reason: `Confidence too low (${confidence}/100 < ${this.thresholds.confidenceHardStop}) — refusing to heal`,
+                canProceed: false,
+            };
+        }
+        // ── 2. Zero-Trust Verification ───────────────────────────────
+        // The AI's contentChange field is self-reported and may be absent even
+        // when the element's text actually changed (e.g. AI found #error-label-v2
+        // but stayed silent about it now showing "Error" instead of "Success").
+        //
+        // When liveText + dnaBaselineText are both available and differ, we
+        // synthesise a contentChange pair and apply the full inversion-check
+        // pipeline on it — regardless of what the AI reported.
+        //
+        // If the AI DID report contentChange we use that (more precise than raw
+        // innerText, which may include child element noise).
+        let effectiveContentChange = aiFix.contentChange;
+        if (!effectiveContentChange && liveText !== undefined && dnaBaselineText !== undefined) {
+            const normLive = liveText.trim();
+            const normDNA = dnaBaselineText.trim();
+            if (normLive !== normDNA && normLive.length > 0 && normDNA.length > 0) {
+                console.warn(`[SafetyGuard] 🚨 Zero-Trust override — AI omitted contentChange but live DOM differs:\n` +
+                    `  DNA baseline : "${normDNA}"\n` +
+                    `  Live text    : "${normLive}"`);
+                effectiveContentChange = { oldText: normDNA, newText: normLive };
+            }
+        }
+        // ── 3. Structural-only heal (no text change detected) ────────
+        if (!effectiveContentChange) {
+            const level = confidence < this.thresholds.confidenceReviewThreshold ? "REQUIRES_REVIEW" : "SAFE";
+            return {
+                level,
+                reason: `Structural selector change only (confidence=${confidence})`,
+                canProceed: true,
+            };
+        }
+        const { oldText, newText } = effectiveContentChange;
+        const source = aiFix.contentChange ? "AI-reported" : "zero-trust";
+        console.log(`[SafetyGuard] 🔬 Content change (${source}): "${oldText}" → "${newText}"`);
+        // ── 4. Binary semantic-opposite guard ────────────────────────
+        // Applies in ALL modes: "Enabled"→"Disabled", "Success"→"Error", etc.
+        // These always indicate a state inversion — never safe to auto-heal.
+        if (this.isSemanticOpposite(oldText, newText)) {
+            return {
+                level: "FAIL_HARD",
+                reason: `Semantic inversion detected: "${oldText}" ↔ "${newText}" — ` +
+                    `state inversions mask logical regressions`,
+                canProceed: false,
+            };
+        }
+        // ── 5. Functional role analysis ──────────────────────────────
+        const oldRole = this.classifyFunctionalRole(oldText);
+        const newRole = this.classifyFunctionalRole(newText);
+        console.log(`[SafetyGuard] 🔍 Role classification: "${oldText}"→${oldRole}, "${newText}"→${newRole}`);
+        // STATUS_POSITIVE ↔ STATUS_NEGATIVE is always a logic inversion
+        const isStatusInversion = (oldRole === "STATUS_POSITIVE" && newRole === "STATUS_NEGATIVE") ||
+            (oldRole === "STATUS_NEGATIVE" && newRole === "STATUS_POSITIVE");
+        if (isStatusInversion) {
+            return {
+                level: "FAIL_HARD",
+                reason: `Status inversion: "${oldText}" (${oldRole}) → "${newText}" (${newRole}) — ` +
+                    `masking a logic failure is not permitted`,
+                canProceed: false,
+            };
+        }
+        // Cross-role swap (e.g. DELETE → CANCEL, SUBMIT → NAVIGATE)
+        if (oldRole !== "UNKNOWN" &&
+            newRole !== "UNKNOWN" &&
+            oldRole !== newRole) {
+            if (mode === "assertion") {
+                // Assertion explicitly checked the old functional text; a different
+                // function being found is almost certainly a wrong element fix.
+                return {
+                    level: "BLOCKED",
+                    reason: `Functional role swap in assertion: "${oldText}" (${oldRole}) → "${newText}" (${newRole}) — ` +
+                        `the assertion was verifying a specific functional state`,
+                    canProceed: false,
+                };
+            }
+            // Action mode: allow with warning — a UI refactor may rename a control
+            // (e.g. "Delete" button renamed "Remove" or merged into a menu)
+            console.warn(`[SafetyGuard] ⚠️  Functional role change in action: ` +
+                `"${oldText}" (${oldRole}) → "${newText}" (${newRole}) — review recommended`);
+            return {
+                level: "REQUIRES_REVIEW",
+                reason: `Functional role change in action: "${oldText}" (${oldRole}) → "${newText}" (${newRole})`,
+                canProceed: true,
+            };
+        }
+        // ── 6. Intent Auditor gate ───────────────────────────────────
+        // Call the secondary LLM auditor when:
+        //   a) zero-trust synthesized the contentChange (AI was silent → extra scrutiny), OR
+        //   b) we are in assertion mode (the test explicitly checked the text), OR
+        //   c) both roles are UNKNOWN (no functional category to fall back on).
+        // Captures the auditor's score breakdown when it runs so the engine can
+        // emit a consolidated heal-summary log after all checks pass.
+        let localAuditMeta;
+        const shouldAudit = source === "zero-trust" ||
+            mode === "assertion" ||
+            (oldRole === "UNKNOWN" && newRole === "UNKNOWN");
+        if (shouldAudit) {
+            const auditVerdict = await this.intentAuditor.auditIntent({
+                dnaText: oldText,
+                dnaRole: aiFix.dnaRole,
+                liveText: newText,
+                healMode: mode,
+                // v2 structural context forwarded for scoring
+                dnaAncestry: aiFix.dnaAncestry,
+                liveAncestry: aiFix.liveAncestry,
+                dnaAnchors: aiFix.dnaAnchors,
+                liveAnchors: aiFix.liveAnchors,
+            });
+            // ── 7. Verdict mapping ──────────────────────────────────────
+            if (auditVerdict.verdict === "INCONSISTENT") {
+                return {
+                    level: "FAIL_HARD",
+                    reason: `Intent Auditor — INCONSISTENT: ${auditVerdict.reason}` +
+                        (auditVerdict.inversionType
+                            ? ` [inversion: ${auditVerdict.inversionType}]`
+                            : ""),
+                    canProceed: false,
+                };
+            }
+            if (auditVerdict.verdict === "SUSPICIOUS") {
+                const meta = {
+                    auditorVerdict: "SUSPICIOUS",
+                    auditorConfidence: auditVerdict.confidence,
+                };
+                // Block by default in assertion mode; allowSuspicious (loose policy) downgrades to REQUIRES_REVIEW
+                if (!this.thresholds.allowSuspicious && mode === "assertion") {
+                    return {
+                        level: "BLOCKED",
+                        reason: `Intent Auditor — SUSPICIOUS in assertion mode: ${auditVerdict.reason}`,
+                        canProceed: false,
+                        meta,
+                    };
+                }
+                if (this.thresholds.allowSuspicious && mode === "assertion") {
+                    console.log(`[SafetyGuard] ℹ️  allowSuspicious=true — SUSPICIOUS in assertion mode escalated to REQUIRES_REVIEW`);
+                }
+                return {
+                    level: "REQUIRES_REVIEW",
+                    reason: `Intent Auditor — SUSPICIOUS in ${mode} mode: ${auditVerdict.reason}`,
+                    canProceed: true,
+                    meta,
+                };
+            }
+            // CONSISTENT — fall through to similarity gate
+            console.log(`[SafetyGuard] ✅ Intent Auditor — CONSISTENT (${auditVerdict.confidence}%): ${auditVerdict.reason}`);
+            if (auditVerdict.scoreBreakdown) {
+                const { rawConfidence, penalty, bonus } = auditVerdict.scoreBreakdown;
+                if (penalty !== 0 || bonus !== 0) {
+                    localAuditMeta = {
+                        auditScoreBreakdown: {
+                            rawConfidence,
+                            penalty,
+                            bonus,
+                            adjustedConfidence: auditVerdict.confidence,
+                        },
+                    };
+                }
+            }
+        }
+        // ── 8. Semantic similarity gate (same-role or both UNKNOWN) ──
+        // For same-role pairs (e.g. SUBMIT→SUBMIT: "Submit"→"Send") we skip
+        // the similarity gate entirely — the role match is sufficient proof
+        // of functional equivalence.
+        //
+        // The gate is only applied when BOTH roles are UNKNOWN in assertion
+        // mode, where we have no functional category to fall back on.
+        if (mode === "assertion" && oldRole === "UNKNOWN" && newRole === "UNKNOWN") {
+            const similarity = this.computeSemanticSimilarity(oldText, newText);
+            console.log(`[SafetyGuard] 📊 Similarity: "${oldText}" ↔ "${newText}" = ${(similarity * 100).toFixed(1)}%`);
+            if (similarity < this.thresholds.assertionSimilarityFloor) {
+                return {
+                    level: "BLOCKED",
+                    reason: `Text divergence too high in assertion: "${oldText}" → "${newText}" ` +
+                        `(similarity=${(similarity * 100).toFixed(1)}% < ${(this.thresholds.assertionSimilarityFloor * 100).toFixed(0)}%) — ` +
+                        `possible content regression`,
+                    canProceed: false,
+                };
+            }
+        }
+        // ── 9. Confidence tiers ──────────────────────────────────────
+        if (confidence < this.thresholds.confidenceReviewThreshold) {
+            return {
+                level: "REQUIRES_REVIEW",
+                reason: `Low-confidence fix (${confidence}/100) — tagging for manual review`,
+                canProceed: true,
+                meta: localAuditMeta,
+            };
+        }
+        return {
+            level: "SAFE",
+            reason: `All safety checks passed (confidence=${confidence}, source=${source}, ` +
+                `oldRole=${oldRole}, newRole=${newRole})`,
+            canProceed: true,
+            meta: localAuditMeta,
+        };
+    }
+    // ─────────────────────────────────────────────────────────────
+    // SEMANTIC OPPOSITE CHECK
+    // ─────────────────────────────────────────────────────────────
+    isSemanticOpposite(oldText, newText) {
+        const key = `${oldText.toLowerCase().trim()}|${newText.toLowerCase().trim()}`;
+        return SEMANTIC_OPPOSITE_PAIRS.has(key);
+    }
+    // ─────────────────────────────────────────────────────────────
+    // FUNCTIONAL ROLE CLASSIFICATION
+    //
+    // Returns the first role whose keyword set contains the text
+    // (exact match or substring). Returns UNKNOWN when no role matches.
+    // ─────────────────────────────────────────────────────────────
+    classifyFunctionalRole(text) {
+        const normalized = text.toLowerCase().trim();
+        for (const [role, keywords] of ROLE_KEYWORDS) {
+            for (const kw of keywords) {
+                if (normalized === kw || normalized.includes(kw)) {
+                    return role;
+                }
+            }
+        }
+        return "UNKNOWN";
+    }
+    // ─────────────────────────────────────────────────────────────
+    // SEMANTIC SIMILARITY  (no external dependencies)
+    //
+    // Combined score: 0.5 × levenshtein_similarity + 0.5 × jaccard_similarity
+    //
+    // Levenshtein captures character-level similarity (typos, abbreviations).
+    // Jaccard captures word-level overlap (shared vocabulary, different order).
+    // The 50/50 blend is robust against short labels where one metric misleads.
+    // ─────────────────────────────────────────────────────────────
+    computeSemanticSimilarity(a, b) {
+        const na = a.toLowerCase().trim();
+        const nb = b.toLowerCase().trim();
+        if (na === nb)
+            return 1;
+        const maxLen = Math.max(na.length, nb.length);
+        const levSim = maxLen === 0 ? 1 : 1 - this.levenshteinDistance(na, nb) / maxLen;
+        const jaccard = this.jaccardSimilarity(na, nb);
+        return 0.5 * levSim + 0.5 * jaccard;
+    }
+    // ─────────────────────────────────────────────────────────────
+    // PRIVATE: Levenshtein distance (space-optimised two-row DP)
+    // ─────────────────────────────────────────────────────────────
+    levenshteinDistance(a, b) {
+        const m = a.length;
+        const n = b.length;
+        if (m === 0)
+            return n;
+        if (n === 0)
+            return m;
+        let prev = Array.from({ length: n + 1 }, (_, i) => i);
+        let curr = new Array(n + 1);
+        for (let i = 1; i <= m; i++) {
+            curr[0] = i;
+            for (let j = 1; j <= n; j++) {
+                const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+                curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+            }
+            [prev, curr] = [curr, prev];
+        }
+        return prev[n];
+    }
+    // ─────────────────────────────────────────────────────────────
+    // PRIVATE: Jaccard word-set similarity
+    // ─────────────────────────────────────────────────────────────
+    jaccardSimilarity(a, b) {
+        const setA = new Set(a.split(/\s+/).filter(Boolean));
+        const setB = new Set(b.split(/\s+/).filter(Boolean));
+        if (setA.size === 0 && setB.size === 0)
+            return 1;
+        let intersection = 0;
+        for (const w of setA) {
+            if (setB.has(w))
+                intersection++;
+        }
+        const union = setA.size + setB.size - intersection;
+        return union === 0 ? 1 : intersection / union;
+    }
+}
+exports.SafetyGuard = SafetyGuard;

package/dist/services/SnapshotService.d.ts

@@ -0,0 +1,11 @@
+import { Page } from "@playwright/test";
+import { ElementSnapshot, ElementSnapshotV2 } from "../types";
+export declare class SnapshotService {
+    private baseDir;
+    constructor();
+    save(key: string, data: ElementSnapshot): Promise<void>;
+    load(key: string): Promise<ElementSnapshotV2 | null>;
+    captureElement(page: Page, selector: string, framePath?: string[]): Promise<ElementSnapshotV2 | null>;
+    private migrateToV2;
+}
+//# sourceMappingURL=SnapshotService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SnapshotService.d.ts","sourceRoot":"","sources":["../../src/services/SnapshotService.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EACL,eAAe,EACf,iBAAiB,EAElB,MAAM,UAAU,CAAC;AAElB,qBAAa,eAAe;IAC1B,OAAO,CAAC,OAAO,CAAS;;IASlB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAYvD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAwBpD,cAAc,CAClB,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,MAAM,EAChB,SAAS,GAAE,MAAM,EAAO,GACvB,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAoRpC,OAAO,CAAC,WAAW;CAsBpB"}