@kkeve/suite 0.0.13 → 0.0.17

package/dist/dsl/locatorSource.js

@@ -0,0 +1,323 @@
+"use strict";
+/**
+ * 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` 这类链的结果集正确。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.locatorSource = locatorSource;
+/** 生成页内定位器源码（幂等：重复注入只覆盖同名函数，无副作用） */
+function locatorSource() {
+    return `(() => {
+  "use strict";
+  if (window.__keveLocatorSource === "v1") return "cached";
+
+  function classToCss(v) {
+    return String(v).trim().split(/\\s+/).filter(Boolean).map(function (c) {
+      return "." + c.replace(/^\\.+/, "");
+    }).join("");
+  }
+
+  function hopToCss(type, value) {
+    if (type === "selector") return String(value);
+    if (type === "id") return "#" + String(value).replace(/^#/, "");
+    if (type === "shadow-dom") return /^[.#[]/.test(String(value))
+      ? String(value) : classToCss(value);
+    return classToCss(value);
+  }
+
+  function queryAll(root, css) {
+    if (!root || !css) return [];
+    try { return Array.prototype.slice.call(root.querySelectorAll(css)); }
+    catch (e) { return []; }
+  }
+
+  /** 递归收集 open shadow root 内的匹配（对齐 Playwright css 自动穿透 open shadow） */
+  function queryAllDeep(root, css) {
+    var out = queryAll(root, css);
+    var hosts = queryAll(root, "*");
+    for (var i = 0; i < hosts.length; i += 1) {
+      if (hosts[i].shadowRoot) {
+        var inner = queryAllDeep(hosts[i].shadowRoot, css);
+        for (var j = 0; j < inner.length; j += 1) out.push(inner[j]);
+      }
+    }
+    return out;
+  }
+
+  function depthOf(el) {
+    var d = 0, cur = el;
+    while (cur && cur.parentElement) { d += 1; cur = cur.parentElement; }
+    return d;
+  }
+
+  /** label 文本 → 关联控件：label[for] / 控件嵌套于 label / aria-label */
+  function byLabel(root, text) {
+    var needle = String(text).trim();
+    var labels = queryAllDeep(root, "label");
+    for (var i = 0; i < labels.length; i += 1) {
+      var lab = labels[i];
+      if (String(lab.textContent || "").indexOf(needle) < 0) continue;
+      var forId = lab.getAttribute("for");
+      if (forId) {
+        var byId = root.getElementById ? root.getElementById(forId) : null;
+        if (!byId) {
+          var candidates = queryAllDeep(root, "[id]");
+          for (var c = 0; c < candidates.length; c += 1) {
+            if (candidates[c].id === forId) { byId = candidates[c]; break; }
+          }
+        }
+        if (byId) return byId;
+      }
+      var nested = queryAll(lab, "input,textarea,select,button,[role]")[0];
+      if (nested) return nested;
+    }
+    var aria = queryAllDeep(root, "[aria-label]");
+    for (var a = 0; a < aria.length; a += 1) {
+      if (String(aria[a].getAttribute("aria-label") || "").indexOf(needle) >= 0) return aria[a];
+    }
+    return null;
+  }
+
+  /**
+   * 一跳 → 新集合。返回 { els, status }；els 为空表示该跳落空。
+   * index 收敛在这里做（与 Playwright .nth(index-1) 等价）。
+   */
+  /** 在 roots 范围内按 role(+name) 找元素（语义对齐 Playwright getByRole 的子集） */
+  function resolveByRoleIn(roots, role, name) {
+    var pool = [];
+    for (var r = 0; r < roots.length; r += 1) {
+      pool = pool.concat(queryAllDeep(roots[r], "[role],button,a,input,select,textarea,img"));
+    }
+    var want = String(role).toLowerCase();
+    return pool.filter(function (el) {
+      var actual = String(el.getAttribute("role") || implicitRole(el)).toLowerCase();
+      if (actual !== want) return false;
+      if (name == null || name === "") return true;
+      return accessibleName(el).indexOf(String(name)) >= 0;
+    });
+  }
+
+  /** 子定位在 scope 的后代里求值（has / notHas 复合限定用） */
+  function resolveWithin(scope, ref) {
+    var hops = hopsOf(ref);
+    if (!hops.length) return [];
+    return resolveChain(hops, [scope]).els;
+  }
+
+  function applyHop(scopeEls, hop) {
+    var type = String(hop.type || "");
+    var value = hop.value;
+    var idx = Number(hop.index);
+    var useIndex = isFinite(idx) && idx > 0;
+    var picked = [];
+
+    for (var s = 0; s < scopeEls.length; s += 1) {
+      var scope = scopeEls[s];
+      if (type === "includes" || type === "text") {
+        var needle = String(value).trim();
+        if (!needle) continue;
+        var all = queryAllDeep(scope, "*");
+        var hits = [];
+        for (var i = 0; i < all.length; i += 1) {
+          if (String(all[i].textContent || "").indexOf(needle) >= 0) hits.push(all[i]);
+        }
+        if (!hits.length) continue;
+        // 「最小元素」= 命中里最深的一个（与 Playwright text= 命中叶子节点一致）
+        var best = hits[0], bestDepth = depthOf(best);
+        for (var h = 1; h < hits.length; h += 1) {
+          var d = depthOf(hits[h]);
+          if (d > bestDepth) { bestDepth = d; best = hits[h]; }
+        }
+        picked.push(best);
+      } else if (type === "label") {
+        var ctl = byLabel(scope, value);
+        if (!ctl) continue;
+        picked.push(ctl);
+      } else if (type === "role") {
+        var spec = value && typeof value === "object" ? value : { role: value };
+        picked = picked.concat(resolveByRoleIn([scope], spec.role, spec.name));
+      } else if (type === "data-ref") {
+        var refHits = queryAllDeep(scope, "[data-ref]").filter(function (el) {
+          return el.getAttribute("data-ref") === String(value);
+        });
+        picked = picked.concat(refHits);
+      } else if (type === "has-text") {
+        if (String(scope.textContent || "").indexOf(String(value)) >= 0) picked.push(scope);
+      } else if (type === "has-sub") {
+        if (resolveWithin(scope, value).length) picked.push(scope);
+      } else if (type === "not-has-sub") {
+        if (!resolveWithin(scope, value).length) picked.push(scope);
+      } else {
+        picked = picked.concat(queryAllDeep(scope, hopToCss(type, value)));
+      }
+    }
+
+    if (!picked.length) return { els: [], status: "no-match" };
+    if (useIndex) {
+      var one = picked[idx - 1];
+      return one ? { els: [one], status: "ok" } : { els: [], status: "index-out-of-range" };
+    }
+    // 去重（多 scope 可能命中同一元素）
+    var seen = [];
+    for (var p = 0; p < picked.length; p += 1) {
+      if (seen.indexOf(picked[p]) < 0) seen.push(picked[p]);
+    }
+    return { els: seen, status: status };
+  }
+
+  /**
+   * 定位链求值。roots 为起始文档/元素集合。
+   * 返回 { els, status }：els 是「末端匹配集合」（未收敛），
+   * 调用方按需取 .nth / .first。
+   */
+  function resolveChain(hops, roots) {
+    var scopeEls = roots && roots.length ? roots : [document];
+    var list = Array.isArray(hops) ? hops : [];
+    var sawIframe = false;
+
+    for (var i = 0; i < list.length; i += 1) {
+      var hop = list[i] || {};
+      var type = String(hop.type || "");
+      if (type === "javascript" || type === "source" || type === "") continue;
+
+      if (type === "iframe-url") {
+        var frames = [];
+        for (var s = 0; s < scopeEls.length; s += 1) {
+          frames = frames.concat(queryAllDeep(scopeEls[s], "iframe"));
+        }
+        var match = null;
+        for (var f = 0; f < frames.length; f += 1) {
+          if (String(frames[f].getAttribute("src") || "").indexOf(String(hop.value)) >= 0) { match = frames[f]; break; }
+        }
+        if (!match) return { els: [], status: "no-iframe" };
+        var doc = null;
+        try { doc = match.contentDocument; } catch (e) { doc = null; }
+        if (!doc) return { els: [], status: "cross-origin-iframe" };
+        scopeEls = [doc];
+        sawIframe = true;
+        continue;
+      }
+
+      var res = applyHop(scopeEls, hop);
+      if (!res.els.length) return res;
+      scopeEls = res.els;
+    }
+
+    // iframe 进入后无后续定位跳：兜底取 frame 的 body（与 Playwright 实现一致）
+    if (sawIframe && scopeEls.length === 1 && scopeEls[0].nodeType === 9) {
+      scopeEls = queryAll(scopeEls[0], "body");
+    }
+    return { els: scopeEls, status: "ok" };
+  }
+
+  /**
+   * ElementRef → hop 序列（与 elementResolver.resolveElement 同构）
+   *   基础定位：chain 优先 → css → role(+name) → ref
+   *   复合限定：hasText / has / notHas 转成追加 hop，在前一步的结果集上过滤
+   */
+  function hopsOf(ref) {
+    if (!ref || typeof ref !== "object") return [];
+    var hops = [];
+    if (ref.chain && ref.chain.length) {
+      hops = hops.concat(ref.chain);
+    } else if (ref.css) {
+      hops.push({ type: "selector", value: ref.css });
+    } else if (ref.role) {
+      hops.push({ type: "role", value: { role: ref.role, name: ref.name == null ? null : ref.name } });
+    } else if (ref.ref) {
+      hops.push({ type: "data-ref", value: ref.ref });
+    }
+    if (ref.hasText != null) hops.push({ type: "has-text", value: ref.hasText });
+    if (ref.has) hops.push({ type: "has-sub", value: ref.has });
+    if (ref.notHas) hops.push({ type: "not-has-sub", value: ref.notHas });
+    return hops;
+  }
+
+  /** 单个 ElementRef → 末端匹配集合 */
+  function resolveRef(ref) {
+    var hops = hopsOf(ref);
+    if (!hops.length) return { els: [], status: "invalid-ref" };
+    return resolveChain(hops, [document]);
+  }
+
+  /**
+   * ElementRef 链（engine.resolveChain(page, a, b, c) 的浏览器等价物）：
+   * 第一个 ref 从 document 求值，后续 ref 在前一步的结果集范围内继续求值。
+   */
+  function resolveRefChain(refs) {
+    if (!refs || !refs.length) return { els: [], status: "empty-ref" };
+    var res = resolveRef(refs[0]);
+    for (var i = 1; i < refs.length; i += 1) {
+      if (!res.els.length) return res;
+      var hops = hopsOf(refs[i]);
+      if (!hops.length) continue;
+      res = resolveChain(hops, res.els);
+    }
+    return res;
+  }
+
+  function implicitRole(el) {
+    var tag = String(el.tagName || "").toLowerCase();
+    if (tag === "button") return "button";
+    if (tag === "a" && el.hasAttribute("href")) return "link";
+    if (tag === "input") {
+      var t = String(el.getAttribute("type") || "text").toLowerCase();
+      if (t === "checkbox") return "checkbox";
+      if (t === "radio") return "radio";
+      if (t === "submit" || t === "button") return "button";
+      return "textbox";
+    }
+    if (tag === "select") return "combobox";
+    if (tag === "textarea") return "textbox";
+    return "";
+  }
+
+  function accessibleName(el) {
+    var labelled = "";
+    var ids = String(el.getAttribute("aria-labelledby") || "").split(/\\s+/).filter(Boolean);
+    for (var i = 0; i < ids.length; i += 1) {
+      var node = document.getElementById(ids[i]);
+      if (node) labelled += " " + String(node.textContent || "");
+    }
+    return String(
+      el.getAttribute("aria-label")
+      || labelled
+      || (el.labels && el.labels[0] ? el.labels[0].textContent : "")
+      || el.textContent
+      || el.getAttribute("placeholder")
+      || ""
+    ).trim();
+  }
+
+  window.__keveLocator = {
+    version: "v1",
+    resolveRef: resolveRef,
+    resolveRefChain: resolveRefChain,
+    resolveChain: resolveChain,
+    queryAllDeep: queryAllDeep,
+    accessibleName: accessibleName,
+    implicitRole: implicitRole,
+  };
+  window.__keveLocatorSource = "v1";
+  return "ok";
+})()`;
+}

