@nocobase/shared 3.0.0-alpha.5 → 3.0.0-alpha.7

package/lib/variable-usage.d.ts

@@ -9,6 +9,14 @@
 export type JSONValue = string | {
     [key: string]: JSONValue;
 } | JSONValue[];
+export type VariableUsageExtractionResult = {
+    unsupportedDynamicPath: boolean;
+    usage: Record<string, string[]>;
+};
+/**
+ * 提取模板中的 ctx 使用情况。该函数只做静态扫描，不执行表达式。
+ */
+export declare function extractVariableUsage(template: JSONValue): VariableUsageExtractionResult;
 /**
  * 提取模板中使用到的 ctx 顶层变量名集合。
  * - 支持点语法与顶层括号变量：ctx.user / ctx["user"]

package/lib/variable-usage.js

@@ -28,111 +28,289 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var variable_usage_exports = {};
 __export(variable_usage_exports, {
   extractUsedVariableNames: () => extractUsedVariableNames,
-  extractUsedVariablePaths: () => extractUsedVariablePaths
+  extractUsedVariablePaths: () => extractUsedVariablePaths,
+  extractVariableUsage: () => extractVariableUsage
 });
 module.exports = __toCommonJS(variable_usage_exports);
-function extractUsedVariableNames(template) {
-  const result = /* @__PURE__ */ new Set();
-  const visit = /* @__PURE__ */ __name((src) => {
-    if (typeof src === "string") {
-      const regex = /\{\{\s*([^}]+?)\s*\}\}/g;
-      let m;
-      while ((m = regex.exec(src)) !== null) {
-        const expr = m[1];
-        const pathRegex = /ctx\.([a-zA-Z_$][a-zA-Z0-9_$]*)/g;
-        let pm;
-        while ((pm = pathRegex.exec(expr)) !== null) {
-          result.add(pm[1]);
-        }
-        const bracketVarRegex = /ctx\[\s*(["'])\s*([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\1\s*\]/g;
-        let bm;
-        while ((bm = bracketVarRegex.exec(expr)) !== null) {
-          result.add(bm[2]);
-        }
+function isObject(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+__name(isObject, "isObject");
+function isIdentifierStart(char) {
+  return !!char && /[a-zA-Z_$]/.test(char);
+}
+__name(isIdentifierStart, "isIdentifierStart");
+function isIdentifierPart(char) {
+  return !!char && /[a-zA-Z0-9_$]/.test(char);
+}
+__name(isIdentifierPart, "isIdentifierPart");
+function skipSpaces(input, index) {
+  let next = index;
+  while (/\s/.test(input[next] || "")) next += 1;
+  return next;
+}
+__name(skipSpaces, "skipSpaces");
+function skipPostfix(input, index) {
+  let next = skipSpaces(input, index);
+  while (input[next] === "!") {
+    next = skipSpaces(input, next + 1);
+  }
+  return next;
+}
+__name(skipPostfix, "skipPostfix");
+function previousNonSpaceIndex(input, index) {
+  let next = index;
+  while (next >= 0 && /\s/.test(input[next] || "")) next -= 1;
+  return next;
+}
+__name(previousNonSpaceIndex, "previousNonSpaceIndex");
+function isGroupedCtxReference(input, start) {
+  const openParenIndex = previousNonSpaceIndex(input, start - 1);
+  if (input[openParenIndex] !== "(") return false;
+  const beforeOpenParenIndex = previousNonSpaceIndex(input, openParenIndex - 1);
+  if (beforeOpenParenIndex < 0) return true;
+  const beforeOpenParen = input[beforeOpenParenIndex];
+  return !isIdentifierPart(beforeOpenParen) && beforeOpenParen !== ")" && beforeOpenParen !== "]";
+}
+__name(isGroupedCtxReference, "isGroupedCtxReference");
+function hasGroupedContinuation(input, index) {
+  const closeParenIndex = skipSpaces(input, index);
+  if (input[closeParenIndex] !== ")") return false;
+  const continuationIndex = skipSpaces(input, closeParenIndex + 1);
+  return input[continuationIndex] === "." || input[continuationIndex] === "[" || input.startsWith("?.", continuationIndex);
+}
+__name(hasGroupedContinuation, "hasGroupedContinuation");
+function readIdentifier(input, index) {
+  if (!isIdentifierStart(input[index])) return null;
+  let next = index + 1;
+  while (isIdentifierPart(input[next])) next += 1;
+  return { value: input.slice(index, next), next };
+}
+__name(readIdentifier, "readIdentifier");
+function readNumber(input, index) {
+  const match = input.slice(index).match(/^\d+/);
+  return match ? { value: match[0], next: index + match[0].length } : null;
+}
+__name(readNumber, "readNumber");
+function readQuotedProperty(input, index) {
+  const quote = input[index];
+  if (quote !== '"' && quote !== "'") return null;
+  let next = index + 1;
+  let value = "";
+  while (next < input.length) {
+    const char = input[next];
+    if (char === "\\") {
+      value += input.slice(next, next + 2);
+      next += 2;
+      continue;
+    }
+    if (char === quote) {
+      return { value, next: next + 1 };
+    }
+    value += char;
+    next += 1;
+  }
+  return null;
+}
+__name(readQuotedProperty, "readQuotedProperty");
+function readBracketAccess(input, index) {
+  let next = skipSpaces(input, index + 1);
+  const quoted = readQuotedProperty(input, next);
+  if (quoted) {
+    next = skipSpaces(input, quoted.next);
+    if (input[next] !== "]") return { dynamic: true };
+    return { dynamic: false, kind: "property", next: next + 1, value: quoted.value };
+  }
+  const number = readNumber(input, next);
+  if (number) {
+    next = skipSpaces(input, number.next);
+    if (input[next] !== "]") return { dynamic: true };
+    return { dynamic: false, kind: "index", next: next + 1, value: number.value };
+  }
+  return { dynamic: true };
+}
+__name(readBracketAccess, "readBracketAccess");
+function appendPathSegment(segments, kind, value) {
+  if (kind === "property") {
+    segments.push(value);
+    return;
+  }
+  if (segments.length) {
+    segments[segments.length - 1] = `${segments[segments.length - 1]}[${value}]`;
+    return;
+  }
+  segments.push(`[${value}]`);
+}
+__name(appendPathSegment, "appendPathSegment");
+function readAccess(input, index) {
+  const next = skipPostfix(input, index);
+  if (input[next] === "[") {
+    return readBracketAccess(input, next);
+  }
+  if (input.startsWith("?.", next)) {
+    const propertyStart = skipSpaces(input, next + 2);
+    if (input[propertyStart] === "[") {
+      return readBracketAccess(input, propertyStart);
+    }
+    const identifier = readIdentifier(input, propertyStart) || readNumber(input, propertyStart);
+    return identifier ? { dynamic: false, kind: "property", next: identifier.next, value: identifier.value } : null;
+  }
+  if (input[next] === ".") {
+    const propertyStart = skipSpaces(input, next + 1);
+    const identifier = readIdentifier(input, propertyStart) || readNumber(input, propertyStart);
+    return identifier ? { dynamic: false, kind: "property", next: identifier.next, value: identifier.value } : null;
+  }
+  return null;
+}
+__name(readAccess, "readAccess");
+function parseDotOnlyCtxReference(expr) {
+  const trimmed = expr.trim();
+  const segment = "(?:[a-zA-Z_$][a-zA-Z0-9_$-]*|\\d+)";
+  const match = trimmed.match(new RegExp(`^ctx\\.([a-zA-Z_$][a-zA-Z0-9_$]*)(?:\\.(${segment}(?:\\.${segment})*))?$`));
+  if (!match) return null;
+  return {
+    methodCall: false,
+    path: match[2] || void 0,
+    unsupportedDynamicPath: false,
+    varName: match[1]
+  };
+}
+__name(parseDotOnlyCtxReference, "parseDotOnlyCtxReference");
+function parseCtxReference(input, start) {
+  if (input.slice(start, start + 3) !== "ctx") return null;
+  if (isIdentifierPart(input[start - 1]) || isIdentifierPart(input[start + 3])) return null;
+  if (isGroupedCtxReference(input, start)) {
+    return {
+      next: start + 3,
+      reference: {
+        methodCall: false,
+        unsupportedDynamicPath: true,
+        varName: ""
       }
-    } else if (Array.isArray(src)) {
-      src.forEach(visit);
-    } else if (src && typeof src === "object") {
-      Object.values(src).forEach(visit);
+    };
+  }
+  const rootAccess = readAccess(input, start + 3);
+  if (!rootAccess) return null;
+  if (rootAccess.dynamic) {
+    return {
+      next: start + 3,
+      reference: {
+        methodCall: false,
+        unsupportedDynamicPath: true,
+        varName: ""
+      }
+    };
+  }
+  if (rootAccess.kind !== "property") {
+    return null;
+  }
+  const segments = [];
+  let next = rootAccess.next;
+  let methodCall = false;
+  let unsupportedDynamicPath = false;
+  while (next < input.length) {
+    const accessStart = skipPostfix(input, next);
+    if ((input[accessStart] === "(" || input.startsWith("?.(", accessStart)) && !segments.length) {
+      methodCall = true;
+      next = accessStart;
+      break;
     }
-  }, "visit");
-  visit(template);
-  return result;
+    const access = readAccess(input, next);
+    if (!access) {
+      next = accessStart;
+      if (input[accessStart] === "[" || input[accessStart] === "." || input.startsWith("?.", accessStart)) {
+        unsupportedDynamicPath = true;
+      }
+      break;
+    }
+    if (access.dynamic) {
+      unsupportedDynamicPath = true;
+      next = accessStart;
+      break;
+    }
+    appendPathSegment(segments, access.kind, access.value);
+    next = access.next;
+  }
+  const path = segments.join(".");
+  return {
+    next: Math.max(next, rootAccess.next),
+    reference: {
+      methodCall,
+      path: path || void 0,
+      unsupportedDynamicPath: unsupportedDynamicPath || hasGroupedContinuation(input, next),
+      varName: rootAccess.value
+    }
+  };
 }
-__name(extractUsedVariableNames, "extractUsedVariableNames");
-function extractUsedVariablePaths(template) {
+__name(parseCtxReference, "parseCtxReference");
+function collectCtxReferences(expr) {
+  const dotOnly = parseDotOnlyCtxReference(expr);
+  if (dotOnly) return [dotOnly];
+  const references = [];
+  for (let index = 0; index < expr.length; index += 1) {
+    if (expr.slice(index, index + 3) !== "ctx") continue;
+    const parsed = parseCtxReference(expr, index);
+    if (!parsed) continue;
+    references.push(parsed.reference);
+    index = Math.max(index, parsed.next - 1);
+  }
+  return references;
+}
+__name(collectCtxReferences, "collectCtxReferences");
+function addUsagePath(usage, varName, path, methodCall) {
+  usage[varName] = usage[varName] || [];
+  if (path) {
+    usage[varName].push(path);
+  } else if (methodCall && !usage[varName].includes("")) {
+    usage[varName].push("");
+  }
+}
+__name(addUsagePath, "addUsagePath");
+function extractVariableUsage(template) {
   const usage = {};
+  let unsupportedDynamicPath = false;
+  const visitExpression = /* @__PURE__ */ __name((expr) => {
+    for (const reference of collectCtxReferences(expr)) {
+      if (reference.unsupportedDynamicPath) {
+        unsupportedDynamicPath = true;
+        continue;
+      }
+      if (!reference.varName) continue;
+      addUsagePath(usage, reference.varName, reference.path, reference.methodCall);
+    }
+  }, "visitExpression");
   const visit = /* @__PURE__ */ __name((src) => {
     if (typeof src === "string") {
       const regex = /\{\{\s*([^}]+?)\s*\}\}/g;
-      let m;
-      while ((m = regex.exec(src)) !== null) {
-        const expr = m[1];
-        const pathRegex = /ctx\.([a-zA-Z_$][a-zA-Z0-9_$]*)([^\s)]*)/g;
-        let pm;
-        while ((pm = pathRegex.exec(expr)) !== null) {
-          const varName = pm[1];
-          const after = pm[2] || "";
-          usage[varName] = usage[varName] || [];
-          if (after.startsWith(".")) {
-            usage[varName].push(after.slice(1));
-          } else if (after.startsWith("[")) {
-            const mm = after.match(/^\[\s*(["'])\s*([^'"\]]+)\s*\1\s*\](.*)$/);
-            if (mm) {
-              const first = mm[2];
-              const rest = mm[3] || "";
-              usage[varName].push(`${first}${rest}`);
-            } else {
-              const mn = after.match(/^\[(\d+)\](.*)$/);
-              if (mn) {
-                const idx = mn[1];
-                const rest = mn[2] || "";
-                usage[varName].push(`[${idx}]${rest}`);
-              }
-            }
-          } else if (after.startsWith("(")) {
-            if (!usage[varName].length) usage[varName].push("");
-          }
-        }
-        const bracketVarRegex = /ctx\[\s*(["'])\s*([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\1\s*\]([^\s)]*)/g;
-        let bm;
-        while ((bm = bracketVarRegex.exec(expr)) !== null) {
-          const varName = bm[2];
-          const after = bm[3] || "";
-          usage[varName] = usage[varName] || [];
-          if (after.startsWith(".")) {
-            usage[varName].push(after.slice(1));
-          } else if (after.startsWith("[")) {
-            const mm = after.match(/^\[\s*(["'])\s*([^'"\]]+)\s*\1\s*\](.*)$/);
-            if (mm) {
-              const first = mm[2];
-              const rest = mm[3] || "";
-              usage[varName].push(`${first}${rest}`);
-            } else {
-              const mn = after.match(/^\[(\d+)\](.*)$/);
-              if (mn) {
-                const idx = mn[1];
-                const rest = mn[2] || "";
-                usage[varName].push(`[${idx}]${rest}`);
-              }
-            }
-          } else if (after.startsWith("(")) {
-            if (!usage[varName].length) usage[varName].push("");
-          }
-        }
+      let match;
+      while ((match = regex.exec(src)) !== null) {
+        visitExpression(match[1]);
       }
-    } else if (Array.isArray(src)) {
+      return;
+    }
+    if (Array.isArray(src)) {
       src.forEach(visit);
-    } else if (src && typeof src === "object") {
+      return;
+    }
+    if (isObject(src)) {
       Object.values(src).forEach(visit);
     }
   }, "visit");
   visit(template);
-  return usage;
+  return { unsupportedDynamicPath, usage };
+}
+__name(extractVariableUsage, "extractVariableUsage");
+function extractUsedVariableNames(template) {
+  return new Set(Object.keys(extractVariableUsage(template).usage));
+}
+__name(extractUsedVariableNames, "extractUsedVariableNames");
+function extractUsedVariablePaths(template) {
+  return extractVariableUsage(template).usage;
 }
 __name(extractUsedVariablePaths, "extractUsedVariablePaths");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   extractUsedVariableNames,
-  extractUsedVariablePaths
+  extractUsedVariablePaths,
+  extractVariableUsage
 });

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@nocobase/shared",
-  "version": "3.0.0-alpha.5",
+  "version": "3.0.0-alpha.7",
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",
   "license": "Apache-2.0",
-  "gitHead": "82c7ed1cdb2f247c190582e34ee37f154cac0968"
+  "gitHead": "19cd28c710f3b3c614ebe2fd7d5a415d527ee559"
 }

package/src/variable-usage.ts

@@ -10,41 +10,316 @@
 // 轻量模板类型定义：与前后端均可复用
 export type JSONValue = string | { [key: string]: JSONValue } | JSONValue[];
 
+export type VariableUsageExtractionResult = {
+  unsupportedDynamicPath: boolean;
+  usage: Record<string, string[]>;
+};
+
+type CtxReference = {
+  methodCall: boolean;
+  path?: string;
+  unsupportedDynamicPath: boolean;
+  varName: string;
+};
+
+function isObject(value: unknown): value is Record<string, JSONValue> {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isIdentifierStart(char: string | undefined) {
+  return !!char && /[a-zA-Z_$]/.test(char);
+}
+
+function isIdentifierPart(char: string | undefined) {
+  return !!char && /[a-zA-Z0-9_$]/.test(char);
+}
+
+function skipSpaces(input: string, index: number) {
+  let next = index;
+  while (/\s/.test(input[next] || '')) next += 1;
+  return next;
+}
+
+function skipPostfix(input: string, index: number) {
+  let next = skipSpaces(input, index);
+  while (input[next] === '!') {
+    next = skipSpaces(input, next + 1);
+  }
+  return next;
+}
+
+function previousNonSpaceIndex(input: string, index: number) {
+  let next = index;
+  while (next >= 0 && /\s/.test(input[next] || '')) next -= 1;
+  return next;
+}
+
+function isGroupedCtxReference(input: string, start: number) {
+  const openParenIndex = previousNonSpaceIndex(input, start - 1);
+  if (input[openParenIndex] !== '(') return false;
+
+  const beforeOpenParenIndex = previousNonSpaceIndex(input, openParenIndex - 1);
+  if (beforeOpenParenIndex < 0) return true;
+
+  const beforeOpenParen = input[beforeOpenParenIndex];
+  return !isIdentifierPart(beforeOpenParen) && beforeOpenParen !== ')' && beforeOpenParen !== ']';
+}
+
+function hasGroupedContinuation(input: string, index: number) {
+  const closeParenIndex = skipSpaces(input, index);
+  if (input[closeParenIndex] !== ')') return false;
+
+  const continuationIndex = skipSpaces(input, closeParenIndex + 1);
+  return (
+    input[continuationIndex] === '.' || input[continuationIndex] === '[' || input.startsWith('?.', continuationIndex)
+  );
+}
+
+function readIdentifier(input: string, index: number): { next: number; value: string } | null {
+  if (!isIdentifierStart(input[index])) return null;
+  let next = index + 1;
+  while (isIdentifierPart(input[next])) next += 1;
+  return { value: input.slice(index, next), next };
+}
+
+function readNumber(input: string, index: number): { next: number; value: string } | null {
+  const match = input.slice(index).match(/^\d+/);
+  return match ? { value: match[0], next: index + match[0].length } : null;
+}
+
+function readQuotedProperty(input: string, index: number): { next: number; value: string } | null {
+  const quote = input[index];
+  if (quote !== '"' && quote !== "'") return null;
+  let next = index + 1;
+  let value = '';
+  while (next < input.length) {
+    const char = input[next];
+    if (char === '\\') {
+      value += input.slice(next, next + 2);
+      next += 2;
+      continue;
+    }
+    if (char === quote) {
+      return { value, next: next + 1 };
+    }
+    value += char;
+    next += 1;
+  }
+  return null;
+}
+
+function readBracketAccess(input: string, index: number) {
+  let next = skipSpaces(input, index + 1);
+  const quoted = readQuotedProperty(input, next);
+  if (quoted) {
+    next = skipSpaces(input, quoted.next);
+    if (input[next] !== ']') return { dynamic: true as const };
+    return { dynamic: false as const, kind: 'property' as const, next: next + 1, value: quoted.value };
+  }
+
+  const number = readNumber(input, next);
+  if (number) {
+    next = skipSpaces(input, number.next);
+    if (input[next] !== ']') return { dynamic: true as const };
+    return { dynamic: false as const, kind: 'index' as const, next: next + 1, value: number.value };
+  }
+
+  return { dynamic: true as const };
+}
+
+function appendPathSegment(segments: string[], kind: 'property' | 'index', value: string) {
+  if (kind === 'property') {
+    segments.push(value);
+    return;
+  }
+  if (segments.length) {
+    segments[segments.length - 1] = `${segments[segments.length - 1]}[${value}]`;
+    return;
+  }
+  segments.push(`[${value}]`);
+}
+
+function readAccess(input: string, index: number) {
+  const next = skipPostfix(input, index);
+  if (input[next] === '[') {
+    return readBracketAccess(input, next);
+  }
+  if (input.startsWith('?.', next)) {
+    const propertyStart = skipSpaces(input, next + 2);
+    if (input[propertyStart] === '[') {
+      return readBracketAccess(input, propertyStart);
+    }
+    const identifier = readIdentifier(input, propertyStart) || readNumber(input, propertyStart);
+    return identifier
+      ? { dynamic: false as const, kind: 'property' as const, next: identifier.next, value: identifier.value }
+      : null;
+  }
+  if (input[next] === '.') {
+    const propertyStart = skipSpaces(input, next + 1);
+    const identifier = readIdentifier(input, propertyStart) || readNumber(input, propertyStart);
+    return identifier
+      ? { dynamic: false as const, kind: 'property' as const, next: identifier.next, value: identifier.value }
+      : null;
+  }
+  return null;
+}
+
+function parseDotOnlyCtxReference(expr: string): CtxReference | null {
+  const trimmed = expr.trim();
+  const segment = '(?:[a-zA-Z_$][a-zA-Z0-9_$-]*|\\d+)';
+  const match = trimmed.match(new RegExp(`^ctx\\.([a-zA-Z_$][a-zA-Z0-9_$]*)(?:\\.(${segment}(?:\\.${segment})*))?$`));
+  if (!match) return null;
+  return {
+    methodCall: false,
+    path: match[2] || undefined,
+    unsupportedDynamicPath: false,
+    varName: match[1],
+  };
+}
+
+function parseCtxReference(input: string, start: number): { next: number; reference: CtxReference } | null {
+  if (input.slice(start, start + 3) !== 'ctx') return null;
+  if (isIdentifierPart(input[start - 1]) || isIdentifierPart(input[start + 3])) return null;
+
+  if (isGroupedCtxReference(input, start)) {
+    return {
+      next: start + 3,
+      reference: {
+        methodCall: false,
+        unsupportedDynamicPath: true,
+        varName: '',
+      },
+    };
+  }
+
+  const rootAccess = readAccess(input, start + 3);
+  if (!rootAccess) return null;
+  if (rootAccess.dynamic) {
+    return {
+      next: start + 3,
+      reference: {
+        methodCall: false,
+        unsupportedDynamicPath: true,
+        varName: '',
+      },
+    };
+  }
+  if (rootAccess.kind !== 'property') {
+    return null;
+  }
+
+  const segments: string[] = [];
+  let next = rootAccess.next;
+  let methodCall = false;
+  let unsupportedDynamicPath = false;
+
+  while (next < input.length) {
+    const accessStart = skipPostfix(input, next);
+    if ((input[accessStart] === '(' || input.startsWith('?.(', accessStart)) && !segments.length) {
+      methodCall = true;
+      next = accessStart;
+      break;
+    }
+
+    const access = readAccess(input, next);
+    if (!access) {
+      next = accessStart;
+      if (input[accessStart] === '[' || input[accessStart] === '.' || input.startsWith('?.', accessStart)) {
+        unsupportedDynamicPath = true;
+      }
+      break;
+    }
+    if (access.dynamic) {
+      unsupportedDynamicPath = true;
+      next = accessStart;
+      break;
+    }
+    appendPathSegment(segments, access.kind, access.value);
+    next = access.next;
+  }
+
+  const path = segments.join('.');
+  return {
+    next: Math.max(next, rootAccess.next),
+    reference: {
+      methodCall,
+      path: path || undefined,
+      unsupportedDynamicPath: unsupportedDynamicPath || hasGroupedContinuation(input, next),
+      varName: rootAccess.value,
+    },
+  };
+}
+
+function collectCtxReferences(expr: string): CtxReference[] {
+  const dotOnly = parseDotOnlyCtxReference(expr);
+  if (dotOnly) return [dotOnly];
+
+  const references: CtxReference[] = [];
+  for (let index = 0; index < expr.length; index += 1) {
+    if (expr.slice(index, index + 3) !== 'ctx') continue;
+    const parsed = parseCtxReference(expr, index);
+    if (!parsed) continue;
+    references.push(parsed.reference);
+    index = Math.max(index, parsed.next - 1);
+  }
+  return references;
+}
+
+function addUsagePath(usage: Record<string, string[]>, varName: string, path?: string, methodCall?: boolean) {
+  usage[varName] = usage[varName] || [];
+  if (path) {
+    usage[varName].push(path);
+  } else if (methodCall && !usage[varName].includes('')) {
+    usage[varName].push('');
+  }
+}
+
 /**
- * 提取模板中使用到的 ctx 顶层变量名集合。
- * - 支持点语法与顶层括号变量：ctx.user / ctx["user"]
+ * 提取模板中的 ctx 使用情况。该函数只做静态扫描，不执行表达式。
  */
-export function extractUsedVariableNames(template: JSONValue): Set<string> {
-  const result = new Set<string>();
+export function extractVariableUsage(template: JSONValue): VariableUsageExtractionResult {
+  const usage: Record<string, string[]> = {};
+  let unsupportedDynamicPath = false;
 
-  const visit = (src: any) => {
+  const visitExpression = (expr: string) => {
+    for (const reference of collectCtxReferences(expr)) {
+      if (reference.unsupportedDynamicPath) {
+        unsupportedDynamicPath = true;
+        continue;
+      }
+      if (!reference.varName) continue;
+      addUsagePath(usage, reference.varName, reference.path, reference.methodCall);
+    }
+  };
+
+  const visit = (src: JSONValue) => {
     if (typeof src === 'string') {
       const regex = /\{\{\s*([^}]+?)\s*\}\}/g;
-      let m: RegExpExecArray | null;
-      while ((m = regex.exec(src)) !== null) {
-        const expr = m[1];
-        // ctx.<var>
-        const pathRegex = /ctx\.([a-zA-Z_$][a-zA-Z0-9_$]*)/g;
-        let pm: RegExpExecArray | null;
-        while ((pm = pathRegex.exec(expr)) !== null) {
-          result.add(pm[1]);
-        }
-        // ctx["var"] or ctx['var']
-        const bracketVarRegex = /ctx\[\s*(["'])\s*([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\1\s*\]/g;
-        let bm: RegExpExecArray | null;
-        while ((bm = bracketVarRegex.exec(expr)) !== null) {
-          result.add(bm[2]);
-        }
+      let match: RegExpExecArray | null;
+      while ((match = regex.exec(src)) !== null) {
+        visitExpression(match[1]);
       }
-    } else if (Array.isArray(src)) {
+      return;
+    }
+    if (Array.isArray(src)) {
       src.forEach(visit);
-    } else if (src && typeof src === 'object') {
+      return;
+    }
+    if (isObject(src)) {
       Object.values(src).forEach(visit);
     }
   };
 
   visit(template);
-  return result;
+  return { unsupportedDynamicPath, usage };
+}
+
+/**
+ * 提取模板中使用到的 ctx 顶层变量名集合。
+ * - 支持点语法与顶层括号变量：ctx.user / ctx["user"]
+ */
+export function extractUsedVariableNames(template: JSONValue): Set<string> {
+  return new Set(Object.keys(extractVariableUsage(template).usage));
 }
 
 /**
@@ -54,79 +329,5 @@ export function extractUsedVariableNames(template: JSONValue): Set<string> {
  * - 方法调用：记录空字符串以触发服务端 attach（例如 ctx.twice(21) => { twice: [''] }）
  */
 export function extractUsedVariablePaths(template: JSONValue): Record<string, string[]> {
-  const usage: Record<string, string[]> = {};
-
-  const visit = (src: any) => {
-    if (typeof src === 'string') {
-      const regex = /\{\{\s*([^}]+?)\s*\}\}/g;
-      let m: RegExpExecArray | null;
-      while ((m = regex.exec(src)) !== null) {
-        const expr = m[1];
-
-        // 点语法：ctx.varName[...]
-        const pathRegex = /ctx\.([a-zA-Z_$][a-zA-Z0-9_$]*)([^\s)]*)/g;
-        let pm: RegExpExecArray | null;
-        while ((pm = pathRegex.exec(expr)) !== null) {
-          const varName = pm[1];
-          const after = pm[2] || '';
-          usage[varName] = usage[varName] || [];
-          if (after.startsWith('.')) {
-            usage[varName].push(after.slice(1));
-          } else if (after.startsWith('[')) {
-            // 首段括号键或数字索引
-            const mm = after.match(/^\[\s*(["'])\s*([^'"\]]+)\s*\1\s*\](.*)$/);
-            if (mm) {
-              const first = mm[2];
-              const rest = mm[3] || '';
-              usage[varName].push(`${first}${rest}`);
-            } else {
-              const mn = after.match(/^\[(\d+)\](.*)$/);
-              if (mn) {
-                const idx = mn[1];
-                const rest = mn[2] || '';
-                usage[varName].push(`[${idx}]${rest}`);
-              }
-            }
-          } else if (after.startsWith('(')) {
-            if (!usage[varName].length) usage[varName].push('');
-          }
-        }
-
-        // 顶层括号变量：ctx["varName"]...
-        const bracketVarRegex = /ctx\[\s*(["'])\s*([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\1\s*\]([^\s)]*)/g;
-        let bm: RegExpExecArray | null;
-        while ((bm = bracketVarRegex.exec(expr)) !== null) {
-          const varName = bm[2];
-          const after = bm[3] || '';
-          usage[varName] = usage[varName] || [];
-          if (after.startsWith('.')) {
-            usage[varName].push(after.slice(1));
-          } else if (after.startsWith('[')) {
-            const mm = after.match(/^\[\s*(["'])\s*([^'"\]]+)\s*\1\s*\](.*)$/);
-            if (mm) {
-              const first = mm[2];
-              const rest = mm[3] || '';
-              usage[varName].push(`${first}${rest}`);
-            } else {
-              const mn = after.match(/^\[(\d+)\](.*)$/);
-              if (mn) {
-                const idx = mn[1];
-                const rest = mn[2] || '';
-                usage[varName].push(`[${idx}]${rest}`);
-              }
-            }
-          } else if (after.startsWith('(')) {
-            if (!usage[varName].length) usage[varName].push('');
-          }
-        }
-      }
-    } else if (Array.isArray(src)) {
-      src.forEach(visit);
-    } else if (src && typeof src === 'object') {
-      Object.values(src).forEach(visit);
-    }
-  };
-
-  visit(template);
-  return usage;
+  return extractVariableUsage(template).usage;
 }