@77-zhike/app-sdk 0.2.0-d7b1.2

package/src/toolchain/source-discovery.js

@@ -0,0 +1,710 @@
+import { frontendPoint } from '../client/points.generated.js';
+import { sdkIconNames } from '../ui/icons.generated.js';
+import { readdir, readFile } from "node:fs/promises";
+import { posix, relative, resolve, sep } from "node:path";
+import ts from "typescript";
+
+import { ZhikeCliError } from "../errors.js";
+
+const KEY_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
+const RECORD_OBJECT_PATTERN = /^[a-z][a-z0-9_]{0,106}$/;
+const RECORD_ACTION_LABEL_MAX_LENGTH = 80;
+const RECORD_ACTION_OBJECTS_MAX_LENGTH = 32;
+const SDK_ICON_NAMES = new Set(sdkIconNames);
+const SERVER_MODULE_PATTERN = /^server\/functions\/[a-z0-9][a-z0-9/-]*$/;
+const LIFECYCLE_EVENTS = new Set([
+  "app-installed",
+  "app-uninstalled",
+  "connection-added",
+  "connection-removed",
+]);
+const SDK_IMPORTS = new Set([
+  "@77-zhike/app-sdk",
+  "@77-zhike/app-sdk/client",
+  "@77-zhike/app-sdk/ui",
+  "@77-zhike/app-sdk/forms",
+  "react",
+  "react/jsx-runtime",
+  "react/jsx-dev-runtime",
+  "@77-zhike/app-sdk/server",
+]);
+const NODE_BUILTINS = new Set([
+  "assert",
+  "buffer",
+  "child_process",
+  "cluster",
+  "crypto",
+  "dgram",
+  "dns",
+  "events",
+  "fs",
+  "http",
+  "https",
+  "module",
+  "net",
+  "os",
+  "path",
+  "perf_hooks",
+  "process",
+  "readline",
+  "stream",
+  "tls",
+  "url",
+  "util",
+  "v8",
+  "vm",
+  "worker_threads",
+  "zlib",
+]);
+
+export async function discoverAppSources(projectDirectory) {
+  const sourceRoot = resolve(projectDirectory, "src");
+  const files = await listFiles(sourceRoot);
+  const normalized = files.map((path) => ({
+    absolutePath: path,
+    relativePath: relative(sourceRoot, path).split(sep).join("/"),
+  }));
+  rejectUnsupportedPaths(normalized);
+
+  const frontendExtensions = [];
+  const lifecycleEvents = [];
+  const serverFunctions = [];
+  const webhookHandlers = [];
+  const globalKeys = new Map();
+  for (const file of normalized) {
+    const sourceText = await readFile(file.absolutePath, "utf8");
+    const sourceFile = ts.createSourceFile(
+      file.relativePath,
+      sourceText,
+      ts.ScriptTarget.ES2022,
+      true,
+      file.relativePath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+    );
+    assertSyntacticallyValid(sourceFile);
+    validateImports(sourceFile, file.relativePath);
+
+    const extensionMatch = file.relativePath.match(
+      /^app\/extensions\/([a-z][a-z0-9-]{0,63})\/extension\.tsx$/,
+    );
+    const lifecycleMatch = file.relativePath.match(
+      /^app\/events\/(app-installed|app-uninstalled|connection-added|connection-removed)\.event\.ts$/,
+    );
+    const webhookMatch = file.relativePath.match(
+      /^app\/webhooks\/([a-z][a-z0-9-]{0,63})\.webhook\.ts$/,
+    );
+    const serverMatch = file.relativePath.match(
+      /^(server\/functions\/[a-z0-9][a-z0-9/-]*)\.server\.ts$/,
+    );
+    if (lifecycleMatch) {
+      const definition = parseLifecycleEvent(
+        sourceFile,
+        file.relativePath,
+        lifecycleMatch[1],
+      );
+      registerUniqueKey(globalKeys, definition.key, file.relativePath);
+      lifecycleEvents.push(definition);
+    } else if (extensionMatch) {
+      const definition = parseFrontendExtension(
+        sourceFile,
+        file.relativePath,
+        extensionMatch[1],
+      );
+      registerUniqueKey(globalKeys, definition.key, file.relativePath);
+      frontendExtensions.push(definition);
+    } else if (webhookMatch) {
+      const definition = parseWebhookHandler(
+        sourceFile,
+        file.relativePath,
+        webhookMatch[1],
+      );
+      registerUniqueKey(globalKeys, definition.key, file.relativePath);
+      webhookHandlers.push(definition);
+    } else if (serverMatch) {
+      const definition = parseServerFunction(
+        sourceFile,
+        file.relativePath,
+        serverMatch[1],
+      );
+      registerUniqueKey(globalKeys, definition.key, file.relativePath);
+      serverFunctions.push(definition);
+    }
+  }
+  if (
+    frontendExtensions.length === 0 &&
+    lifecycleEvents.length === 0 &&
+    serverFunctions.length === 0 &&
+    webhookHandlers.length === 0
+  ) {
+    throw toolchainError(
+      "zhike_source_entry_missing",
+      "未发现一期 Lifecycle Event、Frontend Extension、Server Function 或 Webhook Handler",
+    );
+  }
+  if (frontendExtensions.filter(item => item.type === "settings").length > 1) {
+    throw toolchainError("zhike_settings_duplicate", "一个 App 至多声明一个 Settings");
+  }
+  return Object.freeze({
+    frontendExtensions: Object.freeze(sortByKey(frontendExtensions)),
+    lifecycleEvents: Object.freeze(sortByKey(lifecycleEvents)),
+    serverFunctions: Object.freeze(sortByKey(serverFunctions)),
+    sourceFiles: Object.freeze(normalized.map((file) => file.relativePath).sort()),
+    webhookHandlers: Object.freeze(sortByKey(webhookHandlers)),
+  });
+}
+
+function parseLifecycleEvent(sourceFile, relativePath, fileEvent) {
+  if (hasSdkNamedImport(sourceFile, "@77-zhike/app-sdk/server", "defineLifecycleEvent")) {
+    throw toolchainError(
+      "zhike_lifecycle_event_wrapper_deprecated",
+      `${relativePath}: defineLifecycleEvent 已不再用于新 Build，请直接 default export async function`,
+    );
+  }
+  const handler = requireDefaultAsyncFunction(sourceFile, relativePath);
+  if (!LIFECYCLE_EVENTS.has(fileEvent)) {
+    throw toolchainError(
+      "zhike_lifecycle_event_identity_invalid",
+      `${relativePath}: 文件名必须是受支持的生命周期事件`,
+    );
+  }
+  return Object.freeze({ event: fileEvent, key: fileEvent, relativePath, handler });
+}
+
+function requireDefaultAsyncFunction(
+  sourceFile,
+  relativePath,
+  {
+    errorCode = "zhike_lifecycle_event_export_invalid",
+    entryName = "Lifecycle Event",
+  } = {},
+) {
+  const functions = sourceFile.statements.filter(
+    (statement) =>
+      ts.isFunctionDeclaration(statement) &&
+      statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) &&
+      statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword),
+  );
+  const defaultAssignments = sourceFile.statements.filter(
+    (statement) => ts.isExportAssignment(statement) && !statement.isExportEquals,
+  );
+  if (functions.length !== 1 || defaultAssignments.length !== 0) {
+    throw toolchainError(
+      errorCode,
+      `${relativePath}: 必须有且只有一个 export default async function`,
+    );
+  }
+  const handler = functions[0];
+  if (
+    !handler.body ||
+    !handler.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.AsyncKeyword)
+  ) {
+    throw toolchainError(
+      errorCode,
+      `${relativePath}: ${entryName} default export 必须是 async function`,
+    );
+  }
+  return handler.name?.text || null;
+}
+
+function parseFrontendExtension(sourceFile, relativePath, directoryKey) {
+  requireSdkNamedImport(
+    sourceFile,
+    relativePath,
+    "@77-zhike/app-sdk/client",
+    "defineFrontendExtension",
+  );
+  const call = requireDefaultExportCall(
+    sourceFile,
+    relativePath,
+    "defineFrontendExtension",
+  );
+  const object = requireObjectLiteral(call.arguments[0], relativePath);
+  const key = requireStringProperty(object, "key", relativePath);
+  const type = requireStringProperty(object, "type", relativePath);
+  const point = frontendPoint(type);
+  if (!point) throw toolchainError("zhike_frontend_extension_type_unsupported", `${relativePath}: 扩展类型尚未开放`);
+  const handlerName = point.kind === "view" ? "component" : (point.callbackName || "handler");
+  const forbiddenNames = point.kind === "view"
+    ? ["handler", "onTrigger"]
+    : ["component", ...(handlerName === "handler" ? ["onTrigger"] : ["handler"])];
+  if (forbiddenNames.some(name => findProperty(object, name))) {
+    throw toolchainError("zhike_frontend_definition_mixed", `${relativePath}: component 与 handler 不得混填`);
+  }
+  const property = findProperty(object, handlerName);
+  if (point.kind === "view" && property && ts.isPropertyAssignment(property) && ts.isIdentifier(property.initializer)) {
+    // 引用的组件由 TypeScript 检查可调用性；控制面不执行组件。
+  } else {
+    requireFunctionProperty(object, handlerName, relativePath);
+  }
+  if (key !== directoryKey || !KEY_PATTERN.test(key)) {
+    throw toolchainError(
+      "zhike_frontend_extension_key_invalid",
+      `${relativePath}: key 必须与扩展目录一致`,
+    );
+  }
+  if (type === "record-action") {
+    return Object.freeze({
+      key,
+      type,
+      entry: key,
+      relativePath,
+      ...parseRecordActionMetadata(object, relativePath),
+    });
+  }
+  return Object.freeze({ key, type, entry: key, relativePath });
+}
+
+function parseRecordActionMetadata(object, relativePath) {
+  assertOnlyProperties(object, ["key", "type", "label", "icon", "objects", "onTrigger"], relativePath);
+  const label = requireStringProperty(object, "label", relativePath).trim();
+  if (
+    [...label].length === 0 ||
+    [...label].length > RECORD_ACTION_LABEL_MAX_LENGTH ||
+    /\p{Cc}/u.test(label)
+  ) {
+    throw toolchainError(
+      "zhike_record_action_label_invalid",
+      `${relativePath}: label 必须是 1～${RECORD_ACTION_LABEL_MAX_LENGTH} 个非控制字符`,
+    );
+  }
+  const iconProperty = findProperty(object, "icon");
+  const icon = iconProperty ? requireStringProperty(object, "icon", relativePath) : null;
+  if (icon !== null && (!KEY_PATTERN.test(icon) || !SDK_ICON_NAMES.has(icon))) {
+    throw toolchainError(
+      "zhike_record_action_icon_invalid",
+      `${relativePath}: icon 必须来自 SDK 统一图标目录`,
+    );
+  }
+  const objectsProperty = findProperty(object, "objects");
+  const objects = objectsProperty ? requireRecordObjects(objectsProperty, relativePath) : null;
+  return {
+    label,
+    ...(icon === null ? {} : { icon }),
+    ...(objects === null ? {} : { objects }),
+  };
+}
+
+function requireRecordObjects(property, relativePath) {
+  if (!ts.isPropertyAssignment(property)) {
+    throw toolchainError("zhike_record_action_objects_invalid", `${relativePath}: objects 必须是字符串字面量或字符串字面量数组`);
+  }
+  const initializer = property.initializer;
+  const values = ts.isStringLiteral(initializer)
+    ? [initializer.text]
+    : ts.isArrayLiteralExpression(initializer)
+      ? initializer.elements.map(item => {
+          if (!ts.isStringLiteral(item)) {
+            throw toolchainError("zhike_record_action_objects_invalid", `${relativePath}: objects 必须是字符串字面量数组`);
+          }
+          return item.text;
+        })
+      : null;
+  if (
+    values === null ||
+    values.length === 0 ||
+    values.length > RECORD_ACTION_OBJECTS_MAX_LENGTH ||
+    values.some(value => !RECORD_OBJECT_PATTERN.test(value))
+  ) {
+    throw toolchainError(
+      "zhike_record_action_objects_invalid",
+      `${relativePath}: objects 必须包含 1～${RECORD_ACTION_OBJECTS_MAX_LENGTH} 个合法公开对象标识`,
+    );
+  }
+  return Object.freeze([...new Set(values)]);
+}
+
+function assertOnlyProperties(object, allowed, relativePath) {
+  const allowedNames = new Set(allowed);
+  for (const property of object.properties) {
+    const name = property.name && (
+      ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)
+    ) ? property.name.text : null;
+    if (!name || !allowedNames.has(name)) {
+      throw toolchainError(
+        "zhike_frontend_definition_unknown_property",
+        `${relativePath}: Frontend Extension 包含不支持的字段`,
+      );
+    }
+  }
+}
+
+function parseServerFunction(sourceFile, relativePath, moduleId) {
+  if (hasSdkNamedImport(sourceFile, "@77-zhike/app-sdk/server", "defineServerFunction")) {
+    throw toolchainError(
+      "zhike_server_function_wrapper_deprecated",
+      `${relativePath}: defineServerFunction 已不再用于新 Build，请直接 export default async function`,
+    );
+  }
+  requireDefaultAsyncFunction(sourceFile, relativePath, {
+    errorCode: "zhike_server_function_export_invalid",
+    entryName: "Server Function",
+  });
+  if (!SERVER_MODULE_PATTERN.test(moduleId)) {
+    throw toolchainError(
+      "zhike_server_function_key_invalid",
+      `${relativePath}: Server Function module ID 不合法`,
+    );
+  }
+  return Object.freeze({ key: moduleId, relativePath });
+}
+
+function parseWebhookHandler(sourceFile, relativePath, fileKey) {
+  if (hasSdkNamedImport(sourceFile, "@77-zhike/app-sdk/server", "defineWebhookHandler")) {
+    throw toolchainError(
+      "zhike_webhook_handler_wrapper_deprecated",
+      `${relativePath}: defineWebhookHandler 已不再用于新 Build，请直接 default export async function`,
+    );
+  }
+  requireDefaultAsyncFunction(sourceFile, relativePath, {
+    errorCode: "zhike_webhook_handler_export_invalid",
+    entryName: "Webhook Handler",
+  });
+  return Object.freeze({
+    key: fileKey,
+    methods: Object.freeze(["POST"]),
+    relativePath,
+  });
+}
+
+function requireDefaultExportCall(sourceFile, relativePath, expectedCallee) {
+  const exports = sourceFile.statements.filter(
+    (statement) => ts.isExportAssignment(statement) && !statement.isExportEquals,
+  );
+  if (exports.length !== 1 || !ts.isCallExpression(exports[0].expression)) {
+    throw toolchainError(
+      "zhike_entry_default_export_invalid",
+      `${relativePath}: 必须有且只有一个直接 default export`,
+    );
+  }
+  const call = exports[0].expression;
+  if (!ts.isIdentifier(call.expression) || call.expression.text !== expectedCallee) {
+    throw toolchainError(
+      "zhike_entry_definition_invalid",
+      `${relativePath}: default export 必须直接调用 ${expectedCallee}`,
+    );
+  }
+  return call;
+}
+
+function requireSdkNamedImport(sourceFile, relativePath, specifier, importedName) {
+  const matches = sourceFile.statements.filter((statement) =>
+    hasNamedImport(statement, specifier, importedName),
+  );
+  if (matches.length !== 1) {
+    throw toolchainError(
+      "zhike_sdk_definition_import_invalid",
+      `${relativePath}: ${importedName} 必须从 ${specifier} 直接 named import且不得重命名`,
+    );
+  }
+}
+
+function hasSdkNamedImport(sourceFile, specifier, importedName) {
+  return sourceFile.statements.some((statement) =>
+    hasNamedImport(statement, specifier, importedName),
+  );
+}
+
+function hasNamedImport(statement, specifier, importedName) {
+    if (
+      !ts.isImportDeclaration(statement) ||
+      statement.moduleSpecifier.text !== specifier ||
+      !statement.importClause?.namedBindings ||
+      !ts.isNamedImports(statement.importClause.namedBindings)
+    ) {
+      return false;
+    }
+    return statement.importClause.namedBindings.elements.some(
+      (element) =>
+        (element.propertyName?.text || element.name.text) === importedName &&
+        element.name.text === importedName,
+    );
+}
+
+function validateImports(sourceFile, relativePath) {
+  const allowsStandardFetch =
+    relativePath.startsWith("server/") ||
+    /^app\/events\/.+\.event\.ts$/.test(relativePath) ||
+    /^app\/webhooks\/.+\.webhook\.ts$/.test(relativePath);
+  const visit = (node) => {
+    if (
+      ts.isCallExpression(node) &&
+      node.expression.kind === ts.SyntaxKind.ImportKeyword
+    ) {
+      throw toolchainError(
+        "zhike_dynamic_import_forbidden",
+        `${relativePath}: 一期禁止动态 import`,
+      );
+    }
+    if (
+      !allowsStandardFetch &&
+      ts.isCallExpression(node) &&
+      ((ts.isIdentifier(node.expression) && node.expression.text === "fetch") ||
+        (ts.isPropertyAccessExpression(node.expression) &&
+          node.expression.name.text === "fetch" &&
+          ts.isIdentifier(node.expression.expression) &&
+          ["globalThis", "window", "self"].includes(
+            node.expression.expression.text,
+          )))
+    ) {
+      throw toolchainError(
+        "zhike_network_egress_forbidden",
+        `${relativePath}: 前端网络能力必须由受控 Host capability 提供`,
+      );
+    }
+    if (
+      (ts.isNewExpression(node) &&
+        ts.isIdentifier(node.expression) &&
+        ["EventSource", "WebSocket", "XMLHttpRequest"].includes(
+          node.expression.text,
+        )) ||
+      (ts.isCallExpression(node) &&
+        ts.isPropertyAccessExpression(node.expression) &&
+        node.expression.name.text === "sendBeacon" &&
+        ts.isIdentifier(node.expression.expression) &&
+        node.expression.expression.text === "navigator")
+    ) {
+      throw toolchainError(
+        "zhike_network_egress_forbidden",
+        `${relativePath}: 一期禁止未托管的浏览器网络能力`,
+      );
+    }
+    if (
+      (ts.isIdentifier(node) &&
+        ["ZHIKE_CLIENT_SDK", "ZHIKE_SERVER_SDK"].includes(node.text)) ||
+      (ts.isPropertyAccessExpression(node) &&
+        ["ZHIKE_CLIENT_SDK", "ZHIKE_SERVER_SDK"].includes(node.name.text))
+    ) {
+      throw toolchainError(
+        "zhike_host_global_forbidden",
+        `${relativePath}: App 源码不得直接读取 Host SDK global`,
+      );
+    }
+    if (ts.isImportDeclaration(node)) {
+      const specifier = node.moduleSpecifier.text;
+      if (specifier === "@77-zhike/app-sdk/server" && !allowsStandardFetch) {
+        throw toolchainError(
+          "zhike_server_sdk_client_forbidden",
+          `${relativePath}: 前端代码不得导入服务端 SDK`,
+        );
+      }
+      if (specifier.startsWith("node:") || NODE_BUILTINS.has(specifier)) {
+        throw toolchainError(
+          "zhike_node_builtin_forbidden",
+          `${relativePath}: 一期禁止 Node builtin ${specifier}`,
+        );
+      }
+      if (!specifier.startsWith(".") && !SDK_IMPORTS.has(specifier)) {
+        throw toolchainError(
+          "zhike_external_dependency_forbidden",
+          `${relativePath}: 一期禁止第三方或内部依赖 ${specifier}`,
+        );
+      }
+      if (specifier.startsWith(".")) {
+        const resolvedSourcePath = posix.normalize(
+          posix.join(posix.dirname(relativePath), specifier),
+        );
+        if (resolvedSourcePath === ".." || resolvedSourcePath.startsWith("../")) {
+          throw toolchainError(
+            "zhike_source_import_outside_root",
+            `${relativePath}: relative import 不得越过 src 根目录`,
+          );
+        }
+      }
+      if (specifier.includes(".server.tsx") || specifier.endsWith(".server.tsx")) {
+        throw toolchainError(
+          "zhike_server_function_extension_invalid",
+          `${relativePath}: Server Function 不支持 .server.tsx`,
+        );
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+}
+
+function rejectUnsupportedPaths(files) {
+  for (const file of files) {
+    const path = file.relativePath;
+    if (
+      path.startsWith("app/events/") &&
+      path.endsWith(".ts") &&
+      !/^app\/events\/(app-installed|app-uninstalled|connection-added|connection-removed)\.event\.ts$/.test(path)
+    ) {
+      throw toolchainError(
+        "zhike_lifecycle_event_location_invalid",
+        `${path}: 生命周期事件文件名不受支持`,
+      );
+    }
+    if (path === "app.ts" || path === "app/index.ts") {
+      throw toolchainError(
+        "zhike_legacy_entry_forbidden",
+        `${path}: 一期不支持 Legacy app entry`,
+      );
+    }
+    if (/(^|\/)(workflows?|connections?)(\/|\.|$)/i.test(path)) {
+      throw toolchainError(
+        "zhike_capability_unsupported",
+        `${path}: 一期不支持 Workflow/Event/Connection/Settings`,
+      );
+    }
+    if (path.endsWith(".server.tsx")) {
+      throw toolchainError(
+        "zhike_server_function_extension_invalid",
+        `${path}: Server Function 只允许 .server.ts`,
+      );
+    }
+    if (
+      path.endsWith(".server.ts") &&
+      !/^server\/functions\/[a-z0-9][a-z0-9/-]*\.server\.ts$/.test(path)
+    ) {
+      throw toolchainError(
+        "zhike_server_function_location_invalid",
+        `${path}: Server Function 必须位于 src/server/functions`,
+      );
+    }
+    if (
+      path.startsWith("app/extensions/") &&
+      path.endsWith(".tsx") &&
+      !/^app\/extensions\/[a-z][a-z0-9-]{0,63}\/extension\.tsx$/.test(path)
+    ) {
+      throw toolchainError(
+        "zhike_frontend_extension_location_invalid",
+        `${path}: Frontend Extension 必须使用约定目录`,
+      );
+    }
+    if (
+      path.startsWith("app/webhooks/") &&
+      path.endsWith(".ts") &&
+      !/^app\/webhooks\/[a-z][a-z0-9-]{0,63}\.webhook\.ts$/.test(path)
+    ) {
+      throw toolchainError(
+        "zhike_webhook_location_invalid",
+        `${path}: Webhook Handler 必须使用 <key>.webhook.ts`,
+      );
+    }
+  }
+}
+
+function requireObjectLiteral(node, relativePath) {
+  if (!node || !ts.isObjectLiteralExpression(node)) {
+    throw toolchainError(
+      "zhike_entry_definition_invalid",
+      `${relativePath}: definition 必须是可静态解析的对象字面量`,
+    );
+  }
+  return node;
+}
+
+function requireStringProperty(object, name, relativePath) {
+  const property = findProperty(object, name);
+  if (!property || !ts.isPropertyAssignment(property) || !ts.isStringLiteral(property.initializer)) {
+    throw toolchainError(
+      "zhike_entry_definition_invalid",
+      `${relativePath}: ${name} 必须是字符串字面量`,
+    );
+  }
+  return property.initializer.text;
+}
+
+function requireStringArrayProperty(object, name, relativePath) {
+  const property = findProperty(object, name);
+  if (!property || !ts.isPropertyAssignment(property) || !ts.isArrayLiteralExpression(property.initializer)) {
+    throw toolchainError(
+      "zhike_entry_definition_invalid",
+      `${relativePath}: ${name} 必须是字符串字面量数组`,
+    );
+  }
+  return property.initializer.elements.map((item) => {
+    if (!ts.isStringLiteral(item)) {
+      throw toolchainError(
+        "zhike_entry_definition_invalid",
+        `${relativePath}: ${name} 必须是字符串字面量数组`,
+      );
+    }
+    return item.text.toUpperCase();
+  });
+}
+
+function requireFunctionProperty(object, name, relativePath, { requireAsync = false } = {}) {
+  const property = findProperty(object, name);
+  const functionNode =
+    property && ts.isMethodDeclaration(property)
+      ? property
+      : property && ts.isPropertyAssignment(property) && isFunctionLike(property.initializer)
+        ? property.initializer
+        : null;
+  if (
+    !functionNode ||
+    (requireAsync &&
+      !functionNode.modifiers?.some(
+        (modifier) => modifier.kind === ts.SyntaxKind.AsyncKeyword,
+      ))
+  ) {
+    throw toolchainError(
+      "zhike_entry_definition_invalid",
+      `${relativePath}: ${name} 必须是${requireAsync ? " async" : ""}函数`,
+    );
+  }
+  return functionNode;
+}
+
+function findProperty(object, name) {
+  return object.properties.find((property) => {
+    const propertyName = property.name;
+    return (
+      (ts.isIdentifier(propertyName) || ts.isStringLiteral(propertyName)) &&
+      propertyName.text === name
+    );
+  });
+}
+
+function isFunctionLike(node) {
+  return ts.isArrowFunction(node) || ts.isFunctionExpression(node);
+}
+
+function registerUniqueKey(keys, key, relativePath) {
+  const existing = keys.get(key);
+  if (existing) {
+    throw toolchainError(
+      "zhike_definition_key_duplicate",
+      `definition key ${key} 同时出现在 ${existing} 和 ${relativePath}`,
+    );
+  }
+  keys.set(key, relativePath);
+}
+
+function assertSyntacticallyValid(sourceFile) {
+  if (sourceFile.parseDiagnostics.length === 0) return;
+  const diagnostic = sourceFile.parseDiagnostics[0];
+  throw toolchainError(
+    "zhike_source_syntax_invalid",
+    `${sourceFile.fileName}: ${ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n")}`,
+  );
+}
+
+async function listFiles(root) {
+  let entries;
+  try {
+    entries = await readdir(root, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    throw error;
+  }
+  const result = [];
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    const path = resolve(root, entry.name);
+    if (entry.isDirectory()) {
+      result.push(...(await listFiles(path)));
+    } else if (entry.isFile() && /\.(ts|tsx)$/.test(entry.name)) {
+      result.push(path);
+    }
+  }
+  return result;
+}
+
+function sortByKey(items) {
+  return items.sort((left, right) => left.key.localeCompare(right.key));
+}
+
+function toolchainError(code, message) {
+  return new ZhikeCliError(code, message);
+}