package/dist/dsl/ops.d.ts

@@ -0,0 +1,46 @@
+/**
+ * ops — 平台 DSL 算子 / 断言算子语义表
+ *
+ * 这张表的唯一用途是「可诊断」：生成器遇到不认识的算子时，报错信息能说清
+ * 是「平台用了新算子」还是「这个算子本来就不该出现在可执行用例里」。
+ *
+ * 约束：本模块必须保持零依赖、零副作用 —— dsl/ 会同时被打进 Playwright 与
+ * Cypress 的执行产物，不能引入 Node/框架依赖。
+ */
+/** 平台 stepDsl.operation 取值（来自 stepDsl 表 operation 列的真实分布） */
+export declare const STEP_OPERATIONS: readonly ["OPEN_PAGE", "REDIRECT_TO", "REFRESH_PAGE", "CLICK_ELEMENT", "DB_CLICK_ELEMENT", "FORCE_CLICK_ELEMENT", "CHECK_TEXT", "INPUT_ELEMENT", "MOVE_ELEMENT", "SCROLL", "DRAGGING", "CLEAN", "WAIT_EVENTS", "WAIT_RESPONSE", "WRITE_GLOBAL", "SCREEN_SHOT", "SCREENSHOT", "TAKE_SCREENSHOT"];
+export type StepOperation = (typeof STEP_OPERATIONS)[number];
+/** 是否为已知步骤算子（未知算子一律确定性失败，不静默跳过） */
+export declare function isKnownOperation(op: string): boolean;
+/**
+ * 断言算子（stepDsl.expectation[].type）。
+ *
+ * 语义分成两类，这个区分很关键：
+ *  - 可执行断言：必须渲染成 engine 断言，失败即步骤失败
+ *  - 纯文案载体：只有 text 没有可执行语义，仅喂给 keveGoal 的 expected，
+ *    不产生任何断言（渲染成注释级信息）
+ */
+/** 可执行断言算子 */
+export declare const ASSERT_OPERATIONS: readonly ["ELEMENT_EXIST", "ELEMENT_NOT_EXIST", "ELEMENT_VISIBLE", "ELEMENT_NOT_VISIBLE", "TEXT_EXIST", "TEXT_NOT_EXIST", "TEXT_EQUAL", "EXPECTED_VALUE", "EXPECTED__PAGET_VALUE", "SCREEN_SHOT_COMPARE", "SCREENSHOT_COMPARE", "IMAGE_COMPARE"];
+/**
+ * 纯文案载体算子：不渲染断言。
+ *
+ * `TEXT` 是平台里占比最高的 expectation 类型（500+ 条），它只承载一句人话
+ * （「列表提示无匹配」），没有任何可执行的定位/期望值。把它当未知算子抛错会
+ * 让大批存量用例在生成期就失败 —— 它的语义本来就已经由 keveGoal 的 expected
+ * 承载了。
+ */
+export declare const TEXT_ONLY_ASSERT_OPERATIONS: readonly ["TEXT"];
+export declare function isKnownAssert(type: string): boolean;
+export declare function isTextOnlyAssert(type: string): boolean;
+/**
+ * EXPECTED_VALUE 的受支持比较维度。
+ * ctype 是「比什么」，cexpression 是「怎么比」（chai 风格，历史字段）。
+ */
+export declare const EXPECTED_VALUE_CTYPES: readonly ["text", "class", "placeholder", "style", "index"];
+export declare const COMPARISON_EXPRESSIONS: readonly ["include", "eq", "not.include", "not.eq"];
+/** 历史字段 cexpression → 语义方向 */
+export declare function parseComparison(cexpression: string): {
+    mode: 'include' | 'eq';
+    negated: boolean;
+};

