@kkeve/suite 0.0.15 → 0.0.18

package/dist/core/page-object/elementResolver.js

@@ -0,0 +1,236 @@
+"use strict";
+/**
+ * elementResolver — 将 ElementRef 解析为 Playwright Locator
+ *
+ * 支持单元素解析和多级嵌套链式解析（resolveChain）。
+ * 引擎无关层：仅依赖 Playwright Locator API。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveElement = resolveElement;
+exports.resolveChain = resolveChain;
+exports.resolveFromPage = resolveFromPage;
+const definePage_js_1 = require("./definePage.js");
+// ─── Platform Hop Resolution (keve-wiki chain) ────────────────────────
+/** class/shadow-dom hop value → css（支持空格分隔多 class，容忍 value 自带前导点） */
+function classToCss(v) {
+    return String(v).trim().split(/\s+/).map((c) => `.${c.replace(/^\.+/, '')}`).join('');
+}
+/** hop → css 片段：selector 原样；id 补 #；shadow-dom 宿主按 class 定位（Playwright css 自动穿透 open shadow root） */
+function hopToCss(t, v) {
+    if (t === 'selector')
+        return v;
+    if (t === 'id')
+        return `#${v.replace(/^#/, '')}`;
+    if (t === 'shadow-dom')
+        return /^[.#[]/.test(v) ? v : classToCss(v);
+    return classToCss(v);
+}
+/**
+ * 平台定位链解析：按 hop 序列逐级收窄
+ *
+ * - selector → locator(css)
+ * - class    → locator('.a.b')
+ * - includes/text → locator('text=...')（在当前范围内找包含该文本的元素）
+ * - label    → getByLabel（表单控件按可见标签定位，平台 label hop 37 处）
+ * - iframe-url    → frameLocator（进入 iframe 上下文，src 部分匹配）
+ * - javascript/source → 跳过（javascript 仅 WRITE_GLOBAL 场景由 engine.evaluate 处理）
+ *
+ * hop.index：1-based，-1/缺省表示不取序号。取序号时用 .nth(index-1) —— 平台侧
+ * 91 处带 index 的跳，此前被整体忽略，导致命中第一个元素而非期望的第 N 个。
+ */
+function applyHops(page, scope, hops) {
+    let cur = scope;
+    let lastHop = null;
+    for (const hop of hops) {
+        const t = String(hop?.type || '');
+        const v = hop?.value;
+        if (t === 'javascript' || t === 'source' || t === '')
+            continue;
+        if (t === 'iframe-url') {
+            const css = `iframe[src*="${String(v).replace(/"/g, '\\"')}"]`;
+            cur = cur.frameLocator(css);
+            lastHop = null; // iframe 本身不产生最终定位，重置
+            continue;
+        }
+        if (t === 'selector' || t === 'id' || t === 'shadow-dom') {
+            cur = cur.locator(hopToCss(t, String(v)));
+        }
+        else if (t === 'class') {
+            cur = cur.locator(classToCss(String(v)));
+        }
+        else if (t === 'includes' || t === 'text') {
+            const text = String(v).trim();
+            // 「包含文本」语义：用 text= 引擎匹配「包含该文本的最小元素」。
+            // 老实现 locator('*').filter({ hasText }) 只搜后代 —— 当文本是当前元素的
+            // 直接文本节点（如 .tab-text「我创建的」）时后代为空，链路永久落空（点击等到超时）。
+            // text= 引擎对「自身直挂文本」与「文本在后代元素」两类 DOM 都命中，
+            // 且与老行为（点中文本所在叶子）兼容。
+            cur = cur.locator('text=' + text.replace(/\\/g, '\\\\').replace(/"/g, '\\"'));
+        }
+        else if (t === 'label') {
+            // 表单控件按可见标签定位（平台 label hop）。Playwright getByLabel 在
+            // Locator/FrameLocator 上同样可用，语义与「找 label 文本对应的输入控件」一致。
+            const label = String(v).trim();
+            cur = cur.getByLabel(label, { exact: false });
+        }
+        else {
+            throw new Error(`Unknown hop type '${t}' in chain: ${JSON.stringify(hop)}`);
+        }
+        // 序号收敛：1-based → .nth(index-1)；-1 / 0 / 非数字表示不取序号
+        const idx = Number(hop?.index);
+        if (Number.isFinite(idx) && idx > 0 && typeof cur?.nth === 'function') {
+            cur = cur.nth(idx - 1);
+        }
+        lastHop = { type: t, value: v };
+    }
+    // iframe 进入后无后续定位跳：兜底取 frame 的 body
+    if (!lastHop && hops.some((h) => String(h?.type || '') === 'iframe-url')) {
+        cur = cur.locator('body');
+    }
+    if (!cur || typeof cur.locator !== 'function') {
+        throw new Error(`Chain resolution produced a non-Locator: ${JSON.stringify(hops).slice(0, 200)}`);
+    }
+    return cur;
+}
+// ─── Single Element Resolution ────────────────────────────────────────
+/**
+ * 将单个 ElementRef 解析为 Playwright Locator
+ *
+ * 优先级：ref > role+name > css
+ * 复合定位：hasText, has, notHas 在基础定位上叠加
+ */
+function resolveElement(page, ref) {
+    // 平台多跳定位链优先（keve-wiki 导出代码的原生形态）
+    if (ref.chain && ref.chain.length > 0) {
+        return applyHops(page, page, ref.chain);
+    }
+    let locator;
+    if (ref.ref) {
+        // AI 探索临时 ref（Playwright MCP 风格的 a11y ref）
+        // 实际实现中需要通过 ariaSnapshot 映射，这里用 css 兜底
+        locator = page.locator(`[data-ref="${ref.ref}"]`);
+    }
+    else if (ref.role) {
+        // role + name 语义定位
+        if (ref.name) {
+            locator = page.getByRole(ref.role, { name: ref.name, exact: false });
+        }
+        else {
+            locator = page.getByRole(ref.role);
+        }
+    }
+    else if (ref.css) {
+        locator = page.locator(ref.css);
+    }
+    else {
+        throw new Error(`Invalid ElementRef: must have role, css, or ref. Got: ${JSON.stringify(ref)}`);
+    }
+    // 复合定位：hasText
+    if (ref.hasText) {
+        locator = locator.filter({ hasText: ref.hasText });
+    }
+    // 复合定位：has（包含子元素）
+    if (ref.has) {
+        const childLocator = resolveElement(page, ref.has);
+        locator = locator.filter({ has: childLocator });
+    }
+    // 复合定位：notHas（不包含子元素）
+    if (ref.notHas) {
+        const childLocator = resolveElement(page, ref.notHas);
+        locator = locator.filter({ hasNot: childLocator });
+    }
+    return locator;
+}
+// ─── Chain Resolution (Multi-level Nesting) ──────────────────────────
+/**
+ * 多级嵌套解析：按顺序在父元素范围内查找子元素
+ *
+ * resolveChain(page, parent, child)           → parent.locator(child)
+ * resolveChain(page, a, b, c, d)             → a.locator(b).locator(c).locator(d)
+ *
+ * 支持 ElementRef 和 ElementEntry（工厂函数需先调用）
+ */
+function resolveChain(page, ...refs) {
+    if (refs.length === 0) {
+        throw new Error('resolveChain requires at least one element ref');
+    }
+    // 将所有 entry 规范化为 ElementRef
+    const elements = refs.map((entry, _idx) => {
+        if ((0, definePage_js_1.isElementFactory)(entry)) {
+            throw new Error('Cannot use factory function in chain without calling it first. Call factory(item) before passing to resolveChain.');
+        }
+        return entry;
+    });
+    // 第一个元素：从 page 级定位
+    let locator = resolveElement(page, elements[0]);
+    // 后续元素：在父 locator 范围内定位
+    for (let i = 1; i < elements.length; i++) {
+        const childRef = elements[i];
+        // 平台多跳定位链：在当前范围内继续 hop 解析
+        if (childRef.chain && childRef.chain.length > 0) {
+            locator = applyHops(page, locator, childRef.chain);
+            continue;
+        }
+        // 子元素如果只有 hasText，用 filter；否则用 locator 链
+        if (childRef.hasText && !childRef.role && !childRef.css && !childRef.ref) {
+            locator = locator.filter({ hasText: childRef.hasText });
+        }
+        else if (childRef.role) {
+            if (childRef.name) {
+                locator = locator.getByRole(childRef.role, { name: childRef.name, exact: false });
+            }
+            else {
+                locator = locator.getByRole(childRef.role);
+            }
+        }
+        else if (childRef.css) {
+            locator = locator.locator(childRef.css);
+        }
+        else if (childRef.ref) {
+            locator = locator.locator(`[data-ref="${childRef.ref}"]`);
+        }
+        else {
+            throw new Error(`Invalid chain element at position ${i}: ${JSON.stringify(childRef)}`);
+        }
+        // 复合定位叠加
+        if (childRef.hasText && (childRef.role || childRef.css || childRef.ref)) {
+            locator = locator.filter({ hasText: childRef.hasText });
+        }
+        if (childRef.has) {
+            locator = locator.filter({ has: resolveElement(page, childRef.has) });
+        }
+        if (childRef.notHas) {
+            locator = locator.filter({ hasNot: resolveElement(page, childRef.notHas) });
+        }
+    }
+    return locator;
+}
+// ─── Convenience: Resolve from Page definition ────────────────────────
+/**
+ * 从 DefinedPage 中解析元素（自动处理工厂函数）
+ *
+ * resolveFromPage(page, 'saveButton')                                  → Locator
+ * resolveFromPage(page, 'itemByName', '时间')                           → Locator（工厂调用）
+ * resolveFromPage(page, 'dimensionList', ['itemByName', '时间'])       → 链式解析
+ */
+function resolveFromPage(pwPage, defPage, ...keys) {
+    const refs = [];
+    for (const key of keys) {
+        if (typeof key === 'string') {
+            const entry = defPage.elements[key];
+            if ((0, definePage_js_1.isElementFactory)(entry)) {
+                throw new Error(`Element '${key}' is a factory, needs args. Use [key, ...args] tuple.`);
+            }
+            refs.push(entry);
+        }
+        else if (Array.isArray(key)) {
+            const [k, ...args] = key;
+            const entry = defPage.elements[k];
+            if (!(0, definePage_js_1.isElementFactory)(entry)) {
+                throw new Error(`Element '${k}' is not a factory, but args were provided.`);
+            }
+            refs.push(entry(...args));
+        }
+    }
+    return resolveChain(pwPage, ...refs);
+}

package/dist/core/page-object/engine-types.d.ts

@@ -0,0 +1,140 @@
+/**
+ * engine-types — EngineAdapter 契约（零依赖，浏览器安全）
+ *
+ * 所有测试脚本通过 `engine.*` 调用操作，不直接使用 page.locator / cy.get。
+ * 契约单独成文件的原因：Cypress 侧要在浏览器里 import 它，而
+ * engineAdapter.ts 里躺着 PlaywrightEngine —— 只要 Cypress 入口碰到那个模块，
+ * esbuild 就会把 playwright-core → node:fs 整条链拉进浏览器 bundle 而构建失败。
+ *
+ * 约束：本模块只允许 `import type`，不得引入任何运行时依赖。
+ */
+import type { ElementRef, ElementEntry, DefinedPage } from './definePage.js';
+import type { ExpectScreenshotOptions, ShotDiffResult } from '../judge/screenshotDiff.js';
+/** waitForResponse 选项：就绪门语义（软等待 = 超时不阻塞，与 waitForReady.api 一致） */
+export interface WaitForResponseOptions {
+    /** 等待超时（默认 15000ms） */
+    timeout?: number;
+    /** 匹配的 HTTP 方法（如 'POST'；不传则不限） */
+    method?: string;
+    /** 期望的 HTTP 状态码列表（如 [200]；不传则不限）。给定时不匹配则继续等 */
+    status?: number[];
+    /** 超时是否视为失败。默认 false（软等待：打日志继续），true 则抛错（硬门） */
+    required?: boolean;
+    /** 命中后额外等待，给前端渲染留时间（默认 0） */
+    afterMs?: number;
+}
+/** waitForResponse 结果：命中的响应摘要；软等待超时时 hit=false */
+export interface WaitForResponseResult {
+    hit: boolean;
+    url: string;
+    status: number;
+    /** 响应体（JSON 可解析时为对象，否则为文本；体过大或非文本为 null） */
+    body: any;
+    elapsedMs: number;
+}
+export interface EngineAdapter {
+    /** 导航到 URL */
+    navigate(url: string): Promise<void>;
+    /** 打开 PageObject 页面入口：按 KEVE_ENV 解析四环境 URL 并填充 ${param} 占位（overrides 优先于 page.url.params） */
+    openPage(page: DefinedPage, overrides?: Record<string, string>): Promise<void>;
+    /** 调用其他场景（用例组合原语）：按 @keveScene 注册的 id 查找并执行其方法体，无需 spec 互相 import */
+    callScene(sceneId: string, keveGoal?: unknown): Promise<void>;
+    /** 等待页面就绪（API + UI 信号） */
+    waitForReady(page: DefinedPage): Promise<void>;
+    /** 等待指定响应（就绪门，平台 WAIT_RESPONSE 转译落地用）。
+     *  配置型场景没有 DefinedPage，只能按 URL 片段/正则等待 —— 语义与 waitForReady.api 一致 */
+    waitForResponse(urlPart: string | RegExp, opts?: WaitForResponseOptions): Promise<WaitForResponseResult>;
+    /** 点击元素 */
+    click(...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    /** 双击元素（平台 DB_CLICK_ELEMENT） */
+    dblClick(...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    /** 强制点击元素（平台 FORCE_CLICK_ELEMENT，跳过 actionability 检查） */
+    forceClick(...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    /** 输入文本 */
+    type(text: string, ...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    /** 清空输入内容（平台 CLEAN） */
+    clear(...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    /** 悬停元素 */
+    hover(...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    /** 拖拽元素到目标（平台 DRAGGING：source 拖到 target） */
+    drag(source: ElementRef | ElementEntry, target: ElementRef | ElementEntry): Promise<void>;
+    /** 滚动使元素进入视口（平台 SCROLL） */
+    scroll(...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    /** 等待指定毫秒（平台 WAIT_EVENTS） */
+    wait(ms: number): Promise<void>;
+    /** 等待元素就绪（平台元素门的真检测：按 selector 等 visible/hidden，超时返回 found=false 不抛错；
+     *  替代「固定延时兜底」——只有元素真的就绪才算就绪，防丢响应/防假就绪） */
+    waitForElement(selector: string, opts?: {
+        timeout?: number;
+        visible?: boolean;
+    }): Promise<{
+        found: boolean;
+    }>;
+    /** 刷新页面（平台 REFRESH_PAGE） */
+    refresh(): Promise<void>;
+    /** 在页面上下文执行 JS 表达式（平台 WRITE_GLOBAL 的 javascript hop） */
+    evaluate(expression: string): Promise<any>;
+    /** 截图并附加到测试报告（平台 SCREEN_SHOT_COMPARE）。⚠ 语义已升级为基线对比断言：
+     *  无基线 → 自动建候选基线（pass）；差异率超阈值 → 抛 ScreenshotDiffError（确定性 fail）；
+     *  对比结果（差异率/区块/证据图路径）进 keveGoalResult attachment（screenshotDiff 字段） */
+    screenshot(name: string, ...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    /** 截图基线对比断言（expectScreenshot 的显式形态，支持阈值/掩码/全页选项） */
+    expectScreenshot(key: string, opts?: ExpectScreenshotOptions, ...refs: (ElementRef | ElementEntry)[]): Promise<ShotDiffResult>;
+    /** 获取元素文本 */
+    text(...refs: (ElementRef | ElementEntry)[]): Promise<string>;
+    /** 断言：元素可见 */
+    expectVisible(...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    /** 断言：元素不可见 */
+    expectHidden(...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    /** 断言：元素文本包含 */
+    expectText(expected: string, ...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    /** 断言：元素文本不包含（平台 TEXT_NOT_EXIST） */
+    expectNotText(expected: string, ...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    /** 断言：元素文本等于（平台 TEXT_EQUAL / EXPECTED_VALUE ctype=text cexpression=eq） */
+    expectTextEquals(expected: string, ...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    /** 断言：元素文本不等于（平台 EXPECTED_VALUE ctype=text cexpression=not.eq） */
+    expectTextNotEquals(expected: string, ...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    /** 断言：元素数量 */
+    expectCount(count: number, ...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    /** 断言：元素集合中「文本非空」的个数（平台 EXPECTED_VALUE ctype=index，历史语义为计数） */
+    expectNonEmptyCount(count: number, ...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    /** 断言：元素存在 */
+    expectExists(...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    /** 断言：元素不存在 */
+    expectNotExists(...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    /** 断言：元素包含指定 class */
+    expectClass(className: string, ...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    /** 断言：元素不包含指定 class（平台 EXPECTED_VALUE ctype=class cexpression=not.include） */
+    expectNotClass(className: string, ...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    /** 断言：元素属性值 */
+    expectAttribute(attr: string, value: string, ...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    /** 断言：元素属性值包含（平台 EXPECTED_VALUE ctype=style cexpression=include） */
+    expectAttributeContains(attr: string, value: string, ...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    /** 断言：当前 URL 包含指定片段（平台 EXPECTED__PAGET_VALUE ctype=url） */
+    expectUrlContains(part: string): Promise<void>;
+    /** 断言：当前 URL 不包含指定片段 */
+    expectUrlNotContains(part: string): Promise<void>;
+    /** 断言：当前 URL 等于（平台 EXPECTED__PAGET_VALUE ctype=url cexpression=eq） */
+    expectUrlEquals(url: string): Promise<void>;
+    /** 断言：当前 URL 不等于 */
+    expectUrlNotEquals(url: string): Promise<void>;
+    /** 断言：页面标题包含（平台 EXPECTED__PAGET_VALUE ctype=title cexpression=include） */
+    expectTitle(part: string): Promise<void>;
+    /** 断言：页面标题等于 */
+    expectTitleEquals(title: string): Promise<void>;
+    /** 获取底层引擎 page（仅探索场景使用；Cypress 下返回 CDP driver，无 Playwright Page） */
+    rawPage(): any;
+    /** aria snapshot（AI 探索用） */
+    ariaSnapshot(options?: {
+        mode?: string;
+    }): Promise<string>;
+    /** 注入 cookies 到当前浏览器上下文（登录态透传） */
+    injectCookies(cookies: any[]): Promise<void>;
+}
+/** 当前执行环境（调度层 KEVE_ENV 注入；与 keve-wiki test-data.ts 同源同序） */
+export declare const KEVE_ENV: string;
+/**
+ * 解析 PageObject 入口 URL：KEVE_ENV 环境值 → ${param} 占位填充（overrides 优先于默认 params）
+ * 环境值非法（非 http，如平台脏数据 "1"）时回退 test → online → 任意 http 值
+ */
+export declare function resolvePageUrl(page: DefinedPage, overrides?: Record<string, string>): string;

package/dist/core/page-object/engine-types.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * engine-types — EngineAdapter 契约（零依赖，浏览器安全）
+ *
+ * 所有测试脚本通过 `engine.*` 调用操作，不直接使用 page.locator / cy.get。
+ * 契约单独成文件的原因：Cypress 侧要在浏览器里 import 它，而
+ * engineAdapter.ts 里躺着 PlaywrightEngine —— 只要 Cypress 入口碰到那个模块，
+ * esbuild 就会把 playwright-core → node:fs 整条链拉进浏览器 bundle 而构建失败。
+ *
+ * 约束：本模块只允许 `import type`，不得引入任何运行时依赖。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KEVE_ENV = void 0;
+exports.resolvePageUrl = resolvePageUrl;
+/** 当前执行环境（调度层 KEVE_ENV 注入；与 keve-wiki test-data.ts 同源同序） */
+exports.KEVE_ENV = (['online', 'pre', 'rc', 'test'].includes(process.env.KEVE_ENV || '') ? process.env.KEVE_ENV : 'test');
+/**
+ * 解析 PageObject 入口 URL：KEVE_ENV 环境值 → ${param} 占位填充（overrides 优先于默认 params）
+ * 环境值非法（非 http，如平台脏数据 "1"）时回退 test → online → 任意 http 值
+ */
+function resolvePageUrl(page, overrides) {
+    const u = page.url;
+    if (!u)
+        throw new Error(`openPage: 页面 ${page.__pageId} 未定义 url 入口`);
+    const candidates = [u[String(exports.KEVE_ENV)], u.test, u.online, ...Object.values(u)].filter((v) => typeof v === 'string' && /^https?:\/\//.test(v));
+    let url = String(candidates[0] || '');
+    if (!url)
+        throw new Error(`openPage: 页面 ${page.__pageId} 的 url 无有效 http 值: ${JSON.stringify(u)}`);
+    const params = { ...(u.params || {}), ...(overrides || {}) };
+    for (const [k, v] of Object.entries(params)) {
+        url = url.split('${' + k + '}').join(encodeURIComponent(String(v)));
+    }
+    return url.replace(/\$\{\w+\}/g, ''); // 未覆盖的占位符清空（保底不把 ${x} 发给服务端）
+}

package/dist/core/sso-cookie.d.ts

@@ -0,0 +1,18 @@
+/**
+ * SSO Cookie 类型定义（仅类型，不做登录/缓存）
+ *
+ * SSO 登录态的唯一缓存与登录入口都在 eve-backend
+ * （src/services/ai/sso-cookies.ts，Redis key sso:{username}）。
+ * suite 侧只负责接收服务端下发的 cookie 并注入浏览器，不再持有任何
+ * Redis/进程内缓存，避免多套缓存各自过期、互相覆盖造成「坏登录态被复用」。
+ */
+export interface SsoCookie {
+    name: string;
+    value: string;
+    domain: string;
+    path: string;
+    secure: boolean;
+    httpOnly?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+    expires?: number;
+}

package/dist/core/sso-cookie.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * SSO Cookie 类型定义（仅类型，不做登录/缓存）
+ *
+ * SSO 登录态的唯一缓存与登录入口都在 eve-backend
+ * （src/services/ai/sso-cookies.ts，Redis key sso:{username}）。
+ * suite 侧只负责接收服务端下发的 cookie 并注入浏览器，不再持有任何
+ * Redis/进程内缓存，避免多套缓存各自过期、互相覆盖造成「坏登录态被复用」。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/dsl/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * dsl — 平台 DSL ↔ @kkeve/suite 装饰器脚本的双向投影入口
+ *
+ * 本目录保持**零 IO、零框架依赖**，因此可以同时被打进：
+ *   - Playwright 执行产物（@kkeve/suite/keve-test）
+ *   - Cypress 浏览器 bundle（@kkeve/engine-cypress）
+ *   - eve-backend 的生成器 service 层（Node 侧）
+ *
+ * 分层：DB 装载 / 内嵌场景展开 / 元素库 source 跳解析 / 变量表查询全部留在
+ * 调用方（见 eve-backend 的 dslLoader）。这里只做纯函数投影。
+ */
+export { toDecorator, type DslHop, type DslValue, type DslExpectation, type DslStep, type DslVariableRow, type ToDecoratorOptions, } from './toDecorator.js';
+/** 语义别名：调用方按「生成一份装饰器 spec」的语义引用时更直观 */
+export { toDecorator as generateDecoratorSpec } from './toDecorator.js';
+export { STEP_OPERATIONS, ASSERT_OPERATIONS, TEXT_ONLY_ASSERT_OPERATIONS, EXPECTED_VALUE_CTYPES, COMPARISON_EXPRESSIONS, isKnownOperation, isKnownAssert, isTextOnlyAssert, parseComparison, type StepOperation, } from './ops.js';

package/dist/dsl/index.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * dsl — 平台 DSL ↔ @kkeve/suite 装饰器脚本的双向投影入口
+ *
+ * 本目录保持**零 IO、零框架依赖**，因此可以同时被打进：
+ *   - Playwright 执行产物（@kkeve/suite/keve-test）
+ *   - Cypress 浏览器 bundle（@kkeve/engine-cypress）
+ *   - eve-backend 的生成器 service 层（Node 侧）
+ *
+ * 分层：DB 装载 / 内嵌场景展开 / 元素库 source 跳解析 / 变量表查询全部留在
+ * 调用方（见 eve-backend 的 dslLoader）。这里只做纯函数投影。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseComparison = exports.isTextOnlyAssert = exports.isKnownAssert = exports.isKnownOperation = exports.COMPARISON_EXPRESSIONS = exports.EXPECTED_VALUE_CTYPES = exports.TEXT_ONLY_ASSERT_OPERATIONS = exports.ASSERT_OPERATIONS = exports.STEP_OPERATIONS = exports.generateDecoratorSpec = exports.toDecorator = void 0;
+var toDecorator_js_1 = require("./toDecorator.js");
+Object.defineProperty(exports, "toDecorator", { enumerable: true, get: function () { return toDecorator_js_1.toDecorator; } });
+/** 语义别名：调用方按「生成一份装饰器 spec」的语义引用时更直观 */
+var toDecorator_js_2 = require("./toDecorator.js");
+Object.defineProperty(exports, "generateDecoratorSpec", { enumerable: true, get: function () { return toDecorator_js_2.toDecorator; } });
+var ops_js_1 = require("./ops.js");
+Object.defineProperty(exports, "STEP_OPERATIONS", { enumerable: true, get: function () { return ops_js_1.STEP_OPERATIONS; } });
+Object.defineProperty(exports, "ASSERT_OPERATIONS", { enumerable: true, get: function () { return ops_js_1.ASSERT_OPERATIONS; } });
+Object.defineProperty(exports, "TEXT_ONLY_ASSERT_OPERATIONS", { enumerable: true, get: function () { return ops_js_1.TEXT_ONLY_ASSERT_OPERATIONS; } });
+Object.defineProperty(exports, "EXPECTED_VALUE_CTYPES", { enumerable: true, get: function () { return ops_js_1.EXPECTED_VALUE_CTYPES; } });
+Object.defineProperty(exports, "COMPARISON_EXPRESSIONS", { enumerable: true, get: function () { return ops_js_1.COMPARISON_EXPRESSIONS; } });
+Object.defineProperty(exports, "isKnownOperation", { enumerable: true, get: function () { return ops_js_1.isKnownOperation; } });
+Object.defineProperty(exports, "isKnownAssert", { enumerable: true, get: function () { return ops_js_1.isKnownAssert; } });
+Object.defineProperty(exports, "isTextOnlyAssert", { enumerable: true, get: function () { return ops_js_1.isTextOnlyAssert; } });
+Object.defineProperty(exports, "parseComparison", { enumerable: true, get: function () { return ops_js_1.parseComparison; } });

package/dist/dsl/locatorSource.d.ts

@@ -0,0 +1,25 @@
+/**
+ * locatorSource — 浏览器侧元素定位（hop 链）源码生成
+ *
+ * Cypress 侧没有 Playwright Locator，元素定位必须在 AUT 的 DOM 里自己实现。
+ * 本模块不直接操作 DOM，只**生成一段可在页面上下文求值的自包含源码字符串**，
+ * 由 engine-cypress 通过 CDP `Runtime.evaluate` 注入一次，之后复用。
+ *
+ * 之所以生成源码而不是导出普通函数：注入 isolate world 的函数无法闭包引用
+ * bundle 里的变量，只能整段作为源码传过去。因此生成物必须零外部引用。
+ *
+ * 语义严格对齐 elementResolver.ts::applyHops —— 同一套 hop 只有一种解释：
+ *   selector/id/shadow-dom → CSS
+ *   class                  → .a.b（空格分隔多 class）
+ *   includes/text          → 文本包含，取「包含该文本的最深（最小）元素」
+ *   label                  → 可见 label 关联的表单控件
+ *   iframe-url             → 同源 iframe 内继续；跨源标记 cross-origin-iframe
+ *   javascript/source/''   → 跳过
+ *   hop.index              → 1-based；-1/0/非数字表示不取序号
+ *
+ * 关键差异（相对 Playwright）：Playwright 的 locator 链是「集合 → 集合」，
+ * 中间不收敛到单元素；只有末端 .first()/.nth(i) 才收敛。这里同样保持
+ * 「集合传递」直到末端，保证 `selector` + `includes` 这类链的结果集正确。
+ */
+/** 生成页内定位器源码（幂等：重复注入只覆盖同名函数，无副作用） */
+export declare function locatorSource(): string;