sela-core 0.1.0-alpha.1

package/dist/services/DefinitionTracer.js

@@ -0,0 +1,366 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FunctionalReturnAnalyzer = exports.DefinitionTracer = void 0;
+const ts_morph_1 = require("ts-morph");
+const logger_1 = require("../utils/logger");
+// ═══════════════════════════════════════════════════════════════════
+// DefinitionTracer
+//
+// T-5: traceIdentifier - follow bare variable name to its initializer.
+// T-6: tracePropertyAccess - follow OBJECT.prop to the property value.
+//
+// In-file first; signals crossFile when symbol comes from an import.
+// Never does I/O beyond what ts-morph provides on the given SourceFile.
+// ═══════════════════════════════════════════════════════════════════
+const MAX_TRACE_DEPTH = 5;
+class DefinitionTracer {
+    // ─────────────────────────────────────────────────────────────────
+    // T-5: Identifier trace
+    // ─────────────────────────────────────────────────────────────────
+    static traceIdentifier(identifierNode, sourceFile, callerLine, depth = 0) {
+        if (depth >= MAX_TRACE_DEPTH) {
+            return {
+                found: false,
+                crossFile: false,
+                reason: "max trace depth reached",
+            };
+        }
+        const symbolName = identifierNode.getText().trim();
+        // 1. In-file: find closest VariableDeclaration before callerLine.
+        const decl = findVarDeclInFile(sourceFile, symbolName, callerLine);
+        if (decl) {
+            const init = decl.getInitializer();
+            if (!init) {
+                return {
+                    found: false,
+                    crossFile: false,
+                    reason: `"${symbolName}" has no initializer`,
+                };
+            }
+            // Recursive follow: if init is another identifier, trace again.
+            if (ts_morph_1.Node.isIdentifier(init)) {
+                return DefinitionTracer.traceIdentifier(init, sourceFile, decl.getStartLineNumber(), depth + 1);
+            }
+            logger_1.logger.debug(`traceIdentifier: "${symbolName}" → ` +
+                `${init.getKindName()} @ ${sourceFile.getBaseName()}:${init.getStartLineNumber()}`);
+            return {
+                found: true,
+                targetNode: init,
+                targetFile: sourceFile,
+                declarationNode: decl,
+            };
+        }
+        // 2. Symbol not in file - check import declarations.
+        const imported = findImportedSymbol(sourceFile, symbolName);
+        if (imported) {
+            logger_1.logger.debug(`traceIdentifier: "${symbolName}" comes from "${imported.modulePath}" (cross-file)`);
+            return { found: false, crossFile: true, ...imported };
+        }
+        // 3. Last resort: ts-morph language-service definition lookup.
+        try {
+            const defNodes = identifierNode.getDefinitionNodes?.();
+            if (defNodes && defNodes.length > 0) {
+                for (const def of defNodes) {
+                    if (ts_morph_1.Node.isVariableDeclaration(def)) {
+                        const init = def.getInitializer();
+                        if (init) {
+                            logger_1.logger.debug(`traceIdentifier (via LangSvc): "${symbolName}" → ` +
+                                `${init.getKindName()} @ ${def.getSourceFile().getBaseName()}:${init.getStartLineNumber()}`);
+                            return {
+                                found: true,
+                                targetNode: init,
+                                targetFile: def.getSourceFile(),
+                            };
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+            // Language service unavailable - not an error.
+        }
+        return {
+            found: false,
+            crossFile: false,
+            reason: `"${symbolName}" not resolved in file or imports`,
+        };
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // T-6: PropertyAccessExpression trace
+    // ─────────────────────────────────────────────────────────────────
+    static tracePropertyAccess(propAccessNode, sourceFile, callerLine) {
+        if (!ts_morph_1.Node.isPropertyAccessExpression(propAccessNode)) {
+            return {
+                found: false,
+                crossFile: false,
+                reason: "node is not a PropertyAccessExpression",
+            };
+        }
+        const expr = propAccessNode;
+        const objectName = expr.getExpression().getText().trim();
+        const propName = expr.getName();
+        // Find the object's VariableDeclaration.
+        const objDecl = findVarDeclInFile(sourceFile, objectName, callerLine);
+        if (!objDecl) {
+            const imported = findImportedSymbol(sourceFile, objectName);
+            if (imported) {
+                logger_1.logger.debug(`tracePropertyAccess: "${objectName}" comes from "${imported.modulePath}" (cross-file)`);
+                return { found: false, crossFile: true, ...imported };
+            }
+            return {
+                found: false,
+                crossFile: false,
+                reason: `object "${objectName}" not found in file or imports`,
+            };
+        }
+        const init = objDecl.getInitializer();
+        if (!init || !ts_morph_1.Node.isObjectLiteralExpression(init)) {
+            return {
+                found: false,
+                crossFile: false,
+                reason: `"${objectName}" initializer is not an ObjectLiteralExpression (got ${init?.getKindName() ?? "none"})`,
+            };
+        }
+        // ts-morph getProperty(name) - returns the first matching property.
+        const prop = init.getProperty(propName);
+        if (!prop || !ts_morph_1.Node.isPropertyAssignment(prop)) {
+            return {
+                found: false,
+                crossFile: false,
+                reason: `property "${propName}" not found on "${objectName}"`,
+            };
+        }
+        const valueNode = prop.getInitializer();
+        if (!valueNode) {
+            return {
+                found: false,
+                crossFile: false,
+                reason: `property "${propName}" on "${objectName}" has no initializer`,
+            };
+        }
+        logger_1.logger.debug(`tracePropertyAccess: "${objectName}.${propName}" → ` +
+            `${valueNode.getKindName()} "${valueNode.getText()}" ` +
+            `@ ${sourceFile.getBaseName()}:${valueNode.getStartLineNumber()}`);
+        return {
+            found: true,
+            targetNode: valueNode,
+            targetFile: sourceFile,
+            declarationNode: prop,
+        };
+    }
+    // ─────────────────────────────────────────────────────────────────
+    // traceByName - used by CrossFileHealer
+    //
+    // Like traceIdentifier but takes a plain symbol name string instead
+    // of an Identifier node.  Searches the entire file (no callerLine
+    // constraint) so it's suitable for resolving exported symbols.
+    // ─────────────────────────────────────────────────────────────────
+    static traceByName(symbolName, sourceFile) {
+        const decl = findVarDeclInFile(sourceFile, symbolName, Number.MAX_SAFE_INTEGER);
+        if (!decl) {
+            const imported = findImportedSymbol(sourceFile, symbolName);
+            if (imported)
+                return { found: false, crossFile: true, ...imported };
+            return {
+                found: false,
+                crossFile: false,
+                reason: `"${symbolName}" not found in ${sourceFile.getBaseName()}`,
+            };
+        }
+        const init = decl.getInitializer();
+        if (!init) {
+            return {
+                found: false,
+                crossFile: false,
+                reason: `"${symbolName}" has no initializer`,
+            };
+        }
+        logger_1.logger.debug(`traceByName: "${symbolName}" → ` +
+            `${init.getKindName()} @ ${sourceFile.getBaseName()}:${init.getStartLineNumber()}`);
+        return {
+            found: true,
+            targetNode: init,
+            targetFile: sourceFile,
+            declarationNode: decl,
+        };
+    }
+}
+exports.DefinitionTracer = DefinitionTracer;
+// ═══════════════════════════════════════════════════════════════════
+// FunctionalReturnAnalyzer
+//
+// T-7: Given a CallExpression whose callee is a local function,
+// enter the function body and return its return expression + arg bindings.
+// ═══════════════════════════════════════════════════════════════════
+class FunctionalReturnAnalyzer {
+    static analyze(callNode, sourceFile) {
+        if (!ts_morph_1.Node.isCallExpression(callNode)) {
+            return { kind: "complex", reason: "node is not a CallExpression" };
+        }
+        const call = callNode;
+        const calleeExpr = call.getExpression();
+        // Only handle simple identifier callees: getScopedInput(role).
+        // PropertyAccess callees (obj.method()) are out of scope for Phase 2.
+        if (!ts_morph_1.Node.isIdentifier(calleeExpr)) {
+            return {
+                kind: "complex",
+                reason: `callee is ${calleeExpr.getKindName()}, not a simple identifier`,
+            };
+        }
+        const calleeName = calleeExpr.getText();
+        const fnResult = findFunctionBody(sourceFile, calleeName);
+        if (!fnResult) {
+            return {
+                kind: "complex",
+                reason: `function "${calleeName}" not found in file`,
+            };
+        }
+        const { returnExpr, params, line } = fnResult;
+        // Build argument bindings: paramName → runtime value text.
+        const callArgs = call.getArguments();
+        const bindings = new Map();
+        for (let i = 0; i < params.length; i++) {
+            const argNode = callArgs[i];
+            if (!argNode)
+                continue;
+            const raw = argNode.getText();
+            // Strip surrounding quotes for string literals so bindings hold the value, not the syntax.
+            const value = ts_morph_1.Node.isStringLiteral(argNode)
+                ? argNode.getLiteralValue()
+                : raw.replace(/^["'`]|["'`]$/g, "");
+            bindings.set(params[i], value);
+        }
+        if (ts_morph_1.Node.isStringLiteral(returnExpr) ||
+            ts_morph_1.Node.isNoSubstitutionTemplateLiteral(returnExpr)) {
+            logger_1.logger.debug(`"${calleeName}" returns StringLiteral ` +
+                `"${returnExpr.getLiteralValue()}" @ line ${line}`);
+            return {
+                kind: "literal",
+                literalNode: returnExpr,
+                functionFile: sourceFile,
+                functionLine: line,
+            };
+        }
+        if (ts_morph_1.Node.isTemplateExpression(returnExpr)) {
+            const head = returnExpr
+                .getHead()
+                .getLiteralText();
+            logger_1.logger.debug(`"${calleeName}" returns TemplateExpression ` +
+                `(head: "${head}") @ line ${line}. Bindings: ${JSON.stringify(Object.fromEntries(bindings))}`);
+            return {
+                kind: "template",
+                templateNode: returnExpr,
+                bindings,
+                functionFile: sourceFile,
+                functionLine: line,
+            };
+        }
+        return {
+            kind: "complex",
+            reason: `"${calleeName}" return expression is ${returnExpr.getKindName()} - not directly healable`,
+        };
+    }
+}
+exports.FunctionalReturnAnalyzer = FunctionalReturnAnalyzer;
+// ═══════════════════════════════════════════════════════════════════
+// Private helpers
+// ═══════════════════════════════════════════════════════════════════
+function findVarDeclInFile(sourceFile, varName, beforeLine) {
+    const text = sourceFile.getFullText();
+    const lines = text.split("\n");
+    let beforeOffset = 0;
+    for (let i = 0; i < Math.min(beforeLine - 1, lines.length); i++) {
+        beforeOffset += lines[i].length + 1;
+    }
+    let best = null;
+    let bestOffset = -1;
+    for (const decl of sourceFile.getDescendantsOfKind(ts_morph_1.SyntaxKind.VariableDeclaration)) {
+        if (decl.getName() !== varName)
+            continue;
+        const offset = decl.getStart();
+        if (offset < beforeOffset && offset > bestOffset) {
+            best = decl;
+            bestOffset = offset;
+        }
+    }
+    return best;
+}
+function findImportedSymbol(sourceFile, symbolName) {
+    for (const importDecl of sourceFile.getImportDeclarations()) {
+        const modulePath = importDecl.getModuleSpecifierValue();
+        // Default import: import Foo from '...'
+        const defaultImport = importDecl.getDefaultImport();
+        if (defaultImport?.getText() === symbolName) {
+            return { modulePath, symbolName };
+        }
+        // Named imports: import { Foo, Bar as B } from '...'
+        for (const named of importDecl.getNamedImports()) {
+            const localName = named.getAliasNode()?.getText() ?? named.getName();
+            if (localName === symbolName) {
+                return { modulePath, symbolName: named.getName() };
+            }
+        }
+        // Namespace import: import * as NS from '...'
+        const nsImport = importDecl.getNamespaceImport();
+        if (nsImport?.getText() === symbolName) {
+            return { modulePath, symbolName };
+        }
+    }
+    return null;
+}
+function findFunctionBody(sourceFile, fnName) {
+    // 1. FunctionDeclaration: function getScopedInput(...) { ... }
+    const fnDecl = sourceFile.getFunction(fnName);
+    if (fnDecl) {
+        const params = fnDecl.getParameters().map((p) => p.getName());
+        const body = fnDecl.getBody();
+        if (!body)
+            return null;
+        const returnExpr = extractReturnExpression(body);
+        if (!returnExpr)
+            return null;
+        return { returnExpr, params, line: fnDecl.getStartLineNumber() };
+    }
+    // 2. const fnName = (...) => expr  or  const fnName = function(...) { ... }
+    for (const decl of sourceFile.getDescendantsOfKind(ts_morph_1.SyntaxKind.VariableDeclaration)) {
+        if (decl.getName() !== fnName)
+            continue;
+        const init = decl.getInitializer();
+        if (!init)
+            continue;
+        if (ts_morph_1.Node.isArrowFunction(init)) {
+            const arrow = init;
+            const params = arrow.getParameters().map((p) => p.getName());
+            const body = arrow.getBody();
+            // Concise body: (role) => `...`  - body IS the return expression.
+            if (!ts_morph_1.Node.isBlock(body)) {
+                return { returnExpr: body, params, line: decl.getStartLineNumber() };
+            }
+            const returnExpr = extractReturnExpression(body);
+            if (!returnExpr)
+                return null;
+            return { returnExpr, params, line: decl.getStartLineNumber() };
+        }
+        if (ts_morph_1.Node.isFunctionExpression(init)) {
+            const fnExpr = init;
+            const params = fnExpr.getParameters().map((p) => p.getName());
+            const body = fnExpr.getBody();
+            const returnExpr = extractReturnExpression(body);
+            if (!returnExpr)
+                return null;
+            return { returnExpr, params, line: decl.getStartLineNumber() };
+        }
+    }
+    return null;
+}
+function extractReturnExpression(body) {
+    // Concise arrow body - the node itself is the return value.
+    if (!ts_morph_1.Node.isBlock(body))
+        return body;
+    // Block body: search for ReturnStatement.
+    const returnStmts = body.getDescendantsOfKind(ts_morph_1.SyntaxKind.ReturnStatement);
+    if (returnStmts.length === 0)
+        return null;
+    // Use the first one - for conditional returns we signal COMPLEX upstream.
+    return returnStmts[0].getExpression() ?? null;
+}

package/dist/services/DnaEditorService.d.ts

@@ -0,0 +1,31 @@
+import type { ElementSnapshotV2 } from "../types/index.js";
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+export interface DnaSnapshotExtended extends ElementSnapshotV2 {
+    selector: string;
+    testTitle?: string;
+    sourceFile?: string;
+    sourceLine?: number;
+    lastHealed?: string | null;
+    status?: "healed" | "broken";
+    originalSelector?: string;
+    healedSelector?: string;
+}
+export type DnaPatch = Partial<DnaSnapshotExtended>;
+export interface IDnaEditorService {
+    read(key: string): Promise<DnaSnapshotExtended>;
+    write(key: string, patch: DnaPatch): Promise<string>;
+    rollback(key: string): Promise<void>;
+    validate(candidate: unknown): ValidationResult;
+}
+export declare class DnaEditorService implements IDnaEditorService {
+    private readonly snapshotDir;
+    constructor(snapshotDir: string);
+    read(key: string): Promise<DnaSnapshotExtended>;
+    write(key: string, patch: DnaPatch): Promise<string>;
+    rollback(key: string): Promise<void>;
+    validate(candidate: unknown): ValidationResult;
+}
+//# sourceMappingURL=DnaEditorService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"DnaEditorService.d.ts","sourceRoot":"","sources":["../../src/services/DnaEditorService.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAID,MAAM,WAAW,mBAAoB,SAAQ,iBAAiB;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC7B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAEpD,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAChD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,OAAO,GAAG,gBAAgB,CAAC;CAChD;AA6BD,qBAAa,gBAAiB,YAAW,iBAAiB;IAC5C,OAAO,CAAC,QAAQ,CAAC,WAAW;gBAAX,WAAW,EAAE,MAAM;IAE1C,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAgB/C,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC;IA2CpD,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAa1C,QAAQ,CAAC,SAAS,EAAE,OAAO,GAAG,gBAAgB;CA4H/C"}

package/dist/services/DnaEditorService.js

@@ -0,0 +1,217 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DnaEditorService = void 0;
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+function jsonPath(dir, key) {
+    return path_1.default.join(dir, `${key}.json`);
+}
+function tmpPath(dir, key) {
+    return path_1.default.join(dir, `${key}.json.tmp`);
+}
+function bakPath(dir, key) {
+    return path_1.default.join(dir, `${key}.json.bak`);
+}
+// Derive a best-effort selector from engine snapshot fields when none is stored.
+function deriveSelector(snap) {
+    const id = snap["id"];
+    const classes = snap["classes"];
+    const tagName = snap["tagName"];
+    if (typeof id === "string" && id)
+        return `#${id}`;
+    if (Array.isArray(classes) && classes.length > 0)
+        return `.${classes.join(".")}`;
+    return typeof tagName === "string" ? tagName : "unknown";
+}
+function dnaError(message, code) {
+    const err = new Error(message);
+    err.code = code;
+    return err;
+}
+class DnaEditorService {
+    snapshotDir;
+    constructor(snapshotDir) {
+        this.snapshotDir = snapshotDir;
+    }
+    async read(key) {
+        const target = jsonPath(this.snapshotDir, key);
+        let raw;
+        try {
+            raw = await promises_1.default.readFile(target, "utf-8");
+        }
+        catch {
+            throw dnaError(`DNA not found: ${key}`, "DNA_NOT_FOUND");
+        }
+        const parsed = JSON.parse(raw);
+        // Promote to extended format if selector not stored
+        if (!parsed["selector"]) {
+            parsed["selector"] = deriveSelector(parsed);
+        }
+        return parsed;
+    }
+    async write(key, patch) {
+        const target = jsonPath(this.snapshotDir, key);
+        const bak = bakPath(this.snapshotDir, key);
+        const tmp = tmpPath(this.snapshotDir, key);
+        // 1. Read existing snapshot
+        const original = await this.read(key);
+        // 2. Shallow-merge patch (arrays and objects replaced, not deep-merged)
+        const merged = {
+            ...original,
+            ...patch,
+        };
+        // Any CLI write = human has reviewed the DNA → clear auto-heal status flag.
+        delete merged["status"];
+        // 3. Derive selector only when absent - never override an explicit (possibly invalid) value
+        if (merged["selector"] == null) {
+            merged["selector"] = deriveSelector(merged);
+        }
+        // 4. Validate before touching disk
+        const validation = this.validate(merged);
+        if (!validation.valid) {
+            throw dnaError(`Validation failed for ${key}: ${validation.errors.join("; ")}`, "VALIDATION_FAILED");
+        }
+        // 5. Backup current file (overwrite previous bak)
+        await promises_1.default.writeFile(bak, JSON.stringify(original, null, 2), "utf-8");
+        // 6. Write to tmp
+        await promises_1.default.writeFile(tmp, JSON.stringify(merged, null, 2), "utf-8");
+        // 7. Atomic rename tmp → json
+        await promises_1.default.rename(tmp, target);
+        return bak;
+    }
+    async rollback(key) {
+        const target = jsonPath(this.snapshotDir, key);
+        const bak = bakPath(this.snapshotDir, key);
+        try {
+            await promises_1.default.access(bak);
+        }
+        catch {
+            throw dnaError(`No backup found for: ${key}`, "DNA_NOT_FOUND");
+        }
+        await promises_1.default.rename(bak, target);
+    }
+    validate(candidate) {
+        const errors = [];
+        if (typeof candidate !== "object" ||
+            candidate === null ||
+            Array.isArray(candidate)) {
+            return { valid: false, errors: ["candidate must be a plain object"] };
+        }
+        const snap = candidate;
+        // ── Required top-level fields ─────────────────────────────────────────────
+        for (const field of [
+            "tagName",
+            "selector",
+            "schemaVersion",
+            "timestamp",
+        ]) {
+            if (!(field in snap) || snap[field] === undefined) {
+                errors.push(`Missing required field: ${field}`);
+            }
+        }
+        if (snap["schemaVersion"] !== 2) {
+            errors.push(`schemaVersion must be 2, got ${String(snap["schemaVersion"])}`);
+        }
+        // ── selector ─────────────────────────────────────────────────────────────
+        const sel = snap["selector"];
+        if (typeof sel === "string") {
+            if (sel.trim() === "")
+                errors.push("selector must not be empty");
+            if (sel === "undefined")
+                errors.push('selector must not be the string "undefined"');
+            if (/[\r\n]/.test(sel))
+                errors.push("selector must not contain raw newlines");
+        }
+        else if ("selector" in snap) {
+            errors.push("selector must be a string");
+        }
+        // ── tagName ───────────────────────────────────────────────────────────────
+        const tag = snap["tagName"];
+        if (typeof tag === "string") {
+            if (!/^[a-z][a-z0-9-]*$/.test(tag)) {
+                errors.push("tagName must match /^[a-z][a-z0-9-]*$/");
+            }
+        }
+        else if ("tagName" in snap) {
+            errors.push("tagName must be a string");
+        }
+        // ── text ─────────────────────────────────────────────────────────────────
+        const text = snap["text"];
+        if (text !== null && text !== undefined) {
+            if (typeof text !== "string") {
+                errors.push("text must be a string or null");
+            }
+            else if (text.length >= 2000) {
+                errors.push("text must be fewer than 2000 characters");
+            }
+        }
+        // ── attributes ───────────────────────────────────────────────────────────
+        const attrs = snap["attributes"];
+        if (attrs !== undefined) {
+            if (typeof attrs !== "object" || attrs === null || Array.isArray(attrs)) {
+                errors.push("attributes must be a plain object");
+            }
+            else {
+                for (const [k, v] of Object.entries(attrs)) {
+                    if (!k)
+                        errors.push("attributes keys must not be empty");
+                    if (typeof v !== "string")
+                        errors.push(`attributes["${k}"] must be a string`);
+                }
+            }
+        }
+        // ── visibility (all 4 keys required) ─────────────────────────────────────
+        const vis = snap["visibility"];
+        if (typeof vis === "object" && vis !== null && !Array.isArray(vis)) {
+            const visObj = vis;
+            for (const key of [
+                "isGhost",
+                "ghostReason",
+                "isOccluded",
+                "opacity",
+            ]) {
+                if (!(key in visObj))
+                    errors.push(`visibility.${key} is required`);
+            }
+        }
+        else {
+            errors.push("visibility block is required and must be an object");
+        }
+        // ── anchors (all 3 keys required) ────────────────────────────────────────
+        const anch = snap["anchors"];
+        if (typeof anch === "object" && anch !== null && !Array.isArray(anch)) {
+            const anchObj = anch;
+            for (const key of [
+                "closestLabel",
+                "rowAnchor",
+                "neighborTexts",
+            ]) {
+                if (!(key in anchObj))
+                    errors.push(`anchors.${key} is required`);
+            }
+            const cl = anchObj["closestLabel"];
+            if (cl !== null && typeof cl !== "string") {
+                errors.push("anchors.closestLabel must be a string or null");
+            }
+            const nt = anchObj["neighborTexts"];
+            if (!Array.isArray(nt)) {
+                errors.push("anchors.neighborTexts must be an array");
+            }
+            else {
+                if (nt.length > 10)
+                    errors.push("anchors.neighborTexts must have at most 10 elements");
+                if (!nt.every((x) => typeof x === "string")) {
+                    errors.push("anchors.neighborTexts elements must all be strings");
+                }
+            }
+        }
+        else {
+            errors.push("anchors block is required and must be an object");
+        }
+        return { valid: errors.length === 0, errors };
+    }
+}
+exports.DnaEditorService = DnaEditorService;

package/dist/services/DnaIndexService.d.ts

@@ -0,0 +1,24 @@
+import type { DnaRecord, DnaIndex } from "./types.js";
+export interface IDnaIndexService {
+    buildIndex(snapshotDir: string): Promise<DnaIndex>;
+    findBySelector(pattern: string): DnaRecord[];
+    findByText(pattern: string): DnaRecord[];
+    findBySourceFile(filePath: string): DnaRecord[];
+    findByTestTitle(pattern: string): DnaRecord[];
+    getByKey(key: string): DnaRecord | null;
+    getIndex(): DnaIndex;
+    refresh(): void;
+}
+export declare class DnaIndexService implements IDnaIndexService {
+    private cachedIndex;
+    buildIndex(snapshotDir: string): Promise<DnaIndex>;
+    findBySelector(pattern: string): DnaRecord[];
+    findByText(pattern: string): DnaRecord[];
+    findBySourceFile(filePath: string): DnaRecord[];
+    findByTestTitle(pattern: string): DnaRecord[];
+    getByKey(key: string): DnaRecord | null;
+    getIndex(): DnaIndex;
+    refresh(): void;
+    private requireIndex;
+}
+//# sourceMappingURL=DnaIndexService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"DnaIndexService.d.ts","sourceRoot":"","sources":["../../src/services/DnaIndexService.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAatD,MAAM,WAAW,gBAAgB;IAC/B,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnD,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,CAAC;IAC7C,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,CAAC;IACzC,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,CAAC;IAChD,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,CAAC;IAC9C,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;IACxC,QAAQ,IAAI,QAAQ,CAAC;IACrB,OAAO,IAAI,IAAI,CAAC;CACjB;AAkED,qBAAa,eAAgB,YAAW,gBAAgB;IACtD,OAAO,CAAC,WAAW,CAAyB;IAEtC,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAoCxD,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE;IAK5C,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE;IAOxC,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE;IAO/C,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE;IAK7C,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAIvC,QAAQ,IAAI,QAAQ;IAIpB,OAAO,IAAI,IAAI;IAIf,OAAO,CAAC,YAAY;CAQrB"}