package/dist/dsl/ops.js

@@ -0,0 +1,95 @@
+"use strict";
+/**
+ * ops — 平台 DSL 算子 / 断言算子语义表
+ *
+ * 这张表的唯一用途是「可诊断」：生成器遇到不认识的算子时，报错信息能说清
+ * 是「平台用了新算子」还是「这个算子本来就不该出现在可执行用例里」。
+ *
+ * 约束：本模块必须保持零依赖、零副作用 —— dsl/ 会同时被打进 Playwright 与
+ * Cypress 的执行产物，不能引入 Node/框架依赖。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMPARISON_EXPRESSIONS = exports.EXPECTED_VALUE_CTYPES = exports.TEXT_ONLY_ASSERT_OPERATIONS = exports.ASSERT_OPERATIONS = exports.STEP_OPERATIONS = void 0;
+exports.isKnownOperation = isKnownOperation;
+exports.isKnownAssert = isKnownAssert;
+exports.isTextOnlyAssert = isTextOnlyAssert;
+exports.parseComparison = parseComparison;
+/** 平台 stepDsl.operation 取值（来自 stepDsl 表 operation 列的真实分布） */
+exports.STEP_OPERATIONS = [
+    'OPEN_PAGE',
+    'REDIRECT_TO',
+    'REFRESH_PAGE',
+    'CLICK_ELEMENT',
+    'DB_CLICK_ELEMENT',
+    'FORCE_CLICK_ELEMENT',
+    'CHECK_TEXT',
+    'INPUT_ELEMENT',
+    'MOVE_ELEMENT',
+    'SCROLL',
+    'DRAGGING',
+    'CLEAN',
+    'WAIT_EVENTS',
+    'WAIT_RESPONSE',
+    'WRITE_GLOBAL',
+    'SCREEN_SHOT',
+    'SCREENSHOT',
+    'TAKE_SCREENSHOT',
+];
+const STEP_OPERATION_SET = new Set(exports.STEP_OPERATIONS);
+/** 是否为已知步骤算子（未知算子一律确定性失败，不静默跳过） */
+function isKnownOperation(op) {
+    return STEP_OPERATION_SET.has(String(op || ''));
+}
+/**
+ * 断言算子（stepDsl.expectation[].type）。
+ *
+ * 语义分成两类，这个区分很关键：
+ *  - 可执行断言：必须渲染成 engine 断言，失败即步骤失败
+ *  - 纯文案载体：只有 text 没有可执行语义，仅喂给 keveGoal 的 expected，
+ *    不产生任何断言（渲染成注释级信息）
+ */
+/** 可执行断言算子 */
+exports.ASSERT_OPERATIONS = [
+    'ELEMENT_EXIST',
+    'ELEMENT_NOT_EXIST',
+    'ELEMENT_VISIBLE',
+    'ELEMENT_NOT_VISIBLE',
+    'TEXT_EXIST',
+    'TEXT_NOT_EXIST',
+    'TEXT_EQUAL',
+    'EXPECTED_VALUE',
+    'EXPECTED__PAGET_VALUE',
+    'SCREEN_SHOT_COMPARE',
+    'SCREENSHOT_COMPARE',
+    'IMAGE_COMPARE',
+];
+/**
+ * 纯文案载体算子：不渲染断言。
+ *
+ * `TEXT` 是平台里占比最高的 expectation 类型（500+ 条），它只承载一句人话
+ * （「列表提示无匹配」），没有任何可执行的定位/期望值。把它当未知算子抛错会
+ * 让大批存量用例在生成期就失败 —— 它的语义本来就已经由 keveGoal 的 expected
+ * 承载了。
+ */
+exports.TEXT_ONLY_ASSERT_OPERATIONS = ['TEXT'];
+const ASSERT_OPERATION_SET = new Set(exports.ASSERT_OPERATIONS);
+const TEXT_ONLY_SET = new Set(exports.TEXT_ONLY_ASSERT_OPERATIONS);
+function isKnownAssert(type) {
+    return ASSERT_OPERATION_SET.has(String(type || ''));
+}
+function isTextOnlyAssert(type) {
+    return TEXT_ONLY_SET.has(String(type || ''));
+}
+/**
+ * EXPECTED_VALUE 的受支持比较维度。
+ * ctype 是「比什么」，cexpression 是「怎么比」（chai 风格，历史字段）。
+ */
+exports.EXPECTED_VALUE_CTYPES = ['text', 'class', 'placeholder', 'style', 'index'];
+exports.COMPARISON_EXPRESSIONS = ['include', 'eq', 'not.include', 'not.eq'];
+/** 历史字段 cexpression → 语义方向 */
+function parseComparison(cexpression) {
+    const raw = String(cexpression || 'include').trim().toLowerCase();
+    const negated = raw.startsWith('not.');
+    const mode = raw.replace(/^not\./, '') === 'eq' ? 'eq' : 'include';
+    return { mode, negated };
+}

package/dist/dsl/toDecorator.d.ts

@@ -0,0 +1,98 @@
+/**
+ * DSL → @kkeve/suite 装饰器脚本（纯投影，零 DB / 零框架依赖）
+ *
+ * 输入：**已展开、已解析**的 stepDsl 清单（内嵌场景已递归展开、source 元素库
+ * 引用已解析成 locator 跳、变量已可查表）。输出：可被 Playwright 与 Cypress
+ * 两个引擎同时执行的装饰器脚本源码。
+ *
+ * 为什么生成器放在 suite 包而不是调用方：
+ *  1. 同一份 DSL 必须只投影出一种脚本 —— 两端报告一致的前提是执行体一致
+ *  2. 探索期由 LLM 生成的 @kkeve/suite 脚本，后续要能回填成 DSL；正反变换
+ *     放在同一个包里才闭得上环，否则两边算子语义会各自漂移
+ *
+ * 分层约定：本模块**不做任何 IO**。DB 装载、内嵌展开、元素库解析、变量表
+ * 查询全部留在调用方的 service 层（见 keve 侧 dslLoader）。这样本模块可以被
+ * Cypress 浏览器 bundle 直接引用。
+ *
+ * 关于「不支持就报错」：未知算子渲染成确定性 throw，而不是静默跳过 —— 静默
+ * 跳过会让报告出现「验证通过」的假绿。但**已知的纯文案载体**（TEXT 断言、
+ * 无 type 的 expectation）不是未知算子，它们只喂 expected 文案，不产生断言。
+ */
+/** 平台定位跳（context / expectation.context 的元素） */
+export interface DslHop {
+    type?: string;
+    value?: any;
+    /** 历史字段：部分步骤把定位写在 selector 上 */
+    selector?: string;
+    /** 1-based；-1 / undefined 表示不取第几个 */
+    index?: number;
+}
+/** 平台 DSL 值：字面量或 { type, value } 包装 */
+export type DslValue = string | number | null | undefined | {
+    type?: string;
+    value?: any;
+    variable?: Array<{
+        key: string;
+        value: any;
+    }>;
+};
+/** 一条断言 / 预期 */
+export interface DslExpectation {
+    text?: string;
+    type?: string;
+    /** 比较维度：text | class | placeholder | style | index | url | title */
+    ctype?: string;
+    /** 比较方式：include | eq | not.include（chai 风格历史字段） */
+    cexpression?: string;
+    value?: DslValue;
+    context?: DslHop[];
+    baseImgUrl?: string;
+}
+/** 一条步骤 */
+export interface DslStep {
+    id?: number;
+    operation?: string | null;
+    text?: string;
+    value?: DslValue;
+    context?: DslHop[];
+    wait?: Array<{
+        waitType?: string;
+        value?: any;
+    }>;
+    expectation?: DslExpectation[];
+    /** 拖拽目标 / 嵌套上下文 */
+    child?: any;
+    urlPart?: string;
+}
+/** 变量表行（按环境列取值） */
+export interface DslVariableRow {
+    id?: number;
+    name?: string;
+    variable?: Array<{
+        key: string;
+        value: any;
+    }>;
+    [env: string]: any;
+}
+export interface ToDecoratorOptions {
+    /** 平台 stepGroup id（用于生成稳定类名 / 场景 id） */
+    stepGroupId: number;
+    caseName: string;
+    /** 已展开的 DSL 步骤清单 */
+    dslList: DslStep[];
+    /** 变量取值环境列名（test / rc / pre / online） */
+    env: string;
+    /** 变量表（按 id 或 name 引用） */
+    variableList?: DslVariableRow[];
+    /** 账号占位插值：${loginName} / ${pwd} */
+    account?: {
+        name: string;
+        password: string;
+    };
+    /** 是否已注入 SSO cookie（仅写进注释，供执行现场排查） */
+    ssoInject?: boolean;
+    /** import 来源，默认 @kkeve/suite/keve-test */
+    importFrom?: string;
+}
+/** 生成装饰器脚本源码（UTF-8 文本） */
+export declare function toDecorator(options: ToDecoratorOptions): string;